https://wiki.archlinux.org/api.php?action=feedcontributions&user=Hexhu&feedformat=atomArchWiki - User contributions [en]2024-03-28T21:19:42ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Telegram&diff=748308Telegram2022-09-25T10:59:21Z<p>Hexhu: /* Fcitx support for Qt 6 Telegram */ wording</p>
<hr />
<div>[[Category:Instant messaging]]<br />
[[fa:Telegram]]<br />
[[ja:Telegram]]<br />
[[pt:Telegram]]<br />
[[ru:Telegram]]<br />
[[zh-hans:Telegram]]<br />
[[wikipedia:Telegram (software)|Telegram]] is a cloud-based cross-platform instant messaging service with optional end-to-end encryption. Account creation requires a phone number.<br />
<br />
The official clients are open-source but the code for recent versions is not always immediately published. The server-side code is proprietary.<br />
<br />
== Installation ==<br />
<br />
You can use one of following methods in order to use Telegram:<br />
<br />
=== Chat client plugins ===<br />
<br />
* By using the {{AUR|telegram-tdlib-purple-git}} package, connection to Telegram through (graphical or command-line) messenger software based on {{Pkg|libpurple}} such as [[Pidgin]] is provided.<br />
* Messaging apps that are using [[wikipedia:Telepathy_(software)|Telepathy]] can make use of {{Pkg|telepathy-haze}} package, which provides possibility of using {{Pkg|libpurple}} and thus {{AUR|telegram-tdlib-purple-git}} to connect Telegram.<br />
* In the [[KDE]] desktop environment using {{Pkg|telepathy-morse}} provides capability of connecting the default messenger to Telegram.<br />
<br />
=== Graphical clients ===<br />
<br />
The [https://desktop.telegram.org/ official application] built by Arch Linux: {{Pkg|telegram-desktop}}.<br />
<br />
Third-party clients:<br />
<br />
* {{AUR|kotatogram-desktop-bin}}, {{AUR|kotatogram-desktop}}, {{AUR|kotatogram-desktop-dynamic-bin}}<br />
<br />
=== Command-line clients ===<br />
<br />
* {{AUR|telegram-cli-git}} provides command-line interface to connect and use Telegram. For more information about the program, visit the program page on [https://github.com/kenorb-contrib/tg Github].<br />
* {{AUR|nctelegram-git}} is a command-line interface for Telegram based on [[wikipedia:Ncurses|Ncurses]] and needs {{AUR|telegram-cli-git}} to run. For more information about the program, visit the program page on [https://github.com/Nanoseb/ncTelegram Github].<br />
* {{AUR|telegram-tg}} Telegram terminal client. For more information about the program, visit the program page on [https://github.com/paul-nameless/tg Github].<br />
* {{AUR|python-telegram-send}}, not a full client but a command-line tool to directly send messages or files via Telegram.<br />
* [https://github.com/zevlg/telega.el telega.el] - GNU Emacs Telegram client.<br />
* [https://github.com/vtr0n/TelegramTUI TelegramTUI] - terminal Telegam client with a pseudo-graphic GUI<br />
<br />
=== Web-based clients ===<br />
<br />
* The official [https://web.telegram.org/k/ Telegram WebK].<br />
* The official [https://web.telegram.org/z/ Telegram WebZ].<br />
* {{AUR|franz}} is an [https://github.com/meetfranz/franz open-source] web-based application that can be used for web-based interface of various instant messaging software such as [[wikipedia:Telegram (software)|Telegram]], [[wikipedia:WhatsApp|WhatsApp]], [[wikipedia:Facebook|Facebook]], and more.<br />
* {{AUR|rambox-bin}} is an alternative to Franz, also open source. It offers all features of its counterpart.<br />
* Use [https://telegram.org/dl/webogram/chromeapp Telegram Chrome app] for [[Chromium]], to connect to Telegram in your browser via web interface.<br />
<br />
== Tips and tricks ==<br />
<br />
=== GTK dialogs in Telegram Desktop ===<br />
<br />
If you want to use [[GTK]] file dialogs instead of Qt ones, set {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] to {{ic|gtk3}}.<br />
<br />
=== KDE dialogs in Telegram Desktop ===<br />
<br />
If you want to use [[KDE]] file dialogs instead of Qt ones, set {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] to {{ic|flatpak}}.<br />
<br />
=== SVG icon theme in Telegram Desktop ===<br />
<br />
If you want to use an icon theme based on svg image (e.g. {{Pkg|papirus-icon-theme}}) install {{Pkg|qt5-svg}}. See [[Qt#Icon theme is not applied]] for details.<br />
<br />
=== Wayland support ===<br />
<br />
GNOME Wayland may not set cursor settings for Telegram[https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/5894][https://github.com/telegramdesktop/tdesktop/issues/25075#issuecomment-1250020362]. This may result in cursors being of the wrong theme, size and not being able to resize the window.<br />
<br />
Set {{ic|XCURSOR_THEME}} and {{ic|XCURSOR_SIZE}} environment variables manually (e.g., {{ic|1=XCURSOR_THEME=Adwaita}} and {{ic|1=XCURSOR_SIZE=24}})<br />
<br />
See [[Wayland#Qt]] for further instructions.<br />
<br />
=== xdg-open in Telegram Desktop ===<br />
<br />
If you want to use xdg-open on t.me links and receive an error not finding a handler for tg:<br />
<br />
{{bc|1=<br />
xdg-mime default telegramdesktop.desktop application/x-xdg-protocol-tg<br />
xdg-mime default telegramdesktop.desktop x-scheme-handler/tg<br />
}}<br />
<br />
=== Failed to set real-time priority for thread: Operation not permitted ===<br />
<br />
If you get the following error<br />
<br />
{{hc|$ telegram-desktop|<br />
[ALSOFT] (EE) Failed to set real-time priority for thread: Operation not permitted (1)<br />
}}<br />
<br />
Install {{Pkg|realtime-privileges}}, [[Users and groups#Group management|add]] yourself to the {{ic|realtime}} group and reboot. See [[Realtime process management#Configuring PAM]] for details.<br />
<br />
=== HiDPI scaling ===<br />
<br />
If you have Qt scaling enabled on your system, and the scaling factor is not an integer, you may encounter problems like [https://github.com/telegramdesktop/tdesktop/issues/23953 pixelated images and icons]. you may need to disable [https://doc.qt.io/qt-5/highdpi.html#high-dpi-support-in-qt high-DPI scaling] for Telegram separately.<br />
<br />
Copy {{ic|/usr/share/applications/telegramdesktop.desktop}} to your [[Desktop entries#Application entry|user-specific applications]] and [[textedit|edit]] it as follows: <br />
<br />
{{hc|1=$HOME/.local/share/applications/telegramdesktop-no-scaling.desktop|2=<br />
...<br />
Exec=env -u QT_SCREEN_SCALE_FACTORS telegram-desktop -- %u<br />
...<br />
}}<br />
<br />
You may need to [[Desktop entries#Update database of desktop entries|update the database]] of desktop entries.<br />
<br />
=== Audio backend ===<br />
<br />
As Telegram makes use of [https://github.com/kcat/openal-soft OpenAL], it is possible to configure the audio settings by editing its [https://github.com/kcat/openal-soft/blob/master/alsoftrc.sample config files], i.e. {{ic|~/.config/alsoft.conf}}, or the [[environment variables]] listed [https://github.com/kcat/openal-soft/blob/master/docs/env-vars.txt here].<br />
<br />
In case sound is not working due to an invalid audio backend being used, it can be overwritten by setting the [[environment variable]] {{ic|ALSOFT_DRIVERS}} or the {{ic|drivers}} property in the {{ic|[general]}} section of the OpenAL config. The drivers value {{ic|"pulse,"}} for example would try pulseaudio first and then fallback to the default driver list.<br />
<br />
=== Choose correct web camera ===<br />
<br />
Telegram version 3.7.1 does not allow to select the web camera to use in video conference. If you want to force telegram to use a different camera, as a workaround you can disable the unwanted camera device as described in [https://askubuntu.com/a/166819].<br />
<br />
=== Fcitx support for Qt 6 Telegram ===<br />
<br />
Telegram-desktop is built against Qt 6 since 3.4.2-2. Users upgrading from an older version might notice [[Fcitx]] stop working for this application. To make it work again, install {{Pkg|fcitx-qt6}} or the {{Pkg|fcitx-im}} group. If using [[Fcitx5]], install {{Pkg|fcitx5-im}}.<br />
<br />
== See also ==<br />
<br />
* [https://t.me/archlinuxgroup Arch Linux] - Unofficial group for discussing everything about Arch Linux.<br />
* [https://t.me/archewikibot ArchWikiBot] - Inline bot for searching through ArchWiki pages.<br />
* [https://t.me/planetarch Planet Arch Linux & News] - Channel with recent Planet Arch updates and Latest News in one place.<br />
* [https://t.me/archlinux_updates Arch Linux: Recent package updates] - Channel with recent package updates in Arch Linux repositories.<br />
* [https://t.me/archlinuxnews Arch Linux News] - Channel with news from Arch web site ''(not updated since 2018)''.<br />
* [https://t.me/archplanet Planet Arch] - Channel with posts from Planet Arch web site ''(not updated since 2018)''.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Telegram&diff=748307Telegram2022-09-25T10:50:43Z<p>Hexhu: /* Fcitx support for Qt 6 Telegram */ better wording</p>
<hr />
<div>[[Category:Instant messaging]]<br />
[[fa:Telegram]]<br />
[[ja:Telegram]]<br />
[[pt:Telegram]]<br />
[[ru:Telegram]]<br />
[[zh-hans:Telegram]]<br />
[[wikipedia:Telegram (software)|Telegram]] is a cloud-based cross-platform instant messaging service with optional end-to-end encryption. Account creation requires a phone number.<br />
<br />
The official clients are open-source but the code for recent versions is not always immediately published. The server-side code is proprietary.<br />
<br />
== Installation ==<br />
<br />
You can use one of following methods in order to use Telegram:<br />
<br />
=== Chat client plugins ===<br />
<br />
* By using the {{AUR|telegram-tdlib-purple-git}} package, connection to Telegram through (graphical or command-line) messenger software based on {{Pkg|libpurple}} such as [[Pidgin]] is provided.<br />
* Messaging apps that are using [[wikipedia:Telepathy_(software)|Telepathy]] can make use of {{Pkg|telepathy-haze}} package, which provides possibility of using {{Pkg|libpurple}} and thus {{AUR|telegram-tdlib-purple-git}} to connect Telegram.<br />
* In the [[KDE]] desktop environment using {{Pkg|telepathy-morse}} provides capability of connecting the default messenger to Telegram.<br />
<br />
=== Graphical clients ===<br />
<br />
The [https://desktop.telegram.org/ official application] built by Arch Linux: {{Pkg|telegram-desktop}}.<br />
<br />
Third-party clients:<br />
<br />
* {{AUR|kotatogram-desktop-bin}}, {{AUR|kotatogram-desktop}}, {{AUR|kotatogram-desktop-dynamic-bin}}<br />
<br />
=== Command-line clients ===<br />
<br />
* {{AUR|telegram-cli-git}} provides command-line interface to connect and use Telegram. For more information about the program, visit the program page on [https://github.com/kenorb-contrib/tg Github].<br />
* {{AUR|nctelegram-git}} is a command-line interface for Telegram based on [[wikipedia:Ncurses|Ncurses]] and needs {{AUR|telegram-cli-git}} to run. For more information about the program, visit the program page on [https://github.com/Nanoseb/ncTelegram Github].<br />
* {{AUR|telegram-tg}} Telegram terminal client. For more information about the program, visit the program page on [https://github.com/paul-nameless/tg Github].<br />
* {{AUR|python-telegram-send}}, not a full client but a command-line tool to directly send messages or files via Telegram.<br />
* [https://github.com/zevlg/telega.el telega.el] - GNU Emacs Telegram client.<br />
* [https://github.com/vtr0n/TelegramTUI TelegramTUI] - terminal Telegam client with a pseudo-graphic GUI<br />
<br />
=== Web-based clients ===<br />
<br />
* The official [https://web.telegram.org/k/ Telegram WebK].<br />
* The official [https://web.telegram.org/z/ Telegram WebZ].<br />
* {{AUR|franz}} is an [https://github.com/meetfranz/franz open-source] web-based application that can be used for web-based interface of various instant messaging software such as [[wikipedia:Telegram (software)|Telegram]], [[wikipedia:WhatsApp|WhatsApp]], [[wikipedia:Facebook|Facebook]], and more.<br />
* {{AUR|rambox-bin}} is an alternative to Franz, also open source. It offers all features of its counterpart.<br />
* Use [https://telegram.org/dl/webogram/chromeapp Telegram Chrome app] for [[Chromium]], to connect to Telegram in your browser via web interface.<br />
<br />
== Tips and tricks ==<br />
<br />
=== GTK dialogs in Telegram Desktop ===<br />
<br />
If you want to use [[GTK]] file dialogs instead of Qt ones, set {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] to {{ic|gtk3}}.<br />
<br />
=== KDE dialogs in Telegram Desktop ===<br />
<br />
If you want to use [[KDE]] file dialogs instead of Qt ones, set {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] to {{ic|flatpak}}.<br />
<br />
=== SVG icon theme in Telegram Desktop ===<br />
<br />
If you want to use an icon theme based on svg image (e.g. {{Pkg|papirus-icon-theme}}) install {{Pkg|qt5-svg}}. See [[Qt#Icon theme is not applied]] for details.<br />
<br />
=== Wayland support ===<br />
<br />
GNOME Wayland may not set cursor settings for Telegram[https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/5894][https://github.com/telegramdesktop/tdesktop/issues/25075#issuecomment-1250020362]. This may result in cursors being of the wrong theme, size and not being able to resize the window.<br />
<br />
Set {{ic|XCURSOR_THEME}} and {{ic|XCURSOR_SIZE}} environment variables manually (e.g., {{ic|1=XCURSOR_THEME=Adwaita}} and {{ic|1=XCURSOR_SIZE=24}})<br />
<br />
See [[Wayland#Qt]] for further instructions.<br />
<br />
=== xdg-open in Telegram Desktop ===<br />
<br />
If you want to use xdg-open on t.me links and receive an error not finding a handler for tg:<br />
<br />
{{bc|1=<br />
xdg-mime default telegramdesktop.desktop application/x-xdg-protocol-tg<br />
xdg-mime default telegramdesktop.desktop x-scheme-handler/tg<br />
}}<br />
<br />
=== Failed to set real-time priority for thread: Operation not permitted ===<br />
<br />
If you get the following error<br />
<br />
{{hc|$ telegram-desktop|<br />
[ALSOFT] (EE) Failed to set real-time priority for thread: Operation not permitted (1)<br />
}}<br />
<br />
Install {{Pkg|realtime-privileges}}, [[Users and groups#Group management|add]] yourself to the {{ic|realtime}} group and reboot. See [[Realtime process management#Configuring PAM]] for details.<br />
<br />
=== HiDPI scaling ===<br />
<br />
If you have Qt scaling enabled on your system, and the scaling factor is not an integer, you may encounter problems like [https://github.com/telegramdesktop/tdesktop/issues/23953 pixelated images and icons]. you may need to disable [https://doc.qt.io/qt-5/highdpi.html#high-dpi-support-in-qt high-DPI scaling] for Telegram separately.<br />
<br />
Copy {{ic|/usr/share/applications/telegramdesktop.desktop}} to your [[Desktop entries#Application entry|user-specific applications]] and [[textedit|edit]] it as follows: <br />
<br />
{{hc|1=$HOME/.local/share/applications/telegramdesktop-no-scaling.desktop|2=<br />
...<br />
Exec=env -u QT_SCREEN_SCALE_FACTORS telegram-desktop -- %u<br />
...<br />
}}<br />
<br />
You may need to [[Desktop entries#Update database of desktop entries|update the database]] of desktop entries.<br />
<br />
=== Audio backend ===<br />
<br />
As Telegram makes use of [https://github.com/kcat/openal-soft OpenAL], it is possible to configure the audio settings by editing its [https://github.com/kcat/openal-soft/blob/master/alsoftrc.sample config files], i.e. {{ic|~/.config/alsoft.conf}}, or the [[environment variables]] listed [https://github.com/kcat/openal-soft/blob/master/docs/env-vars.txt here].<br />
<br />
In case sound is not working due to an invalid audio backend being used, it can be overwritten by setting the [[environment variable]] {{ic|ALSOFT_DRIVERS}} or the {{ic|drivers}} property in the {{ic|[general]}} section of the OpenAL config. The drivers value {{ic|"pulse,"}} for example would try pulseaudio first and then fallback to the default driver list.<br />
<br />
=== Choose correct web camera ===<br />
<br />
Telegram version 3.7.1 does not allow to select the web camera to use in video conference. If you want to force telegram to use a different camera, as a workaround you can disable the unwanted camera device as described in [https://askubuntu.com/a/166819].<br />
<br />
=== Fcitx support for Qt 6 Telegram ===<br />
<br />
Since 3.4.2-2, telegram-desktop is built against Qt 6, and {{Pkg|fcitx-qt6}} or the {{Pkg|fcitx-im}} group must be installed for [[Fcitx]] to work. If using [[Fcitx5]], install {{Pkg|fcitx5-im}}.<br />
<br />
== See also ==<br />
<br />
* [https://t.me/archlinuxgroup Arch Linux] - Unofficial group for discussing everything about Arch Linux.<br />
* [https://t.me/archewikibot ArchWikiBot] - Inline bot for searching through ArchWiki pages.<br />
* [https://t.me/planetarch Planet Arch Linux & News] - Channel with recent Planet Arch updates and Latest News in one place.<br />
* [https://t.me/archlinux_updates Arch Linux: Recent package updates] - Channel with recent package updates in Arch Linux repositories.<br />
* [https://t.me/archlinuxnews Arch Linux News] - Channel with news from Arch web site ''(not updated since 2018)''.<br />
* [https://t.me/archplanet Planet Arch] - Channel with posts from Planet Arch web site ''(not updated since 2018)''.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Fcitx&diff=748306Fcitx2022-09-25T10:49:30Z<p>Hexhu: /* Input method module */ mention fcitx-qt6 module</p>
<hr />
<div>[[Category:Input methods]]<br />
[[de:Fcitx]]<br />
[[ja:Fcitx]]<br />
[[ko:Fcitx]]<br />
[[zh-hans:Fcitx]]<br />
{{Related articles start}}<br />
{{Related|Fcitx5}}<br />
{{Related|IBus}}<br />
{{Related|SCIM}}<br />
{{Related|uim}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Fcitx|Fcitx]] is a lightweight [[input method]] framework aimed at providing environment independent language support for Linux. It supports a lot of different languages and also provides many useful non-CJK features.<br />
<br />
{{Warning|Fcitx is now in maintenance mode. It is recommended to use [[Fcitx5]] instead.}} <br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|fcitx}} package.<br />
<br />
=== Input method engines ===<br />
<br />
Fcitx provides built-in input methods for Chinese [[wikipedia:Pinyin|Pinyin]] and table-based input (for example [[wikipedia:Wubi method|Wubi]]).<br />
<br />
Depending on the language you wish to type, other input method engines are available:<br />
<br />
==== Chinese ====<br />
<br />
* {{AUR|fcitx-baidupinyin}}, fcitx wrapper for Baidu Pinyin IM engine.<br />
* {{Pkg|fcitx-chewing}} is a popular Zhuyin input engine for Traditional Chinese based on {{Pkg|libchewing}}.<br />
* {{Pkg|fcitx-cloudpinyin}} uses internet sources to provide input candidates. The selected cloud result will be added to local dictionary. It support all fcitx pinyin input method except {{Pkg|fcitx-rime}}.<br />
* {{Pkg|fcitx-googlepinyin}}, Googlepinyin wrapper for fcitx.<br />
* {{Pkg|fcitx-libpinyin}}, based on {{Pkg|libpinyin}}. It has a better algorithm than {{Pkg|fcitx-sunpinyin}}.<br />
* {{Pkg|fcitx-rime}}, based on schemas from the [[Rime IME]] project.<br />
* {{AUR|fcitx-sogoupinyin}}, [https://pinyin.sogou.com/linux/ Sogou input method] supporting Jianpin, fuzzy sound, cloud input, English input, and mixed skin.<br />
* {{Pkg|fcitx-sunpinyin}}, based on {{Pkg|sunpinyin}}. It strikes a good balance between speed and accuracy.<br />
<br />
==== Japanese ====<br />
<br />
* {{Pkg|fcitx-anthy}}, a popular Japanese input engine. However, it is not actively developed anymore.<br />
* {{Pkg|fcitx-mozc}}, based on [[Mozc]], the Open Source Edition of Google Japanese Input.<br />
* {{Pkg|fcitx-kkc}}, a Japanese Kana Kanji input engine, based on {{Pkg|libkkc}}.<br />
* {{Pkg|fcitx-skk}}, a Japanese Kana Kanji input engine, based on {{Pkg|libskk}}.<br />
<br />
==== Other languages ====<br />
<br />
* {{Pkg|fcitx-hangul}}, for typing Korean hangul, based on {{Pkg|libhangul}}.<br />
* {{Pkg|fcitx-m17n}}, for other languages provided by [https://www.nongnu.org/m17n/ M17n].<br />
* {{Pkg|fcitx-sayura}}, for typing Sinhalese.<br />
* {{Pkg|fcitx-unikey}}, for typing Vietnamese characters.<br />
<br />
=== Input method module ===<br />
<br />
To obtain a better experience in Qt programs, install {{AUR|fcitx-qt4}}, {{Pkg|fcitx-qt5}} or {{Pkg|fcitx-qt6}} input method modules as your need, or the {{Grp|fcitx-im}} group to install {{Pkg|fcitx}}, {{Pkg|fcitx-qt5}} and {{Pkg|fcitx-qt6}}. Without these modules, the input method may work on most applications but you may experience input method hang up, preview window screen location error or no preview error. <br />
<br />
Applications below do not use GTK/Qt input module: <br />
<br />
* Applications use Tk, motif or xlib<br />
* Emacs, Opera, OpenOffice, LibreOffice, Skype, Wine, Java, Xterm, urxvt, WPS<br />
<br />
=== Others ===<br />
<br />
* {{Pkg|fcitx-ui-light}}, light UI for fcitx.<br />
* {{Pkg|fcitx-table-extra}} adds [[wikipedia:Cangjie_input_method|Cangjie]], [[wikipedia:Zhengma_method|Zhengma]], [[wikipedia:Boshiamy_method|Boshiamy]] support.<br />
* {{Pkg|fcitx-table-other}}, tables for Latex, Emoji and others. <br />
* [[#GUI configuration tools]]<br />
<br />
Others packages (including git version) are also available in the [[AUR]]. All components of fcitx will requires fcitx to restart after install.<br />
<br />
== Usage ==<br />
<br />
{{Note|You need to have [[Fonts#Chinese, Japanese, Korean, Vietnamese|Chinese, Japanese, Korean or Vietnamese font]] installed to be able to enter the corresponding characters.}}<br />
<br />
=== Desktop Environment Autostart ===<br />
<br />
If you are using any XDG compatible desktop environment such as [[KDE]], [[GNOME]], [[Xfce]], [[LXDE]], after you re-login, the autostart should work out of the box. If not, run the ''fcitx'' executable. To see if fcitx is working correctly, open an application and press {{ic|Ctrl+Space}} (the default shortcut for switching the input method) to invoke fcitx and input some words.<br />
<br />
If fcitx failed to start with your desktop automatically or if you want to change the parameters to start fcitx, configure [[Autostarting#On_Xorg_startup|autostart]] or edit the {{ic|fcitx-autostart.desktop}} file in your {{ic|~/.config/autostart/}} directory (copy it from {{ic|/etc/xdg/autostart/}} if it does not exist yet).<br />
<br />
When other input methods with xim support are also running, fcitx may fail to start due to an xim error. Ensure that no other input methods are running before you start fcitx.<br />
<br />
Also please set the following environment variables to prefer IM modules for GTK/Qt applications.<br />
<br />
For [[i3]] and [[Sway]] users, add {{ic|exec --no-startup-id fcitx -d<br />
}} in your configuration file. [[fcitx5]] users should add {{ic|exec --no-startup-id fcitx5 -d}} instead.<br />
<br />
=== Set environment variables for IM modules ===<br />
<br />
[[Environment variables#Graphical environment|Set]] the following environment variables to register the input method modules.<br />
<br />
{{bc|1=<br />
GTK_IM_MODULE=fcitx<br />
QT_IM_MODULE=fcitx<br />
XMODIFIERS=@im=fcitx<br />
}}<br />
<br />
{{Note|If you are using the deprecated {{ic|~/.pam_environment}} file, the {{ic|@}} must be escaped as {{ic|\@}}.}}<br />
<br />
Without these variables, applications may fallback to XIM protocol, except for Qt5 applications which do not have XIM support and require an IM module in place.<br />
<br />
If ''fcitx'' process does not start automatically, you might need to add {{ic|fcitx &}} in your {{ic|~/.xinitrc}}.<br />
If {{ic|fcitx &}} does not start, type {{ic|sleep 2}} after it<br />
<br />
{{Note|<br />
* Avoid {{ic|.bashrc}} for this, see [[GregsWiki:DotFiles]].<br />
* If all Qt applications have problem with fcitx, run ''qtconfig'' (''qtconfig-qt4''), and go to the third tab, make sure ''fcitx'' is in the ''Default Input Method'' combo-box.<br />
}}<br />
<br />
=== XIM ===<br />
<br />
Optionally, you can use the [[Wikipedia:X Input Method|X Input Method]] (XIM) in your GTK and/or Qt programs without installing the above modules in which case you need to change the corresponding lines above as following:<br />
<br />
GTK_IM_MODULE DEFAULT=xim<br />
QT_IM_MODULE DEFAULT=xim<br />
<br />
If you change it in {{ic|~/.xprofile}} or {{ic|~/.xinitrc}}, add {{ic|export}}.<br />
<br />
{{Warning| Using XIM can sometimes cause problems including not being able to input, no cursor following, word selection window issue, application freeze on input method restart. For these XIM related problems, Fcitx cannot provide any fix or support. This is the same with any other input method framework, so please use the GTK and Qt input method modules instead of xim whenever possible}}<br />
<br />
{{Note|<br />
* Gtk2 uses {{ic|/usr/lib/gtk-2.0/2.10.0/immodules.cache}} as immodule cache file since 2.24.20. If you have set {{ic|GTM_IM_MODULE_FILE}} environment variable or do not use install script of official packages to update the cache, please change/clear the environment variable and use {{ic|/usr/bin/gtk-query-immodules-2.0 --update-cache}} to update immodule cache.<br />
* Qt5 applications no longer support XIM protocol as Qt4 did, and rely on IM modules entirely for communicating with fcitx.}}<br />
<br />
== Configuration ==<br />
<br />
=== GUI configuration tools ===<br />
<br />
fcitx provides a [[KDE]] configuration module ({{Pkg|kcm-fcitx}}) and a GTK3 configuration tool ({{Pkg|fcitx-configtool}}).<br />
<br />
Run ''fcitx-config-gtk3'' after {{Pkg|fcitx-configtool}} is installed. Unset ''Only Show Current Language'' if you want to enable an input method for a different language.<br />
<br />
Stop fcitx manually before changing configuration, or the change may be lost. <br />
<br />
In order to enable spell checking, press {{ic|Ctrl+Alt+h}} when fcitx is on an input method provided by fcitx-keyboard.<br />
<br />
=== Input methods configuration ===<br />
<br />
You can add/remove input methods in the GUI tools. Note that the search is case sensitive.<br />
<br />
The first set input method is the inactive state, while all the rest will be active states. You generally want the inactive state to be one of the ''Keyboard'' options (e.g. "Keyboard - English (US)"). These options just input based on the keyboard layout in the name.<br />
<br />
Under ''Global Config'', the ''Trigger Input Method'' shortcut will only switch between the inactive and last used active state. The ''Scroll between Input Methods'' will by default only scroll between different active states, but can also be set to include the inactive state in the advanced settings. Furthermore, the ''Scroll between Input Methods'' shortcut has to be pressed in order, e.g. {{ic|ALT_SHIFT}} will only activate if {{ic|alt}} is pressed before {{ic|shift}}.<br />
<br />
Configuration settings for IME's can be found by by setting the keyboard to the desired IME and right-clicking the tray icon.<br />
<br />
=== Change default UI ===<br />
<br />
Fcitx support kimpanel protocol to provide better desktop integration.<br />
<br />
* Gnome-Shell: You can install kimpanel from extensions.gnome.org or {{AUR|gnome-shell-extension-kimpanel-git}}, which provides a similar user experience as ibus-gjs.<br />
* KDE: {{Pkg|kimtoy}} could use skin from Sogou and fcitx.<br />
<br />
=== Extend pinyin dictionary ===<br />
<br />
Pinyin dictionary is located at {{ic|~/.config/fcitx/pinyin}}. File {{ic|pybase.mb}} is for single characters and file {{ic|pyphrase.mb}} defines pinyin phrases. To extend them, put your file into {{ic|/usr/share/fcitx/pinyin}} and restart fcitx.<br />
<br />
=== Skins ===<br />
<br />
You can download skins and extract them to one of the following directories, you can create the directory if it does not exist:<br />
<br />
/usr/share/fcitx/skin #Global settings<br />
~/.config/fcitx/skin #User settings<br />
<br />
=== Cloud Pinyin configuration ===<br />
<br />
After installing the {{Pkg|fcitx-cloudpinyin}} input method, restart fcitx. If you could not find it in configuration GUI, enable advanced settings. The cloud query result will be added to current input method dictionary automatically. <br />
<br />
If your network prevents you from accessing Google, change Cloud Pinyin source to Baidu.<br />
<br />
The query result from cloud will list as secondary candidate by default and it is configurable. If the result already exists, only one item is shown. <br />
<br />
{{Note|Set query result as first candidate is not recommend because the dictionary order will be changed if query returns an empty result}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Shortcut keys ===<br />
<br />
Some commonly used default shortcut keys:<br />
<br />
* {{ic|Ctrl+Space}} - activates the input method<br />
* {{ic|Left Shift}} - temporarily switches to English<br />
* {{ic|Ctrl+Shift}} - switch between input methods<br />
* {{ic|-}}/{{ic|1==}} - page forward/backward<br />
* {{ic|Shift+Space}} - Full-width, half-width switching<br />
<br />
{{Note|You can modify these shortcut keys in the global configuration of the configuration interface.}}<br />
<br />
=== Vim ===<br />
<br />
If you often use Fcitx under Vim, you can install the {{AUR|vim-fcitx}} plugin, or add the following code to {{ic|~/.vimrc}}. When exiting insert mode, Fcitx is automatically closed, otherwise the reverse:<br />
<br />
"##### auto fcitx ###########<br />
let g:input_toggle = 1<br />
function! Fcitx2en()<br />
let s:input_status = system("fcitx-remote")<br />
if s:input_status == 2<br />
let g:input_toggle = 1<br />
let l:a = system("fcitx-remote -c")<br />
endif<br />
endfunction<br />
<br />
function! Fcitx2zh()<br />
let s:input_status = system("fcitx-remote")<br />
if s:input_status != 2 && g:input_toggle == 1<br />
let l:a = system("fcitx-remote -o")<br />
let g:input_toggle = 0<br />
endif<br />
endfunction<br />
<br />
set ttimeoutlen=150<br />
"Exit insert mode<br />
autocmd InsertLeave * call Fcitx2en()<br />
"Enter insert mode<br />
autocmd InsertEnter * call Fcitx2zh()<br />
"##### auto fcitx end ######<br />
<br />
{{Note|Due to calling external programs, this will significantly slow down the mapping that will repeatedly enter and exit insert mode. It is recommended to rewrite the relevant mapping, and use Vim with Python support in conjunction with fcitx.vim to improve efficiency.}}<br />
<br />
=== Special symbols ===<br />
<br />
Create {{ic|~/.config/fcitx/data/pySym.mb}}, the content of the file is as follows:<br />
<br />
#The first line with "#" is a comment<br />
#Format: coding symbol<br />
#Code can only be lowercase letters, after pinyin analysis, the longest is 10 (such as py is 2, pinyin is also 2)<br />
#Mathematics symbols<br />
sxfh +<br />
sxfh -<br />
sxfh <<br />
sxfh =<br />
sxfh ><br />
sxfh ±<br />
sxfh ×<br />
sxfh ÷<br />
sxfh ∈<br />
sxfh ∏<br />
sxfh ∑<br />
sxfh ∕<br />
sxfh √<br />
sxfh ∝<br />
<br />
Enter a code directly to match the corresponding special symbol.<br />
<br />
{{Note|The encoding can only be expressed with twenty-six lowercase letters; starting with v is invalid.}}<br />
<br />
=== Clipboard Access ===<br />
<br />
You can use fcitx to input text in you clipboard (as well as a short clipboard history and primary selection). The default trigger key is {{ic|Ctrl-;}}. You can change the trigger key as well as other options in the Clipboard addon configure page.<br />
<br />
{{Note|This is NOT a clipboard manager, it does not hold the selection or change its content as what a clipboard manager is supposed to do. It can only be used to input from the clipboard.}}<br />
<br />
{{Warning| Some clients do not support multi-line input, so you may see the multi-line clipboard content pasted as a single line using fcitx-clipboard. This is either a bug or feature of the program being used and it is not something fcitx is able to help with.}}<br />
<br />
=== fcitx-remote ===<br />
<br />
''fcitx-remote'' is a commandline tool that can be used to control the fcitx state. It is installed with the {{Pkg|fcitx}} package.<br />
<br />
One option worth elaborating upon here is {{ic|fcitx-remote -s ''imname''}}, which switches to the input method identified by {{ic|''imname''}}. The correct {{ic|''imname''}} for an in use input method can be found by executing ''fcitx-diagnose'', and looking under the "## Input Methods:" section.<br />
<br />
=== Input special character ===<br />
<br />
See [[Fcitx5#Input special character]], this content also applies to Fcitx.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Disable or change ''Extra key for trigger input method'' [sic] ===<br />
<br />
This setting is under the ''Global Config'' tab and defaults to ''SHIFT Both'', meaning that pressing ''either'' shift key will immediately change input methods. Although it should only apply when a shift key is pressed individually, it tends to randomly interrupt typing capital letters, selecting text with the keyboard, etc. while using standard keyboard input.<br />
<br />
In addition, this setting may revert to default without warning at any time. To ensure fcitx's configuration cannot be modified, you must make the file immutable: {{ic|chattr +i ~/.config/fcitx/config}} (as the root user).<br />
<br />
=== Diagnose the problem ===<br />
<br />
If you have problems using fcitx, eg. Ctrl+Space fail to work in all applications, then the first thing you should try is to diagnose using {{ic|fcitx-diagnose}}.<br />
The output of {{ic|fcitx-diagnose}} should contain the clue to most common problems.<br />
Providing the output of it will also help when you consult other people(eg. in IRC or forums).<br />
<br />
=== Emacs ===<br />
<br />
If your {{ic|LC_CTYPE}} is English, you may not be able to use input method in emacs due to an old emacs bug. You can set your {{ic|LC_CTYPE}} to something else such as {{ic|zh_CN.UTF-8}} before emacs starts to get rid of this problem. <br />
<br />
Note that the corresponding [[locale]] should be [[Locale#Generating locales|generated]] on your your system.<br />
<br />
The default fontset will use `-*-*-*-r-normal--14-*-*-*-*-*-*-*' as basefont (in {{ic|src/xfns.c}}), if you do not have one matched (like terminus or 75dpi things, you can look the output of `xlsfonts'), XIM can not be activated. According to [https://fcitx-im.org/wiki/FAQ#Emacs FAQ] and [[Fonts#Bitmap|Fonts]], it is likely that {{AUR|xorg-fonts-misc-otb}} is the one that should be installed since {{Pkg|xorg-fonts-misc}} no longer provides the required fontset.<br />
<br />
==== Emacs Daemon ====<br />
<br />
If you are using [[Emacs#As_a_daemon|emacs daemon/client mode]], {{ic|LC_CTYPE}} should be set when starting the daemon. For example, by running emacs daemon with {{ic|1=LC_CTYPE=zh_CN.UTF-8 emacs --daemon}}.<br />
<br />
If starting emacs daemon from [[systemd]], [[Systemd#Editing provided_units|set]] {{ic|1=Environment="LC_CTYPE=zh_CN.UTF-8" "XMODIFIERS=@im=fcitx"}} in the unit file.<br />
<br />
({{ic|XMODIFIERS}} may need to be set explicitly here as systemd does not load {{ic|.xprofile}}. Check the {{ic|initial-environment}} variable in emacs to verify both variables are set correctly.)<br />
<br />
=== Ctrl+Space fail to work in GTK programs ===<br />
<br />
This problem sometimes happens especially when the locale is set as English. Please make sure your {{ic|GTK_IM_MODULE}} is set correctly.<br />
<br />
See also [https://fcitx-im.org/wiki/FAQ#When_use_Ctrl_.2B_Space.2C_Fcitx_cannot_be_triggered_on FAQ]<br />
<br />
If you have set the {{ic|*_IM_MODULE}} environment variables to fcitx but cannot activate fcitx, please check if you have installed the corresponding input method modules.<br />
<br />
Some programs can only use xim, if you are using these programs, please make sure your {{ic|XMODIFIERS}} is set properly and be aware of the problems you may have. These programs include all programs that are not using GTK or Qt (e.g. programs that use tk, motif, or xlib directly), emacs, opera, openoffice, libreoffice, skype.<br />
<br />
If you cannot enable fcitx in ''gnome-terminal'' under Gnome and the above way does not work, try:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Gtk/IMModule':<'fcitx'>}"<br />
<br />
=== Buildin Chinese Pinyin Default NOT ACTIVE ===<br />
<br />
If your locale is {{ic|en_US.UTF-8}}, fcitx did NOT enable the buildin Chinese Pinyin input method by default. There is only {{ic|fcitx-keyboard-us}} input method enabled. You can get a notice by {{ic|fcitx-diagnose}} command like this:<br />
<br />
## Input Methods:<br />
1. Found 1 enabled input methods:<br />
fcitx-keyboard-us<br />
2. Default input methods:<br />
**You only have one input method enabled, please add a keyboard input method as the first one and your main input method as the second one.**<br />
<br />
Then you should add {{ic|Pinyin}} or {{ic|Shuangpin}} input method to actived input methods by the GUI configure tool.<br />
<br />
=== fcitx and KDE ===<br />
<br />
For some reasons, [[KDE]] does not handle keyboard layouts properly. For example, if you switch from US (English) to LT (Lithuanian), all numbers on the keyboard should produce Lithuanian letters, but they still produce numbers as the output. This can be fixed by these steps:<br />
<br />
# Turn off ''fcitx'' if it is running in the background.<br />
# Disable stuff related to KDE:<br />
## At ''System settings > Input devices > Layouts (tab)'' make sure that ''Configure layouts'' is unchecked.<br />
## At ''System settings > Input devices > Advanced (tab)'' make sure that ''Configure keyboard options'' is unchecked.<br />
# Start ''fcitx'' to start it. You can close the terminal - ''fcitx'' will still be running in the background.<br />
# Set up your needed layouts (right click on the system tray icon, then ''Configure'').<br />
# Right click on the system tray icon, then ''Exit''<br />
<br />
At this point you should have working layouts, native KDE layouts switch icon should appear and you can switch them by mouse scroll or click on it.<br />
<br />
=== Input method switched to English unintentionally ===<br />
<br />
For instance, in XMind, when the user presses {{ic|Enter}} to create a node, input method is always switched to English, and has to be switched back to Chinese manually.<br />
<br />
To fix this issue, open the fcitx GUI configuration tool (provided by {{Pkg|fcitx-configtool}}), switch to tab ''Global Config'', in dropdown menu ''Share State Among Window'', select ''PerProgram'' or ''All''.<br />
<br />
=== xmodmap settings being overwritten ===<br />
<br />
fcitx controls keyboard layout, so your [[xmodmap]] settings will be overwritten.<br />
Since 4.2.7, Fcitx will try to load {{ic|~/.Xmodmap}} if it exists.<br />
<br />
For more details on how you can save your xmodmap changes see [https://fcitx-im.org/wiki/FAQ#xmodmap_settings_being_overwritten FAQ]<br />
<br />
==== Fcitx and setxkbmap ====<br />
<br />
If you are using ''setxkbmap'' for another language, then (as per above) fcitx can overwrite them and even prevent from switching to that language in certain applications (e.g. QuteBrowser).<br />
<br />
If you would like to prevent that and manage your [[xmodmap]] layouts independently from fcitx then follow these steps:<br />
# Open the fcitx GUI configuration tool (provided by {{Pkg|fcitx-configtool}})<br />
# Switch to tab ''Addon''<br />
# Select ''Advanced''<br />
# Search for ''xkb''#<br />
# Select ''X Keyboards Integration''<br />
# Click ''Configure''<br />
# Unselect ''Allow to Override System XKB Settings''<br />
# Click ''OK''<br />
<br />
=== Fcitx preedit box is too small with HiDPI ===<br />
<br />
See [[HiDPI#Fcitx]]<br />
<br />
== See also ==<br />
<br />
* [https://gitlab.com/fcitx/fcitx Fcitx GitLab]<br />
* [https://fcitx-im.org/ Fcitx Wiki]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Telegram&diff=748305Telegram2022-09-25T10:44:39Z<p>Hexhu: /* Tips and tricks */ Add solution to fcitx failure issue that's commonly met by people upgrading from an older non-qt6 telegram-desktop</p>
<hr />
<div>[[Category:Instant messaging]]<br />
[[fa:Telegram]]<br />
[[ja:Telegram]]<br />
[[pt:Telegram]]<br />
[[ru:Telegram]]<br />
[[zh-hans:Telegram]]<br />
[[wikipedia:Telegram (software)|Telegram]] is a cloud-based cross-platform instant messaging service with optional end-to-end encryption. Account creation requires a phone number.<br />
<br />
The official clients are open-source but the code for recent versions is not always immediately published. The server-side code is proprietary.<br />
<br />
== Installation ==<br />
<br />
You can use one of following methods in order to use Telegram:<br />
<br />
=== Chat client plugins ===<br />
<br />
* By using the {{AUR|telegram-tdlib-purple-git}} package, connection to Telegram through (graphical or command-line) messenger software based on {{Pkg|libpurple}} such as [[Pidgin]] is provided.<br />
* Messaging apps that are using [[wikipedia:Telepathy_(software)|Telepathy]] can make use of {{Pkg|telepathy-haze}} package, which provides possibility of using {{Pkg|libpurple}} and thus {{AUR|telegram-tdlib-purple-git}} to connect Telegram.<br />
* In the [[KDE]] desktop environment using {{Pkg|telepathy-morse}} provides capability of connecting the default messenger to Telegram.<br />
<br />
=== Graphical clients ===<br />
<br />
The [https://desktop.telegram.org/ official application] built by Arch Linux: {{Pkg|telegram-desktop}}.<br />
<br />
Third-party clients:<br />
<br />
* {{AUR|kotatogram-desktop-bin}}, {{AUR|kotatogram-desktop}}, {{AUR|kotatogram-desktop-dynamic-bin}}<br />
<br />
=== Command-line clients ===<br />
<br />
* {{AUR|telegram-cli-git}} provides command-line interface to connect and use Telegram. For more information about the program, visit the program page on [https://github.com/kenorb-contrib/tg Github].<br />
* {{AUR|nctelegram-git}} is a command-line interface for Telegram based on [[wikipedia:Ncurses|Ncurses]] and needs {{AUR|telegram-cli-git}} to run. For more information about the program, visit the program page on [https://github.com/Nanoseb/ncTelegram Github].<br />
* {{AUR|telegram-tg}} Telegram terminal client. For more information about the program, visit the program page on [https://github.com/paul-nameless/tg Github].<br />
* {{AUR|python-telegram-send}}, not a full client but a command-line tool to directly send messages or files via Telegram.<br />
* [https://github.com/zevlg/telega.el telega.el] - GNU Emacs Telegram client.<br />
* [https://github.com/vtr0n/TelegramTUI TelegramTUI] - terminal Telegam client with a pseudo-graphic GUI<br />
<br />
=== Web-based clients ===<br />
<br />
* The official [https://web.telegram.org/k/ Telegram WebK].<br />
* The official [https://web.telegram.org/z/ Telegram WebZ].<br />
* {{AUR|franz}} is an [https://github.com/meetfranz/franz open-source] web-based application that can be used for web-based interface of various instant messaging software such as [[wikipedia:Telegram (software)|Telegram]], [[wikipedia:WhatsApp|WhatsApp]], [[wikipedia:Facebook|Facebook]], and more.<br />
* {{AUR|rambox-bin}} is an alternative to Franz, also open source. It offers all features of its counterpart.<br />
* Use [https://telegram.org/dl/webogram/chromeapp Telegram Chrome app] for [[Chromium]], to connect to Telegram in your browser via web interface.<br />
<br />
== Tips and tricks ==<br />
<br />
=== GTK dialogs in Telegram Desktop ===<br />
<br />
If you want to use [[GTK]] file dialogs instead of Qt ones, set {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] to {{ic|gtk3}}.<br />
<br />
=== KDE dialogs in Telegram Desktop ===<br />
<br />
If you want to use [[KDE]] file dialogs instead of Qt ones, set {{ic|QT_QPA_PLATFORMTHEME}} [[environment variable]] to {{ic|flatpak}}.<br />
<br />
=== SVG icon theme in Telegram Desktop ===<br />
<br />
If you want to use an icon theme based on svg image (e.g. {{Pkg|papirus-icon-theme}}) install {{Pkg|qt5-svg}}. See [[Qt#Icon theme is not applied]] for details.<br />
<br />
=== Wayland support ===<br />
<br />
GNOME Wayland may not set cursor settings for Telegram[https://gitlab.gnome.org/GNOME/gnome-shell/-/issues/5894][https://github.com/telegramdesktop/tdesktop/issues/25075#issuecomment-1250020362]. This may result in cursors being of the wrong theme, size and not being able to resize the window.<br />
<br />
Set {{ic|XCURSOR_THEME}} and {{ic|XCURSOR_SIZE}} environment variables manually (e.g., {{ic|1=XCURSOR_THEME=Adwaita}} and {{ic|1=XCURSOR_SIZE=24}})<br />
<br />
See [[Wayland#Qt]] for further instructions.<br />
<br />
=== xdg-open in Telegram Desktop ===<br />
<br />
If you want to use xdg-open on t.me links and receive an error not finding a handler for tg:<br />
<br />
{{bc|1=<br />
xdg-mime default telegramdesktop.desktop application/x-xdg-protocol-tg<br />
xdg-mime default telegramdesktop.desktop x-scheme-handler/tg<br />
}}<br />
<br />
=== Failed to set real-time priority for thread: Operation not permitted ===<br />
<br />
If you get the following error<br />
<br />
{{hc|$ telegram-desktop|<br />
[ALSOFT] (EE) Failed to set real-time priority for thread: Operation not permitted (1)<br />
}}<br />
<br />
Install {{Pkg|realtime-privileges}}, [[Users and groups#Group management|add]] yourself to the {{ic|realtime}} group and reboot. See [[Realtime process management#Configuring PAM]] for details.<br />
<br />
=== HiDPI scaling ===<br />
<br />
If you have Qt scaling enabled on your system, and the scaling factor is not an integer, you may encounter problems like [https://github.com/telegramdesktop/tdesktop/issues/23953 pixelated images and icons]. you may need to disable [https://doc.qt.io/qt-5/highdpi.html#high-dpi-support-in-qt high-DPI scaling] for Telegram separately.<br />
<br />
Copy {{ic|/usr/share/applications/telegramdesktop.desktop}} to your [[Desktop entries#Application entry|user-specific applications]] and [[textedit|edit]] it as follows: <br />
<br />
{{hc|1=$HOME/.local/share/applications/telegramdesktop-no-scaling.desktop|2=<br />
...<br />
Exec=env -u QT_SCREEN_SCALE_FACTORS telegram-desktop -- %u<br />
...<br />
}}<br />
<br />
You may need to [[Desktop entries#Update database of desktop entries|update the database]] of desktop entries.<br />
<br />
=== Audio backend ===<br />
<br />
As Telegram makes use of [https://github.com/kcat/openal-soft OpenAL], it is possible to configure the audio settings by editing its [https://github.com/kcat/openal-soft/blob/master/alsoftrc.sample config files], i.e. {{ic|~/.config/alsoft.conf}}, or the [[environment variables]] listed [https://github.com/kcat/openal-soft/blob/master/docs/env-vars.txt here].<br />
<br />
In case sound is not working due to an invalid audio backend being used, it can be overwritten by setting the [[environment variable]] {{ic|ALSOFT_DRIVERS}} or the {{ic|drivers}} property in the {{ic|[general]}} section of the OpenAL config. The drivers value {{ic|"pulse,"}} for example would try pulseaudio first and then fallback to the default driver list.<br />
<br />
=== Choose correct web camera ===<br />
<br />
Telegram version 3.7.1 does not allow to select the web camera to use in video conference. If you want to force telegram to use a different camera, as a workaround you can disable the unwanted camera device as described in [https://askubuntu.com/a/166819].<br />
<br />
=== Fcitx support for Qt 6 Telegram ===<br />
<br />
Since 3.4.2-2 telegram-desktop is built against Qt 6, so {{Pkg|fcitx-qt6}} or the {{Pkg|fcitx-im}} group must be installed for [[Fcitx]] to work in the app. If using [[Fcitx5]], install {{Pkg|fcitx5-im}}.<br />
<br />
== See also ==<br />
<br />
* [https://t.me/archlinuxgroup Arch Linux] - Unofficial group for discussing everything about Arch Linux.<br />
* [https://t.me/archewikibot ArchWikiBot] - Inline bot for searching through ArchWiki pages.<br />
* [https://t.me/planetarch Planet Arch Linux & News] - Channel with recent Planet Arch updates and Latest News in one place.<br />
* [https://t.me/archlinux_updates Arch Linux: Recent package updates] - Channel with recent package updates in Arch Linux repositories.<br />
* [https://t.me/archlinuxnews Arch Linux News] - Channel with news from Arch web site ''(not updated since 2018)''.<br />
* [https://t.me/archplanet Planet Arch] - Channel with posts from Planet Arch web site ''(not updated since 2018)''.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Localization/Simplified_Chinese&diff=698209Localization/Simplified Chinese2021-10-03T13:40:37Z<p>Hexhu: /* Basic Chinese support */ add link to Locale wiki page</p>
<hr />
<div>[[Category:Localization]]<br />
[[zh-hans:Localization (简体中文)/Simplified Chinese]]<br />
{{Related articles start}}<br />
{{Related|Localization/Chinese}}<br />
{{Related|Localization (正體中文)/Traditional Chinese (正體中文)}}<br />
{{Related|Installation guide}}<br />
{{Related|General recommendations}}<br />
{{Related articles end}}<br />
<br />
According to "[[The Arch Way]]": We cannot configure everything for you, because "Preferences and needs are different for everyone", but we will try to ensure the configuration to be convenient and simple. In fact, it is even easier than some Chinese versions of Linux.<br />
<br />
This article provides Chinese cultural guidance for various common software as much as possible. But in practical applications, you may encounter all kinds of issues. Do not be discouraged when you are in trouble. Solving problems is a pleasure in itself. You can seek help through various platforms:<br />
<br />
* [https://www.google.com/ncr Google] and other search engines<br />
* [https://bbs.archlinux.org/ Arch official forum]<br />
* [https://forum.ubuntu.org.cn/viewforum.php?f=155 Ubuntu Chinese Forum Arch area]<br />
* [ircs://irc.libera.chat/archlinux-cn IRC channel: #archlinux-cn]<br />
<br />
== Basic Chinese support ==<br />
<br />
To properly display Chinese, you must set the [[Locale|locale]] correctly and install the appropriate Chinese fonts.<br />
<br />
=== locale settings ===<br />
<br />
==== Install Chinese locale ====<br />
<br />
In Linux, locales are used to set up different environments for running programs. Commonly used Chinese locales are (the most intuitive is the number of words that can be displayed):<br />
<br />
zh_CN.GB2312<br />
zh_CN.GBK<br />
zh_CN.GB18030<br />
zh_CN.UTF-8<br />
zh_TW.BIG-5<br />
zh_TW.UTF-8<br />
<br />
It is recommended to use UTF-8 locale. You need to modify {{ic|/etc/locale.gen}} to set the locales that can be used in the system (erase the comment symbol "{{ic|#}}" before the corresponding item):<br />
<br />
en_US.UTF-8 UTF-8<br />
zh_CN.UTF-8 UTF-8<br />
<br />
After executing {{ic|locale-gen}}, the selected locales can be used in the system. You may use {{ic|locale}} to view the currently used locale(s), and {{ic|locale -a}} to view the currently available locales.<br />
<br />
==== Enable Chinese locales ====<br />
<br />
{{Warning|Globally setting Chinese locales in {{ic|/etc/locale.conf}} will cause tty to display garbled texts due to the [https://unix.stackexchange.com/questions/273061/273063#273063 tty glyph limitation of Linux kernel]. To properly display Chinese characters under tty, install and [http://zhcon.sourceforge.net/faq.html#faq1 configure] {{AUR|zhcon}}.}}<br />
<br />
===== Set the global default locale to English (optional) =====<br />
<br />
To avoid the tty garbled text issue mentioned above, globally set the [[Locale#LANG:_default_locale|LANG locale]] to {{ic|en_US.UTF-8}} in {{ic|/etc/locale.conf}}:<br />
<br />
LANG=en_US.UTF-8<br />
<br />
===== User-specific locales =====<br />
<br />
You may set your own user environment variables in {{ic|~/.bashrc}}, {{ic|~/.xinitrc}}, or {{ic|~/.xprofile}}.<br />
<br />
* {{ic|.bashrc}}: Settings are applied everytime you log in '''using the terminal'''.<br />
* {{ic|.xinitrc}}: Settings are applied everytime you '''use [[startx]] or [[SLiM]] to start the [[X]] interface'''.<br />
* {{ic|.xprofile}}: Settings are applied everytime you '''log in using a display manager such as [[GDM]]'''.<br />
<br />
===== Set Chinese locales for graphical interfaces =====<br />
<br />
It is not recommended to set a global Chinese locale in {{ic|/etc/locale.conf}} because it causes tty to display garbled characters.<br />
<br />
As mentioned earlier, Chinese locale can be set separately in {{ic|~/.xinitrc}} or {{ic|~/.xprofile}}. Prepend the following two lines to one of the two files (if you are not sure which file to use, prepend to both):<br />
<br />
export LANG=zh_CN.UTF-8<br />
export LANGUAGE=zh_CN:en_US<br />
<br />
{{Warning|Be sure to put them '''before''' the {{ic|exec ''_example_WM_or_DE_''}} line in {{ic|~/.xinitrc}}.}}<br />
<br />
{{Note|This method is suitable for [[SLiM]] users or for people who don't use a graphical login interface (aka greeter). [[GDM]] and [[SDDM]] users can configure the display language in [[GNOME]] or [[KDE]] settings.}}<br />
<br />
{{Note|It is not recommended to override all locale settings with a global {{ic|export LC_ALL}}. {{ic|LC_ALL}} should be reserved for diagnostic debugging purposes only. {{ic|LC_ALL}} will bring unnecessary difficulties for diagnosing language settings issues.}}<br />
<br />
=== Chinese fonts ===<br />
<br />
==== Install fonts ====<br />
<br />
In addition to locales, Chinese fonts are also required.<br />
<br />
Commonly used free (GPL or compatible copyright) Chinese fonts include:<br />
<br />
* {{Pkg|wqy-microhei}}<br />
* {{Pkg|wqy-microhei-lite}}<br />
* {{Pkg|wqy-bitmapfont}}<br />
* {{Pkg|wqy-zenhei}}<br />
* {{Pkg|ttf-arphic-ukai}}<br />
* {{Pkg|ttf-arphic-uming}}<br />
* {{Pkg|adobe-source-han-sans-cn-fonts}}<br />
* {{Pkg|adobe-source-han-serif-cn-fonts}}<br />
* {{Pkg|noto-fonts-cjk}}<br />
<br />
{{Out of date|The {{ic|~/.fonts}} path is deprecated. It may be preferable to link to [[Fonts#Manual installation]] instead of duplicating information regarding font paths here.}}<br />
<br />
System fonts will be installed to {{ic|/usr/share/fonts}} by default. If you do not have root authority or plan to use certain fonts yourself, you can directly copy these fonts to {{ic|~/.fonts}} (or its subdirectories) and add the path to {{ic|/etc/fonts/local.conf}}. For details, go over the following chapters.<br />
<br />
See also: [http://wiki.debian.org.hk/w/Where_can_I_find_fonts_for_GNU/Linux]<br />
<br />
==== Chinese fonts configuration ====<br />
<br />
===== fontconfig settings =====<br />
<br />
{{Out of date|The {{ic|~/.fonts.conf}} path appears to be deprecated. It may be preferable to link to [[Font configuration#Fontconfig configuration]] or [[Font configuration (简体中文)#Fontconfig配置]] instead of explicitly mentioning font configuration paths.}}<br />
<br />
The setting file of fontconfig is {{ic|~/.fonts.conf}} (user) or {{ic|/etc/fonts/conf.d}} (global). It is recommended to modify the former.<br />
<br />
For Chinese fonts settings, see [[Fonts (简体中文)]] and [[Font configuration (简体中文)]].<br />
<br />
[[Font Configuration (简体中文)/Chinese (简体中文)]] provides a demonstration of Chinese fontconfig.<br />
<br />
See also:<br />
<br />
* [http://www.chinalinuxpub.com/read.php?wid=634 fontconfig 用户手册]<br />
* [http://wiki.linux.org.hk/w/Make_Debian_support_Chinese Debian 中文支持]<br />
* [https://web.archive.org/web/20070219091008/http://www.higherorder.org/wiki/Fontconfig Fontconfig wiki page]<br />
<br />
===== Fixed Simplified Chinese display as a variant (Japanese) glyph =====<br />
<br />
After installing Noto Sans CJK, {{Pkg|adobe-source-han-sans-otc-fonts}} (Siyuan Bold) or {{Pkg|adobe-source-han-serif-otc-fonts}} (Siyuan Song), in some cases (framework undefined area), rendered Chinese characters do not match the standard form, such as 门, 关, and 复.<br />
<br />
This is because different default fonts can be set in each program, such as Arial or Tohamo, and the attributes of these fonts are controlled by [[fontconfig (简体中文)|fontconfig]]. The order of use is based on the regional code and the default order of A-Z. Since {{ic|ja-JP}} is before {{ic|zh_{CN,HK,SG,TW}<nowiki/>}}, Japanese fonts are used first.<br />
<br />
{{Tip|Fonts can be set separately in Chromium/Chrome/Firefox browser settings, for example, adjust the font option to Noto xxx CJK SC.}}<br />
<br />
You can use the following methods to solve the issue (taking simplified Chinese as an example):<br />
<br />
* Only install Simplified Chinese fonts in cjk, such as Siyuan Bold Simplified Chinese package {{Pkg|adobe-source-han-sans-cn-fonts}}, {{Pkg|adobe-source-han-serif-cn-fonts}} or {{AUR|noto-fonts-sc}}.<br />
* Add {{ic|1=LANG=zh_CN.UTF-8}} to {{ic|locale.conf}} to set Simplified Chinese as the default language. Since the [[Locale]] is defined for CJK priority, the default priority is ignored.<br />
* Manually adjust the priority so that the Chinese fonts are set before the Japanese fonts. [https://tieba.baidu.com/p/4879946717]:<br />
<br />
Create a file under {{ic|/etc/fonts/conf.d/}} or {{ic|/etc/fonts/conf.avail/}}, such as {{ic|64-language-selector-prefer.conf}}, or modify or create {{ic|~/.fonts.conf}} (only effective for the user):<br />
<br />
If {{Pkg|noto-fonts-cjk}} is installed, write:<br />
<br />
{{bc|1=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>Noto Sans CJK SC</family><br />
<family>Noto Sans CJK TC</family><br />
<family>Noto Sans CJK JP</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the priority of sans serif font--><br />
<alias><br />
<family>monospace</family><br />
<prefer><br />
<family>Noto Sans Mono CJK SC</family><br />
<family>Noto Sans Mono CJK TC</family><br />
<family>Noto Sans Mono CJK JP</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the monospace font priority--><br />
</fontconfig><br />
}}<br />
<br />
If you have installed {{Pkg|adobe-source-han-sans-otc-fonts}}:<br />
<br />
{{bc|1=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>Source Han Sans SC</family><br />
<family>Source Han Sans TC</family><br />
<family>Source Han Sans HW</family><br />
<family>Source Han Sans K</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the priority of sans serif font--><br />
<alias><br />
<family>monospace</family><br />
<prefer><br />
<family>Source Han Sans SC</family><br />
<family>Source Han Sans TC</family><br />
<family>Source Han Sans HW</family><br />
<family>Source Han Sans K</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the monospace font priority--><br />
</fontconfig><br />
}}<br />
<br />
Note that if you create an xml file under {{ic|/etc/fonts/conf.avail}}, for example:<br />
<br />
# ln -s /etc/fonts/conf.avail/64-language-selector-prefer.conf /etc/fonts/conf.d/64-language-selector-prefer.conf<br />
<br />
you have to update the font cache to take effect:<br />
<br />
# fc-cache -fv<br />
<br />
Execute the following command to check. If {{ic|NotoSansCJK-Regular.ttc: "Noto Sans CJK SC" "Regular"}} appears, the settings are successfully applied:<br />
<br />
# fc-match -s | grep 'Noto Sans CJK'<br />
<br />
=== Chinese input method ===<br />
<br />
Commonly used Chinese input method frameworks are [[IBus]], [[fcitx]] and [[scim]]. For specific installation and configuration, please refer to the respective articles.<br />
<br />
{{Note|SCIM current lacks maintenance and is therefore not recommended.}}<br />
<br />
== Terminal Chinese support ==<br />
<br />
=== Bootloader Chinese support ===<br />
<br />
See [[GRUB2 (简体中文)]].<br />
<br />
== Cultural configuration in software ==<br />
<br />
=== Firefox ===<br />
<br />
Simplified Chinese installation: {{Pkg|firefox-i18n-zh-cn}}。<br />
<br />
Traditional Chinese installation: {{Pkg|firefox-i18n-zh-tw}}。<br />
<br />
=== Libreoffice ===<br />
<br />
Simplified Chinese installation: {{Pkg|libreoffice-fresh-zh-cn}} or {{Pkg|libreoffice-still-zh-cn}}.<br />
<br />
Traditional Chinese installation: {{Pkg|libreoffice-fresh-zh-tw}} or {{Pkg|libreoffice-still-zh-cn}}.<br />
<br />
=== PDF reader ===<br />
<br />
Most PDF viewers already support Chinese. However, there are some additional language packs/fonts that need to be installed:<br />
<br />
Arcobat's fonts are {{AUR|acroread-fonts}}, or {{AUR|acroread-fonts-systemwide}} for system-wide fonts.<br />
<br />
For {{Pkg|poppler}}-based readers (e.g., {{Pkg|okular}}, [[Evince]]) and image processing tools that can handle PDF files (e.g., [[Inkscape]], {{Pkg|krita}}, {{Pkg|mypaint}}), {{Pkg|poppler-data}} needs to be installed.<br />
<br />
=== Java ===<br />
<br />
For Sun [[Java]] users, create a {{ic|fallback}} directory under {{ic|/opt/java/jre/lib/fonts}}, then link or copy several Chinese fonts to the directory to allow java programs to display Chinese correctly. For example, if {{AUR|jre}} and {{Pkg|opendesktop-fonts}} have been installed, use the following command:<br />
<br />
# ln -s /usr/share/fonts/TTF/odosung.ttc /opt/java/jre/lib/fonts/fallback/<br />
# cd /opt/java/jre/lib/fonts/fallback/<br />
# mkfontdir<br />
# mkfontscale<br />
<br />
=== vim ===<br />
<br />
If the locale is utf8-encoded, using [[vim]] to open other Chinese encoded files may be garbled. The following settings need to be made in {{ic|~/.vimrc}}:<br />
<br />
{{hc|~/.vimrc|2=<br />
...<br />
set fileencodings=utf8,cp936,gb18030,big5<br />
...<br />
}}<br />
<br />
=== Chinese video subtitles ===<br />
<br />
==== MPlayer ====<br />
<br />
To allow [[MPlayer]] to display Chinese subtitles correctly, the key is to make sure the encoding of the subtitle file is consistent with the encoding used in mplayer's configurations. If the subtitle file is encoded as gbk, use {{ic|1=subcp=cp936}}; If the subtitle file is encoded as utf-8, use {{ic|1=subcp=utf8}}. If the subtitle file is encoded as utf-8 and set to {{ic|1=subcp=cp936}}, some garbled characters will appear. Another simpler method is to set to {{ic|1=subcp=enca:zh:ucs-2}}, so that enca is responsible for the encoding and display of subtitles.<br />
<br />
Modify {{ic|~/.mplayer/config}}:<br />
<br />
{{hc|~/.mplayer/config|2=<br />
font='文泉驿正黑'<br />
subcp=enca:zh:ucs-2<br />
}}<br />
<br />
Use the following command to manually load subtitles:<br />
<br />
$ mplayer xxx.avi -sub xxxxx.srt<br />
<br />
If a graphical front end (such as [[SMPlayer]]) is used, it will work as long as you set the default subtitle encoding and font in the settings dialog box.<br />
<br />
==== xine ====<br />
<br />
Xine can also display Chinese subtitles, but you need to make your own Chinese fonts. For details, please refer to [https://forum.ubuntu.org.cn/about2760.html].<br />
<br />
==== gstreamer ====<br />
<br />
In totem 1.4.0, since gstreamer0.10 is used, it should be able to automatically load srt subtitles with the same name.<br />
<br />
=== LaTeX ===<br />
<br />
You need to install CJK packages and the appropriate fonts. For details, please refer to [http://www.ctex.org].<br />
<br />
== Garbled problem ==<br />
<br />
The basic principle to avoid garbled characters is to use utf-8 instead of gbk/gb2312.<br />
<br />
=== File name is garbled ===<br />
<br />
Install {{Pkg|convmv}} and use the {{ic|convmv}} command to convert the encoding format. For example:<br />
<br />
$ convmv -f GBK -t UTF-8 --notest --nosmart file<br />
<br />
{{ic|-f}} specifies the original encoding, and {{ic|-t}} specifies the output encoding. Use {{ic|convmv --list}} to find out all the supported encodings.<br />
{{ic|--notest}} means not to test but to transcode (if you do not use this parameter, the conversion result will be printed instead of actual transcoding), {{ic|--smart}} allows {{ic|convmv}} to ignore the request if it is already in UTF-8.<br />
<br />
=== File content is garbled ===<br />
<br />
Use the {{ic|iconv}} command to convert the format. For example:<br />
<br />
$ iconv -f GBK -t UTF-8 -o new-file origin-file<br />
<br />
{{ic|-f}} specifies the original encoding, and {{ic|-t}} specifies the output encoding. Use {{ic|iconv -l}} to query all supported encodings. {{ic|-o}} specifies the output file.<br />
<br />
=== zip compressed package is garbled ===<br />
<br />
Under non-utf8 coding environment (generally the Chinese environment under Windows), do not use zip for compressions ([[7z]] is recommended). Install and use {{AUR|unzip-iconv}} or {{AUR|unzip-natspec}} instead of the original {{Pkg|unzip}} program to decompress. For example:<br />
<br />
$ unzip -O gbk file.zip<br />
<br />
{{ic|file.zip}} is the compressed file, {{ic|gbk}} is the encoding format of the file, specified with {{ic|-O}} (the original unzip command has no {{ic|-O}} option).<br />
<br />
=== MP3 file label garbled ===<br />
<br />
For players that use [[GStreamer]] as the backend, such as [[Rhythmbox]] and totem, after setting the following environment variables, the GB3 encoded ID3 tag in mp3 can be read correctly:<br />
<br />
export GST_ID3_TAG_ENCODING=GBK:UTF-8:GB18030<br />
export GST_ID3V2_TAG_ENCODING=GBK:UTF-8:GB18030<br />
<br />
For Beep media player, you can select MPEG Audio plugin in {{ic|pefenrence->plugins->media}}, and then click Penfenrences below. A dialog box will appear. Select title, tick {{ic|Disable ID3v2 and Convert non-UTF8 ID3 tags to UTF8}}. Fill in {{ic|gbk}} in ID3 encoding. Now, BMP can correctly display the GB3 encoded ID3 tag.<br />
<br />
Quod Libet player supports tag editing and setting ID3v2 encoding. This can be set in {{ic|~/.quodlibet/config}}:<br />
<br />
{{hc|~/.quodlibet/config|2=<br />
...<br />
id3encoding = gbk<br />
...<br />
}}<br />
<br />
{{Note|Quod Libet supports utf8 encoding by default.}}<br />
<br />
The best solution is to convert the id3 tag encoded as gbk to utf8 encoding. Install {{Pkg|python-mutagen}}, then use the following command to convert:<br />
<br />
$ mid3iconv -e gbk XXX.mp3<br />
<br />
=== Garbled Chinese file name under Windows partition ===<br />
<br />
Generally, the mounted character set is different from the locales. You can modify {{ic|/etc/fstab}} (if you do not understand, please read [[fstab]] carefully). If the locale is utf8, modify the line to:<br />
<br />
{{hc|/etc/fstab|2=<br />
...<br />
/dev/sdxx /media/win ntfs defaults,iocharset=utf8 0 0<br />
}}<br />
<br />
If the locale is GBK, it should be:<br />
<br />
{{hc|/etc/fstab|2=<br />
...<br />
/dev/sdxx /media/win ntfs defaults,iocharset=cp936 0 0<br />
...<br />
}}<br />
<br />
=== Samba garbled ===<br />
<br />
When using Arch as a [[Samba]] server, adding the following line to {{ic|/etc/samba/smb.conf}} can solve the garbled problem of Windows clients:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
unix charset=gb2312<br />
...<br />
}}<br />
<br />
=== ftp garbled ===<br />
<br />
Many ftp sites are GBK encoded. If you use UTF8 locale, the downloaded file name may be garbled. For lftp, make the following settings under {{ic|.lftp/rc}}:<br />
<br />
{{hc|.lftp/rc|<br />
...<br />
set ftp:charset "gbk"<br />
set file:charset "UTF-8"<br />
...<br />
}}<br />
<br />
For gftp, you can do the following settings in {{ic|.gftp/gftprc}}:<br />
<br />
{{hc|.gftp/gftprc|2=<br />
...<br />
remote_charsets=gb2312<br />
...<br />
}}<br />
<br />
However, the downloaded file name is still garbled and needs to be patched and compiled. The patch address is: https://www.teatime.com.tw/%7Etommy/linux/gftp_remote_charsets.patch<br />
<br />
== Translation software ==<br />
<br />
* {{Pkg|stardict}}: StarDict.<br />
* {{Pkg|sdcv}}: command line StarDict.<br />
* {{Pkg|ydcv}}: Youdao dictionary on the command line.<br />
* {{AUR|youdao-dict}}: Youdao dictionary (graphic interface), screen word translation.<br />
* {{Pkg|goldendict}}: There is no dictionary by default, you can download the corresponding dictionary package (supports Babylon's thesaurus format {{ic|.BGL}}, StarDict no longer maintained thesaurus format ({{ic|.ifo}}/{{ic|.dict}}/{{ic|.idx}}/{{ic|.syn}}), [[dictd]] words Library format ({{ic|.index}}/{{ic|.dict}}({{ic|.dz}}), ABBYY Lingvo's thesaurus format ({{ic|.dsl}}/{{ic|.lsa}}/{{ic|.dat}}), mdict's thesaurus format, etc. The thesaurus files of these dictionaries can be downloaded and imported on the Internet Use of [[GoldenDict]] (may have copyright issues).<br />
* {{AUR|moedict}}: A multi-platform Chinese dictionary. In addition to Chinese characters, words, idioms, etc., it also contains Hakka, Hokkien, simple foreign language translations, stroke order writing, etc. [https://www.moedict.tw/%E8%90%8C moedict online address]<br />
* {{AUR|linedict}}: An online English-Chinese dictionary that gets results by crawling Youdao translation webpage, some support English-Chinese translation, imitating [[dmenu]] to display the results at the top of the screen. It's rather easy to use. The API used by {{Pkg|ydcv}} has expired, and the new API is free to use the frequency limit, so {{AUR|linedict}} is a good alternative.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Localization/Simplified_Chinese&diff=698208Localization/Simplified Chinese2021-10-03T13:39:21Z<p>Hexhu: /* Enable Chinese locales */ less confusing wording</p>
<hr />
<div>[[Category:Localization]]<br />
[[zh-hans:Localization (简体中文)/Simplified Chinese]]<br />
{{Related articles start}}<br />
{{Related|Localization/Chinese}}<br />
{{Related|Localization (正體中文)/Traditional Chinese (正體中文)}}<br />
{{Related|Installation guide}}<br />
{{Related|General recommendations}}<br />
{{Related articles end}}<br />
<br />
According to "[[The Arch Way]]": We cannot configure everything for you, because "Preferences and needs are different for everyone", but we will try to ensure the configuration to be convenient and simple. In fact, it is even easier than some Chinese versions of Linux.<br />
<br />
This article provides Chinese cultural guidance for various common software as much as possible. But in practical applications, you may encounter all kinds of issues. Do not be discouraged when you are in trouble. Solving problems is a pleasure in itself. You can seek help through various platforms:<br />
<br />
* [https://www.google.com/ncr Google] and other search engines<br />
* [https://bbs.archlinux.org/ Arch official forum]<br />
* [https://forum.ubuntu.org.cn/viewforum.php?f=155 Ubuntu Chinese Forum Arch area]<br />
* [ircs://irc.libera.chat/archlinux-cn IRC channel: #archlinux-cn]<br />
<br />
== Basic Chinese support ==<br />
<br />
To properly display Chinese, you must set the locale correctly and install the appropriate Chinese fonts.<br />
<br />
=== locale settings ===<br />
<br />
==== Install Chinese locale ====<br />
<br />
In Linux, locales are used to set up different environments for running programs. Commonly used Chinese locales are (the most intuitive is the number of words that can be displayed):<br />
<br />
zh_CN.GB2312<br />
zh_CN.GBK<br />
zh_CN.GB18030<br />
zh_CN.UTF-8<br />
zh_TW.BIG-5<br />
zh_TW.UTF-8<br />
<br />
It is recommended to use UTF-8 locale. You need to modify {{ic|/etc/locale.gen}} to set the locales that can be used in the system (erase the comment symbol "{{ic|#}}" before the corresponding item):<br />
<br />
en_US.UTF-8 UTF-8<br />
zh_CN.UTF-8 UTF-8<br />
<br />
After executing {{ic|locale-gen}}, the selected locales can be used in the system. You may use {{ic|locale}} to view the currently used locale(s), and {{ic|locale -a}} to view the currently available locales.<br />
<br />
==== Enable Chinese locales ====<br />
<br />
{{Warning|Globally setting Chinese locales in {{ic|/etc/locale.conf}} will cause tty to display garbled texts due to the [https://unix.stackexchange.com/questions/273061/273063#273063 tty glyph limitation of Linux kernel]. To properly display Chinese characters under tty, install and [http://zhcon.sourceforge.net/faq.html#faq1 configure] {{AUR|zhcon}}.}}<br />
<br />
===== Set the global default locale to English (optional) =====<br />
<br />
To avoid the tty garbled text issue mentioned above, globally set the [[Locale#LANG:_default_locale|LANG locale]] to {{ic|en_US.UTF-8}} in {{ic|/etc/locale.conf}}:<br />
<br />
LANG=en_US.UTF-8<br />
<br />
===== User-specific locales =====<br />
<br />
You may set your own user environment variables in {{ic|~/.bashrc}}, {{ic|~/.xinitrc}}, or {{ic|~/.xprofile}}.<br />
<br />
* {{ic|.bashrc}}: Settings are applied everytime you log in '''using the terminal'''.<br />
* {{ic|.xinitrc}}: Settings are applied everytime you '''use [[startx]] or [[SLiM]] to start the [[X]] interface'''.<br />
* {{ic|.xprofile}}: Settings are applied everytime you '''log in using a display manager such as [[GDM]]'''.<br />
<br />
===== Set Chinese locales for graphical interfaces =====<br />
<br />
It is not recommended to set a global Chinese locale in {{ic|/etc/locale.conf}} because it causes tty to display garbled characters.<br />
<br />
As mentioned earlier, Chinese locale can be set separately in {{ic|~/.xinitrc}} or {{ic|~/.xprofile}}. Prepend the following two lines to one of the two files (if you are not sure which file to use, prepend to both):<br />
<br />
export LANG=zh_CN.UTF-8<br />
export LANGUAGE=zh_CN:en_US<br />
<br />
{{Warning|Be sure to put them '''before''' the {{ic|exec ''_example_WM_or_DE_''}} line in {{ic|~/.xinitrc}}.}}<br />
<br />
{{Note|This method is suitable for [[SLiM]] users or for people who don't use a graphical login interface (aka greeter). [[GDM]] and [[SDDM]] users can configure the display language in [[GNOME]] or [[KDE]] settings.}}<br />
<br />
{{Note|It is not recommended to override all locale settings with a global {{ic|export LC_ALL}}. {{ic|LC_ALL}} should be reserved for diagnostic debugging purposes only. {{ic|LC_ALL}} will bring unnecessary difficulties for diagnosing language settings issues.}}<br />
<br />
=== Chinese fonts ===<br />
<br />
==== Install fonts ====<br />
<br />
In addition to locales, Chinese fonts are also required.<br />
<br />
Commonly used free (GPL or compatible copyright) Chinese fonts include:<br />
<br />
* {{Pkg|wqy-microhei}}<br />
* {{Pkg|wqy-microhei-lite}}<br />
* {{Pkg|wqy-bitmapfont}}<br />
* {{Pkg|wqy-zenhei}}<br />
* {{Pkg|ttf-arphic-ukai}}<br />
* {{Pkg|ttf-arphic-uming}}<br />
* {{Pkg|adobe-source-han-sans-cn-fonts}}<br />
* {{Pkg|adobe-source-han-serif-cn-fonts}}<br />
* {{Pkg|noto-fonts-cjk}}<br />
<br />
{{Out of date|The {{ic|~/.fonts}} path is deprecated. It may be preferable to link to [[Fonts#Manual installation]] instead of duplicating information regarding font paths here.}}<br />
<br />
System fonts will be installed to {{ic|/usr/share/fonts}} by default. If you do not have root authority or plan to use certain fonts yourself, you can directly copy these fonts to {{ic|~/.fonts}} (or its subdirectories) and add the path to {{ic|/etc/fonts/local.conf}}. For details, go over the following chapters.<br />
<br />
See also: [http://wiki.debian.org.hk/w/Where_can_I_find_fonts_for_GNU/Linux]<br />
<br />
==== Chinese fonts configuration ====<br />
<br />
===== fontconfig settings =====<br />
<br />
{{Out of date|The {{ic|~/.fonts.conf}} path appears to be deprecated. It may be preferable to link to [[Font configuration#Fontconfig configuration]] or [[Font configuration (简体中文)#Fontconfig配置]] instead of explicitly mentioning font configuration paths.}}<br />
<br />
The setting file of fontconfig is {{ic|~/.fonts.conf}} (user) or {{ic|/etc/fonts/conf.d}} (global). It is recommended to modify the former.<br />
<br />
For Chinese fonts settings, see [[Fonts (简体中文)]] and [[Font configuration (简体中文)]].<br />
<br />
[[Font Configuration (简体中文)/Chinese (简体中文)]] provides a demonstration of Chinese fontconfig.<br />
<br />
See also:<br />
<br />
* [http://www.chinalinuxpub.com/read.php?wid=634 fontconfig 用户手册]<br />
* [http://wiki.linux.org.hk/w/Make_Debian_support_Chinese Debian 中文支持]<br />
* [https://web.archive.org/web/20070219091008/http://www.higherorder.org/wiki/Fontconfig Fontconfig wiki page]<br />
<br />
===== Fixed Simplified Chinese display as a variant (Japanese) glyph =====<br />
<br />
After installing Noto Sans CJK, {{Pkg|adobe-source-han-sans-otc-fonts}} (Siyuan Bold) or {{Pkg|adobe-source-han-serif-otc-fonts}} (Siyuan Song), in some cases (framework undefined area), rendered Chinese characters do not match the standard form, such as 门, 关, and 复.<br />
<br />
This is because different default fonts can be set in each program, such as Arial or Tohamo, and the attributes of these fonts are controlled by [[fontconfig (简体中文)|fontconfig]]. The order of use is based on the regional code and the default order of A-Z. Since {{ic|ja-JP}} is before {{ic|zh_{CN,HK,SG,TW}<nowiki/>}}, Japanese fonts are used first.<br />
<br />
{{Tip|Fonts can be set separately in Chromium/Chrome/Firefox browser settings, for example, adjust the font option to Noto xxx CJK SC.}}<br />
<br />
You can use the following methods to solve the issue (taking simplified Chinese as an example):<br />
<br />
* Only install Simplified Chinese fonts in cjk, such as Siyuan Bold Simplified Chinese package {{Pkg|adobe-source-han-sans-cn-fonts}}, {{Pkg|adobe-source-han-serif-cn-fonts}} or {{AUR|noto-fonts-sc}}.<br />
* Add {{ic|1=LANG=zh_CN.UTF-8}} to {{ic|locale.conf}} to set Simplified Chinese as the default language. Since the [[Locale]] is defined for CJK priority, the default priority is ignored.<br />
* Manually adjust the priority so that the Chinese fonts are set before the Japanese fonts. [https://tieba.baidu.com/p/4879946717]:<br />
<br />
Create a file under {{ic|/etc/fonts/conf.d/}} or {{ic|/etc/fonts/conf.avail/}}, such as {{ic|64-language-selector-prefer.conf}}, or modify or create {{ic|~/.fonts.conf}} (only effective for the user):<br />
<br />
If {{Pkg|noto-fonts-cjk}} is installed, write:<br />
<br />
{{bc|1=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>Noto Sans CJK SC</family><br />
<family>Noto Sans CJK TC</family><br />
<family>Noto Sans CJK JP</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the priority of sans serif font--><br />
<alias><br />
<family>monospace</family><br />
<prefer><br />
<family>Noto Sans Mono CJK SC</family><br />
<family>Noto Sans Mono CJK TC</family><br />
<family>Noto Sans Mono CJK JP</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the monospace font priority--><br />
</fontconfig><br />
}}<br />
<br />
If you have installed {{Pkg|adobe-source-han-sans-otc-fonts}}:<br />
<br />
{{bc|1=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>Source Han Sans SC</family><br />
<family>Source Han Sans TC</family><br />
<family>Source Han Sans HW</family><br />
<family>Source Han Sans K</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the priority of sans serif font--><br />
<alias><br />
<family>monospace</family><br />
<prefer><br />
<family>Source Han Sans SC</family><br />
<family>Source Han Sans TC</family><br />
<family>Source Han Sans HW</family><br />
<family>Source Han Sans K</family><br />
</prefer><br />
</alias><br />
<!--The above is to set the monospace font priority--><br />
</fontconfig><br />
}}<br />
<br />
Note that if you create an xml file under {{ic|/etc/fonts/conf.avail}}, for example:<br />
<br />
# ln -s /etc/fonts/conf.avail/64-language-selector-prefer.conf /etc/fonts/conf.d/64-language-selector-prefer.conf<br />
<br />
you have to update the font cache to take effect:<br />
<br />
# fc-cache -fv<br />
<br />
Execute the following command to check. If {{ic|NotoSansCJK-Regular.ttc: "Noto Sans CJK SC" "Regular"}} appears, the settings are successfully applied:<br />
<br />
# fc-match -s | grep 'Noto Sans CJK'<br />
<br />
=== Chinese input method ===<br />
<br />
Commonly used Chinese input method frameworks are [[IBus]], [[fcitx]] and [[scim]]. For specific installation and configuration, please refer to the respective articles.<br />
<br />
{{Note|SCIM current lacks maintenance and is therefore not recommended.}}<br />
<br />
== Terminal Chinese support ==<br />
<br />
=== Bootloader Chinese support ===<br />
<br />
See [[GRUB2 (简体中文)]].<br />
<br />
== Cultural configuration in software ==<br />
<br />
=== Firefox ===<br />
<br />
Simplified Chinese installation: {{Pkg|firefox-i18n-zh-cn}}。<br />
<br />
Traditional Chinese installation: {{Pkg|firefox-i18n-zh-tw}}。<br />
<br />
=== Libreoffice ===<br />
<br />
Simplified Chinese installation: {{Pkg|libreoffice-fresh-zh-cn}} or {{Pkg|libreoffice-still-zh-cn}}.<br />
<br />
Traditional Chinese installation: {{Pkg|libreoffice-fresh-zh-tw}} or {{Pkg|libreoffice-still-zh-cn}}.<br />
<br />
=== PDF reader ===<br />
<br />
Most PDF viewers already support Chinese. However, there are some additional language packs/fonts that need to be installed:<br />
<br />
Arcobat's fonts are {{AUR|acroread-fonts}}, or {{AUR|acroread-fonts-systemwide}} for system-wide fonts.<br />
<br />
For {{Pkg|poppler}}-based readers (e.g., {{Pkg|okular}}, [[Evince]]) and image processing tools that can handle PDF files (e.g., [[Inkscape]], {{Pkg|krita}}, {{Pkg|mypaint}}), {{Pkg|poppler-data}} needs to be installed.<br />
<br />
=== Java ===<br />
<br />
For Sun [[Java]] users, create a {{ic|fallback}} directory under {{ic|/opt/java/jre/lib/fonts}}, then link or copy several Chinese fonts to the directory to allow java programs to display Chinese correctly. For example, if {{AUR|jre}} and {{Pkg|opendesktop-fonts}} have been installed, use the following command:<br />
<br />
# ln -s /usr/share/fonts/TTF/odosung.ttc /opt/java/jre/lib/fonts/fallback/<br />
# cd /opt/java/jre/lib/fonts/fallback/<br />
# mkfontdir<br />
# mkfontscale<br />
<br />
=== vim ===<br />
<br />
If the locale is utf8-encoded, using [[vim]] to open other Chinese encoded files may be garbled. The following settings need to be made in {{ic|~/.vimrc}}:<br />
<br />
{{hc|~/.vimrc|2=<br />
...<br />
set fileencodings=utf8,cp936,gb18030,big5<br />
...<br />
}}<br />
<br />
=== Chinese video subtitles ===<br />
<br />
==== MPlayer ====<br />
<br />
To allow [[MPlayer]] to display Chinese subtitles correctly, the key is to make sure the encoding of the subtitle file is consistent with the encoding used in mplayer's configurations. If the subtitle file is encoded as gbk, use {{ic|1=subcp=cp936}}; If the subtitle file is encoded as utf-8, use {{ic|1=subcp=utf8}}. If the subtitle file is encoded as utf-8 and set to {{ic|1=subcp=cp936}}, some garbled characters will appear. Another simpler method is to set to {{ic|1=subcp=enca:zh:ucs-2}}, so that enca is responsible for the encoding and display of subtitles.<br />
<br />
Modify {{ic|~/.mplayer/config}}:<br />
<br />
{{hc|~/.mplayer/config|2=<br />
font='文泉驿正黑'<br />
subcp=enca:zh:ucs-2<br />
}}<br />
<br />
Use the following command to manually load subtitles:<br />
<br />
$ mplayer xxx.avi -sub xxxxx.srt<br />
<br />
If a graphical front end (such as [[SMPlayer]]) is used, it will work as long as you set the default subtitle encoding and font in the settings dialog box.<br />
<br />
==== xine ====<br />
<br />
Xine can also display Chinese subtitles, but you need to make your own Chinese fonts. For details, please refer to [https://forum.ubuntu.org.cn/about2760.html].<br />
<br />
==== gstreamer ====<br />
<br />
In totem 1.4.0, since gstreamer0.10 is used, it should be able to automatically load srt subtitles with the same name.<br />
<br />
=== LaTeX ===<br />
<br />
You need to install CJK packages and the appropriate fonts. For details, please refer to [http://www.ctex.org].<br />
<br />
== Garbled problem ==<br />
<br />
The basic principle to avoid garbled characters is to use utf-8 instead of gbk/gb2312.<br />
<br />
=== File name is garbled ===<br />
<br />
Install {{Pkg|convmv}} and use the {{ic|convmv}} command to convert the encoding format. For example:<br />
<br />
$ convmv -f GBK -t UTF-8 --notest --nosmart file<br />
<br />
{{ic|-f}} specifies the original encoding, and {{ic|-t}} specifies the output encoding. Use {{ic|convmv --list}} to find out all the supported encodings.<br />
{{ic|--notest}} means not to test but to transcode (if you do not use this parameter, the conversion result will be printed instead of actual transcoding), {{ic|--smart}} allows {{ic|convmv}} to ignore the request if it is already in UTF-8.<br />
<br />
=== File content is garbled ===<br />
<br />
Use the {{ic|iconv}} command to convert the format. For example:<br />
<br />
$ iconv -f GBK -t UTF-8 -o new-file origin-file<br />
<br />
{{ic|-f}} specifies the original encoding, and {{ic|-t}} specifies the output encoding. Use {{ic|iconv -l}} to query all supported encodings. {{ic|-o}} specifies the output file.<br />
<br />
=== zip compressed package is garbled ===<br />
<br />
Under non-utf8 coding environment (generally the Chinese environment under Windows), do not use zip for compressions ([[7z]] is recommended). Install and use {{AUR|unzip-iconv}} or {{AUR|unzip-natspec}} instead of the original {{Pkg|unzip}} program to decompress. For example:<br />
<br />
$ unzip -O gbk file.zip<br />
<br />
{{ic|file.zip}} is the compressed file, {{ic|gbk}} is the encoding format of the file, specified with {{ic|-O}} (the original unzip command has no {{ic|-O}} option).<br />
<br />
=== MP3 file label garbled ===<br />
<br />
For players that use [[GStreamer]] as the backend, such as [[Rhythmbox]] and totem, after setting the following environment variables, the GB3 encoded ID3 tag in mp3 can be read correctly:<br />
<br />
export GST_ID3_TAG_ENCODING=GBK:UTF-8:GB18030<br />
export GST_ID3V2_TAG_ENCODING=GBK:UTF-8:GB18030<br />
<br />
For Beep media player, you can select MPEG Audio plugin in {{ic|pefenrence->plugins->media}}, and then click Penfenrences below. A dialog box will appear. Select title, tick {{ic|Disable ID3v2 and Convert non-UTF8 ID3 tags to UTF8}}. Fill in {{ic|gbk}} in ID3 encoding. Now, BMP can correctly display the GB3 encoded ID3 tag.<br />
<br />
Quod Libet player supports tag editing and setting ID3v2 encoding. This can be set in {{ic|~/.quodlibet/config}}:<br />
<br />
{{hc|~/.quodlibet/config|2=<br />
...<br />
id3encoding = gbk<br />
...<br />
}}<br />
<br />
{{Note|Quod Libet supports utf8 encoding by default.}}<br />
<br />
The best solution is to convert the id3 tag encoded as gbk to utf8 encoding. Install {{Pkg|python-mutagen}}, then use the following command to convert:<br />
<br />
$ mid3iconv -e gbk XXX.mp3<br />
<br />
=== Garbled Chinese file name under Windows partition ===<br />
<br />
Generally, the mounted character set is different from the locales. You can modify {{ic|/etc/fstab}} (if you do not understand, please read [[fstab]] carefully). If the locale is utf8, modify the line to:<br />
<br />
{{hc|/etc/fstab|2=<br />
...<br />
/dev/sdxx /media/win ntfs defaults,iocharset=utf8 0 0<br />
}}<br />
<br />
If the locale is GBK, it should be:<br />
<br />
{{hc|/etc/fstab|2=<br />
...<br />
/dev/sdxx /media/win ntfs defaults,iocharset=cp936 0 0<br />
...<br />
}}<br />
<br />
=== Samba garbled ===<br />
<br />
When using Arch as a [[Samba]] server, adding the following line to {{ic|/etc/samba/smb.conf}} can solve the garbled problem of Windows clients:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
unix charset=gb2312<br />
...<br />
}}<br />
<br />
=== ftp garbled ===<br />
<br />
Many ftp sites are GBK encoded. If you use UTF8 locale, the downloaded file name may be garbled. For lftp, make the following settings under {{ic|.lftp/rc}}:<br />
<br />
{{hc|.lftp/rc|<br />
...<br />
set ftp:charset "gbk"<br />
set file:charset "UTF-8"<br />
...<br />
}}<br />
<br />
For gftp, you can do the following settings in {{ic|.gftp/gftprc}}:<br />
<br />
{{hc|.gftp/gftprc|2=<br />
...<br />
remote_charsets=gb2312<br />
...<br />
}}<br />
<br />
However, the downloaded file name is still garbled and needs to be patched and compiled. The patch address is: https://www.teatime.com.tw/%7Etommy/linux/gftp_remote_charsets.patch<br />
<br />
== Translation software ==<br />
<br />
* {{Pkg|stardict}}: StarDict.<br />
* {{Pkg|sdcv}}: command line StarDict.<br />
* {{Pkg|ydcv}}: Youdao dictionary on the command line.<br />
* {{AUR|youdao-dict}}: Youdao dictionary (graphic interface), screen word translation.<br />
* {{Pkg|goldendict}}: There is no dictionary by default, you can download the corresponding dictionary package (supports Babylon's thesaurus format {{ic|.BGL}}, StarDict no longer maintained thesaurus format ({{ic|.ifo}}/{{ic|.dict}}/{{ic|.idx}}/{{ic|.syn}}), [[dictd]] words Library format ({{ic|.index}}/{{ic|.dict}}({{ic|.dz}}), ABBYY Lingvo's thesaurus format ({{ic|.dsl}}/{{ic|.lsa}}/{{ic|.dat}}), mdict's thesaurus format, etc. The thesaurus files of these dictionaries can be downloaded and imported on the Internet Use of [[GoldenDict]] (may have copyright issues).<br />
* {{AUR|moedict}}: A multi-platform Chinese dictionary. In addition to Chinese characters, words, idioms, etc., it also contains Hakka, Hokkien, simple foreign language translations, stroke order writing, etc. [https://www.moedict.tw/%E8%90%8C moedict online address]<br />
* {{AUR|linedict}}: An online English-Chinese dictionary that gets results by crawling Youdao translation webpage, some support English-Chinese translation, imitating [[dmenu]] to display the results at the top of the screen. It's rather easy to use. The API used by {{Pkg|ydcv}} has expired, and the new API is free to use the frequency limit, so {{AUR|linedict}} is a good alternative.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Localization_(%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87)/Simplified_Chinese_(%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87)&diff=698199Localization (简体中文)/Simplified Chinese (简体中文)2021-10-03T12:25:02Z<p>Hexhu: /* 启用中文 locale */ 改善修辞</p>
<hr />
<div>[[Category:Localization (简体中文)]]<br />
[[en:Localization/Simplified Chinese]]<br />
{{Related articles start (简体中文)}}<br />
{{Related|Localization/Chinese}}<br />
{{Related|Localization (正體中文)/Traditional Chinese (正體中文)}}<br />
{{Related|Installation guide (简体中文)}}<br />
{{Related|General recommendations (简体中文)}}<br />
{{Related articles end}}<br />
<br />
依据「[[Arch 之道]]」:我们不会为你配置好一切,因为“喜好和需求,每人皆不同”,但是会尽量确保让配置时方便和简单。事实上,甚至远比使用某些 Linux 中文版本容易。<br />
<br />
本文尽可能提供了各种常见软件的中文化指导。但实际应用中,你可能遇到各种各样的麻烦。遇到了麻烦,不要气馁,解决问题本身就是一种乐趣。你可以通过各种渠道寻求帮助:<br />
* [https://www.google.com/ncr Google] 等搜索引擎<br />
* [https://bbs.archlinux.org/ Arch 官方论坛]<br />
* [https://forum.ubuntu.org.cn/viewforum.php?f=155 Ubuntu 中文论坛 Arch 专区]<br />
* [ircs://irc.libera.chat/archlinux-cn IRC 频道:#archlinux-cn]<br />
<br />
== 基本中文支持 ==<br />
<br />
要正确显示中文,必需设置正确的 locale 并安装合适的中文字体。<br />
<br />
=== locale 设置 ===<br />
<br />
==== 安装中文 locale ====<br />
<br />
Linux 中通过 locale 来设置程序运行的不同环境。常用的中文 locale 有(最直观的分别是可显示字的数量):<br />
<br />
zh_CN.GB2312<br />
zh_CN.GBK<br />
zh_CN.GB18030<br />
zh_CN.UTF-8<br />
zh_SG.GB2312<br />
zh_SG.GBK<br />
zh_SG.GB18030<br />
zh_SG.UTF-8<br />
zh_TW.BIG-5<br />
zh_TW.UTF-8<br />
<br />
推荐使用 UTF-8 的 locale。需要修改 {{ic|/etc/locale.gen}} 文件来设定系统中可以使用的 locale(取消对应项前的注释符号「{{ic|#}}」即可):<br />
<br />
en_US.UTF-8 UTF-8<br />
zh_CN.UTF-8 UTF-8<br />
zh_SG.UTF-8 UTF-8<br />
<br />
然后执行 {{ic|locale-gen}} 命令,便可以在系统中使用这些 locale。可以通过 {{ic|locale}} 命令来查看当前使用的 locale:亦可通过 {{ic|locale -a}} 命令来查看目前可以使用的 locale。<br />
<br />
==== 配置中文 locale ====<br />
<br />
===== 配置全局 locale (可选) =====<br />
<br />
首先设置一个英文的全局 locale. 这并不是必须的,只是为了防止 tty 乱码(见下方警告):<br />
<br />
{{hc|$ cat /etc/locale.conf|<nowiki><br />
LANG=en_US.UTF-8<br />
</nowiki>}}<br />
<br />
{{ic|LANG}} 这个环境变量代表默认的区域设置,具体的含义见 [[Locale_(简体中文)#LANG:默认的区域设置|Locale_(简体中文)#LANG:默认的区域设置]]<br />
<br />
{{警告|不推荐在 {{ic|/etc/locale.conf}} 里把全局的 LANG locale 设置成中文 {{ic|1=LANG=zh_CN.UTF-8}},这会导致 tty 乱码。在 tty 下显示和输入中文需要安装 {{AUR|zhcon}} 或其他软件包。}}<br />
<br />
每个用户单独的 locale 可以在 {{ic|~/.bashrc}}、{{ic|~/.xinitrc}} 或 {{ic|~/.xprofile}} 中设置:<br />
<br />
* {{ic|.bashrc}}:每次'''使用终端时'''会应用此处的设置。<br />
* {{ic|.xinitrc}}:每次'''使用 [[startx (简体中文)|startx]] 或 [[SLiM (简体中文)|SLiM]] 来启动 [[X (简体中文)|X]] 窗口系统时'''会应用此处的设置。<br />
* {{ic|.xprofile}}:每次'''使用 [[GDM (简体中文)|GDM]] 等显示管理器时'''会应用此处的设置。<br />
<br />
===== 为图形界面配置中文 locale =====<br />
<br />
不推荐 {{ic|/etc/locale.conf}} 使用全局中文 locale,会导致 tty 乱码。<br />
<br />
如前所述,建议在 {{ic|~/.xinitrc}} 或 {{ic|~/.xprofile}} 里单独设置中文 locale,即添加下面两行到文件的最开头(如果不确定使用哪个文件,都添加):<br />
<br />
export LANG=zh_CN.UTF-8<br />
export LANGUAGE=zh_CN:en_US<br />
<br />
{{警告|若欲将此两行放至 {{ic|~/.xinitrc}} 中,请注意将其放在 {{ic|exec ''_example_WM_or_DE_''}} 行之前,此为常见错误。}}<br />
<br />
{{注意|该方法适用于 SLiM 或者无登陆管理器的用户,而 [[GDM (简体中文)|GDM]] 和 [[SDDM (简体中文)|SDDM]] 用户可以在 [[GNOME (简体中文)|GNOME]] 或 [[KDE (简体中文)|KDE]] 设置中选择语言。}}<br />
<br />
{{注意|不推荐使用 {{ic|export LC_ALL}} 来覆盖所有 locale 设置,{{ic|LC_ALL}} 应该仅用于诊断调试,全局设置 {{ic|LC_ALL}} 会为诊断语言设置问题带来不必要的困难。}}<br />
<br />
=== 中文字体 ===<br />
<br />
==== 安装字体 ====<br />
<br />
除了设置好 locale,还需要安装中文字体。<br />
<br />
常用的免费(GPL 或兼容版权)中文字体有:<br />
<br />
* {{Pkg|wqy-microhei}}<br />
* {{Pkg|wqy-microhei-lite}}<br />
* {{Pkg|wqy-bitmapfont}}<br />
* {{Pkg|wqy-zenhei}}<br />
* {{Pkg|ttf-arphic-ukai}}<br />
* {{Pkg|ttf-arphic-uming}}<br />
* {{Pkg|adobe-source-han-sans-cn-fonts}}<br />
* {{Pkg|adobe-source-han-serif-cn-fonts}}<br />
* {{Pkg|noto-fonts-cjk}}<br />
<br />
系统字体将默认安装到 {{ic|/usr/share/fonts}}。如果没有 root 权限或只打算自己使用某些字体,可以直接复制这些字体到 {{ic|~/.fonts}} 目录(或其子目录)下面,并把该路径加入 {{ic|/etc/fonts/local.conf}} 中。具体参见后面章节。<br />
<br />
另见:[http://wiki.debian.org.hk/w/Where_can_I_find_fonts_for_GNU/Linux]<br />
<br />
==== 中文字体配置 ====<br />
<br />
===== fontconfig 设置 =====<br />
<br />
fontconfig 的设置文件是 {{ic|~/.fonts.conf}}或{{ic|~/.config/fontconfig/conf.d/}}(用户)或者 {{ic|/etc/fonts/conf.d}}(全局)。推荐修改前者。<br />
<br />
关于中文字体设置,参见:[[Fonts (简体中文)]]、[[Font configuration (简体中文)]]。<br />
<br />
[[Font Configuration (简体中文)/Chinese (简体中文)]] 提供了中文字体 fontconfig 示范。<br />
<br />
另见:<br />
* [http://www.chinalinuxpub.com/read.php?wid=634 fontconfig 用户手册]<br />
* [http://wiki.linux.org.hk/w/Make_Debian_support_Chinese Debian 中文支持]<br />
* [http://www.higherorder.org/wiki/Fontconfig]<br />
<br />
===== 修正简体中文显示为异体(日文)字形 =====<br />
<br />
安装的 Noto Sans CJK 或 {{Pkg|adobe-source-han-sans-otc-fonts}}(思源黑体)或 {{Pkg|adobe-source-han-serif-otc-fonts}}(思源宋体)后,在某些情况下(框架未定义地区)汉字字形与标准形态不符,例如门、关、复等字字形与规范中文不符。<br />
<br />
这是因为每个程序中可以设置不同的默认字体,比如 Arial 或者 Tohamo,而这些字体的属性由 [[fontconfig (简体中文)|fontconfig]] 控制,其使用顺序是据地区代码以 A-Z 字母表顺序成默认排序,由于 {{ic|ja-JP}} 在 {{ic|<nowiki>zh_{CN,HK,SG,TW}</nowiki>}} 之前,故优先显示日文字形。<br />
<br />
{{提示|Chromium/Chrome/Firefox 浏览器的设置中可单独设置字体,例如将字体选项调成 Noto xxx CJK SC。}}<br />
<br />
可选用以下方法解决(以简体中文为例):<br />
* 只安装 cjk 中的简体中文字体,例如思源黑体简体中文包 {{Pkg|adobe-source-han-sans-cn-fonts}}、{{Pkg|adobe-source-han-serif-cn-fonts}} 或者 {{AUR|noto-fonts-sc}}。<br />
<br />
* 在 {{ic|locale.conf}} 中添加 {{ic|1=LANG=zh_CN.UTF-8}},以将简体中文设置为默认语言。由于对 [[Locale (简体中文)|Locale]] 定义了框架内地区(即 CJK 优先度),使得默认的优先级被忽略。<br />
<br />
* 手动调整优先级,将中文字形调整到日文字形之前。[https://tieba.baidu.com/p/4879946717]在 {{ic|/etc/fonts/conf.d/}} 或 {{ic|/etc/fonts/conf.avail/}} 下创建文件,例如 {{ic|64-language-selector-prefer.conf}},也可以修改或创建 {{ic|~/.fonts.conf}}或在{{ic|~/.config/fontconfig/conf.d/}}创建后缀为.conf的文件(仅对该用户生效)。例如针对{{Pkg|noto-fonts-cjk}}的规则,写入:<br />
<br />
{{bc|1=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>Noto Sans CJK SC</family><br />
<family>Noto Sans CJK TC</family><br />
<family>Noto Sans CJK JP</family><br />
</prefer><br />
</alias><br />
<!--以上为设置无衬线字体优先度--><br />
<alias><br />
<family>monospace</family><br />
<prefer><br />
<family>Noto Sans Mono CJK SC</family><br />
<family>Noto Sans Mono CJK TC</family><br />
<family>Noto Sans Mono CJK JP</family><br />
</prefer><br />
</alias><br />
<!--以上为设置等宽字体优先度--><br />
</fontconfig><br />
}}<br />
<br />
如果安装的是 {{Pkg|adobe-source-han-sans-otc-fonts}},写入:<br />
<br />
{{bc|1=<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<alias><br />
<family>sans-serif</family><br />
<prefer><br />
<family>Source Han Sans SC</family><br />
<family>Source Han Sans TC</family><br />
<family>Source Han Sans HW</family><br />
<family>Source Han Sans K</family><br />
</prefer><br />
</alias><br />
<!--以上为设置无衬线字体优先度--><br />
<alias><br />
<family>monospace</family><br />
<prefer><br />
<family>Source Han Sans SC</family><br />
<family>Source Han Sans TC</family><br />
<family>Source Han Sans HW</family><br />
<family>Source Han Sans K</family><br />
</prefer><br />
</alias><br />
<!--以上为设置等宽字体优先度--><br />
</fontconfig><br />
}}<br />
<br />
注意,如果你是在 {{ic|/etc/fonts/conf.avail}} 目录下创建的 xml 文件,则将该 xml 文件软链接到 {{ic|/etc/fonts/conf.d}} 下,例如:<br />
<br />
# ln -s /etc/fonts/conf.avail/64-language-selector-prefer.conf /etc/fonts/conf.d/64-language-selector-prefer.conf<br />
<br />
然后更新字体缓存即可生效:<br />
<br />
# fc-cache -fv<br />
<br />
执行以下命令检查,如果出现 {{ic|NotoSansCJK-Regular.ttc: "Noto Sans CJK SC" "Regular"}} 则表示设置成功:<br />
<br />
# fc-match -s | grep 'Noto Sans CJK'<br />
<br />
=== 中文输入法 ===<br />
<br />
常用的中文输入法平台有 [[IBus (简体中文)|IBus]]、[[Fcitx (简体中文)|fcitx]]、[[Fcitx5 (简体中文)|fcitx5]] 和 [[Smart Common Input Method platform (简体中文)|scim]]。具体安装配置参见各自条目。<br />
<br />
{{注意|scim 现在维护滞后,不推荐使用。fcitx 目前有新版本 fcitx5,且两者不兼容,推荐使用 fcitx5。}}<br />
<br />
== 终端中文支持 ==<br />
<br />
=== 引导中文支持 ===<br />
<br />
请见 [[GRUB2 (简体中文)]]。<br />
<br />
== 软件中文化配置 ==<br />
<br />
=== Firefox ===<br />
<br />
简体中文用户安装 {{Pkg|firefox-i18n-zh-cn}}。<br />
<br />
繁体中文用户安装 {{Pkg|firefox-i18n-zh-tw}}。<br />
<br />
=== Libreoffice ===<br />
<br />
简体中文用户安装 {{Pkg|libreoffice-fresh-zh-cn}} 或 {{Pkg|libreoffice-still-zh-cn}}。<br />
<br />
繁体中文用户安装 {{Pkg|libreoffice-fresh-zh-tw}} 或 {{Pkg|libreoffice-still-zh-cn}}。<br />
<br />
=== PDF 阅读器 ===<br />
<br />
多数 PDF 查看器已经支持中文。但也有部分需要安装额外的语言包/字体:<br />
<br />
Acrobat 的字体为 {{AUR|acroread-fonts}},或者可以安装 {{AUR|acroread-fonts-systemwide}} 以使用系统范围的字体。<br />
<br />
okular、[[evince]] 等 poppler 相关的阅读器及 [[Inkscape (简体中文)|Inkscape]]、Krita、MyPaint 等可以处理 pdf 的图像处理工具:需要安装 {{Pkg|poppler-data}}<br />
<br />
=== Java ===<br />
<br />
对于 Sun [[Java (简体中文)|Java]] 用户,在 {{ic|/opt/java/jre/lib/fonts}} 中建立 {{ic|fallback}} 目录,然后链接或拷贝若干中文字体到该目录就能使 java 程序正确显示中文。例如,在已经安装 {{AUR|jre}} 和 {{Pkg|opendesktop-fonts}} 的情况下,使用执行下面的命令即可:<br />
<br />
# ln -s /usr/share/fonts/TTF/odosung.ttc /opt/java/jre/lib/fonts/fallback/<br />
# cd /opt/java/jre/lib/fonts/fallback/<br />
# mkfontdir<br />
# mkfontscale<br />
<br />
=== vim ===<br />
<br />
如果 locale 是 utf8 编码,用 [[vim (简体中文)|vim]] 打开其他中文编码的文件可能会乱码。需要在 {{ic|~/.vimrc}} 做如下设置:<br />
<br />
{{hc|~/.vimrc|2=<br />
...<br />
set fileencodings=utf8,cp936,gb18030,big5<br />
...<br />
}}<br />
<br />
=== 中文视频字幕 ===<br />
<br />
==== MPlayer ====<br />
<br />
要使 [[MPlayer (简体中文)|MPlayer]] 正确显示字幕,关键是要使字幕文件的编码和 mplayer config 里使用的编码相一致。字幕文件编码为 gbk,则 {{ic|1=subcp=cp936}};字幕文件编码为 utf-8,则 {{ic|1=subcp=utf8}}。如果字幕文件编码为 utf-8,而设置成 {{ic|1=subcp=cp936}},则会出现部分乱码的情况。另一种更为简单的方法是设置成 {{ic|1=subcp=enca:zh:ucs-2}},由 enca 负责字幕的编码显示问题。<br />
<br />
修改 {{ic|~/.mplayer/config}}:<br />
<br />
{{hc|~/.mplayer/config|2=<br />
font='文泉驿正黑'<br />
subcp=enca:zh:ucs-2<br />
}}<br />
<br />
使用下面的命令手动加载字幕:<br />
<br />
$ mplayer xxx.avi -sub xxxxx.srt<br />
<br />
如果使用图形前端(比如 [[SMPlayer]]),会更简单一些,只要在设置对话框里设定缺省字幕编码和字体即可。<br />
<br />
==== xine ====<br />
<br />
xine 也可以显示中文字幕,但需要制作自己的中文字体。具体可以参考:[https://forum.ubuntu.org.cn/about2760.html]。<br />
<br />
==== gstreamer ====<br />
<br />
在 totem 1.4.0,由于使用 gstreamer0.10,应该是可以自动加载同名的 srt 字幕。<br />
<br />
=== LaTeX ===<br />
<br />
首先需要安装 CJK 包,然后需要安装合适的字体。具体可以参考:[http://www.ctex.org]。<br />
<br />
== 乱码问题 ==<br />
<br />
避免乱码基本原则:使用 utf-8 代替 gbk/gb2312。<br />
<br />
=== 文件名乱码 ===<br />
<br />
安装 {{Pkg|convmv}},使用 {{ic|convmv}} 命令转换编码格式。示例:<br />
<br />
$ convmv -f GBK -t UTF-8 --notest --nosmart file<br />
<br />
{{ic|-f}} 指定原始编码,{{ic|-t}} 指定输出编码。使用 {{ic|convmv --list}} 可查询所有支持的编码。<br />
{{ic|--notest}} 表示非测试而是要进行转码(如果不使用该参数只会打印出转换结果而不会实际转码),{{ic|--smart}} 表示如果已经是 UTF-8 则忽略。<br />
<br />
=== 文件内容乱码 ===<br />
<br />
使用 {{ic|iconv}} 命令转换格式。示例:<br />
<br />
$ iconv -f GBK -t UTF-8 -o new-file origin-file<br />
<br />
{{ic|-f}} 指定原始编码,{{ic|-t}} 指定输出编码。使用 {{ic|iconv -l}} 可查询所有支持的编码。{{ic|-o}} 指定输出文件。<br />
<br />
=== zip 压缩包乱码 ===<br />
<br />
避免方法:非 utf8 编码环境下(一般 windows 下的中文环境即是)不使用 zip 进行压缩(建议使用 [[7z (简体中文)|7z]])。<br />
解决方案:安装使用 {{AUR|unzip-iconv}} 或者 {{AUR|unzip-natspec}} 取代原版的 {{Pkg|unzip}} 来解压缩,示例:<br />
<br />
$ unzip -O gbk file.zip<br />
<br />
{{ic|file.zip}} 是压缩文件,{{ic|gbk}} 是该文件的编码格式,以 {{ic|-O}} 指定(原版 unzip 无 {{ic|-O}} 选项)。<br />
<br />
=== MP3 文件标签乱码 ===<br />
<br />
对于用 [[GStreamer (简体中文)|GStreamer]] 做后端的播放器,如 [[Rhythmbox]],totem,设置如下的环境变量后即可正确读取 mp3 中 GBK 编码的 ID3 tag:<br />
<br />
export GST_ID3_TAG_ENCODING=GBK:UTF-8:GB18030<br />
export GST_ID3V2_TAG_ENCODING=GBK:UTF-8:GB18030<br />
<br />
对于 Beep media player,可以在 {{ic|pefenrence->plugins->media}} 中选中 MPEG Audio plugin 然后点击下方的 Penfenrences,此时会出现一个对话框,选择 title,将 Disable ID3v2 和 Convert non-UTF8 ID3 tags to UTF8 前的选择框选中。然后在 ID3 encoding 中填入 {{ic|gbk}}。这样 bmp 就能正确显示 GBK 编码的 ID3 tag。<br />
<br />
Quod Libet 播放器支持 tag 编辑及设置 ID3v2 编码。可以在 {{ic|~/.quodlibet/config}} 中设置<br />
<br />
{{hc|~/.quodlibet/config|2=<br />
...<br />
id3encoding = gbk<br />
...<br />
}}<br />
<br />
{{注意|Quod Libet 默认支持 utf8 编码。}}<br />
<br />
最为彻底的解决方法为将编码为 gbk 的 id3 tag 转化为 utf8 编码。首先安装 {{Pkg|python-mutagen}},然后利用下面的命令转换:<br />
<br />
$ mid3iconv -e gbk XXX.mp3<br />
<br />
=== Windows 分区下的中文文件名乱码 ===<br />
<br />
一般是因为挂载的字符集与 locale 不同,可以修改 {{ic|/etc/fstab}}(如果不了解请仔细阅读 [[fstab (简体中文)]])。如果 locale 是 utf8,修改为:<br />
<br />
{{hc|/etc/fstab|2=<br />
...<br />
/dev/sdxx /media/win ntfs defaults,iocharset=utf8 0 0<br />
}}<br />
<br />
如果 locale 是 GBK,则应该是:<br />
<br />
{{hc|/etc/fstab|2=<br />
...<br />
/dev/sdxx /media/win ntfs defaults,iocharset=cp936 0 0<br />
...<br />
}}<br />
<br />
=== Samba 乱码 ===<br />
<br />
用 Arch 作为 [[Samba (简体中文)|Samba]] 服务器时,在 {{ic|/etc/samba/smb.conf}} 中加入下面一行就可以解决 Windows 客户端乱码问题:<br />
<br />
{{hc|/etc/samba/smb.conf|2=<br />
...<br />
unix charset=gb2312<br />
...<br />
}}<br />
<br />
=== ftp 乱码 ===<br />
<br />
很多 ftp 站点是 GBK 编码。如果使用 UTF8 的 locale,下载的文件名可能会乱码。对于 lftp,在 {{ic|.lftp/rc}} 下做如下设置:<br />
<br />
{{hc|.lftp/rc|<br />
...<br />
set ftp:charset "gbk"<br />
set file:charset "UTF-8"<br />
...<br />
}}<br />
<br />
对于 gftp,可以在 {{ic|.gftp/gftprc}} 中做如下设置即可:<br />
<br />
{{hc|.gftp/gftprc|2=<br />
...<br />
remote_charsets=gb2312<br />
...<br />
}}<br />
<br />
但下载下来的文件名仍然是乱码,需要打补丁编译。补丁地址为: https://www.teatime.com.tw/%7Etommy/linux/gftp_remote_charsets.patch<br />
<br />
== 翻译软件 ==<br />
<br />
* {{Pkg|stardict}}:星际译王。<br />
* {{Pkg|sdcv}}:命令行的星际译王。<br />
* {{Pkg|ydcv}}:命令行的有道词典。<br />
* {{AUR|youdao-dict}}:有道词典(图形界面),屏幕取词翻译。<br />
* {{Pkg|goldendict}}:默认都不带字典,可下载相应字典包(支持 Babylon 的词库格式 {{ic|.BGL}},已经不再维护的 StarDict 的词库格式({{ic|.ifo}}/{{ic|.dict}}/{{ic|.idx}}/{{ic|.syn}}),[[dictd]] 的词库格式({{ic|.index}}/{{ic|.dict}}({{ic|.dz}}) ,ABBYY Lingvo 的词库格式({{ic|.dsl}}/{{ic|.lsa}}/{{ic|.dat}}),mdict 的词库格式等等。可在互联网上下载这些词典的词库文件导入的 [[GoldenDict (简体中文)|GoldenDict]] 使用(可能有版权问题)。<br />
* {{AUR|moedict}}:一个跨多平台的汉语词典,除汉字、词、成语等,还包含客家话、闽南话、简单的外文翻译、笔顺书写等等,[https://www.moedict.tw/%E8%90%8C 萌典在线地址]。<br />
* {{AUR|linedict}}:一个通过爬取有道翻译网页得到结果的在线英汉词典,部分支持英汉翻译,模仿 [[dmenu (简体中文)|dmenu]] 在屏幕顶端显示结果,使用方便,由于 {{Pkg|ydcv}} 使用的 api 已失效,而有道新的 api 有免费使用次数限制,{{AUR|linedict}} 是一个较好的替代品。</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Limits.conf&diff=688616Limits.conf2021-07-20T01:59:45Z<p>Hexhu: /* nofile */ update recommended nofile setting for database applications</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Authentication]]<br />
[[ja:Limits.conf]]<br />
{{Move|System limits|This should cover setting limits in systemd configs as well.|section=Including systemd issues}}<br />
<br />
{{Related articles start}}<br />
{{Related|Cgroups}}<br />
{{Related|Security}}<br />
{{Related articles end}}<br />
<br />
{{ic|/etc/security/limits.conf}} allows setting resource limits for users logged in via [[PAM]]. This is a useful way of preventing, for example, [[Wikipedia:Fork_bomb|fork-bombs]] from using up all system resources. <br />
<br />
{{Note|The file does not affect system services. For [[systemd]] services the files {{ic|/etc/systemd/system.conf}}, {{ic|/etc/systemd/user.conf}}, and {{ic|/etc/systemd/system/''unit''.d/override.conf}} control the limit. See the {{man|5|systemd-system.conf}} man page for details.}}<br />
<br />
== Syntax ==<br />
<br />
The default file comes well-commented, but extra information can be gleaned by checking the {{man|5|limits.conf}} man page.<br />
<br />
== Recommendations ==<br />
<br />
=== core ===<br />
<br />
Corefiles are useful for debugging, but annoying when normally using your system. You should have a soft limit of 0 and a hard limit of unlimited, and then temporarily raise your limit for the current shell with {{ic|ulimit -c unlimited}} when you need corefiles for debugging.<br />
<br />
* soft core 0 # Prevent corefiles from being generated by default.<br />
* hard core unlimited # Allow corefiles to be temporarily enabled.<br />
<br />
=== nice ===<br />
<br />
You should disallow everyone except for root from having processes of minimal niceness (-20), so that root can fix an unresponsive system.<br />
<br />
* hard nice -19 # Prevent non-root users from running a process at minimal niceness.<br />
root hard nice -20 # Allows root to run a process at minimal niceness to fix the system when unresponsive.<br />
<br />
=== nofile ===<br />
<br />
This limits the number of file descriptors any process owned by the specified domain can have open at any one time. You may need to increase this value to something as high as {{ic|8192}} [https://appdb.winehq.org/objectManager.php?sClass=version&iId=21080&iTestingId=89787#notes for certain games to work]. Some database applications like MongoDB or Apache Kafka recommends setting nofile to {{ic|64000}} or {{ic|128000}}[https://docs.mongodb.com/manual/reference/ulimit/#recommended-ulimit-settings].<br />
<br />
* hard nofile 8192 # Required for certain games to run.<br />
<br />
=== nproc ===<br />
<br />
Having an nproc limit is important, because this will limit how many times a fork-bomb can replicate. However, having it too low can make your system unstable or even unusable, as new processes will not be able to be created.<br />
<br />
A value of {{ic|300}} is too low for even the most minimal of Window-managers to run more than a few desktop applications and daemons, but is often fine for an X-less server (in fact, {{ic|300}} is the value that the University of Georgia uses for the undergrad process limit on its Linux server).<br />
<br />
Here is an example nproc limit for all users on a system:<br />
<br />
* hard nproc 2048 # Prevent fork-bombs from taking out the system.<br />
<br />
Note that this value of {{ic|2048}} is just an example, and you may need to set yours higher. On the flipside, you also may be able to do with it being lower.<br />
<br />
Whatever you set your nproc to, make sure to allow your root user to create as many processes as it wants; else, you might make your system inoperable by setting the normal nproc limit too low. Note that this line has to come after the global hardlimit, and that the value below ({{ic|65536}}) is arbitrary.<br />
<br />
root hard nproc 65536 # Prevent root from not being able to launch enough processes<br />
<br />
=== priority ===<br />
<br />
The default niceness should generally be 0, but you can set individual users and groups to have different default priorities using this parameter.<br />
<br />
* soft priority 0 # Set the default priority to neutral niceness.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=PCI_passthrough_via_OVMF&diff=668139PCI passthrough via OVMF2021-05-07T04:25:18Z<p>Hexhu: /* Enabling IOMMU */ amd_iommu=on is never a valid kernel param option. See git blame and git history at https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/kernel-parameters.txt#L290</p>
<hr />
<div>[[Category:Virtualization]]<br />
[[ja:OVMF による PCI パススルー]]<br />
[[zh-hans:PCI passthrough via OVMF]]<br />
{{Related articles start}}<br />
{{Related|Intel GVT-g}}<br />
{{Related|PCI passthrough via OVMF/Examples}}<br />
{{Related articles end}}<br />
<br />
The Open Virtual Machine Firmware ([https://github.com/tianocore/tianocore.github.io/wiki/OVMF OVMF]) is a project to enable UEFI support for virtual machines. Starting with Linux 3.9 and recent versions of [[QEMU]], it is now possible to passthrough a graphics card, offering the VM native graphics performance which is useful for graphic-intensive tasks.<br />
<br />
Provided you have a desktop computer with a spare GPU you can dedicate to the host (be it an integrated GPU or an old OEM card, the brands do not even need to match) and that your hardware supports it (see [[#Prerequisites]]), it is possible to have a VM of any OS with its own dedicated GPU and near-native performance. For more information on techniques see the background [https://www.linux-kvm.org/images/b/b3/01x09b-VFIOandYou-small.pdf presentation (pdf)].<br />
<br />
== Prerequisites ==<br />
<br />
A VGA Passthrough relies on a number of technologies that are not ubiquitous as of today and might not be available on your hardware. You will not be able to do this on your machine unless the following requirements are met :<br />
<br />
* Your CPU must support hardware virtualization (for kvm) and IOMMU (for the passthrough itself)<br />
** [https://ark.intel.com/Search/FeatureFilter?productType=873&0_VTD=True List of compatible Intel CPUs (Intel VT-x and Intel VT-d)]<br />
** All AMD CPUs from the Bulldozer generation and up (including Zen) should be compatible.<br />
*** CPUs from the K10 generation (2007) do not have an IOMMU, so you '''need''' to have a motherboard with a [https://support.amd.com/TechDocs/43403.pdf#page=18 890FX] or [https://support.amd.com/TechDocs/48691.pdf#page=21 990FX] chipset to make it work, as those have their own IOMMU.<br />
* Your motherboard must also support IOMMU<br />
** Both the chipset and the BIOS must support it. It is not always easy to tell at a glance whether or not this is the case, but there is a fairly comprehensive list on the matter on the [https://wiki.xen.org/wiki/VTd_HowTo Xen wiki] as well as [[Wikipedia:List of IOMMU-supporting hardware]].<br />
* Your guest GPU ROM must support UEFI.<br />
** If you can find [https://www.techpowerup.com/vgabios/ any ROM in this list] that applies to your specific GPU and is said to support UEFI, you are generally in the clear. All GPUs from 2012 and later should support this, as Microsoft made UEFI a requirement for devices to be marketed as compatible with Windows 8.<br />
<br />
You will probably want to have a spare monitor or one with multiple input ports connected to different GPUs (the passthrough GPU will not display anything if there is no screen plugged in and using a VNC or Spice connection will not help your performance), as well as a mouse and a keyboard you can pass to your VM. If anything goes wrong, you will at least have a way to control your host machine this way.<br />
<br />
== Setting up IOMMU ==<br />
<br />
{{Note|<br />
* IOMMU is a generic name for Intel VT-d and AMD-Vi.<br />
* VT-d stands for ''Intel Virtualization Technology for Directed I/O'' and should not be confused with VT-x ''Intel Virtualization Technology''. VT-x allows one hardware platform to function as multiple “virtual” platforms while VT-d improves security and reliability of the systems and also improves performance of I/O devices in virtualized environments.<br />
}}<br />
<br />
Using IOMMU opens to features like PCI passthrough and memory protection from faulty or malicious devices, see [[Wikipedia:Input-output memory management unit#Advantages]] and [https://www.quora.com/Memory-Management-computer-programming/Could-you-explain-IOMMU-in-plain-English Memory Management (computer programming): Could you explain IOMMU in plain English?].<br />
<br />
=== Enabling IOMMU ===<br />
<br />
Ensure that AMD-Vi/Intel VT-d is supported by the CPU and enabled in the BIOS settings. Both normally show up alongside other CPU features (meaning they could be in an overclocking-related menu) either with their actual names ("VT-d" or "AMD-Vi") or in more ambiguous terms such as "Virtualization technology", which may or may not be explained in the manual.<br />
<br />
Manually enable IOMMU support by setting the correct [[kernel parameter]] depending on the type of CPU in use:<br />
<br />
* For Intel CPUs (VT-d) set {{ic|1=intel_iommu=on}}. Since the kernel config option CONFIG_INTEL_IOMMU_DEFAULT_ON is not set in {{Pkg|linux}}.<br />
* For AMD CPUs (AMD-Vi), it's on if kernel detects IOMMU HW support from BIOS.<br />
<br />
You should also append the {{ic|1=iommu=pt}} parameter. This will prevent Linux from touching devices which cannot be passed through.<br />
<br />
After rebooting, check [[dmesg]] to confirm that IOMMU has been correctly enabled:<br />
<br />
{{hc|# dmesg {{!}} grep -i -e DMAR -e IOMMU|<br />
[ 0.000000] ACPI: DMAR 0x00000000BDCB1CB0 0000B8 (v01 INTEL BDW 00000001 INTL 00000001)<br />
[ 0.000000] Intel-IOMMU: enabled<br />
[ 0.028879] dmar: IOMMU 0: reg_base_addr fed90000 ver 1:0 cap c0000020660462 ecap f0101a<br />
[ 0.028883] dmar: IOMMU 1: reg_base_addr fed91000 ver 1:0 cap d2008c20660462 ecap f010da<br />
[ 0.028950] IOAPIC id 8 under DRHD base 0xfed91000 IOMMU 1<br />
[ 0.536212] DMAR: No ATSR found<br />
[ 0.536229] IOMMU 0 0xfed90000: using Queued invalidation<br />
[ 0.536230] IOMMU 1 0xfed91000: using Queued invalidation<br />
[ 0.536231] IOMMU: Setting RMRR:<br />
[ 0.536241] IOMMU: Setting identity map for device 0000:00:02.0 [0xbf000000 - 0xcf1fffff]<br />
[ 0.537490] IOMMU: Setting identity map for device 0000:00:14.0 [0xbdea8000 - 0xbdeb6fff]<br />
[ 0.537512] IOMMU: Setting identity map for device 0000:00:1a.0 [0xbdea8000 - 0xbdeb6fff]<br />
[ 0.537530] IOMMU: Setting identity map for device 0000:00:1d.0 [0xbdea8000 - 0xbdeb6fff]<br />
[ 0.537543] IOMMU: Prepare 0-16MiB unity mapping for LPC<br />
[ 0.537549] IOMMU: Setting identity map for device 0000:00:1f.0 [0x0 - 0xffffff]<br />
[ 2.182790] [drm] DMAR active, disabling use of stolen memory<br />
}}<br />
<br />
=== Ensuring that the groups are valid ===<br />
<br />
The following script should allow you to see how your various PCI devices are mapped to IOMMU groups. If it does not return anything, you either have not enabled IOMMU support properly or your hardware does not support it.<br />
<br />
#!/bin/bash<br />
shopt -s nullglob<br />
for g in `find /sys/kernel/iommu_groups/* -maxdepth 0 -type d | sort -V`; do<br />
echo "IOMMU Group ${g##*/}:"<br />
for d in $g/devices/*; do<br />
echo -e "\t$(lspci -nns ${d##*/})"<br />
done;<br />
done;<br />
<br />
Example output:<br />
<br />
IOMMU Group 1:<br />
00:01.0 PCI bridge: Intel Corporation Xeon E3-1200 v2/3rd Gen Core processor PCI Express Root Port [8086:0151] (rev 09)<br />
IOMMU Group 2:<br />
00:14.0 USB controller: Intel Corporation 7 Series/C210 Series Chipset Family USB xHCI Host Controller [8086:0e31] (rev 04)<br />
IOMMU Group 4:<br />
00:1a.0 USB controller: Intel Corporation 7 Series/C210 Series Chipset Family USB Enhanced Host Controller #2 [8086:0e2d] (rev 04)<br />
IOMMU Group 10:<br />
00:1d.0 USB controller: Intel Corporation 7 Series/C210 Series Chipset Family USB Enhanced Host Controller #1 [8086:0e26] (rev 04)<br />
IOMMU Group 13:<br />
06:00.0 VGA compatible controller: NVIDIA Corporation GM204 [GeForce GTX 970] [10de:13c2] (rev a1)<br />
06:00.1 Audio device: NVIDIA Corporation GM204 High Definition Audio Controller [10de:0fbb] (rev a1)<br />
<br />
An IOMMU group is the smallest set of physical devices that can be passed to a virtual machine. For instance, in the example above, both the GPU in 06:00.0 and its audio controller in 6:00.1 belong to IOMMU group 13 and can only be passed together. The frontal USB controller, however, has its own group (group 2) which is separate from both the USB expansion controller (group 10) and the rear USB controller (group 4), meaning that [[#USB controller|any of them could be passed to a VM without affecting the others]].<br />
<br />
=== Gotchas ===<br />
<br />
==== Plugging your guest GPU in an unisolated CPU-based PCIe slot ====<br />
<br />
Not all PCI-E slots are the same. Most motherboards have PCIe slots provided by both the CPU and the PCH. Depending on your CPU, it is possible that your processor-based PCIe slot does not support isolation properly, in which case the PCI slot itself will appear to be grouped with the device that is connected to it.<br />
<br />
IOMMU Group 1:<br />
00:01.0 PCI bridge: Intel Corporation Xeon E3-1200 v2/3rd Gen Core processor PCI Express Root Port (rev 09)<br />
01:00.0 VGA compatible controller: NVIDIA Corporation GM107 [GeForce GTX 750] (rev a2)<br />
01:00.1 Audio device: NVIDIA Corporation Device 0fbc (rev a1)<br />
<br />
This is fine so long as only your guest GPU is included in here, such as above. Depending on what is plugged in to your other PCIe slots and whether they are allocated to your CPU or your PCH, you may find yourself with additional devices within the same group, which would force you to pass those as well. If you are ok with passing everything that is in there to your VM, you are free to continue. Otherwise, you will either need to try and plug your GPU in your other PCIe slots (if you have any) and see if those provide isolation from the rest or to install the ACS override patch, which comes with its own drawbacks. See [[#Bypassing the IOMMU groups (ACS override patch)]] for more information.<br />
<br />
{{Note|If they are grouped with other devices in this manner, pci root ports and bridges should neither be bound to vfio at boot, nor be added to the VM.}}<br />
<br />
== Isolating the GPU ==<br />
<br />
In order to assign a device to a virtual machine, this device and all those sharing the same IOMMU group must have their driver replaced by a stub driver or a VFIO driver in order to prevent the host machine from interacting with them. In the case of most devices, this can be done on the fly right before the VM starts.<br />
<br />
However, due to their size and complexity, GPU drivers do not tend to support dynamic rebinding very well, so you cannot just have some GPU you use on the host be transparently passed to a VM without having both drivers conflict with each other. Because of this, it is generally advised to bind those placeholder drivers manually before starting the VM, in order to stop other drivers from attempting to claim it.<br />
<br />
The following section details how to configure a GPU so those placeholder drivers are bound early during the boot process, which makes said device inactive until a VM claims it or the driver is switched back. This is the preferred method, considering it has less caveats than switching drivers once the system is fully online.<br />
<br />
{{Warning|Once you reboot after this procedure, whatever GPU you have configured will no longer be usable on the host until you reverse the manipulation. Make sure the GPU you intend to use on the host is properly configured before doing this - your motherboard should be set to display using the host GPU.}}<br />
<br />
Starting with Linux 4.1, the kernel includes vfio-pci. This is a VFIO driver, meaning it fulfills the same role as pci-stub did, but it can also control devices to an extent, such as by switching them into their D3 state when they are not in use.<br />
<br />
=== Binding vfio-pci via device ID ===<br />
<br />
Vfio-pci normally targets PCI devices by ID, meaning you only need to specify the IDs of the devices you intend to passthrough. For the following IOMMU group, you would want to bind vfio-pci with {{ic|10de:13c2}} and {{ic|10de:0fbb}}, which will be used as example values for the rest of this section.<br />
<br />
IOMMU Group 13:<br />
06:00.0 VGA compatible controller: NVIDIA Corporation GM204 [GeForce GTX 970] [10de:13c2] (rev a1)<br />
06:00.1 Audio device: NVIDIA Corporation GM204 High Definition Audio Controller [10de:0fbb] (rev a1)}}<br />
<br />
{{Note|<br />
* You cannot specify which device to isolate using vendor-device ID pairs if the host GPU and the guest GPU share the same pair (i.e : if both are the same model). If this is your case, read [[#Using identical guest and host GPUs]] instead.<br />
* If, as noted in [[#Plugging your guest GPU in an unisolated CPU-based PCIe slot]], your pci root port is part of your IOMMU group, you '''must not''' pass its ID to {{ic|vfio-pci}}, as it needs to remain attached to the host to function properly. Any other device within that group, however, should be left for {{ic|vfio-pci}} to bind with.<br />
* Binding the audio device ({{ic|10de:0fbb}} in above's example) is optional. Libvirt is able to unbind it from the {{ic|snd_hda_intel}} driver on its own.<br />
}}<br />
<br />
Two methods exist for providing the device IDs. Specifying them via [[kernel parameters]] has the advantage of being able to easily edit, remove, or undo any breaking changes via your boot loader:<br />
<br />
vfio-pci.ids=10de:13c2,10de:0fbb<br />
<br />
Alternatively, the IDs may be added to a modprobe conf file. Since these conf files are embedded in the initramfs image, any changes require regenerating a new image each time:<br />
<br />
{{hc|/etc/modprobe.d/vfio.conf|2=<br />
options vfio-pci ids=10de:13c2,10de:0fbb<br />
}}<br />
<br />
=== Loading vfio-pci early ===<br />
<br />
==== mkinitcpio ====<br />
<br />
Since Arch's {{Pkg|linux}} has vfio-pci built as a module, we need to force it to load early before the graphics drivers have a chance to bind to the card. To ensure that, add {{ic|vfio_pci}}, {{ic|vfio}}, {{ic|vfio_iommu_type1}}, and {{ic|vfio_virqfd}} to [[mkinitcpio]]:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=(... vfio_pci vfio vfio_iommu_type1 vfio_virqfd ...)<br />
}}<br />
<br />
{{Note|If you also have another driver loaded this way for [[Kernel mode setting#Early KMS start|early modesetting]] (such as {{ic|nouveau}}, {{ic|radeon}}, {{ic|amdgpu}}, {{ic|i915}}, etc.), all of the aforementioned VFIO modules must precede it.}}<br />
<br />
Also, ensure that the modconf hook is included in the HOOKS list of {{ic|mkinitcpio.conf}}:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
HOOKS=(... modconf ...)<br />
}}<br />
<br />
Since new modules have been added to the initramfs configuration, you must [[regenerate the initramfs]].<br />
<br />
==== booster ====<br />
<br />
Similar to mkinitcpio you need to specify modules to load early:<br />
{{hc|/etc/booster.yaml|2=<br />
modules_force_load: vfio_pci,vfio,vfio_iommu_type1,vfio_virqfd<br />
}}<br />
<br />
and then [[Booster#Regenerate_booster_images|regenerate the initramfs]].<br />
<br />
==== dracut ====<br />
<br />
dracut's early loading mechanism is configured via kernel parameters. To load vfio-pci early, add both the [[#Binding vfio-pci via device ID|device ids]] and the following line to your [[kernel parameters]]:<br />
<br />
rd.driver.pre=vfio_pci<br />
<br />
We also need to add all the vfio drivers to the initramfs. Add the following file to {{ic|/etc/dracut.conf.d}}:<br />
<br />
{{hc|10-vfio.conf|2=<br />
add_drivers+=" vfio_pci vfio vfio_iommu_type1 vfio_virqfd "<br />
}}<br />
<br />
As with mkinitcpio, you must regenerate the initramfs. See [[dracut]] for more details.<br />
<br />
=== Verifying that the configuration worked ===<br />
<br />
Reboot and verify that vfio-pci has loaded properly and that it is now bound to the right devices.<br />
<br />
{{hc|# dmesg {{!}} grep -i vfio|<br />
[ 0.329224] VFIO - User Level meta-driver version: 0.3<br />
[ 0.341372] vfio_pci: add [10de:13c2[ffff:ffff]] class 0x000000/00000000<br />
[ 0.354704] vfio_pci: add [10de:0fbb[ffff:ffff]] class 0x000000/00000000<br />
[ 2.061326] vfio-pci 0000:06:00.0: enabling device (0100 -> 0103)<br />
}}<br />
<br />
It is not necessary for all devices (or even expected device) from {{ic|vfio.conf}} to be in ''dmesg'' output. Sometimes a device does not appear in output at boot but actually is able to be visible and operatable in guest VM.<br />
<br />
{{hc|$ lspci -nnk -d 10de:13c2|<br />
06:00.0 VGA compatible controller: NVIDIA Corporation GM204 [GeForce GTX 970] [10de:13c2] (rev a1)<br />
Kernel driver in use: vfio-pci<br />
Kernel modules: nouveau nvidia<br />
}}<br />
<br />
{{hc|$ lspci -nnk -d 10de:0fbb|<br />
06:00.1 Audio device: NVIDIA Corporation GM204 High Definition Audio Controller [10de:0fbb] (rev a1)<br />
Kernel driver in use: vfio-pci<br />
Kernel modules: snd_hda_intel<br />
}}<br />
<br />
== Setting up an OVMF-based guest VM ==<br />
<br />
OVMF is an open-source UEFI firmware for QEMU virtual machines. While it is possible to use SeaBIOS to get similar results to an actual PCI passthrough, the setup process is different and it is generally preferable to use the EFI method if your hardware supports it.<br />
<br />
=== Configuring libvirt ===<br />
<br />
[[Libvirt]] is a wrapper for a number of virtualization utilities that greatly simplifies the configuration and deployment process of virtual machines. In the case of KVM and QEMU, the frontend it provides allows us to avoid dealing with the permissions for QEMU and make it easier to add and remove various devices on a live VM. Its status as a wrapper, however, means that it might not always support all of the latest qemu features, which could end up requiring the use of a wrapper script to provide some extra arguments to QEMU.<br />
<br />
{{Accuracy|{{Pkg|libvirt}} depends on ''ebtables'', not {{pkg|iptables-nft}} which is just a translation layer.}}<br />
<br />
Install {{Pkg|qemu}}, {{Pkg|libvirt}}, {{Pkg|edk2-ovmf}}, and {{Pkg|virt-manager}}. For the default network connection, {{pkg|iptables-nft}} and {{pkg|dnsmasq}} are required.<br />
<br />
You can now [[enable]] and [[start]] {{ic|libvirtd.service}} and its logging component {{ic|virtlogd.socket}}.<br />
<br />
You may also need to [https://wiki.libvirt.org/page/Networking#NAT_forwarding_.28aka_.22virtual_networks.22.29 activate the default libvirt network]:<br />
# virsh net-autostart default<br />
# virsh net-start default<br />
<br />
{{Note|The default libvirt network will only be listed if the virsh command is run as root.}}<br />
<br />
=== Setting up the guest OS ===<br />
<br />
The process of setting up a VM using {{ic|virt-manager}} is mostly self-explanatory, as most of the process comes with fairly comprehensive on-screen instructions.<br />
<br />
However, you should pay special attention to the following steps:<br />
<br />
* When the VM creation wizard asks you to name your VM (final step before clicking "Finish"), check the "Customize before install" checkbox.<br />
* In the "Overview" section, [https://i.imgur.com/73r2ctM.png set your firmware to "UEFI"]. If the option is grayed out, make sure that:<br />
** Your hypervisor is running as a system session and not a user session. This can be verified [https://i.ibb.co/N1XZCdp/Deepin-Screenshot-select-area-20190125113216.png by clicking, then hovering] over the session in virt-manager. If you are accidentally running it as a user session, you must open a new connection by clicking "File" > "Add Connection..", then select the option from the drop-down menu station "QEMU/KVM" and not "QEMU/KVM user session".<br />
* In the "CPUs" section, change your CPU model to "host-passthrough". If it is not in the list, you will have to either type it by hand or by using {{ic|virt-xml ''vmname'' --edit --cpu host-passthrough}}. This will ensure that your CPU is detected properly, since it causes libvirt to expose your CPU capabilities exactly as they are instead of only those it recognizes (which is the preferred default behavior to make CPU behavior easier to reproduce). Without it, some applications may complain about your CPU being of an unknown model.<br />
* If you want to minimize IO overhead, it's easier to setup [[#Virtio disk]] before installing<br />
<br />
The rest of the installation process will take place as normal using a standard QXL video adapter running in a window. At this point, there is no need to install additional drivers for the rest of the virtual devices, since most of them will be removed later on. Once the guest OS is done installing, simply turn off the virtual machine. It is possible you will be dropped into the UEFI menu instead of starting the installation upon powering your VM for the first time. Sometimes the correct ISO file was not automatically detected and you will need to manually specify the drive to boot. By typing exit and navigating to "boot manager" you will enter a menu that allows you to choose between devices.<br />
<br />
=== Attaching the PCI devices ===<br />
<br />
With the installation done, it is now possible to edit the hardware details in libvirt and remove virtual integration devices, such as the spice channel and virtual display, the QXL video adapter, the emulated mouse and keyboard and the USB tablet device. For example, remove the following sections from your XML file:<br />
<br />
{{bc|<nowiki><br />
<channel type="spicevmc"><br />
...<br />
</channel><br />
<input type="tablet" bus="usb"><br />
...<br />
</input><br />
<input type="mouse" bus="ps2"/><br />
<input type="keyboard" bus="ps2"/><br />
<graphics type="spice" autoport="yes"><br />
...<br />
</graphics><br />
<video><br />
<model type="qxl" .../><br />
...<br />
</video><br />
</nowiki>}}<br />
<br />
Since that leaves you with no input devices, you may want to bind a few USB host devices to your VM as well, but remember to '''leave at least one mouse and/or keyboard assigned to your host''' in case something goes wrong with the guest. This may be done by using {{ic|Add Hardware > USB Host Device}}.<br />
<br />
At this point, it also becomes possible to attach the PCI device that was isolated earlier; simply click on "Add Hardware" and select the PCI Host Devices you want to passthrough. If everything went well, the screen plugged into your GPU should show the OVMF splash screen and your VM should start up normally. From there, you can setup the drivers for the rest of your VM.<br />
<br />
=== Video card driver virtualisation detection ===<br />
<br />
Video card drivers by AMD incorporate very basic virtual machine detection targeting Hyper-V extensions. Should this detection mechanism trigger the drivers will refuse to run (resulting in a black screen).<br />
<br />
It is therefore required to modify the reported Hyper-V vendor ID:<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
...<br />
<features><br />
...<br />
<hyperv><br />
...<br />
<vendor_id state='on' value='randomid'/><br />
...<br />
</hyperv><br />
...<br />
</features><br />
...<br />
}}<br />
<br />
Nvidia guest drivers prior to version 465 exhibited a similar behaviour which resulted in a generic error 43 in the card's device manager status. Systems using these older drivers therefore also need the above modification. In addition, they also require hiding the KVM CPU leaf:<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
...<br />
<features><br />
...<br />
<kvm><br />
<hidden state='on'/><br />
</kvm><br />
...<br />
</features><br />
...<br />
}}<br />
<br />
Note that the above steps do not equate 'hiding' the virtual machine from Windows or any drivers/programs running in the VM. Also, various other issues not related to any detection mechanism referred to here can also trigger error 43.<br />
<br />
=== Passing keyboard/mouse via Evdev ===<br />
<br />
If you do not have a spare mouse or keyboard to dedicate to your guest, and you do not want to suffer from the video overhead of Spice, you can setup evdev to share them between your Linux host and your virtual machine.<br />
<br />
{{Note|Press both left and right '''Ctrl''' keys at the same time to swap control between the host and the guest.}}<br />
<br />
First, modify the libvirt configuration. If you encounter {{ic|failed to get domain ''vmname''}} error, add {{ic|-c qemu:///system}} arguments to {{ic|virsh}}.<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
<domain type='kvm'><br />
}}<br />
<br />
to<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
<domain type='kvm' xmlns:qemu='<nowiki>http://libvirt.org/schemas/domain/qemu/1.0</nowiki>'><br />
}}<br />
<br />
Next, find your keyboard and mouse devices in {{ic|/dev/input/by-id/}}. You may find multiple devices associated to your mouse or keyboard, so try {{ic|cat /dev/input/by-id/''device_id''}} and either hit some keys on the keyboard or wiggle your mouse to see if input comes through, if so you have got the right device. Now add those devices to your configuration right before the closing </domain> tag:<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<qemu:commandline><br />
<qemu:arg value='-object'/><br />
<qemu:arg value='input-linux,id=mouse1,evdev=/dev/input/by-id/MOUSE_NAME'/><br />
<qemu:arg value='-object'/><br />
<qemu:arg value='input-linux,id=kbd1,evdev=/dev/input/by-id/KEYBOARD_NAME,grab_all=on,repeat=on'/><br />
</qemu:commandline><br />
...<br />
</nowiki>}}<br />
<br />
Replace {{ic|MOUSE_NAME}} and {{ic|KEYBOARD_NAME}} with your device id. You will also need to include these devices in your qemu config, and setting the user and group to one that has access to your input devices:<br />
<br />
{{hc|/etc/libvirt/qemu.conf|<nowiki><br />
...<br />
user = "<some_user>"<br />
group = "kvm"<br />
...<br />
cgroup_device_acl = [<br />
"/dev/input/by-id/KEYBOARD_NAME",<br />
"/dev/input/by-id/MOUSE_NAME",<br />
"/dev/null", "/dev/full", "/dev/zero",<br />
"/dev/random", "/dev/urandom",<br />
"/dev/ptmx", "/dev/kvm", "/dev/kqemu",<br />
"/dev/rtc","/dev/hpet", "/dev/sev"<br />
]<br />
...<br />
</nowiki>}}<br />
<br />
Then ensure that the user you provided has access to the {{ic|kvm}} and {{ic|input}} [[user group]]s. [[Restart]] {{ic|libvirtd.service}}. Now you can startup the guest OS and test swapping control of your mouse and keyboard between the host and guest by pressing both the left and right control keys at the same time.<br />
<br />
You may also consider switching from PS/2 to Virtio inputs in your configurations. Add these two devices:<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<input type='mouse' bus='virtio'/><br />
<input type='keyboard' bus='virtio'/><br />
...<br />
</nowiki>}}<br />
<br />
The virtio input devices will not actually be used until the guest drivers are installed. QEMU will continue to send key events to the PS2 devices until it detects the virtio input driver initialization. Note that the PS2 devices cannot be removed as they are an internal function of the emulated Q35/440FX chipsets.<br />
<br />
=== Gotchas ===<br />
<br />
==== Using a non-EFI image on an OVMF-based VM ====<br />
<br />
The OVMF firmware does not support booting off non-EFI mediums. If the installation process drops you in a UEFI shell right after booting, you may have an invalid EFI boot media. Try using an alternate Linux/Windows image to determine if you have an invalid media.<br />
<br />
== Performance tuning ==<br />
<br />
Most use cases for PCI passthroughs relate to performance-intensive domains such as video games and GPU-accelerated tasks. While a PCI passthrough on its own is a step towards reaching native performance, there are still a few ajustments on the host and guest to get the most out of your VM.<br />
<br />
=== CPU pinning ===<br />
<br />
The default behavior for KVM guests is to run operations coming from the guest as a number of threads representing virtual processors. Those threads are managed by the Linux scheduler like any other thread and are dispatched to any available CPU cores based on niceness and priority queues. As such, the local CPU cache benefits (L1/L2) are lost each time the host scheduler reschedules the virtual CPU thread on a different physical CPU. This can noticeably harm performance on the guest. CPU pinning aims to resolve this by limiting which physical CPUs the virtual CPUs are allowed to run on. The ideal setup is a one to one mapping such that the virtual CPU cores match physical CPU cores while taking hyperthreading/SMT into account.<br />
<br />
{{Note|For certain users enabling CPU pinning may introduce stuttering and short hangs, especially with the MuQSS scheduler (present in linux-ck and linux-zen kernels). You might want to try disabling pinning first if you experience similar issues, which effectively trades maximum performance for responsiveness at all times.}}<br />
<br />
==== CPU topology ====<br />
<br />
Most modern CPUs support hardware multitasking, also known as hyper-threading on Intel CPUs or SMT on AMD CPUs. Hyper-threading/SMT is simply a very efficient way of running two threads on one CPU core at any given time. You will want to take into consideration that the CPU pinning you choose will greatly depend on what you do with your host while your VM is running.<br />
<br />
To find the topology for your CPU run {{ic|1=lscpu -e}}:<br />
<br />
{{Note|Pay special attention to the 4th column '''"CORE"''' as this shows the association of the Physical/Logical CPU cores}}<br />
<br />
{{ic|lscpu -e}} on a 6c/12t Ryzen 5 1600:<br />
<br />
CPU NODE SOCKET CORE L1d:L1i:L2:L3 ONLINE MAXMHZ MINMHZ<br />
0 0 0 0 0:0:0:0 yes 3800.0000 1550.0000<br />
1 0 0 0 0:0:0:0 yes 3800.0000 1550.0000<br />
2 0 0 1 1:1:1:0 yes 3800.0000 1550.0000<br />
3 0 0 1 1:1:1:0 yes 3800.0000 1550.0000<br />
4 0 0 2 2:2:2:0 yes 3800.0000 1550.0000<br />
5 0 0 2 2:2:2:0 yes 3800.0000 1550.0000<br />
6 0 0 3 3:3:3:1 yes 3800.0000 1550.0000<br />
7 0 0 3 3:3:3:1 yes 3800.0000 1550.0000<br />
8 0 0 4 4:4:4:1 yes 3800.0000 1550.0000<br />
9 0 0 4 4:4:4:1 yes 3800.0000 1550.0000<br />
10 0 0 5 5:5:5:1 yes 3800.0000 1550.0000<br />
11 0 0 5 5:5:5:1 yes 3800.0000 1550.0000<br />
<br />
{{Note|Ryzen 3000 ComboPi AGESA changes topology to match Intel example, even on prior generation CPUs. Above valid only on older AGESA. }}<br />
<br />
{{ic|lscpu -e}} on a 6c/12t Intel 8700k:<br />
<br />
CPU NODE SOCKET CORE L1d:L1i:L2:L3 ONLINE MAXMHZ MINMHZ<br />
0 0 0 0 0:0:0:0 yes 4600.0000 800.0000<br />
1 0 0 1 1:1:1:0 yes 4600.0000 800.0000<br />
2 0 0 2 2:2:2:0 yes 4600.0000 800.0000<br />
3 0 0 3 3:3:3:0 yes 4600.0000 800.0000<br />
4 0 0 4 4:4:4:0 yes 4600.0000 800.0000<br />
5 0 0 5 5:5:5:0 yes 4600.0000 800.0000<br />
6 0 0 0 0:0:0:0 yes 4600.0000 800.0000<br />
7 0 0 1 1:1:1:0 yes 4600.0000 800.0000<br />
8 0 0 2 2:2:2:0 yes 4600.0000 800.0000<br />
9 0 0 3 3:3:3:0 yes 4600.0000 800.0000<br />
10 0 0 4 4:4:4:0 yes 4600.0000 800.0000<br />
11 0 0 5 5:5:5:0 yes 4600.0000 800.0000<br />
<br />
As we see above, with AMD '''Core 0''' is sequential with '''CPU 0 & 1''', whereas Intel places '''Core 0''' on '''CPU 0 & 6'''.<br />
<br />
{{Tip|You can view your systems topology in diagram form, which may help some users. If you have {{Pkg|hwloc}} installed, run {{ic|lstopo}} to generate a helpful image of your CPU/Thread groupings.}}<br />
<br />
If you do not need all cores for the guest, it would then be preferable to leave at the very least one core for the host. Choosing which cores one to use for the host or guest should be based on the specific hardware characteristics of your CPU, however '''Core 0''' is a good choice for the host in most cases. If any cores are reserved for the host, it is recommended to pin the emulator and iothreads, if used, to the host cores rather than the VCPUs. This may improve performance and reduce latency for the guest since those threads will not pollute the cache or contend for scheduling with the guest VCPU threads. If all cores are passed to the guest, there is no need or benefit to pinning the emulator or iothreads.<br />
<br />
==== XML examples ====<br />
<br />
{{Note|Do not use the '''iothread''' lines from the XML examples shown below if you have not added an '''iothread''' to your disk controller. '''iothread''''s only work on '''virtio-scsi''' or '''virtio-blk''' devices.}}<br />
<br />
===== 4c/1t CPU w/o Hyperthreading Example =====<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<vcpu placement='static'>4</vcpu><br />
<cputune><br />
<vcpupin vcpu='0' cpuset='0'/><br />
<vcpupin vcpu='1' cpuset='1'/><br />
<vcpupin vcpu='2' cpuset='2'/><br />
<vcpupin vcpu='3' cpuset='3'/><br />
</cputune><br />
...<br />
</nowiki>}}<br />
<br />
===== 4c/2t Intel/AMD CPU example (after ComboPI AGESA bios update) =====<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<vcpu placement='static'>8</vcpu><br />
<iothreads>1</iothreads><br />
<cputune><br />
<vcpupin vcpu='0' cpuset='2'/><br />
<vcpupin vcpu='1' cpuset='8'/><br />
<vcpupin vcpu='2' cpuset='3'/><br />
<vcpupin vcpu='3' cpuset='9'/><br />
<vcpupin vcpu='4' cpuset='4'/><br />
<vcpupin vcpu='5' cpuset='10'/><br />
<vcpupin vcpu='6' cpuset='5'/><br />
<vcpupin vcpu='7' cpuset='11'/><br />
<emulatorpin cpuset='0,6'/><br />
<iothreadpin iothread='1' cpuset='0,6'/><br />
</cputune><br />
...<br />
<cpu mode='host-passthrough'><br />
<topology sockets='1' cores='4' threads='2'/><br />
</cpu><br />
...<br />
</nowiki>}}<br />
<br />
===== 4c/2t AMD CPU example (Before ComboPi AGESA bios update) =====<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<vcpu placement='static'>8</vcpu><br />
<iothreads>1</iothreads><br />
<cputune><br />
<vcpupin vcpu='0' cpuset='2'/><br />
<vcpupin vcpu='1' cpuset='3'/><br />
<vcpupin vcpu='2' cpuset='4'/><br />
<vcpupin vcpu='3' cpuset='5'/><br />
<vcpupin vcpu='4' cpuset='6'/><br />
<vcpupin vcpu='5' cpuset='7'/><br />
<vcpupin vcpu='6' cpuset='8'/><br />
<vcpupin vcpu='7' cpuset='9'/><br />
<emulatorpin cpuset='0-1'/><br />
<iothreadpin iothread='1' cpuset='0-1'/><br />
</cputune><br />
...<br />
<cpu mode='host-passthrough'><br />
<topology sockets='1' cores='4' threads='2'/><br />
</cpu><br />
...<br />
</nowiki>}}<br />
<br />
{{Note|If further CPU isolation is needed, consider using the '''isolcpus''' kernel command-line parameter on the unused physical/logical cores.}}<br />
<br />
If you do not intend to be doing any computation-heavy work on the host (or even anything at all) at the same time as you would on the VM, you may want to pin your VM threads across all of your cores, so that the VM can fully take advantage of the spare CPU time the host has available. Be aware that pinning all physical and logical cores of your CPU could induce latency in the guest VM.<br />
<br />
=== Huge memory pages ===<br />
<br />
When dealing with applications that require large amounts of memory, memory latency can become a problem since the more memory pages are being used, the more likely it is that this application will attempt to access information across multiple memory "pages", which is the base unit for memory allocation. Resolving the actual address of the memory page takes multiple steps, and so CPUs normally cache information on recently used memory pages to make subsequent uses on the same pages faster. Applications using large amounts of memory run into a problem where, for instance, a virtual machine uses 4 GiB of memory divided into 4 KiB pages (which is the default size for normal pages) for a total of 1.04 million pages, meaning that such cache misses can become extremely frequent and greatly increase memory latency. Huge pages exist to mitigate this issue by giving larger individual pages to those applications, increasing the odds that multiple operations will target the same page in succession.<br />
<br />
==== Transparent huge pages ====<br />
<br />
QEMU will use 2MiB sized transparent huge pages automatically without any explicit configuration in QEMU or Libvirt, subject to some important caveats. When using VFIO the pages are locked in at boot time and transparent huge pages are allocated up front when the VM first boots. If the kernel memory is highly fragmented, or the VM is using a majority of the remaining free memory, it is likely that the kernel will not have enough 2MiB pages to fully satisfy the allocation. In such a case, it silently fails by using a mix of 2MiB and 4KiB pages. Since the pages are locked in VFIO mode, the kernel will not be able to convert those 4KiB pages to huge after the VM starts either. The number of available 2MiB huge pages available to THP is the same as via the [[#Dynamic huge pages]] mechanism described in the following sections.<br />
<br />
To check how much memory THP is using globally:<br />
<br />
{{hc|$ grep AnonHugePages /proc/meminfo|<br />
AnonHugePages: 8091648 kB<br />
}}<br />
<br />
To check a specific QEMU instance. QEMU's PID must be substituted in the grep command:<br />
<br />
{{hc|$ grep -P 'AnonHugePages:\s+(?!0)\d+' /proc/[PID]/smaps|<br />
AnonHugePages: 8087552 kB<br />
}}<br />
<br />
In this example, the VM was allocated 8388608KiB of memory, but only 8087552KiB was available via THP. The remaining 301056KiB are allocated as 4KiB pages. Aside from manually checking, there is no indication when partial allocations occur. As such, THP's effectiveness is very much dependent on the host system's memory fragmentation at the time of VM startup. If this trade off is unacceptable or strict guarantees are required, [[#Static huge pages]] is recommended.<br />
<br />
Arch kernels have THP compiled in and enabled by default with {{ic|1=/sys/kernel/mm/transparent_hugepage/enabled}} set to {{ic|1=madvise}} mode.<br />
<br />
Also when trying to allocate pages for {{ic|virsh}}, e.g. {{ic|1=virsh allocpages 2M 2048}}, you might need to free up cached RAM. This is because your system might have allocated RAM for cache resources over time. One possible solution is to drop the page cache of your system:<br />
<br />
{{ic|# echo 1 > /proc/sys/vm/drop_caches}}<br />
<br />
==== Static huge pages ====<br />
<br />
While transparent huge pages should work in the vast majority of cases, they can also be allocated statically during boot. This should only be needed to make use 1 GiB hugepages on machines that support it, since transparent huge pages normally only go up to 2 MiB.<br />
<br />
{{Warning|Static huge pages lock down the allocated amount of memory, making it unavailable for applications that are not configured to use them. Allocating 4 GiBs worth of huge pages on a machine with 8 GiB of memory will only leave you with 4 GiB of available memory on the host '''even when the VM is not running'''.}}<br />
<br />
To allocate huge pages at boot, one must simply specify the desired amount on their kernel command line with {{ic|1=hugepages=''x''}}. For instance, reserving 1024 pages with {{ic|1=hugepages=1024}} and the default size of 2048 KiB per huge page creates 2 GiB worth of memory for the virtual machine to use.<br />
<br />
If supported by CPU page size could be set manually. 1 GiB huge page support could be verified by {{ic|grep pdpe1gb /proc/cpuinfo}}. Setting 1 GiB huge page size via kernel parameters : {{ic|1=default_hugepagesz=1G hugepagesz=1G hugepages=X}}.<br />
<br />
Also, since static huge pages can only be used by applications that specifically request it, you must add this section in your libvirt domain configuration to allow kvm to benefit from them :<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<memoryBacking><br />
<hugepages/><br />
</memoryBacking><br />
...<br />
</nowiki>}}<br />
<br />
==== Dynamic huge pages ====<br />
<br />
{{Accuracy|Need futher testing if this variant as effective as static one}}<br />
<br />
Hugepages could be allocated manually via {{ic|vm.nr_overcommit_hugepages}} [[sysctl]] parameter.<br />
<br />
{{hc|/etc/sysctl.d/10-kvm.conf|2=<br />
vm.nr_hugepages = 0<br />
vm.nr_overcommit_hugepages = ''num''<br />
}}<br />
<br />
Where {{ic|''num''}} - is the number of huge pages, which default size if 2 MiB.<br />
Pages will be automatically allocated, and freed after VM stops.<br />
<br />
More manual way:<br />
<br />
# echo ''num'' > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages<br />
# echo ''num'' > /sys/kernel/mm/hugepages/hugepages-1048576kB/nr_hugepages<br />
<br />
For 2 MiB and 1 GiB page size respectively.<br />
And they should be manually freed in the same way.<br />
<br />
It is hardly recommended to drop caches, compact memory and wait couple of seconds before starting VM, as there could be not enough free contiguous memory for required huge pages blocks. Especially after some uptime of the host system.<br />
<br />
# echo 3 > /proc/sys/vm/drop_caches<br />
# echo 1 > /proc/sys/vm/compact_memory<br />
<br />
Theoretically, 1 GiB pages works as 2 MiB. But practically - no guaranteed way was found to get contiguous 1 GiB memory blocks. Each consequent request of 1 GiB blocks lead to lesser and lesser dynamically allocated count.<br />
<br />
=== CPU frequency governor ===<br />
<br />
Depending on the way your [[CPU frequency scaling|CPU governor]] is configured, the VM threads may not hit the CPU load thresholds for the frequency to ramp up. Indeed, KVM cannot actually change the CPU frequency on its own, which can be a problem if it does not scale up with vCPU usage as it would result in underwhelming performance. An easy way to see if it behaves correctly is to check if the frequency reported by {{ic|watch lscpu}} goes up when running a CPU-intensive task on the guest. If you are indeed experiencing stutter and the frequency does not go up to reach its reported maximum, it may be due to [https://lime-technology.com/forum/index.php?topic=46664.msg447678#msg447678 cpu scaling being controlled by the host OS]. In this case, try setting all cores to maximum frequency to see if this improves performance. Note that if you are using a modern intel chip with the default pstate driver, cpupower commands will be [[CPU frequency scaling#CPU frequency driver|ineffective]], so monitor {{ic|/proc/cpuinfo}} to make sure your cpu is actually at max frequency.<br />
<br />
=== Isolating pinned CPUs ===<br />
<br />
CPU pinning by itself will not prevent other host processes from running on the pinned CPUs. Properly isolating the pinned CPUs can reduce latency in the guest VM.<br />
<br />
==== With isolcpus kernel parameter ====<br />
<br />
In this example, let us assume you are using CPUs 4-7.<br />
Use the [[kernel parameters]] {{ic|isolcpus nohz_full rcu_nocbs}} to completely isolate the CPUs from the kernel. For example:<br />
<br />
isolcpus=4-7 nohz_full=4-7 rcu_nocbs=4-7<br />
<br />
Then, run {{ic|qemu-system-x86_64}} with taskset and chrt:<br />
<br />
# chrt -r 1 taskset -c 4-7 qemu-system-x86_64 ...<br />
<br />
The {{ic|chrt}} command will ensure that the task scheduler will round-robin distribute work (otherwise it will all stay on the first cpu). For {{ic|taskset}}, the CPU numbers can be comma- and/or dash-separated, like "0,1,2,3" or "0-4" or "1,7-8,10" etc.<br />
<br />
See [https://www.removeddit.com/r/VFIO/comments/6vgtpx/high_dpc_latency_and_audio_stuttering_on_windows/dm0sfto/ this Removeddit mirror of a Reddit thread] for more info. ([https://www.reddit.com/r/VFIO/comments/6vgtpx/high_dpc_latency_and_audio_stuttering_on_windows/dm0sfto/ The original thread] is worthless because of deleted comments.)<br />
<br />
==== Dynamically isolating CPUs ====<br />
<br />
The isolcpus kernel parameter will permanently reserve CPU cores, even when the guest is not running. A more flexible alternative is to dynamically isolate CPUs when starting the guest. This can be achieved with the following alternatives:<br />
<br />
* {{AUR|cpuset-git}} ([https://www.redhat.com/archives/vfio-users/2016-September/msg00072.html vfio-users post], [https://rokups.github.io/#!pages/gaming-vm-performance.md blog post], [https://github.com/PassthroughPOST/VFIO-Tools/blob/master/libvirt_hooks/hooks/cset.sh example script])<br />
* {{AUR|vfio-isolate}}<br />
* systemd ([https://www.reddit.com/r/VFIO/comments/ebe3l5/deprecated_isolcpus_workaround/fem8jgk reddit post])<br />
<br />
=== Improving performance on AMD CPUs ===<br />
<br />
Starting with QEMU 3.1 the TOPOEXT cpuid flag is disabled by default. In order to use hyperthreading (SMT) on AMD CPUs you need to manually enable it:<br />
<br />
<cpu mode='host-passthrough' check='none'><br />
<topology sockets='1' cores='4' threads='2'/><br />
<feature policy='require' name='topoext'/><br />
</cpu><br />
<br />
commit: https://git.qemu.org/?p=qemu.git;a=commit;h=7210a02c58572b2686a3a8d610c6628f87864aed<br />
<br />
=== Virtio disk ===<br />
<br />
{{Merge|QEMU#Installing virtio drivers|Off-topic.|section=Moving virtio disk section to QEMU}}<br />
<br />
The default disk types are SATA or IDE emulation out of the box. These controllers offer maximum compatibility but are not suited for efficient virtualization. Two accelerated models exist: {{ic|1=virtio-scsi}} for SCSI emulation and passthrough, or {{ic|1=virtio-blk}} for a more basic block device emulation.<br />
<br />
==== Drivers ====<br />
<br />
* Linux guests should support these out of the box on any modern kernel<br />
* macOS has {{ic|1=virtio-blk}} support starting in Mojave via {{ic|1=AppleVirtIO.kext}}<br />
* Windows needs the [https://docs.fedoraproject.org/en-US/quick-docs/creating-windows-virtual-machines-using-virtio-drivers/ Windows virtio drivers]. {{ic|1=virtio-scsi}} uses the {{ic|1=vioscsi}} driver. {{ic|1=virtio-blk}} uses the {{ic|1=viostor}} driver<br />
* Windows can be installed directly onto these disks by selecting 'load driver' on the installer disk selection menu. The windows iso and virtio driver iso should both be attached as regular SATA/IDE cdroms during the installation process<br />
* To switch boot disks to virtio on an existing Windows installation:<br />
** {{ic|1=virtio-blk}}: Add a temporary disk with bus {{ic|1=virtio}}, boot windows & load the driver for the disk, then shutdown and switch the boot disk disk bus to {{ic|1=virtio}}<br />
** {{ic|1=virtio-scsi}}: Add a scsi controller with model {{ic|1=virtio}}, boot windows & load the driver for the controller, then shutdown and switch the boot disk bus to {{ic|1=scsi}} (not virtio)<br />
<br />
==== Considerations ====<br />
<br />
* {{ic|1=virtio-scsi}} TRIM support is mature, all versions should support it. Traditionally, {{ic|1=virtio-scsi}} has been the preferred approach for this reason<br />
* {{ic|1=virtio-blk}} TRIM support is new, this requires requires qemu 4.0+, guest linux kernel 5.0+, guest windows drivers 0.1.173+<br />
* Thin provisioning works by enabling TRIM on a sparse image file: {{ic|1=discard='unmap'}}. Unused blocks will be freed and the disk usage will drop (works on both raw and qcow2). Actual on-disk size of a sparse image file may be checked with {{ic|1=du /path/to/disk.img}}<br />
* Thin provisioning can also work with block storage such as zfs zvols or thin lvm<br />
* Virt queue count will influence the number of threads inside the guest kernel used for IO processing, suggest using {{ic|1=queues='4'}} or more<br />
* Native mode ({{ic|1=io='native'}}) uses a single threaded model based on linux AIO, is a bit more CPU efficient but may have lower peak performance and does not allow host side caching to be used<br />
* Threaded mode ({{ic|1=io='threads'}}) will spawn dozens of threads on demand as the disk is used. This is less efficient but may perform better if there are enough host cores available to run them, and allows for host side caching to be used<br />
* Modern versions of libvirt will group the dynamic worker threads created when using threaded mode in with the iothread=1 cgroup for pinning purposes. Very old versions of libvirt left these in the emulator cgroup<br />
<br />
==== IO threads ====<br />
<br />
An IO thread is a dedicated thread for processing disk events, rather than using the main qemu emulator loop. This should not be confused with the worker threads spawned on demand with {{ic|1=io='threads'}}.<br />
<br />
* You can only use one iothread per disk controller. The thread must be assigned to a specific controller with {{ic|1=iothread='X'}} in the {{ic|1=<driver>}} tag. Furthermore, extra & unassigned iothreads will not be used and do nothing<br />
* In the case of {{ic|1=virtio-scsi}}, there is one controller for multiple scsi disks. The iothread is assigned on the controller: {{ic|1=<controller><driver iothread='X'>}}<br />
* In the case of {{ic|1=virtio-blk}}, each disk has its own controller. The iothread is assigned in the driver tag under the disk itself: {{ic|1=<disk><driver iothread='X'>}}<br />
* Since emulated disks incur a significant amount of CPU overhead, that can lead to vcpu stuttering under high disk load (especially high random IOPS). In this case it helps to pin the IO to different core(s) than your vcpus with {{ic|1=<iothreadpin>}}<br />
<br />
==== Examples with libvirt ====<br />
<br />
virtio-scsi + iothread + worker threads + host side writeback caching + full disk block device backend:<br />
<domain><br />
<devices><br />
<disk type='block' device='disk'><br />
<driver name='qemu' type='raw' cache='writeback' io='threads' discard='unmap'/><br />
<source dev='/dev/disk/by-id/ata-Samsung_SSD_840_EVO_1TB_S1D9NSAF206396F'/><br />
<target dev='sda' bus='scsi'/><br />
</disk><br />
<controller type='scsi' index='0' model='virtio-scsi'><br />
<driver iothread='1' queues='8'/><br />
</controller><br />
<br />
virtio-blk + iothread + native aio + no host caching + raw sparse image backend:<br />
<domain><br />
<devices><br />
<disk type='file' device='disk'><br />
<driver name='qemu' type='raw' cache='none' io='native' discard='unmap' iothread='1' queues='8'/><br />
<source file='/var/lib/libvirt/images/pool/win10.img'/><br />
<target dev='vda' bus='virtio'/><br />
</disk><br />
<br />
Creating the iothreads:<br />
<domain><br />
<iothreads>1</iothreads><br />
<br />
Pinning iothreads:<br />
<domain><br />
<cputune><br />
<iothreadpin iothread='1' cpuset='0-1,6-7'/><br />
<br />
==== Example with virt-manager ====<br />
<br />
This will create a {{ic|1=virtio-blk}} device:<br />
# Open the VM preferences<br />
# Go to {{ic|Add Hardware > Storage}}<br />
# Create or choose a storage file<br />
# Select {{ic|Device Type: Disk device}} and {{ic|Bus type: VirtIO}}<br />
# Click Finish<br />
<br />
=== Virtio network ===<br />
<br />
The default NIC models rtl8139 or e1000 can be a bottleneck for gigabit+ speeds and have a significant amount of CPU overhead compared to {{ic|1=virtio-net}}.<br />
<br />
* Select {{ic|1=virtio}} as the model for the NIC with libvirt or use the {{ic|1=virtio-net-pci}} device in bare qemu<br />
* Windows needs the {{ic|1=NetKVM}} driver from [https://docs.fedoraproject.org/en-US/quick-docs/creating-windows-virtual-machines-using-virtio-drivers/ Windows virtio drivers]<br />
* Virtio uses vhost-net by default for in-kernel packet processing without exiting to userspace<br />
* Multiqueue can enabled for a further speedup with multiple connections but typically will not boost single stream speeds. For libvirt add {{ic|1=<driver queues='8'/>}} under the interface tag<br />
* Zero copy transmit may also be enabled on macvtap by setting the module parameter {{ic|1=vhost_net.experimental_zcopytx=1}} but this may actually have worse performance, see [https://github.com/torvalds/linux/commit/098eadce3c622c07b328d0a43dda379b38cf7c5e commit]<br />
<br />
Libvirt example with a bridge:<br />
<br />
<interface type='bridge'><br />
<mac address="52:54:00:6d:6e:2e"/><br />
<source bridge='br0'/><br />
<model type='virtio'/><br />
<driver queues='8'/><br />
</interface><br />
<br />
=== Further tuning ===<br />
<br />
More specialized VM tuning tips are available at [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html-single/Virtualization_Tuning_and_Optimization_Guide/index.html Red Hat's Virtualization Tuning and Optimization Guide].<br />
<br />
== Special procedures ==<br />
<br />
Certain setups require specific configuration tweaks in order to work properly. If you are having problems getting your host or your VM to work properly, see if your system matches one of the cases below and try adjusting your configuration accordingly.<br />
<br />
=== Using identical guest and host GPUs ===<br />
<br />
{{Expansion|A number of users have been having issues with this, it should probably be adressed by the article.|Talk:PCI passthrough via OVMF#Additionnal sections}}<br />
<br />
Due to how vfio-pci uses your vendor and device id pair to identify which device they need to bind to at boot, if you have two GPUs sharing such an ID pair you will not be able to get your passthrough driver to bind with just one of them. This sort of setup makes it necessary to use a script, so that whichever driver you are using is instead assigned by pci bus address using the {{ic|driver_override}} mechanism.<br />
<br />
==== Script variants ====<br />
<br />
===== Passthrough all GPUs but the boot GPU =====<br />
<br />
Here, we will make a script to bind vfio-pci to all GPUs but the boot gpu. Create the script {{ic|/usr/local/bin/vfio-pci-override.sh}}:<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
<br />
for i in /sys/bus/pci/devices/*/boot_vga; do<br />
if [ $(cat "$i") -eq 0 ]; then<br />
GPU="${i%/boot_vga}"<br />
AUDIO="$(echo "$GPU" | sed -e "s/0$/1/")"<br />
USB="$(echo "$GPU" | sed -e "s/0$/2/")"<br />
echo "vfio-pci" > "$GPU/driver_override"<br />
if [ -d "$AUDIO" ]; then<br />
echo "vfio-pci" > "$AUDIO/driver_override"<br />
fi<br />
if [ -d "$USB" ]; then<br />
echo "vfio-pci" > "$USB/driver_override"<br />
fi<br />
fi<br />
done<br />
<br />
modprobe -i vfio-pci<br />
</nowiki>}}<br />
<br />
===== Passthrough selected GPU =====<br />
<br />
In this case we manually specify the GPU to bind.<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
<br />
DEVS="0000:03:00.0 0000:03:00.1"<br />
<br />
if [ ! -z "$(ls -A /sys/class/iommu)" ]; then<br />
for DEV in $DEVS; do<br />
echo "vfio-pci" > /sys/bus/pci/devices/$DEV/driver_override<br />
done<br />
fi<br />
<br />
modprobe -i vfio-pci<br />
</nowiki>}}<br />
<br />
==== Script installation ====<br />
<br />
Edit {{ic|/etc/mkinitcpio.conf}}:<br />
<br />
# Add {{ic|modconf}} to the [[mkinitcpio#HOOKS|HOOKS]] array and {{ic|/usr/local/bin/vfio-pci-override.sh}} to the [[mkinitcpio#BINARIES and FILES|FILES]] array.<br />
<br />
Edit {{ic|/etc/modprobe.d/vfio.conf}}:<br />
<br />
# Add the following line: {{ic|install vfio-pci /usr/local/bin/vfio-pci-override.sh}}<br />
# [[Regenerate the initramfs]] and reboot.<br />
<br />
=== Passing the boot GPU to the guest ===<br />
<br />
{{Expansion|This is related to VBIOS issues and should be moved into a separate section regarding VBIOS compatibility.|section=UEFI (OVMF) Compatibility in VBIOS}}<br />
<br />
The GPU marked as {{ic|boot_vga}} is a special case when it comes to doing PCI passthroughs, since the BIOS needs to use it in order to display things like boot messages or the BIOS configuration menu. To do that, it makes [https://www.redhat.com/archives/vfio-users/2016-May/msg00224.html a copy of the VGA boot ROM which can then be freely modified]. This modified copy is the version the system gets to see, which the passthrough driver may reject as invalid. As such, it is generally recommended to change the boot GPU in the BIOS configuration so the host GPU is used instead or, if that is not possible, to swap the host and guest cards in the machine itself.<br />
<br />
=== Using Looking Glass to stream guest screen to the host ===<br />
<br />
It is possible to make VM share the monitor, and optionally a keyboard and a mouse with a help of [https://looking-glass.io/ Looking Glass].<br />
<br />
==== Adding IVSHMEM Device to VM ====<br />
<br />
Looking glass works by creating a shared memory buffer between a host and a guest. This is a lot faster than streaming frames via localhost, but requires additional setup. <br />
<br />
With your VM turned off open the machine configuration<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<devices><br />
...<br />
<shmem name='looking-glass'><br />
<model type='ivshmem-plain'/><br />
<size unit='M'>32</size><br />
</shmem><br />
</devices><br />
...<br />
</nowiki>}}<br />
<br />
You should replace 32 with your own calculated value based on what resolution you are going to pass through. It can be calculated like this:<br />
<br />
width x height x 4 x 2 = total bytes<br />
total bytes / 1024 / 1024 = total mebibytes + 2<br />
<br />
For example, in case of 1920x1080<br />
<br />
1920 x 1080 x 4 x 2 = 16,588,800 bytes<br />
16,588,800 / 1024 / 1024 = 15.82 MiB + 2 = 17.82<br />
<br />
The result must be '''rounded up''' to the nearest power of two, and since 17.82 is bigger than 16 we should choose 32.<br />
<br />
Next create a configuration file to create the shared memory file on boot<br />
<br />
{{hc|/etc/tmpfiles.d/10-looking-glass.conf|2=<br />
f /dev/shm/looking-glass 0660 '''user''' kvm -<br />
}}<br />
<br />
Replace user with your username.<br />
<br />
Ask systemd-tmpfiles to create the shared memory file now without waiting to next boot<br />
<br />
# systemd-tmpfiles --create /etc/tmpfiles.d/10-looking-glass.conf<br />
<br />
==== Installing the IVSHMEM Host to Windows guest ====<br />
<br />
Currently Windows would not notify users about a new IVSHMEM device, it would silently install a dummy driver. To actually enable the device you have to go into device manager and update the driver for the device under the "System Devices" node for '''"PCI standard RAM Controller"'''. Download the signed driver [https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/upstream-virtio/ from Red Hat].<br />
<br />
Once the driver is installed you must download a matching [https://looking-glass.io/downloads looking-glass-host] package that matches the client you will install from AUR, and install it on your guest. In order to run it you would also need to install Microsoft Visual C++ Redistributable from [https://www.visualstudio.com/downloads/ Microsoft]. The recent version will automatically install a service that starts the daemon on boot. The logs of the host daemon are located at {{ic|%ProgramData%\Looking Glass (host)\looking-glass-host.txt}} on the guest system.<br />
<br />
==== Setting up the null video device ====<br />
<br />
(Retrieved from: https://looking-glass.io/wiki/Installation#Spice_Server)<br />
<br />
If you would like to use Spice to give you keyboard and mouse input along with clipboard sync support, make sure you have a {{ic|<nowiki><graphics type='spice'></nowiki>}} device, then:<br />
<br />
* Find your {{ic|<video>}} device, and set {{ic|<nowiki><model type='none'/></nowiki>}}<br />
* If you cannot find it, make sure you have a {{ic|<graphics>}} device, save and edit again<br />
<br />
==== Getting a client ====<br />
<br />
Looking glass client can be installed from AUR using {{AUR|looking-glass}} or {{AUR|looking-glass-git}} packages.<br />
<br />
You can start it once the VM is set up and running<br />
<br />
$ looking-glass-client<br />
<br />
If you do not want to use Spice to control the guest mouse and keyboard you can disable the Spice server.<br />
<br />
$ looking-glass-client -s<br />
<br />
Additionally you may want to start Looking Glass Client as full screen, otherwise the image may be scaled down resulting in poor image fidelity.<br />
<br />
$ looking-glass-client -F<br />
<br />
Launch with the {{ic|--help}} option for further information.<br />
<br />
==== Additional information ====<br />
<br />
Refer to the [https://looking-glass.io/wiki/Installation upstream documentation] for further details.<br />
<br />
=== Swap peripherals to and from the Host ===<br />
<br />
Looking Glass includes a Spice client in order to control mouse movement on the Windows guest. However this may have too much latency for certain applications, such as gaming. An alternative method is passing through specific USB devices for minimal latency. This allows for switching the devices between host and guest.<br />
<br />
First create a .xml file for the device(s) you wish to pass-through, which libvirt will use to identify the device.<br />
<br />
{{hc|~/.VFIOinput/input_1.xml|2=<br />
<hostdev mode='subsystem' type='usb' managed='no'><br />
<source><br />
<vendor id='0x[Before Colon]'/><br />
<product id='0x[After Colon]'/><br />
</source><br />
</hostdev><br />
}}<br />
<br />
Replace [Before/After Colon] with the contents of the 'lsusb' command, specific to the device you want to pass-through.<br />
<br />
For instance my mouse is {{ic|Bus 005 Device 002: ID 1532:0037 Razer USA, Ltd}} so I would replace {{ic|vendor id}} with 1532, and {{ic|product id}} with 1037.<br />
<br />
Repeat this process for any additional USB devices you want to pass-through. If your mouse / keyboard has multiple entries in {{ic|lsusb}}, perhaps if it is wireless, then create additional xml files for each.<br />
<br />
{{Note|Do not forget to change the path & name of the script(s) above and below to match your user and specific system.}}<br />
<br />
Next a bash script file is needed to tell libvirt what to attach/detach the USB devices to the guest.<br />
<br />
{{hc|~/.VFIOinput/input_attach.sh|2=<br />
#!/bin/bash<br />
<br />
virsh attach-device [VM-Name] [USBdevice]<br />
}}<br />
<br />
Replace [VM-Name] with the name of your virtual machine, which can be seen under virt-manager. Additionally replace [USBdevice] with the '''full''' path to the .xml file for the device you wish to pass-through. Add additional lines for more than 1 device. For example here is my script:<br />
<br />
{{hc|~/.VFIOinput/input_attach.sh|2=<br />
#!/bin/bash<br />
<br />
virsh attach-device win10 /home/$USER/.VFIOinput/input_mouse.xml<br />
virsh attach-device win10 /home/$USER/.VFIOinput/input_keyboard.xml<br />
}}<br />
<br />
Next duplicate the script file and replace {{ic|attach-device}} with {{ic|detach-device}}. Ensure both scripts are executable with {{ic|chmod +x $script.sh}}<br />
<br />
This 2 script files can now be executed to attach or detach your USB devices from the host to the guest VM. It is important to note that they may need to be executed as root. To run the script from the Windows VM, one possibility is using [[PuTTY]] to [[SSH]] into the host, and execute the script. On Windows PuTTY comes with plink.exe which can execute singular commands over SSH before then logging out, instead of opening a SSH terminal, all in the background.<br />
<br />
{{hc|detach_devices.bat|2=<br />
"C:\Program Files\PuTTY\plink.exe" root@$HOST_IP -pw $ROOTPASSWORD /home/$USER/.VFIOinput/input_detach.sh<br />
}}<br />
<br />
Replace {{ic|$HOST_IP}} with the Host [[Network configuration#IP addresses|IP Address]] and $ROOTPASSWORD with the root password.<br />
<br />
{{warning|This method is insecure if somebody has access to your VM, since they could open the file and read your password. It is advisable to use [[SSH keys]] instead!}}<br />
<br />
You may also want to execute the script files using key binds. On Windows one option is [https://autohotkey.com/ Autohotkey], and on the Host [[Xbindkeys]]. Because of the need to run the scripts as root, you may also need to use [[Polkit]] or [[Sudo]] which can both be used to authenticate specific executables as able to run as root without needing a password.<br />
<br />
=== Bypassing the IOMMU groups (ACS override patch) ===<br />
<br />
If you find your PCI devices grouped among others that you do not wish to pass through, you may be able to seperate them using Alex Williamson's ACS override patch. Make sure you understand [https://vfio.blogspot.com/2014/08/iommu-groups-inside-and-out.html the potential risk] of doing so. <br />
<br />
You will need a kernel with the patch applied. The easiest method to acquiring this is through the {{pkg|linux-zen}} or {{AUR|linux-vfio}} package.<br />
<br />
In addition, the ACS override patch needs to be enabled with kernel command line options. The patch file adds the following documentation:<br />
<br />
pcie_acs_override =<br />
[PCIE] Override missing PCIe ACS support for:<br />
downstream<br />
All downstream ports - full ACS capabilties<br />
multifunction<br />
All multifunction devices - multifunction ACS subset<br />
id:nnnn:nnnn<br />
Specfic device - full ACS capabilities<br />
Specified as vid:did (vendor/device ID) in hex<br />
<br />
The option {{ic|1=pcie_acs_override=downstream,multifunction}} should break up as many devices as possible.<br />
<br />
After installation and configuration, reconfigure your [[Kernel parameters|bootloader kernel parameters]] to load the new kernel with the {{ic|1=pcie_acs_override=}} option enabled.<br />
<br />
== Plain QEMU without libvirt ==<br />
<br />
Instead of setting up a virtual machine with the help of libvirt, plain QEMU commands with custom parameters can be used for running the VM intended to be used with PCI passthrough. This is desirable for some use cases like scripted setups, where the flexibility for usage with other scripts is needed.<br />
<br />
To achieve this after [[#Setting up IOMMU]] and [[#Isolating the GPU]], follow the [[QEMU]] article to setup the virtualized environment, [[QEMU#Enabling KVM|enable KVM]] on it and use the flag {{ic|1=-device vfio-pci,host=07:00.0}} replacing the identifier (07:00.0) with your actual device's ID that you used for the GPU isolation earlier.<br />
<br />
For utilizing the OVMF firmware, make sure the {{Pkg|edk2-ovmf}} package is installed, copy the UEFI variables from {{ic|/usr/share/edk2-ovmf/x64/OVMF_VARS.fd}} to temporary location like {{ic|/tmp/MY_VARS.fd}} and finally specify the OVMF paths by appending the following parameters to the QEMU command (order matters):<br />
<br />
* {{ic|1=-drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2-ovmf/x64/OVMF_CODE.fd}} for the actual OVMF firmware binary, note the readonly option<br />
* {{ic|1=-drive if=pflash,format=raw,file=/tmp/MY_VARS.fd}} for the variables<br />
<br />
{{Note|<br />
* Make sure that {{ic|1=OVMF_CODE.fd}} is given as a command line parameter before {{ic|1=MY_VARS.fd}}. The boot sequence will fail otherwise.<br />
* QEMU's default SeaBIOS can be used instead of OVMF, but it is not recommended as it can cause issues with passthrough setups.<br />
}}<br />
<br />
It is recommended to study the QEMU article for ways to enhance the performance by using the [[QEMU#Installing virtio drivers|virtio drivers]] and other further configurations for the setup.<br />
<br />
You also might have to use the {{ic|1=-cpu host,kvm=off}} parameter to forward the host's CPU model info to the VM and fool the virtualization detection used by Nvidia's and possibly other manufacturers' device drivers trying to block the full hardware usage inside a virtualized system.<br />
<br />
== Passing through other devices ==<br />
<br />
=== USB controller ===<br />
<br />
If your motherboard has multiple USB controllers mapped to multiple groups, it is possible to pass those instead of USB devices. Passing an actual controller over an individual USB device provides the following advantages : <br />
<br />
* If a device disconnects or changes ID over the course of an given operation (such as a phone undergoing an update), the VM will not suddenly stop seeing it.<br />
* Any USB port managed by this controller is directly handled by the VM and can have its devices unplugged, replugged and changed without having to notify the hypervisor.<br />
* Libvirt will not complain if one of the USB devices you usually pass to the guest is missing when starting the VM.<br />
<br />
Unlike with GPUs, drivers for most USB controllers do not require any specific configuration to work on a VM and control can normally be passed back and forth between the host and guest systems with no side effects.<br />
<br />
{{Warning|Make sure your USB controller supports resetting: [[#Passing through a device that does not support resetting]]}}<br />
<br />
You can find out which PCI devices correspond to which controller and how various ports and devices are assigned to each one of them using this command :<br />
<br />
{{hc|$ <nowiki>for usb_ctrl in /sys/bus/pci/devices/*/usb*; do pci_path=${usb_ctrl%/*}; iommu_group=$(readlink $pci_path/iommu_group); echo "Bus $(cat $usb_ctrl/busnum) --> ${pci_path##*/} (IOMMU group ${iommu_group##*/})"; lsusb -s ${usb_ctrl#*/usb}:; echo; done</nowiki>|<br />
Bus 1 --> 0000:00:1a.0 (IOMMU group 4)<br />
Bus 001 Device 004: ID 04f2:b217 Chicony Electronics Co., Ltd Lenovo Integrated Camera (0.3MP)<br />
Bus 001 Device 007: ID 0a5c:21e6 Broadcom Corp. BCM20702 Bluetooth 4.0 [ThinkPad]<br />
Bus 001 Device 008: ID 0781:5530 SanDisk Corp. Cruzer<br />
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
<br />
Bus 2 --> 0000:00:1d.0 (IOMMU group 9)<br />
Bus 002 Device 006: ID 0451:e012 Texas Instruments, Inc. TI-Nspire Calculator<br />
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub<br />
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
}}<br />
<br />
This laptop has 3 USB ports managed by 2 USB controllers, each with their own IOMMU group. In this example, Bus 001 manages a single USB port (with a SanDisk USB pendrive plugged into it so it appears on the list), but also a number of internal devices, such as the internal webcam and the bluetooth card. Bus 002, on the other hand, does not apprear to manage anything except for the calculator that is plugged into it. The third port is empty, which is why it does not show up on the list, but is actually managed by Bus 002.<br />
<br />
Once you have identified which controller manages which ports by plugging various devices into them and decided which one you want to passthrough, simply add it to the list of PCI host devices controlled by the VM in your guest configuration. No other configuration should be needed.<br />
<br />
{{Note|If your USB controller does not support resetting, is not in an isolated group, or is otherwise unable to be passed through then it may still be possible to accomplish similar results through [[udev]] rules. See [https://github.com/olavmrk/usb-libvirt-hotplug] which allows any device connected to specified USB ports to be automatically attached to a virtual machine.}}<br />
<br />
=== Passing VM audio to host via PulseAudio ===<br />
<br />
It is possible to route the virtual machine's audio to the host as an application using libvirt. This has the advantage of multiple audio streams being routable to one host output, and working with audio output devices that do not support passthrough. [[PulseAudio]] is required for this to work.<br />
<br />
First, remove the comment from the {{ic|1=#user = ""}} line. Then add your username in the quotations. This tells QEMU which user's pulseaudio stream to route through.<br />
<br />
{{hc|/etc/libvirt/qemu.conf|2=<br />
user = "example"<br />
}}<br />
<br />
Next, modify the libvirt configuration<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
<domain type='kvm'><br />
}}<br />
<br />
to<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
<domain type='kvm' xmlns:qemu='<nowiki>http://libvirt.org/schemas/domain/qemu/1.0</nowiki>'><br />
}}<br />
<br />
Then set the QEMU PulseAudio variables at the bottom of the libvirt xml file<br />
<br />
{{hc|$ virsh edit ''vmname''|<br />
</devices><br />
</domain><br />
}}<br />
<br />
to<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
</devices><br />
<qemu:commandline><br />
<qemu:arg value="-audiodev"/><br />
<qemu:arg value="pa,id=snd0,server=/run/user/1000/pulse/native"/><br />
</qemu:commandline><br />
</domain><br />
</nowiki>}}<br />
<br />
You can also use the /tmp directory if you have multiple users accessing PulseAudio<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
</devices><br />
<qemu:commandline><br />
<qemu:arg value="-audiodev"/><br />
<qemu:arg value="pa,id=snd0,server=unix:/tmp/pulse-socket"/><br />
</qemu:commandline><br />
</domain><br />
</nowiki>}}<br />
<br />
You may want to change 1000 under the user directory to your current user uid (which can be found by running the {{ic|id}} command. Remember to save the file and exit it without ending the process before continuing, otherwise the changes will not register. If you get the message {{ic|Domain ''vmname'' XML configuration edited.}} after exiting, it means that your changes have been applied. Virtual Machine audio will now be routed through the host as an application. A application such as {{Pkg|pavucontrol}} can be used to control the output device.<br />
<br />
==== QEMU 4.0/4.2+ audio changes ====<br />
<br />
As of QEMU 4.0 and made official with [https://www.kraxel.org/blog/2020/01/qemu-sound-audiodev/ QEMU 4.2] the {{ic|1=-audiodev}} parameter is now to be used with PulseAudio sound passthrough, any previous environmental variables you have defined in your XML '''need''' to be removed e.g. {{ic|qemu:env}} to properly use this.<br />
<br />
You will also need to change the chipset accordingly with each QEMU update to how your VM is set up, i.e. {{ic|pc-q35-4.2}} or {{ic|pc-i440fx-4.2}} to take advantage of the changes in QEMU:<br />
<br />
{{hc|$ virsh edit ''vmname''|2=<br />
<os><br />
<type arch='x86_64' machine='pc-q35-4.2'>hvm</type><br />
...<br />
</os><br />
...<br />
<os><br />
<type arch='x86_64' machine='pc-i440fx-4.2'>hvm</type><br />
...<br />
</os><br />
}}<br />
<br />
The latest audiodev changes in QEMU also suggest using the ICH9 instead of ICH6 or AC97 for audio emulation to take advantage of this newer code, it is recommended to use the parameters as shown below because Libvirt currently does not define the {{ic|1=id=}} parameter correctly:<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
<qemu:arg value="-device"/><br />
<qemu:arg value="ich9-intel-hda,bus=pcie.0,addr=0x1b"/><br />
<qemu:arg value="-device"/><br />
<qemu:arg value="hda-micro,audiodev=hda"/><br />
<qemu:arg value="-audiodev"/><br />
<qemu:arg value="pa,id=hda,server=unix:/tmp/pulse-socket"/><br />
</nowiki>}}<br />
<br />
QEMU 4.2 also has 5.1 channel audio support via {{ic|usb-audio}} emulation, this can be enabled as shown below:<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
<qemu:arg value="-device"/><br />
<qemu:arg value="usb-audio,audiodev=usb,multi=on"/><br />
<qemu:arg value="-audiodev"/><br />
<qemu:arg value="pa,id=usb,server=unix:/tmp/pulse-socket,out.mixing-engine=off"/><br />
</nowiki>}}<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* You can have multiple audio backends, by simply specifying {{ic|1=-audiodev}} multiple times in your XML and by assigning them different ids. This can be useful for a use case of having two identical backends. With PulseAudio each backend is a separate stream and can be routed to different output devices on the host (using a pulse mixer app like {{Pkg|pavucontrol}} or {{Pkg|pulsemixer}}).<br />
* USB 3 emulation is needed in Libvirt/QEMU to enable the {{ic|usb-audio}} parameter<br />
* It is recommended to enable MSI interrupts with a tool such as [https://forums.guru3d.com/threads/windows-line-based-vs-message-signaled-based-interrupts-msi-tool.378044/ this] on the ICH9 audio device to mitigate any crackling, stuttering, speedup, or no audio at all after VM restart<br />
* The {{ic|1=-audiodev=hda}} parameter can be changed to your liking, but as shown above, the names must match each other or the VM will not start<br />
* If audio is crackling/stuttering/speedup etc. is still present you may want to adjust parameters such as {{ic|buffer-length}} and {{ic|timer-period}}, more information on these parameters and more can be found in the {{man|1|qemu}} manual<br />
* Some audio chipsets such as [https://bugzilla.kernel.org/show_bug.cgi?id=195303 Realtek alc1220] may also have issues out of the box so do consider this when using any audio emulation with QEMU<br />
* Improper pinning or heavy host usage without using [[#Isolating pinned CPUs|isolcpus]] can also influence sound bugs, especially while gaming in a VM<br />
}}<br />
<br />
=== Passing VM audio to host via Scream ===<br />
<br />
It is possible to pass VM audio through a bridged network such as the one provided by Libvirt or by adding a IVSHMEM device to the host by using a application called [https://github.com/duncanthrax/scream Scream]. This section will only cover using PulseAudio as a receiver on the host.<br />
See the project page for more details and instructions on other methods.<br />
<br />
==== Using Scream with a bridged network ====<br />
<br />
{{Note|<br />
* This is the ''preferred'' way to use this, although results may vary per user<br />
* It is recommend to use the [[#Virtio network]] adapter while using Scream, other virtual adapters provided by QEMU such as '''e1000e''' may lead to poor performance<br />
}}<br />
<br />
To use scream via your network you will want to find your bridge name via {{ic|1=ip -a}}, in most cases it will be called '''br0''' or '''virbr0'''. Below is a example of the command needed to start the Scream application:<br />
<br />
$ scream -o pulse -i virbr0 &<br />
<br />
{{Warning| This will not work with a '''macvtap bridge''' as that does not allow host to guest communication, also make sure you have the proper firewall ports open for it to communicate with the VM}}<br />
<br />
==== Adding the IVSHMEM device to use Scream with IVSHMEM ====<br />
<br />
With the VM turned off, edit the machine configuration<br />
<br />
{{hc|$ virsh edit ''vmname''|<nowiki><br />
...<br />
<devices><br />
...<br />
<shmem name='scream-ivshmem'><br />
<model type='ivshmem-plain'/><br />
<size unit='M'>2</size><br />
</shmem><br />
</devices><br />
...<br />
</nowiki>}}<br />
<br />
In the above configuration, the size of the IVSHMEM device is 2MB (the recommended amount). Change this as needed.<br />
<br />
Now refer to [[#Adding IVSHMEM Device to VM]] to configure the host to create the shared memory file on boot, replacing {{ic|looking-glass}} with {{ic|scream-ivshmem}}.<br />
<br />
===== Configuring the Windows guest for IVSHMEM =====<br />
<br />
The correct driver must be installed for the IVSHMEM device on the guest. <br />
See [[#Installing the IVSHMEM Host to Windows guest]]. Ignore the part about {{ic|looking-glass-host}}.<br />
<br />
Install the [https://github.com/duncanthrax/scream/releases Scream] virtual audio driver on the guest. <br />
If you have secure boot enabled for your VM, you may need to disable it. <br />
<br />
Using the registry editor, set the DWORD {{ic|HKLM\SYSTEM\CurrentControlSet\Services\Scream\Options\UseIVSHMEM}} to the size of the IVSHMEM device in MB.<br />
Note that scream identifies its IVSHMEM device using its size, so make sure there is only one device of that size.<br />
<br />
====== Configuring the host ======<br />
<br />
Install {{AUR|scream}}.<br />
<br />
Create a [[systemd/User|systemd user service]] to control the receiver:<br />
<br />
{{hc|~/.config/systemd/user/scream-ivshmem-pulse.service|2=<br />
[Unit]<br />
Description=Scream IVSHMEM pulse receiver<br />
After=pulseaudio.service<br />
Wants=pulseaudio.service<br />
<br />
[Service]<br />
Type=simple<br />
ExecStartPre=/usr/bin/truncate -s 0 /dev/shm/scream-ivshmem<br />
ExecStartPre=/usr/bin/dd if=/dev/zero of=/dev/shm/scream-ivshmem bs=1M count=2<br />
ExecStart=/usr/bin/scream -m /dev/shm/scream-ivshmem<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
Edit {{ic|1=count=2}} with the size of the IVSHMEM device in MiB.<br />
<br />
{{Tip|If you are using [[PipeWire]], replace {{ic|pulseaudio.service}} with {{ic|pipewire-pulse.service}}.}}<br />
<br />
Now start the service with:<br />
<br />
$ systemctl start --user scream-ivshmem-pulse<br />
<br />
To have it automatically start on next login, enable the service:<br />
<br />
$ systemctl enable --user scream-ivshmem-pulse<br />
<br />
=== Physical disk/partition ===<br />
<br />
Raw and qcow2 especially can have noticeable overhead for heavy IO. A whole disk or a partition may be used directly to bypass the filesystem and improve I/O performance. If you wish to dual boot the guest OS natively you would need to pass the entire disk without any partitioning. It is suggested to use /dev/disk/by- paths to refer to the disk since /dev/sdX entries can change between boots. To find out which disk/partition is associated with the one you would like to pass:<br />
<br />
{{hc|$ ls -l /dev/disk/by-id|<br />
ata-ST1000LM002-9VQ14L_Z0501SZ9 -> ../../sdd<br />
}}<br />
<br />
See [[#Virtio disk]] on how to add these with libvirt XML. You can also add the disk with Virt-Manager's '''Add Hardware''' menu and then type the disk you want in the '''Select or create custom storage''' box, e.g. '''/dev/disk/by-id/ata-ST1000LM002-9VQ14L_Z0501SZ9'''<br />
<br />
=== Gotchas ===<br />
<br />
==== Passing through a device that does not support resetting ====<br />
<br />
When the VM shuts down, all devices used by the guest are deinitialized by its OS in preparation for shutdown. In this state, those devices are no longer functional and must then be power-cycled before they can resume normal operation. Linux can handle this power-cycling on its own, but when a device has no known reset methods, it remains in this disabled state and becomes unavailable. Since Libvirt and Qemu both expect all host PCI devices to be ready to reattach to the host before completely stopping the VM, when encountering a device that will not reset, they will hang in a "Shutting down" state where they will not be able to be restarted until the host system has been rebooted. It is therefore recommended to only pass through PCI devices which the kernel is able to reset, as evidenced by the presence of a {{ic|reset}} file in the PCI device sysfs node, such as {{ic|/sys/bus/pci/devices/0000:00:1a.0/reset}}.<br />
<br />
The following bash command shows which devices can and cannot be reset.<br />
<br />
{{hc|<nowiki>for iommu_group in $(find /sys/kernel/iommu_groups/ -maxdepth 1 -mindepth 1 -type d);do echo "IOMMU group $(basename "$iommu_group")"; for device in $(\ls -1 "$iommu_group"/devices/); do if [[ -e "$iommu_group"/devices/"$device"/reset ]]; then echo -n "[RESET]"; fi; echo -n $'\t';lspci -nns "$device"; done; done</nowiki>|<br />
IOMMU group 0<br />
00:00.0 Host bridge [0600]: Intel Corporation Xeon E3-1200 v2/Ivy Bridge DRAM Controller [8086:0158] (rev 09)<br />
IOMMU group 1<br />
00:01.0 PCI bridge [0604]: Intel Corporation Xeon E3-1200 v2/3rd Gen Core processor PCI Express Root Port [8086:0151] (rev 09)<br />
01:00.0 VGA compatible controller [0300]: NVIDIA Corporation GK208 [GeForce GT 720] [10de:1288] (rev a1)<br />
01:00.1 Audio device [0403]: NVIDIA Corporation GK208 HDMI/DP Audio Controller [10de:0e0f] (rev a1)<br />
IOMMU group 2<br />
00:14.0 USB controller [0c03]: Intel Corporation 7 Series/C210 Series Chipset Family USB xHCI Host Controller [8086:1e31] (rev 04)<br />
IOMMU group 4<br />
[RESET] 00:1a.0 USB controller [0c03]: Intel Corporation 7 Series/C210 Series Chipset Family USB Enhanced Host Controller #2 [8086:1e2d] (rev 04)<br />
IOMMU group 5<br />
[RESET] 00:1b.0 Audio device [0403]: Intel Corporation 7 Series/C210 Series Chipset Family High Definition Audio Controller [8086:1e20] (rev 04)<br />
IOMMU group 10<br />
[RESET] 00:1d.0 USB controller [0c03]: Intel Corporation 7 Series/C210 Series Chipset Family USB Enhanced Host Controller #1 [8086:1e26] (rev 04)<br />
IOMMU group 13<br />
06:00.0 VGA compatible controller [0300]: NVIDIA Corporation GM204 [GeForce GTX 970] [10de:13c2] (rev a1)<br />
06:00.1 Audio device [0403]: NVIDIA Corporation GM204 High Definition Audio Controller [10de:0fbb] (rev a1)<br />
}}<br />
<br />
This signals that the xHCI USB controller in 00:14.0 cannot be reset and will therefore stop the VM from shutting down properly, while the integrated sound card in 00:1b.0 and the other two controllers in 00:1a.0 and 00:1d.0 do not share this problem and can be passed without issue.<br />
<br />
== Complete setups and examples ==<br />
<br />
For many reasons users may seek to see [[PCI_passthrough_via_OVMF/Examples|complete passthrough setup examples]].<br />
<br />
These examples offer a supplement to existing hardware compatibility lists. Additionally, if you have trouble configuring a certain mechanism in your setup, you might find these examples very valuable. Users there have described their setups in detail, and some have provided examples of their configuration files as well. <br />
<br />
We encourage those who successfully build their system from this resource to help improve it by contributing their builds. Due to the many different hardware manufacturers involved, the seemingly significant lack of sufficient documentation, as well as other issues due to the nature of this process, community contributions are necessary.<br />
<br />
== Troubleshooting ==<br />
<br />
If your issue is not mentioned below, you may want to browse [[QEMU#Troubleshooting]].<br />
<br />
=== QEMU 4.0: Unable to load graphics drivers/BSOD/Graphics stutter after driver install using Q35 ===<br />
<br />
Starting with QEMU 4.0, the Q35 machine type changes the default {{ic|<nowiki>kernel_irqchip</nowiki>}} from {{ic|off}} to {{ic|split}} which breaks some guest devices, such as nVidia graphics (the driver fails to load / black screen / code 43 / graphics stutters, usually when mouse moving). Switch to full KVM mode instead by adding {{ic|<nowiki><ioapic driver='kvm'/></nowiki>}} under libvirt's {{ic|<nowiki><features></nowiki>}} tag in your VM configuration or by adding {{ic|<nowiki>kernel_irqchip=on</nowiki>}} in the {{ic|-machine}} QEMU arg.<br />
<br />
=== QEMU 5.0: host-passthrough with kernel version 5.5 to 5.8.1 when using Zen 2 processors: Windows 10 BSOD loop 'KERNEL SECURITY CHECK FAILURE' ===<br />
<br />
{{Note|As of kernel version 5.8.2, disabling STIBP is not required anymore.}}<br />
<br />
Starting with QEMU 5.0 virtual machines running on Zen 2 and newer kernels than 5.4 will cause a BSOD loop of: 'KERNEL SECURITY CHECK FAILURE'. This can be fixed by either updating to kernel version 5.8.2 or higher, or disabling STIBP:<br />
<cpu mode='host-passthrough' ...><br />
...<br />
<feature policy='disable' name='amd-stibp'/><br />
...<br />
</cpu><br />
This requires libvirt 6.5 or higher. On older versions, several workarounds exist:<br />
* Switch CPU mode from {{ic|host-passthrough}} to {{ic|host-model}}. This only works on libvirt 6.4 or lower.<br />
* Manually patch {{Pkg|qemu}} in order to revert [https://github.com/qemu/qemu/commit/143c30d4d346831a09e59e9af45afdca0331e819 this] commit.<br />
* On qemu commandline, add {{ic|1=amd-stibp=off}} to the cpu flags string. This can also be invoked through libvirt via a {{ic|<qemu:commandline>}} entry.<br />
<br />
=== "Error 43: Driver failed to load" with mobile (Optimus/max-q) nvidia GPUs ===<br />
<br />
This error occurs because the Nvidia driver wants to check the status of the power supply. If no battery is present, the driver does not work. Whether Libvirt or Quemu, by default none of them provide the possibility to simulate a battery. This might also result in a reduced screen resolution and the Nvidia Desktop Manager refusing to load when right-clicking the desktop, saying it requires Windows 10, a compatible GPU and the Nvidia graphics driver.<br />
<br />
You can however create and add a custom acpi table file to the virtual machine which will do the work.<br />
<br />
First you have to create the custom acpi table file by pasting the following base64 string [https://base64.guru/converter/decode/file here] and save the result file as SSDT1.dat:<br />
{{bc|<nowiki><br />
U1NEVKEAAAAB9EJPQ0hTAEJYUENTU0RUAQAAAElOVEwYEBkgoA8AFVwuX1NCX1BDSTAGABBMBi5f<br />
U0JfUENJMFuCTwVCQVQwCF9ISUQMQdAMCghfVUlEABQJX1NUQQCkCh8UK19CSUYApBIjDQELcBcL<br />
cBcBC9A5C1gCCywBCjwKPA0ADQANTElPTgANABQSX0JTVACkEgoEAAALcBcL0Dk=<br />
</nowiki>}}<br />
<br />
Next you must add the processed file to the main domain of the virtual machine:<br />
{{bc|<nowiki><br />
<domain xmlns:qemu="http://libvirt.org/schemas/domain/qemu/1.0" type="kvm"><br />
...<br />
<qemu:commandline><br />
<qemu:arg value="-acpitable"/><br />
<qemu:arg value="file=/path/to/your/SSDT1.dat"/><br />
</qemu:commandline><br />
</domain><br />
</nowiki>}}<br />
<br />
Make sure your XML file has the correct namespace in the {{ic|<domain>}} tag as visible above, otherwise the XML verification will fail.<br />
<br />
[https://www.reddit.com/r/VFIO/comments/ebo2uk/nvidia_geforce_rtx_2060_mobile_success_qemu_ovmf/ Source]<br />
<br />
=== "BAR 3: cannot reserve [mem]" error in dmesg after starting VM ===<br />
<br />
{{Expansion|This error is actually related to the boot_vgs issue and should be merged together with everything else concerning GPU ROMs.|section=UEFI (OVMF) Compatibility in VBIOS}}<br />
<br />
With respect to [https://www.linuxquestions.org/questions/linux-kernel-70/kernel-fails-to-assign-memory-to-pcie-device-4175487043/ this article]:<br />
<br />
If you still have code 43 check ''dmesg'' for memory reservation errors after starting up VM, if you have similar it could be the case:<br />
<br />
vfio-pci 0000:09:00.0: BAR 3: cannot reserve [mem 0xf0000000-0xf1ffffff 64bit pref]<br />
<br />
Find out a PCI Bridge your graphic card is connected to. This will give actual hierarchy of devices:<br />
<br />
$ lspci -t<br />
<br />
Before starting VM run following lines replacing IDs with actual from previous output.<br />
<br />
# echo 1 > /sys/bus/pci/devices/0000\:00\:03.1/remove<br />
# echo 1 > /sys/bus/pci/rescan<br />
<br />
{{Note|Probably setting [[kernel parameter]] {{ic|1=video=efifb:off}} is required as well. [https://pve.proxmox.com/wiki/Pci_passthrough#BAR_3:_can.27t_reserve_.5Bmem.5D_error Source]}}<br />
<br />
In addition try adding kernel parameter {{ic|1=pci=realloc}} which also [https://github.com/Dunedan/mbp-2016-linux/issues/60#issuecomment-396311301 helps with hotplugging issues].<br />
<br />
=== UEFI (OVMF) compatibility in VBIOS ===<br />
<br />
{{Remove|Flashing you guest GPU for the purpose of a GPU passthrough is '''never''' good advice. A full section should be dedicated to VBIOS compatibility.|section= UEFI (OVMF) Compatibility in VBIOS}}<br />
<br />
With respect to [https://pve.proxmox.com/wiki/Pci_passthrough#How_to_known_if_card_is_UEFI_.28ovmf.29_compatible this article]:<br />
<br />
Error 43 can be caused by the GPU's VBIOS without UEFI support. To check whenever your VBIOS supports it, you will have to use {{ic|rom-parser}}:<br />
<br />
$ git clone https://github.com/awilliam/rom-parser<br />
$ cd rom-parser && make<br />
<br />
Dump the GPU VBIOS:<br />
<br />
# echo 1 > /sys/bus/pci/devices/0000:01:00.0/rom<br />
# cat /sys/bus/pci/devices/0000:01:00.0/rom > /tmp/image.rom<br />
# echo 0 > /sys/bus/pci/devices/0000:01:00.0/rom<br />
<br />
And test it for compatibility:<br />
<br />
{{hc|$ ./rom-parser /tmp/image.rom|<br />
Valid ROM signature found @600h, PCIR offset 190h<br />
PCIR: type 0 (x86 PC-AT), vendor: 10de, device: 1184, class: 030000<br />
PCIR: revision 0, vendor revision: 1<br />
Valid ROM signature found @fa00h, PCIR offset 1ch<br />
PCIR: type 3 (EFI), vendor: 10de, device: 1184, class: 030000<br />
PCIR: revision 3, vendor revision: 0<br />
EFI: Signature Valid, Subsystem: Boot, Machine: X64<br />
Last image<br />
}}<br />
<br />
To be UEFI compatible, you need a "type 3 (EFI)" in the result. If it is not there, try updating your GPU VBIOS. GPU manufacturers often share VBIOS upgrades on their support pages. A large database of known compatible and working VBIOSes (along with their UEFI compatibility status!) is available on [https://www.techpowerup.com/vgabios/ TechPowerUp].<br />
<br />
Updated VBIOS can be used in the VM without flashing. To load it in QEMU:<br />
<br />
-device vfio-pci,host=07:00.0,......,romfile=/path/to/your/gpu/bios.bin \<br />
<br />
And in libvirt:<br />
<br />
{{bc|1=<br />
<hostdev><br />
...<br />
<rom file='/path/to/your/gpu/bios.bin'/><br />
...<br />
</hostdev><br />
}}<br />
<br />
One should compare VBIOS versions between host and guest systems using [https://www.techpowerup.com/download/nvidia-nvflash/ nvflash] (Linux versions under ''Show more versions'') or <br />
[https://www.techpowerup.com/download/techpowerup-gpu-z/ GPU-Z] (in Windows guest). To check the currently loaded VBIOS:<br />
<br />
{{hc|$ ./nvflash --version|<br />
...<br />
Version : 80.04.XX.00.97<br />
...<br />
UEFI Support : No<br />
UEFI Version : N/A<br />
UEFI Variant Id : N/A ( Unknown )<br />
UEFI Signer(s) : Unsigned<br />
...<br />
}}<br />
<br />
And to check a given VBIOS file:<br />
<br />
{{hc|$ ./nvflash --version NV299MH.rom|<br />
...<br />
Version : 80.04.XX.00.95<br />
...<br />
UEFI Support : Yes<br />
UEFI Version : 0x10022 (Jul 2 2013 @ 16377903 )<br />
UEFI Variant Id : 0x0000000000000004 ( GK1xx )<br />
UEFI Signer(s) : Microsoft Corporation UEFI CA 2011<br />
...<br />
}}<br />
<br />
If the external ROM did not work as it should in the guest, you will have to flash the newer VBIOS image to the GPU. In some cases it is possible to create your own VBIOS image with UEFI support using [https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html GOPUpd] tool, however this is risky and may result in GPU brick.<br />
<br />
{{Warning|Failure during flashing may "brick" your GPU - recovery may be possible, but rarely easy and often requires additional hardware. '''DO NOT''' flash VBIOS images for other GPU models (different boards may use different VBIOSes, clocks, fan configuration). If it breaks, you get to keep all the pieces.}}<br />
<br />
In order to avoid the irreparable damage to your graphics adapter it is necessary to unload the NVIDIA kernel driver first:<br />
<br />
# modprobe -r nvidia_modeset nvidia <br />
<br />
Flashing the VBIOS can be done with:<br />
<br />
# ./nvflash romfile.bin<br />
<br />
{{Warning|'''DO NOT''' interrupt the flashing process, even if it looks like it is stuck. Flashing should take about a minute on most GPUs, but may take longer.}}<br />
<br />
=== Slowed down audio pumped through HDMI on the video card ===<br />
<br />
For some users VM's audio slows down/starts stuttering/becomes demonic after a while when it is pumped through HDMI on the video card. This usually also slows down graphics.<br />
A possible solution consists of enabling MSI (Message Signaled-Based Interrupts) instead of the default (Line-Based Interrupts).<br />
<br />
In order to check whether MSI is supported or enabled, run the following command as root:<br />
<br />
# lspci -vs $device | grep 'MSI:'<br />
<br />
where `$device` is the card's address (e.g. `01:00.0`).<br />
<br />
The output should be similar to:<br />
<br />
Capabilities: [60] MSI: Enable'''-''' Count=1/1 Maskable- 64bit+<br />
<br />
A {{ic|-}} after {{ic|Enable}} means MSI is supported, but not used by the VM, while a {{ic|+}} says that the VM is using it.<br />
<br />
The procedure to enable it is quite complex, instructions and an overview of the setting can be found [https://forums.guru3d.com/showthread.php?t=378044 here].<br />
<br />
On a linux guest you can use modinfo to see if there is option to enable MSI (for example: "modinfo snd_hda_intel |grep msi"). If there is, one can enable it by adding the relevant option to a custom omdprobe file - in "/etc/modprobe.d/snd-hda-intel.conf" inserting "options snd-hda-intel enable_msi=1"<br />
<br />
Other hints can be found on the [https://lime-technology.com/wiki/index.php/UnRAID_6/VM_Guest_Support#Enable_MSI_for_Interrupts_to_Fix_HDMI_Audio_Support lime-technology's wiki], or on this article on [https://vfio.blogspot.it/2014/09/vfio-interrupts-and-how-to-coax-windows.html VFIO tips and tricks].<br />
<br />
A UI tool called [https://github.com/CHEF-KOCH/MSI-utility MSI Utility (FOSS Version 2)] works with Windows 10 64-bit and simplifies the process.<br />
<br />
In order to fix the issues enabling MSI on the 0 function of a nVidia card ({{ic|01:00.0 VGA compatible controller: NVIDIA Corporation GM206 [GeForce GTX 960] (rev a1) (prog-if 00 [VGA controller])}}) was not enough; it will also be required to enable it on the other function ({{ic|01:00.1 Audio device: NVIDIA Corporation Device 0fba (rev a1)}}) to fix the issue.<br />
<br />
=== No HDMI audio output on host when intel_iommu is enabled ===<br />
<br />
If after enabling {{ic|intel_iommu}} the HDMI output device of Intel GPU becomes unusable on the host then setting the option {{ic|igfx_off}} (i.e. {{ic|1=intel_iommu=on,igfx_off}}) might bring the audio back, please read [https://www.kernel.org/doc/html/latest/x86/intel-iommu.html#graphics-problems intel-iommu.html] for details about setting {{ic|igfx_off}}.<br />
<br />
=== X does not start after enabling vfio_pci ===<br />
<br />
This is related to the host GPU being detected as a secondary GPU, which causes X to fail/crash when it tries to load a driver for the guest GPU. To circumvent this, a Xorg configuration file specifying the BusID for the host GPU is required. The correct BusID can be acquired from lspci or the Xorg log. [https://www.redhat.com/archives/vfio-users/2016-August/msg00025.html Source →]<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-intel.conf|<nowiki><br />
Section "Device"<br />
Identifier "Intel GPU"<br />
Driver "modesetting"<br />
BusID "PCI:0:2:0"<br />
EndSection<br />
</nowiki>}}<br />
<br />
=== Chromium ignores integrated graphics for acceleration ===<br />
<br />
Chromium and friends will try to detect as many GPUs as they can in the system and pick which one is preferred (usually discrete NVIDIA/AMD graphics). It tries to pick a GPU by looking at PCI devices, not OpenGL renderers available in the system - the result is that Chromium may ignore the integrated GPU available for rendering and try to use the dedicated GPU bound to the {{ic|vfio-pci}} driver, and unusable on the host system, regardless of whenever a guest VM is running or not. This results in software rendering being used (leading to higher CPU load, which may also result in choppy video playback, scrolling and general un-smoothness).<br />
<br />
This can be fixed by [[Chromium/Tips and tricks#Forcing specific GPU|explicitly telling Chromium which GPU you want to use]].<br />
<br />
=== VM only uses one core ===<br />
<br />
For some users, even if IOMMU is enabled and the core count is set to more than 1, the VM still only uses one CPU core and thread. To solve this enable "Manually set CPU topology" in {{ic|virt-manager}} and set it to the desirable amount of CPU sockets, cores and threads. Keep in mind that "Threads" refers to the thread count per CPU, not the total count.<br />
<br />
=== Passthrough seems to work but no output is displayed ===<br />
<br />
Make sure if you are using virt-manager that UEFI firmware is selected for your virtual machine. Also, make sure you have passed the correct device to the VM.<br />
<br />
=== Host lockup after VM shutdown ===<br />
<br />
This issue seems to primarily affect users running a Windows 10 guest and usually after the VM has been run for a prolonged period of time: the host will experience multiple CPU core lockups (see [https://bbs.archlinux.org/viewtopic.php?id=206050&p=2]). To fix this try enabling Message Signal Interrupts on the GPU passed through to the guest. A good guide for how to do this can be found in [https://forums.guru3d.com/threads/windows-line-based-vs-message-signaled-based-interrupts.378044/]. You can also download this application for windows here [https://github.com/TechtonicSoftware/MSIInturruptEnabler] that should make the process easier.<br />
<br />
=== Host lockup if guest is left running during sleep ===<br />
<br />
VFIO-enabled virtual machines tend to become unstable if left running through a sleep/wakeup cycle and have been known to cause the host machine to lockup when an attempt is then made to shut them down. In order to avoid this, one can simply prevent the host from going into sleep while the guest is running using the following libvirt hook script and systemd unit. The hook file needs executable permissions to work.<br />
<br />
{{hc|/etc/libvirt/hooks/qemu|<nowiki><br />
#!/bin/bash<br />
<br />
OBJECT="$1"<br />
OPERATION="$2"<br />
SUBOPERATION="$3"<br />
EXTRA_ARG="$4"<br />
<br />
case "$OPERATION" in<br />
"prepare")<br />
systemctl start libvirt-nosleep@"$OBJECT"<br />
;;<br />
"release")<br />
systemctl stop libvirt-nosleep@"$OBJECT"<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/libvirt-nosleep@.service|<nowiki><br />
[Unit]<br />
Description=Preventing sleep while libvirt domain "%i" is running<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/systemd-inhibit --what=sleep --why="Libvirt domain \"%i\" is running" --who=%U --mode=block sleep infinity<br />
</nowiki>}}<br />
<br />
=== Cannot boot after upgrading ovmf ===<br />
<br />
If you cannot boot after upgrading from {{Pkg|ovmf}}{{Broken package link|replaced by {{Pkg|edk2-ovmf}}}} version 1:r23112.018432f0ce-1 then you need to remove the old {{ic|*VARS.fd}} file in {{ic|/var/lib/libvirt/qemu/nvram/}}:<br />
<br />
# mv /var/lib/libvirt/qemu/nvram/vmname_VARS.fd /var/lib/libvirt/qemu/nvram/vmname_VARS.fd.old<br />
<br />
See {{Bug|57825}} for further details.<br />
<br />
=== QEMU via cli pulseaudio stuttering/delay ===<br />
<br />
Using following flags for the audio device and chipset might help if you are running into the stuttering/delay audio issues when running QEMU via cli:<br />
<br />
qemu-system-x86_64 \<br />
-machine pc-i440fx-3.0 \<br />
-device hda-micro \<br />
-soundhw hda \<br />
-...<br />
<br />
As noted in [[#QEMU 3.0 audio changes|QEMU 3.0 audio changes]]{{Broken section link}} the specified chipset will include a series of audio patches.<br />
<br />
Setting {{ic|QEMU_AUDIO_TIMER_PERIOD}} to values higher than 100 might also help (did not test value lower than 100).<br />
<br />
=== Bluescreen at boot since Windows 10 1803 ===<br />
<br />
Since Windows 10 1803 there is a problem when you are using "host-passthrough" as cpu model. The machine cannot boot and is either boot looping or you get a bluescreen.<br />
You can workaround this by:<br />
<br />
# echo 1 > /sys/module/kvm/parameters/ignore_msrs<br />
<br />
To make it permanently you can create a modprobe file {{ic|kvm.conf}}:<br />
<br />
options kvm ignore_msrs=1<br />
<br />
To prevent clogging up ''dmesg'' with "ignored rdmsr" messages you can additionally add:<br />
<br />
options kvm report_ignored_msrs=0<br />
<br />
=== AMD Ryzen / BIOS updates (AGESA) yields "Error: internal error: Unknown PCI header type ‘127’" ===<br />
<br />
AMD users have been experiencing breakage of their KVM setups after updating the BIOS on their motherboard. There is a kernel [https://clbin.com/VCiYJ patch], (see [[Kernel/Arch Build System]] for instruction on compiling kernels with custom patches) that can resolve the issue as of now (7/28/19), but this is not the first time AMD has made an error of this very nature, so take this into account if you are considering updating your BIOS in the future as a VFIO user.<br />
<br />
=== AMD GPU not resetting properly yielding "Error: internal error: Unknown PCI header type ‘127’" (Separate issue from the one above) ===<br />
<br />
Passing through an AMD GPU may result into a problem known as the "AMD reset bug". Upon power cycling the guest, the GPU does not properly reset its state which causes the device to malfunction until the host is also rebooted. This is usually paired with a "code 43" driver error in a Windows guest, and the message "Error: internal error: Unknown PCI header type '127'" in the libvirt log on the host.<br />
<br />
In the past, this meant having to use work-arounds to manually reset the GPU, or resorting to the use of kernel patches that were unlikely to land in upstream. Currently, the recommended solution that does not require patching of the kernel is to install {{AUR|vendor-reset-git}} or {{AUR|vendor-reset-dkms-git}} and making sure the 'vendor-reset' kernel module is loaded before booting the guest.<br />
<br />
{{Note| Make sure you do not have any of the AMD reset bug kernel patches installed if you are using {{AUR|vendor-reset-git}} or {{AUR|vendor-reset-dkms-git}}.}}<br />
<br />
=== Host crashes when hotplugging Nvidia card with USB ===<br />
<br />
If attempting to hotplug an Nvidia card with a USB port, you may have to blacklist the {{ic|i2c_nvidia_gpu}} driver. Do this by adding the line {{ic|blacklist i2c_nvidia_gpu}} to {{ic|/etc/modprobe.d/blacklist.conf}}.<br />
<br />
=== Host unable to boot and stuck in black screen after enabling vfio ===<br />
<br />
If debug kernel messages during boot are enabled by adding with the {{ic|debug ignore_loglevel}} [[kernel parameters]], you may see boot stuck with the last message similar to<br />
<br />
vfio-pci 0000:01:00.0: vgaarb: changed VGA decodes: olddecodes=io+mem,decodes=io+mem:owns=none<br />
<br />
This can be resolved by disconnecting the passthroughed GPU with your moniter. You may reconnect the passthroughed GPU to a moniter after host is booted.<br />
<br />
=== AER errors when passing through PCIe USB hub ===<br />
<br />
In some cases passing through a PCIe USB hub, such as one connected to the guest GPU, might fail with AER errors similar to the following:<br />
<br />
kernel: pcieport 0000:00:01.1: AER: Uncorrected (Non-Fatal) error received: 0000:00:01.1<br />
kernel: pcieport 0000:00:01.1: AER: PCIe Bus Error: severity=Uncorrected (Non-Fatal), type=Transaction Layer, (Requester ID)<br />
kernel: pcieport 0000:00:01.1: AER: device [8086:1905] error status/mask=00100000/00000000<br />
kernel: pcieport 0000:00:01.1: AER: [20] UnsupReq (First)<br />
kernel: pcieport 0000:00:01.1: AER: TLP Header: 00000000 00000000 00000000 00000000<br />
kernel: pcieport 0000:00:01.1: AER: device recovery successful<br />
<br />
=== Reserved Memory Region Reporting (RMRR) Conflict ===<br />
<br />
If you run into an issue passing through a device because of the BIOS's usage of RMRR, like the error below.<br />
<br />
vfio-pci 0000:01:00.1: Device is ineligible for IOMMU domain attach due to platform RMRR requirement. Contact your platform vendor.<br />
<br />
You can try the patches here: https://github.com/kiler129/relax-intel-rmrr<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=162768 Discussion on Arch Linux forums] | [https://archive.is/kZYMt Archived link]<br />
* [https://docs.google.com/spreadsheet/ccc?key=0Aryg5nO-kBebdFozaW9tUWdVd2VHM0lvck95TUlpMlE User contributed hardware compatibility list]<br />
* [https://pastebin.com/rcnUZCv7 Example script] from https://www.youtube.com/watch?v=37D2bRsthfI<br />
* [https://vfio.blogspot.com/ Complete tutorial for PCI passthrough]<br />
* [https://www.redhat.com/archives/vfio-users/ VFIO users mailing list]<br />
* [ircs://chat.freenode.net/vfio-users #vfio-users on freenode]<br />
* [https://www.youtube.com/watch?v=aLeWg11ZBn0 YouTube: Level1Linux - GPU Passthrough for Virtualization with Ryzen]<br />
* [https://www.reddit.com/r/VFIO /r/VFIO: A subreddit focused on vfio]<br />
* [https://github.com/intel/gvt-linux/wiki/GVTd_Setup_Guide GVT-d: passthrough of an entire integrated GPU]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Talk:PCI_passthrough_via_OVMF&diff=668138Talk:PCI passthrough via OVMF2021-05-07T03:59:53Z<p>Hexhu: /* Is amd_iommu=on, pt still needed? */ re:</p>
<hr />
<div>== Supported Hardware Table ==<br />
<br />
I think it would be a good idea to add a table of working / not working hardware like this:<br />
<br />
{| class="wikitable"<br />
! Motherboard<br />
! CPU<br />
! Host GPU<br />
! Client GPU<br />
! uname -r<br />
! ACS Override needed<br />
! Notes<br />
|-<br />
| [https://www.asus.com/Motherboards/Z170-A/ ASUS Z170-A]<br />
| Intel i7-6700K<br />
| Integrated<br />
| [https://www.asus.com/Graphics-Cards/STRIXGTX980TIDC3OC6GD5GAMING/ ASUS Strix GTX 980 Ti]<br />
| 4.3.3-3-ARCH<br />
| no<br />
| No problems<br />
|-<br />
| [http://asrock.com/mb/AMD/Fatal1ty%20X370%20Gaming%20X/index.asp Asrock Fatal1ty X370 Gaming X]<br />
| Ryzen 5 1600X<br />
| Nvidia GTX 480<br />
| Nvidia GTX 960<br />
| 4.14.14-1-ck<br />
| no<br />
| Couldn't get it to work with GTX 480 as guest GPU<br />
|-<br />
| <br />
| <br />
| <br />
| <br />
| <br />
| <br />
| <br />
|}<br />
<br />
--[[User:Phiresky|Phiresky]] ([[User talk:Phiresky|talk]]) 12:28, 29 January 2016 (UTC)<br />
<br />
: Well, there's: https://docs.google.com/spreadsheets/d/1LnGpTrXalwGVNy0PWJDURhyxa3sgqkGXmvNCIvIMenk/edit#gid=2 and it has (if I read it properly) 208 unique motherboards. I'm not sure if Wiki can handle such a long list. [[User:Annisar|Annisar]] ([[User talk:Annisar|talk]])<br />
<br />
: Huh, looks like I missed that. Yeah, that list is probably too long. Kind of unclean / hard to read and can't edit it though. [[User:Phiresky|Phiresky]] ([[User talk:Phiresky|talk]]) 13:20, 29 January 2016 (UTC)<br />
<br />
== Page rewrite ==<br />
<br />
I've fiddled a lot with vfio in the last few months and I've been thinking about restructuring this page based on the information I've gathered over time. Considering large chunks of the page date all the way back from wen it was first written, and that the structure of the page isn't as researched as what you'd find on the rest of the wiki, I think a restructuration could greatly improve the overall understability of the page. Here's the overall structure I had in mind :<br />
; Prerequisites<br />
; Setting up IOMMU<br />
: Enabling IOMMU<br />
: Ensuring that the groups are valid<br />
: Common mistakes/Gotchas<br />
; Isolating the GPU<br />
: Using vfio-pci (Reccomended, Linux 4.1+)<br />
: Using pci-stub (Legacy)<br />
: Common mistakes/Gotchas<br />
; Setting up QEMU-kvm<br />
: Using libvirt<br />
: Using the qemu command line<br />
; Troubleshooting<br />
: Error 43 in Windows on Nvidia cards<br />
: "Invalid ROM content" in dmesg when trying to claim the guest GPU<br />
: ...<br />
; Extras<br />
: ACS override patch<br />
: Improving performance on the VM<br />
<br />
I've already written a good chunk of what's left, but I'd like some feedback on the proposed structure and what's already there before I proceed.<br />
[[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 20:55, 8 April 2016 (UTC)<br />
<br />
:Due to a lack of technical background, I can't really comment on completeness of your draft TOC compared to what the article covers, but it reads very structured. I had a look over the last edits you already committed to the article. Well done, I only want to give a couple of hints: <br />
:# Please take care when moving sections and editing, best split the move into its own commit. It is very difficult for someone else (or yourself later) to follow-up on what has been done (see [[ArchWiki:Contributing#Do not make complex edits at once]]). <br />
:# Point 1 is particularly important if you decide content is outdated and remove it during the restructuring. Usually we put [[Template:Deletion]] to the part first. Maybe you can do that as well. However, during a restructure the content might be in the way. You can also use a temporary section e.g. "Obsoleted sections" to move the sections to for the time being. If you delete parts, please do so only per subsection (edit button next to the header). This way it is easier to figure via history what went where. <br />
:# For the language, simple one: We avoid contractions ([[Help:Style#Language register]]) <br />
:# Looking at the existing article, there are some sections (e.g. [[PCI passthrough via OVMF#Complete example for QEMU .28CLI-based.29 without libvirtd]]) with very very long code blocks. Too long for good reading. Two alternatives for those (if you need them in the anticipated structure): Either move the long example code blocks to the end of the article (e.g. the Extras section) and crosslink them from above, quoting only the required excerpts. Or quote as well, but move the actual full code to a non-ad-spoiled gist (e.g. gist.github.com). If you move them outside the wiki, please do the removal/replacement with the gist link in one edit (same reason as for deletions, thanks).<br />
:# In the other talk items there are a few suggestions, e.g. [[#Article_Specificity]] and [[#Supported_Hardware_Table]] that might be useful to consider going forward. <br />
:That said, I hope your push to restructure and refresh the article gets input and help from other contributors to this article. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:49, 18 April 2016 (UTC)<br />
<br />
:Thanks for all of the contributions, please remember to keep the scope of the page inside it's original design: to achieve PCI passthrough via OVMF. I would like to have the long blocks of code removed/relocated especially those that do not necessarily explain the actual process of getting passthrough to work. Thanks!<br />
:{{unsigned|20:42, 24 April 2016|Naruni}}<br />
<br />
::I think it may have lost some focus because OVMF was not explicitly pointed to in the intro. As suggested in [[#Article_Specificity]], it '''may''' be useful to split content unrelated to OVMF into a separate article, e.g. [[PCI passthrough]] and this article may stay single or become a subpage for it (e.g. [[PCI passthrough/OVMF]]), whatever is best to keep focus, while not duplicating instructions or loose contributions which are not directly OVMF related. <br />
::If you look at the above structure Victoire has worked out, does it contain sections you would consider out-of-scope for OVMF? <br />
::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 13:04, 26 April 2016 (UTC)<br />
<br />
:So I have reached the point where most of the structure is now in place and most of the work left is either related to adressing specific issues people are likely to encounter or rephrasing some parts to make them more readable, such as the part on setting up the guest OS, which could use some fleshing out.<br />
:I have also taken the liberty of adding a ''Performance Tuning'' section, which may or may not be out of place considering the scope of the article. I would appreciate some feedback on whether or this belongs here.<br />
:Also, both for the sake of readability and because I couldn't test the instructions myself, I removed most of the QEMU-related (without libvirt) instructions. While it seemed like a good decision at the time, I would like to get some feedback on this, as it is still a removal of potentially useful instructions (although some of them did seem dubtious).<br />
:[[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 14:07, 9 May 2016 (UTC)<br />
<br />
::I was hoping others with topic experience chime in to feedback, perhaps that happens still. Arguably the whole article is about performance tuning, so I would see the section you added in scope. It is an interesting read even for someone like me, who has not used any of this. For the QEMU point I'm unable to give feedback. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 08:02, 30 June 2016 (UTC)<br />
<br />
::I agree that some of the QEMU scripts removed from the article were too detailed and still not explained well enough, but originally when I was setting up my passthrough system with the help of this article, I preferred the scripted way instead of libvirt and still do after a long good experience with the method. At the time the scripts in the article pointed me to the right direction. I'd really like to contribute to the article with smaller and simpler script examples with decent explanations for using every core parameter needed for the VM started with QEMU commands, so anyone with an opinion about this please comment before I start working on it. The scripted way is great for many use cases and I really think it needs to be addressed better on this article. [[User:Nd43|Nd43]] ([[User talk:Nd43|talk]]) 07:28, 20 April 2017 (UTC)<br />
<br />
==Additionnal sections==<br />
In case I forget, I made a list of things I wanted to add to this article some time ago, I just haven't found the time to write those parts yet.<br />
<br />
* Performance tuning<br />
** Kernel config ([https://www.redhat.com/archives/vfio-users/2016-March/msg00081.html Volountary preemption], 1000 Hz timer frequency, [https://www.youtube.com/watch?v=G3jHP9kNjwc dynticks], halt_poll_ns, etc.)<br />
** Advanced CPUs features<br />
*** 1GB hugepages<br />
*** NUMA node assignment<br />
*** Hardware virtual interrupt management (AVIC/APICv)<br />
<s><br />
* Special Procedures<br />
** Using identical guest and host GPUs<br />
** Passing the boot GPU ([https://www.redhat.com/archives/vfio-users/2016-May/msg00224.html see here])<br />
** Bypassing the IOMMU groups (ACS override patch)<br />
* Additionnal devices<br />
** GPU soundcard (MSI interrupts)</s><br />
<br />
As of now, I don't have the sort of hardware that would allow me to test these special cases, so it's a bit hard for me to justify writing those sections, but it might be interesting to add those someday.<br />
<br />
[[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 02:16, 5 August 2016 (UTC)<br />
<br />
EDIT1 : [[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 03:10, 9 August 2016 (UTC)<br />
<br />
EDIT2 (Might need to revisit some of those now that Ryzen comes with most of these features) : [[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 00:09, 7 August 2017 (UTC)<br />
<br />
== hotplug gpu ==<br />
<br />
found something interresting for hotpluging the gpu without to restart x:<br />
<br />
http://arseniyshestakov.com/2016/03/31/how-to-pass-gpu-to-vm-and-back-without-x-restart/<br />
repo: https://gist.github.com/ArseniyShestakov/dc152d080c65ebaa6781<br />
<br />
It removes the card from the graphics driver module (here radeon) and add's it to the vfio-module.<br />
<br />
I'm currently testing this. <br />
{{unsigned| 22:25, 12 August 2016|Xtf}}<br />
<br />
:I have been using {{Pkg|bumblebee}} and {{Pkg|bbswitch}} for hot plugging my Nvidia GPU. It used to work flawlessly, but within the last year it broke and now it fails to unload the Nvidia driver properly. My current solution is to use the vfio_pci module and manually unload it when I want to run a native app on the dGPU. the VM seams to be able to unload nvidia if bumblebee is not using it. my setup is a work in progress, but I would like to see it mentioned here. [[User:U6bkep|U6bkep]] ([[User talk:U6bkep|talk]]) 16:08, 19 February 2019 (UTC)<br />
<br />
== Inaccurate hugepage advice ==<br />
<br />
The static hugepage section says:<br />
"On a VM with a PCI passthrough, however, it is not possible to benefit from transparent huge pages, as IOMMU requires that the guest's memory be allocated and pinned as soon as the VM starts. It is therefore required to allocate huge pages statically in order to benefit from them."<br />
<br />
This may have been true previously but in my experience (currently verified on an Ubuntu Trusty box with kernel 4.4) this is no longer accurate:<br />
<nowiki>gpu-hypervisor:~$ uname -a<br />
Linux rcgpudc1r54-07 4.4.0-59-generic #80~14.04.1-Ubuntu SMP Fri Jan 6 18:02:02 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux<br />
gpu-hypervisor:~$ ps auxww | grep qemu | grep -v qemu<br />
libvirt+ 105915 297 95.3 325650548 251763980 ? SLl Apr10 9725:30 /usr/bin/qemu-system-x86_64 -name instance-00000167 -S -machine pc-i440fx-xenial,accel=kvm,usb=off -cpu host -m 245760 -realtime mlock=off -smp 24,sockets=2,cores=12,threads=1 -object memory-backend-ram,id=ram-node0,size=128849018880,host-nodes=0,policy=bind -numa node,nodeid=0,cpus=0-11,memdev=ram-node0 -object memory-backend-ram,id=ram-node1,size=128849018880,host-nodes=1,policy=bind -numa node,nodeid=1,cpus=12-23,memdev=ram-node1 -uuid 87681aae-2bc7-4b2e-b17b-f407cf23701e -smbios type=1,manufacturer=OpenStack Foundation,product=OpenStack Nova,version=12.0.4,serial=4c4c4544-0059-4710-8036-c3c04f483832,uuid=87681aae-2bc7-4b2e-b17b-f407cf23701e,family=Virtual Machine -no-user-config -nodefaults -chardev socket,id=charmonitor,path=/var/lib/libvirt/qemu/domain-instance-00000167/monitor.sock,server,nowait -mon chardev=charmonitor,id=monitor,mode=control -rtc base=utc,driftfix=slew -global kvm-pit.lost_tick_policy=discard -no-hpet -no-shutdown -boot strict=on -device piix3-usb-uhci,id=usb,bus=pci.0,addr=0x1.0x2 -drive file=/var/lib/nova/instances/87681aae-2bc7-4b2e-b17b-f407cf23701e/disk,format=raw,if=none,id=drive-virtio-disk0,cache=none -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x4,drive=drive-virtio-disk0,id=virtio-disk0,bootindex=1 -drive file=/var/lib/nova/instances/87681aae-2bc7-4b2e-b17b-f407cf23701e/disk.eph0,format=raw,if=none,id=drive-virtio-disk1,cache=none -device virtio-blk-pci,scsi=off,bus=pci.0,addr=0x5,drive=drive-virtio-disk1,id=virtio-disk1 -netdev tap,fd=29,id=hostnet0,vhost=on,vhostfd=31 -device virtio-net-pci,netdev=hostnet0,id=net0,mac=fa:16:3e:5e:21:1c,bus=pci.0,addr=0x3 -chardev file,id=charserial0,path=/var/lib/nova/instances/87681aae-2bc7-4b2e-b17b-f407cf23701e/console.log -device isa-serial,chardev=charserial0,id=serial0 -chardev pty,id=charserial1 -device isa-serial,chardev=charserial1,id=serial1 -device usb-tablet,id=input0 -vnc 0.0.0.0:0 -k en-us -device cirrus-vga,id=video0,bus=pci.0,addr=0x2 -device vfio-pci,host=05:00.0,id=hostdev0,bus=pci.0,addr=0x6 -device vfio-pci,host=06:00.0,id=hostdev1,bus=pci.0,addr=0x7 -device vfio-pci,host=85:00.0,id=hostdev2,bus=pci.0,addr=0x8 -device vfio-pci,host=86:01.1,id=hostdev3,bus=pci.0,addr=0x9 -device vfio-pci,host=84:00.0,id=hostdev4,bus=pci.0,addr=0xa -device virtio-balloon-pci,id=balloon0,bus=pci.0,addr=0xb -msg timestamp=on<br />
gpu-hypervisor:~$ grep AnonHuge /proc/meminfo<br />
AnonHugePages: 246108160 kB</nowiki><br />
<br />
I don't have an Arch system to verify this on, but I don't expect it to be distro specific. Any objection to removing this?<br />
<br />
:Have you tested memory performance inside the VM? As in, statically allocated hugepages vs transparent, with VFIO devices bound and actively used inside the VM? [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 11:18, 13 April 2017 (UTC)<br />
<br />
== Using identical guest and host GPUs - did not work for me. ==<br />
<br />
I had to create the script vfio-pci-override.sh in bin, not sbin, or it would not find the file. (and update the modprobe and mkinitcpio accordingly)<br />
<br />
furthermore, I had to change the sys/devices path to search a directory deeper. The script /bin/vfio-pci-override.sh looks like this then:<br />
<br />
#!/bin/sh<br />
<br />
for i in /sys/devices/pci*/*/*/boot_vga; do<br />
if [ $(cat "$i") -eq 0 ]; then<br />
GPU="${i%/boot_vga}"<br />
AUDIO="$(echo "$GPU" | sed -e "s/0$/1/")"<br />
echo "vfio-pci" > "$GPU/driver_override"<br />
if [ -d "$AUDIO" ]; then<br />
echo "vfio-pci" > "$AUDIO/driver_override"<br />
fi<br />
fi<br />
done<br />
<br />
modprobe -i vfio-pci<br />
<br />
<br />
This situation is the only one that worked for me.<br />
[[User:Eggz|Eggz]] ([[User talk:Eggz|talk]]) 19:12, 14 April 2017 (UTC)<br />
<br />
== Passthrough via OVMF without libvirt ==<br />
<br />
I don't have a graphic card with UEFI fw to test this but it should work (with the ovmf package and not ovmf-git), please test and add it to the page if it does work.<br />
<br />
qemu-system-x86_64 \<br />
-enable-kvm \<br />
-m 8192 \<br />
-M q35 \<br />
-cpu host \<br />
-smp 4,sockets=1,cores=4,threads=1 \<br />
-vga none \<br />
-drive if=pflash,format=raw,readonly,file=/usr/share/ovmf/ovmf_code_x64.bin \<br />
-drive if=pflash,format=raw,file=/tmp/ovmf/qemu-vm-01/ovmf_vars_x64.bin \<br />
-device vfio-pci,host=05:00.0,addr=09.0,multifunction=on,x-vga=on \<br />
-device vfio-pci,host=05:00.1,addr=09.1 \<br />
-drive file=diskimg.qcow2,format=qcow2<br />
[[User:Dhead|Dhead]] ([[User talk:Dhead|talk]]) 15:58, 8 May 2017 (UTC)<br />
<br />
: And you should copy the vars first<br />
mkdir -p /tmp/ovmf/qemu_vm-01<br />
cp /usr/share/ovmf/ovmf_vars_x64.bin /tmp/ovmf/qemu_vm-01/ovmf_vars_x64.bin<br />
: [[User:Dhead|Dhead]] ([[User talk:Dhead|talk]]) 16:08, 8 May 2017 (UTC)<br />
<br />
: Oh, indeed the official ovmf package seems to be updated after a long while to include the variable files, at least I was told they were missing from it before. I'll test this out and do a writeup about it as I'm actually writing a draft for adding the scripted method back to the artictle, check here: [[User:Nd43/Scripted QEMU setup without libvirt]]. It's still incomplete but already it's also getting pretty big and detailed, any comments welcomed. Also I'm wondering if it should be a subpage or not when I finally start merging it back to this actual article. [[User:Nd43|Nd43]] ([[User talk:Nd43|talk]]) 08:19, 9 May 2017 (UTC)<br />
<br />
:: Nice guide but I don't think the ArchWiki is the right place for it, it's too specific and too detailed to be incorporated into this article and adding it as a subpage will end with duplicated content which will never be in sync.<br>The starting point of this article is that the user (an Arch user, not a copy-paste monkey) already gone through the QEMU article so everything not directly related to pci passing like systemd service, audio, putting all in a script should not be added to this article. So instead we should just add the very basic command switches related to using OVMF.<br><br>I might be a little digressing, but I also think this page should be torn down and reworked. All the performance tuning should be in its own subpage of the main QEMU article. Using OVMF instead of the default SeaBIOS also should be in a subpage (of QEMU). So we will be left with just the PCI passthrough stuff here. [[User:Dhead|Dhead]] ([[User talk:Dhead|talk]])<br />
<br />
::: How about mentioning just the passthrough switches for QEMU here? The <code>-device vfio-pci,host=...</code> ones, even OVMF isn't *required* for the passthrough to work (although it is easier to work with). Other than that, passthrough can be thrown in for just about any QEMU VM, and it's up to the guest OS to handle these devices somehow. Other QEMU args are specific to that VM. [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 10:09, 9 May 2017 (UTC)<br />
<br />
::::I agree, just adding the related QEMU command switches should be more than enough. p.s. OVMF might be preferred for VGA PCI passthrough as at least on my system SeaBIOS seems to have some issues with USB input devices on boot/in bootloader (not an issue when the OS/kernel is running).[[User:Dhead|Dhead]] ([[User talk:Dhead|talk]]) 12:05, 9 May 2017 (UTC)<br />
<br />
::: You're probably right, but I still think many details of my writeup should be easily available for Arch users looking just to deploy a QEMU VM with PCI passthrough. I also agree that the whole article needs a rewrite on some parts but I really don't want to see the actually relevant information get removed temporarily or buried behind too many internal links to other articles. I've already seen how the article has suffered during the few years and currently its structure is partly very unclear. Does anyone have additional suggestions for the information to be added or should I just start editing with small additions to see how they're received? [[User:Nd43|Nd43]] ([[User talk:Nd43|talk]]) 18:44, 9 May 2017 (UTC)<br />
<br />
:::: Passing through the GPUs to a ready VM is just about adding those two switches and making sure you have some "extras" in if you're using a specific setup (GeForces requiring the spoofed vendor ID, etc). It might make more sense to let people configure their VM first (= installing OS under UEFI, installing VirtIO drivers, configuring their base environment etc) and THEN explain how to pass through the GPU to that ready VM - this might fit pretty well in this article.<br />
<br />
:::: Most of these copy-n-paste guides assume a very specific setup (memory, CPU cores, disks, etc), and there is value in those, since you can peek at complete solutions that are known to work under specific hardware combinations. However I'd rather create a separate VFIO "examples" page, where a brief description of that user's hardware, software (kernel + cmdline, additional VM configuration steps, etc) and the QEMU script/libvirt domain file would be posted. Exact specifics (additional scripts, configuration files for Synergy, PulseAudio and such) would have to be posted on GitHub/GitLab/somewhere else as to not clutter the wiki beyond reason (older examples would have to be removed or updated over time, since QEMU/libvirt break things once in a while). Does that sound fine? [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 21:55, 10 May 2017 (UTC)<br />
<br />
::::: I like your thinking. I made an initial revision edit at [[PCI passthrough via OVMF#Plain QEMU without libvirt]] describing the bare minimum for achieving a practical QEMU setup with links to other relevant articles. I'm probably going to continue editing the section later as I want to pay attention to some details and terminology a bit more, but for now I think it will do for provoking people to make additions/changes to reach better guidance on the topic. So, comments and edits highly welcomed. I also removed the old links for the time being, even though I really liked Melvin's script examples, they indeed belong to the "See also" section or somewhere else totally. Feel free to relocate the links to a logical order. [[User:Nd43|Nd43]] ([[User talk:Nd43|talk]]) 15:32, 13 May 2017 (UTC)<br />
<br />
:::::: I've created the [[PCI_passthrough_via_OVMF/Examples]] page, feel free to contribute your working setups there. There's a template etc available to make adding new entries easier and more consistent. [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 14:37, 19 May 2017 (UTC)<br />
<br />
== Moving the full tutorial elsewhere? ==<br />
<br />
A number of people on this talk page have already mentioned how having a complete tutorial like this on the Arch Wiki makes some parts of the article somewhat redundant with other pages on the wiki, and that it would probably be better if the article were split into multiple parts and spread across a number of pages. At the same time, having a full tutorial like this here means it can't really cover other distros without breaking the contribution guidelines, which limits the article's reach somewhat.<br />
<br />
However, I know a lot of people (myself included) have been convinced to try Arch after seeing a number of quality articles on the official wiki, and from what I've seen elsewhere, this very article has been this to some people. I've seen people on [https://www.reddit.com/r/VFIO/ /r/vfio] and elsewhere use this article as their primary reference for people who want to setup their machine this way. That's somewhat what I was aiming for when I started reworking this article to try and adapt [http://vfio.blogspot.com AW's blog] into something that's less intimidating to read, and it's great to see it has managed to evolve into what it is now thanks to all the contributions that have happened since then.<br />
<br />
I'd like to know, according to more experienced Arch Wiki contributors than me, whether or not this article actually belongs here, or if the current page shouldn't be moved to the VFIO subreddit and the Arch page torn down and its content split on other QEMU-related pages.<br />
<br />
[[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 14:56, 10 July 2017 (UTC)<br />
<br />
:IMO this article is fine here - it's widely linked, kept mostly up-to-date, clearly explained and doesn't require two days of research to even attempt this setup. I would agree making an exception and allowing other distro-specific information to be posted here would be great, but moving the entire post to /r/vfio, where the wiki pages don't work on mobile and limit contributors to the subreddit's moderators or manually added people will limit the article's reach even more and cause it to go out-of-date in a few months. (If the wiki is open to all registered redditors, most more-popular wiki pages *will* be defaced.) [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 12:24, 11 July 2017 (UTC)<br />
<br />
:Victoire, this is the Arch Wiki, users of other distros will be better served with full tutorials elsewhere, /r/VFIO has a wiki.<br>Regarding your choice of words, the page shouldn't be moved anywhere, copied somewhere else, yes, there you could just have a simple full tutorial from start to finish to set a host and guest QEMU machines with GPU passthrough, but the contents of this page should stay here so Arch Wiki users and maintainers could change it as needed, which I gather it's what you meant by "moved". In fact, from the little I've been seeing in /r/VFIO there are nice examples and tutorials that are buried and not being mentioned and linked in the /r/VFIO wiki.<br>Regards the needed updates to this page, first start, I would say the Performance tuning needs to go into the Tips and tricks in the QEMU page (which deserve its own subpage), the article name should be changed to PCI passthrough so it would reflect the actual content of the page which isn't UEFI specific.<br>Also, the complete examples page seems superfluous, why not have a wiki page in /r/VFIO with known compatible MB, or MB+GPU setups as all rest of the devices (recent CPU, RAM, storage) shouldn't matter, I wouldn't be surprised if the moderators would remove it.[[User:Dhead|Dhead]] ([[User talk:Dhead|talk]]) 14:05, 11 July 2017 (UTC)<br />
<br />
The one downside of having it here is that users that are not using arch as their daily driver can't contribute particularly easily because of the captchas. I stopped maintaining my Arch install a few months ago, so I had to have a friend run the `pacman -V|base32|head -1` on my behalf. Obviously, this is normally fine. This is ArchWiki lol. But this page is pretty general, so non-Arch user contributions have more friction that you might otherwise expect.<br />
[[User:Srutherford|Srutherford]] ([[User talk:Srutherford|talk]]) 01:35, 22 October 2019 (UTC)<br />
<br />
== Set firmware to UEFI ==<br />
<br />
>"In the "Overview" section, set your firmware to "UEFI". If the option is grayed out, make sure that you have correctly specified the location of your firmware in /etc/libvirt/qemu.conf and restart libvirtd.service."<br />
<br />
I see the Overview section, but I do not see "firmware" or "UEFI" anywhere on that section. There is nothing "grayed out". I only see:<br />
*Name<br />
*UUID<br />
*Status<br />
*Title<br />
*Description<br />
*Hypervisor<br />
*Architecture<br />
*Emulator<br />
*Chipset (i440FX or Q35 are the options)<br />
<br />
This makes me think the information could be outdated. I am not able to proceed and I suspect this to be the cause. [[User:Henstepl|Henstepl]] ([[User talk:Henstepl|talk]]) 19:57, 3 August 2017 (UTC)<br />
<br />
:This can be set only during the VM creation - check "Customize installation" on the final creation wizard screen and [https://i.imgur.com/73r2ctM.png the relevant option will show up]. If you can't select this during the VM creation, install `ovmf-git` or `ovmf`. [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 20:05, 3 August 2017 (UTC)<br />
::Yes, I am looking at exactly that, but there is no "Firmware" option at all. It just skips directly from "Emulator" to "Chipset". Nothing greyed out. Simply not there. [[User:Henstepl|Henstepl]] ([[User talk:Henstepl|talk]]) 23:07, 3 August 2017 (UTC)<br />
:::Are you sure you've got <code>ovmf</code> or <code>ovmf-git</code> installed? If you've built it yourself, make sure <code>/etc/libvirt/qemu.conf</code> contains the proper OVMF binary path: <code>nvram = [ "/usr/share/ovmf/x64/ovmf_x64.bin:/usr/share/ovmf/x64/ovmf_vars_x64.bin" ]</code> - there should be a section like this in that file, but commented and possibly with different paths. Point it at your OVMF binaries (<code>pacman -Ql ovmf or ovmf-git</code> will show all files in that package). [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 10:20, 4 August 2017 (UTC)<br />
::::Yes, ovmf has been installed from the start. <code>nvram = ["/usr/share/ovmf/ovmf_code_x64.bin:/usr/share/ovmf/ovmf_vars_x64.bin"]</code>, as contains the paths listed by <code>pacman -Ql ovfm</code>, has been in <code>/etc/libvirt/qemu.conf</code>. Thanks for your advice but it hasn't elucidated anything I've done wrong, and there still is no Firmware option. [[User:Henstepl|Henstepl]] ([[User talk:Henstepl|talk]]) 04:38, 5 August 2017 (UTC)<br />
:::::Okay, not sure why this option doesn't show up, but there's also a way to manually manipulate the domain XML file to use OVMF. [https://github.com/DragoonAethis/VFIO/blob/master/Windows8.1.xml#L18-L23 Here are the relevant lines], once you've created the VM, open your terminal and enter <code>sudo EDITOR=your-editor-like-nano-or-vim-or-somethign virsh edit your-domain-name</code> and make the <os> section there contain the <loader> and <nvram> entries pointing to proper OVMF files. If you're missing the vars file, [https://stuff.dragonic.eu/Windows8.1_VARS.fd here it is] from my VM. [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 11:39, 5 August 2017 (UTC)<br />
::::::I was hoping that a solution to this would help me avoid the error message I have been getting when I try to start my VM:<pre>Unable to complete install: 'internal error: process exited while connecting to monitor: 2017-08-03T03:20:54.793536Z qemu-system-x86_64: -chardev pty,id=charserial0: char device redirected to /dev/pts/2 (label charserial0)<br />
Could not access KVM kernel module: Permission denied<br />
failed to initialize KVM: Permission denied'<br />
<br />
Traceback (most recent call last):<br />
File "/usr/share/virt-manager/virtManager/asyncjob.py", line 88, in cb_wrapper<br />
callback(asyncjob, *args, **kwargs)<br />
File "/usr/share/virt-manager/virtManager/create.py", line 2288, in _do_async_install<br />
guest.start_install(meter=meter)<br />
File "/usr/share/virt-manager/virtinst/guest.py", line 477, in start_install<br />
doboot, transient)<br />
File "/usr/share/virt-manager/virtinst/guest.py", line 405, in _create_guest<br />
self.domain.create()<br />
File "/usr/lib/python2.7/site-packages/libvirt.py", line 1062, in create<br />
if ret == -1: raise libvirtError ('virDomainCreate() failed', dom=self)<br />
libvirtError: internal error: process exited while connecting to monitor: 2017-08-03T03:20:54.793536Z qemu-system-x86_64: -chardev pty,id=charserial0: char device redirected to /dev/pts/2 (label charserial0)<br />
Could not access KVM kernel module: Permission denied<br />
failed to initialize KVM: Permission denied</pre><br />
::::::Which prevents me from creating a VM with those settings... Welp. Maybe I will just reinstall everything from the start. [[User:Henstepl|Henstepl]] ([[User talk:Henstepl|talk]]) 05:48, 7 August 2017 (UTC)<br />
<br />
I had the same issue, fixed it by forcing the kvm gid to 78, an update of systemd give kvm group a dynamic id while libvirtd expect to be 78. <code>groupmod -g 78 kvm</code> and a reboot fixed it (https://bbs.archlinux.org/viewtopic.php?id=228936) [[User:Makz|Makz]] ([[User talk:Makz|talk]]) 22:15, 9 September 2017 (UTC)<br />
<br />
== Boot GPU Passthrough ==<br />
<br />
I managed to pass the boot gpu (the only one in my system) by:<br />
* setting the GRUB option {{ic|<nowiki>GRUB_GFXPAYLOAD_LINUX=text</nowiki>}} (for example in /etc/default/grub)<br />
* and adding the kernel parameter {{ic|<nowiki>earlymodules=vfio-pci</nowiki>}} (although I'm not sure if that is necessary at all)<br />
<br />
That prevents the initramfs from initializing a graphical console on the boot gpu, allowing the VM to take over it directly after GRUB. However, you can't see your boot status and will have to type your LUKS password blind if you encrypted your root partition.<br />
<br />
The Hardware I used: AMD Ryzen 7 1700 CPU, Mainboard: Biostar X370GTN, Passthrough GPU: Nvidia GeForce GTX 970<br />
<br />
-- [[User:Dasisdormax|dasisdormax]] ([[User talk:Dasisdormax|talk]]) 11:33, 8 August 2017 (UTC)<br />
<br />
I followed the steps in the guide and added {{ic|<nowiki>video=efifb:off</nowiki>}} but then I saw messages like {{ic|<nowiki>Invalid PCI ROM header signature: expecting 0xaa55, got 0xffff</nowiki>}}. <br />
<br />
I resolved this by putting my main GPU in a secondary slot, putting a spare GPU in the primary slot, disabling all the vfio-pci stuff (i.e. letting nouveau load) and making a copy of the ROM from {{ic|<nowiki>/sys/devices/pci0000:40/0000:40:01.3/0000:41:00.0/rom</nowiki>}}. It's worth noting that ROM images from places like TechPowerup don't work because they use a different format, the one used by nvflash.<br />
<br />
Once I had the ROM image, I had to add {{ic|<nowiki><rom file='/path/to/rom'/></nowiki>}} to my domain XML and all was well.<br />
<br />
I used an AMD Threadripper 1920X, ASUS PRIME X399-A and MSI Gaming X GTX1080Ti.<br />
<br />
-- [[User:bobobo1618|bobobo1618]] ([[User talk:bobobo1618|talk]]) 15:43, 10 February 2018 (UTC+1)<br />
<br />
== Slow boot linked to the RAM amount ==<br />
<br />
> Windows 10 VM with hugepages, 16Gb ram = 1m40 from the start to login screen, same VM reduced to 1Gb ram = 10 seconds from start to login screen (i7-6900K + 64Gb DDR4-2133 non-ECC) brand new installation<br />
<br />
Same setup on a bi-Xeon + 64Gb DDR3-1600 ECC ram, 16Gb ram = 13 seconds, 1Gb = 13 seconds<br />
<br />
While the VM is booting, all assigned CPU are working at 100%<br />
<br />
Is the ECC ram help to boot faster ? Is it a OVMF related issue ? Maybe the virtual bios is checking the ram before starting the OS ?<br />
<br />
While it's loading, i have a black screen, i don't think the GPU is handled by the VM at this moment.<br />
<br />
I saw some users on forums having this issue and tried latest ovmf build but no fix so far.<br />
<br />
[[User:Makz|Makz]] ([[User talk:Makz|talk]]) 09:10, 10 September 2017 (UTC)<br />
<br />
:One year later finally found a way to get rid of this slow down.<br />
<br />
:In short, this slow down is because the arch kernel is preemptive by default, compiling the kernel without CONFIG_PREEMPT=y and with CONFIG_PREEMPT_VOLUNTARY=y fixed my issue.<br />
<br />
:Boot time is down to ~35 seconds instead of +3 minutes<br />
<br />
:[[User:Makz|Makz]] ([[User talk:Makz|talk]]) 14:52, 24 November 2018 (UTC)<br />
<br />
== Question about virtlogd and iommu=pt ==<br />
<br />
Is enabling virtlogd.socket optional? If so, that should be stated.<br />
<br />
Is iommu=pt only for AMD? It looks like that on this page https://www.linux-kvm.org/page/How_to_assign_devices_with_VT-d_in_KVM<br />
<br />
Their instructions says:<br />
<br />
intel_iommu=on # Intel only<br />
<br />
iommu=pt iommu=1 # AMD only<br />
<br />
{{Unsigned|19:59, 16 January 2018|Limero}}<br />
<br />
:virtlogd.socket must be enabled, libvirt will otherwise fail to start. iommu=pt is separate from the intel_iommu=on and amd_iommu=on - iommu=pt enables the IOMMU hardware (on any platform) only for the passthrough devices and lets all the other devices (not passed to the VMs) do whatever they want. The "normal" IOMMU mode is to isolate all devices and make sure all devices behave nicely (no writes out of their address space, DMA only to their assigned section of memory, etc), but this may cause problems on some older platforms. [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 20:27, 16 January 2018 (UTC)<br />
<br />
== Slowed down audio pumped through HDMI on the video card ==<br />
<br />
In this section it is mentioned that the "MSI_util" program does not work on windows 10 64-bit however in the page linked earlier[https://forums.guru3d.com/threads/windows-line-based-vs-message-signaled-based-interrupts.378044/] there is now a "MSI_util_v2" program available and this program did work, for me at least. I would love it if other people can test it and report back so I can update the page.<br />
<br />
[[User:Victorheld|Victorheld]] ([[User talk:Victorheld|talk]]) 11:21, 5 June 2018 (UTC)<br />
<br />
: I used it successfully on Windows 8.1 64-bit too, +1 for replacing it with v2. [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 12:02, 5 June 2018 (UTC)<br />
<br />
== UEFI (OVMF) Compatibility in VBIOS ==<br />
<br />
Sorry if I am using this wrong and for just butting in as a new user, but I spent quite a lot of time getting a VBIOS card '''without UEFI''' working, and I feel like this guide could be clearer. I have a HD5970 card currently passing through using OVMF / VFIO (not pci-stub) to Windows 10, without flashing the card, and it would appear that CrossFire is working as well in Windows.<br />
<br />
It is simply enough. Get the VBIOS file from the card itself, use GOPupD, pass through the updated ROM file in the VM XML using rom file=. Flashing should be a '''last resort''' (IMHO) due to the danger of bricking. I was going to just use pci-stub, but I do not have that kernel module for one reason or another, so I had to make VFIO work (I'm using Antergos with 4.17.2-1-ARCH #1 SMP PREEMPT kernel).<br />
<br />
There are always hidden dangers with flashing that can be avoided by using rom files in the XML. In my case, the HD5970 is dual GPU, and each GPU has a different device IDs and, it seems, slightly different VBIOS files. I did not know this going in (and this is what took me a while). Had I just flashed the same GOPupD VBIOS, I likely would have bricked my card (when I passed the wrong ROM files in the XML to each GPU it crashed the whole system, I would hate to see what it would have done if I flashed it to the card itself).<br />
<br />
I know that 8 year old hardware isn't everybody's concern, but the miracle of Linux is the breath of life it provides to older hardware. I'm using an i7 980x on a P6X58D Premium motherboard with 24GB of RAM ... I really don't feel a need to upgrade my rig when it still kicks butt. Eventually I am putting in a new GPU so I can use newer games and this will all seem very trivial to me, but may help other people unable to upgrade.<br />
<br />
Also, with my 5970 each GPU was in its own IOMMU group. I am not sure if all dual GPUs are like that, but perhaps telling people that dual GPUs may be split up may help them. I could not get the card to function until I separated the second GPU on that card, gave it to the VM, and gave it the correct GOPupD ROM file. I don't know where to ask this question, but I do wonder if this card could use one GPU for the host and one for the guest (same card, but it has a different IOMMU group for each GPU and has 2 x DVI and a mini-DP). That would be an interesting project. [[User:Dracodeus|Dracodeus]] ([[User talk:Dracodeus|talk]]) 09:53, 27 June 2018 (UTC)<br />
<br />
: The lack of instructions for this sort of thing is something I fully agree with. The article glosses over the topic of VBIOS and UEFI compatibility a whole bunch of times, but never really adresses it. It seems a lot of people (including myself, back in the days!!) run into strange VBIOS-related issues that the article does not adress and a number of sections are there to suggest ways to workaround them.<br />
<br />
: I'll mark those sections for cleanup/removal, this definitely needs to be adressed in the main article. [[User:Victoire|Victoire]] ([[User talk:Victoire|talk]]) 17:28, 28 July 2018 (UTC)<br />
<br />
== Change hupepages allocation in runtime ==<br />
<br />
In the "Static huge pages" section, the article states "Static huge pages lock down the allocated amount of memory, making it unavailable for applications that are not configured to use them". This is true. However, the amount of allocated hugepages can be modified in runtime, so the end result is you can allocate those pages just before starting the vm, and free them when it stops. Perhaps we should rewrite the warning or add a note.<br />
<br />
The amount of allocated pages can be seen and modified in `/sys/devices/system/node/nodeX/hugepages/hugepages-1048576kB/nr_hugepages`<br />
<br />
--[[User:Roobre|Roobre]] ([[User talk:Roobre|talk]]) 08:08, 16 August 2018 (UTC)<br />
<br />
: Yeah, it can be done like this. [https://github.com/DragoonAethis/VFIO/blob/c024f8e41fe8df71fcd67fbf5d02bf467e0e35f4/vfio.sh#L45 I do this in my setup.] The biggest problem with this is that after your system has been running for a while, it gets increasingly more difficult to find continuous blocks of free 1GBs of RAM to map as hugepages - in practice, if you're allocating larger amounts, it's possible only shortly after booting up. (Rebooting is an option, too.) While this could be mentioned, it would also have to contain a lot of warnings that this can behave rather erratically if you're not trying to allocate those right after booting, plus the exact behavior might be confusing (allocating hugepages occasionally fails for no user-visible reason, and the only way to check if that happened is just to manually check how many hugepages were allocated). [[User:DragoonAethis|DragoonAethis]] ([[User talk:DragoonAethis|talk]]) 19:09, 16 August 2018 (UTC)<br />
<br />
== QEMU 4.0: Unable to load ... install using Q35 - Other solutions ==<br />
<br />
I wrote the original KVM patches for [http://events17.linuxfoundation.org/sites/events/files/slides/Performant%20Security%20Hardening_0.pdf split irqchip] back in 2016. It should be possible to work around any issues with split irqchip by using MSIs. For Windows, you can configure this using the [https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/enabling-message-signaled-interrupts-in-the-registry registry]. If I'm not mistaken, Linux should be pretty light on the IOAPIC. I say this about Linux with some caution since I'm mostly familiar with VMs in Cloud, which have a different set of devices than physical machines (e.g. no USB, which the debian box I'm currently on actually does put across the IOAPIC).<br />
<br />
For the Passthrough VM I was using to play Apex Legends on Windows, I was able to get things working without issue after changing to using MSIs. I considered getting the synthetic interrupt controller/vapic working (which should also skip the potential perf issues with split irqchip), but I wanted to use what I wrote :P. I was also nervous that getting windows to use the SynIC might also clue the nvidia driver that it's being used in an VM.<br />
<br />
Obviously, since most users trust their VMs, using a kernel irqchip is fine. Disabling split irqchip is nowhere near as unsafe as the ACS override (which is also a workaround listed on this page). IOAPIC based interrupts will still have a high cost relative to physical hardware, but back of the envelope estimate is that the IOAPIC takes about 10x as long to talk to when it's up in usermode, which is pretty substantial if it's actually perf critical.<br />
<br />
I considered just writing a description of working around split irqchip directly into the topic, but I don't really know the norms for wikis and it seemed like a bad plan to shill my own work in my first post.<br />
<br />
If anyone is willing to go test out the SynIC as a work around I'd be pretty curious to hear results. I'd also be curious if someone tested out A/B testing MSIs against kernel irqchip. If anyone has gotten posted interrupts to work with MSIs to cut down the latency to be as low as possible, that'd be pretty cool to hear about as well.<br />
<br />
[[User:Srutherford|Srutherford]] ([[User talk:Srutherford|talk]]) 01:30, 22 October 2019 (UTC)<br />
<br />
== Is amd_iommu=on, pt still needed? ==<br />
<br />
They're not configured in my grub but dmesg shows iommu is active anyway.<br />
Also is amd_iommu=on valid? it's not listed as an option https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/kernel-parameters.txt#L286<br />
[[User:Beepboo|Beepboo]] ([[User talk:Beepboo|talk]]) 20:02, 20 March 2020 (UTC)<br />
<br />
I don't think amd_iommu=on is valid anymore. It only takes 3 possible params as of 5.12.1: fullflush, off and force_isolation, so the default behavior is on.<br />
Relevant doc: https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html?highlight=amd_iommu<br />
Not sure about iommu=pt though.<br />
[[User:Hexhu|Hexhu]] ([[User talk:Hexhu|talk]]) 03:59, 7 May 2021 (UTC)<br />
<br />
== Error 43? ==<br />
<br />
Windows showed error 43. I tried may things - vbios (not this), moving PCI-e slots (didn't really help).<br />
Eventually... I followed this https://mathiashueber.com/fighting-error-43-nvidia-gpu-virtual-machine/ to get mine to work (RTX2070 super) - the hidden setting did it (along with the others) [[User:Beepboo|Beepboo]] ([[User talk:Beepboo|talk]]) 21:32, 20 March 2020 (UTC)<br />
<br />
== Moving virtio disk section to QEMU ==<br />
<br />
This page has a lot of details on both adding device block emulation with virtio, as well as passing through a SCSI drive. I consider this to be significant info, that [[QEMU#Installing virtio drivers]] does not have. As far as I can tell, this doesn't necessarily pertain to PCI passthrough, so I feel that [[PCI passthrough via OVMF#Virtio disk]] should be merged with [[QEMU]]. ~ [[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 13:15, 25 March 2020 (UTC)<br />
<br />
:There is indeed a lot of overlap and offtopic info on this page and much of this info would also make sense on other pages like [[QEMU]] or [[libvirt]]. However around two thirds of the PCI Passthrough page is already completly unrelated to passthrough. The PCI Passthrough page has sort of morphed into a "Gaming VM" guide over the years and the perhaps the primary page most people look at for setup, tuning, and dealing with virtualization realated quirks. In that context its good for people to see the info here. It's certainly not the first time someone has brought up reorganizing all this info onto other pages or perhaps making an entirely new topic for optimization & quirks. [[User:Aiber|Aiber]] ([[User talk:Aiber|talk]]) 14:48, 25 March 2020 (UTC)<br />
<br />
::That's not an argument against the merge, you can just leave a link to the relevant section of the [[QEMU]] page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:17, 25 March 2020 (UTC)<br />
<br />
== vesafb claiming GPU == <br />
<br />
I spent a lot of time trying to solve [[PCI_passthrough_via_OVMF#"BAR_3:_cannot_reserve_[mem]"_error_in_dmesg_after_starting_VM]], and the solution didn't come from the Wiki. I would like to bring some more information about the steps i follow to diagnose the issue, and how i solved the error (basically cat /proc/iomem to detect that vesafb was claiming memory, and kernel parameters different than {{ic|1=video=efifb:off}} thas is proposed in the wiki. <br />
<br />
The solution provided by the wiki was not really helpful to me.<br />
<br />
As a beginner in wiki edition, and because the section is already marked for merge with VBIOS issues, and also because I don't know if vesafb claiming for the GPU is actually related to VBios, I would like some feedback or advices before making any changes to this section. <br />
So, do you think that i should edit this section to propose a way to diagnose the issue by checking /proc/iomem, and propose some other kernel parameters ?<br />
<br />
{{unsigned|15:25, 12 July 2020|Mjfcolas}}<br />
<br />
== QEMU 5 & Zen2 with host-passthrough ==<br />
<br />
Now that we have added troubleshooting for Zen2 and QEMU 5, a warning about instability has been removed. I have done some testing and the Windows 10 crashes in less than an half hour. Tested this again with 'better' method that has been edited to the page with libvirt 6.5 and it still is unstable to do anything useful than run a single benchmark. I know the troubleshoot section for this important but do we really not want to warn users about its instability? [[User:Fireflower|Fireflower]] ([[User talk:Fireflower|talk]]) 16:43, 1 August 2020 (UTC)!<br />
<br />
== Elevated GPU driver VM detection mitigation from troubleshooting to main section ==<br />
<br />
I've moved hiding the KVM flag and vendor_id to the main sections of this page because I believe that the majority of the readers of this page need to perform this step in any case, since it affects both Nvidia and AMD. As always, feel free to disagree and suggest alternative approaches. --[[User:Jyf|Jyf]] ([[User talk:Jyf|talk]]) 08:20, 23 August 2020 (UTC)<br />
<br />
:I agree, the problem is common enough to be mentioned in about every possible guide. Especially since Windows VM gaming / cad working is become more popular thanks to knowledge being posted about it. I also strongly think any information regarding general stability should be left on the wiki instead being removed as unnecessary. It saves a lot time when people don't have to try figure out so much why their VM becomes unstable. [[User:Fireflower|Fireflower]] ([[User talk:Fireflower|talk]]) 16:25, 24 August 2020 (UTC)</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Install_Arch_Linux_from_existing_Linux&diff=654100Install Arch Linux from existing Linux2021-03-06T19:23:06Z<p>Hexhu: /* Method B: Using the LiveCD image */ update path to airootfs</p>
<hr />
<div>[[Category:Installation process]]<br />
[[de:Arch Linux auf einem Root-Server]]<br />
[[es:Install Arch Linux from existing Linux]]<br />
[[fr:Install chroot]]<br />
[[it:Install Arch Linux from existing Linux]]<br />
[[ja:既存の Linux からインストール]]<br />
[[pt:Install Arch Linux from existing Linux]]<br />
[[ru:Install Arch Linux from existing Linux]]<br />
[[zh-hans:Install Arch Linux from existing Linux]]<br />
[[zh-hant:Install Arch Linux from existing Linux]]<br />
{{Related articles start}}<br />
{{Related|Install from SSH}}<br />
{{Related articles end}}<br />
<br />
This document describes the bootstrapping process required to install Arch Linux from a running Linux host system.<br />
After bootstrapping, the installation proceeds as described in the [[Installation guide]].<br />
<br />
Installing Arch Linux from a running Linux is useful for:<br />
<br />
* remotely installing Arch Linux, e.g. a (virtual) root server<br />
* replacing an existing Linux without a LiveCD (see [[#Replacing the existing system without a LiveCD]])<br />
* creating a new Linux distribution or [[Arch-based distributions|LiveMedia based on Arch Linux]]<br />
* creating an Arch Linux chroot environment, e.g. for a Docker base container<br />
* [[Diskless network boot NFS root|rootfs-over-NFS for diskless machines]]<br />
<br />
The goal of the bootstrapping procedure is to setup an environment from which the scripts from {{Pkg|arch-install-scripts}} (such as {{ic|pacstrap}} and {{ic|arch-chroot}}) can be run.<br />
<br />
If the host system runs Arch Linux, this can be achieved by simply installing {{Pkg|arch-install-scripts}}. If the host system runs another Linux distribution, you will first need to set up an Arch Linux-based chroot.<br />
<br />
{{Note|This guide requires that the existing host system be able to execute the new target Arch Linux architecture programs. This means it has to be an x86_64 host.}}<br />
<br />
{{Warning|Please make sure you understand each step before proceeding. It is easy to destroy your system or to lose critical data, and your service provider will likely charge a lot to help you recover. }}<br />
<br />
== Backup and preparation ==<br />
<br />
Backup all your data including mails, webservers, etc. Have all information at your fingertips. Preserve all your server configurations, hostnames, etc.<br />
<br />
Here is a list of data you will likely need:<br />
<br />
* IP address<br />
* hostname(s), (note: rootserver are mostly also part of the providers domain, check or save your {{ic|/etc/hosts}} before you delete)<br />
* DNS server (check {{ic|/etc/resolv.conf}})<br />
* SSH keys (if other people work on your server, they will have to accept new keys otherwise. This includes keys from your Apache, your mail servers, your SSH server and others.)<br />
* Hardware info (network card, etc. Refer to your pre-installed {{ic|/etc/modules.conf}} )<br />
* Grub configuration files.<br />
<br />
In general, it is a good idea to have a local copy of your original {{ic|/etc}} directory on your local hard drive.<br />
<br />
== From a host running Arch Linux ==<br />
<br />
Install the {{Pkg|arch-install-scripts}} package.<br />
<br />
Follow [[Installation guide#Mount the file systems]] to mount the filesystem that will be used for the root directory as well as all the other needed mount points. If you already use the {{ic|/mnt}} directory for something else, just create another directory such as {{ic|/mnt/install}} and use it as the mount point base for the rest of the installation.<br />
<br />
At this stage, Arch Linux can either be installed from scratch or it can mirror the host installation. The two options are described thereafter.<br />
<br />
=== Create a new Arch installation ===<br />
<br />
Follow [[Installation guide#Installation]].<br />
<br />
In the procedure, the first step, [[Installation guide#Select the mirrors]], can be skipped since the host should already have a correct mirrorlist.<br />
<br />
{{Tip|<br />
* In order to avoid redownloading all the packages, consider following [[Pacman/Tips and tricks#Network shared pacman cache]], or use ''pacstrap''<nowiki>'</nowiki>s {{ic|-c}} option to use your host machine's package cache.<br />
* When the grub boot-loader is used, the {{ic|grub-mkconfig}} may detect devices incorrectly. This will result in {{ic|Error:no such device}} when trying to boot from the stick. To solve this problem, from the host running Arch Linux, mount the newly installed partitions, ''arch-chroot'' to the new partition, then install and configure grub. The last step may require disabling ''lvmetad'' from {{ic|/etc/lvm/lvm.conf}} by setting {{ic|1=use_lvmetad=0}}.<br />
}}<br />
<br />
=== Create a copy of an existing Arch installation ===<br />
<br />
It is possible to replicate an existing Arch Linux installation by copying the host filesystem to the new partition and make some adjustments to it to make it bootable and unique.<br />
<br />
The first step is to copy the host files into the mounted new partition, for this, consider using the approach exhibited in [[rsync#Full system backup]].<br />
<br />
Then, follow the procedure described in [[Installation guide#Configure the system]] with some caveats and additional steps:<br />
<br />
* [[Installation guide#Time zone]], [[Installation guide#Localization]] and [[Installation guide#Root password]] can be skipped<br />
* [[Installation guide#Initramfs]] may be required in particular if changing filesystem, for example from [[ext4]] to [[Btrfs]]<br />
* Regarding [[Installation guide#Boot loader]], it is necessary to reinstall the bootloader<br />
* Delete {{ic|/etc/machine-id}} so that a new, unique one, is generated at the next boot<br />
<br />
If the mirrored Arch installation may be used within a different configuration or with another hardware, consider the following additional operations:<br />
<br />
* Use the CPU [[microcode]] update adapted to the target system during the step [[Installation guide#Boot loader]]<br />
* If any specific [[Xorg#Configuration]] was present on the host and may be incompatible with the target system, follow [[Moving an existing install into (or out of) a virtual machine#Disable any Xorg-related files]]<br />
* Make any other adjustment appropriate to the target system, like reconfiguring the network or the audio.<br />
<br />
== From a host running another Linux distribution ==<br />
<br />
There are multiple tools which automate a large part of the steps described in the following subsections. See their respective homepages for detailed instructions.<br />
<br />
* [https://github.com/tokland/arch-bootstrap arch-bootstrap] (Bash)<br />
* [https://github.com/gh2o/digitalocean-debian-to-arch digitalocean-debian-to-arch] (repartition disk, DigitalOcean specific)<br />
* [https://github.com/hartwork/image-bootstrap image-bootstrap] (Python)<br />
* [https://gitlab.com/drizzt/vps2arch vps2arch] (Bash)<br />
* [https://github.com/BiteDasher/archbashstrap archbashstrap] (Bash)<br />
<br />
The manual way is presented in the following subsections. The idea is to either get [[pacman]] working directly on the host system, or to run an Arch system inside the host system, with the actual installation being executed from the Arch system. The nested system is contained inside a chroot.<br />
<br />
=== Using pacman from the host system ===<br />
<br />
[https://git.archlinux.org/pacman.git/ Pacman] can be compiled on most Linux distributions, and used directly on the host system to bootstrap Arch Linux. The [https://git.archlinux.org/arch-install-scripts.git/about/ arch-install-scripts] should run without issues directly from the downloaded sources on any recent distribution.<br />
<br />
Some distributions provide a package for ''pacman'' and/or ''arch-install-scripts'' in their official repositories which can be used for this purpose. As of July 2020, Void Linux is known to provide the ''pacman'' package, and Alpine Linux and Fedora are known to provide both ''pacman'' and ''arch-install-scripts''.<br />
<br />
=== Creating a chroot ===<br />
<br />
Two methods to setup and enter the chroot are presented below, from the easiest to the most complicated. Select only one of the two methods. Then, continue at [[#Using a chroot environment]].<br />
<br />
==== Method A: Using the bootstrap image (recommended) ====<br />
<br />
Download the bootstrap image from a [https://archlinux.org/download mirror] into {{ic|/tmp}}. You can also download the signature (same URL with {{ic|.sig}} added) and [[GnuPG#Verify_a_signature|verify it with GnuPG]].<br />
<br />
Extract the tarball:<br />
<br />
# tar xzf <path-to-bootstrap-image>/archlinux-bootstrap-*-x86_64.tar.gz<br />
<br />
Select a repository server by editing {{ic|/tmp/root.x86_64/etc/pacman.d/mirrorlist}}.<br />
<br />
Enter the chroot:<br />
* If bash 4 or later is installed, and ''unshare'' supports the {{ic|--fork}} and {{ic|--pid}} options: {{bc|# /tmp/root.x86_64/bin/arch-chroot /tmp/root.x86_64/}}<br />
* Otherwise, run the following commands: {{bc|<nowiki><br />
# mount --bind /tmp/root.x86_64 /tmp/root.x86_64<br />
# cd /tmp/root.x86_64<br />
# cp /etc/resolv.conf etc<br />
# mount -t proc /proc proc<br />
# mount --make-rslave --rbind /sys sys<br />
# mount --make-rslave --rbind /dev dev<br />
# mount --make-rslave --rbind /run run # (assuming /run exists on the system)<br />
# chroot /tmp/root.x86_64 /bin/bash<br />
</nowiki>}}<br />
<br />
==== Method B: Using the LiveCD image ====<br />
<br />
It is possible to mount the root image of the latest Arch Linux installation media and then chroot into it. This method has the advantage of providing a working Arch Linux installation right within the host system without the need to prepare it by installing specific packages.<br />
<br />
{{Note|Before proceeding, make sure the latest version of [http://squashfs.sourceforge.net/ squashfs] is installed on the host system. Otherwise, errors like the following are to be expected: {{ic|FATAL ERROR aborting: uncompress_inode_table: failed to read block}}.}}<br />
<br />
The root image can be found on one of the [https://archlinux.org/download mirrors] under {{ic|iso/latest/arch/x86_64/}}. The squashfs format is not editable, so we unsquash the root image and mount it.<br />
<br />
To unsquash the root image, run<br />
<br />
# unsquashfs airootfs.sfs<br />
<br />
Select a repository server by editing {{ic|squashfs-root/etc/pacman.d/mirrorlist}}.<br />
<br />
Before [[Change root|chrooting]] to the unsquashed root image, we need to set up some mount points and copy the {{ic|resolv.conf}} for networking.<br />
<br />
# mount --bind squashfs-root squashfs-root<br />
# mount -t proc none squashfs-root/proc<br />
# mount -t sysfs none squashfs-root/sys<br />
# mount -o bind /dev squashfs-root/dev<br />
# mount -o bind /dev/pts squashfs-root/dev/pts ## important for pacman (for signature check)<br />
# cp -L /etc/resolv.conf squashfs-root/etc ## this is needed to use networking within the chroot<br />
<br />
Now, everything is prepared to chroot into the newly installed Arch environment:<br />
<br />
# chroot squashfs-root bash<br />
<br />
=== Using a chroot environment ===<br />
<br />
The bootstrap environment is really barebones (no {{Pkg|nano}} or {{Pkg|lvm2}}). Therefore, we need to set up pacman in order to download other necessary packages.<br />
<br />
==== Initializing pacman keyring ====<br />
<br />
Before starting the installation, pacman keys need to be setup. Before running the following two commands, read [[pacman-key#Initializing the keyring]] to understand the entropy requirements:<br />
<br />
# pacman-key --init<br />
# pacman-key --populate archlinux<br />
<br />
{{Tip|If you need to run {{ic|pacman-key --init}} on a computer that does not generate much entropy (e.g. a headless server), key generation may take a very long time. To generate pseudo-entropy, install either [[haveged]] or [[rng-tools]] '''on the host system''' and start the corresponding service before running {{ic|pacman-key --init}}. (Installing these services on the target system instead will not work, since ''systemd'' will [https://superuser.com/questions/688733/start-a-systemd-service-inside-chroot refuse to start services from a chroot] and you need to initialize the pacman keyring prior to installing any packages anyway.)<br />
<br />
If you prefer generating entropy through system activity and decide to run {{ic|ls -Ra /}} in another console (TTY, terminal, SSH session...), do not be afraid of running it in a loop a few times: five or six runs from the host proved sufficient to generate enough entropy on a remote headless server.<br />
}}<br />
<br />
==== Downloading basic tools ====<br />
<br />
[[Mirrors#Force_pacman_to_refresh_the_package_lists|Refresh the package lists]] and [[install]] what you need: {{Grp|base-devel}}, {{Pkg|parted}} etc.<br />
<br />
{{Note|When you try to install packages with pacman, you might get {{ic|''error: could not determine cachedir mount point /var/cache/pacman/pkg''}}. To workaround it, run {{bc|mount --bind ''directory-to-livecd-or-bootstrap'' ''directory-to-livecd-or-bootstrap''}} before chrooting. See {{Bug|46169}}.}}<br />
<br />
=== Installation tips ===<br />
<br />
You can now proceed to [[Installation guide#Partition the disks]] and follow the rest of the [[Installation guide]].<br />
<br />
Some host systems or configurations may require certain extra steps. See the sections below for tips.<br />
<br />
===== Debian-based host =====<br />
<br />
====== /dev/shm ======<br />
<br />
On some Debian-based host systems, ''pacstrap'' may produce the following error:<br />
<br />
{{hc|# pacstrap /mnt base|<br />
==> Creating install root at /mnt<br />
mount: mount point /mnt/dev/shm is a symbolic link to nowhere<br />
==> ERROR: failed to setup API filesystems in new root<br />
}}<br />
<br />
This is because in some versions of Debian, {{ic|/dev/shm}} points to {{ic|/run/shm}} while in the Arch-based chroot, {{ic|/run/shm}} does not exist and the link is broken. To correct this error, create a directory {{ic|/run/shm}}:<br />
<br />
# mkdir /run/shm<br />
<br />
====== /dev/pts ======<br />
<br />
While installing {{ic|archlinux-2015.07.01-x86_64}} from a Debian 7 host, the following error prevented both [https://projects.archlinux.org/arch-install-scripts.git/tree/pacstrap.in pacstrap] and [[Change root#Using arch-chroot|arch-chroot]] from working:<br />
<br />
{{hc|# pacstrap -i /mnt|<br />
mount: mount point /mnt/dev/pts does not exist<br />
==> ERROR: failed to setup chroot /mnt<br />
}}<br />
<br />
Apparently, this is because these two scripts use a common function. {{ic|chroot_setup()}}[https://projects.archlinux.org/arch-install-scripts.git/tree/common#n76] relies on newer features of {{Pkg|util-linux}}, which are incompatible with Debian 7 userland (see {{Bug|45737}}).<br />
<br />
The solution for ''pacstrap'' is to manually execute its [https://projects.archlinux.org/arch-install-scripts.git/tree/pacstrap.in#n77 various tasks], but use the [[Change root#Using_chroot|regular procedure]] to mount the kernel filesystems on the target directory ({{ic|"$newroot"}}):<br />
<br />
# newroot=/mnt<br />
# mkdir -m 0755 -p "$newroot"/var/{cache/pacman/pkg,lib/pacman,log} "$newroot"/{dev,run,etc}<br />
# mkdir -m 1777 -p "$newroot"/tmp<br />
# mkdir -m 0555 -p "$newroot"/{sys,proc}<br />
# mount --bind "$newroot" "$newroot"<br />
# mount -t proc /proc "$newroot/proc"<br />
# mount --rbind /sys "$newroot/sys"<br />
# mount --rbind /run "$newroot/run"<br />
# mount --rbind /dev "$newroot/dev"<br />
# pacman -r "$newroot" --cachedir="$newroot/var/cache/pacman/pkg" -Sy base base-devel ... ## add the packages you want<br />
# cp -a /etc/pacman.d/gnupg "$newroot/etc/pacman.d/" ## copy keyring<br />
# cp -a /etc/pacman.d/mirrorlist "$newroot/etc/pacman.d/" ## copy mirrorlist<br />
<br />
Instead of using ''arch-chroot'' for [[Installation guide#Chroot]], simply use:<br />
<br />
# chroot "$newroot"<br />
<br />
====== lvmetad ======<br />
<br />
Trying to create [[LVM]] [[LVM#Logical volumes|logical volumes]] from an {{ic|archlinux-bootstrap-2015.07.01-x86_64}} environment on a Debian 7 host resulted in the following error:<br />
<br />
{{hc|# lvcreate -L 20G lvm -n root|<br />
/run/lvm/lvmetad.socket: connect failed: No such file or directory<br />
WARNING: Failed to connect to lvmetad. Falling back to internal scanning.<br />
/dev/lvm/root: not found: device not cleared<br />
Aborting. Failed to wipe start of new LV.}}<br />
<br />
(Physical volume and volume group creation worked despite {{ic|/run/lvm/lvmetad.socket: connect failed: No such file or directory}} being displayed.)<br />
<br />
This could be easily worked around by creating the logical volumes outside the chroot (from the Debian host). They are then available once chrooted again.<br />
<br />
{{Accuracy|This problem did not arise when installing from a Debian 7 host without ''lvmetad'' enabled. The recommended messaround with {{ic|/etc/lvm/lvm.conf}} looks rather error prone (2015-07-26).}}<br />
<br />
Also, if the system you are using has lvm, you might have the following output:<br />
<br />
{{hc|1=# grub-install --target=i386-pc --recheck /dev/main/archroot|2=<br />
Installing for i386-pc platform.<br />
/run/lvm/lvmetad.socket: connect failed: No such file or directory<br />
WARNING: Failed to connect to lvmetad. Falling back to internal scanning.<br />
/run/lvm/lvmetad.socket: connect failed: No such file or directory<br />
WARNING: Failed to connect to lvmetad. Falling back to internal scanning.<br />
/run/lvm/lvmetad.socket: connect failed: No such file or directory<br />
WARNING: Failed to connect to lvmetad. Falling back to internal scanning.<br />
/run/lvm/lvmetad.socket: connect failed: No such file or directory<br />
WARNING: Failed to connect to lvmetad. Falling back to internal scanning.<br />
/run/lvm/lvmetad.socket: connect failed: No such file or directory<br />
WARNING: Failed to connect to lvmetad. Falling back to internal scanning.<br />
}}<br />
<br />
This is because debian does not use lvmetad by default. You need to edit {{ic|/etc/lvm/lvm.conf}} and set {{ic|use_lvmetad}} to {{ic|0}}:<br />
<br />
use_lvmetad = 0<br />
{{Accuracy|Is it the problem with LVM on Debian or with trying to install Arch on LVM?}}<br />
{{Style|poor style}}<br />
This will trigger later an error on boot in the initrd stage. Therefore, you have to change it back after the grub generation. In a software RAID + LVM, steps would be the following:<br />
<br />
* After installing the system, double check your [[Mkinitcpio]] and your bootloader settings. See [[Arch boot process#Boot loader]] for a list of bootloaders.<br />
* You may need to change your {{ic|/etc/mdadm.conf}} to reflect your [[RAID]] settings (if applicable).<br />
* You may need to change your {{ic|HOOKS}} and {{ic|MODULES}} according to your [[LVM]] and [[RAID]] requirements: {{ic|1=MODULES="dm_mod" HOOKS="base udev '''mdadm_udev''' ... block '''lvm2''' filesystems ..."}}<br />
* You will most likely need to generate new initrd images with mkinitcpio. See [[Mkinitcpio#Image creation and activation]].<br />
* Set {{ic|1=use_lvmetad = 0}} in {{ic|/etc/lvm/lvm.conf}}.<br />
* Update your bootloader settings. See your bootloader's wiki page for details.<br />
* Set {{ic|1=use_lvmetad = 1}} in {{ic|/etc/lvm/lvm.conf}}.<br />
<br />
===== Fedora-based host =====<br />
<br />
On Fedora based hosts and live USBs you may encounter problems when using ''genfstab'' to generate your [[fstab]]. Remove duplicate entries and the "seclabel" option where it appears, as this is Fedora-specific and will keep your system from booting normally.<br />
<br />
== Things to check before you reboot ==<br />
<br />
Before rebooting, doublecheck a few details in your installation to achieve a successful installation. To do so, first chroot into the newly-installed system, and then:<br />
<br />
* [[Users and groups#User management|create a user with password]], so you can login via ''ssh''. This is critical since root login is disabled by default since OpenSSH-7.1p2.<br />
* [[Users and groups#User management|set a root password]] so that you can switch to root via ''su'' later<br />
* [[install]] a [[ssh]] solution and [[enable]] its server instance to start automatically at boot.<br />
* set up your [[network configuration]] in order to have a connection started automatically at boot.<br />
* set up a [[boot loader]] and configure it to use the swap partition you appropriated earlier as the root partition. You might want to configure your bootloader to be able to boot into your old system; it is helpful to re-use the server's existing {{ic|/boot}} partition in the new system for this purpose.<br />
<br />
== Replacing the existing system without a LiveCD ==<br />
<br />
Find ~700 MB of free space somewhere on the disk, e.g. by partitioning a swap partition. You can disable the swap partition and set up your system there. <br />
<br />
===Set old swap partition as new root partition===<br />
<br />
Check {{ic|cfdisk}}, {{ic|/proc/swaps}} or {{ic|/etc/fstab}} to find your swap partition. Assuming your hard drive is located on {{ic|sda''X''}} ({{ic|''X''}} will be a number). <br />
<br />
Do the following:<br />
<br />
Disable the swap space:<br />
<br />
# swapoff /dev/sda''X''<br />
<br />
Create a filesystem on it<br />
<br />
# fdisk /dev/sda<br />
(set /dev/sda''X'' ID field to "Linux" - Hex 83)<br />
# mke2fs -j /dev/sda''X''<br />
<br />
Create a directory to mount it in<br />
<br />
# mkdir /mnt/newsys<br />
<br />
Finally, mount the new directory for installing the intermediate system.<br />
<br />
# mount -t ext4 /dev/sda''X'' /mnt/newsys<br />
<br />
=== Installation ===<br />
<br />
[[Installation guide#Install essential packages|Install essentials packages]] and any other package required to get a system with internet connection up and running in the temporary partition, being careful with the limit of ~700 MB space. When specifying packages to be installed with ''pacstrap'', consider adding the {{ic|-c}} flag to avoid filling up valuable space by downloading packages to the host system.<br />
<br />
Once the new Arch Linux system is installed, fix the bootloader configuration, then reboot into the newly created system, and [[rsync#Full system backup|rsync the entire system]] to the primary partition.</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_X1_Carbon_(Gen_8)&diff=641326Lenovo ThinkPad X1 Carbon (Gen 8)2020-11-11T07:20:17Z<p>Hexhu: Add audio section and fix ref to Talk#Microphone</p>
<hr />
<div>[[Category:Lenovo]]<br />
{{Related articles start}}<br />
{{Related|Lenovo ThinkPad X1 Carbon}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 2)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 3)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 4)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 5)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 6)}}<br />
{{Related|Lenovo ThinkPad X1 Carbon (Gen 7)}}<br />
{{Related|Lenovo ThinkPad X1 Yoga (Gen 3)}}<br />
{{Related|Lenovo ThinkPad X1 Yoga (Gen 4)}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|Too little content.}}<br />
<br />
The Lenovo ThinkPad X1 Carbon, 8th generation is an ultrabook introduced in early 2020. It features a 14" screen, 10th-gen Intel Core processors and integrated [[Intel graphics|Intel UHD 620 graphics]].<br />
<br />
To ensure you have this version, [[install]] the package {{Pkg|dmidecode}} and run:<br />
<br />
{{bc|# dmidecode -s system-version<br />
ThinkPad X1 Carbon Gen 8<br />
}}<br />
<br />
{{Tip|A great resource for thinkpads is https://www.thinkwiki.org/wiki/ThinkWiki}}<br />
<br />
{| class="wikitable" style="float: right; clear: right; margin: 0 0 0.5em 0.5em; max-width: 420px; width: 100%;"<br />
| '''Device''' || '''Working''' || '''Modules'''<br />
|-<br />
| [[Intel graphics]] || {{Yes}} || i915, (intel_agp)<br />
|-<br />
| [[Wireless network configuration#iwlwifi|Wireless network]] || {{Yes}} || iwlmvm<br />
|-<br />
| Native Ethernet with [https://www.lenovo.com/us/en/accessories-and-monitors/cables-and-adapters/adapters/CABLE-BO-Ethernet-Extension-Adapter-2/p/4X90Q84427 dongle] || {{Yes}} || ?<br />
|-<br />
| Mobile broadband Fibocom || {{Yes}}¹ || ?<br />
|-<br />
| Audio || {{Yes}} || snd_hda_intel<br />
|-<br />
| Microphone || {{Yes}}⁴ || snd_sof<br />
|-<br />
| [[Touchpad]] || {{Yes}} || psmouse, rmi_smbus, i2c_i801<br />
|-<br />
| [[TrackPoint]] || {{Yes}} || psmouse, rmi_smbus, i2c_i801<br />
|-<br />
| Camera || {{Yes}} || uvcvideo<br />
|-<br />
| [[fprint|Fingerprint reader]] || {{Yes}}² || ?<br />
|-<br />
| [[Power management]] || {{Yes}}³ || ?<br />
|-<br />
| [[Bluetooth]] || {{Yes}} || btusb<br />
|-<br />
| Keyboard backlight || {{Yes}} || thinkpad_acpi<br />
|-<br />
| NFC || {{No}}⁵ || ?<br />
|-<br />
| Function/Multimedia keys || {{Yes}} || ?<br />
|-<br />
| colspan=3 style="font-size: 70%; border: none;" | <ol><br />
<li>The Fibocom LTE module has Linux support once switched to USB mode; see [https://forums.lenovo.com/t5/Other-Linux-Discussions/How-To-Configure-X1-Carbon-Gen-7-on-Debian-FingerPrint-4G-Modem/td-p/4550327] and [https://github.com/abrasive/xmm7360]</li><br />
<li>An official driver has been released on [[fwupd]].</li><br />
<li>S3 suspend requires changes to BIOS settings, see section on [[#Sleep/Suspend]].</li><br />
<li>The internal microphone does not work on versions of the {{pkg|linux}} kernel before 5.3. On version 5.3 and newer the SOF firmware can be enabled, see [[Talk:Lenovo_ThinkPad_X1_Carbon_(Gen_7)#Microphone|Talk#Microphone]].</li><br />
<li>Lenovo developers think it's not a priority (august 2020) [https://forums.lenovo.com/t5/Redhat-Fedora-CentOS/X1-Carbon-Gen8-and-other-models-too-coming-with-Fedora-Linux/m-p/5011378?page=1#5042158 forum]</li><br />
|}<br />
<br />
== Updates ==<br />
</li><br />
=== Automatic (Linux Vendor Firmware Service) ===<br />
<br />
[https://blogs.gnome.org/hughsie/2018/08/06/please-welcome-lenovo-to-the-lvfs/ In August of 2018 Lenovo has joined] the [https://fwupd.org/ Linux Vendor Firmware Service (LVFS)] project, which enables firmware updates from within the OS.<br />
BIOS updates (and possibly other firmware such as the Thunderbolt controller) can be queried for and installed through [[fwupd]].<br />
<br />
=== Manual (fwupdmgr) ===<br />
<br />
Lenovo may in the future provide cabinet files that can be directly installed with fwupdmgr.<br />
Check for Linux ''.cab'' files from the [https://pcsupport.lenovo.com/de/de/products/laptops-and-netbooks/thinkpad-x-series-laptops/thinkpad-x1-carbon-8th-gen-type-20u9-20ua/20u9/parts/display/compatible Lenovo ThinkPad X1 Carbon (Gen 8) driver website].<br />
<br />
# Make sure the AC adapter is firmly connected to the target computer.<br />
# Launch Terminal.<br />
# Move to the directory where the cabinet file was placed.<br />
# Run {{ic|fwupdmgr install xxxxxxxx.cab}} to schedule firmware update.<br />
# Restart the system.<br />
# The computer will be restarted and the UEFI BIOS will be updated.<br />
<br />
== Sleep/Suspend ==<br />
<br />
The BIOS has two ''Sleep State'' options, Windows and Linux, which you can find in at ''Config > Power > Sleep State''. The Linux option is the traditional S3 power state where all hardware components are turned off except for the RAM, and it should work normally. The Windows option is a newer software-based "modern standby" which works on Linux (despite the name). One possible benefit to the Windows sleep state is faster wake up time, and one possible drawback is increased power usage.<br />
<br />
== Audio ==<br />
See [[Lenovo_ThinkPad_X1_Carbon_(Gen_7)#Audio]]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Systemd-networkd&diff=637200Systemd-networkd2020-10-04T23:52:24Z<p>Hexhu: /* Basic usage */ fix a typo in the previous edit</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Virtualization]]<br />
[[es:Systemd-networkd]]<br />
[[fr:systemd-networkd]]<br />
[[ja:systemd-networkd]]<br />
[[ru:Systemd-networkd]]<br />
[[zh-hans:Systemd-networkd]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-resolved}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Network bridge}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|:Category:Network configuration}}<br />
{{Related articles end}}<br />
<br />
''systemd-networkd'' is a system daemon that manages network configurations. It detects and configures network devices as they appear; it can also create virtual network devices. This service can be especially useful to set up complex network configurations for a container managed by [[systemd-nspawn]] or for virtual machines. It also works fine on simple connections.<br />
<br />
== Basic usage ==<br />
The {{Pkg|systemd}} package is part of the default Arch installation and contains all needed files to operate a wired network. Wireless adapters, covered later in this article, can be set up by services, such as [[wpa_supplicant]] or [[iwd]].<br />
<br />
=== Required services and setup ===<br />
<br />
To use ''systemd-networkd'', [[start/enable]] {{ic|systemd-networkd.service}}.<br />
<br />
{{Note|You must ensure that no other service that wants to configure the network is running; in fact, multiple networking services will conflict. You can find a list of the currently running services with {{ic|1=systemctl --type=service}} and then [[stop]] them.}}<br />
<br />
It is optional to also [[start/enable]] {{ic|systemd-resolved.service}}, which is a network name resolution service to local applications, considering the following points:<br />
<br />
* The [[systemd-resolved]] service is required if DNS entries are specified in ''.network'' files.<br />
* [[systemd-resolved]] is also required if you want to obtain DNS addresses from DHCP servers or IPv6 Router Advertisements (by setting {{ic|1=DHCP=}} or {{ic|1=IPv6AcceptRA=}} in the {{ic|[Network]}} section, and, in their own section, setting {{ic|1=UseDNS=yes}} (the default)).<br />
* It is important to understand how [[resolv.conf]] and ''systemd-resolved'' interact to properly configure the DNS that will be used, some explanations are provided in [[systemd-resolved]].<br />
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.<br />
<br />
=== Configuration examples ===<br />
<br />
All configurations in this section are stored as {{ic|foo.network}} in {{ic|/etc/systemd/network/}}. For a full listing of options and processing order, see [[#Configuration files]] and {{man|5|systemd.network}}.<br />
<br />
Systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use {{ic|networkctl list}} to list the devices on the system.<br />
<br />
After making changes to a configuration file, [[restart]] {{ic|systemd-networkd.service}}.<br />
<br />
{{Note|<br />
* The options specified in the configuration files are case sensitive.<br />
* In the examples below, {{ic|enp1s0}} is the wired adapter and {{ic|wlp2s0}} is the wireless adapter. These names can be different on different systems. It is also possible to use a wildcard, e.g. {{ic|1=Name=en*}}.<br />
* If you want to disable IPv6, see [[IPv6#systemd-networkd_3|IPv6#systemd-networkd]].<br />
}}<br />
<br />
==== Wired adapter using DHCP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
==== Wired adapter using a static IP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
#DNS=8.8.8.8<br />
}}<br />
<br />
{{ic|1=Address=}} can be used more than once to configure multiple IPv4 or IPv6 addresses. See [[#network files]] or {{man|5|systemd.network}} for more options.<br />
<br />
==== Wireless adapter ====<br />
<br />
In order to connect to a wireless network with ''systemd-networkd'', a wireless adapter configured with another application such as [[WPA supplicant]] or [[Iwd]] is required.<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
If the wireless adapter has a static IP address, the configuration is the same (except for the interface name) as in a [[#Wired adapter using a static IP|wired adapter]].<br />
<br />
==== Wired and wireless adapters on the same machine ====<br />
<br />
This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel to decide on-the-fly which one to use. This way, no connection downtime is observed when the wired connection is unplugged.<br />
<br />
The kernel's route metric (same as configured with ''ip'') decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).<br />
<br />
{{Note|The {{ic|Metric}} option is for static routes while the {{ic|RouteMetric}} option is for setups not using static routes. See {{man|5|systemd.network}} for more details.}}<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=10}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=20<br />
}}<br />
<br />
==== Renaming an interface ====<br />
<br />
Instead of [[Network configuration#Change interface name|editing udev rules]], a ''.link'' file can be used to rename an interface. A useful example is to set a predictable interface name for a USB-to-Ethernet adapter based on its MAC address, as those adapters are usually given different names depending on which USB port they are plugged into.<br />
<br />
{{hc|head=/etc/systemd/network/10-ethusb0.link|output=<br />
[Match]<br />
MACAddress=12:34:56:78:90:ab<br />
<br />
[Link]<br />
Description=USB to Ethernet Adapter<br />
Name=ethusb0<br />
}}<br />
<br />
{{Note|Any user-supplied ''.link'' '''must''' have a lexically earlier file name than the default config {{ic|99-default.link}} in order to be considered at all. For example, name the file {{ic|10-ethusb0.link}} and not {{ic|ethusb0.link}}.}}<br />
<br />
== Configuration files ==<br />
<br />
Configuration files are located in {{ic|/usr/lib/systemd/network/}}, the volatile runtime network directory {{ic|/run/systemd/network/}} and the local administration network directory {{ic|/etc/systemd/network/}}. Files in {{ic|/etc/systemd/network/}} have the highest priority.<br />
<br />
There are three types of configuration files. They all use a format similar to [[systemd#Writing unit files|systemd unit files]]. <br />
<br />
* ''.network'' files. They will apply a network configuration for a ''matching'' device<br />
* ''.netdev'' files. They will create a ''virtual network device'' for a ''matching'' environment<br />
* ''.link'' files. When a network device appears, [[udev]] will look for the first ''matching'' ''.link'' file<br />
<br />
They all follow the same rules: <br />
<br />
* If '''all''' conditions in the {{ic|[Match]}} section are matched, the profile will be activated<br />
* an empty {{ic|[Match]}} section means the profile will apply in any case (can be compared to the {{ic|*}} wildcard)<br />
* all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live<br />
* files with identical name replace each other<br />
<br />
{{Tip|<br />
* Files in {{ic|/etc/systemd/network/}} override the corresponding system-supplied file in {{ic|/usr/lib/systemd/network/}}. You can also create a symlink to {{ic|/dev/null}} to "mask" a system file.<br />
* systemd accepts the values {{ic|1, true, yes, on}} for a true boolean, and the values {{ic|0, false, no, off}} for a false boolean<br />
}}<br />
<br />
=== network files ===<br />
<br />
These files are aimed at setting network configuration variables, especially for servers and containers.<br />
<br />
''.network'' files have the following sections: {{ic|[Match]}}, {{ic|[Link]}}, {{ic|[Network]}}, {{ic|[Address]}}, {{ic|[Route]}}, and {{ic|[DHCP]}}. Below are commonly configured keys for each section. See {{man|5|systemd.network}} for more information and examples.<br />
<br />
==== [Match] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Name=}} || Match device names, e.g. {{ic|en*}}. By prefixing with {{ic|!}}, the list can be inverted. || white-space separated device names with globs, logical negation ({{ic|!}}) ||<br />
|-<br />
| {{ic|1=MACAddress=}} || Match MAC addresses, e.g. {{ic|1=MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF}} || whitespace-separated MAC addresses in full colon-, hyphen- or dot-delimited hexadecimal || <br />
|-<br />
| {{ic|1=Host=}} || Match the hostname or machine ID of the host. || hostname string with globs, [https://jlk.fjfi.cvut.cz/arch/manpages/man/machine-id.5.en machine ID] ||<br />
|-<br />
| {{ic|1=Virtualization=}} || Check whether the system is executed in a virtualized environment. {{ic|1=Virtualization=false}} will only match your host machine, while {{ic|1=Virtualization=true}} matches any container or VM. It is possible to check for a specific virtualization type or implementation. || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|xen}}, {{ic|bochs}}, {{ic|uml}}, {{ic|bhyve}}, {{ic|qnx}}, {{ic|openvz}}, {{ic|lxc}}, {{ic|lxc-libvirt}}, {{ic|systemd-nspawn}}, {{ic|docker}}, {{ic|podman}}, {{ic|rkt}}, {{ic|wsl}}, {{ic|acrn}}) ||<br />
|}<br />
<br />
==== [Link] ====<br />
<br />
* {{ic|1=MACAddress=}} useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]<br />
* {{ic|1=MTUBytes=}} setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers<br />
* {{ic|1=Multicast=}} allows the usage of [[wikipedia:Multicast_address|multicast]] on interface(s)<br />
<br />
==== [Network] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=DHCP=}} || Controls DHCPv4 and/or DHCPv6 client support. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DHCPServer=}} || If enabled, a DHCPv4 server will be started. || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=MulticastDNS=}} || Enables [https://tools.ietf.org/html/rfc6762 multicast DNS] support. When set to {{ic|resolve}}, only resolution is enabled, but not host or service registration and announcement. || boolean, {{ic|resolve}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNSSEC=}} || Controls DNSSEC DNS validation support on the link. When set to {{ic|allow-downgrade}}, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. || boolean, {{ic|allow-downgrade}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNS=}} || Configure static [[DNS]] addresses. May be specified more than once. || {{man|3|inet_pton}} ||<br />
|-<br />
| {{ic|1=Domains=}} || A list of domains which should be resolved using the DNS servers on this link. [https://www.freedesktop.org/software/systemd/man/systemd.network.html#Domains= more information] || domain name, optionally prefixed with a tilde ({{ic|~}}) ||<br />
|-<br />
| {{ic|1=IPForward=}} || If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. See [[Internet sharing#Enable packet forwarding]] for details. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=IPMasquerade=}} || If enabled, packets forwarded from the network interface will appear as coming from the local host. Implies {{ic|1=IPForward=ipv4}}. || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=IPv6PrivacyExtensions=}} || Configures use of stateless temporary addresses that change over time (see [https://tools.ietf.org/html/rfc4941 RFC 4941]). When {{ic|prefer-public}}, enables the privacy extensions, but prefers public addresses over temporary addresses. When {{ic|kernel}}, the kernel's default setting will be left in place. || boolean, {{ic|prefer-public}}, {{ic|kernel}} || {{ic|false}}<br />
|}<br />
<br />
==== [Address] ====<br />
<br />
* {{ic|1=Address=}} this option is '''mandatory''' unless DHCP is used<br />
<br />
==== [Route] ====<br />
<br />
* {{ic|1=Gateway=}} this option is '''mandatory''' unless DHCP is used<br />
* {{ic|1=Destination=}} the destination prefix of the route, possibly followed by a slash and the prefix length <br />
<br />
If {{ic|Destination}} is not present in {{ic|[Route]}} section this section is treated as a default route.<br />
<br />
{{Tip|You can put the {{ic|1=Address=}} and {{ic|1=Gateway=}} keys in the {{ic|[Network]}} section as a short-hand if {{ic|[Address]}} section contains only an {{ic|Address}} key and {{ic|[Route]}} section contains only a {{ic|Gateway}} key.}}<br />
<br />
==== [DHCP] ====<br />
<br />
{| class = "wikitable<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=UseDNS=}} || controls whether the DNS servers advertised by the DHCP server are used || boolean || {{ic|true}}<br />
|-<br />
| {{ic|1=Anonymize=}} || when true, the options sent to the DHCP server will follow the [https://tools.ietf.org/html/rfc7844 RFC7844] (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=UseDomains=}} || controls whether the domain name received from the DHCP server will be used as DNS search domain. If set to {{ic|route}}, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching. This option can sometimes fix local name resolving when using [[systemd-resolved]] || boolean, {{ic|route}} || {{ic|false}}<br />
|}<br />
<br />
==== [DHCPServer] ====<br />
<br />
This is an example of a DHCP server configuration which works well with [[hostapd]] to create a wireless hotspot. {{ic|IPMasquerade}} adds the firewall rules for [[Internet sharing#Enable NAT|NAT]] and implies {{ic|1=IPForward=ipv4}} to enable [[Internet sharing#Enable packet forwarding|packet forwarding]].<br />
<br />
{{Accuracy|{{ic|1=IPMasquerade=true}} does not add the rules for the {{ic|filter}} table, they have to be added manually. See [[systemd-nspawn#Use a virtual Ethernet link]].}}<br />
<br />
{{hc|/etc/systemd/network/''wlan0''.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Address=10.1.1.1/24<br />
DHCPServer=true<br />
IPMasquerade=true<br />
<br />
[DHCPServer]<br />
PoolOffset=100<br />
PoolSize=20<br />
EmitDNS=yes<br />
DNS=9.9.9.9<br />
</nowiki>}}<br />
<br />
=== netdev files ===<br />
<br />
These files will create virtual network devices. They have two sections: {{ic|[Match]}} and {{ic|[NetDev]}}. Below are commonly configured keys for each section. See {{man|5|systemd.netdev}} for more information and examples.<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=Host=}} the hostname<br />
* {{ic|1=Virtualization=}} check if the system is running in a virtualized environment<br />
<br />
==== [NetDev] section ====<br />
<br />
Most common keys are:<br />
<br />
* {{ic|1=Name=}} the interface name. '''mandatory'''<br />
* {{ic|1=Kind=}} e.g. ''bridge'', ''bond'', ''vlan'', ''veth'', ''sit'', etc. '''mandatory'''<br />
<br />
=== link files ===<br />
<br />
These files are an alternative to custom udev rules and will be applied by [[udev]] as the device appears. They have two sections: {{ic|[Match]}} and {{ic|[Link]}}. Below are commonly configured keys for each section. See {{man|5|systemd.link}} for more information and examples.<br />
<br />
{{Tip|Use {{ic|udevadm test-builtin net_setup_link /sys/path/to/network/device}} as the root user to diagnose problems with ''.link'' files.}}<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=MACAddress=}} the MAC address<br />
* {{ic|1=Host=}} the host name<br />
* {{ic|1=Virtualization=}} <br />
* {{ic|1=Type=}} the device type e.g. vlan<br />
<br />
==== [Link] section ====<br />
<br />
* {{ic|1=MACAddressPolicy=}} persistent or random addresses, or<br />
* {{ic|1=MACAddress=}} a specific address<br />
* {{ic|1=NamePolicy=}} list of policies by which the interface name should be set, e.g. kernel, keep<br />
<br />
{{Note|the system {{ic|/usr/lib/systemd/network/99-default.link}} is generally sufficient for most of the basic cases.}}<br />
<br />
== Usage with containers ==<br />
<br />
''systemd-networkd'' can provide fully automatic configuration of networking for [[systemd-nspawn]] containers when it is used on the host system as well as inside the container. See [[systemd-nspawn#Networking]] for a comprehensive overview.<br />
<br />
For the examples below, <br />
* we will limit the output of the {{ic|ip a}} command to the concerned interfaces.<br />
* we assume the ''host'' is your main OS you are booting to and the ''container'' is your guest virtual machine.<br />
* all interface names and IP addresses are only examples.<br />
<br />
=== Network bridge with DHCP ===<br />
<br />
==== Bridge interface ====<br />
<br />
First, create a virtual [[bridge]] interface. We tell systemd to create a device named ''br0'' that functions as an ethernet bridge.<br />
<br />
{{hc|/etc/systemd/network/''MyBridge''.netdev|2=<br />
[NetDev]<br />
Name=br0<br />
Kind=bridge}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.<br />
<br />
On host and container:<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default <br />
link/ether ae:bd:35:ea:0c:c9 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
Note that the interface ''br0'' is listed but is still DOWN at this stage.<br />
<br />
==== Bind ethernet to bridge ====<br />
The next step is to add to the newly created bridge a network interface. In the example below, we add any interface that matches the name ''en*'' into the bridge ''br0''.<br />
<br />
{{hc|/etc/systemd/network/''bind''.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
Bridge=br0}}<br />
The ethernet interface must not have DHCP or an IP address associated as the bridge requires an interface to bind to with no IP: modify the corresponding {{ic|/etc/systemd/network/''MyEth''.network}} accordingly to remove the addressing.<br />
<br />
==== Bridge network ====<br />
<br />
Now that the bridge has been created and has been bound to an existing network interface, the IP configuration of the bridge interface must be specified. This is defined in a third ''.network'' file, the example below uses DHCP.<br />
<br />
{{hc|/etc/systemd/network/''mybridge''.network|2=<br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DHCP=ipv4}}<br />
<br />
==== Configure the container ====<br />
<br />
Use the {{ic|1=--networkd-bridge=br0}} option when starting the container. See [[systemd-nspawn#Use a network bridge]] for details.<br />
<br />
==== Result ====<br />
<br />
* on host<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default <br />
link/ether 14:da:e9:b5:7a:88 brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.87/24 brd 192.168.1.255 scope global br0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::16da:e9ff:feb5:7a88/64 scope link <br />
valid_lft forever preferred_lft forever<br />
6: vb-''MyContainer'': <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state UP group default qlen 1000<br />
link/ether d2:7c:97:97:37:25 brd ff:ff:ff:ff:ff:ff<br />
inet6 fe80::d07c:97ff:fe97:3725/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip a|<br />
2: host0: <BROADCAST,MULTICAST,ALLMULTI,AUTOMEDIA,NOTRAILERS,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000<br />
link/ether 5e:96:85:83:a8:5d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.73/24 brd 192.168.1.255 scope global host0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::5c96:85ff:fe83:a85d/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
==== Notice ====<br />
<br />
* we have now one IP address for {{ic|br0}} on the host, and one for {{ic|host0}} in the container<br />
* two new interfaces have appeared: {{ic|vb-''MyContainer''}} in the host and {{ic|host0}} in the container. This comes as a result of the {{ic|1=--network-bridge=br0}} option as explained in [[systemd-nspawn#Use a network bridge]] for details.<br />
* the DHCP address on {{ic|host0}} comes from the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file.<br />
* on host<br />
<br />
{{Out of date|''brctl'' is deprecated, use {{ic|bridge link}}. See [[Network bridge#With iproute2]].}}<br />
{{hc|$ brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
br0 8000.14dae9b57a88 no enp7s0<br />
vb-''MyContainer''<br />
}}<br />
<br />
the above command output confirms we have a bridge with two interfaces binded to.<br />
<br />
* on host<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev br0 <br />
192.168.1.0/24 dev br0 proto kernel scope link src 192.168.1.87<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev host0 <br />
192.168.1.0/24 dev host0 proto kernel scope link src 192.168.1.73<br />
}}<br />
<br />
the above command outputs confirm we have activated {{ic|br0}} and {{ic|host0}} interfaces with an IP address and Gateway 192.168.1.254. The gateway address has been automatically grabbed by ''systemd-networkd''.<br />
<br />
=== Network bridge with static IP addresses ===<br />
<br />
Setting a static IP address for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system {{ic|/usr/lib/systemd/network/99-default.link}} file has the {{ic|1=MACAddressPolicy=persistent}} option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.<br />
<br />
The following configuration needs to be done for this setup:<br />
<br />
* on host <br />
<br />
The configuration is very similar to the [[#Network bridge with DHCP]] section. First, a virtual bridge interface needs to be created and the main physical interface needs to be bound to it. This task can be accomplished with the following two files, with contents equal to those available in the DHCP section.<br />
<br />
/etc/systemd/network/''MyBridge''.netdev<br />
/etc/systemd/network/''MyEth''.network<br />
<br />
Next, you need to configure the IP and DNS of the newly created virtual bridge interface. For example:<br />
<br />
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki><br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.87/24<br />
Gateway=192.168.1.254<br />
</nowiki>}}<br />
<br />
* on container<br />
<br />
To get configure a static IP address on the container, we need to override the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file, which provides a DHCP configuration for the {{ic|host0}} network interface of the container. This can be done by placing the configuration into {{ic|/etc/systemd/network/80-container-host0.network}}. For example:<br />
<br />
{{hc|/etc/systemd/network/80-container-host0.network|2=<br />
[Match]<br />
Name=host0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.94/24<br />
Gateway=192.168.1.254<br />
}}<br />
<br />
Make sure that {{ic|systemd-networkd.service}} is [[enabled]] in the container.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Interface and desktop integration ===<br />
<br />
''systemd-networkd'' does not have a proper interactive management interface neither via [[command-line shell]] nor graphical.<br />
<br />
Still, some tools are available to either display the current state of the network, receive notifications or interact with the wireless configuration:<br />
<br />
* ''networkctl'' (via CLI) offers a simple dump of the network interface states.<br />
* When ''networkd'' is configured with [[wpa_supplicant]], both ''wpa_cli'' and ''wpa_gui'' offer the ability to associate and configure WLAN interfaces dynamically.<br />
* {{AUR|networkd-notify-git}} can generate simple notifications in response to network interface state changes (such as connection/disconnection and re-association).<br />
* The {{AUR|networkd-dispatcher}} daemon allows executing scripts in response to network interface state changes, similar to ''NetworkManager-dispatcher''.<br />
* As for the DNS resolver ''systemd-resolved'', information about current DNS servers can be visualized with {{ic|resolvectl status}}.<br />
<br />
=== Configuring static IP or DHCP based on SSID (location) ===<br />
<br />
Often there is a situation where your home wireless network uses DHCP and office wireless network uses static IP. This mixed setup can be configured as follows:<br />
<br />
{{Note|Number in the file name decides the order in which the files are processed. You can [Match] based on SSID or BSSID or both.}}<br />
<br />
{{hc|/etc/systemd/network/24-wireless-office.network|<nowiki><br />
# special configuration for office WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
SSID=office_ap_name<br />
#BSSID=aa:bb:cc:dd:ee:ff<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
#DNS=8.8.8.8<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless-dhcp.network|<nowiki><br />
# use DHCP for any other WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
=== Bonding a wired and wireless interface ===<br />
<br />
See also [[Wireless bonding]].<br />
<br />
Bonding allows connection sharing through multiple interfaces, so if e.g. the wired interface is unplugged, the wireless is still connected and the network connectivity remains up seamlessly.<br />
<br />
Create a bond interface. In this case the mode is ''active-backup'', which means packets are routed through a secondary interface if the primary interface goes down.<br />
<br />
{{hc|/etc/systemd/network/30-bond0.netdev|<nowiki><br />
[NetDev]<br />
Name=bond0<br />
Kind=bond<br />
<br />
[Bond]<br />
Mode=active-backup<br />
PrimaryReselectPolicy=always<br />
MIIMonitorSec=1s<br />
</nowiki>}}<br />
<br />
Set the wired interface as the primary:<br />
<br />
{{hc|/etc/systemd/network/30-ethernet-bond0.network|<nowiki><br />
[Match]<br />
Name=enp0s25<br />
<br />
[Network]<br />
Bond=bond0<br />
PrimarySlave=true<br />
</nowiki>}}<br />
<br />
Set the wireless as the secondary:<br />
<br />
{{hc|/etc/systemd/network/30-wifi-bond0.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Bond=bond0<br />
</nowiki>}}<br />
<br />
Configure the bond interface as you would a normal interface:<br />
<br />
{{hc|/etc/systemd/network/30-bond0.network|<nowiki><br />
[Match]<br />
Name=bond0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
Now if the wired network is unplugged, the connection should remain through the wireless:<br />
<br />
{{hc|$ networkctl|<nowiki><br />
IDX LINK TYPE OPERATIONAL SETUP <br />
1 lo loopback carrier unmanaged <br />
2 enp0s25 ether no-carrier configured<br />
3 bond0 bond degraded-carrier configured<br />
5 wlan0 wlan enslaved configured<br />
<br />
4 links listed.<br />
</nowiki>}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mount services at boot fail ===<br />
<br />
If running services like [[Samba]]/[[NFS]] which fail if they are started before the network is up, you may want to [[enable]] the {{ic|systemd-networkd-wait-online.service}}. This is, however, rarely necessary because most networked daemons start up okay, even if the network has not been configured yet.<br />
<br />
== See also ==<br />
<br />
* {{man|8|systemd-networkd}}<br />
* [https://coreos.com/blog/intro-to-systemd-networkd/ Tom Gundersen posts on Core OS blog]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1393759#p1393759 How to set up systemd-networkd with wpa_supplicant] (WonderWoofy's walkthrough on Arch forums)</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Systemd-networkd&diff=637199Systemd-networkd2020-10-04T23:41:39Z<p>Hexhu: /* Required services and setup */ Specify that all "UseDNS=" entries in .network files require using systemd-resolved.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Virtualization]]<br />
[[es:Systemd-networkd]]<br />
[[fr:systemd-networkd]]<br />
[[ja:systemd-networkd]]<br />
[[ru:Systemd-networkd]]<br />
[[zh-hans:Systemd-networkd]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|systemd-resolved}}<br />
{{Related|systemd-nspawn}}<br />
{{Related|Network bridge}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|:Category:Network configuration}}<br />
{{Related articles end}}<br />
<br />
''systemd-networkd'' is a system daemon that manages network configurations. It detects and configures network devices as they appear; it can also create virtual network devices. This service can be especially useful to set up complex network configurations for a container managed by [[systemd-nspawn]] or for virtual machines. It also works fine on simple connections.<br />
<br />
== Basic usage ==<br />
The {{Pkg|systemd}} package is part of the default Arch installation and contains all needed files to operate a wired network. Wireless adapters, covered later in this article, can be set up by services, such as [[wpa_supplicant]] or [[iwd]].<br />
<br />
=== Required services and setup ===<br />
<br />
To use ''systemd-networkd'', [[start/enable]] {{ic|systemd-networkd.service}}.<br />
<br />
{{Note|You must ensure that no other service that wants to configure the network is running; in fact, multiple networking services will conflict. You can find a list of the currently running services with {{ic|1=systemctl --type=service}} and then [[stop]] them.}}<br />
<br />
It is optional to also [[start/enable]] {{ic|systemd-resolved.service}}, which is a network name resolution service to local applications, considering the following points:<br />
<br />
* The [[systemd-resolved]] service is required if DNS entries are specified in ''.network'' files.<br />
* [[systemd-resolved]] is also required if you want to obtain DNS addresses from DHCP servers or IPv6 Router Advertisements (by setting {{ic|1=DHCP=}} or {{ic|1=IPv6AcceptRA=}} in the {{ic|[Network]}} section, and, in their own section, set {{ic|1=UseDNS=yes}} (the default)).<br />
* It is important to understand how [[resolv.conf]] and ''systemd-resolved'' interact to properly configure the DNS that will be used, some explanations are provided in [[systemd-resolved]].<br />
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.<br />
<br />
=== Configuration examples ===<br />
<br />
All configurations in this section are stored as {{ic|foo.network}} in {{ic|/etc/systemd/network/}}. For a full listing of options and processing order, see [[#Configuration files]] and {{man|5|systemd.network}}.<br />
<br />
Systemd/udev automatically assigns predictable, stable network interface names for all local Ethernet, WLAN, and WWAN interfaces. Use {{ic|networkctl list}} to list the devices on the system.<br />
<br />
After making changes to a configuration file, [[restart]] {{ic|systemd-networkd.service}}.<br />
<br />
{{Note|<br />
* The options specified in the configuration files are case sensitive.<br />
* In the examples below, {{ic|enp1s0}} is the wired adapter and {{ic|wlp2s0}} is the wireless adapter. These names can be different on different systems. It is also possible to use a wildcard, e.g. {{ic|1=Name=en*}}.<br />
* If you want to disable IPv6, see [[IPv6#systemd-networkd_3|IPv6#systemd-networkd]].<br />
}}<br />
<br />
==== Wired adapter using DHCP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
==== Wired adapter using a static IP ====<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
#DNS=8.8.8.8<br />
}}<br />
<br />
{{ic|1=Address=}} can be used more than once to configure multiple IPv4 or IPv6 addresses. See [[#network files]] or {{man|5|systemd.network}} for more options.<br />
<br />
==== Wireless adapter ====<br />
<br />
In order to connect to a wireless network with ''systemd-networkd'', a wireless adapter configured with another application such as [[WPA supplicant]] or [[Iwd]] is required.<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
}}<br />
<br />
If the wireless adapter has a static IP address, the configuration is the same (except for the interface name) as in a [[#Wired adapter using a static IP|wired adapter]].<br />
<br />
==== Wired and wireless adapters on the same machine ====<br />
<br />
This setup will enable a DHCP IP for both a wired and wireless connection making use of the metric directive to allow the kernel to decide on-the-fly which one to use. This way, no connection downtime is observed when the wired connection is unplugged.<br />
<br />
The kernel's route metric (same as configured with ''ip'') decides which route to use for outgoing packets, in cases when several match. This will be the case when both wireless and wired devices on the system have active connections. To break the tie, the kernel uses the metric. If one of the connections is terminated, the other automatically wins without there being a gap with nothing configured (ongoing transfers may still not deal with this nicely but that is at a different OSI layer).<br />
<br />
{{Note|The {{ic|Metric}} option is for static routes while the {{ic|RouteMetric}} option is for setups not using static routes. See {{man|5|systemd.network}} for more details.}}<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=enp1s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=10}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless.network|2=<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=yes<br />
<br />
[DHCP]<br />
RouteMetric=20<br />
}}<br />
<br />
==== Renaming an interface ====<br />
<br />
Instead of [[Network configuration#Change interface name|editing udev rules]], a ''.link'' file can be used to rename an interface. A useful example is to set a predictable interface name for a USB-to-Ethernet adapter based on its MAC address, as those adapters are usually given different names depending on which USB port they are plugged into.<br />
<br />
{{hc|head=/etc/systemd/network/10-ethusb0.link|output=<br />
[Match]<br />
MACAddress=12:34:56:78:90:ab<br />
<br />
[Link]<br />
Description=USB to Ethernet Adapter<br />
Name=ethusb0<br />
}}<br />
<br />
{{Note|Any user-supplied ''.link'' '''must''' have a lexically earlier file name than the default config {{ic|99-default.link}} in order to be considered at all. For example, name the file {{ic|10-ethusb0.link}} and not {{ic|ethusb0.link}}.}}<br />
<br />
== Configuration files ==<br />
<br />
Configuration files are located in {{ic|/usr/lib/systemd/network/}}, the volatile runtime network directory {{ic|/run/systemd/network/}} and the local administration network directory {{ic|/etc/systemd/network/}}. Files in {{ic|/etc/systemd/network/}} have the highest priority.<br />
<br />
There are three types of configuration files. They all use a format similar to [[systemd#Writing unit files|systemd unit files]]. <br />
<br />
* ''.network'' files. They will apply a network configuration for a ''matching'' device<br />
* ''.netdev'' files. They will create a ''virtual network device'' for a ''matching'' environment<br />
* ''.link'' files. When a network device appears, [[udev]] will look for the first ''matching'' ''.link'' file<br />
<br />
They all follow the same rules: <br />
<br />
* If '''all''' conditions in the {{ic|[Match]}} section are matched, the profile will be activated<br />
* an empty {{ic|[Match]}} section means the profile will apply in any case (can be compared to the {{ic|*}} wildcard)<br />
* all configuration files are collectively sorted and processed in lexical order, regardless of the directory in which they live<br />
* files with identical name replace each other<br />
<br />
{{Tip|<br />
* Files in {{ic|/etc/systemd/network/}} override the corresponding system-supplied file in {{ic|/usr/lib/systemd/network/}}. You can also create a symlink to {{ic|/dev/null}} to "mask" a system file.<br />
* systemd accepts the values {{ic|1, true, yes, on}} for a true boolean, and the values {{ic|0, false, no, off}} for a false boolean<br />
}}<br />
<br />
=== network files ===<br />
<br />
These files are aimed at setting network configuration variables, especially for servers and containers.<br />
<br />
''.network'' files have the following sections: {{ic|[Match]}}, {{ic|[Link]}}, {{ic|[Network]}}, {{ic|[Address]}}, {{ic|[Route]}}, and {{ic|[DHCP]}}. Below are commonly configured keys for each section. See {{man|5|systemd.network}} for more information and examples.<br />
<br />
==== [Match] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Name=}} || Match device names, e.g. {{ic|en*}}. By prefixing with {{ic|!}}, the list can be inverted. || white-space separated device names with globs, logical negation ({{ic|!}}) ||<br />
|-<br />
| {{ic|1=MACAddress=}} || Match MAC addresses, e.g. {{ic|1=MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF}} || whitespace-separated MAC addresses in full colon-, hyphen- or dot-delimited hexadecimal || <br />
|-<br />
| {{ic|1=Host=}} || Match the hostname or machine ID of the host. || hostname string with globs, [https://jlk.fjfi.cvut.cz/arch/manpages/man/machine-id.5.en machine ID] ||<br />
|-<br />
| {{ic|1=Virtualization=}} || Check whether the system is executed in a virtualized environment. {{ic|1=Virtualization=false}} will only match your host machine, while {{ic|1=Virtualization=true}} matches any container or VM. It is possible to check for a specific virtualization type or implementation. || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|xen}}, {{ic|bochs}}, {{ic|uml}}, {{ic|bhyve}}, {{ic|qnx}}, {{ic|openvz}}, {{ic|lxc}}, {{ic|lxc-libvirt}}, {{ic|systemd-nspawn}}, {{ic|docker}}, {{ic|podman}}, {{ic|rkt}}, {{ic|wsl}}, {{ic|acrn}}) ||<br />
|}<br />
<br />
==== [Link] ====<br />
<br />
* {{ic|1=MACAddress=}} useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]<br />
* {{ic|1=MTUBytes=}} setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers<br />
* {{ic|1=Multicast=}} allows the usage of [[wikipedia:Multicast_address|multicast]] on interface(s)<br />
<br />
==== [Network] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=DHCP=}} || Controls DHCPv4 and/or DHCPv6 client support. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DHCPServer=}} || If enabled, a DHCPv4 server will be started. || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=MulticastDNS=}} || Enables [https://tools.ietf.org/html/rfc6762 multicast DNS] support. When set to {{ic|resolve}}, only resolution is enabled, but not host or service registration and announcement. || boolean, {{ic|resolve}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNSSEC=}} || Controls DNSSEC DNS validation support on the link. When set to {{ic|allow-downgrade}}, compatibility with non-DNSSEC capable networks is increased, by automatically turning off DNSSEC in this case. || boolean, {{ic|allow-downgrade}} || {{ic|false}}<br />
|-<br />
| {{ic|1=DNS=}} || Configure static [[DNS]] addresses. May be specified more than once. || {{man|3|inet_pton}} ||<br />
|-<br />
| {{ic|1=Domains=}} || A list of domains which should be resolved using the DNS servers on this link. [https://www.freedesktop.org/software/systemd/man/systemd.network.html#Domains= more information] || domain name, optionally prefixed with a tilde ({{ic|~}}) ||<br />
|-<br />
| {{ic|1=IPForward=}} || If enabled, incoming packets on any network interface will be forwarded to any other interfaces according to the routing table. See [[Internet sharing#Enable packet forwarding]] for details. || boolean, {{ic|ipv4}}, {{ic|ipv6}} || {{ic|false}}<br />
|-<br />
| {{ic|1=IPMasquerade=}} || If enabled, packets forwarded from the network interface will appear as coming from the local host. Implies {{ic|1=IPForward=ipv4}}. || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=IPv6PrivacyExtensions=}} || Configures use of stateless temporary addresses that change over time (see [https://tools.ietf.org/html/rfc4941 RFC 4941]). When {{ic|prefer-public}}, enables the privacy extensions, but prefers public addresses over temporary addresses. When {{ic|kernel}}, the kernel's default setting will be left in place. || boolean, {{ic|prefer-public}}, {{ic|kernel}} || {{ic|false}}<br />
|}<br />
<br />
==== [Address] ====<br />
<br />
* {{ic|1=Address=}} this option is '''mandatory''' unless DHCP is used<br />
<br />
==== [Route] ====<br />
<br />
* {{ic|1=Gateway=}} this option is '''mandatory''' unless DHCP is used<br />
* {{ic|1=Destination=}} the destination prefix of the route, possibly followed by a slash and the prefix length <br />
<br />
If {{ic|Destination}} is not present in {{ic|[Route]}} section this section is treated as a default route.<br />
<br />
{{Tip|You can put the {{ic|1=Address=}} and {{ic|1=Gateway=}} keys in the {{ic|[Network]}} section as a short-hand if {{ic|[Address]}} section contains only an {{ic|Address}} key and {{ic|[Route]}} section contains only a {{ic|Gateway}} key.}}<br />
<br />
==== [DHCP] ====<br />
<br />
{| class = "wikitable<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=UseDNS=}} || controls whether the DNS servers advertised by the DHCP server are used || boolean || {{ic|true}}<br />
|-<br />
| {{ic|1=Anonymize=}} || when true, the options sent to the DHCP server will follow the [https://tools.ietf.org/html/rfc7844 RFC7844] (Anonymity Profiles for DHCP Clients) to minimize disclosure of identifying information || boolean || {{ic|false}}<br />
|-<br />
| {{ic|1=UseDomains=}} || controls whether the domain name received from the DHCP server will be used as DNS search domain. If set to {{ic|route}}, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching. This option can sometimes fix local name resolving when using [[systemd-resolved]] || boolean, {{ic|route}} || {{ic|false}}<br />
|}<br />
<br />
==== [DHCPServer] ====<br />
<br />
This is an example of a DHCP server configuration which works well with [[hostapd]] to create a wireless hotspot. {{ic|IPMasquerade}} adds the firewall rules for [[Internet sharing#Enable NAT|NAT]] and implies {{ic|1=IPForward=ipv4}} to enable [[Internet sharing#Enable packet forwarding|packet forwarding]].<br />
<br />
{{Accuracy|{{ic|1=IPMasquerade=true}} does not add the rules for the {{ic|filter}} table, they have to be added manually. See [[systemd-nspawn#Use a virtual Ethernet link]].}}<br />
<br />
{{hc|/etc/systemd/network/''wlan0''.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Address=10.1.1.1/24<br />
DHCPServer=true<br />
IPMasquerade=true<br />
<br />
[DHCPServer]<br />
PoolOffset=100<br />
PoolSize=20<br />
EmitDNS=yes<br />
DNS=9.9.9.9<br />
</nowiki>}}<br />
<br />
=== netdev files ===<br />
<br />
These files will create virtual network devices. They have two sections: {{ic|[Match]}} and {{ic|[NetDev]}}. Below are commonly configured keys for each section. See {{man|5|systemd.netdev}} for more information and examples.<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=Host=}} the hostname<br />
* {{ic|1=Virtualization=}} check if the system is running in a virtualized environment<br />
<br />
==== [NetDev] section ====<br />
<br />
Most common keys are:<br />
<br />
* {{ic|1=Name=}} the interface name. '''mandatory'''<br />
* {{ic|1=Kind=}} e.g. ''bridge'', ''bond'', ''vlan'', ''veth'', ''sit'', etc. '''mandatory'''<br />
<br />
=== link files ===<br />
<br />
These files are an alternative to custom udev rules and will be applied by [[udev]] as the device appears. They have two sections: {{ic|[Match]}} and {{ic|[Link]}}. Below are commonly configured keys for each section. See {{man|5|systemd.link}} for more information and examples.<br />
<br />
{{Tip|Use {{ic|udevadm test-builtin net_setup_link /sys/path/to/network/device}} as the root user to diagnose problems with ''.link'' files.}}<br />
<br />
==== [Match] section ====<br />
<br />
* {{ic|1=MACAddress=}} the MAC address<br />
* {{ic|1=Host=}} the host name<br />
* {{ic|1=Virtualization=}} <br />
* {{ic|1=Type=}} the device type e.g. vlan<br />
<br />
==== [Link] section ====<br />
<br />
* {{ic|1=MACAddressPolicy=}} persistent or random addresses, or<br />
* {{ic|1=MACAddress=}} a specific address<br />
* {{ic|1=NamePolicy=}} list of policies by which the interface name should be set, e.g. kernel, keep<br />
<br />
{{Note|the system {{ic|/usr/lib/systemd/network/99-default.link}} is generally sufficient for most of the basic cases.}}<br />
<br />
== Usage with containers ==<br />
<br />
''systemd-networkd'' can provide fully automatic configuration of networking for [[systemd-nspawn]] containers when it is used on the host system as well as inside the container. See [[systemd-nspawn#Networking]] for a comprehensive overview.<br />
<br />
For the examples below, <br />
* we will limit the output of the {{ic|ip a}} command to the concerned interfaces.<br />
* we assume the ''host'' is your main OS you are booting to and the ''container'' is your guest virtual machine.<br />
* all interface names and IP addresses are only examples.<br />
<br />
=== Network bridge with DHCP ===<br />
<br />
==== Bridge interface ====<br />
<br />
First, create a virtual [[bridge]] interface. We tell systemd to create a device named ''br0'' that functions as an ethernet bridge.<br />
<br />
{{hc|/etc/systemd/network/''MyBridge''.netdev|2=<br />
[NetDev]<br />
Name=br0<br />
Kind=bridge}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.<br />
<br />
On host and container:<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default <br />
link/ether ae:bd:35:ea:0c:c9 brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
Note that the interface ''br0'' is listed but is still DOWN at this stage.<br />
<br />
==== Bind ethernet to bridge ====<br />
The next step is to add to the newly created bridge a network interface. In the example below, we add any interface that matches the name ''en*'' into the bridge ''br0''.<br />
<br />
{{hc|/etc/systemd/network/''bind''.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
Bridge=br0}}<br />
The ethernet interface must not have DHCP or an IP address associated as the bridge requires an interface to bind to with no IP: modify the corresponding {{ic|/etc/systemd/network/''MyEth''.network}} accordingly to remove the addressing.<br />
<br />
==== Bridge network ====<br />
<br />
Now that the bridge has been created and has been bound to an existing network interface, the IP configuration of the bridge interface must be specified. This is defined in a third ''.network'' file, the example below uses DHCP.<br />
<br />
{{hc|/etc/systemd/network/''mybridge''.network|2=<br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DHCP=ipv4}}<br />
<br />
==== Configure the container ====<br />
<br />
Use the {{ic|1=--networkd-bridge=br0}} option when starting the container. See [[systemd-nspawn#Use a network bridge]] for details.<br />
<br />
==== Result ====<br />
<br />
* on host<br />
<br />
{{hc|$ ip a|<br />
3: br0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default <br />
link/ether 14:da:e9:b5:7a:88 brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.87/24 brd 192.168.1.255 scope global br0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::16da:e9ff:feb5:7a88/64 scope link <br />
valid_lft forever preferred_lft forever<br />
6: vb-''MyContainer'': <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state UP group default qlen 1000<br />
link/ether d2:7c:97:97:37:25 brd ff:ff:ff:ff:ff:ff<br />
inet6 fe80::d07c:97ff:fe97:3725/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip a|<br />
2: host0: <BROADCAST,MULTICAST,ALLMULTI,AUTOMEDIA,NOTRAILERS,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000<br />
link/ether 5e:96:85:83:a8:5d brd ff:ff:ff:ff:ff:ff<br />
inet 192.168.1.73/24 brd 192.168.1.255 scope global host0<br />
valid_lft forever preferred_lft forever<br />
inet6 fe80::5c96:85ff:fe83:a85d/64 scope link <br />
valid_lft forever preferred_lft forever<br />
}}<br />
<br />
==== Notice ====<br />
<br />
* we have now one IP address for {{ic|br0}} on the host, and one for {{ic|host0}} in the container<br />
* two new interfaces have appeared: {{ic|vb-''MyContainer''}} in the host and {{ic|host0}} in the container. This comes as a result of the {{ic|1=--network-bridge=br0}} option as explained in [[systemd-nspawn#Use a network bridge]] for details.<br />
* the DHCP address on {{ic|host0}} comes from the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file.<br />
* on host<br />
<br />
{{Out of date|''brctl'' is deprecated, use {{ic|bridge link}}. See [[Network bridge#With iproute2]].}}<br />
{{hc|$ brctl show|<br />
bridge name bridge id STP enabled interfaces<br />
br0 8000.14dae9b57a88 no enp7s0<br />
vb-''MyContainer''<br />
}}<br />
<br />
the above command output confirms we have a bridge with two interfaces binded to.<br />
<br />
* on host<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev br0 <br />
192.168.1.0/24 dev br0 proto kernel scope link src 192.168.1.87<br />
}}<br />
<br />
* on container<br />
<br />
{{hc|$ ip route|<br />
default via 192.168.1.254 dev host0 <br />
192.168.1.0/24 dev host0 proto kernel scope link src 192.168.1.73<br />
}}<br />
<br />
the above command outputs confirm we have activated {{ic|br0}} and {{ic|host0}} interfaces with an IP address and Gateway 192.168.1.254. The gateway address has been automatically grabbed by ''systemd-networkd''.<br />
<br />
=== Network bridge with static IP addresses ===<br />
<br />
Setting a static IP address for each device can be helpful in case of deployed web services (e.g FTP, http, SSH). Each device will keep the same MAC address across reboots if your system {{ic|/usr/lib/systemd/network/99-default.link}} file has the {{ic|1=MACAddressPolicy=persistent}} option (it has by default). Thus, you will easily route any service on your Gateway to the desired device.<br />
<br />
The following configuration needs to be done for this setup:<br />
<br />
* on host <br />
<br />
The configuration is very similar to the [[#Network bridge with DHCP]] section. First, a virtual bridge interface needs to be created and the main physical interface needs to be bound to it. This task can be accomplished with the following two files, with contents equal to those available in the DHCP section.<br />
<br />
/etc/systemd/network/''MyBridge''.netdev<br />
/etc/systemd/network/''MyEth''.network<br />
<br />
Next, you need to configure the IP and DNS of the newly created virtual bridge interface. For example:<br />
<br />
{{hc|/etc/systemd/network/''MyBridge''.network|<nowiki><br />
[Match]<br />
Name=br0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.87/24<br />
Gateway=192.168.1.254<br />
</nowiki>}}<br />
<br />
* on container<br />
<br />
To get configure a static IP address on the container, we need to override the system {{ic|/usr/lib/systemd/network/80-container-host0.network}} file, which provides a DHCP configuration for the {{ic|host0}} network interface of the container. This can be done by placing the configuration into {{ic|/etc/systemd/network/80-container-host0.network}}. For example:<br />
<br />
{{hc|/etc/systemd/network/80-container-host0.network|2=<br />
[Match]<br />
Name=host0<br />
<br />
[Network]<br />
DNS=192.168.1.254<br />
Address=192.168.1.94/24<br />
Gateway=192.168.1.254<br />
}}<br />
<br />
Make sure that {{ic|systemd-networkd.service}} is [[enabled]] in the container.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Interface and desktop integration ===<br />
<br />
''systemd-networkd'' does not have a proper interactive management interface neither via [[command-line shell]] nor graphical.<br />
<br />
Still, some tools are available to either display the current state of the network, receive notifications or interact with the wireless configuration:<br />
<br />
* ''networkctl'' (via CLI) offers a simple dump of the network interface states.<br />
* When ''networkd'' is configured with [[wpa_supplicant]], both ''wpa_cli'' and ''wpa_gui'' offer the ability to associate and configure WLAN interfaces dynamically.<br />
* {{AUR|networkd-notify-git}} can generate simple notifications in response to network interface state changes (such as connection/disconnection and re-association).<br />
* The {{AUR|networkd-dispatcher}} daemon allows executing scripts in response to network interface state changes, similar to ''NetworkManager-dispatcher''.<br />
* As for the DNS resolver ''systemd-resolved'', information about current DNS servers can be visualized with {{ic|resolvectl status}}.<br />
<br />
=== Configuring static IP or DHCP based on SSID (location) ===<br />
<br />
Often there is a situation where your home wireless network uses DHCP and office wireless network uses static IP. This mixed setup can be configured as follows:<br />
<br />
{{Note|Number in the file name decides the order in which the files are processed. You can [Match] based on SSID or BSSID or both.}}<br />
<br />
{{hc|/etc/systemd/network/24-wireless-office.network|<nowiki><br />
# special configuration for office WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
SSID=office_ap_name<br />
#BSSID=aa:bb:cc:dd:ee:ff<br />
<br />
[Network]<br />
Address=10.1.10.9/24<br />
Gateway=10.1.10.1<br />
DNS=10.1.10.1<br />
#DNS=8.8.8.8<br />
</nowiki>}}<br />
<br />
{{hc|/etc/systemd/network/25-wireless-dhcp.network|<nowiki><br />
# use DHCP for any other WiFi network<br />
[Match]<br />
Name=wlp2s0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
=== Bonding a wired and wireless interface ===<br />
<br />
See also [[Wireless bonding]].<br />
<br />
Bonding allows connection sharing through multiple interfaces, so if e.g. the wired interface is unplugged, the wireless is still connected and the network connectivity remains up seamlessly.<br />
<br />
Create a bond interface. In this case the mode is ''active-backup'', which means packets are routed through a secondary interface if the primary interface goes down.<br />
<br />
{{hc|/etc/systemd/network/30-bond0.netdev|<nowiki><br />
[NetDev]<br />
Name=bond0<br />
Kind=bond<br />
<br />
[Bond]<br />
Mode=active-backup<br />
PrimaryReselectPolicy=always<br />
MIIMonitorSec=1s<br />
</nowiki>}}<br />
<br />
Set the wired interface as the primary:<br />
<br />
{{hc|/etc/systemd/network/30-ethernet-bond0.network|<nowiki><br />
[Match]<br />
Name=enp0s25<br />
<br />
[Network]<br />
Bond=bond0<br />
PrimarySlave=true<br />
</nowiki>}}<br />
<br />
Set the wireless as the secondary:<br />
<br />
{{hc|/etc/systemd/network/30-wifi-bond0.network|<nowiki><br />
[Match]<br />
Name=wlan0<br />
<br />
[Network]<br />
Bond=bond0<br />
</nowiki>}}<br />
<br />
Configure the bond interface as you would a normal interface:<br />
<br />
{{hc|/etc/systemd/network/30-bond0.network|<nowiki><br />
[Match]<br />
Name=bond0<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
Now if the wired network is unplugged, the connection should remain through the wireless:<br />
<br />
{{hc|$ networkctl|<nowiki><br />
IDX LINK TYPE OPERATIONAL SETUP <br />
1 lo loopback carrier unmanaged <br />
2 enp0s25 ether no-carrier configured<br />
3 bond0 bond degraded-carrier configured<br />
5 wlan0 wlan enslaved configured<br />
<br />
4 links listed.<br />
</nowiki>}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mount services at boot fail ===<br />
<br />
If running services like [[Samba]]/[[NFS]] which fail if they are started before the network is up, you may want to [[enable]] the {{ic|systemd-networkd-wait-online.service}}. This is, however, rarely necessary because most networked daemons start up okay, even if the network has not been configured yet.<br />
<br />
== See also ==<br />
<br />
* {{man|8|systemd-networkd}}<br />
* [https://coreos.com/blog/intro-to-systemd-networkd/ Tom Gundersen posts on Core OS blog]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1393759#p1393759 How to set up systemd-networkd with wpa_supplicant] (WonderWoofy's walkthrough on Arch forums)</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Network_configuration&diff=637075Network configuration2020-10-03T09:47:20Z<p>Hexhu: /* DHCP */ clarify that the listed two DHCP client implementations are not the only option</p>
<hr />
<div>[[Category:Network configuration]]<br />
[[cs:Network configuration]]<br />
[[el:Network configuration]]<br />
[[es:Network configuration]]<br />
[[fr:Connexions reseau]]<br />
[[it:Network configuration]]<br />
[[ja:ネットワーク設定]]<br />
[[nl:Network configuration]]<br />
[[pl:Network configuration]]<br />
[[pt:Network configuration]]<br />
[[ru:Network configuration]]<br />
[[zh-hans:Network configuration]]<br />
[[zh-hant:Network configuration]]<br />
{{Related articles start}}<br />
{{Related|Network Debugging}}<br />
{{Related|Firewalls}}<br />
{{Related|Jumbo frames}}<br />
{{Related|Internet sharing}}<br />
{{Related|Router}}<br />
{{Related articles end}}<br />
<br />
This article describes how to configure network connections on [[Wikipedia:OSI layer 3|OSI layer 3]] and above. Medium-specifics are handled in the [[/Ethernet]] and [[/Wireless]] subpages.<br />
<br />
== Check the connection ==<br />
<br />
To troubleshoot a network connection, go through the following conditions and ensure that you meet them:<br />
<br />
# Your [[#Network interfaces|network interface]] is listed and enabled. Otherwise, check the device driver – see [[/Ethernet#Device driver]] or [[/Wireless#Device driver]].<br />
# You are connected to the network. The cable is plugged in or you are [[/Wireless|connected to the wireless LAN]].<br />
# Your network interface has an [[#IP addresses|IP address]].<br />
# Your [[#Routing table|routing table]] is correctly set up.<br />
# You can [[#Ping|ping]] a local IP address (e.g. your default gateway).<br />
# You can [[#Ping|ping]] a public IP address (e.g. {{ic|8.8.8.8}}, which is a Google DNS server and is a convenient address to test with).<br />
# [[Check if you can resolve domain names]] (e.g. {{ic|archlinux.org}}).<br />
<br />
=== Ping ===<br />
<br />
{{Expansion|Add or link explanation of common ping errors like Unknown hosts / Network is unreachable.}}<br />
<br />
[[Wikipedia:Ping (networking utility)|ping]] is used to test if you can reach a host.<br />
<br />
{{hc|$ ping www.example.com|2=<br />
PING www.example.com (93.184.216.34): 56(84) data bytes<br />
64 bytes from 93.184.216.34: icmp_seq=0 ttl=56 time=11.632 ms<br />
64 bytes from 93.184.216.34: icmp_seq=1 ttl=56 time=11.726 ms<br />
64 bytes from 93.184.216.34: icmp_seq=2 ttl=56 time=10.683 ms<br />
...<br />
}}<br />
<br />
For every reply you receive, the ping utility will print a line like the above. For more information see the {{man|8|ping}} manual. Note that computers can be configured not to respond to ICMP echo requests. [https://unix.stackexchange.com/questions/412446/how-to-disable-ping-response-icmp-echo-in-linux-all-the-time]<br />
<br />
If you receive no reply, this may be related to your default gateway or your Internet Service Provider (ISP). You can run a [[traceroute]] to further diagnose the route to the host.<br />
<br />
{{Note|If you receive an error like {{ic|ping: icmp open socket: Operation not permitted}} when executing ''ping'', try to re-install the {{Pkg|iputils}} package.}}<br />
<br />
== Network management ==<br />
<br />
To set up a network connection, go through the following steps:<br />
<br />
# Ensure your [[#Network interfaces|network interface]] is listed and enabled.<br />
# Connect to the network. Plug in the Ethernet cable or [[/Wireless|connect to the wireless LAN]].<br />
# Configure your network connection:<br />
#* [[#Static IP address|static IP address]]<br />
#* dynamic IP address: use [[#DHCP|DHCP]]<br />
<br />
{{Note|The installation image uses [[systemd-resolved]] and [[systemd-networkd]], which is configured as a DHCP client for [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/airootfs/etc/systemd/network/20-ethernet.network wired] and [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/airootfs/etc/systemd/network/20-wireless.network wireless] network interfaces.}}<br />
<br />
=== net-tools ===<br />
<br />
Arch Linux has deprecated {{Pkg|net-tools}} in favor of {{Pkg|iproute2}}.[https://www.archlinux.org/news/deprecation-of-net-tools/]<br />
<br />
{| class="wikitable"<br />
! Deprecated command !! Replacement commands<br />
|-<br />
| arp || ip neighbor<br />
|-<br />
| [[Wikipedia:ifconfig|ifconfig]] || ip address, ip link<br />
|-<br />
| netstat || [[#Investigate sockets|ss]]<br />
|-<br />
| route || ip route<br />
|}<br />
<br />
For a more complete rundown, see [https://dougvitale.wordpress.com/2011/12/21/deprecated-linux-networking-commands-and-their-replacements/ this blog post].<br />
<br />
=== iproute2 ===<br />
<br />
[[Wikipedia:iproute2|iproute2]] is a dependency of the {{Pkg|base}} [[meta package]] and provides the {{man|8|ip}} command-line interface, used to manage [[#Network interfaces|network interfaces]], [[#IP addresses|IP addresses]] and the [[#Routing table|routing table]]. Be aware that configuration made using {{ic|ip}} will be lost after a reboot. For persistent configuration, you can use a [[network manager]] or automate ''ip'' commands using scripts and [[systemd#Writing unit files|systemd units]]. Also note that {{ic|ip}} commands can generally be abbreviated, for clarity they are however spelled out in this article.<br />
<br />
=== Network interfaces ===<br />
<br />
By default [[udev]] assigns names to your network interfaces using [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names], which prefixes interfaces names with {{ic|en}} (wired/[[Wikipedia:Ethernet|Ethernet]]), {{ic|wl}} (wireless/WLAN), or {{ic|ww}} ([[Wikipedia:Wireless WAN|WWAN]]).<br />
<br />
{{Tip|To change interface names, see [[#Change interface name]] and [[#Revert to traditional interface names]].}}<br />
<br />
==== Listing network interfaces ====<br />
<br />
Both wired and wireless interface names can be found via {{ic|ls /sys/class/net}} or {{ic|ip link}}. Note that {{ic|lo}} is the [[Wikipedia:loop device|loop device]] and not used in making network connections.<br />
<br />
Wireless device names can also be retrieved using {{ic|iw dev}}. See also [[/Wireless#Get the name of the interface]].<br />
<br />
If your network interface is not listed, make sure your device driver was loaded successfully. See [[/Ethernet#Device driver]] or [[/Wireless#Device driver]].<br />
<br />
==== Enabling and disabling network interfaces ====<br />
<br />
Network interfaces can be enabled or disabled using {{ic|ip link set ''interface'' up{{!}}down}}, see {{man|8|ip-link}}.<br />
<br />
To check the status of the interface {{ic|eth0}}:<br />
<br />
{{hc|$ ip link show dev eth0|<br />
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state DOWN mode DEFAULT qlen 1000<br />
...<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 />
{{Note|If your default route is through interface {{ic|eth0}}, taking it down will also remove the route, and bringing it back up will not automatically re-establish the default route. See [[#Routing table]] for re-establishing it.}}<br />
<br />
=== Static IP address ===<br />
<br />
A static IP address can be configured with most standard [[#Network managers|network managers]] and also [[dhcpcd]].<br />
<br />
To manually configure a static IP address, add an IP address as described in [[#IP addresses]], set up your [[#Routing table|routing table]] and [[Domain name resolution|configure your DNS servers]].<br />
<br />
=== IP addresses ===<br />
<br />
[[Wikipedia:IP address|IP addresses]] are managed using {{man|8|ip-address}}.<br />
<br />
List IP addresses:<br />
<br />
$ ip address show<br />
<br />
Add an IP address to an interface:<br />
<br />
# ip address add ''address/prefix_len'' broadcast + dev ''interface''<br />
<br />
:Note that:<br />
<br />
:* the address is given in [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR notation]] to also supply a [[Wikipedia:Subnetwork|subnet mask]]<br />
:* {{ic|+}} is a special symbol that makes {{ic|ip}} derive the [[Wikipedia:Broadcast address|broadcast address]] from the IP address and the subnet mask<br />
<br />
:{{Note|Make sure manually assigned IP addresses do not conflict with DHCP assigned ones.}}<br />
<br />
Delete an IP address from an interface:<br />
<br />
# ip address del ''address/prefix_len'' dev ''interface''<br />
<br />
Delete all addresses matching a criteria, e.g. of a specific interface:<br />
<br />
# ip address flush dev ''interface''<br />
<br />
{{Tip|IP addresses can be calculated with [http://jodies.de/ipcalc ipcalc] ({{Pkg|ipcalc}}).}}<br />
<br />
=== Routing table ===<br />
<br />
The [[Wikipedia:Routing table|routing table]] is used to determine if you can reach an IP address directly or what gateway (router) you should use. If no other route matches the IP address, the [[Wikipedia:Default gateway|default gateway]] is used.<br />
<br />
The routing table is managed using {{man|8|ip-route}}.<br />
<br />
''PREFIX'' is either a CIDR notation or {{ic|default}} for the default gateway.<br />
<br />
List IPv4 routes:<br />
<br />
$ ip route show<br />
<br />
List IPv6 routes:<br />
<br />
$ ip -6 route<br />
<br />
Add a route:<br />
<br />
# ip route add ''PREFIX'' via ''address'' dev ''interface''<br />
<br />
Delete a route:<br />
<br />
# ip route del ''PREFIX'' via ''address'' dev ''interface''<br />
<br />
=== DHCP ===<br />
<br />
A [[Wikipedia:Dynamic Host Configuration Protocol|Dynamic Host Configuration Protocol]] (DHCP) server provides clients with a dynamic IP address, the subnet mask, the default gateway IP address and optionally also with DNS name servers.<br />
<br />
To use DHCP you need a DHCP server in your network and a DHCP client:<br />
<br />
{| class="wikitable"<br />
! Client !! Package !! [[Archiso]] !! Note !! Systemd units<br />
|-<br />
| [[dhcpcd]] || {{Pkg|dhcpcd}} || {{Yes}} || DHCP, DHCPv6, ZeroConf, static IP || {{ic|dhcpcd.service}}, {{ic|dhcpcd@''interface''.service}}<br />
|-<br />
| [https://www.isc.org/downloads/dhcp/ ISC dhclient] || {{Pkg|dhclient}} || {{Yes}} || DHCP, DHCPv6, BOOTP, static IP || {{ic|dhclient@''interface''.service}}<br />
|}<br />
<br />
{{Note|<br />
* You should not run two DHCP clients simultaneously.<br />
* Instead of directly using a standalone DHCP client you can also use a [[#Network managers|network manager]], some of which have a built-in DHCP client.<br />
* Alternatively, {{Pkg|iwd}} has a built-in DHCP client that can be used with some configuration: [[iwd#Enable built-in network configuration]].<br />
}}<br />
<br />
{{Tip|<br />
* You can check if a DHCP server is running with {{Pkg|dhcping}}.<br />
* While waiting for an IP to be assigned you can run something like {{ic|watch -n 1 ping -c 1 archlinux.org}}.<br />
}}<br />
<br />
==== Servers ====<br />
<br />
{{Expansion|[[systemd-networkd]] has DHCP server support.}}<br />
<br />
{| class="wikitable"<br />
! Server !! Package !! IPv4 !! IPv6 !! GUI !! Interfaces !! Storage backend(s) !! Note<br />
|-<br />
| [[dhcpd]] || {{Pkg|dhcp}} || {{Yes}} || {{Yes}} || [https://github.com/Akkadius/glass-isc-dhcp Glass-ISC-DHCP] || ? || File || <br />
|-<br />
| [[dnsmasq]] || {{Pkg|dnsmasq}} || {{Yes}} || {{Yes}} || {{No}} || ? || File || Also DNS, PXE and TFTP<br />
|-<br />
| [[Kea]] || {{Pkg|kea}} || {{Yes}} || {{Yes}} || [https://github.com/isc-projects/kea-anterius Kea-Anterius (Experimental)] || REST, RADIUS and NETCONF || File, MySQL, PostgreSQL and Cassandra || Also DNS <br />
|}<br />
<br />
=== Network managers ===<br />
<br />
A network manager lets you manage network connection settings in so called network profiles to facilitate switching networks.<br />
<br />
{{Note|There are many solutions to choose from, but remember that all of them are mutually exclusive; you should not run two daemons simultaneously.}}<br />
<br />
{| class="wikitable"<br />
! Network manager || GUI || [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64] || CLI tools || [[Wikipedia:Point-to-Point Protocol|PPP]] support <br>(e.g. 3G modem) || [[#DHCP|DHCP client]] || Systemd units <br />
|-<br />
! [[ConnMan]]<br />
| {{Y|8 unofficial}} || {{No}} || {{man|1|connmanctl}} || {{Yes}} (with {{aur|ofono}}) || internal || {{ic|connman.service}}<br />
|-<br />
! [[netctl]]<br />
| {{Y|2 unofficial}} || {{No}} || {{man|1|netctl}}, wifi-menu || {{Yes}} || [[dhcpcd]] or {{Pkg|dhclient}} || {{ic|netctl-ifplugd@''interface''.service}}, {{ic|netctl-auto@''interface''.service}}<br />
|-<br />
! [[NetworkManager]]<br />
| {{Yes}} || {{No}} || {{man|1|nmcli}}, {{man|1|nmtui}} || {{Yes}} || internal or {{Pkg|dhclient}} || {{ic|NetworkManager.service}}<br />
|-<br />
! [[systemd-networkd]]<br />
| {{No}} || {{Yes}} ({{Pkg|base}}) || {{man|1|networkctl}} || {{No|https://github.com/systemd/systemd/issues/481}} || internal || {{ic|systemd-networkd.service}}, {{ic|systemd-resolved.service}}<br />
|-<br />
! [[Wicd]]<br />
| {{Yes}} || {{No}} || {{man|8|wicd-cli|url=https://manned.org/wicd-cli.8}}, {{man|8|wicd-curses|url=https://manned.org/wicd-curses.8}} || {{No}} || [[dhcpcd]] or {{Pkg|dhclient}} || {{ic|wicd.service}}<br />
|}<br />
<br />
== Set the hostname ==<br />
<br />
A [[Wikipedia:Hostname|hostname]] is a unique name created to identify a machine on a network, configured in {{ic|/etc/hostname}}—see {{man|5|hostname}} and {{man|7|hostname}} for details. The file can contain the system's domain name, if any. To set the hostname, [[textedit|edit]] {{ic|/etc/hostname}} to include a single line with {{ic|''myhostname''}}:<br />
<br />
{{hc|/etc/hostname|<br />
''myhostname''<br />
}}<br />
<br />
{{Tip|For advice on choosing a hostname, see [https://tools.ietf.org/html/rfc1178 RFC 1178].}}<br />
<br />
Alternatively, using {{man|1|hostnamectl}}:<br />
<br />
# hostnamectl set-hostname ''myhostname''<br />
<br />
To temporarily set the hostname (until reboot), use {{man|1|hostname}} from {{Pkg|inetutils}}:<br />
<br />
# hostname ''myhostname''<br />
<br />
To set the "pretty" hostname and other machine metadata, see {{man|5|machine-info}}.<br />
<br />
=== Local hostname resolution ===<br />
<br />
{{Expansion|Explain why you want a resolvable hostname, why {{ic|127.0.1.1}} is used (and why a static IP address should be preferred over it).}}<br />
<br />
The {{ic|myhostname}} [[Name Service Switch]] (NSS) module of [[systemd]] provides local hostname resolution without having to edit {{ic|/etc/hosts}} ({{man|5|hosts}}). It is enabled by default.<br />
<br />
Some clients may however still rely on {{ic|/etc/hosts}}, see [https://lists.debian.org/debian-devel/2013/07/msg00809.html] [https://bugzilla.mozilla.org/show_bug.cgi?id=87717#c55] for examples.<br />
<br />
To configure the hosts file, add the following lines to {{ic|/etc/hosts}}:<br />
<br />
127.0.0.1 localhost<br />
::1 localhost<br />
127.0.1.1 ''myhostname''.localdomain ''myhostname''<br />
<br />
{{Note|The order of hostnames/aliases that follow the IP address in {{ic|/etc/hosts}} is significant. The first string is considered the canonical hostname and may be appended with parent domains, where domain components are separated by a dot (ie. {{ic|.localdomain}} above). All following strings on the same line are considered aliases. See {{man|5|hosts}} for more info.}}<br />
<br />
As a result the system resolves to both entries: <br />
<br />
{{hc|$ getent hosts|<br />
127.0.0.1 localhost<br />
127.0.0.1 localhost<br />
127.0.1.1 ''myhostname''.localdomain ''myhostname''<br />
}}<br />
<br />
For a system with a permanent IP address, that permanent IP address should be used instead of {{ic|127.0.1.1}}.<br />
<br />
=== Local network hostname resolution ===<br />
<br />
To make your machine accessible in your LAN via its hostname you can:<br />
<br />
* edit the {{ic|/etc/hosts}} file for every device in your LAN, see {{man|5|hosts}}<br />
* set up a [[DNS server]] to resolve your hostname and make the LAN devices use it (e.g. via [[#DHCP]])<br />
* or the easy way: use a [[Wikipedia:Zero-configuration networking|Zero-configuration networking]] service:<br />
** Hostname resolution via Microsoft's [[Wikipedia:NetBIOS#Name service|NetBIOS]]. Provided by [[Samba]] on Linux. It only requires the {{ic|nmb.service}}. Computers running Windows, macOS, or Linux with {{ic|nmb}} running, will be able to find your machine.<br />
** Hostname resolution via [[Wikipedia:Multicast DNS|mDNS]]. Provided by either {{ic|nss_mdns}} with [[Avahi]] (see [[Avahi#Hostname resolution]] for setup details) or [[systemd-resolved]]. Computers running macOS, or Linux with Avahi or systemd-resolved running, will be able to find your machine. The older Win32 API does not support mDNS, which may prevent some older Windows applications from accessing your device.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Change interface name ===<br />
<br />
{{Note|When changing the naming scheme, do not forget to update all network-related configuration files and custom systemd unit files to reflect the change.}}<br />
<br />
You can change the device name by defining the name manually with an udev-rule. For example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="aa:bb:cc:dd:ee:ff", NAME="net1"<br />
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="ff:ee:dd:cc:bb:aa", NAME="net0"<br />
}}<br />
<br />
These rules will be applied automatically at boot.<br />
<br />
A couple of things to note:<br />
<br />
* To get the MAC address of each card, use this command: {{ic|cat /sys/class/net/''device_name''/address}}<br />
* Make sure to use the lower-case hex values in your udev rules. It does not like upper-case.<br />
<br />
If the network card has a dynamic MAC, you can use {{ic|DEVPATH}}, for example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", DEVPATH=="/devices/platform/wemac.*", NAME="int"<br />
SUBSYSTEM=="net", DEVPATH=="/devices/pci*/*1c.0/*/net/*", NAME="en"<br />
}}<br />
<br />
To get the {{ic|DEVPATH}} of all currently-connected devices, see where the symlinks in {{ic|/sys/class/net/}} lead. For example:<br />
<br />
{{hc|file /sys/class/net/*|<br />
/sys/class/net/enp0s20f0u4u1: symbolic link to ../../devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4.1/2-4.1:1.0/net/enp0s20f0u4u1<br />
/sys/class/net/enp0s31f6: symbolic link to ../../devices/pci0000:00/0000:00:1f.6/net/enp0s31f6<br />
/sys/class/net/lo: symbolic link to ../../devices/virtual/net/lo<br />
/sys/class/net/wlp4s0: symbolic link to ../../devices/pci0000:00/0000:00:1c.6/0000:04:00.0/net/wlp4s0<br />
}}<br />
<br />
The device path should match both the new and old device name, since the rule may be executed more than once on bootup. For example, in the second rule, {{ic|"/devices/pci*/*1c.0/*/net/enp*"}} would be wrong since it will stop matching once the name is changed to {{ic|en}}. Only the system-default rule will fire the second time around, causing the name to be changed back to e.g. {{ic|enp1s0}}.<br />
<br />
If you are using a USB network device (e.g. Android phone tethering) that has a dynamic MAC address and you want to be able to use different USB ports, you could use a rule that matched depending on vendor and product ID instead:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", ACTION=="add", ATTRS{idVendor}=="12ab", ATTRS{idProduct}=="3cd4", NAME="net2"<br />
}}<br />
<br />
To [[udev#Testing rules before loading|test]] your rules, they can be triggered directly from userspace, e.g. with {{ic|udevadm --debug test /sys/class/net/*}}. Remember to first take down the interface you are trying to rename (e.g. {{ic|ip link set enp1s0 down}}).<br />
<br />
{{Note|When choosing the static names '''it should be avoided to use names in the format of "eth''X''" and "wlan''X''"''', because this may lead to race conditions between the kernel and udev during boot. Instead, it is better to use interface names that are not used by the kernel as default, e.g.: {{ic|net0}}, {{ic|net1}}, {{ic|wifi0}}, {{ic|wifi1}}. For further details please see the [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames systemd] documentation.}}<br />
<br />
=== Revert to traditional interface names ===<br />
<br />
If you would prefer to retain traditional interface names such as eth0, [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names] can be disabled by masking the udev rule:<br />
<br />
# ln -s /dev/null /etc/udev/rules.d/80-net-setup-link.rules<br />
<br />
Alternatively, add {{ic|1=net.ifnames=0}} to the [[kernel parameters]].<br />
<br />
=== Set device MTU and queue length ===<br />
<br />
You can change the device [[wikipedia:Maximum transmission unit|MTU]] and queue length by defining manually with an udev-rule. For example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", ATTR{mtu}="1500", ATTR{tx_queue_len}="2000"<br />
}}<br />
<br />
{{Note|<br />
* {{ic|mtu}}: For PPPoE, the MTU should be no larger than 1492. You can also set MTU via {{man|5|systemd.netdev}}.<br />
* {{ic|tx_queue_len}}: Small value for slower devices with a high latency like modem links and ISDN. High value is recommend for server connected over the high-speed Internet connections that perform large data transfers.<br />
}}<br />
<br />
=== Bonding or LAG ===<br />
<br />
See [[netctl#Bonding|netctl]] or [[systemd-networkd#Bonding a wired and wireless interface|systemd-networkd]], or [[Wireless bonding]].<br />
<br />
=== IP address aliasing ===<br />
<br />
IP aliasing is the process of adding more than one IP address to a network interface. With this, one node on a network can have multiple connections to a network, each serving a different purpose. Typical uses are virtual hosting of Web and FTP servers, or reorganizing servers without having to update any other machines (this is especially useful for nameservers).<br />
<br />
==== Example ====<br />
<br />
To manually set an alias, for some NIC, use {{Pkg|iproute2}} to execute<br />
<br />
# ip addr add 192.168.2.101/24 dev eth0 label eth0:1<br />
<br />
To remove a given alias execute<br />
<br />
# ip addr del 192.168.2.101/24 dev eth0:1<br />
<br />
Packets destined for a subnet will use the primary alias by default. If the destination IP is within a subnet of a secondary alias, then the source IP is set respectively. Consider the case where there is more than one NIC, the default routes can be listed with {{ic|ip route}}.<br />
<br />
=== Promiscuous mode ===<br />
<br />
Toggling [[wikipedia:Promiscuous mode|promiscuous mode]] will make a (wireless) NIC forward all traffic it receives to the OS for further processing. This is opposite to "normal mode" where a NIC will drop frames it is not intended to receive. It is most often used for advanced network troubleshooting and [[wikipedia:Packet sniffing|packet sniffing]].<br />
<br />
{{hc|/etc/systemd/system/promiscuous@.service|<nowiki><br />
[Unit]<br />
Description=Set %i interface in promiscuous mode<br />
After=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/ip link set dev %i promisc on<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
If you want to enable promiscuous mode on interface {{ic|eth0}} run [[enable]] {{ic|promiscuous@eth0.service}}.<br />
<br />
=== Investigate sockets ===<br />
<br />
''ss'' is a utility to investigate network ports and is part of the {{Pkg|iproute2}} package. It has a similar functionality to the [https://www.archlinux.org/news/deprecation-of-net-tools/ deprecated] netstat utility. <br />
<br />
Common usage includes:<br />
<br />
Display all TCP Sockets with service names:<br />
$ ss -at<br />
<br />
Display all TCP Sockets with port numbers:<br />
$ ss -atn<br />
<br />
Display all UDP Sockets:<br />
$ ss -au<br />
<br />
For more information see {{man|8|ss}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== The TCP window scaling problem ===<br />
<br />
TCP packets contain a "window" value in their headers indicating how much data the other host may send in return. This value is represented with only 16 bits, hence the window size is at most 64Kb. TCP packets are cached for a while (they have to be reordered), and as memory is (or used to be) limited, one host could easily run out of it.<br />
<br />
Back in 1992, as more and more memory became available, [http://www.faqs.org/rfcs/rfc1323.html RFC 1323] was written to improve the situation: Window Scaling. The "window" value, provided in all packets, will be modified by a Scale Factor defined once, at the very beginning of the connection. That 8-bit Scale Factor allows the Window to be up to 32 times higher than the initial 64Kb.<br />
<br />
It appears that some broken routers and firewalls on the Internet are rewriting the Scale Factor to 0 which causes misunderstandings between hosts. The Linux kernel 2.6.17 introduced a new calculation scheme generating higher Scale Factors, virtually making the aftermaths of the broken routers and firewalls more visible.<br />
<br />
The resulting connection is at best very slow or broken.<br />
<br />
==== How to diagnose the problem ====<br />
<br />
First of all, let us make it clear: this problem is odd. In some cases, you will not be able to use TCP connections (HTTP, FTP, ...) at all and in others, you will be able to communicate with some hosts (very few).<br />
<br />
When you have this problem, the {{ic|dmesg}}'s output is OK, logs are clean and {{ic|ip addr}} will report normal status... and actually everything appears normal.<br />
<br />
If you cannot browse any website, but you can ping some random hosts, chances are great that you are experiencing this problem: ping uses ICMP and is not affected by TCP problems.<br />
<br />
You can try to use [[Wireshark]]. You might see successful UDP and ICMP communications but unsuccessful TCP communications (only to foreign hosts).<br />
<br />
==== Ways of fixing it ====<br />
<br />
===== Bad =====<br />
<br />
To fix it the bad way, you can change the {{ic|tcp_rmem}} value, on which Scale Factor calculation is based. Although it should work for most hosts, it is not guaranteed, especially for very distant ones.<br />
<br />
# echo "4096 87380 174760" > /proc/sys/net/ipv4/tcp_rmem<br />
<br />
===== Good =====<br />
<br />
Simply disable Window Scaling. Since Window Scaling is a nice TCP feature, it may be uncomfortable to disable it, especially if you cannot fix the broken router. There are several ways to disable Window Scaling, and it seems that the most bulletproof way (which will work with most kernels) is to add the following line to {{ic|/etc/sysctl.d/99-disable_window_scaling.conf}} (see also [[sysctl]]):<br />
<br />
net.ipv4.tcp_window_scaling = 0<br />
<br />
===== Best =====<br />
<br />
This problem is caused by broken routers/firewalls, so let us change them. Some users have reported that the broken router was their very own DSL router.<br />
<br />
==== More about it ====<br />
<br />
This section is based on the LWN article [http://lwn.net/Articles/92727/ TCP window scaling and broken routers] and an archived Kernel Trap article: [https://web.archive.org/web/20120426135627/http://kerneltrap.org:80/node/6723 Window Scaling on the Internet].<br />
<br />
There are also several relevant threads on the LKML.<br />
<br />
=== Connected second PC unable to use bridged LAN ===<br />
<br />
First PC have two LAN. Second PC have one LAN and connected to first PC. Lets go second PC to give all access to LAN after bridged interface:<br />
<br />
{{Expansion|Explain what the settings actually do.}}<br />
<br />
# sysctl net.bridge.bridge-nf-filter-pppoe-tagged=0<br />
# sysctl net.bridge.bridge-nf-filter-vlan-tagged=0<br />
# sysctl net.bridge.bridge-nf-call-ip6tables=0<br />
# sysctl net.bridge.bridge-nf-call-iptables=0<br />
# sysctl net.bridge.bridge-nf-call-arptables=0<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/index.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-reference/ch05.en.html Debian Reference: Network setup]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/ RHEL7: Networking Guide]<br />
* [http://www.linuxhomenetworking.com/wiki/ Linux Home Networking]<br />
* [https://blog.packagecloud.io/eng/2016/06/22/monitoring-tuning-linux-networking-stack-receiving-data/ Monitoring and tuning the Linux Networking Stack: Receiving data]<br />
* [https://blog.packagecloud.io/eng/2017/02/06/monitoring-tuning-linux-networking-stack-sending-data/ Monitoring and tuning the Linux Networking Stack: Sending data]<br />
* [http://blog.yadutaf.fr/2017/07/28/tracing-a-packet-journey-using-linux-tracepoints-perf-ebpf/ Tracing a packet journey using tracepoints, perf and eBPF]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Network_configuration&diff=637042Network configuration2020-10-03T00:22:07Z<p>Hexhu: /* DHCP */ systemd-networkd also contains a DHCP client implementation</p>
<hr />
<div>[[Category:Network configuration]]<br />
[[cs:Network configuration]]<br />
[[el:Network configuration]]<br />
[[es:Network configuration]]<br />
[[fr:Connexions reseau]]<br />
[[it:Network configuration]]<br />
[[ja:ネットワーク設定]]<br />
[[nl:Network configuration]]<br />
[[pl:Network configuration]]<br />
[[pt:Network configuration]]<br />
[[ru:Network configuration]]<br />
[[zh-hans:Network configuration]]<br />
[[zh-hant:Network configuration]]<br />
{{Related articles start}}<br />
{{Related|Network Debugging}}<br />
{{Related|Firewalls}}<br />
{{Related|Jumbo frames}}<br />
{{Related|Internet sharing}}<br />
{{Related|Router}}<br />
{{Related articles end}}<br />
<br />
This article describes how to configure network connections on [[Wikipedia:OSI layer 3|OSI layer 3]] and above. Medium-specifics are handled in the [[/Ethernet]] and [[/Wireless]] subpages.<br />
<br />
== Check the connection ==<br />
<br />
To troubleshoot a network connection, go through the following conditions and ensure that you meet them:<br />
<br />
# Your [[#Network interfaces|network interface]] is listed and enabled. Otherwise, check the device driver – see [[/Ethernet#Device driver]] or [[/Wireless#Device driver]].<br />
# You are connected to the network. The cable is plugged in or you are [[/Wireless|connected to the wireless LAN]].<br />
# Your network interface has an [[#IP addresses|IP address]].<br />
# Your [[#Routing table|routing table]] is correctly set up.<br />
# You can [[#Ping|ping]] a local IP address (e.g. your default gateway).<br />
# You can [[#Ping|ping]] a public IP address (e.g. {{ic|8.8.8.8}}, which is a Google DNS server and is a convenient address to test with).<br />
# [[Check if you can resolve domain names]] (e.g. {{ic|archlinux.org}}).<br />
<br />
=== Ping ===<br />
<br />
{{Expansion|Add or link explanation of common ping errors like Unknown hosts / Network is unreachable.}}<br />
<br />
[[Wikipedia:Ping (networking utility)|ping]] is used to test if you can reach a host.<br />
<br />
{{hc|$ ping www.example.com|2=<br />
PING www.example.com (93.184.216.34): 56(84) data bytes<br />
64 bytes from 93.184.216.34: icmp_seq=0 ttl=56 time=11.632 ms<br />
64 bytes from 93.184.216.34: icmp_seq=1 ttl=56 time=11.726 ms<br />
64 bytes from 93.184.216.34: icmp_seq=2 ttl=56 time=10.683 ms<br />
...<br />
}}<br />
<br />
For every reply you receive, the ping utility will print a line like the above. For more information see the {{man|8|ping}} manual. Note that computers can be configured not to respond to ICMP echo requests. [https://unix.stackexchange.com/questions/412446/how-to-disable-ping-response-icmp-echo-in-linux-all-the-time]<br />
<br />
If you receive no reply, this may be related to your default gateway or your Internet Service Provider (ISP). You can run a [[traceroute]] to further diagnose the route to the host.<br />
<br />
{{Note|If you receive an error like {{ic|ping: icmp open socket: Operation not permitted}} when executing ''ping'', try to re-install the {{Pkg|iputils}} package.}}<br />
<br />
== Network management ==<br />
<br />
To set up a network connection, go through the following steps:<br />
<br />
# Ensure your [[#Network interfaces|network interface]] is listed and enabled.<br />
# Connect to the network. Plug in the Ethernet cable or [[/Wireless|connect to the wireless LAN]].<br />
# Configure your network connection:<br />
#* [[#Static IP address|static IP address]]<br />
#* dynamic IP address: use [[#DHCP|DHCP]]<br />
<br />
{{Note|The installation image uses [[systemd-resolved]] and [[systemd-networkd]], which is configured as a DHCP client for [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/airootfs/etc/systemd/network/20-ethernet.network wired] and [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/airootfs/etc/systemd/network/20-wireless.network wireless] network interfaces.}}<br />
<br />
=== net-tools ===<br />
<br />
Arch Linux has deprecated {{Pkg|net-tools}} in favor of {{Pkg|iproute2}}.[https://www.archlinux.org/news/deprecation-of-net-tools/]<br />
<br />
{| class="wikitable"<br />
! Deprecated command !! Replacement commands<br />
|-<br />
| arp || ip neighbor<br />
|-<br />
| [[Wikipedia:ifconfig|ifconfig]] || ip address, ip link<br />
|-<br />
| netstat || [[#Investigate sockets|ss]]<br />
|-<br />
| route || ip route<br />
|}<br />
<br />
For a more complete rundown, see [https://dougvitale.wordpress.com/2011/12/21/deprecated-linux-networking-commands-and-their-replacements/ this blog post].<br />
<br />
=== iproute2 ===<br />
<br />
[[Wikipedia:iproute2|iproute2]] is a dependency of the {{Pkg|base}} [[meta package]] and provides the {{man|8|ip}} command-line interface, used to manage [[#Network interfaces|network interfaces]], [[#IP addresses|IP addresses]] and the [[#Routing table|routing table]]. Be aware that configuration made using {{ic|ip}} will be lost after a reboot. For persistent configuration, you can use a [[network manager]] or automate ''ip'' commands using scripts and [[systemd#Writing unit files|systemd units]]. Also note that {{ic|ip}} commands can generally be abbreviated, for clarity they are however spelled out in this article.<br />
<br />
=== Network interfaces ===<br />
<br />
By default [[udev]] assigns names to your network interfaces using [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names], which prefixes interfaces names with {{ic|en}} (wired/[[Wikipedia:Ethernet|Ethernet]]), {{ic|wl}} (wireless/WLAN), or {{ic|ww}} ([[Wikipedia:Wireless WAN|WWAN]]).<br />
<br />
{{Tip|To change interface names, see [[#Change interface name]] and [[#Revert to traditional interface names]].}}<br />
<br />
==== Listing network interfaces ====<br />
<br />
Both wired and wireless interface names can be found via {{ic|ls /sys/class/net}} or {{ic|ip link}}. Note that {{ic|lo}} is the [[Wikipedia:loop device|loop device]] and not used in making network connections.<br />
<br />
Wireless device names can also be retrieved using {{ic|iw dev}}. See also [[/Wireless#Get the name of the interface]].<br />
<br />
If your network interface is not listed, make sure your device driver was loaded successfully. See [[/Ethernet#Device driver]] or [[/Wireless#Device driver]].<br />
<br />
==== Enabling and disabling network interfaces ====<br />
<br />
Network interfaces can be enabled or disabled using {{ic|ip link set ''interface'' up{{!}}down}}, see {{man|8|ip-link}}.<br />
<br />
To check the status of the interface {{ic|eth0}}:<br />
<br />
{{hc|$ ip link show dev eth0|<br />
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state DOWN mode DEFAULT qlen 1000<br />
...<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 />
{{Note|If your default route is through interface {{ic|eth0}}, taking it down will also remove the route, and bringing it back up will not automatically re-establish the default route. See [[#Routing table]] for re-establishing it.}}<br />
<br />
=== Static IP address ===<br />
<br />
A static IP address can be configured with most standard [[#Network managers|network managers]] and also [[dhcpcd]].<br />
<br />
To manually configure a static IP address, add an IP address as described in [[#IP addresses]], set up your [[#Routing table|routing table]] and [[Domain name resolution|configure your DNS servers]].<br />
<br />
=== IP addresses ===<br />
<br />
[[Wikipedia:IP address|IP addresses]] are managed using {{man|8|ip-address}}.<br />
<br />
List IP addresses:<br />
<br />
$ ip address show<br />
<br />
Add an IP address to an interface:<br />
<br />
# ip address add ''address/prefix_len'' broadcast + dev ''interface''<br />
<br />
:Note that:<br />
<br />
:* the address is given in [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR notation]] to also supply a [[Wikipedia:Subnetwork|subnet mask]]<br />
:* {{ic|+}} is a special symbol that makes {{ic|ip}} derive the [[Wikipedia:Broadcast address|broadcast address]] from the IP address and the subnet mask<br />
<br />
:{{Note|Make sure manually assigned IP addresses do not conflict with DHCP assigned ones.}}<br />
<br />
Delete an IP address from an interface:<br />
<br />
# ip address del ''address/prefix_len'' dev ''interface''<br />
<br />
Delete all addresses matching a criteria, e.g. of a specific interface:<br />
<br />
# ip address flush dev ''interface''<br />
<br />
{{Tip|IP addresses can be calculated with [http://jodies.de/ipcalc ipcalc] ({{Pkg|ipcalc}}).}}<br />
<br />
=== Routing table ===<br />
<br />
The [[Wikipedia:Routing table|routing table]] is used to determine if you can reach an IP address directly or what gateway (router) you should use. If no other route matches the IP address, the [[Wikipedia:Default gateway|default gateway]] is used.<br />
<br />
The routing table is managed using {{man|8|ip-route}}.<br />
<br />
''PREFIX'' is either a CIDR notation or {{ic|default}} for the default gateway.<br />
<br />
List IPv4 routes:<br />
<br />
$ ip route show<br />
<br />
List IPv6 routes:<br />
<br />
$ ip -6 route<br />
<br />
Add a route:<br />
<br />
# ip route add ''PREFIX'' via ''address'' dev ''interface''<br />
<br />
Delete a route:<br />
<br />
# ip route del ''PREFIX'' via ''address'' dev ''interface''<br />
<br />
=== DHCP ===<br />
<br />
A [[Wikipedia:Dynamic Host Configuration Protocol|Dynamic Host Configuration Protocol]] (DHCP) server provides clients with a dynamic IP address, the subnet mask, the default gateway IP address and optionally also with DNS name servers.<br />
<br />
To use DHCP you need a DHCP server in your network and a DHCP client:<br />
<br />
{| class="wikitable"<br />
! Client !! Package !! [[Archiso]] !! Note !! Systemd units<br />
|-<br />
| [[dhcpcd]] || {{Pkg|dhcpcd}} || {{Yes}} || DHCP, DHCPv6, ZeroConf, static IP || {{ic|dhcpcd.service}}, {{ic|dhcpcd@''interface''.service}}<br />
|-<br />
| [https://www.isc.org/downloads/dhcp/ ISC dhclient] || {{Pkg|dhclient}} || {{Yes}} || DHCP, DHCPv6, BOOTP, static IP || {{ic|dhclient@''interface''.service}}<br />
|-<br />
| [[systemd-networkd]] || {{Pkg|systemd}} || {{Yes}} || DHCP, DHCPv6, ZeroConf, static IP || {{ic|systemd-networkd.service}}<br />
|}<br />
<br />
Alternatively, {{Pkg|iwd}} has a built-in DHCP client that can be used with some configuration: [[iwd#Enable built-in network configuration]].<br />
<br />
{{Note|<br />
* You should not run two DHCP clients simultaneously.<br />
* Instead of directly using a DHCP client you can also use a [[#Network managers|network manager]].<br />
}}<br />
<br />
{{Tip|<br />
* You can check if a DHCP server is running with {{Pkg|dhcping}}.<br />
* While waiting for an IP to be assigned you can run something like {{ic|watch -n 1 ping -c 1 archlinux.org}}.<br />
}}<br />
<br />
==== Servers ====<br />
<br />
{{Expansion|[[systemd-networkd]] has DHCP server support.}}<br />
<br />
{| class="wikitable"<br />
! Server !! Package !! IPv4 !! IPv6 !! GUI !! Interfaces !! Storage backend(s) !! Note<br />
|-<br />
| [[dhcpd]] || {{Pkg|dhcp}} || {{Yes}} || {{Yes}} || [https://github.com/Akkadius/glass-isc-dhcp Glass-ISC-DHCP] || ? || File || <br />
|-<br />
| [[dnsmasq]] || {{Pkg|dnsmasq}} || {{Yes}} || {{Yes}} || {{No}} || ? || File || Also DNS, PXE and TFTP<br />
|-<br />
| [[Kea]] || {{Pkg|kea}} || {{Yes}} || {{Yes}} || [https://github.com/isc-projects/kea-anterius Kea-Anterius (Experimental)] || REST, RADIUS and NETCONF || File, MySQL, PostgreSQL and Cassandra || Also DNS <br />
|}<br />
<br />
=== Network managers ===<br />
<br />
A network manager lets you manage network connection settings in so called network profiles to facilitate switching networks.<br />
<br />
{{Note|There are many solutions to choose from, but remember that all of them are mutually exclusive; you should not run two daemons simultaneously.}}<br />
<br />
{| class="wikitable"<br />
! Network manager || GUI || [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64] || CLI tools || [[Wikipedia:Point-to-Point Protocol|PPP]] support <br>(e.g. 3G modem) || [[#DHCP|DHCP client]] || Systemd units <br />
|-<br />
! [[ConnMan]]<br />
| {{Y|8 unofficial}} || {{No}} || {{man|1|connmanctl}} || {{Yes}} (with {{aur|ofono}}) || internal || {{ic|connman.service}}<br />
|-<br />
! [[netctl]]<br />
| {{Y|2 unofficial}} || {{No}} || {{man|1|netctl}}, wifi-menu || {{Yes}} || [[dhcpcd]] or {{Pkg|dhclient}} || {{ic|netctl-ifplugd@''interface''.service}}, {{ic|netctl-auto@''interface''.service}}<br />
|-<br />
! [[NetworkManager]]<br />
| {{Yes}} || {{No}} || {{man|1|nmcli}}, {{man|1|nmtui}} || {{Yes}} || internal or {{Pkg|dhclient}} || {{ic|NetworkManager.service}}<br />
|-<br />
! [[systemd-networkd]]<br />
| {{No}} || {{Yes}} ({{Pkg|base}}) || {{man|1|networkctl}} || {{No|https://github.com/systemd/systemd/issues/481}} || internal || {{ic|systemd-networkd.service}}, {{ic|systemd-resolved.service}}<br />
|-<br />
! [[Wicd]]<br />
| {{Yes}} || {{No}} || {{man|8|wicd-cli|url=https://manned.org/wicd-cli.8}}, {{man|8|wicd-curses|url=https://manned.org/wicd-curses.8}} || {{No}} || [[dhcpcd]] or {{Pkg|dhclient}} || {{ic|wicd.service}}<br />
|}<br />
<br />
== Set the hostname ==<br />
<br />
A [[Wikipedia:Hostname|hostname]] is a unique name created to identify a machine on a network, configured in {{ic|/etc/hostname}}—see {{man|5|hostname}} and {{man|7|hostname}} for details. The file can contain the system's domain name, if any. To set the hostname, [[textedit|edit]] {{ic|/etc/hostname}} to include a single line with {{ic|''myhostname''}}:<br />
<br />
{{hc|/etc/hostname|<br />
''myhostname''<br />
}}<br />
<br />
{{Tip|For advice on choosing a hostname, see [https://tools.ietf.org/html/rfc1178 RFC 1178].}}<br />
<br />
Alternatively, using {{man|1|hostnamectl}}:<br />
<br />
# hostnamectl set-hostname ''myhostname''<br />
<br />
To temporarily set the hostname (until reboot), use {{man|1|hostname}} from {{Pkg|inetutils}}:<br />
<br />
# hostname ''myhostname''<br />
<br />
To set the "pretty" hostname and other machine metadata, see {{man|5|machine-info}}.<br />
<br />
=== Local hostname resolution ===<br />
<br />
{{Expansion|Explain why you want a resolvable hostname, why {{ic|127.0.1.1}} is used (and why a static IP address should be preferred over it).}}<br />
<br />
The {{ic|myhostname}} [[Name Service Switch]] (NSS) module of [[systemd]] provides local hostname resolution without having to edit {{ic|/etc/hosts}} ({{man|5|hosts}}). It is enabled by default.<br />
<br />
Some clients may however still rely on {{ic|/etc/hosts}}, see [https://lists.debian.org/debian-devel/2013/07/msg00809.html] [https://bugzilla.mozilla.org/show_bug.cgi?id=87717#c55] for examples.<br />
<br />
To configure the hosts file, add the following lines to {{ic|/etc/hosts}}:<br />
<br />
127.0.0.1 localhost<br />
::1 localhost<br />
127.0.1.1 ''myhostname''.localdomain ''myhostname''<br />
<br />
{{Note|The order of hostnames/aliases that follow the IP address in {{ic|/etc/hosts}} is significant. The first string is considered the canonical hostname and may be appended with parent domains, where domain components are separated by a dot (ie. {{ic|.localdomain}} above). All following strings on the same line are considered aliases. See {{man|5|hosts}} for more info.}}<br />
<br />
As a result the system resolves to both entries: <br />
<br />
{{hc|$ getent hosts|<br />
127.0.0.1 localhost<br />
127.0.0.1 localhost<br />
127.0.1.1 ''myhostname''.localdomain ''myhostname''<br />
}}<br />
<br />
For a system with a permanent IP address, that permanent IP address should be used instead of {{ic|127.0.1.1}}.<br />
<br />
=== Local network hostname resolution ===<br />
<br />
To make your machine accessible in your LAN via its hostname you can:<br />
<br />
* edit the {{ic|/etc/hosts}} file for every device in your LAN, see {{man|5|hosts}}<br />
* set up a [[DNS server]] to resolve your hostname and make the LAN devices use it (e.g. via [[#DHCP]])<br />
* or the easy way: use a [[Wikipedia:Zero-configuration networking|Zero-configuration networking]] service:<br />
** Hostname resolution via Microsoft's [[Wikipedia:NetBIOS#Name service|NetBIOS]]. Provided by [[Samba]] on Linux. It only requires the {{ic|nmb.service}}. Computers running Windows, macOS, or Linux with {{ic|nmb}} running, will be able to find your machine.<br />
** Hostname resolution via [[Wikipedia:Multicast DNS|mDNS]]. Provided by either {{ic|nss_mdns}} with [[Avahi]] (see [[Avahi#Hostname resolution]] for setup details) or [[systemd-resolved]]. Computers running macOS, or Linux with Avahi or systemd-resolved running, will be able to find your machine. The older Win32 API does not support mDNS, which may prevent some older Windows applications from accessing your device.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Change interface name ===<br />
<br />
{{Note|When changing the naming scheme, do not forget to update all network-related configuration files and custom systemd unit files to reflect the change.}}<br />
<br />
You can change the device name by defining the name manually with an udev-rule. For example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="aa:bb:cc:dd:ee:ff", NAME="net1"<br />
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="ff:ee:dd:cc:bb:aa", NAME="net0"<br />
}}<br />
<br />
These rules will be applied automatically at boot.<br />
<br />
A couple of things to note:<br />
<br />
* To get the MAC address of each card, use this command: {{ic|cat /sys/class/net/''device_name''/address}}<br />
* Make sure to use the lower-case hex values in your udev rules. It does not like upper-case.<br />
<br />
If the network card has a dynamic MAC, you can use {{ic|DEVPATH}}, for example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", DEVPATH=="/devices/platform/wemac.*", NAME="int"<br />
SUBSYSTEM=="net", DEVPATH=="/devices/pci*/*1c.0/*/net/*", NAME="en"<br />
}}<br />
<br />
To get the {{ic|DEVPATH}} of all currently-connected devices, see where the symlinks in {{ic|/sys/class/net/}} lead. For example:<br />
<br />
{{hc|file /sys/class/net/*|<br />
/sys/class/net/enp0s20f0u4u1: symbolic link to ../../devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4.1/2-4.1:1.0/net/enp0s20f0u4u1<br />
/sys/class/net/enp0s31f6: symbolic link to ../../devices/pci0000:00/0000:00:1f.6/net/enp0s31f6<br />
/sys/class/net/lo: symbolic link to ../../devices/virtual/net/lo<br />
/sys/class/net/wlp4s0: symbolic link to ../../devices/pci0000:00/0000:00:1c.6/0000:04:00.0/net/wlp4s0<br />
}}<br />
<br />
The device path should match both the new and old device name, since the rule may be executed more than once on bootup. For example, in the second rule, {{ic|"/devices/pci*/*1c.0/*/net/enp*"}} would be wrong since it will stop matching once the name is changed to {{ic|en}}. Only the system-default rule will fire the second time around, causing the name to be changed back to e.g. {{ic|enp1s0}}.<br />
<br />
If you are using a USB network device (e.g. Android phone tethering) that has a dynamic MAC address and you want to be able to use different USB ports, you could use a rule that matched depending on vendor and product ID instead:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", ACTION=="add", ATTRS{idVendor}=="12ab", ATTRS{idProduct}=="3cd4", NAME="net2"<br />
}}<br />
<br />
To [[udev#Testing rules before loading|test]] your rules, they can be triggered directly from userspace, e.g. with {{ic|udevadm --debug test /sys/class/net/*}}. Remember to first take down the interface you are trying to rename (e.g. {{ic|ip link set enp1s0 down}}).<br />
<br />
{{Note|When choosing the static names '''it should be avoided to use names in the format of "eth''X''" and "wlan''X''"''', because this may lead to race conditions between the kernel and udev during boot. Instead, it is better to use interface names that are not used by the kernel as default, e.g.: {{ic|net0}}, {{ic|net1}}, {{ic|wifi0}}, {{ic|wifi1}}. For further details please see the [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames systemd] documentation.}}<br />
<br />
=== Revert to traditional interface names ===<br />
<br />
If you would prefer to retain traditional interface names such as eth0, [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names] can be disabled by masking the udev rule:<br />
<br />
# ln -s /dev/null /etc/udev/rules.d/80-net-setup-link.rules<br />
<br />
Alternatively, add {{ic|1=net.ifnames=0}} to the [[kernel parameters]].<br />
<br />
=== Set device MTU and queue length ===<br />
<br />
You can change the device [[wikipedia:Maximum transmission unit|MTU]] and queue length by defining manually with an udev-rule. For example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", ATTR{mtu}="1500", ATTR{tx_queue_len}="2000"<br />
}}<br />
<br />
{{Note|<br />
* {{ic|mtu}}: For PPPoE, the MTU should be no larger than 1492. You can also set MTU via {{man|5|systemd.netdev}}.<br />
* {{ic|tx_queue_len}}: Small value for slower devices with a high latency like modem links and ISDN. High value is recommend for server connected over the high-speed Internet connections that perform large data transfers.<br />
}}<br />
<br />
=== Bonding or LAG ===<br />
<br />
See [[netctl#Bonding|netctl]] or [[systemd-networkd#Bonding a wired and wireless interface|systemd-networkd]], or [[Wireless bonding]].<br />
<br />
=== IP address aliasing ===<br />
<br />
IP aliasing is the process of adding more than one IP address to a network interface. With this, one node on a network can have multiple connections to a network, each serving a different purpose. Typical uses are virtual hosting of Web and FTP servers, or reorganizing servers without having to update any other machines (this is especially useful for nameservers).<br />
<br />
==== Example ====<br />
<br />
To manually set an alias, for some NIC, use {{Pkg|iproute2}} to execute<br />
<br />
# ip addr add 192.168.2.101/24 dev eth0 label eth0:1<br />
<br />
To remove a given alias execute<br />
<br />
# ip addr del 192.168.2.101/24 dev eth0:1<br />
<br />
Packets destined for a subnet will use the primary alias by default. If the destination IP is within a subnet of a secondary alias, then the source IP is set respectively. Consider the case where there is more than one NIC, the default routes can be listed with {{ic|ip route}}.<br />
<br />
=== Promiscuous mode ===<br />
<br />
Toggling [[wikipedia:Promiscuous mode|promiscuous mode]] will make a (wireless) NIC forward all traffic it receives to the OS for further processing. This is opposite to "normal mode" where a NIC will drop frames it is not intended to receive. It is most often used for advanced network troubleshooting and [[wikipedia:Packet sniffing|packet sniffing]].<br />
<br />
{{hc|/etc/systemd/system/promiscuous@.service|<nowiki><br />
[Unit]<br />
Description=Set %i interface in promiscuous mode<br />
After=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/ip link set dev %i promisc on<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
If you want to enable promiscuous mode on interface {{ic|eth0}} run [[enable]] {{ic|promiscuous@eth0.service}}.<br />
<br />
=== Investigate sockets ===<br />
<br />
''ss'' is a utility to investigate network ports and is part of the {{Pkg|iproute2}} package. It has a similar functionality to the [https://www.archlinux.org/news/deprecation-of-net-tools/ deprecated] netstat utility. <br />
<br />
Common usage includes:<br />
<br />
Display all TCP Sockets with service names:<br />
$ ss -at<br />
<br />
Display all TCP Sockets with port numbers:<br />
$ ss -atn<br />
<br />
Display all UDP Sockets:<br />
$ ss -au<br />
<br />
For more information see {{man|8|ss}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== The TCP window scaling problem ===<br />
<br />
TCP packets contain a "window" value in their headers indicating how much data the other host may send in return. This value is represented with only 16 bits, hence the window size is at most 64Kb. TCP packets are cached for a while (they have to be reordered), and as memory is (or used to be) limited, one host could easily run out of it.<br />
<br />
Back in 1992, as more and more memory became available, [http://www.faqs.org/rfcs/rfc1323.html RFC 1323] was written to improve the situation: Window Scaling. The "window" value, provided in all packets, will be modified by a Scale Factor defined once, at the very beginning of the connection. That 8-bit Scale Factor allows the Window to be up to 32 times higher than the initial 64Kb.<br />
<br />
It appears that some broken routers and firewalls on the Internet are rewriting the Scale Factor to 0 which causes misunderstandings between hosts. The Linux kernel 2.6.17 introduced a new calculation scheme generating higher Scale Factors, virtually making the aftermaths of the broken routers and firewalls more visible.<br />
<br />
The resulting connection is at best very slow or broken.<br />
<br />
==== How to diagnose the problem ====<br />
<br />
First of all, let us make it clear: this problem is odd. In some cases, you will not be able to use TCP connections (HTTP, FTP, ...) at all and in others, you will be able to communicate with some hosts (very few).<br />
<br />
When you have this problem, the {{ic|dmesg}}'s output is OK, logs are clean and {{ic|ip addr}} will report normal status... and actually everything appears normal.<br />
<br />
If you cannot browse any website, but you can ping some random hosts, chances are great that you are experiencing this problem: ping uses ICMP and is not affected by TCP problems.<br />
<br />
You can try to use [[Wireshark]]. You might see successful UDP and ICMP communications but unsuccessful TCP communications (only to foreign hosts).<br />
<br />
==== Ways of fixing it ====<br />
<br />
===== Bad =====<br />
<br />
To fix it the bad way, you can change the {{ic|tcp_rmem}} value, on which Scale Factor calculation is based. Although it should work for most hosts, it is not guaranteed, especially for very distant ones.<br />
<br />
# echo "4096 87380 174760" > /proc/sys/net/ipv4/tcp_rmem<br />
<br />
===== Good =====<br />
<br />
Simply disable Window Scaling. Since Window Scaling is a nice TCP feature, it may be uncomfortable to disable it, especially if you cannot fix the broken router. There are several ways to disable Window Scaling, and it seems that the most bulletproof way (which will work with most kernels) is to add the following line to {{ic|/etc/sysctl.d/99-disable_window_scaling.conf}} (see also [[sysctl]]):<br />
<br />
net.ipv4.tcp_window_scaling = 0<br />
<br />
===== Best =====<br />
<br />
This problem is caused by broken routers/firewalls, so let us change them. Some users have reported that the broken router was their very own DSL router.<br />
<br />
==== More about it ====<br />
<br />
This section is based on the LWN article [http://lwn.net/Articles/92727/ TCP window scaling and broken routers] and an archived Kernel Trap article: [https://web.archive.org/web/20120426135627/http://kerneltrap.org:80/node/6723 Window Scaling on the Internet].<br />
<br />
There are also several relevant threads on the LKML.<br />
<br />
=== Connected second PC unable to use bridged LAN ===<br />
<br />
First PC have two LAN. Second PC have one LAN and connected to first PC. Lets go second PC to give all access to LAN after bridged interface:<br />
<br />
{{Expansion|Explain what the settings actually do.}}<br />
<br />
# sysctl net.bridge.bridge-nf-filter-pppoe-tagged=0<br />
# sysctl net.bridge.bridge-nf-filter-vlan-tagged=0<br />
# sysctl net.bridge.bridge-nf-call-ip6tables=0<br />
# sysctl net.bridge.bridge-nf-call-iptables=0<br />
# sysctl net.bridge.bridge-nf-call-arptables=0<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/index.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-reference/ch05.en.html Debian Reference: Network setup]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/ RHEL7: Networking Guide]<br />
* [http://www.linuxhomenetworking.com/wiki/ Linux Home Networking]<br />
* [https://blog.packagecloud.io/eng/2016/06/22/monitoring-tuning-linux-networking-stack-receiving-data/ Monitoring and tuning the Linux Networking Stack: Receiving data]<br />
* [https://blog.packagecloud.io/eng/2017/02/06/monitoring-tuning-linux-networking-stack-sending-data/ Monitoring and tuning the Linux Networking Stack: Sending data]<br />
* [http://blog.yadutaf.fr/2017/07/28/tracing-a-packet-journey-using-linux-tracepoints-perf-ebpf/ Tracing a packet journey using tracepoints, perf and eBPF]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=MariaDB&diff=590853MariaDB2019-12-03T06:06:02Z<p>Hexhu: fix link for point-in-time recovery</p>
<hr />
<div>[[Category:Relational DBMSs]]<br />
[[cs:MySQL]]<br />
[[de:MySQL]]<br />
[[es:MySQL]]<br />
[[fr:MariaDB]]<br />
[[it:MySQL]]<br />
[[ja:MariaDB]]<br />
[[ru:MySQL]]<br />
[[sr:MySQL]]<br />
[[zh-hans:MariaDB]]<br />
{{Related articles start}}<br />
{{Related|phpMyAdmin}}<br />
{{Related|Adminer}}<br />
{{Related|JDBC and MySQL}}<br />
{{Related|Open Database Connectivity}}<br />
{{Related articles end}}<br />
[[Wikipedia:MariaDB|MariaDB]] is a reliable, high performance and full-featured database server which aims to be an 'always Free, backward compatible, drop-in' replacement of [[MySQL]]. Since 2013 MariaDB is Arch Linux's default implementation of MySQL.[https://www.archlinux.org/news/mariadb-replaces-mysql-in-repositories/]<br />
<br />
== Installation ==<br />
<br />
[https://mariadb.com/ MariaDB] is the [https://www.archlinux.org/news/mariadb-replaces-mysql-in-repositories/ default implementation] of MySQL in Arch Linux, provided with the {{Pkg|mariadb}} package.<br />
<br />
{{Tip|<br />
* If the database (in {{ic|/var/lib/mysql}}) resides on a [[Btrfs]] file system, you should consider disabling [[Btrfs#Copy-on-Write (CoW)|Copy-on-Write]] for the directory before creating any database.<br />
* If the database resides on a [[ZFS]] file system, you should consult [[ZFS#Databases]] before creating any database.<br />
}}<br />
<br />
Install {{Pkg|mariadb}}, afterwards run the following command '''before starting''' the {{ic|mariadb.service}}:<br />
<br />
# mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql<br />
<br />
{{Note|For security reasons, the systemd service file contains {{ic|1=ProtectHome=true}}, which prevents MariaDB from accessing files under the {{ic|/home}}, {{ic|/root}} and {{ic|/run/user}} hierarchies. The {{ic|datadir}} has to be in an accessible location and [[chown|owned]] by the {{ic|mysql}} user and group.<br />
You can modify this behavior by creating a supplementary service file as described here: https://mariadb.com/kb/en/mariadb/systemd/}}<br />
<br />
Now the {{ic|mariadb.service}} can be started and/or enabled with [[systemd#Using units|systemd]].<br />
<br />
{{Tip|If you use something different from {{ic|/var/lib/mysql}} for your data dir, you need to set {{Ic|1=datadir=<YOUR_DATADIR>}} under section {{Ic|[mysqld]}} of your {{Ic|/etc/my.cnf.d/server.cnf}}.}}<br />
<br />
To simplify administration, you might want to install a [[MySQL#Graphical tools|front-end]].<br />
<br />
== Configuration ==<br />
<br />
{{Out of date|The main /etc/my.cnf configuration file is now splitted into various files in /etc/my.cnf.d/ dir.}}<br />
<br />
Once you have started the MySQL server and added a root account, you may want to change the default configuration.<br />
<br />
To log in as {{ic|root}} on the MySQL server, use the following command:<br />
$ mysql -u root -p<br />
<br />
=== Improve security ===<br />
<br />
The {{ic|mysql_secure_installation}} command will interactively guide you through a number of recommended security measures at the database level:<br />
# mysql_secure_installation<br />
<br />
=== Add user ===<br />
<br />
Creating a new user takes two steps: create the user; grant privileges. In the below example, the user ''monty'' with ''some_pass'' as password is being created, then granted full permissions to the database ''mydb'': <br />
<br />
{{hc|$ mysql -u root -p|<br />
MariaDB> CREATE USER 'monty'@'localhost' IDENTIFIED BY 'some_pass';<br />
MariaDB> GRANT ALL PRIVILEGES ON mydb.* TO 'monty'@'localhost';<br />
MariaDB> FLUSH PRIVILEGES;<br />
MariaDB> quit}}<br />
<br />
=== Configuration files ===<br />
<br />
''MariaDB'' configuration options are read from the following files in the given order (according to {{ic|mysqld --help --verbose | tail -20}} output):<br />
<br />
/etc/my.cnf /etc/my.cnf.d/ ~/.my.cnf<br />
<br />
Depending on the scope of the changes you want to make (system-wide, user-only...), use the corresponding file. See [https://mariadb.com/kb/en/library/configuring-mariadb-with-option-files/ this entry] of the Knowledge Base for more information.<br />
<br />
=== Grant remote access ===<br />
<br />
{{Warning|This is not considered as best practice and may cause security issues. Consider using [[Secure Shell]], [[VNC]] or [[VPN]], if you want to maintain the MySQL-server outside and/or inside your LAN.}}<br />
<br />
If you want to access your MySQL server from other LAN hosts, you have to edit the following lines in {{ic|/etc/my.cnf.d/server.cnf}}:<br />
<br />
[mysqld]<br />
...<br />
#skip-networking<br />
bind-address = <some ip-address><br />
...<br />
<br />
Grant any MySQL user remote access (example for root):<br />
<br />
$ mysql -u root -p<br />
<br />
Check current users with remote access privileged:<br />
<br />
SELECT User, Host FROM mysql.user WHERE Host <> 'localhost';<br />
<br />
Now grant remote access for your user (here root)::<br />
<br />
GRANT ALL PRIVILEGES ON *.* TO 'root'@'192.168.1.%' IDENTIFIED BY 'my_optional_remote_password' WITH GRANT OPTION;<br />
<br />
You can change the '%' wildcard to a specific host if you like. The password can be different from user's main password.<br />
<br />
=== Disable remote access ===<br />
<br />
The MySQL server is accessible from the network by default. If MySQL is only needed for the localhost, you can improve security by not listening on TCP port 3306. To refuse remote connections, uncomment the following line in {{ic|/etc/my.cnf.d/server.cnf}}:<br />
<br />
skip-networking<br />
<br />
You will still be able to log in from the localhost.<br />
<br />
=== Enable auto-completion ===<br />
<br />
{{Note|Enabling this feature can make the client initialization longer.}}<br />
<br />
The MySQL client completion feature is disabled by default. To enable it system-wide edit {{ic|/etc/mysql/my.cnf}}, and replace {{ic|no-auto-rehash}} by {{ic|auto-rehash}} (or add if it doesn't exist). Note that this must be placed under {{ic|mysql}} and not {{ic|mysqld}}. Completion will be enabled next time you run the MySQL client.<br />
<br />
=== Using UTF8MB4 ===<br />
<br />
{{Warning|Before changing the character set be sure to create a backup first.}}<br />
<br />
{{Note|<br />
* The {{Pkg|mariadb}} package already uses {{ic|utf8mb4}} as charset and {{ic|utf8mb4_unicode_ci}} as collation. Users using the default (character) settings may want to skip this section.<br />
* UTF8MB4 is recommended over UTF-8 since it allows full Unicode support [https://mathiasbynens.be/notes/mysql-utf8mb4] [https://stackoverflow.com/questions/30074492/what-is-the-difference-between-utf8mb4-and-utf8-charsets-in-mysql].}}<br />
<br />
[[Append]] the following values to the main configuration file located at {{ic|/etc/mysql/my.cnf}}:<br />
<br />
{{bc|<nowiki><br />
[client]<br />
default-character-set = utf8mb4<br />
<br />
[mysqld]<br />
collation_server = utf8mb4_unicode_ci<br />
character_set_server = utf8mb4<br />
<br />
[mysql]<br />
default-character-set = utf8mb4<br />
</nowiki>}}<br />
<br />
[[Restart]] {{ic|mariadb.service}} to apply the changes.<br />
<br />
See [[#Database maintenance]] to optimize and check the database health.<br />
<br />
=== Increase character limit ===<br />
<br />
{{Out of date|As of 10.3.1 this section is no longer applicable. All 3 options are now enabled by default. {{ic|innodb_file_format}} and {{ic|innodb_large_prefix}} are deprecated and can no longer be used. The mariadb service will fail to start if either are included in {{ic|my.cnf}} ([https://mariadb.com/kb/en/library/innodb-system-variables/#innodb_file_format source])}}<br />
<br />
{{Note|The character-limit depends on the character-set in use [http://mechanics.flite.com/blog/2014/07/29/using-innodb-large-prefix-to-avoid-error-1071/] [https://dev.mysql.com/doc/refman/5.5/en/innodb-parameters.html#sysvar_innodb_large_prefix] [https://easyengine.io/tutorials/mysql/enable-innodb-file-per-table/].}}<br />
<br />
For InnoDB execute the following commands to support a higher character-limit:<br />
<br />
mysql> set global innodb_file_format = BARRACUDA;<br />
Query OK, 0 rows affected (0.00 sec)<br />
<br />
mysql> set global innodb_file_per_table = ON;<br />
Query OK, 0 rows affected (0.00 sec)<br />
<br />
mysql> set global innodb_large_prefix = ON;<br />
Query OK, 0 rows affected (0.00 sec)<br />
<br />
[[Append]] the following lines in {{ic|/etc/mysql/my.cnf}} to always use a higher character-limit:<br />
<br />
[mysqld]<br />
innodb_file_format = barracuda<br />
innodb_file_per_table = 1<br />
innodb_large_prefix = 1<br />
<br />
[[Restart]] {{ic|mariadb.service}} to apply the changes.<br />
<br />
On table creating append the {{ic|ROW_FORMAT}} as seen in the example:<br />
<br />
mysql> create table if not exists products (<br />
-> day date not null,<br />
-> product_id int not null,<br />
-> dimension1 varchar(500) not null,<br />
-> dimension2 varchar(500) not null,<br />
-> unique index unique_index (day, product_id, dimension1, dimension2)<br />
-> ) ENGINE=InnoDB ROW_FORMAT=DYNAMIC;<br />
Query OK, 0 rows affected (0.02 sec)<br />
<br />
=== Using a TMPFS for tmpdir ===<br />
<br />
The directory used by MySQL for storing temporary files is named ''tmpdir''. For example, it is used to perform disk based large sorts, as well as for internal and explicit temporary tables.<br />
<br />
Create the directory with appropriate permissions:<br />
<br />
# mkdir -pv /var/lib/mysqltmp<br />
# chown mysql:mysql /var/lib/mysqltmp<br />
<br />
Find the id and gid of the {{ic|mysql}} user and group:<br />
<br />
$ id mysql<br />
uid=27(mysql) gid=27(mysql) groups=27(mysql)<br />
<br />
Add to your {{ic|/etc/fstab}} file.<br />
<br />
tmpfs /var/lib/mysqltmp tmpfs rw,gid=27,uid=27,size=100M,mode=0750,noatime 0 0<br />
<br />
Add to your {{ic|/etc/mysql/my.cnf}} file under the {{ic|mysqld}} group:<br />
<br />
tmpdir = /var/lib/mysqltmp<br />
<br />
Then reboot or ( shutdown mysql, mount the tmpdir, start mysql ).<br />
<br />
=== Time zone tables ===<br />
<br />
Although time zone tables are created during the installation, they are not automatically populated. They need to be populated if you are planning on using CONVERT_TZ() in SQL queries.<br />
<br />
To populate the time zone tables with all the time zones:<br />
<br />
$ mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql<br />
<br />
Optionally, you may populate the table with specific time zone files:<br />
<br />
$ mysql_tzinfo_to_sql <timezone_file> <timezone_name> | mysql -u root -p mysql<br />
<br />
== Database maintenance ==<br />
<br />
=== Upgrade databases on major releases ===<br />
<br />
Upon a major version release of {{Pkg|mariadb}} (for example mariadb-10.1.10-1 to mariadb-10.1.18-1), it is wise to upgrade databases:<br />
<br />
$ mysql_upgrade -u root -p<br />
<br />
To upgrade from 10.1.x to 10.3.x:<br />
<br />
* keep the 10.1.x database daemon running<br />
* upgrade the package<br />
* run {{ic|mysql_upgrade}} (from the new package version) against the old still-running daemon. This will produce some error messages; however, the upgrade will succeed.<br />
* restart the daemon, so the 10.3.x daemon runs.<br />
<br />
Alternatively, stop the (old) daemon, run the (new) daemon in safe mode, run {{ic|mysql_upgrade}} against that, and then start the (new) daemon as described below in [[#Unable to run mysql upgrade because MySQL cannot start|troubleshooting]].<br />
<br />
=== Checking, optimizing and repairing databases ===<br />
<br />
{{Pkg|mariadb}} ships with {{ic|mysqlcheck}} which can be used to check, repair, and optimize tables within databases from the shell. See the mysqlcheck man page for more. Several command tasks are shown:<br />
<br />
To check all tables in all databases:<br />
<br />
$ mysqlcheck --all-databases -u root -p -c<br />
<br />
To analyze all tables in all databases:<br />
<br />
$ mysqlcheck --all-databases -u root -p -a<br />
<br />
To repair all tables in all databases:<br />
<br />
$ mysqlcheck --all-databases -u root -p -r<br />
<br />
To optimize all tables in all databases:<br />
<br />
$ mysqlcheck --all-databases -u root -p -o<br />
<br />
== Backup ==<br />
<br />
There are various [https://mariadb.com/kb/en/mariadb/documentation/backing-up-and-restoring/ tools and strategies] to back up your databases.<br />
<br />
If you are using the default InnoDB storage engine, a [https://mariadb.com/kb/en/mariadb/documentation/clients-and-utilities/backup-restore-and-import/mysqldump/#examples suggested] way of backing up all your bases online while provisioning for [https://dev.mysql.com/doc/refman/5.6/en/point-in-time-recovery.html point-in-time recovery] (also known as “roll-forward,” when you need to restore an old backup and replay the changes that happened since that backup) is to execute the following command:<br />
<br />
$ mysqldump --single-transaction --flush-logs --master-data=2 --all-databases -u root -p > all_databases.sql<br />
<br />
This will prompt for '''MariaDB's''' root user's password, which was defined during database [[#Configuration]].<br />
<br />
Specifying the password on the command line is [https://dev.mysql.com/doc/refman/5.6/en/password-security-user.html strongly discouraged], as it exposes it to discovery by other users through the use of {{ic|ps aux}} or other techniques. Instead, the aforementioned command will prompt for the specified user's password, concealing it away.<br />
<br />
=== Compression ===<br />
<br />
As SQL tables can get pretty large, it is recommended to pipe the output of the aforementioned command in a compression utility like {{Pkg|gzip}}:<br />
<br />
$ mysqldump --single-transaction --flush-logs --master-data=2 --all-databases -u root -p | gzip > all_databases.sql.gz<br />
<br />
Decompressing the backup thus created and reloading it in the server is achieved by doing:<br />
<br />
$ zcat all_databases.sql.gz | mysql -u root -p<br />
<br />
This will recreate and repopulate all the databases previously backed up (see [https://stackoverflow.com/questions/23180963/restore-all-mysql-database-from-a-all-database-sql-gz-file#comment35453351_23180977 this] or [http://www.linuxquestions.org/questions/linux-server-73/how-to-restore-mysqldump-all-databases-backup-892922/ this]).<br />
<br />
=== Non-interactive ===<br />
<br />
If you want to setup non-interactive backup script for use in [[cron]] jobs or [[Systemd/cron_functionality|systemd timers]], see [https://dev.mysql.com/doc/refman/5.6/en/option-files.html option files] and [https://stackoverflow.com/a/9293090 this illustration] for ''mysqldump''.<br />
<br />
Basically you should add the following section to the relevant [[#Configuration_files|configuration file]]:<br />
<br />
{{bc|1=<br />
[mysqldump]<br />
user=mysqluser<br />
password=secret<br />
}}<br />
<br />
Mentioning a user here is optional, but doing so will free you from having to mention it on the command line. If you want to set this for all tools, including {{ic|mysql}}, use the {{ic|[client]}} group.<br />
<br />
==== Example script ====<br />
<br />
The database can be dumped to a file for easy backup. The following shell script will do this for you, creating a {{ic|db_backup.gz}} file in the same directory as the script, containing your database dump:<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
THISDIR=$(dirname $(readlink -f "$0"))<br />
<br />
mysqldump --single-transaction --flush-logs --master-data=2 --all-databases \<br />
| gzip > $THISDIR/db_backup.gz<br />
echo 'purge master logs before date_sub(now(), interval 7 day);' | mysql<br />
</nowiki>}}<br />
<br />
See also the official {{ic|mysqldump}} page in the [http://dev.mysql.com/doc/refman/5.6/en/mysqldump.html MySQL] and [https://mariadb.com/kb/en/mariadb/documentation/clients-and-utilities/backup-restore-and-import/mysqldump MariaDB] manuals.<br />
<br />
=== Holland Backup ===<br />
<br />
A python-based software package named [http://hollandbackup.org/ Holland Backup] is available in [[AUR]] to automate all of the backup work. It supports direct mysqldump, LVM snapshots to tar files (mysqllvm), LVM snapshots with mysqldump (mysqldump-lvm), and {{pkg|xtrabackup}} methods to extract the data. The Holland framework supports a multitude of options and is highly configurable to address almost any backup situation.<br />
<br />
The main {{AUR|holland}} and {{AUR|holland-common}} packages provide the core framework; one of the sub-packages ({{AUR|holland-mysqldump}}, {{AUR|holland-mysqllvm}} and/or {{AUR|holland-xtrabackup}} must be installed for full operation. Example configurations for each method are in the {{ic|/usr/share/doc/holland/examples/}} directory and can be copied to {{ic|/etc/holland/backupsets/}}, as well as using the {{ic|holland mk-config}} command to generate a base config for a named provider.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Unable to run mysql_upgrade because MySQL cannot start ===<br />
<br />
Try run MySQL in safemode:<br />
<br />
# mysqld_safe --datadir=/var/lib/mysql/<br />
<br />
And then run:<br />
<br />
# mysql_upgrade -u root -p<br />
<br />
=== Reset the root password ===<br />
<br />
Stop {{ic|mariadb.service}}. Issue the following command:<br />
<br />
# mysqld_safe --skip-grant-tables &<br />
<br />
Connect to the mysql server. Issue the following command:<br />
<br />
# mysql<br />
<br />
Change root password:<br />
<br />
mysql> use mysql;<br />
mysql> FLUSH PRIVILEGES;<br />
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('MyNewPass');<br />
mysql> exit<br />
<br />
Then kill currently running mysql server:<br />
<br />
# killall -9 mysqld<br />
<br />
And finally start {{ic|mariadb.service}}:<br />
<br />
Start {{ic|mariadb.service}}.<br />
<br />
=== Check and repair all tables ===<br />
<br />
Check and auto repair all tables in all databases, [http://dev.mysql.com/doc/refman/5.7/en/mysqlcheck.html see more]:<br />
<br />
# mysqlcheck -A --auto-repair -u root -p<br />
<br />
=== Optimize all tables ===<br />
<br />
Forcefully optimize all tables, automatically fixing table errors that may come up.<br />
<br />
# mysqlcheck -A --auto-repair -f -o -u root -p<br />
<br />
=== OS error 22 when running on ZFS ===<br />
<br />
If using MySQL databases on [[ZFS]], the error '''InnoDB: Operating system error number 22 in a file operation''' may occur.<br />
<br />
A workaround is to disable ''aio_writes'' in {{ic|/etc/mysql/my.cnf}}:<br />
<br />
{{hc|/etc/mysql/my.cnf|2=<br />
[mysqld]<br />
innodb_use_native_aio = 0}}<br />
<br />
=== Cannot login through CLI, but phpmyadmin works well ===<br />
<br />
This may happen if you are using a long (>70-75) password. As for 5.5.36, for some reason, mysql CLI cannot handle that much characters in readline mode. So, if you are planning to use the recommended password input mode:<br />
<br />
$ mysql -u <user> -p<br />
Password:<br />
<br />
Consider changing the password to smaller one.<br />
<br />
{{Note|You still can log in by specifying the password as an argument to mysql command.<br />
<br />
{{Warning|This behavior is considered dangerous, because your password might leak, for example, to the logs. Use it only in case of emergency and do not forget to change password right afterwards.}}<br />
<br />
$ mysql -u <user> -p"<some-very-strong-password>"<br />
<br />
}}<br />
<br />
=== MySQL binary logs are taking up huge disk space ===<br />
<br />
By default, mysqld creates binary log files in {{ic|/var/lib/mysql}}. This is useful for replication master server or data recovery. But these binary logs can eat up your disk space. If you do not plan to use replication or data recovery features, you may disable binary logging by commenting out these lines in {{ic|/etc/mysql/my.cnf}}:<br />
<br />
#log-bin=mysql-bin<br />
#binlog_format=mixed<br />
<br />
Or you could limit the size of the logfile like this:<br />
<br />
expire_logs_days = 10<br />
max_binlog_size = 100M<br />
<br />
Alternatively, you can purge some binary logs in {{ic|/var/lib/mysql}} to free up disk space with this command:<br />
<br />
# mysql -u root -p"PASSWORD" -e "PURGE BINARY LOGS TO 'mysql-bin.0000xx';"<br />
<br />
{{Warning|This may decrease the chances of successful data recovery when trying to repair database tables (i.e. on database corruption).}}<br />
<br />
=== OpenRC fails to start MySQL ===<br />
<br />
To use MySQL with [[OpenRC]] you need to add the following lines to the {{ic|[mysqld]}} section in the MySQL config file, located at {{ic|/etc/mysql/my.cnf}}.<br />
<br />
user = mysql<br />
basedir = /usr<br />
datadir = /var/lib/mysql<br />
pid-file = /run/mysqld/mysql.pid<br />
<br />
You should now be able to start MySQL using:<br />
<br />
# rc-service mysql start<br />
<br />
=== Specified key was too long ===<br />
<br />
See [[#Increase character limit]].<br />
<br />
=== Changed limits warning on max_open_files/table_open_cache ===<br />
<br />
Increase the number of file descriptors by creating a [[Systemd#Drop-in_files|systemd drop-in]], e.g.:<br />
<br />
{{hc|/etc/systemd/system/mysqld.service.d/limit_nofile.conf|2=<br />
[Service]<br />
LimitNOFILE=8192<br />
}}<br />
<br />
== See also ==<br />
<br />
* [https://mariadb.com/ MariaDB Official Website]<br />
* [https://mariadb.com/kb/en/ MariaDB knowledge Base]<br />
* [https://www.askapache.com/mysql/performance-tuning-mysql/ MySQL Performance Tuning Scripts and Know-How]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Sway&diff=588982Sway2019-11-16T04:34:37Z<p>Hexhu: Use consistent spelling for XWayland</p>
<hr />
<div>[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
== Starting ==<br />
<br />
{{Tip|See [[Wayland#GUI libraries]] for appropriate environment variables to set for window decoration libraries.}}<br />
<br />
=== From a TTY ===<br />
<br />
To start Sway, simply type ''sway'' from a TTY.<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, then copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file to {{ic|~/.config/sway/config}}. It is located at {{ic|/etc/sway/config}}, unless the {{ic|DFALLBACK_CONFIG_DIR}} flag has been set. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_layout "us,de,ru"<br />
input * xkb_variant "colemak,,typewriter"<br />
input * xkb_options "grp:win_space_toggle"<br />
input "MANUFACTURER1 Keyboard" xkb_model "pc101"<br />
input "MANUFACTURER2 Keyboard" xkb_model "jp106"<br />
</nowiki>}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting sway.<br />
<br />
=== Statusbar ===<br />
<br />
Installing the program {{Pkg|i3status}} is an easy way to get a practical, default statusline. All one has to do is add following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
bar {<br />
status_command i3status<br />
}<br />
</nowiki>}}<br />
<br />
If you want to achieve colored output of i3status, you can adjust following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|<nowiki><br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
</nowiki>}}<br />
<br />
In both examples, the system-wide installed configuration files has been copied over to the user directory and then modified. <br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
output "*" bg /home/onny/pictures/fredwang_norway.jpg fill<br />
</nowiki>}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
=== Input devices ===<br />
<br />
Its possible to tweak specific input device configurations. For example to enable tap-to-click and natural scolling for a touchpad, add an input block:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
input "2:14:ETPS/2_Elantech_Touchpad" {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
</nowiki>}}<br />
<br />
Where as the device identifier can be queried with:<br />
<br />
$ swaymsg -t get_inputs<br />
<br />
The output from the command, sometimes has a "\" to escape symbols like "/" (ie {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control your volume, your monitor brightness or your media player:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
</nowiki>}}<br />
<br />
To control brightness you can use {{Pkg|brightnessctl}} or {{Pkg|light}}. For a list of utilities to control brightness and color correction see [[Backlight]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== Run programs natively under Wayland (without XWayland support) ===<br />
<br />
{{Accuracy|{{ic|xwayland disable}} is not necessary to run programs natively under Wayland, configuring the [[Wayland#GUI libraries|GUI libraries]] appropriately is enough. Keeping XWayland enabled is good for programs that don't work otherwise.}}<br />
<br />
First, be sure the toolkit or library of every program that is and will be installed [[Wayland#GUI_libraries|support Wayland]]. Then append the following line to your sway configuration file to disable XWayland support:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
xwayland disable<br />
</nowiki>}}<br />
<br />
{{ Note| Some programs, like [[Firefox#Wayland|Firefox]], [[#Application launchers|bemenu]] or [[Wayland#Qt_5|Qt5]] based programs, also need specific environment variables set for them to run natively under Wayland. }}<br />
{{ Note| In a fresh Sway install, you need to change the default menu and terminal applications because they depend on XWayland. }}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Autostart on login ===<br />
<br />
To start sway from tty1 on login with default US keyboard, edit:<br />
<br />
{{hc|~/.bash_profile|<br />
<nowiki>if [[ -z $DISPLAY ]] && [[ $(tty) = /dev/tty1 ]]; then<br />
XKB_DEFAULT_LAYOUT=us exec sway<br />
fi</nowiki><br />
}}<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture ===<br />
<br />
Capturing the screen can be done using {{Pkg|grim}} or {{AUR|swayshot}} for screenshots and {{AUR|wf-recorder-git}} for video. Optionally, {{Pkg|slurp}} can be used to select the part of the screen to capture.<br />
<br />
Take a screenshot of the whole screen:<br />
<br />
$ grim screenshot.png<br />
<br />
Take a screenshot of a part of the screen:<br />
<br />
$ grim -g "$(slurp)" screenshot.png<br />
<br />
Capture a video of the whole screen:<br />
<br />
$ wf-recorder -o recording.mp4<br />
<br />
Capture a video of a part of the screen:<br />
<br />
$ wf-recorder -g "$(slurp)"<br />
<br />
Example of usage with {{Pkg|grim}}, {{Pkg|slurp}} and {{Pkg|wl-clipboard}}, screenshot directly with Print button to clipboard. <br />
{{hc|~/.config/sway/config|<br />
<nowiki>bindsym --release Print exec grim -g \"$(slurp)" - | wl-copy</nowiki><br />
}}<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change [[cursor themes |cursor theme]] and size for XWayland apps ===<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme $my_cursor_theme $my_cursor_size<br />
}}<br />
<br />
Where {{ic|$my_cursor_theme}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|$my_cursor_size}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the XWayland application to see the changes.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
=== VirtualBox ===<br />
<br />
Sway doesn't work well (or at all) under [[VirtualBox]].<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://git.sr.ht/~sircmpwn/sway sr.ht git page]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Hexhuhttps://wiki.archlinux.org/index.php?title=Sway&diff=588981Sway2019-11-16T04:33:04Z<p>Hexhu: Add tips for changing cursor size for XWayland apps such as Chromium.</p>
<hr />
<div>[[Category:Tiling WMs]]<br />
[[Category:Dynamic WMs]]<br />
[[ja:Sway]]<br />
[[pt:Sway]]<br />
''sway'' is a compositor for [[Wayland]] designed to be fully compatible with [[i3]]. According to [https://swaywm.org the official website]:<br />
:Sway is a tiling Wayland compositor and a drop-in replacement for the i3 window manager for X11. It works with your existing i3 configuration and supports most of i3's features, plus a few extras.<br />
<br />
== Installation ==<br />
<br />
''sway'' can be [[install]]ed with the {{Pkg|sway}} package. The development version can be installed using {{AUR|wlroots-git}} and {{AUR|sway-git}}. It's advisable to always update ''wlroots'' when you update ''sway'', due to tight dependencies.<br />
<br />
You may also install {{Pkg|swaylock}} and {{Pkg|swayidle}} to lock your screen and set up an idle manager.<br />
<br />
== Starting ==<br />
<br />
{{Tip|See [[Wayland#GUI libraries]] for appropriate environment variables to set for window decoration libraries.}}<br />
<br />
=== From a TTY ===<br />
<br />
To start Sway, simply type ''sway'' from a TTY.<br />
<br />
=== From a display manager ===<br />
<br />
{{Note|Sway does not support display managers officially.[https://github.com/swaywm/sway/pull/3634#issuecomment-462779163]}}<br />
<br />
The sway session is located at {{ic|/usr/share/wayland-sessions/sway.desktop}}. It is automatically recognized by modern display managers like [[GDM]] and [[SDDM]].<br />
<br />
It is also possible to start sway as a [https://github.com/swaywm/sway/wiki/Systemd-integration#running-sway-itself-as-a---user-service systemd user service] through the display manager.<br />
<br />
Also you can use text-based session manager, see [[Display manager#Console]].<br />
<br />
== Configuration ==<br />
<br />
If you already use i3, then copy your i3 configuration to {{ic|~/.config/sway/config}} and it should work out of the box. Otherwise, copy the sample configuration file to {{ic|~/.config/sway/config}}. It is located at {{ic|/etc/sway/config}}, unless the {{ic|DFALLBACK_CONFIG_DIR}} flag has been set. See {{man|5|sway}} for information on the configuration.<br />
<br />
=== Keymap ===<br />
<br />
By default, sway starts with the US QWERTY keymap. To configure per-input:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
input * xkb_layout "us,de,ru"<br />
input * xkb_variant "colemak,,typewriter"<br />
input * xkb_options "grp:win_space_toggle"<br />
input "MANUFACTURER1 Keyboard" xkb_model "pc101"<br />
input "MANUFACTURER2 Keyboard" xkb_model "jp106"<br />
</nowiki>}}<br />
<br />
More details are available in {{man|7|xkeyboard-config}} and {{man|5|sway-input}}.<br />
<br />
The keymap can also be configured using environment variables ({{ic|XKB_DEFAULT_LAYOUT}}, {{ic|XKB_DEFAULT_VARIANT}}, etc.) when starting sway.<br />
<br />
=== Statusbar ===<br />
<br />
Installing the program {{Pkg|i3status}} is an easy way to get a practical, default statusline. All one has to do is add following snippet at the end of your sway config:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
bar {<br />
status_command i3status<br />
}<br />
</nowiki>}}<br />
<br />
If you want to achieve colored output of i3status, you can adjust following part in the i3status configuration:<br />
<br />
{{hc|~/.config/i3status/config|<nowiki><br />
general {<br />
colors = true<br />
interval = 5<br />
}<br />
</nowiki>}}<br />
<br />
In both examples, the system-wide installed configuration files has been copied over to the user directory and then modified. <br />
<br />
{{Tip|{{Pkg|waybar}} is an alternative to the bar included with sway (swaybar).}}<br />
<br />
=== Wallpaper ===<br />
<br />
Since release 1.1.1 the wallpaper part of the SwayWM project was moved to {{Pkg|swaybg}}, which is needed in order to run the output command.<br />
<br />
This line, which can be appended at the end of your sway configuration, sets a background image on all displays (output matches all with name {{ic|"*"}}):<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
output "*" bg /home/onny/pictures/fredwang_norway.jpg fill<br />
</nowiki>}}<br />
<br />
Of course you have to replace the file name and path according to your wallpaper.<br />
<br />
=== Input devices ===<br />
<br />
Its possible to tweak specific input device configurations. For example to enable tap-to-click and natural scolling for a touchpad, add an input block:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
input "2:14:ETPS/2_Elantech_Touchpad" {<br />
tap enabled<br />
natural_scroll enabled<br />
}<br />
</nowiki>}}<br />
<br />
Where as the device identifier can be queried with:<br />
<br />
$ swaymsg -t get_inputs<br />
<br />
The output from the command, sometimes has a "\" to escape symbols like "/" (ie {{ic|"2:14:ETPS\/2_Elantech_Touchpad"}}) and it needs to be removed.<br />
<br />
More documentation and options like acceleration profiles can be found in {{man|5|sway-input}}.<br />
<br />
=== HiDPI ===<br />
<br />
Set your displays scale factor with the {{ic|output}} command in your config file. The scale factor can be fractional, but it is usually 2 for HiDPI screens.<br />
<br />
output <name> scale <factor><br />
<br />
You can find your display name with the following command:<br />
<br />
$ swaymsg -t get_outputs<br />
<br />
=== Custom keybindings ===<br />
<br />
[[Extra keyboard keys|Special keys]] on your keyboard can be used to execute commands, for example to control your volume, your monitor brightness or your media player:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%<br />
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%<br />
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle<br />
bindsym XF86AudioMicMute exec pactl set-source-mute @DEFAULT_SOURCE@ toggle<br />
bindsym XF86MonBrightnessDown exec brightnessctl set 5%-<br />
bindsym XF86MonBrightnessUp exec brightnessctl set +5%<br />
bindsym XF86AudioPlay exec playerctl play-pause<br />
bindsym XF86AudioNext exec playerctl next<br />
bindsym XF86AudioPrev exec playerctl previous<br />
</nowiki>}}<br />
<br />
To control brightness you can use {{Pkg|brightnessctl}} or {{Pkg|light}}. For a list of utilities to control brightness and color correction see [[Backlight]].<br />
<br />
=== Xresources ===<br />
<br />
Copy {{ic|~/.Xresources}} to {{ic|~/.Xdefaults}} to use them in Sway.<br />
<br />
=== Run programs natively under Wayland (without Xwayland support) ===<br />
<br />
{{Accuracy|{{ic|xwayland disable}} is not necessary to run programs natively under Wayland, configuring the [[Wayland#GUI libraries|GUI libraries]] appropriately is enough. Keeping XWayland enabled is good for programs that don't work otherwise.}}<br />
<br />
First, be sure the toolkit or library of every program that is and will be installed [[Wayland#GUI_libraries|support Wayland]]. Then append the following line to your sway configuration file to disable Xwayland support:<br />
<br />
{{hc|~/.config/sway/config|<nowiki><br />
xwayland disable<br />
</nowiki>}}<br />
<br />
{{ Note| Some programs, like [[Firefox#Wayland|Firefox]], [[#Application launchers|bemenu]] or [[Wayland#Qt_5|Qt5]] based programs, also need specific environment variables set for them to run natively under Wayland. }}<br />
{{ Note| In a fresh Sway install, you need to change the default menu and terminal applications because they depend on Xwayland. }}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Autostart on login ===<br />
<br />
To start sway from tty1 on login with default US keyboard, edit:<br />
<br />
{{hc|~/.bash_profile|<br />
<nowiki>if [[ -z $DISPLAY ]] && [[ $(tty) = /dev/tty1 ]]; then<br />
XKB_DEFAULT_LAYOUT=us exec sway<br />
fi</nowiki><br />
}}<br />
<br />
=== Backlight toggle ===<br />
<br />
To turn off (and on) your displays with a key (e.g. {{ic|Pause}}) bind the following script in your Sway {{ic|config}}:<br />
<br />
{{bc|<br />
#!/bin/sh<br />
read lcd < /tmp/lcd<br />
if [ "$lcd" -eq "0" ]; then<br />
swaymsg "output * dpms on"<br />
echo 1 > /tmp/lcd<br />
else<br />
swaymsg "output * dpms off"<br />
echo 0 > /tmp/lcd<br />
fi<br />
}}<br />
<br />
=== Screen capture ===<br />
<br />
Capturing the screen can be done using {{Pkg|grim}} or {{AUR|swayshot}} for screenshots and {{AUR|wf-recorder-git}} for video. Optionally, {{Pkg|slurp}} can be used to select the part of the screen to capture.<br />
<br />
Take a screenshot of the whole screen:<br />
<br />
$ grim screenshot.png<br />
<br />
Take a screenshot of a part of the screen:<br />
<br />
$ grim -g "$(slurp)" screenshot.png<br />
<br />
Capture a video of the whole screen:<br />
<br />
$ wf-recorder -o recording.mp4<br />
<br />
Capture a video of a part of the screen:<br />
<br />
$ wf-recorder -g "$(slurp)"<br />
<br />
Example of usage with {{Pkg|grim}}, {{Pkg|slurp}} and {{Pkg|wl-clipboard}}, screenshot directly with Print button to clipboard. <br />
{{hc|~/.config/sway/config|<br />
<nowiki>bindsym --release Print exec grim -g \"$(slurp)" - | wl-copy</nowiki><br />
}}<br />
<br />
=== Control swaynag with the keyboard ===<br />
<br />
Swaynag, the default warning/prompt program shipped with sway, only supports user interaction with the mouse. A helper program such as {{AUR|swaynagmode}} may be used to enable interaction via keyboard shortcuts.<br />
<br />
Swaynagmode works by first launching swaynag, then listening for signals which trigger actions such as selecting the next button, dismissing the prompt, or accepting the selected button. These signals are sent by launching another instance of the swaynagmode script itself with a control argument, such as {{ic|swaynagmode --select right}} or {{ic|swaynagmode --confirm}}. <br />
<br />
Swaynagmode by default triggers the sway mode {{ic|nag}} upon initialization, followed by {{ic|default}} on exit. This makes it easy to define keybindings in your sway configuration:<br />
<br />
{{hc|~/.config/sway/config|<br />
set $nag exec swaynagmode<br />
mode "nag" {<br />
bindsym {<br />
Ctrl+d mode "default"<br />
<br />
Ctrl+c $nag --exit<br />
q $nag --exit<br />
Escape $nag --exit<br />
<br />
Return $nag --confirm<br />
<br />
Tab $nag --select prev<br />
Shift+Tab $nag --select next<br />
<br />
Left $nag --select next<br />
Right $nag --select prev<br />
<br />
Up $nag --select next<br />
Down $nag --select prev<br />
}<br />
}<br />
}}<br />
<br />
Note that, beginning in sway version 1.2, mode names are case-sensitive.<br />
<br />
You can configure sway to use swaynagmode with the configuration command {{ic|swaynag_command swaynagmode}}.<br />
<br />
=== Change [[cursor themes |cursor theme]] and size for XWayland apps ===<br />
<br />
{{hc|~/.config/sway/config|<br />
seat seat0 xcursor_theme $my_cursor_theme $my_cursor_size<br />
}}<br />
<br />
Where {{ic|$my_cursor_theme}} can be set to or replaced by a specific value like {{ic|default}}, {{ic|Adwaita}} or {{ic|Simple-and-Soft}}, and {{ic|$my_cursor_size}} a value like {{ic|48}}.<br />
<br />
You can inspect their values with {{ic|echo $XCURSOR_SIZE}} and {{ic|echo $XCURSOR_THEME}}.<br />
<br />
Note that you need to restart the XWayland application to see the changes.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Application launchers ===<br />
<br />
i3-dmenu-desktop, {{Pkg|dmenu}}, and {{Pkg|rofi}} all function relatively well in Sway, but all run under XWayland and suffer from the same issue where they can become unresponsive if the cursor is moved to a native Wayland window. The reason for this issue is that Wayland clients/windows do not have access to input devices unless they have focus of the screen. The XWayland server is itself a client to the Wayland compositor, so one of its XWayland clients must have focus for it to access user input. However, once one of its clients has focus, it can gather input and make it available to all XWayland clients through the X11 protocol. Hence, moving the cursor to an XWayland window and pressing Escape should fix the issue, and sometimes running {{ic|pkill}} does too.<br />
<br />
{{Pkg|bemenu}} is a native Wayland dmenu replacement which can optionally be combined with {{AUR|j4-dmenu-desktop}} to provide a Wayland-native combination for launching desktop files (as i3-dmenu-desktop does):<br />
<br />
j4-dmenu-desktop --dmenu='bemenu -i --nb "#3f3f3f" --nf "#dcdccc" --fn "pango:DejaVu Sans Mono 12"' --term='termite'<br />
<br />
You may need to set {{ic|BEMENU_BACKEND}} environment variable to "wayland" if you choose not to disable XWayland.<br />
<br />
You can also build your own with a floating terminal and fzf as discussed in a [https://github.com/swaywm/sway/issues/1367 GitHub issue].<br />
<br />
=== VirtualBox ===<br />
<br />
Sway doesn't work well (or at all) under [[VirtualBox]].<br />
<br />
=== Sway socket not detected ===<br />
<br />
Using a {{ic|swaymsg}} argument, such as {{ic|swaymsg -t get_outputs}}, will sometimes return the message:<br />
<br />
sway socket not detected.<br />
ERROR: Unable to connect to<br />
<br />
when run inside a terminal multiplexer (such as gnu screen or tmux). This means {{ic|swaymsg}} could not connect to the socket provided in your {{ic|SWAYSOCK}}.<br />
<br />
To view what the current value of {{ic|SWAYSOCK}} is, type:<br />
<br />
$ env | fgrep SWAYSOCK<br />
SWAYSOCK=/run/user/1000/sway-ipc.1000.4981.sock<br />
<br />
To work around this problem, you may try attaching to a socket based on the running sway process:<br />
<br />
$ export SWAYSOCK=/run/user/$(id -u)/sway-ipc.$(id -u).$(pgrep -x sway).sock<br />
<br />
To avoid this error, run the command outside of a multiplexer.<br />
<br />
=== Unable to retrieve socket path ===<br />
<br />
Requesting messages from {{ic|swaymsg -t}} on a tty may return the following message:<br />
<br />
Unable to retrieve socket path<br />
<br />
{{ic|SWAYSOCK}} environment variable is set after launching Sway, therefore a workaround to this error is to request {{ic|swaymsg -t [message]}} in a terminal inside Sway.<br />
<br />
=== Keybindings and keyboard layouts ===<br />
<br />
By default, if you are using more than one keyboard layout, e.g. {{ic|<nowiki>input * xkb_layout "us,ru"</nowiki>}}, bindings may become broken when you switch on some secondary layout.<br />
<br />
Thanks to https://github.com/swaywm/sway/pull/3058, all you need is to add {{ic|--to-code}} key to sensitive {{ic|bindsym}} lines like this:<br />
{{bc|<nowiki><br />
bindsym --to-code {<br />
$mod+$left focus left<br />
$mod+$down focus down<br />
$mod+$up focus up<br />
$mod+$right focus right<br />
}</nowiki><br />
}}<br />
<br />
=== Java applications ===<br />
<br />
Some Java-based applications will display blank screen when opened, for example any Intellij editor. To mitigate this, the application can be started with the {{ic|_JAVA_AWT_WM_NONREPARENTING}} environment variable set to 1.<br />
<br />
If you start the application from a launcher like {{Pkg|rofi}} or {{Pkg|dmenu}}, you might want to modify the application desktop entry as shown in [[Desktop entries#Modify environment variables]].<br />
<br />
== See also ==<br />
<br />
* [https://github.com/swaywm/sway GitHub project]<br />
* [https://github.com/swaywm/sway/wiki Sway official wiki]<br />
* [https://git.sr.ht/~sircmpwn/sway sr.ht git page]<br />
* [https://swaywm.org Website]<br />
* [https://drewdevault.com/2019/03/11/Sway-1.0-released.html Announcing the release of sway 1.0]</div>Hexhu