https://wiki.archlinux.org/api.php?action=feedcontributions&user=Progandy&feedformat=atomArchWiki - User contributions [en]2024-03-29T12:32:59ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Unofficial_user_repositories&diff=801504Unofficial user repositories2024-02-28T14:20:56Z<p>Progandy: /* miffe */ add link to AUR profile as data point for key verification</p>
<hr />
<div>[[Category:Package management]]<br />
[[Category:Lists]]<br />
[[es:Unofficial user repositories]]<br />
[[ja:非公式ユーザーリポジトリ]]<br />
[[zh-hans:Unofficial user repositories]]<br />
{{Related articles start}}<br />
{{Related|pacman-key}}<br />
{{Related|Official repositories}}<br />
{{Related articles end}}<br />
<br />
This article lists binary repositories freely created and shared by the community, often providing pre-built versions of PKGBUILDS found in the [[AUR]].<br />
<br />
In order to use these repositories, add them to {{ic|/etc/pacman.conf}}, as explained in [[pacman#Repositories and mirrors]]. If a repository is signed, you must obtain and locally sign the associated key, as explained in [[pacman/Package signing#Adding unofficial keys]].<br />
<br />
If you want to create your own custom repository, follow [[pacman/Tips and tricks#Custom local repository]].<br />
<br />
{{Warning|The official Arch Linux Developers and the Trusted Users do not perform tests of any sort to verify the contents of these repositories. It is your decision whether to trust their maintainers, and you take full responsibility for any consequences of using any unofficial repository.}}<br />
<br />
== Adding your repository to this page ==<br />
<br />
If you have your own repository, please add it to this page so that all the other users will know where to find your packages. Please keep the following rules when adding new repositories:<br />
<br />
* Keep the lists in alphabetical order.<br />
* Include some information about the maintainer: include at least a (nick)name and some form of contact information (website, email address, user page on ArchWiki or the forums, etc.).<br />
* If the repository is of the ''signed'' variety, please include a key-id, possibly using it as the anchor for a link to its keyserver; if the key is not on a keyserver, include a link to the key file.<br />
* Include some short description (e.g., the category of packages provided in the repository).<br />
* If there is a page (either on ArchWiki or external) containing more information about the repository, include a link to it.<br />
* If possible, avoid using comments in code blocks. The formatted description is much more readable. Users who want some comments in their {{ic|pacman.conf}} can easily create it on their own.<br />
<br />
Some repositories may also have packages for architectures besides x86_64. The {{ic|$arch}} variable will be set automatically by pacman.<br />
<br />
== Signed ==<br />
<br />
=== ada ===<br />
<br />
* '''Maintainer:''' Rod Kay <rodakay5 at gmail dot com><br />
* '''Description:''' Arch Ada Repository ~ all packages relating to the [[Ada]] and SPARK programming languages.<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?op=vindex&fingerprint=on&exact=on&search=0xED55AF75B0330A2A3BAA9986B6120CD888A0DFD2 0xED55AF75B0330A2A3BAA9986B6120CD888A0DFD2]<br />
<br />
{{bc|<nowiki><br />
[ada]<br />
Server = http://www.orthanc.site:8080/assets/arch_ada_repo<br />
</nowiki>}}<br />
<br />
=== alerque ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/alerque Caleb Maclennan]<br />
* '''Description:''' Typesetting, publishing, and font development related tools such as SILE, CaSILE, Fontship, and their related dependencies including many fonts, Lua rocks, and Python modules. Also Asterisk, most of the [https://aur.archlinux.org/packages/?O=0&SeB=M&K=alerque&outdated=&SB=n&SO=a&PP=250&do_Search=Go AUR packages I (co-)maintain], and many of the AUR builds I use personally.<br />
* '''Git Repository:''' https://github.com/alerque/aur<br />
* '''Issue Tracker:''' https://github.com/alerque/aur/issues<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?op=vindex&fingerprint=on&exact=on&search=0x9F377DDB6D3153A48EB3EB1E63CC496475267693 63CC496475267693]<br />
<br />
{{bc|<nowiki><br />
[alerque]<br />
Server = https://arch.alerque.com/$arch<br />
</nowiki>}}<br />
<br />
=== ALHP ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/anonfunc Giovanni Harting]<br />
* '''Description:''' [[official repositories]] compiled with [[Wikipedia:Interprocedural_optimization|LTO]], -march=x86-64-vN and -O3.<br />
* '''Issue Tracker:''' https://somegit.dev/ALHP/ALHP.GO/issues<br />
* '''Keyring:''' {{AUR|alhp-keyring}}<br />
* '''Mirrorlist:''' {{AUR|alhp-mirrorlist}}<br />
* '''Upstream page:''' https://somegit.dev/ALHP/ALHP.GO<br />
* '''Debuginfod:''' https://debuginfod.alhp.dev<br />
<br />
{{bc|<nowiki><br />
[core-x86-64-v3]<br />
Include = /etc/pacman.d/alhp-mirrorlist<br />
<br />
[extra-x86-64-v3]<br />
Include = /etc/pacman.d/alhp-mirrorlist<br />
</nowiki>}}<br />
<br />
=== andontie-aur ===<br />
<br />
* '''Maintainer:''' Holly M.<br />
* '''Description:''' A repository containing the most popular AUR packages, as well as some I use all the time. New packages can be requested on the upstream website.<br />
* '''Key-ID:''' B545E9B7CD906FE3<br />
* '''Upstream page:''' https://aur.andontie.net<br />
<br />
{{bc|<nowiki><br />
[andontie-aur]<br />
Server = https://aur.andontie.net/$arch<br />
</nowiki>}}<br />
<br />
=== arcanisrepo ===<br />
<br />
* '''Maintainer:''' [https://arcanis.me/ arcanis]<br />
* '''Description:''' AUR packages (including some VCS packages), mostly development and scientific tools. Updated daily.<br />
* '''Key-ID:''' [https://pgp.mit.edu/pks/lookup?op=get&search=0xBD2AC8C5E989490C 0xBD2AC8C5E989490C]<br />
* '''Upstream page:''' https://repo.arcanis.me/arcanisrepo/x86_64/index.html<br />
<br />
{{bc|<nowiki><br />
[arcanisrepo]<br />
Server = https://repo.arcanis.me/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== arch4edu ===<br />
<br />
* '''Maintainers:''' [https://github.com/petronny Jingbei Li (petronny)], and [https://github.com/arch4edu/arch4edu/graphs/contributors others]<br />
* '''Description:''' arch4edu is a community repository for Arch Linux and Arch Linux ARM that strives to provide the latest versions of most software used by college students.<br />
* '''Git Repo:''' https://github.com/arch4edu/arch4edu<br />
* '''Issue tracking:''' https://github.com/arch4edu/arch4edu/issues for packaging issues, out-of-date notifications, package requests, and related questions<br />
* '''Mirrors:''' https://github.com/arch4edu/mirrorlist/blob/master/mirrorlist.arch4edu<br />
* '''Key-ID:''' 7931B6D628C8D3BA<br />
<br />
{{bc|<nowiki><br />
[arch4edu]<br />
Server = https://mirrors.tuna.tsinghua.edu.cn/arch4edu/$arch<br />
## or other mirrors in https://github.com/arch4edu/mirrorlist/blob/master/mirrorlist.arch4edu<br />
</nowiki>}}<br />
<br />
=== archlinuxcn ===<br />
<br />
* '''Maintainers:''' [https://blog.phoenixlzx.com/ phoenixlzx], [https://archlinux.org/people/developers/#felixonmars Felix Yan (felixonmars, dev)], [https://github.com/lilydjwg lilydjwg], [https://archlinux.org/people/trusted-users/#farseerfc farseerfc (TU)], and [https://github.com/archlinuxcn/repo/graphs/contributors others]<br />
* '''Description:''' Packages by the Chinese Arch Linux community, all signed. Be aware that non-x86_64 packages are not fully maintained and tested. Create an issue if you find some problems.<br />
* '''Git Repo:''' https://github.com/archlinuxcn/repo<br />
* '''Issue tracking:''' https://github.com/archlinuxcn/repo/issues for packaging issues, out-of-date notifications, package requests, and related questions<br />
* '''Mirrors:''' https://github.com/archlinuxcn/mirrorlist-repo (Mostly for users in mainland China), or install ''archlinuxcn-mirrorlist-git'' from the repository.<br />
* '''Key-ID:''' Once the repository is added, ''archlinuxcn-keyring'' package must be installed before any other, so you do not get errors about PGP signatures. ''archlinuxcn-keyring'' package itself is signed by TU.<br />
* '''Debuginfod:''' https://repo.archlinuxcn.org<br />
<br />
{{bc|<nowiki><br />
[archlinuxcn]<br />
Server = https://repo.archlinuxcn.org/$arch<br />
## or install archlinuxcn-mirrorlist-git and use the mirrorlist<br />
#Include = /etc/pacman.d/archlinuxcn-mirrorlist<br />
</nowiki>}}<br />
<br />
=== archzfs ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/minextu Jan Houben (minextu)]<br />
* '''Description:''' Packages for ZFS on Arch Linux.<br />
* '''Upstream page:''' https://github.com/archzfs/archzfs<br />
* '''Key-ID:''' [https://archzfs.com/archzfs.gpg DDF7DB817396A49B2A2723F7403BD972F75D9D76]<br />
<br />
{{bc|<nowiki><br />
[archzfs]<br />
# Origin Server - Finland<br />
Server = http://archzfs.com/$repo/$arch<br />
# Mirror - Germany<br />
Server = http://mirror.sum7.eu/archlinux/archzfs/$repo/$arch<br />
# Mirror - Germany<br />
Server = http://mirror.sunred.org/archzfs/$repo/$arch<br />
# Mirror - Germany<br />
Server = https://mirror.biocrafting.net/archlinux/archzfs/$repo/$arch<br />
# Mirror - India<br />
Server = https://mirror.in.themindsmaze.com/archzfs/$repo/$arch<br />
# Mirror - US<br />
Server = https://zxcvfdsa.com/archzfs/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== artafinde ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/developers/#artafinde Leonidas Spyropoulos]<br />
* '''Description:''' Personal repository with AUR and custom packages.<br />
* '''Key-ID:''' Not needed, as key is in archlinux keyring.<br />
<br />
{{bc|<nowiki><br />
[artafinde]<br />
Server = https://pkgbuild.com/~artafinde/repo<br />
</nowiki>}}<br />
<br />
=== avr ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/vianney Vianney Bouchaud]<br />
* '''Description:''' Some of the AUR builds I use personally, packages mainly related to kubernetes that I used to build for my own use as well as some of my own software that I also package.<br />
* '''Git Repository:''' https://github.com/vbouchaud/aur<br />
* '''Issue Tracker:''' https://github.com/vbouchaud/aur/issues<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?op=vindex&fingerprint=on&exact=on&search=0xAD53F33B1AB4C51802F25068157B08346330029C 157B08346330029C]<br />
* '''Upstream page:''' https://bouchaud.org/packages/avr<br />
<br />
{{bc|<nowiki><br />
[avr]<br />
Server = https://bouchaud.org/packages/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== bioarchlinux ===<br />
<br />
* '''Maintainer:''' BioArchLinux Team<br />
* '''Description:''' Biological Software Repository for Arch Linux<br />
* '''Upstream page:''' https://github.com/BioArchLinux/Packages<br />
* '''Key-ID:''' B1F96021DB62254D<br />
<br />
{{bc|<nowiki><br />
[bioarchlinux]<br />
Server = https://repo.bioarchlinux.org/$arch<br />
</nowiki>}}<br />
<br />
=== blackeagle-pre-community ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#idevolder Ike Devolder]<br />
* '''Description:''' testing of the by me maintained packages before moving to ''extra'' repository<br />
* '''Key-ID:''' Not required, as maintainer is a TU<br />
<br />
{{bc|<nowiki><br />
[blackeagle-pre-community]<br />
Server = https://repo.herecura.eu/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== build.kilabit.info ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/shulhan shulhan]<br />
* '''Package list:''' https://build.kilabit.info/karajo/app/<br />
* '''Key-ID:''' [https://keys.openpgp.org/vks/v1/by-fingerprint/CEF1AA87E337A6C390DE5550F8507EE9148A4CE3 4A5360B500C9C4F0]<br />
* '''Website:''' https://build.kilabit.info<br />
<br />
{{bc|<nowiki><br />
[build.kilabit.info]<br />
Server = https://build.kilabit.info/aur<br />
</nowiki>}}<br />
<br />
=== chaotic-aur ===<br />
<br />
* '''Maintainer:''' [https://github.com/dr460nf1r3 dr460nf1r3], [https://github.com/pedrohlc PedroHLC], [https://github.com/lordkitsuna LordKitsuna], [https://github.com/librewish Librewish]{{Dead link|2023|05|06|status=404}}, [https://github.com/SolarAquarion SolarAquarion], [https://github.com/thotypous thotypous] (former [[TU]]), and [https://github.com/RustemB RustemB] (in memoriam).<br />
* '''Description:''' Auto builds AUR packages the maintainers use, update them hourly (a few are updated daily). It has several mirrors worldwide. Its main builder is hosted at the Federal University of Sao Carlos, Brazil. It's x86_64 only.<br />
* '''Key-ID:''' [https://pgp.mit.edu/pks/lookup?search=0xFBA220DFC880C036&op=index FBA220DFC880C036], with some subkeys. To help, keyring and mirrorlist are available at the repository's homepage.<br />
* '''Note:''' See [https://aur.chaotic.cx repository's homepage].<br />
<br />
{{bc|<nowiki><br />
[chaotic-aur]<br />
Server = https://geo-mirror.chaotic.cx/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== coderkun-aur ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/coderkun/ coderkun]<br />
* '''Description:''' AUR packages with random software. Supporting package deltas and package and database signing.<br />
* '''Upstream page:''' https://www.suruatoel.xyz/arch<br />
* '''Key-ID:''' 39E27199A6BEE374<br />
* '''Keyfile:''' https://www.suruatoel.xyz/coderkun.key<br />
<br />
{{bc|<nowiki><br />
[coderkun-aur]<br />
Server = https://arch.suruatoel.xyz/$repo/$arch/<br />
</nowiki>}}<br />
<br />
=== condorcore ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/MrHacker/ MrHacker]<br />
* '''Description:''' Wazuh-SIEM packages that I co-maintain and AUR. signed from the database.<br />
* '''Upstream page:''' https://aur.condorbs.net<br />
* '''Key-ID:''' 3CA0B9DF1BE7CE09<br />
* '''Keyfile:'''[https://openpgpkey.condorbs.net/.well-known/openpgpkey/condorbs.net/hu/6xijodcce66ymrrur6yqqeohwhzwz97m GPG]<br />
<br />
{{Note|Repository has its own additional keyring at https://aur.centauricorex.net/x86_64/condorcore-keyring-20231117-1-any.pkg.tar.zst}}<br />
<br />
{{bc|<nowiki><br />
[condorcore]<br />
Server = https://aur.centauricorex.net/$arch<br />
</nowiki>}}<br />
<br />
=== copypaste ===<br />
<br />
* '''Maintainer:''' [https://copypaste.wtf Fredrick R. Brennan <copypaste@kittens.ph>]<br />
* '''Description:''' AUR packages with random software. {{aur|blender-git}} and fonts related stuff mostly.<br />
* '''Upstream page:''' http://aur.copypaste.wtf/<br />
* '''Key-ID:''' 98F28F767470129FBE3B054CE2154DD1A1C77B8B<br />
* '''Keyfile:''' http://aur.copypaste.wtf/copypaste.pub.key.asc<br />
<br />
{{bc|<nowiki><br />
[copypaste]<br />
Server = http://aur.copypaste.wtf/<br />
</nowiki>}}<br />
<br />
=== desolve ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/dviktor/ desolve]<br />
* '''Description:''' Collection of R packages plus some extra stuff.<br />
* '''Git repository for R packages:''' https://github.com/dvdesolve/ArchRPkgs<br />
* '''Git repository for other AUR packages:''' https://github.com/dvdesolve/pkgbuilds<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xdd3bf75dcd96541ac723b7cd6a4cd3276ca8ebbd DD3BF75DCD96541AC723B7CD6A4CD3276CA8EBBD]<br />
<br />
{{bc|<nowiki><br />
[desolve]<br />
Server = https://desolve.ru/archrepo/$arch<br />
</nowiki>}}<br />
<br />
=== devkitpro ===<br />
<br />
* '''Maintainer:''' [https://devkitpro.org/ wintermute]<br />
* '''Description:''' Provides Homebrew toolchains for the Nintendo Wii, Gamecube, DS, GBA, Gamepark gp32, and Nintendo Switch<br />
* '''Upstream page:''' https://devkitpro.org/wiki/devkitPro_pacman<br />
* '''Key-ID:''' F7FD5492264BB9D0<br />
<br />
{{Note|Repository has its own additional keyring at https://pkg.devkitpro.org/devkitpro-keyring.pkg.tar.xz}}<br />
<br />
{{bc|<nowiki><br />
[dkp-libs]<br />
Server = https://downloads.devkitpro.org/packages<br />
<br />
[dkp-linux]<br />
Server = https://downloads.devkitpro.org/packages/linux/$arch/<br />
</nowiki>}}<br />
<br />
=== doom2df-repo ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/TerminalHash Dmitry Lyashuk]<br />
* '''Description:''' Pre-built packages for game Doom 2D: Forever, a modern port of Doom 2D by Prikol Software with network play, powerful map editor, etc.<br />
* '''Git Repository:''' https://github.com/Doom2D/Doom2D-ForeverAUR<br />
* '''Issue Tracker:''' https://github.com/Doom2D/Doom2D-ForeverAUR/issues<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?search=E0DBB3D1D7AA8E6B&fingerprint=on&op=index E0DBB3D1D7AA8E6B]<br />
<br />
{{bc|<nowiki><br />
[doom2df-repo]<br />
# RU, Saint-Peterburg<br />
Server = https://repo.terminalcorner.ru/$repo<br />
# USA<br />
Server = https://terminalhash.deadsoftware.ru/repositories/$repo<br />
</nowiki>}}<br />
<br />
=== fcgu ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/fabiscafe Fabian Bornschein]<br />
* '''Description:''' Overlay repository, mostly for unstable (Beta, RC) releases of GNOME- and related software.<br />
* '''Homepage:''' https://codeberg.org/fabiscafe/fcgu<br />
* '''Keyfile:''' https://keys.openpgp.org/vks/v1/by-fingerprint/6E58E886A8E07538A2485FAED6A4F386B4881229<br />
* '''Key-ID:''' D6A4F386B4881229<br />
{{Note|Instructions can be found at [https://codeberg.org/fabiscafe/fcgu#fcgu-repo-for-gnome-pre-releases https://codeberg.org/fabiscafe/fcgu]}}<br />
<br />
=== g14 ===<br />
<br />
* '''Maintainer:''' [https://gitlab.com/flukejones Luke Jones]<br />
* '''Description:''' A custom repository for [[ASUS Linux]], it contains prebuilt binaries for all of the software they offer.<br />
* '''Upstream page:''' https://asus-linux.org/<br />
* '''Package list:''' https://arch.asus-linux.org/<br />
* '''Key-ID:''' 8F654886F17D497FEFE3DB448B15A6B0E9A3FA35<br />
<br />
{{bc|<nowiki><br />
[g14]<br />
# Germany, origin<br />
Server = https://arch.asus-linux.org<br />
# Republic of Korea<br />
Server = https://naru.jhyub.dev/$repo<br />
</nowiki>}}<br />
<br />
=== grawlinson ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/grawlinson George Rawlinson]<br />
* '''Description:''' AUR packages maintained by the user as well as some experimental packages.<br />
* '''Package list:''' https://mirror.little.kiwi<br />
* '''Key-ID:''' 9D120F4AAF400B8313A87EF2369552B2069123EE<br />
* '''Keyfile:''' https://mirror.little.kiwi/grawlinson.asc<br />
* '''Source:''' https://git.little.kiwi/grawlinson/arch-pkgs<br />
<br />
{{bc|<nowiki><br />
[grawlinson]<br />
Server = https://mirror.little.kiwi<br />
Server = https://pkgbuild.com/~grawlinson/repo/$repo<br />
</nowiki>}}<br />
<br />
=== herecura ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#idevolder Ike Devolder]<br />
* '''Description:''' additional packages not found in the ''community'' repository<br />
* '''Key-ID:''' Not required, as maintainer is a TU<br />
* '''Git Repo:''' https://gitlab.com/herecura/packages<br />
<br />
{{bc|<nowiki><br />
[herecura]<br />
Server = https://repo.herecura.eu/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== home-thaodan ===<br />
<br />
* '''Maintainer''': [https://aur.archlinux.org/account/Thaodan Thaodan]<br />
* '''Upstream page''': https://gitlab.com/Thaodans-ArchLinux-Packages/repo-home-thaodan<br />
* '''Description''': packages by Thaodan<br />
* '''Key-ID:''': BBFE2FD421597395E4FC8C8DF6C85FEE79D661A4<br />
<br />
{{bc|<nowiki><br />
[home-thaodan]<br />
Server = https://repo.thaodan.de/archlinux/home-thaodan/$arch<br />
</nowiki>}}<br />
<br />
=== ivasilev ===<br />
<br />
* '''Maintainer:''' [https://ivasilev.net Ianis G. Vasilev]<br />
* '''Description:''' A variety of packages, mostly my own software and AUR builds.<br />
* '''Upstream page:''' https://ivasilev.net/pacman<br />
* '''Key-ID:''' [https://pgp.mit.edu/pks/lookup?op=vindex&search=0xB77A3C8832838F1F80ADFD7E1D0507B417DAB671 17DAB671]<br />
<br />
{{bc|<nowiki><br />
[ivasilev]<br />
Server = https://ivasilev.net/pacman/$arch<br />
</nowiki>}}<br />
<br />
=== jk-aur ===<br />
<br />
* '''Maintainer:''' [https://github.com/jstkdng JustKidding]<br />
* '''Description:''' Packages from the AUR I maintain and co-maintain.<br />
* '''Upstream page:''' https://github.com/jstkdng/aur<br />
* '''Key-ID:''' [https://build.opensuse.org/project/keys_and_certificates/home:justkidding:arch 7627D0F8F60FBA35371A29E1AA6B2752759F9361]<br />
<br />
{{bc|<nowiki><br />
[home_justkidding_arch_Arch]<br />
Server = https://download.opensuse.org/repositories/home:/justkidding:/arch/Arch/$arch<br />
</nowiki>}}<br />
<br />
=== jlk ===<br />
<br />
* '''Maintainer:''' [[User:Lahwaacz|Jakub Klinkovský]]<br />
* '''Description:''' Various packages mostly from the AUR.<br />
* '''Upstream page:''' https://jlk.fjfi.cvut.cz/arch/repo/README.html<br />
* '''Key-ID:''' 932BA3FA0C86812A32D1F54DAB5964AEB9FEDDDC<br />
<br />
{{bc|<nowiki><br />
[jlk]<br />
Server = https://jlk.fjfi.cvut.cz/arch/repo<br />
</nowiki>}}<br />
<br />
=== kawaii ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/LeonidPilyugin Leonid Pilyugin]<br />
* '''Description:''' Kawaii modified packages from AUR and myself.<br />
* '''Upstream page:''' https://github.com/LeonidPilyugin/kawaii-repo<br />
* '''Key-ID:''' A308BDBE10D7C9C168AA2E055F2E4806FFE6B2CD<br />
<br />
{{bc|<nowiki><br />
[kawaii]<br />
Server = https://raw.githubusercontent.com/LeonidPilyugin/kawaii-repo/main/x86_64/<br />
</nowiki>}}<br />
<br />
=== levitating ===<br />
<br />
* '''Maintainer''' [https://levitati.ng levitating]<br />
* '''Description''' An automatically build collection of my own hobby projects.<br />
*'''Key-ID''' [https://keyserver.ubuntu.com/pks/lookup?search=6DF9D13B4F64C91B&fingerprint=on&op=index 6DF9D13B4F64C91B]<br />
<br />
{{bc|<nowiki><br />
[levitating]<br />
Server = https://levitati.ng/archlinux/$repo/os/$arch<br />
</nowiki>}}<br />
<br />
=== linux-nitrous ===<br />
<br />
* '''Maintainer:''' [https://superboring.dev Simao Gomes Viana (superboringdev or xdevs23)]<br />
* '''Description:''' linux-nitrous is a repository with prebuilt packages of the [https://gitlab.com/xdevs23/linux-nitrous linux-nitrous kernel]<br />
* '''Git Repo:''' https://gitlab.com/xdevs23/linux-nitrous<br />
* '''Issue tracking:''' https://github.com/xdevs23/linux-nitrous/issues for packaging issues and questions<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xE9C2DECAC962CB3AF1376D44148A9E3C9C3E3BF0 9C3E3BF0] (keyserver.ubuntu.com) | [https://pgp.mit.edu/pks/lookup?op=get&search=0x148A9E3C9C3E3BF0 9C3E3BF0] (pgp.mit.edu) | [http://pgp.net.nz:11371/pks/lookup?op=get&fingerprint=on&search=0x148A9E3C9C3E3BF0 9C3E3BF0] (pgp.net.nz)<br />
<br />
{{bc|<nowiki><br />
[linux-nitrous]<br />
Server = https://github.com/xdevs23/linux-nitrous/releases/latest/download<br />
</nowiki>}}<br />
<br />
=== linuxrepos ===<br />
<br />
* '''Maintainer:''' [[User:TheRepoClub|TheRepoClub]]<br />
* '''Description:''' A repository with some of the AUR packages that TheRepoClub use<br />
* '''Upstream page:''' https://arch.linuxrepos.org<br />
* '''Key-ID:''' [http://pgp.net.nz:11371/pks/lookup?op=vindex&fingerprint=on&search=0xE30EC2FBFB05C44F 75A38DC684F1A0B808918BCEE30EC2FBFB05C44F]<br />
<br />
{{bc|<nowiki><br />
[linuxrepos]<br />
Server = https://arch.linuxrepos.org/$arch/<br />
</nowiki>}}<br />
<br />
=== liquorix ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/damentz Steven Barrett (damentz)]<br />
* '''Description:''' Repository containing automated builds of {{AUR|linux-lqx}}, {{AUR|linux-lqx-headers}}, and {{AUR|linux-lqx-docs}}<br />
* '''Upstream page:''' https://liquorix.net<br />
* '''Git Repo:''' https://github.com/damentz/liquorix-package, https://aur.archlinux.org/cgit/aur.git/log/?h=linux-lqx<br />
* '''Issue tracking:''' https://github.com/damentz/liquorix-package/issues<br />
* '''Key-ID: ''' [https://keys.openpgp.org/vks/v1/by-fingerprint/C5ADB4F3FEBBCE27A3E54D7D9AE4078033F8024D 9AE4078033F8024D] (keys.openpgp.org)<br />
<br />
{{bc|<nowiki><br />
[liquorix]<br />
Server = https://liquorix.net/archlinux/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== miffe ===<br />
<br />
* '''Maintainer:''' [https://arch.miffe.org/README.html miffe] ([https://aur.archlinux.org/account/miffe AUR profile])<br />
* '''Description:''' AUR packages maintained by miffe, e.g. linux-mainline<br />
* '''Key ID:''' 313F5ABD<br />
<br />
{{bc|<nowiki><br />
[miffe]<br />
Server = https://arch.miffe.org/$arch/<br />
</nowiki>}}<br />
<br />
=== mxmeinhold ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/mxmeinhold mxmeinhold]<br />
* '''Description:''' Packages I maintain in the AUR, currently just factorio-headless<br />
* '''Key ID:''' B77D730E8D444707FA93320D72E05836F8252405<br />
* '''Keyfile:''' https://gpg.mxmeinhold.com<br />
<br />
{{bc|<nowiki><br />
[mxmeinhold]<br />
Server = https://arch.mxmeinhold.com/$arch<br />
</nowiki>}}<br />
<br />
=== orhun ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#orhun Orhun Parmaksiz]<br />
* '''Description:''' Personal repository with AUR and custom packages.<br />
* '''Key-ID:''' Not needed, as the maintainer is a TU<br />
<br />
{{bc|<nowiki><br />
[orhun]<br />
Server = https://pkgbuild.com/~orhun/repo<br />
</nowiki>}}<br />
<br />
=== oscloud ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/bionade24 bionade24]<br />
* '''Description:''' <s>ROS melodic packages and necessary dependencies,</s> various cmd-line tools, and other packages from the AUR.<br />
* '''CI/CD status:''' https://abs-cd.oscloud.info<br />
* '''Key-ID:''' FF363C5F81664E2B<br />
<br />
{{bc|<nowiki><br />
[oscloud]<br />
Server = http://repo.oscloud.info/<br />
</nowiki>}}<br />
<br />
=== ownstuff ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/Martchus Martchus]<br />
* '''Description:''' A lot of packages from the AUR, e.g. a great number packages for mingw-w64 and Android cross compilation, fonts, Perl modules, tools like {{AUR|tageditor}}, {{AUR|syncthingtray}}, {{AUR|subtitlecomposer}} and {{AUR|qmplay2}}<br />
* '''Upstream page''': https://github.com/Martchus/PKGBUILDs (sources beside the AUR) and https://martchus.no-ip.biz/buildservice/#package-search-section (package browser/search)<br />
* '''Key-ID:''' B9E36A7275FC61B464B67907E06FE8F53CDC6A4C<br />
<br />
{{bc|<nowiki><br />
[ownstuff-testing]<br />
Server = https://ftp.f3l.de/~martchus/$repo/os/$arch<br />
Server = https://martchus.no-ip.biz/repo/arch/$repo/os/$arch<br />
<br />
[ownstuff]<br />
Server = https://ftp.f3l.de/~martchus/$repo/os/$arch<br />
Server = https://martchus.no-ip.biz/repo/arch/$repo/os/$arch<br />
</nowiki>}}<br />
<br />
{{Note|The testing repository is supposed to be used together with the official testing repositories.}}<br />
<br />
=== pkgbuilder ===<br />
<br />
* '''Maintainer:''' [https://chriswarrick.com/ Chris Warrick]<br />
* '''Description:''' A repository for PKGBUILDer, a Python AUR helper.<br />
* '''Upstream page:''' https://github.com/Kwpolska/pkgbuilder<br />
* '''Key-ID:''' 5EAAEA16<br />
<br />
{{bc|<nowiki><br />
[pkgbuilder]<br />
Server = https://pkgbuilder-repo.chriswarrick.com/<br />
</nowiki>}}<br />
<br />
=== post-factum kernels ===<br />
<br />
* '''Maintainer''': [https://aur.archlinux.org/account/post-factum Oleksandr Natalenko aka post-factum]<br />
* '''Upstream page''': https://pfkernel.natalenko.name<br />
* '''Description''': [[linux-pf|pf-kernel]] packages by its developer, post-factum<br />
* '''Key-ID:''': 95C357D2AF5DA89D<br />
* '''Keyfile''': https://download.opensuse.org/repositories/home:/post-factum:/kernels/Arch/x86_64/home_post-factum_kernels_Arch.key<br />
<br />
{{bc|<nowiki><br />
[home_post-factum_kernels_Arch]<br />
Server = https://download.opensuse.org/repositories/home:/post-factum:/kernels/Arch/$arch<br />
</nowiki>}}<br />
<br />
=== pro-audio-legacy ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/developers/#dvzrv David Runge]<br />
* '''Description:''' Legacy tooling for [[pro-audio]] (e.g. {{AUR|jack}}), mainly useful for old setups or CI<br />
* '''Key-ID:''' Not needed, as maintainer is a developer/TU<br />
<br />
{{bc|<nowiki><br />
[pro-audio-legacy]<br />
Server = https://pkgbuild.com/~dvzrv/repos/pro-audio-legacy/$arch<br />
</nowiki>}}<br />
<br />
=== proaudio ===<br />
<br />
* '''Maintainer:''' [https://github.com/osam-cologne/ OSAMC] members ([https://aur.archlinux.org/account/SpotlightKid SpotlightKid], [https://aur.archlinux.org/account/cbix cbix], [https://aur.archlinux.org/account/daniel.appelt daniel.appelt] et al.)<br />
* '''Description:''' [[Pro Audio]] packages not (yet) in the official repos, built for x86_64 and aarch64<br />
* '''Upstream page:''' https://arch.osamc.de/<br />
* '''GitHub repo:''' https://github.com/osam-cologne/archlinux-proaudio (PRs welcome)<br />
* '''Key-ID:''' 762AE5DB2B38786364BD81C4B9141BCC62D38EE5<br />
* '''Keyfile:''' https://arch.osamc.de/proaudio/osamc.gpg<br />
<br />
{{bc|<nowiki><br />
[proaudio]<br />
Server = https://arch.osamc.de/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== QOwnNotes ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/pbek Patrizio Bekerle] (pbek), QOwnNotes author<br />
* '''Description:''' QOwnNotes is an open-source notepad and todo list manager with markdown support and [[ownCloud]] integration.<br />
* '''Key-ID:''' F2205FB121DF142B31450865A3BA514562A835DB<br />
* '''Keyfile:''' https://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Arch_Extra/x86_64/home_pbek_QOwnNotes_Arch_Extra.key<br />
<br />
{{bc|<nowiki><br />
[home_pbek_QOwnNotes_Arch_Extra]<br />
Server = https://download.opensuse.org/repositories/home:/pbek:/QOwnNotes/Arch_Extra/$arch<br />
</nowiki>}}<br />
<br />
=== quarry ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/developers/#anatolik anatolik]<br />
* '''Description:''' Arch binary repository for [https://rubygems.org/ Rubygems] packages. See [https://bbs.archlinux.org/viewtopic.php?id=182729 forum announcement] for more information.<br />
* '''Sources:''' https://github.com/anatol/quarry<br />
* '''Key-ID:''' Not needed, as the maintainer is a developer<br />
<br />
{{bc|<nowiki><br />
[quarry]<br />
Server = https://pkgbuild.com/~anatolik/quarry/x86_64/<br />
</nowiki>}}<br />
<br />
=== repo-ck ===<br />
<br />
Kernel and modules with Brain Fuck Scheduler and all the goodies in the ck1 patch set.<br />
<br />
See [[/Repo-ck]].<br />
<br />
=== repo.mksscryertower.quest ===<br />
<br />
* '''Maintainer:''' [[User:Scry3r|Klimenko Maxim Sergievich]]<br />
* '''Description:''' Collection of AUR packages that I personally use: Opensnitch-ebpf, libraries and etc. Repo has backups and some old version of the packages for backward compatibility in index of /repo/ .<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?search=8A36037D80912162&fingerprint=on&op=index 8A36037D80912162]<br />
<br />
{{bc|<nowiki><br />
[repo.mksscryertower.quest]<br />
Server = https://repo.mksscryertower.quest/repo/x86_64/<br />
</nowiki>}}<br />
<br />
=== rne ===<br />
<br />
* '''Maintainer:''' [[User:Schard|Richard Neumann]]<br />
* '''Description:''' Collection of AUR packages that I personally use.<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?search=4CA8D523BD386AF7&fingerprint=on&op=index 4CA8D523BD386AF7]<br />
<br />
{{bc|<nowiki><br />
[rne]<br />
Server = https://srv.richard-neumann.de/pub/repo/<br />
</nowiki>}}<br />
<br />
=== seblu ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/developers/#seblu Sébastien Luttringer]<br />
* '''Description:''' All seblu useful pre-built packages, some homemade (linux-seblu-meta, zfs-dkms, spotify, masterpdfeditor, etc).<br />
* '''Key-ID:''' [https://seblu.net/.well-known/openpgpkey/hu/fmrhcha6xtpwnfp1enxwfw1wac7a77um?h=95b08852 8DBD63B82072D77A]<br />
<br />
{{bc|<nowiki><br />
[seblu]<br />
Server = https://al1.seblu.net/$repo/$arch<br />
Server = https://al2.seblu.net/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== seiichiro ===<br />
<br />
* '''Maintainer:''' [https://www.seiichiro0185.org Stefan Brand (seiichiro0185)]<br />
* '''Description:''' AUR-packages I use frequently<br />
* '''Key-ID:''' 805517CC<br />
<br />
{{bc|<nowiki><br />
[seiichiro]<br />
Server = https://www.seiichiro0185.org/repo/$arch<br />
</nowiki>}}<br />
<br />
=== sergej-repo ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#spupykin Sergej Pupykin]<br />
* '''Description:''' nextcloud, prosody, and some other stuff.<br />
* '''Key-ID:''' Not required, as the maintainer is a TU<br />
<br />
{{bc|<nowiki><br />
[sergej-repo]<br />
Server = http://repo.p5n.pp.ru/$repo/os/$arch<br />
</nowiki>}}<br />
<br />
=== sublime-text ===<br />
<br />
* '''Maintainer:''' Sublime Text developer<br />
* '''Description:''' Sublime Text editor packages from developer's repository<br />
* '''Upstream page:''' https://www.sublimetext.com/docs/3/linux_repositories.html#pacman<br />
* '''Key-ID:''' 8A8F901A<br />
<br />
{{bc|<nowiki><br />
[sublime-text]<br />
Server = https://download.sublimetext.com/arch/stable/$arch<br />
</nowiki>}}<br />
<br />
=== speedie-aur ===<br />
<br />
* '''Maintainer:''' [https://speedie.site speedie]<br />
* '''Description:''' Repository of packages for software I use.<br />
* '''Repository:''' https://aur.speedie.site<br />
* '''Key-ID:''' CEB863B830D1318A<br />
<br />
{{bc|<nowiki><br />
[speedie-aur]<br />
Server = https://aur.speedie.site<br />
</nowiki>}}<br />
<br />
=== supermario ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/supermario Mario Finelli (supermario)]<br />
* '''Description:''' AUR packages that I use or maintain<br />
* '''Git Repository:''' https://github.com/mfinelli/pkgs, https://github.com/mfinelli/aur-packages<br />
* '''Key-ID:''' C3CD75B002978A8468CA7B1F6C3ADDDE36FDA306<br />
* '''Keyfile:''' https://finelli.pub/36FDA306.asc<br />
<br />
{{bc|<nowiki><br />
[supermario]<br />
Server = https://pkgs.finelli.dev/arch/$arch<br />
</nowiki>}}<br />
<br />
=== trinity ===<br />
<br />
* '''Maintainer:''' [https://trinitydesktop.org/ Trinity Desktop Environment Developers]<br />
* '''Description:''' [[Trinity]] Desktop Environment<br />
* '''Key-ID:''' 8685AD8B<br />
<br />
{{bc|<nowiki><br />
[trinity]<br />
Server = https://mirror.ppa.trinitydesktop.org/trinity/archlinux/$arch<br />
</nowiki>}}<br />
<br />
=== wsdm ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/WSDMatty Matthew Sexton]<br />
* '''Description:''' AUR packages I maintain/comaintain plus their AUR dependencies.<br />
* '''Git Repository:''' https://github.com/wsdmatty/wsdm<br />
* '''Key-ID:''' [https://keyserver.ubuntu.com/pks/lookup?search=97928FA059F8050487930EAFACF6C1A315EDCB52&fingerprint=on&exact=on&op=index 97928fa059f8050487930eafacf6c1a315edcb52]<br />
<br />
{{bc|<nowiki><br />
[wsdm]<br />
Server = https://wsdmatty.github.io/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== xuanrui ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/xuanruiqi Xuanrui Qi (xuanruiqi)]<br />
* '''Description:''' xuanruiqi's own packages and frequently-used packages, mainly of interest to functional programmers.<br />
* '''Upstream Page:''' https://www.xuanruiqi.com/linux.html<br />
* '''Key-ID:''' 6E06FBC8<br />
<br />
{{bc|<nowiki><br />
[xuanrui]<br />
Server = https://arch.xuanruiqi.com/repo<br />
</nowiki>}}<br />
<br />
=== xyne-x86_64 ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#xyne Xyne]<br />
* '''Description:''' A repository for Xyne's own projects.<br />
* '''Upstream page:''' https://xyne.dev/projects/<br />
* '''Key-ID:''' Not required, as maintainer is a TU<br />
<br />
{{bc|<nowiki><br />
[xyne-x86_64]<br />
Server = https://xyne.dev/repos/xyne<br />
</nowiki>}}<br />
<br />
== Unsigned ==<br />
<br />
{{Note|Users will need to add the following to these entries: {{ic|1=SigLevel = PackageOptional}}}}<br />
<br />
{{Warning|HTTP must not be used for unsigned repositories, without HTTPS there is no validity check that the content you have downloaded was the content which the web server was serving, potentially allowing a [[Wikipedia:Man-in-the-middle attack|MiTM (Man in The Middle) attack]] to install any software to your system. HTTPS mitigates such vulnerability.}}<br />
<br />
=== alucryd ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#alucryd Maxime Gauduin]<br />
* '''Description:''' Various packages Maxime Gauduin maintains (or not) in the AUR, in particular the multilib repository is for various packages needed to run Steam without its runtime environment.<br />
<br />
{{bc|<nowiki><br />
[core-alucryd]<br />
Server = https://pkgbuild.com/~alucryd/$repo/$arch<br />
[core-testing-alucryd]<br />
Server = https://pkgbuild.com/~alucryd/$repo/$arch<br />
[extra-alucryd]<br />
Server = https://pkgbuild.com/~alucryd/$repo/$arch<br />
[extra-testing-alucryd]<br />
Server = https://pkgbuild.com/~alucryd/$repo/$arch<br />
[multilib-alucryd]<br />
Server = https://pkgbuild.com/~alucryd/$repo/$arch<br />
[multilib-testing-alucryd]<br />
Server = https://pkgbuild.com/~alucryd/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== arch-mact2 ===<br />
<br />
* '''Maintainer:''' [https://noa.codes Noa Himesaka]<br />
* '''Description:''' Kernel and utilities for use on Macs with T2 security chip.<br />
* '''Upstream page:''' https://mirror.funami.tech/arch-mact2<br />
<br />
{{bc|<nowiki><br />
[arch-mact2]<br />
Server = https://mirror.funami.tech/arch-mact2/os/$arch<br />
</nowiki>}}<br />
<br />
=== archlinuxir ===<br />
<br />
* '''Maintainer:''' Bardia Moshiri<br />
* '''Description:''' Most used packages by the Iranian Arch Linux community.<br />
* '''Note:''' Server is hosted in Iran and traffic from Iranian IP's will count as half from ISP's (Nim baha).<br />
* '''Note:''' Keep in mind that the repository is updated every 6 hours.<br />
* '''Upstream page:''' https://mirror.bardia.tech<br />
<br />
{{bc|<nowiki><br />
[archlinuxir]<br />
Server = https://mirror.bardia.tech/archlinuxir/$arch<br />
</nowiki>}}<br />
<br />
=== archlinux-phalcon ===<br />
<br />
* '''Maintainer:''' Michal Sotolar <michal at sotolar dot com><br />
* '''Description:''' Phalcon Framework PHP 5.6 - 7.x extension builds<br />
* '''Upstream page:''' https://archlinux-phalcon.gitlab.io<br />
<br />
{{bc|<nowiki><br />
[archlinux-phalcon]<br />
Server = https://archlinux-phalcon.gitlab.io/repository<br />
</nowiki>}}<br />
<br />
=== archlinux-php ===<br />
<br />
* '''Maintainer:''' Michal Sotolar <michal at sotolar dot com><br />
* '''Description:''' PHP 5.6 - 7.x old stable builds coexistable with mainline version<br />
* '''Upstream page:''' https://archlinux-php.gitlab.io<br />
<br />
{{bc|<nowiki><br />
[archlinux-php]<br />
Server = https://archlinux-php.gitlab.io/repository<br />
</nowiki>}}<br />
<br />
=== archmint ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/ArchMint ArchMint]<br />
* '''Description:''' ArchMint GNU/Linux packages from developer's repository<br />
* '''Upstream page:''' https://sourceforge.net/projects/archmint/files/repo/<br />
<br />
{{bc|<nowiki><br />
[archmint]<br />
Server = https://sourceforge.net/projects/archmint/files/repo/$arch<br />
</nowiki>}}<br />
<br />
=== dx37essentials ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/DragonX256 DragonX256]<br />
* '''Description:''' Personal repository. Contains packages from AUR, which I using every day.<br />
* '''Git repo:''' https://gitlab.com/DX37/dx37essentials<br />
* '''Upstream page:''' https://dx3756.ru/dx37essentials<br />
<br />
{{bc|<nowiki><br />
[dx37essentials]<br />
Server = https://dx3756.ru/$repo/$arch<br />
Server = https://dx37.gitlab.io/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== ffy00 (python) ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#FFY00 Filipe Laíns]<br />
* '''Description:''' Provides several different Python versions (eg. 3.5, 3.6, 3.7). All active Python releases should be available here.<br />
* '''Git repo:''' https://github.com/FFY00/arch-python-repo<br />
* '''Upstream page:''' https://github.com/FFY00/arch-python-repo<br />
<br />
{{bc|<nowiki><br />
[python]<br />
Server = https://ffy00.github.io/arch-python-repo/<br />
</nowiki>}}<br />
<br />
=== heftig ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/developers/#heftig Jan Alexander Steffens]<br />
* '''Description:''' Includes [https://pkgbuild.com/~heftig/packages/firefox-nightly/ firefox-nightly], {{AUR|freetype2-git}} and [https://pkgbuild.com/~heftig/packages/stone-soup-git/ stone-soup-git]<br />
* '''Upstream page:''' https://bbs.archlinux.org/viewtopic.php?id=117157<br />
<br />
{{bc|<nowiki><br />
[heftig]<br />
Server = https://pkgbuild.com/~heftig/repo/$arch<br />
</nowiki>}}<br />
<br />
=== kicad-nightly ===<br />
<br />
* '''Maintainer:''' Rafael Silva <perigoso@riseup.net><br />
* '''Description:''' Prebuilt nightly packages for KiCad<br />
* '''Git repo:''' https://gitlab.com/kicad/packaging/kicad-arch/kicad-arch-builder<br />
* '''Upstream page:''' https://www.kicad.org/help/nightlies-and-rcs/<br />
<br />
{{bc|<nowiki><br />
[kicad-nightly]<br />
Server = https://kicad.gitlab.io/packaging/kicad-arch/kicad-arch-builder/<br />
</nowiki>}}<br />
<br />
=== mesa-git ===<br />
<br />
* '''Maintainer:''' [https://archlinux.org/people/trusted-users/#lcarlier Laurent Carlier]<br />
* '''Description:''' Mesa git builds for the [[testing]] repositories<br />
<br />
{{bc|<nowiki><br />
[mesa-git]<br />
Server = https://pkgbuild.com/~lcarlier/$repo/$arch<br />
</nowiki>}}<br />
<br />
=== principia ===<br />
<br />
* '''Maintainer:''' ROllerozxa <rollerozxa@voxelmanip.se><br />
* '''Description:''' Binary builds of the {{AUR|principia-git}} package.<br />
* '''Upstream page:''' https://grejer.voxelmanip.se/principia/arch-repo/<br />
<br />
{{bc|<nowiki><br />
[principia]<br />
Server = https://grejer.voxelmanip.se/principia/arch-repo/$arch<br />
</nowiki>}}<br />
<br />
=== pietma ===<br />
<br />
* '''Maintainer:''' MartiMcFly <martimcfly@autorisation.de><br />
* '''Description:''' Arch User Repository packages [https://aur.archlinux.org/packages/?K=martimcfly&SeB=m I create or maintain.].<br />
* '''Upstream page:''' https://pietma.com/tag/aur/<br />
<br />
{{bc|<nowiki><br />
[pietma]<br />
Server = https://repository.pietma.com/nexus/content/repositories/archlinux/$arch/$repo<br />
</nowiki>}}<br />
<br />
=== pnsft-pur ===<br />
<br />
* '''Maintainer:''' [https://aur.archlinux.org/account/ponsfoot ponsfoot]<br />
* '''Description:''' Japanese input method packages Mozc (vanilla) and libkkc<br />
<br />
{{bc|<nowiki><br />
[pnsft-pur]<br />
Server = https://osdn.net/projects/ponsfoot-aur/storage/pur/$arch<br />
</nowiki>}}<br />
<br />
=== rayr ===<br />
<br />
* '''Maintainer:''' [https://rayr.link/LinkInBio Rayr]<br />
* '''Description:''' Prebuilt packages of my AUR packages, as an Arch repo.<br />
* '''Upstream page:''' https://github.com/Rayrsn/ArchRepo<br />
<br />
{{bc|<nowiki><br />
[rayr]<br />
Server = https://rayrsn.github.io/ArchRepo/$arch<br />
</nowiki>}}<br />
<br />
=== selinux ===<br />
<br />
* '''Maintainer:''' Nicolas Iooss (nicolas <dot> iooss <at> m4x <dot> org)<br />
* '''Description:''' Provide binary packages for [[SELinux]].<br />
* '''Upstream Page:''' https://github.com/archlinuxhardened/selinux<br />
<br />
{{bc|<nowiki><br />
[selinux]<br />
Server = https://github.com/archlinuxhardened/selinux/releases/download/ArchLinux-SELinux<br />
SigLevel = Never<br />
</nowiki>}}<br />
<br />
=== stx4 ===<br />
<br />
* '''Maintainer:''' StarterX4 <starterx4[at]gmail.com><br />
* '''Description:''' Any – some fonts and fakepkgs; x86_64 – archival yet might useful packages (like PacmanXG4), and some AUR soft I use[d].<br />
* '''Upstream Page:''' https://github.com/StarterX4/StarterX4.github.io<br />
<br />
{{bc|<nowiki><br />
[stx4-any]<br />
Server = https://starterx4.github.io/repos/arch/$arch/stx4<br />
[stx4-x86_64]<br />
Server = https://starterx4.github.io/repos/arch/$arch/stx4<br />
</nowiki>}}<br />
<br />
=== vdr4arch ===<br />
<br />
* '''Maintainers:''' [https://aur.archlinux.org/account/CReimer CReimer], [https://aur.archlinux.org/account/M-Reimer M-Reimer]<br />
* '''Description:''' A set of VDR packages for Arch Linux<br />
* '''Upstream page:''' https://github.com/VDR4Arch/vdr4arch<br />
<br />
{{Note|Packages are automatically built with [https://github.com/VDR4Arch/vdr4arch/blob/master/.ci/repo-make-ci.sh repo-make-ci.sh].}}<br />
<br />
{{bc|<nowiki><br />
[vdr4arch]<br />
Server = https://vdr4arch.github.io/$arch<br />
</nowiki>}}<br />
<br />
== Packages search ==<br />
<br />
{{Warning|{{ic|pkgs.org}} lists [[Arch Linux ARM]] aarch64 repositories as official under the Arch Linux organisation, this is factually incorrect, these repositories are unofficial and you use them at your own risk.}}<br />
<br />
Many of the unofficial Arch Linux repositories are indexed on https://archlinux.pkgs.org/.<br />
<br />
It provides repositories browser and packages search.</div>Progandyhttps://wiki.archlinux.org/index.php?title=XDG_Desktop_Portal&diff=790544XDG Desktop Portal2023-10-20T18:41:55Z<p>Progandy: Remove the out of date message and add a tip in the backends section instead.</p>
<hr />
<div>{{Template:Related articles start}}<br />
{{Template:Related|Flatpak}}<br />
{{Template:Related|PipeWire#WebRTC screen sharing}}<br />
{{Template:Related articles end}}<br />
[[Category:Freedesktop.org]]<br />
[[ja:XDG デスクトップ ポータル]]<br />
<br />
{{Move|xdg-desktop-portal|{{ic|xdg-desktop-portal}} is the official name of the project.}}<br />
<br />
From the [https://docs.flatpak.org/en/latest/desktop-integration.html#portals Flatpak documentation]:<br />
<br />
:Portals are the framework for securely accessing resources from outside an application sandbox. They provide a range of common features to applications, including: Determining network status, opening a file with a file chooser, opening URIs, taking screenshots and screencasts [...]<br />
<br />
Portals were designed for use with applications sandboxed through [[Flatpak]], but any application can use portals to provide uniform access to features independent of desktops and toolkits. This is commonly used, for example, to [[PipeWire#WebRTC screen sharing|allow screen sharing]] on [[Wayland]] via [[PipeWire]], or to [[Firefox#KDE integration|use file open and save dialogs]] on [[Firefox]] that use the same toolkit as your current [[desktop environment]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|xdg-desktop-portal}} and one or more [[#Backends|backends]]. The package includes a [[systemd/User]] service that will be automatically started via [[D-Bus]].<br />
<br />
== Backends ==<br />
<br />
When an application makes a request through a portal, it is handled by {{ic|xdg-desktop-portal}}, which then forwards it to a backend implementation. This allows a clean way to provide suitable user interfaces that fit into different desktop environments, and access environment-specific APIs for requests like showing notifications or recording the screen. Multiple backends can be installed: for example, a [[Sway]] user may use {{Pkg|xdg-desktop-portal-wlr}} for screen sharing support and {{Pkg|xdg-desktop-portal-gtk}} as a fallback for all other interfaces that ''xdg-desktop-portal-wlr'' does not implement.<br />
<br />
Portal backend definitions are located in {{ic|/usr/share/xdg-desktop-portal/portals/*.portal}}. Each portal backend file contains a list of interfaces that it can handle, and the desktop environments that it can be used in. When a request is made, {{ic|xdg-desktop-portal}} will use the {{ic|/usr/share/xdg-desktop-portal/''DE''-portals.conf}} file to determine which backend it will use for the request, where ''DE'' is based on the {{ic|XDG_CURRENT_DESKTOP}} [[environment variable]].<br />
<br />
Users may also create their own portal configuration file at {{ic|$XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf}} to determine which backends they want to use, either generally or for each individual interface. See {{Man|5|portals.conf}} for more information.<br />
<br />
{{Tip|1=To use the gtk portal as a fallback, it may be necessary to create the configuration file {{ic|''DE''-portals.conf}} or {{ic|portals.conf}}. [https://bbs.archlinux.org/viewtopic.php?id=289405 See this forum discussion]. }}<br />
<br />
=== List of backends and interfaces ===<br />
<br />
The following table lists all backends available and their support for certain common interfaces.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Backend !! File chooser !! Screenshot and screen cast<br />
|-<br />
| {{Pkg|xdg-desktop-portal-dde}} || {{G|Yes}} || {{G|Yes, on [[Deepin Desktop Environment]]}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-gnome}} || {{G|Yes}} || {{G|Yes, on [[GNOME]]}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-gtk}} || {{Yes}} || {{No}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-kde}} || {{Yes}} || {{G|Yes, on [[KDE]]}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-hyprland}}<sup>1</sup> || {{No}} || {{G|Yes, on {{Pkg|wlroots}}}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-lxqt}} || {{Yes}} || {{No}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-wlr}} || {{No}} || {{G|Yes, on {{Pkg|wlroots}}}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-xapp}} || {{No}} || {{G|Yes, on [[Cinnamon]]}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-liri-git}} || {{Yes}} || {{G|Yes, on [[Liri]]}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-shana}} || {{Yes}}<sup>2</sup> || {{No}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-td}} || {{Yes}} || {{No}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-termfilechooser-git}} || {{Yes}}<sup>3</sup> || {{No}}<br />
|-<br />
|}<br />
<br />
#works with all wlroots-based compositors, but provides extra functionality when used with [[Hyprland]] such as sharing individual windows.<br />
#redirects requests to GNOME/GTK/KDE/LXQt backends<br />
#allows using a [[List of applications/Utilities#Console|terminal file manager]] as a file chooser<br />
<br />
== Troubleshooting ==<br />
<br />
=== xdg-desktop-portal-wlr does not start automatically on sway ===<br />
<br />
For {{ic|xdg-desktop-portal-wlr}} to work, the {{ic|XDG_CURRENT_DESKTOP}} and {{ic|WAYLAND_DISPLAY}} environment variables have to be set in the [[Systemd/User#Environment variables|systemd user session]]. {{ic|XDG_CURRENT_DESKTOP}} has to be set to the name of your compositor, e.g. {{ic|1=XDG_CURRENT_DESKTOP=sway}}. {{ic|WAYLAND_DISPLAY}} is set automatically by the compositor.<br />
<br />
Check whether these variables are set with {{ic|systemctl --user show-environment}}. If they are not set, import these environment variables into the systemd user session and dbus by running the following commands after launching the compositor (e.g., include them in the compositor's configuration file).<br />
<br />
$ systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP<br />
$ dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=''compositor_name''<br />
<br />
{{Tip|[[Sway]] provides a drop-in file which does this automatically, see [[Sway#Configuration]].}}<br />
<br />
See [https://github.com/emersion/xdg-desktop-portal-wlr#running] and [https://github.com/emersion/xdg-desktop-portal-wlr/wiki] for more details.<br />
<br />
=== Using multiple monitors with xdg-desktop-portal-wlr ===<br />
<br />
{{ic|xdg-desktop-portal-wlr}} requires an external chooser to select the shared monitor. By default, it looks for {{Pkg|slurp}}, {{Pkg|wofi}} and {{Pkg|bemenu}} in this order. When using ''slurp'', after a request for screen sharing you will be presented with a crosshair cursor and you will need to click the screen you want to share. When using ''wofi'' or ''bemenu'', you will be presented with a menu of available displays to share. If no choosers are available, {{ic|xdg-desktop-portal-wlr}} will fallback to the first monitor found. For more information, see {{man|5|xdg-desktop-portal-wlr|SCREENCAST OPTIONS}}.<br />
<br />
== See also ==<br />
<br />
* [https://flatpak.github.io/xdg-desktop-portal/ Portal Documentation]: Lists all APIs applications and backends can implement.</div>Progandyhttps://wiki.archlinux.org/index.php?title=XDG_Desktop_Portal&diff=790543XDG Desktop Portal2023-10-20T17:59:46Z<p>Progandy: /* Troubleshooting */ Add out of date note for xdg-desktop-portal changes adding a new configuration file.</p>
<hr />
<div>{{Template:Related articles start}}<br />
{{Template:Related|Flatpak}}<br />
{{Template:Related|PipeWire#WebRTC screen sharing}}<br />
{{Template:Related articles end}}<br />
[[Category:Freedesktop.org]]<br />
[[ja:XDG デスクトップ ポータル]]<br />
<br />
{{Move|xdg-desktop-portal|{{ic|xdg-desktop-portal}} is the official name of the project.}}<br />
<br />
From the [https://docs.flatpak.org/en/latest/desktop-integration.html#portals Flatpak documentation]:<br />
<br />
:Portals are the framework for securely accessing resources from outside an application sandbox. They provide a range of common features to applications, including: Determining network status, opening a file with a file chooser, opening URIs, taking screenshots and screencasts [...]<br />
<br />
Portals were designed for use with applications sandboxed through [[Flatpak]], but any application can use portals to provide uniform access to features independent of desktops and toolkits. This is commonly used, for example, to [[PipeWire#WebRTC screen sharing|allow screen sharing]] on [[Wayland]] via [[PipeWire]], or to [[Firefox#KDE integration|use file open and save dialogs]] on [[Firefox]] that use the same toolkit as your current [[desktop environment]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|xdg-desktop-portal}} and one or more [[#Backends|backends]]. The package includes a [[systemd/User]] service that will be automatically started via [[D-Bus]].<br />
<br />
== Backends ==<br />
<br />
When an application makes a request through a portal, it is handled by {{ic|xdg-desktop-portal}}, which then forwards it to a backend implementation. This allows a clean way to provide suitable user interfaces that fit into different desktop environments, and access environment-specific APIs for requests like showing notifications or recording the screen. Multiple backends can be installed: for example, a [[Sway]] user may use {{Pkg|xdg-desktop-portal-wlr}} for screen sharing support and {{Pkg|xdg-desktop-portal-gtk}} as a fallback for all other interfaces that ''xdg-desktop-portal-wlr'' does not implement.<br />
<br />
Portal backend definitions are located in {{ic|/usr/share/xdg-desktop-portal/portals/*.portal}}. Each portal backend file contains a list of interfaces that it can handle, and the desktop environments that it can be used in. When a request is made, {{ic|xdg-desktop-portal}} will use the {{ic|/usr/share/xdg-desktop-portal/''DE''-portals.conf}} file to determine which backend it will use for the request, where ''DE'' is based on the {{ic|XDG_CURRENT_DESKTOP}} [[environment variable]].<br />
<br />
Users may also create their own portal configuration file at {{ic|$XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf}} to determine which backends they want to use, either generally or for each individual interface. See {{Man|5|portals.conf}} for more information.<br />
<br />
=== List of backends and interfaces ===<br />
<br />
The following table lists all backends available and their support for certain common interfaces.<br />
<br />
{| class="wikitable"<br />
|-<br />
! Backend !! File chooser !! Screenshot and screen cast<br />
|-<br />
| {{Pkg|xdg-desktop-portal-dde}} || {{G|Yes}} || {{G|Yes, on [[Deepin Desktop Environment]]}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-gnome}} || {{G|Yes}} || {{G|Yes, on [[GNOME]]}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-gtk}} || {{Yes}} || {{No}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-kde}} || {{Yes}} || {{G|Yes, on [[KDE]]}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-hyprland}}<sup>1</sup> || {{No}} || {{G|Yes, on {{Pkg|wlroots}}}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-lxqt}} || {{Yes}} || {{No}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-wlr}} || {{No}} || {{G|Yes, on {{Pkg|wlroots}}}}<br />
|-<br />
| {{Pkg|xdg-desktop-portal-xapp}} || {{No}} || {{G|Yes, on [[Cinnamon]]}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-liri-git}} || {{Yes}} || {{G|Yes, on [[Liri]]}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-shana}} || {{Yes}}<sup>2</sup> || {{No}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-td}} || {{Yes}} || {{No}}<br />
|-<br />
| {{AUR|xdg-desktop-portal-termfilechooser-git}} || {{Yes}}<sup>3</sup> || {{No}}<br />
|-<br />
|}<br />
<br />
#works with all wlroots-based compositors, but provides extra functionality when used with [[Hyprland]] such as sharing individual windows.<br />
#redirects requests to GNOME/GTK/KDE/LXQt backends<br />
#allows using a [[List of applications/Utilities#Console|terminal file manager]] as a file chooser<br />
<br />
== Troubleshooting ==<br />
<br />
=== xdg-desktop-portal-wlr does not start automatically on sway ===<br />
<br />
{{Out of date|In addition to the configuration listed here, recent versions may also [[https://bbs.archlinux.org/viewtopic.php?id=289405 require the file {{ic|sway-portals.conf}}]]. }}<br />
<br />
For {{ic|xdg-desktop-portal-wlr}} to work, the {{ic|XDG_CURRENT_DESKTOP}} and {{ic|WAYLAND_DISPLAY}} environment variables have to be set in the [[Systemd/User#Environment variables|systemd user session]]. {{ic|XDG_CURRENT_DESKTOP}} has to be set to the name of your compositor, e.g. {{ic|1=XDG_CURRENT_DESKTOP=sway}}. {{ic|WAYLAND_DISPLAY}} is set automatically by the compositor.<br />
<br />
Check whether these variables are set with {{ic|systemctl --user show-environment}}. If they are not set, import these environment variables into the systemd user session and dbus by running the following commands after launching the compositor (e.g., include them in the compositor's configuration file).<br />
<br />
$ systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP<br />
$ dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=''compositor_name''<br />
<br />
{{Tip|[[Sway]] provides a drop-in file which does this automatically, see [[Sway#Configuration]].}}<br />
<br />
See [https://github.com/emersion/xdg-desktop-portal-wlr#running] and [https://github.com/emersion/xdg-desktop-portal-wlr/wiki] for more details.<br />
<br />
=== Using multiple monitors with xdg-desktop-portal-wlr ===<br />
<br />
{{ic|xdg-desktop-portal-wlr}} requires an external chooser to select the shared monitor. By default, it looks for {{Pkg|slurp}}, {{Pkg|wofi}} and {{Pkg|bemenu}} in this order. When using ''slurp'', after a request for screen sharing you will be presented with a crosshair cursor and you will need to click the screen you want to share. When using ''wofi'' or ''bemenu'', you will be presented with a menu of available displays to share. If no choosers are available, {{ic|xdg-desktop-portal-wlr}} will fallback to the first monitor found. For more information, see {{man|5|xdg-desktop-portal-wlr|SCREENCAST OPTIONS}}.<br />
<br />
== See also ==<br />
<br />
* [https://flatpak.github.io/xdg-desktop-portal/ Portal Documentation]: Lists all APIs applications and backends can implement.</div>Progandyhttps://wiki.archlinux.org/index.php?title=Firefox&diff=763730Firefox2023-01-10T22:35:26Z<p>Progandy: /* Hardware video acceleration */ media.hardware-video-decoding.force-enabled seems to be necessary</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Mozilla]]<br />
[[de:Firefox]]<br />
[[es:Firefox]]<br />
[[ja:Firefox]]<br />
[[ru:Firefox]]<br />
[[zh-hans:Firefox]]<br />
[[zh-hant:Firefox]]<br />
{{Related articles start}}<br />
{{Related|Firefox/Tweaks}}<br />
{{Related|Firefox/Profile on RAM}}<br />
{{Related|Firefox/Privacy}}<br />
{{Related|Browser extensions}}<br />
{{Related|Chromium}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
[https://www.mozilla.org/firefox Firefox] is a popular open source graphical web browser from [https://www.mozilla.org Mozilla].<br />
<br />
{{Note|For older versions, there may be no "Settings" but "Preferences" in their menus. You can replace "Settings" in the article with "Preferences" if need.}}<br />
<br />
== Installing ==<br />
<br />
Firefox can be [[install]]ed with the {{Pkg|firefox}} package.<br />
<br />
Other alternatives include:<br />
<br />
* {{App|Firefox Developer Edition|for developers|https://www.mozilla.org/firefox/developer/|{{Pkg|firefox-developer-edition}}}}<br />
* {{App|Firefox Extended Support Release|long-term supported version|https://www.mozilla.org/firefox/organizations/|{{AUR|firefox-esr}} or {{AUR|firefox-esr-bin}}}}<br />
* {{App|Firefox Beta|cutting-edge version|https://www.mozilla.org/firefox/channel/desktop/#beta|{{AUR|firefox-beta-bin}}}}<br />
* {{App|Firefox Nightly|nightly builds for testing ([https://developer.mozilla.org/Firefox/Experimental_features experimental features])|https://www.mozilla.org/firefox/channel/desktop/#nightly|{{AUR|firefox-nightly}}}} <br />
* {{App|Firefox KDE|Version of Firefox that incorporates an OpenSUSE patch for better [[#KDE integration|KDE integration]] than is possible through simple Firefox add-ons.|https://build.opensuse.org/package/show/mozilla:Factory/MozillaFirefox|{{AUR|firefox-kde-opensuse}}, {{AUR|firefox-kde}} or {{AUR|firefox-developer-edition-kde}}}}<br />
* On top of the different Mozilla build channels, a number of forks exist with more or less special features; see [[List of applications#Gecko-based]].<br />
<br />
A number of language packs are available for Firefox, other than the standard English. Language packs are usually named as {{ic|firefox-i18n-''languagecode''}} (where {{ic|''languagecode''}} can be any language code, such as '''de''', '''ja''', '''fr''', etc.). For a list of available language packs, see [https://archlinux.org/packages/extra/any/firefox-i18n/ firefox-i18n] for {{Pkg|firefox}}, [https://archlinux.org/packages/community/any/firefox-developer-edition-i18n/ firefox-developer-edition-i18n] for {{Pkg|firefox-developer-edition}} and [https://aur.archlinux.org/packages/?K=firefox-nightly- firefox-nightly-] for {{AUR|firefox-nightly}}.<br />
<br />
{{Note|1=Language packs are disabled on ''-nightly'' and ''-developer-edition'' due to frequent string changes that may cause crashes. To force a change to the UI language, you may need to set {{ic|intl.locale.requested}} in {{ic|about:config}} [https://www.reddit.com/r/firefox/comments/lx3dp9/how_to_change_interface_language/gpovlsp/?context=8&depth=9].}}<br />
<br />
== Add-ons ==<br />
<br />
Firefox is well known for its large library of add-ons which can be used to add new features or modify the behavior of existing features. Firefox's "Add-ons Manager" is used to manage installed add-ons or find new ones. <br />
<br />
For instructions on how to install add-ons and a list of add-ons, see [[Browser extensions]].<br />
<br />
=== Adding search engines ===<br />
<br />
Search engines may be added to Firefox by creating bookmarks:<br />
<br />
* Press the star on the address bar or {{ic|Ctrl+d}}.<br />
* Right click on the bookmark you have created, then press ''Edit Bookmark...''<br />
* Complete the ''URL'' field with search URLs. Complete the place of the query with {{ic|%s}}. Complete the ''Keyword'' field with user-defined characters. Like this:<br />
<br />
URL:<br />
https://duckduckgo.com/html/?q=%s<br />
Keyword:<br />
d<br />
<br />
{{Note|Older versions use "Location" instead of "URL".}}<br />
<br />
Searches are performed by pre-pending the search term with the keyword of the specified search engine: {{ic|d archwiki}} will query DuckDuckGo using the search term {{ic|archwiki}}<br />
<br />
Search engines may also be added to Firefox through add-on extensions; see [https://addons.mozilla.org/firefox/search-tools/ this page] for a list of available search tools and engines.<br />
<br />
A very extensive list of search engines can be found at the [https://mycroftproject.com/ Mycroft Project].<br />
<br />
==== firefox-extension-arch-search ====<br />
<br />
[[Install]] the {{AUR|firefox-extension-arch-search}} package to add Arch-specific searches (AUR, wiki, forum, packages, etc) to the Firefox search toolbar.<br />
<br />
== Plugins ==<br />
<br />
Support for all plugins, including Flash Player, was removed in Firefox 85.[https://support.mozilla.org/kb/npapi-plugins][https://support.mozilla.org/kb/end-support-adobe-flash]<br />
<br />
== Configuration ==<br />
<br />
Firefox exposes a number of configuration options. To examine them, enter in the Firefox address bar:<br />
<br />
about:config<br />
<br />
Once set, these affect the user's current profile, and may be synchronized across all devices via [https://www.mozilla.org/firefox/sync/ Firefox Sync]. Please note that only a subset of the {{ic|about:config}} entries are synchronized by this method, and the exact subset may be found by searching for {{ic|services.sync.prefs}} in {{ic|about:config}}. Additional preferences and third party preferences may be synchronized by creating new boolean entries prepending the value with [https://support.mozilla.org/en-US/kb/sync-custom-preferences services.sync.prefs.sync]. To synchronize the whitelist for the extension [https://addons.mozilla.org/firefox/addon/noscript/ NoScript]:<br />
<br />
services.sync.prefs.sync.capability.policy.maonoscript.sites<br />
<br />
The boolean {{ic|noscript.sync.enabled}} must be set to {{ic|true}} to synchronize the remainder of NoScript's preferences via Firefox Sync.<br />
<br />
=== Settings storage ===<br />
<br />
Firefox stores the configuration for a profile via a {{ic|prefs.js}} in the profile folder, usually {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/}}. <br />
<br />
Firefox also allows configuration for a profile via a {{ic|user.js}} file: [http://kb.mozillazine.org/User.js_file user.js] kept also in the profile folder. A {{ic|user.js}} configuration supersedes a {{ic|prefs.js}}. The {{ic|user.js}} configuration is only parsed at start-up of a profile. Hence, you can test changes via {{ic|about:config}} and modify {{ic|user.js}} at runtime accordingly. For a useful starting point, see e.g [https://github.com/pyllyukko/user.js custom user.js] which is targeted at privacy/security conscious users.<br />
<br />
One drawback of the above approach is that it is not applied system-wide. Furthermore, this is not useful as a "pre-configuration", since the profile directory is created after first launch of the browser. You can, however, let ''firefox'' create a new profile and, after closing it again, [https://support.mozilla.org/en-US/kb/back-and-restore-information-firefox-profiles#w_restoring-a-profile-backup copy the contents] of an already created profile folder into it. <br />
<br />
Sometimes, it may be desired to lock certain settings, a feature useful in widespread deployments of customized Firefox. In order to create a system-wide configuration, follow the steps outlined in [https://support.mozilla.org/en-US/kb/customizing-firefox-using-autoconfig Customizing Firefox Using AutoConfig]:<br />
<br />
1. Create {{ic|/usr/lib/firefox/defaults/pref/autoconfig.js}}:<br />
<br />
pref("general.config.filename", "firefox.cfg");<br />
pref("general.config.obscure_value", 0);<br />
<br />
2. Create {{ic|/usr/lib/firefox/firefox.cfg}} (this stores the actual configuration):<br />
<br />
//<br />
//...your settings...<br />
// e.g to disable Pocket, uncomment the following lines<br />
// lockPref("extensions.pocket.enabled", false);<br />
// lockPref("browser.newtabpage.activity-stream.feeds.section.topstories", false);<br />
<br />
Please note that the first line must contain exactly {{ic|//}}. The syntax of the file is similar to that of {{ic|user.js}}.<br />
<br />
=== Multimedia playback ===<br />
<br />
Firefox uses [[FFmpeg]] for playing multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. Go to [https://cconcolato.github.io/media-mime-support/ video-test page] or [https://hpr.dogphilosophy.net/test/ audio-test page] to check which formats are actually supported.<br />
<br />
Firefox uses [[PulseAudio]] for audio playback and capture. If PulseAudio is not installed, Firefox uses [[ALSA]] instead.<br />
<br />
{{Tip|Firefox might not play video if audio is not configured. If you are intending to use [[PipeWire]] and [[WirePlumber]], make sure they are working properly.}}<br />
<br />
==== HTML5 DRM/Widevine ====<br />
<br />
Widevine is a digital rights management tool that Netflix, Amazon Prime Video, and others use to protect their video content. It can be enabled in ''Settings > General > Digital Rights Management (DRM) Content''. If you visit a Widevine-enabled page when this setting is disabled, Firefox will display a prompt below the address bar asking for permission to install DRM. Approve this and then wait for the "Downloading" bar to disappear; now, you are able to watch videos from Widevine protected sites. <br />
<br />
Firefox can only play 720p video (or lower) with Widevine, due to not using [https://bugzilla.mozilla.org/show_bug.cgi?id=1700815 hardware DRM playback]. It is also required that the private mode browsing is disabled, for the window and in the Settings.<br />
<br />
==== "Open With" extension ====<br />
<br />
# Install [https://addons.mozilla.org/firefox/addon/open-with/ Open With] add-on.<br />
# Go to ''Add-ons > Open With > Preferences''.<br />
# Proceed with instructions to install a file in your system and test the installation. <br />
# Click ''Add browser''.<br />
# In the dialog, write a name for this menu entry and command to start a video streaming capable player (e.g. {{ic|/usr/bin/mpv}}).<br />
## Optionally, add needed arguments to the player (e.g. you may want {{ic|--force-window --ytdl}} for [[mpv]]).<br />
# Right click on links or visit pages containing videos. Select newly created entry from Open With's menu and if the site is supported, the player will open as expected.<br />
<br />
The same procedure can be used to associate video downloaders such as ''youtube-dl''.<br />
<br />
==== Hardware video acceleration ====<br />
<br />
[[Hardware video acceleration]] via VA-API is available under [[Wayland]] [https://mastransky.wordpress.com/2020/06/03/firefox-on-fedora-finally-gets-va-api-on-wayland/] and [[Xorg]] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619523] [https://www.phoronix.com/scan.php?page=news_item&px=Firefox-80-VA-API-X11].<br />
<br />
To enable VA-API in Firefox:<br />
<br />
# Ensure that your video card is correctly configured for VA-API as described in [[Hardware video acceleration]].<br />
# Ensure WebRender is enabled by navigating to {{ic|about:support}} and then ''Compositing''. It is enabled by default in GNOME and other desktop environments [https://mastransky.wordpress.com/2021/01/10/firefox-were-finally-getting-hw-acceleration-on-linux/]. <br />
#* Ensure you are not running Software WebRender as that will not work as of August 2021 [https://bugzilla.mozilla.org/show_bug.cgi?id=1723540#c1]. <br />
#* If necessary, Hardware WebRender can be force enabled by setting {{ic|gfx.webrender.all}} to {{ic|true}}.<br />
# Set {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|true}} in {{ic|about:config}}<br />
# Set {{ic|media.hardware-video-decoding.force-enabled}} to {{ic|true}} in {{ic|about:config}}<br />
# If using [[Wayland]], run Firefox with [[#Wayland|Wayland mode]] enabled.<br />
<br />
{{Note|1=<nowiki/><br />
* While NVIDIA's proprietary driver does not support VA-API, newer versions support DMA-BUF. Using {{AUR|libva-nvidia-driver}} will allow for hardware video decoding on NVIDIA using [[CUDA]]. See the [https://github.com/elFarto/nvidia-vaapi-driver/#firefox GitHub project] for documentation on necessary environment variables and about:config changes.<br />
* Since currently there is no DMA-BUF support for [[VDPAU]] nor {{Pkg|libva-vdpau-driver}}, this package will not enable hardware video acceleration in Firefox. In fact, as of Firefox 102, having this installed and {{ic|media.ffmpeg.vaapi.enabled}} set will make Firefox crash on startup.<br />
* Currently, Firefox's VA-API implementation can decode H.264/AVC, VP8 & VP9, AV1 encoded video. AV1 support requires FireFox 98+ [https://bugzilla.mozilla.org/show_bug.cgi?id=1745225].<br />
* Multi-GPU systems should automatically choose a suitable GPU for VA-API according to this [https://bugzilla.mozilla.org/show_bug.cgi?id=1588904#c36 solved issue].<br />
* [[AMDGPU]] users under {{Pkg|linux-hardened}} may need to rebuild ''linux-hardened'' with {{ic|1=CONFIG_CHECKPOINT_RESTORE=y}} due to {{Pkg|mesa}} [https://gitweb.gentoo.org/repo/gentoo.git/tree/media-libs/mesa/mesa-9999.ebuild requiring the kcmp syscall]. This may no longer be necessary due to this [https://bugzilla.mozilla.org/show_bug.cgi?id=1624743 bug being solved].<br />
}}<br />
<br />
VA-API usage can be verified by checking Firefox's VA-API logs. Run Firefox with the {{ic|1=MOZ_LOG="PlatformDecoderModule:5"}} environment variable and check in the log output that VA-API is enabled and used (search for the "VA-API" string) when playing a video for example. Pay attention to these logs as they might indicate that only one of the two possible compositors described before (WebRender or OpenGL) works with VA-API on your particular setup.<br />
<br />
{{Tip|<br />
* To allow hardware decoding in YouTube, the video codec used must be supported by the hardware. The profiles supported by your GPU can be checked with [[Hardware video acceleration#Verifying VA-API]] and the YouTube codecs used can ''sometimes'' (if offered by YouTube!) be controlled with the [https://addons.mozilla.org/firefox/addon/h264ify/ h264ify] or [https://addons.mozilla.org/firefox/addon/enhanced-h264ify/ enhanced-h264ify] extensions. Alternatively, you can install {{AUR|firefox-h264ify}}.<br />
}}<br />
<br />
=== Spell checking ===<br />
<br />
Firefox can use system-wide installed [[Hunspell]] dictionaries as well as dictionaries installed through its own extension system.<br />
<br />
To enable spell checking for a specific language, right click on any text field and check the ''Check Spelling'' box. To select a language for spell checking, you have to right click again and select your language from the ''Languages'' sub-menu.<br />
<br />
If your default language choice does not stick, see [[#Firefox does not remember default spell check language]].<br />
<br />
==== System-wide Hunspell dictionaries ====<br />
<br />
Install [[Hunspell]] and its dictionaries for the languages you require.<br />
<br />
==== Dictionaries as extensions ====<br />
<br />
To get more languages, right click on any text field, click ''Add Dictionaries...'' and select the dictionary you want to install from the [https://addons.mozilla.org/firefox/language-tools/ Dictionaries and Language Packs list].<br />
<br />
{{Tip|For Russian, the extension is packaged as {{Pkg|firefox-spell-ru}}.}}<br />
<br />
=== KDE integration ===<br />
<br />
* To bring the [[KDE]] look to GTK applications (including Firefox), install {{Pkg|breeze-gtk}} and {{Pkg|kde-gtk-config}}. Afterwards, go to System Settings and in ''Appearance > Application Style > Configure GNOME/GTK Application Style…'' choose 'Breeze'.<br />
* To use the KDE file selection and print dialogs in Firefox 64 or newer, install {{Pkg|xdg-desktop-portal}} and {{Pkg|xdg-desktop-portal-kde}}, then do one of the following:<br />
** Set {{ic|widget.use-xdg-desktop-portal.mime-handler}} to {{ic|1}} in {{ic|about:config}}. You should also change {{ic|widget.use-xdg-desktop-portal.file-picker}} from {{ic|2}} to {{ic|1}}.<br />
** Launch firefox with {{ic|1=GTK_USE_PORTAL=1}} [[environment variable]].<br />
* For integration with [[KDE]] MIME type system, proxy and file dialog, one can use {{AUR|firefox-kde-opensuse}} variant from AUR with OpenSUSE’s patches applied. Alternatively, integration with MIME types can be achieved by creating a symbolic link to the MIME database {{ic|~/.config/mimeapps.list}} from the deprecated {{ic|~/.local/share/applications/mimeapps.list}} that is used by Firefox. See [[XDG MIME Applications#mimeapps.list]].<br />
* Extensions/add-ons may provide additional integration, such as:<br />
** Browser integration in [[Plasma]]: requires {{Pkg|plasma-browser-integration}} and the [https://addons.mozilla.org/firefox/addon/plasma-integration/ Plasma Integration add-on].<br />
::{{Tip|To prevent duplicate entries in the Media Player widget or tray icon, set {{ic|media.hardwaremediakeys.enabled}} to {{ic|false}}. This disables the media entry from Firefox and only uses the one from the Plasma integration add-on.}}<br />
<br />
=== Listen (text to speech) ===<br />
<br />
Firefox can perform Text to Speech synthesis for web pages.<br />
<br />
==== Setup ====<br />
<br />
{{Merge|Speech Dispatcher|2=Speech Dispatcher is used for more than just Firefox.[https://bbs.archlinux.org/viewtopic.php?id=243537] A dedicated page might be in order.}}<br />
<br />
{{Expansion|It should be possible to write a systemd service for running Festival in the background.}}<br />
<br />
TTS must be setup for the ''Listen'' icon to appear in the Reader view. Firefox uses [https://github.com/brailcom/speechd Speech Dispatcher] ([https://htmlpreview.github.io/?https://github.com/brailcom/speechd/blob/master/doc/speech-dispatcher.html#Recommended-installation-procedure Speech Dispatcher documentation]) which requires a speech synthesis engine. The currently recommended speech synthesis engine is [[Festival]].<br />
<br />
# [[Festival#Installation|Install Festival]] then [[Festival#Configuration|configure and test it]].<br />
# Install {{AUR|festival-freebsoft-utils}} (required to use Festival with Speech Dispatcher)<br />
# Install the package {{Pkg|speech-dispatcher}} then [[textedit|edit]] {{ic|/etc/speech-dispatcher/speechd.conf}} and uncomment the line that starts with {{ic|AddModule "festival"}}<br />
# Start Festival as a server: {{ic|festival --server}}<br />
# You should now be able to test Speech Dispatcher: {{ic|spd-conf -s}}<br />
<br />
==== Usage ====<br />
<br />
See the [https://support.mozilla.org/en-US/kb/firefox-reader-view-clutter-free-web-pages illustrated steps] on Mozilla's website.<br />
<br />
The ''Listen'' icon (a headphones icon) will only appear if you have performed all the configuration above, Speech Dispatcher is working, and you have started Firefox after you started the Festival server (you cannot start Firefox then Festival).<br />
<br />
Furthermore, sometimes a Festival server process may linger after you have tried to kill it, but will terminate after you shut down Firefox.<br />
<br />
For common issues, see [[#Web Speech API has no voices]] and [[#Narrate/Listen icon missing in Reader Mode]].<br />
<br />
==== Using the festival-us voices ====<br />
<br />
The voices in the package {{Pkg|festival-us}} provide better quality audio than those in {{Pkg|festival-english}} but they do not work in Firefox. They do not appear in the list of available voices in Firefox and when you open Reader view you will see error messages like this in the terminal output from the Festival server:<br />
<br />
{{bc| SIOD: unknown voice cmu_us_awb_cg }}<br />
<br />
To fix this you need to [[textedit|edit]] the following files:<br />
<br />
* {{ic|/usr/share/festival/voices/us/cmu_us_awb_cg/festvox/cmu_us_awb_cg.scm}}<br />
* {{ic|/usr/share/festival/voices/us/cmu_us_rms_cg/festvox/cmu_us_rms_cg.scm}}<br />
* {{ic|/usr/share/festival/voices/us/cmu_us_slt_cg/festvox/cmu_us_slt_cg.scm}}<br />
<br />
For each of these files you need to add some code to the second last line of code of each file, eg for {{ic|cmu_us_awb_cg.scm}} add code before this line:<br />
{{bc|(provide 'cmu_us_awb_cg)}}<br />
<br />
The code you need to add to {{ic|cmu_us_awb_cg.scm}} is below. You will need to change the voice name, gender, dialect and description as appropriate for the other two files.<br />
{{bc|<br />
(proclaim_voice<br />
'cmu_us_awb_cg<br />
'((language english)<br />
(gender male)<br />
(dialect scottish)<br />
(description "This voice is Scottish")))<br />
}}<br />
<br />
{{Note|To avoid re-doing those changes every time {{Pkg|festival-us}} is upgraded, see [[pacman#Skip file from being upgraded]].}}<br />
<br />
== Tips and tricks ==<br />
<br />
For general enhancements, see [[Firefox/Tweaks]], and for privacy related enhancements, see [[Firefox/Privacy]].<br />
<br />
=== Dark themes ===<br />
<br />
Firefox should respect your GTK theme settings and your OS-wide dark appearance settings (as in the Appearance section of GNOME's settings or KDE system settings). If the latter does not work, make sure to have a suitable {{Pkg|xdg-desktop-portal}} package installed.<br />
<br />
Starting with Firefox 68, you can make all the Firefox interfaces and even other websites respect dark themes, irrespective of the system GTK theme and Firefox theme. To do this, set {{ic|ui.systemUsesDarkTheme}} to {{ic|1}} in {{ic|about:config}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1488384#c23].<br />
<br />
As of Firefox 100, further control of the dark theme of web pages that opt-in (using the CSS media query [https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme prefers-color-scheme]) and Firefox's own in-content pages is possible with {{ic|layout.css.prefers-color-scheme.content-override}}. Setting this to {{ic|3}} will follow the browser theme, setting this to {{ic|2}} will follow the system wide dark-mode preference ({{ic|ui.systemUsesDarkTheme}} as above, which defaults to {{ic|0}} if the user has not changed the dark-mode preference or if a system does not support a system-wide dark-mode preference), while {{ic|1}} and {{ic|0}} will always force light-mode and dark-mode respectively. This setting can also be accessed through the user settings of Firefox under ''General'' > ''Language and Appearance'' > ''Website appearance''.<br />
<br />
=== Frame rate ===<br />
<br />
If Firefox is unable to automatically detect the right value, it will default to 60 fps. To manually correct this, set {{ic|layout.frame_rate}} to the refresh rate of your monitor (e.g. 144 for 144 Hz).<br />
<br />
=== Memory limit ===<br />
<br />
To prevent pages from abusing memory (and possible [[Wikipedia:Out_of_memory|OOM]]), we can use [[Firejail]] with the {{ic|rlimit-as}} option.<br />
<br />
=== New tabs position ===<br />
<br />
To control where new tabs appears (relative or absolute), use {{ic|browser.tabs.insertAfterCurrent}} and {{ic|browser.tabs.insertRelatedAfterCurrent}}. See [https://support.mozilla.org/en/questions/1229062] for more information.<br />
<br />
=== Screenshot of webpage ===<br />
<br />
You can ''Take a Screenshot'' by either using the screenshots button that can be added to the toolbar from the customize screen in the Hamburger menu at ''More tools'' > ''Customize toolbar'', by pressing {{ic|Ctrl+Shift+s}} or by right-clicking on the webpage. See [https://support.mozilla.org/en-US/kb/firefox-screenshots] for more information.<br />
<br />
As an alternative, you can use the screenshot button in the developer tools, which can be added through the developer tools ''Settings'' menu, under the ''Available Toolbox Buttons'' section. The settings for the developer tools are accessible through the three horizontal dots located at the top right of the developer tools pane.<br />
<br />
=== Wayland ===<br />
<br />
More recent versions of Firefox support opting into [[Wayland]] mode via an [[environment variable]].<br />
<br />
$ MOZ_ENABLE_WAYLAND=1 firefox<br />
<br />
To make this permanent, see [[Environment variables#Graphical environment]] and start Firefox via the desktop launcher like you normally would.<br />
<br />
To verify that it worked, look for ''Window Protocol'' in {{ic|about:support}}. It should say {{ic|wayland}}. The presence of {{ic|x11}} means you are running Firefox under [[Xorg]] display server, while {{ic|xwayland}} means your system is running Wayland but executing Firefox as legacy X11 application. <br />
<br />
If it is necessary to be regularly switching between Wayland and X.org, it may be useful to add a conditional to your shell's login [[Command-line shell#Configuration files|startup script]], e.g. {{ic|~/.bash_profile}} for [[Bash]]:<br />
<br />
{{bc|1=<br />
if [ "$XDG_SESSION_TYPE" == "wayland" ]; then<br />
export MOZ_ENABLE_WAYLAND=1<br />
fi<br />
}}<br />
<br />
=== Window manager rules ===<br />
<br />
To apply different configurations to Firefox windows, change the WM_CLASS string by using Firefox's {{ic|--class}} option, to a custom one.<br />
<br />
=== Profiles ===<br />
<br />
To start new Firefox instances, multiple profiles are required. To create a new profile:<br />
<br />
$ firefox [--new-instance] -P<br />
<br />
Class can be specified when launching Firefox with a not-in-use profile:<br />
<br />
$ firefox [--new-instance] -P ''profile_name'' --class=''class_name''<br />
<br />
[https://ffprofile.com/ Firefox Profilemaker] can be used to create a Firefox profile with the defaults you like.<br />
<br />
=== Touchscreen gestures and pixel-perfect trackpad scrolling ===<br />
<br />
{{Merge|Firefox/Tweaks#Enable touchscreen gestures|Same solution.}}<br />
<br />
To enable touch gestures (like scrolling and pinch-to-zoom) and one-to-one trackpad scrolling (as can be witnessed with GTK3 applications like Nautilus), set the {{ic|1=MOZ_USE_XINPUT2=1}} [[environment variable]] before starting Firefox. On Wayland, only {{ic|1=MOZ_ENABLE_WAYLAND=1}} needs to be set.<br />
<br />
Kinetic scrolling feels loose on Wayland due to https://bugzilla.mozilla.org/show_bug.cgi?id=1568722, and can be turned off by going to {{ic|about:config}} and turning off {{ic|apz.gtk.kinetic_scroll.enabled}}. This will make it harder to scroll to the beginning and end of long pages, however.<br />
<br />
=== Multiple home pages ===<br />
<br />
To have multiple tabs opened when starting Firefox, open a new window and then open the sites you want to have as "home tabs".<br />
<br />
Now go to ''Settings > Home'' and under ''Homepage and new windows'' click the ''Use Current Pages'' button.<br />
<br />
Alternatively, go directly to ''Settings > Home'' and now under ''Homepage and new windows'' set the first field to ''Custom URLs..'' and enter the pages you want as new home pages in the following format:<br />
<br />
<nowiki>https://url1.com|https://url2.com|https://url3.com</nowiki><br />
<br />
=== View two pages side by side in the PDF viewer ===<br />
<br />
To display two pages at once with the integrated PDF viewer, set {{ic|pdfjs.spreadModeOnLoad}} to {{ic|1}} in in {{ic|about:config}}.<br />
<br />
=== Kiosk mode ===<br />
<br />
Firefox supports kiosk mode that shows pages in full screen without browser chrome, context menus, and other features useful for typical desktop browsing. These can be seen on ATMs or information panels where users are not expected to interact with the rest of the system.<br />
<br />
To use kiosk mode, start Firefox with:<br />
<br />
$ firefox --kiosk ''url''<br />
<br />
The startup page can be configured the settings or supplied as a command-line parameter.<br />
<br />
If you need printing, you can prevent Firefox from showing paper size configuration dialogs with:<br />
<br />
$ firefox --kiosk --kiosk-printing ''url''<br />
<br />
=== Compact mode ===<br />
<br />
Starting with Firefox version 89, the compact mode density option was removed from the Customize panel [https://support.mozilla.org/en-US/kb/compact-mode-workaround-firefox], but you can still use compact density. To do this, set {{ic|browser.uidensity}} to {{ic|1}} in {{ic|about:config}}.<br />
<br />
=== GNOME search provider ===<br />
<br />
Firefox includes a search provider for GNOME Shell which exposes Firefox bookmarks and history to GNOME Shell search while Firefox is running. To enable this provider go to {{ic|about:config}} and set {{ic|browser.gnome-search-provider.enabled}} to {{ic|true}}.<br />
<br />
Then, you must install {{AUR|firefox-gnome-search-provider}} to add the required GNOME configuration file; {{Pkg|firefox}} itself currently does not include it (see {{Bug|68705}}).<br />
<br />
== Troubleshooting ==<br />
<br />
=== Troubleshoot Mode ===<br />
<br />
The command line switch {{ic|-safe-mode}} starts Firefox in [https://support.mozilla.org/en-US/kb/diagnose-firefox-issues-using-troubleshoot-mode Troubleshoot Mode], which disables extensions, themes, hardware acceleration, the JIT and some other features for this session.<br />
<br />
This mode can also be enabled by pressing on the hamburger menu while Firefox is open, clicking ''Help'', selecting ''Troubleshoot Mode'' and confirming this on the modal dialog that appears. Please note this will require a browser restart.<br />
<br />
This mode was previously named Safe Mode until Firefox 88.<br />
<br />
=== Firefox refresh ===<br />
<br />
Some issues experienced by users in Firefox may be caused by profile issues, such as corruption.<br />
<br />
If you have ruled out other causes, it may be worth trying a new Firefox profile for testing purposes to see if this will resolve your issue. More information on how to create a new profile and switch between profiles can be found on the [https://support.mozilla.org/en-US/kb/profile-manager-create-remove-switch-firefox-profiles Firefox support page].<br />
<br />
If this resolves your issue, you should switch back to your original profile and consider refreshing your Firefox. <br />
<br />
Refreshing your profile will retain all browsing and download history, bookmarks, web form auto-fill data, cookies, personal dictionary and passwords, and will transfer them to a brand new profile without extensions, themes, extension data and preferences, among other data. A backup of your old profile will also be retained.<br />
<br />
To refresh your profile, navigate to {{ic|about:support}}, press ''Refresh Firefox'' and confirm this on the modal dialog that appears. {{ic|about:support}} can also be accessed by pressing the Hamburger menu, selecting ''Help'' and then clicking ''More troubleshooting information''.<br />
<br />
More information on refreshing your Firefox, including further details about what is transferred to the new profile, can be found on the [https://support.mozilla.org/en-US/kb/refresh-firefox-reset-add-ons-and-settings Firefox support page].<br />
<br />
=== Hardware video acceleration issues ===<br />
<br />
If you are having issues with hardware video acceleration in Firefox, e.g. in case of freezes or graphical corruption, start Firefox in [[#Troubleshoot Mode|Troubleshoot Mode]] for testing purposes to confirm that this is the issue. If this step resolves the issue, merely set {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|false}} in {{ic|about:config}} to disable hardware video acceleration, and restart Firefox.<br />
<br />
=== Extension X does not work on some Mozilla owned domains ===<br />
<br />
By default, extensions will not affect pages designated by {{ic|extensions.webextensions.restrictedDomains}}. If this is not desired, this field can be cleared (special pages such as {{ic|about:*}} will not be affected). Then create and set {{ic|privacy.resistFingerprinting.block_mozAddonManager}} to true.<br />
<br />
=== Firefox startup takes very long ===<br />
<br />
If Firefox takes much longer to start up than other browsers, it may be due to lacking configuration of the localhost in {{ic|/etc/hosts}}. See [[Network configuration#Local network hostname resolution]] on how to set it up.<br />
<br />
Misbehaving Firefox extensions, or too many extensions, may be another source of slow startup. This can be confirmed through the use of [[#Troubleshoot Mode|Troubleshoot Mode]], which will disable extensions on restart. <br />
<br />
A further cause of slow start-up may be a profile issue, such as corruption. For more troubleshooting steps around your Firefox profile, see [[#Firefox refresh]].<br />
<br />
=== Font troubleshooting ===<br />
<br />
See [[Font configuration]].<br />
<br />
Firefox has a setting which determines how many replacements it will allow from Fontconfig. To allow it to use all your replacement rules, change {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|127}} (the highest possible value).<br />
<br />
Firefox ships with the ''Twemoji Mozilla'' font. To use the system emoji font, set {{ic|font.name-list.emoji}} to {{ic|emoji}} in {{ic|about:config}}. Additionally, to prevent the Mozilla font interfering with your system emoji font, change {{ic|gfx.font_rendering.opentype_svg.enabled}} to {{ic|false}} or remove {{ic|/usr/lib/firefox/fonts/TwemojiMozilla.ttf}} (see also [[pacman#Skip files from being installed to system]]).<br />
<br />
=== Setting an email client ===<br />
<br />
Inside the browser, {{ic|mailto}} links by default are opened by a web application such as Gmail or Yahoo Mail. To set an external email program, go to ''Settings > General > Applications'' and modify the ''action'' corresponding to the {{ic|mailto}} content type; the file path will need to be designated (e.g. {{ic|/usr/bin/kmail}} for Kmail).<br />
<br />
Outside the browser, {{ic|mailto}} links are handled by the {{ic|x-scheme-handler/mailto}} mime type, which can be easily configured with [[xdg-mime]]. See [[Default applications]] for details and alternatives.<br />
<br />
=== File association ===<br />
<br />
See [[Default applications]].<br />
<br />
=== Firefox keeps creating ~/Desktop even when this is not desired ===<br />
<br />
Firefox uses {{ic|~/Desktop}} as the default place for download and upload files. To change it to another folder, set the {{ic|XDG_DESKTOP_DIR}} option as explained in [[XDG user directories]].<br />
<br />
=== Changes to userChrome.css and userContent.css are ignored ===<br />
<br />
Set {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|true}} in {{ic|about:config}}<br />
<br />
=== Middle-click behavior ===<br />
<br />
To use the middle mouse button to paste whatever text has been highlighted/added to the clipboard, as is common in UNIX-like operating systems, set either {{ic|middlemouse.contentLoadURL}} or {{ic|middlemouse.paste}} to {{ic|true}} in {{ic|about:config}}. Having {{ic|middlemouse.contentLoadURL}} enabled was the default behaviour prior to Firefox 57.<br />
<br />
To scroll on middle-click (default for Windows browsers), set {{ic|general.autoScroll}} to {{ic|true}}.<br />
<br />
=== Backspace does not work as the 'Back' button ===<br />
<br />
According to [http://kb.mozillazine.org/Browser.backspace_action MozillaZine], the {{ic|Backspace}} key was mapped based on which platform the browser was running on. As a compromise, this preference was created to allow the {{ic|Backspace}} key to either go back/forward, scroll up/down a page, or do nothing.<br />
<br />
To make {{ic|Backspace}} go back one page in the tab's history and {{ic|Shift+Backspace}} go forward, set {{ic|browser.backspace_action}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
To have the {{ic|Backspace}} key scroll up one page and {{ic|Shift+Backspace}} scroll down one page, set {{ic|browser.backspace_action}} to {{ic|1}}. Setting this property to any other value will leave the key unmapped (Arch Linux defaults to {{ic|2}}; in other words, it is unmapped by default).<br />
<br />
=== Firefox does not remember login information ===<br />
<br />
It may be due to a corrupted {{ic|cookies.sqlite}} file in [https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data Firefox's profile] folder. In order to fix this, just rename or remove {{ic|cookie.sqlite}} while Firefox is not running.<br />
<br />
Open a terminal of choice and type the following:<br />
<br />
$ rm -f ~/.mozilla/firefox/<profile id>.default/cookies.sqlite<br />
<br />
The profile id is a random 8 character string.<br />
<br />
Restart Firefox and see if it solved the problem.<br />
<br />
If it did not work, check if there exists a {{ic|cookies.sqlite.bak}} file that you could use to manually restore the cookies.<br />
<br />
=== Cannot enter/leave fullscreen ===<br />
<br />
If Firefox detects an [https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html EWMH/ICCCM] compliant window manager, it will try to send a WM_STATE message to the root window to request Firefox be made to enter (or leave) full-screen mode (as defined by the window manager). Window managers are allowed to ignore it, but if they do, Firefox will assume the request got denied and propagate it to the end user which results in nothing happening. This may result in not being able to full screen a video. A general workaround is to set the {{ic|full-screen-api.ignore-widgets}} to {{ic|true}} in {{ic|about:config}}. <br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=1189622 Bugzilla 1189622].<br />
<br />
=== JavaScript context menu does not appear on some sites ===<br />
<br />
You can try setting {{ic|dom.w3c_touch_events.enabled}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
=== Firefox does not remember default spell check language ===<br />
<br />
The default spell checking language can be set as follows:<br />
<br />
# Type {{ic|about:config}} in the address bar.<br />
# Set {{ic|spellchecker.dictionary}} to your language of choice, for instance {{ic|en_GB}}.<br />
# Notice that the for dictionaries installed as a Firefox plugin the notation is {{ic|en-GB}}, and for {{Pkg|hunspell}} dictionaries the notation is {{ic|en_GB}}.<br />
<br />
When you only have system wide dictionaries installed with {{Pkg|hunspell}}, Firefox might not remember your default dictionary language settings. This can be fixed by having at least one [https://addons.mozilla.org/firefox/language-tools/ dictionary] installed as a Firefox plugin. Notice that now you will also have a tab ''Dictionaries'' in ''Add-ons''. You may have to change the order of ''preferred language for displaying pages'' in {{ic|about:preferences#general}} to make the spell check default to the language of the addon dictionary.<br />
<br />
Related questions on the '''StackExchange''' platform: [https://stackoverflow.com/questions/26936792/change-firefox-spell-check-default-language/29446115], [https://stackoverflow.com/questions/21542515/change-default-language-on-firefox/29446353], [https://askubuntu.com/questions/184300/how-can-i-change-firefoxs-default-dictionary/576877]<br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=776028 Bugzilla 776028], [https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/1026869 Ubuntu bug 1026869]<br />
<br />
=== Some MathML symbols are missing ===<br />
<br />
You need some Math fonts, namely Latin Modern Math and STIX (see this MDN page: [https://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts#Linux]), to display MathML correctly.<br />
<br />
In Arch Linux, these fonts are provided by {{Pkg|texlive-core}} '''and''' {{Pkg|texlive-fontsextra}}, but they are not available to fontconfig by default. See [[TeX Live#Making fonts available to Fontconfig]] for details. You can also try other [[Fonts#Math|Math fonts]]. In case you encounter this bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1208776], installing {{Pkg|otf-latinmodern-math}} can help.<br />
<br />
=== Videos load but do not play ===<br />
<br />
This may be a PulseAudio issue. See the suggested fix in [[PulseAudio/Troubleshooting#Browsers load videos but do no play]].<br />
<br />
=== Tearing when scrolling ===<br />
<br />
Try disabling smooth scrolling in ''Settings > General >Browsing''.<br />
<br />
=== Firefox WebRTC module cannot detect a microphone ===<br />
<br />
WebRTC applications for instance [https://mozilla.github.io/webrtc-landing/gum_test.html Firefox WebRTC getUserMedia test page] say that microphone cannot be found. Issue is reproducible for both ALSA or PulseAudio setup. Firefox debug logs show the following error:<br />
<br />
{{hc|1=$ NSPR_LOG_MODULES=MediaManager:5,GetUserMedia:5 firefox|2=<br />
...<br />
[Unnamed thread 0x7fd7c0654340]: D/GetUserMedia VoEHardware:GetRecordingDeviceName: Failed 1<br />
}}<br />
<br />
You can try setting {{ic|media.navigator.audio.full_duplex}} property to {{ic|false}} at {{ic|about:config}} Firefox page and restart Firefox.<br />
<br />
This can also help if you are using the PulseAudio [[PulseAudio#Microphone echo/noise cancellation|module-echo-cancel]] and Firefox does not recognise the virtual echo canceling source.<br />
<br />
=== WebRTC sharing indicator displays an XML parsing error ===<br />
<br />
After agreeing to share a microphone or web camera, you may then see a window with a tan background and a red border in the top left corner on your primary window, displaying the following error message:<br />
<br />
XML Parsing Error: no root element found<br />
Location: chrome://browser/content/webrtcLegacyIndicator.xhtml<br />
Line Number: 1, Column 1:<br />
^<br />
<br />
If this is the case for you, performing the following steps should resolve the issue:<br />
<br />
# Navigate to {{ic|about:support}}.<br />
# Click on the ''Clear Startup Cache'' button and agree to restart the browser.<br />
<br />
See [https://bugzilla.mozilla.org/show_bug.cgi?id=1639821 Mozilla's bug report] for more information.<br />
<br />
=== Cannot login with my Chinese account ===<br />
<br />
Firefox provides a local service for Chinese users, with a local account totally different from the international one. Firefox installed with the {{Pkg|firefox}} package uses the international account system by default, to change into the Chinese local service, you should install the add-on manager on [http://mozilla.com.cn/thread-343905-1-1.html this page], then you can login with your Chinese account now.<br />
<br />
=== No audio on certain videos when using JACK and PulseAudio ===<br />
<br />
If you are using JACK in combination with PulseAudio and cannot hear any sound on some videos, it could be because those videos have mono audio. This happens if your JACK setup uses more than just stereo, but you use normal headphones. To fix this, you simply have to connect the {{ic|front-center}} port from the PulseAudio JACK Sink to both {{ic|playback_1}} and {{ic|playback_2}} ports of the system output.<br />
<br />
You can also do this automatically using a script:<br />
<br />
{{hc|jack-mono.sh<br />
|2=#!/bin/sh<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_1"<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_2"<br />
}}<br />
<br />
Keep in mind that the names for the sink and the ports might be different for you. You can check what your JACK setup looks like with a Patchbay like Catia from {{Pkg|cadence}}.<br />
<br />
=== Geolocation does not work ===<br />
<br />
Recently, Google limited the use of its location service with Arch Linux, which causes the following error when geolocation is enabled on a website: {{ic|Geolocation error: Unknown error acquiring position}}. Region-locked services such as [https://www.hulu.com/ Hulu] may display a similar error indicating that your location could not be determined even though you have allowed location services for the site.<br />
<br />
To avoid these problems, you can switch to use the [https://location.services.mozilla.com/ Mozilla Location Service]. In {{ic|about:config}} change the {{ic|geo.provider.network.url}} setting to:<br />
<br />
<nowiki>https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%</nowiki><br />
<br />
See {{Bug|65241}} for more details.<br />
<br />
=== Right mouse button instantly clicks the first option in window managers ===<br />
<br />
This problem has been observed in [[i3]], [[bspwm]] and [[xmonad]].<br />
<br />
To fix it, navigate to {{ic|about:config}} and change {{ic|ui.context_menus.after_mouseup}} to {{ic|true}}.<br />
<br />
See [https://www.reddit.com/r/i3wm/comments/88k0yt/right_mouse_btn_instantly_clicks_first_option_in/]<br />
<br />
=== Firefox window does not repaint after disabling or enabling compositing ===<br />
<br />
Unset the environment variable {{ic|MOZ_X11_EGL}}.<br />
<br />
Related bug report: [https://bugzilla.mozilla.org/show_bug.cgi?id=1711039 Bugzilla 1711039].<br />
<br />
=== Firefox continuously asks to be set as default browser upon launch ===<br />
<br />
There are a couple things you can try: if you are using a [[desktop environment]], check if Firefox is set as the default browser in your system settings. If it is not, then set it, otherwise you can run the following {{man|1|xdg-settings}} command, provided by the [[xdg-utils]] package, to query which browser is set as default on your system:<br />
<br />
$ xdg-settings get default-web-browser<br />
<br />
If no value is returned or it is not Firefox, then run this command to set it:<br />
<br />
$ xdg-settings set default-web-browser firefox.desktop<br />
<br />
If Firefox still asks to be set as the default browser, then it may be quieted if it is set to handle ''http'' and ''https'' URL schemes. To do so, run these {{man|1|xdg-mime}} commands: <br />
<br />
$ xdg-mime default firefox.desktop x-scheme-handler/http<br />
$ xdg-mime default firefox.desktop x-scheme-handler/https<br />
<br />
If those do not work either, check if you have set the environment variable {{ic|GTK_USE_PORTAL}} (all values trigger the bug), in which case, unset it. Related bug report: [https://bugzilla.mozilla.org/show_bug.cgi?id=1516290 Bugzilla 1516290]. If that does not work or you did not set it, navigate Firefox to {{ic|about:config}}, check if the variable {{ic|widget.use-xdg-desktop-portal}} is set to {{ic|true}} and, if so, set it to {{ic|false}}.<br />
<br />
If you wish to disable default browser check entirely, navigate Firefox to {{ic|about:config}} and set {{ic|browser.shell.checkDefaultBrowser}} to {{ic|false}}.<br />
<br />
=== Video stuttering ===<br />
<br />
If you experience video stuttering and you notice that Firefox is only hitting one core at 100% when watching videos (especially higher resolution videos), this might help you.<br />
<br />
Go into {{ic|about:config}} and search for {{ic|dom.ipc.processCount}} and change {{ic|dom.ipc.processCount.file}} from 1 to a higher number. An ad hoc method to find a good number is to increase it one at a time until you get good results, but 4 seems to be a good value.<br />
<br />
=== Bengali font broken in some pages ===<br />
<br />
In most cases, installing the {{Pkg|noto-fonts}} and making '''Noto Sans Bengali''' as defaults in '''Fonts and Colors''' settings solves it. However, in some social media sites, Bengali fonts may still be broken. In those cases, Mozilla provides a detailed guide on how to see all the fonts gets loaded in a page. By using [https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Open_the_Inspector Page Inspector], find out [https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts#all_fonts_on_page all the fonts] that are being loaded on that particular page. Removing fonts other than '''Noto Sans''' from the system will resolve the issue permanently.<br />
<br />
There will be some fonts that have been installed as dependency of other package. For example, {{Pkg|chromium}} installs {{Pkg|ttf-liberation}} as dependency, which loads itself in some Firefox pages automatically and breaks Bengali fonts on those pages. To solve this issue, use the following rule in your [[font configuration]]: <br />
<br />
{{hc|$XDG_CONFIG_HOME/fontconfig/fonts.conf|2=<br />
<match target="pattern"><br />
<test qual="any" name="family"><string>Liberation</string></test><br />
<edit mode="assign" name="family" binding="same"><string>Noto Sans Bengali</string></edit><br />
</match><br />
}}<br />
<br />
=== Web Speech API has no voices ===<br />
<br />
Firefox uses for text to speech (tts) speechd. You can use the command {{ic|spd-say "some test sentence"}} to test if it reads the text or {{ic|spd-say -L}} to get a list of the voices. If there are no voices, too, you can install some with the package {{Pkg|espeak-ng}}. If they do not work out of the box, you maybe have to configure them. You can use the {{ic|spd-conf}} command or edit the config file {{ic|.config/speech-dispatcher/speechd.conf}}. There should be the following lines active (without # in front of it):<br />
<br />
AddModule "espeak-ng" "sd_espeak-ng" "espeak-ng.conf"<br />
DefaultModule espeak-ng<br />
<br />
=== Narrate/Listen icon missing in Reader Mode === <br />
<br />
==== Enable Speech Synthesis ====<br />
<br />
Per https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API/Using_the_Web_Speech_API, speech synthesis must be enabled (it is enabled by default). To enable, set {{ic|media.webspeech.synth.enabled}} to {{ic|true}} in {{ic|about:config}}.<br />
<br />
==== Disable Fingerprinting Protection ====<br />
<br />
Per https://support.mozilla.org/en-US/kb/firefox-protection-against-fingerprinting,<br />
Fingerprinting Protection disables the WebSpeech API. If you enabled this option, you will need to disable it for the narrator to work. To disable fingerprinting protection, set {{ic|privacy.resistFingerprinting}} to {{ic|false}} in {{ic|about:config}}.<br />
<br />
==== Disable filter voices ====<br />
<br />
If you do not see the narrator icon, try setting {{ic|narrate.filter-voices}} to {{ic|false}} in {{ic|about:config}}.<br />
<br />
This can be used to check whether {{ic|speech-dispatcher}} works at all. If it helps, you may miss voices for the language of the article opened in reader mode (check {{ic|spd-say -L}}). If you have voices for the reader article language installed, there may be some incorrect settings or defaults related to {{ic|speech-dispatcher}} configuration.<br />
<br />
=== File dialogs do not open when downloading files ===<br />
<br />
If no file chooser is shown when downloading files, even with the option "Always ask where to save files" enabled in Firefox's preferences, then you might not have both {{Pkg|xdg-desktop-portal}} and a suitable implementation. Desktop environments usually provide an implementation, but if you are using a standalone window manager such as [[i3]], then you may need to manually install one. [[Install]] {{Pkg|xdg-desktop-portal}} and for example {{Pkg|xdg-desktop-portal-gtk}}.<br />
<br />
== See also ==<br />
<br />
* [https://www.mozilla.org/firefox/ Official website]<br />
* [https://www.mozilla.org/ Mozilla Foundation]<br />
* [[MozillaWiki:Firefox]]<br />
* [[Wikipedia:Mozilla Firefox]]<br />
* [https://addons.mozilla.org/ Firefox Add-ons]<br />
* [https://addons.mozilla.org/firefox/themes/ Firefox themes]<br />
* [https://ftp.mozilla.org/pub/firefox/releases/ Mozilla's FTP]<br />
* [http://forums.mozillazine.org/ mozillaZine] unofficial forums</div>Progandyhttps://wiki.archlinux.org/index.php?title=Firefox&diff=728998Firefox2022-05-10T04:15:39Z<p>Progandy: /* Hardware video acceleration */ out of date, update for firefox 100 necessary.</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Mozilla]]<br />
[[de:Firefox]]<br />
[[es:Firefox]]<br />
[[fr:Firefox]]<br />
[[ja:Firefox]]<br />
[[ru:Firefox]]<br />
[[zh-hans:Firefox]]<br />
[[zh-hant:Firefox]]<br />
{{Related articles start}}<br />
{{Related|Firefox/Tweaks}}<br />
{{Related|Firefox/Profile on RAM}}<br />
{{Related|Firefox/Privacy}}<br />
{{Related|Browser extensions}}<br />
{{Related|Chromium}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
[https://www.mozilla.org/firefox Firefox] is a popular open source graphical web browser from [https://www.mozilla.org Mozilla].<br />
<br />
== Installing ==<br />
<br />
Firefox can be [[install]]ed with the {{Pkg|firefox}} package.<br />
<br />
Other alternatives include:<br />
<br />
* {{App|Firefox Developer Edition|for developers|https://www.mozilla.org/firefox/developer/|{{Pkg|firefox-developer-edition}}}}<br />
* {{App|Firefox Extended Support Release|long-term supported version|https://www.mozilla.org/firefox/organizations/|{{AUR|firefox-esr}} or {{AUR|firefox-esr-bin}}}}<br />
* {{App|Firefox Beta|cutting-edge version|https://www.mozilla.org/firefox/channel/desktop/#beta|{{AUR|firefox-beta-bin}}}}<br />
* {{App|Firefox Nightly|nightly builds for testing ([https://developer.mozilla.org/Firefox/Experimental_features experimental features])|https://www.mozilla.org/firefox/channel/desktop/#nightly|{{AUR|firefox-nightly}}}} <br />
* {{App|Firefox KDE|Version of Firefox that incorporates an OpenSUSE patch for better [[#KDE integration|KDE integration]] than is possible through simple Firefox add-ons.|https://build.opensuse.org/package/show/mozilla:Factory/MozillaFirefox|{{AUR|firefox-kde-opensuse}}, {{AUR|firefox-kde-opensuse-rpm}}, {{AUR|firefox-kde}} or {{AUR|firefox-developer-edition-kde}}}}<br />
* On top of the different Mozilla build channels, a number of forks exist with more or less special features; see [[List of applications#Gecko-based]].<br />
<br />
A number of language packs are available for Firefox, other than the standard English. Language packs are usually named as {{ic|firefox-i18n-''languagecode''}} (where {{ic|''languagecode''}} can be any language code, such as '''de''', '''ja''', '''fr''', etc.). For a list of available language packs see [https://archlinux.org/packages/extra/any/firefox-i18n/ firefox-i18n] for {{Pkg|firefox}}, [https://archlinux.org/packages/community/any/firefox-developer-edition-i18n/ firefox-developer-edition-i18n] for {{Pkg|firefox-developer-edition}} and [https://aur.archlinux.org/packages/?K=firefox-nightly- firefox-nightly-] for {{AUR|firefox-nightly}}.<br />
<br />
{{Note|1=Language packs are disabled on ''-nightly'' and ''-developer-edition'' due to frequent string changes that may cause crashes. To force a change to the UI language, you may need to set {{ic|intl.locale.requested}} in {{ic|about:config}} [https://www.reddit.com/r/firefox/comments/lx3dp9/how_to_change_interface_language/gpovlsp/?context=8&depth=9].}}<br />
<br />
== Add-ons ==<br />
<br />
Firefox is well known for its large library of add-ons which can be used to add new features or modify the behavior of existing features. Firefox's "Add-ons Manager" is used to manage installed add-ons or find new ones. <br />
<br />
For instructions on how to install add-ons and a list of add-ons, see [[Browser extensions]].<br />
<br />
=== Adding search engines ===<br />
<br />
Search engines may be added to Firefox by creating bookmarks with the {{ic|Location}} field using search URLs completed with %s in place of the query and the {{ic|Keyword}} field completed with user-defined characters:<br />
<br />
Location:<br />
https://duckduckgo.com/html/?q=%s<br />
Keyword:<br />
d<br />
<br />
Searches are performed by pre-pending the search term with the keyword of the specified search engine: {{ic|d archwiki}} will query DuckDuckGo using the search term {{ic|archwiki}}<br />
<br />
Search engines may also be added to Firefox through add-on extensions, see [https://addons.mozilla.org/firefox/search-tools/ this page] for a list of available search tools and engines.<br />
<br />
A very extensive list of search engines can be found at the [https://mycroftproject.com/ Mycroft Project].<br />
<br />
Also, you can use the [https://firefox.maltekraus.de/extensions/add-to-search-bar add-to-searchbar] extension to add a search to your search bar from any web site, by simply right clicking on the site's search field and selecting ''Add to Search Bar...''<br />
<br />
==== firefox-extension-arch-search ====<br />
<br />
[[Install]] the {{AUR|firefox-extension-arch-search}} package to add Arch-specific searches (AUR, wiki, forum, packages, etc) to the Firefox search toolbar.<br />
<br />
== Plugins ==<br />
<br />
Support for all plugins, including Flash Player, was removed in Firefox 85.[https://support.mozilla.org/kb/npapi-plugins][https://support.mozilla.org/kb/end-support-adobe-flash]<br />
<br />
== Configuration ==<br />
<br />
Firefox exposes a number of configuration options. To examine them, enter in the Firefox address bar:<br />
<br />
about:config<br />
<br />
Once set, these affect the user's current profile, and may be synchronized across all devices via [https://www.mozilla.org/firefox/sync/ Firefox Sync]. Please note that only a subset of the {{ic|about:config}} entries are synchronized by this method, and the exact subset may be found by searching for {{ic|services.sync.prefs}} in {{ic|about:config}}. Additional preferences and third party preferences may be synchronized by creating new boolean entries prepending the value with [https://support.mozilla.org/en-US/kb/sync-custom-preferences services.sync.prefs.sync]. To synchronize the whitelist for the extension [https://addons.mozilla.org/firefox/addon/noscript/ NoScript]:<br />
<br />
services.sync.prefs.sync.capability.policy.maonoscript.sites<br />
<br />
The boolean {{ic|noscript.sync.enabled}} must be set to {{ic|true}} to synchronize the remainder of NoScript's preferences via Firefox Sync.<br />
<br />
=== Settings storage ===<br />
<br />
Firefox stores the configuration for a profile via a {{ic|prefs.js}} in the profile folder, usually {{ic|~/.mozilla/firefox/xxxxxxxx.default/}}. <br />
<br />
Firefox also allows configuration for a profile via a {{ic|user.js}} file: [http://kb.mozillazine.org/User.js_file user.js] kept also in the profile folder. A {{ic|user.js}} configuration supersedes a {{ic|prefs.js}}. For a useful starting point, see e.g [https://github.com/pyllyukko/user.js custom user.js] which is targeted at privacy/security conscious users.<br />
<br />
One drawback of the above approach is that it is not applied system-wide. Furthermore, this is not useful as a "pre-configuration", since the profile directory is created after first launch of the browser. You can, however, let ''firefox'' create a new profile and, after closing it again, [https://support.mozilla.org/en-US/kb/back-and-restore-information-firefox-profiles#w_restoring-a-profile-backup copy the contents] of an already created profile folder into it. <br />
<br />
Sometimes it may be desired to lock certain settings, a feature useful in widespread deployments of customized Firefox. In order to create a system-wide configuration, follow the steps outlined in [http://kb.mozillazine.org/Locking_preferences Locking preferences]:<br />
<br />
1. Create {{ic|/usr/lib/firefox/defaults/pref/local-settings.js}}:<br />
<br />
pref("general.config.obscure_value", 0);<br />
pref("general.config.filename", "mozilla.cfg");<br />
<br />
2. Create {{ic|/usr/lib/firefox/mozilla.cfg}} (this stores the actual configuration):<br />
<br />
//<br />
//...your settings...<br />
// e.g to disable Pocket, uncomment the following lines<br />
// lockPref("extensions.pocket.enabled", false);<br />
// lockPref("browser.newtabpage.activity-stream.feeds.section.topstories", false);<br />
<br />
Please note that the first line must contain exactly {{ic|//}}. The syntax of the file is similar to that of {{ic|user.js}}.<br />
<br />
=== Multimedia playback ===<br />
<br />
Firefox uses [[FFmpeg]] for playing multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. Go to [http://demo.nimius.net/video_test/ video-test page] or [https://hpr.dogphilosophy.net/test/ audio-test page] to check which formats are actually supported.<br />
<br />
Firefox uses [[PulseAudio]] for audio playback and capture. If PulseAudio is not installed, Firefox uses [[alsa]] instead.<br />
<br />
{{Tip|<br />
Firefox might not play video if audio is not configured. If you are intending to use [[PipeWire]] and [[WirePlumber]] make sure they are working properly<br />
}}<br />
<br />
==== HTML5 DRM/Widevine ====<br />
<br />
Widevine is a digital rights management tool that Netflix, Amazon Prime Video, and others use to protect their video content. It can be enabled in ''Preferences > General > Digital Rights Management (DRM) Content''. If you visit a Widevine-enabled page when this setting is disabled, Firefox will display a prompt below the address bar asking for permission to install DRM. Approve this and then wait for the "Downloading" bar to disappear, you are now able to watch videos from Widevine protected sites. <br />
<br />
Firefox can only play 720p video (or lower) with Widevine, due to not using [https://bugzilla.mozilla.org/show_bug.cgi?id=1700815 hardware DRM playback]. It is also required that the private mode browsing is disabled, for the window and in the preferences.<br />
<br />
==== Open With extension ====<br />
<br />
# Install [https://addons.mozilla.org/firefox/addon/open-with/ Open With] add-on.<br />
# Go to ''Add-ons > Open With > Preferences''.<br />
# Proceed with instructions to install a file in your system and test the installation. <br />
# Click ''Add browser''.<br />
# In the dialog write a name for this menu entry and command to start a video streaming capable player (e.g. [[mpv|/usr/bin/mpv]]).<br />
# (Optional step) Add needed arguments to the player (e.g. you may want {{ic|--force-window --ytdl}} for ''mpv'')<br />
# Right click on links or visit pages containing videos. Select newly created entry from Open With's menu and if the site is supported, the player will open as expected.<br />
<br />
The same procedure can be used to associate video downloaders such as ''youtube-dl''.<br />
<br />
==== Hardware video acceleration ====<br />
<br />
{{Out of date|Point 3. is wrong for Firefox 100. The RDD process must be used.}}<br />
<br />
[[Hardware video acceleration]] via VA-API is available under [[Wayland]] [https://mastransky.wordpress.com/2020/06/03/firefox-on-fedora-finally-gets-va-api-on-wayland/] and [[Xorg]] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619523] [https://www.phoronix.com/scan.php?page=news_item&px=Firefox-80-VA-API-X11].<br />
<br />
To enable VA-API in Firefox:<br />
<br />
# Ensure that your video card is correctly configured for VA-API:<br />
#* See [[Hardware video acceleration]] for steps to verify and install VA-API drivers if required.<br />
# Ensure WebRender is enabled.<br />
#* Verify WebRender is enabled by opening {{ic|about:support}} and then {{ic|Compositing}}. It is enabled by default in GNOME and other desktop environments [https://mastransky.wordpress.com/2021/01/10/firefox-were-finally-getting-hw-acceleration-on-linux/]. <br />
#** Ensure you are not running Software WebRender as that will not work as of August 2021 [https://bugzilla.mozilla.org/show_bug.cgi?id=1723540#c1]. <br />
#** If necessary, Hardware WebRender can be force enabled by setting {{ic|gfx.webrender.all}} to {{ic|true}}.<br />
# Set the following flags in {{ic|about:config}}:{{Note|1=on Firefox 96 only setting {{ic|media.ffmpeg.vaapi.enabled}} and {{ic|media.rdd-ffmpeg.enabled}} to true ''should'' be necessary. Many below preferences no longer need to be set since [https://bugzilla.mozilla.org/show_bug.cgi?id=1698778#c32 the RDD sandbox] was mostly fixed. However, some issues still remain [https://bugzilla.mozilla.org/show_bug.cgi?id=1743926].}}{{Note|1=starting from Firefox 97, only setting {{ic|media.ffmpeg.vaapi.enabled}} to true ''should'' be necessary.[https://bugzilla.mozilla.org/show_bug.cgi?id=1683808#c36]}}{{Note|1=As of Firefox 98, VA-API is blocked by RDD sandbox, but can be used by setting the environment variable {{ic|1=MOZ_DISABLE_RDD_SANDBOX=1}}, although this is less secure. [https://bugzilla.mozilla.org/show_bug.cgi?id=1751363]}}<br />
#* {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|true}} in order to enable the use of VA-API with FFmpeg.<br />
#* {{ic|media.ffvpx.enabled}} to {{ic|false}} to disable the internal decoders for VP8/VP9. This is necessary despite [https://bugzilla.mozilla.org/show_bug.cgi?id=1660336 this bug] being fixed [https://bugzilla.mozilla.org/show_bug.cgi?id=1720363#c6][https://bugzilla.mozilla.org/show_bug.cgi?id=1683808].<br />
#* {{ic|media.navigator.mediadatadecoder_vpx_enabled}} to {{ic|true}} to enable hardware VA-API decoding for WebRTC [https://bugzilla.mozilla.org/show_bug.cgi?id=1709009].<br />
#* {{ic|media.rdd-vpx.enabled}} to {{ic|false}} to disable the remote data decoder process for VP8/VP9. Firefox attempts to use the RDD process for VP8/VP9 but the RDD sandbox blocks VA-API access [https://bugzilla.mozilla.org/show_bug.cgi?id=1673184]. Disabling the remote data decoder for VP8/VP9 process means VA-API will run in the content process instead. In Firefox 96 mostly working support for running VA-API in the RDD process was added.<br />
#** Another possible workaround is to completely disable the RDD process by setting {{ic|media.rdd-process.enabled}} to {{ic|false}}, instead of just disabling it for VP8/VP9 as above.<br />
#* On Intel, in some cases VA-API might not work with the Intel iHD driver {{Pkg|intel-media-driver}}. This might be workaroundable by using the Intel i965 driver {{Pkg|libva-intel-driver}}. This workaround does not work anymore with Intel Iris Xe graphics, which are only supported by {{Pkg|intel-media-driver}}. Luckily Firefox 96 introduced better support for the RDD Process, which should help with {{Pkg|intel-media-driver}}. [https://bugzilla.mozilla.org/show_bug.cgi?id=1619585#c42] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619585#c62] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619585#c63].<br />
#** As a last resort, the content process sandbox can be disabled. However, this is a serious security risk and disables protection against attackers. It is recommended to leave the sandbox settings as default [https://bugzilla.mozilla.org/show_bug.cgi?id=1683808#c26]. Nevertheless, to disable the content sandbox set {{ic|security.sandbox.content.level}} to {{ic|0}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1720363#c9].<br />
# Run Firefox with the following [[environment variable]] enabled:<br />
#* In Wayland, with {{ic|1=MOZ_ENABLE_WAYLAND=1}}, see [[#Wayland]].<br />
#* In X.org, since 94, Firefox will run in EGL mode by default which is sufficient [https://mozillagfx.wordpress.com/2021/10/30/switching-the-linux-graphics-stack-from-glx-to-egl/].<br />
#** For older releases, in X.org, enable EGL with {{ic|1=MOZ_X11_EGL=1}} or set {{ic|gfx.x11-egl.force-enabled}} to {{ic|true}} and {{ic|gfx.x11-egl.force-disabled}} to {{ic|false}} in {{ic|about:config}}.<br />
<br />
{{Warning|Disabling the content process sandbox is a security risk, starting in Firefox 96 initial support for working VA-API in the RDD process exists.}}<br />
<br />
{{Tip|<br />
* As well as following [[Hardware video acceleration#Verification]], one can confirm VA-API usage by checking Firefox VA-API logs. Run Firefox with the {{ic|1=MOZ_LOG="PlatformDecoderModule:5"}} environment variable and check in the log output that VA-API is enabled and used (search for the "VA-API" string) when playing a video for example. Pay attention to these logs as they might indicate that only one of the two possible compositors described before (WebRender or OpenGL) works with VA-API on your particular setup.<br />
* To allow hardware decoding in YouTube, the video codec used must be supported by the hardware. The profiles supported by your GPU can be checked with [[Hardware video acceleration#Verifying VA-API]] and the YouTube codecs used can ''sometimes'' (if offered by YouTube!) be controlled with the [https://addons.mozilla.org/firefox/addon/h264ify/ h264ify] or [https://addons.mozilla.org/firefox/addon/enhanced-h264ify/ enhanced-h264ify] extensions. Alternatively, you can install {{AUR|firefox-h264ify}}.<br />
}}<br />
<br />
{{Note|1=<nowiki/><br />
* NVIDIA's proprietary driver potentially has support for DMA-BUF in the 470 drivers [https://bugs.kde.org/show_bug.cgi?id=428089#c2][https://www.phoronix.com/scan.php?page=news_item&px=NVIDIA-DMA-BUF-Wayland-KDE]. By using [[CUDA]] and DMA-BUF with {{AUR|libva-nvidia-driver}} it should potentially work [https://github.com/elFarto/nvidia-vaapi-driver/#firefox]. DMA-BUF is necessary for hardware video acceleration in Firefox [https://bugzilla.mozilla.org/show_bug.cgi?id=1669189#c4] and since currently there is no DMA-BUF support for [[VDPAU]] nor {{Pkg|libva-vdpau-driver}} this lasts options will not work.<br />
* Currently Firefox's VA-API implementation can decode H.264/AVC, VP8 & VP9, AV1 encoded video. AV1 support requires FireFox 98+ [https://bugzilla.mozilla.org/show_bug.cgi?id=1745225].<br />
* Multi-GPU systems should automatically choose a suitable GPU for VA-API according to this [https://bugzilla.mozilla.org/show_bug.cgi?id=1588904#c36 solved issue].<br />
* Some videos (e.g. YouTube VR) may show a black image after setting {{ic|media.ffvpx.enabled}} to {{ic|false}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1667537].<br />
* To workaround VA-API not working correctly in the RDD process, the RDD process sandbox can be disabled instead of moving VA-API to the content process as suggested above. This is not recommended since disabling the sandbox is a large security risk and disables protection against attackers. Set the environment variable {{ic|1=MOZ_DISABLE_RDD_SANDBOX=1}} to disable RDD sandbox. <br />
* [[AMDGPU]] users under {{Pkg|linux-hardened}} may need to rebuild ''linux-hardened'' with {{ic|1=CONFIG_CHECKPOINT_RESTORE=y}} due to {{Pkg|mesa}} [https://gitweb.gentoo.org/repo/gentoo.git/tree/media-libs/mesa/mesa-9999.ebuild requiring the kcmp syscall]. This may no longer be necessary due to this [https://bugzilla.mozilla.org/show_bug.cgi?id=1624743 bug being solved].<br />
}}<br />
<br />
=== Spell checking ===<br />
<br />
Firefox can use system-wide installed [[Hunspell]] dictionaries as well as dictionaries installed through its own extension system.<br />
<br />
To enable spell checking for a specific language right click on any text field and check the ''Check Spelling'' box. To select a language for spell checking to you have right click again and select your language from the ''Languages'' sub-menu.<br />
<br />
When your default language choice does not stick, see [[#Firefox does not remember default spell check language]].<br />
<br />
==== System-wide Hunspell dictionaries ====<br />
<br />
Install [[Hunspell]] and its dictionaries for the languages you require.<br />
<br />
==== Dictionaries as extensions ====<br />
<br />
To get more languages right click on any text field and just click ''Add Dictionaries...'' and select the dictionary you want to install from the [https://addons.mozilla.org/firefox/language-tools/ Dictionaries and Language Packs list].<br />
<br />
{{Tip|For Russian, the extension is packaged as {{Pkg|firefox-spell-ru}}.}}<br />
<br />
=== KDE integration ===<br />
<br />
* To bring the [[KDE]] look to GTK applications (including Firefox), install {{Pkg|breeze-gtk}} and {{Pkg|kde-gtk-config}}. Afterwards, go to System Settings and in ''Appearance > Application Style > Configure GNOME/GTK Application Style…'' choose 'Breeze'.<br />
* To use the KDE file selection and print dialogs in Firefox 64 or newer, install {{Pkg|xdg-desktop-portal}} and {{Pkg|xdg-desktop-portal-kde}}, then do one of the following:<br />
** Set {{ic|widget.use-xdg-desktop-portal.mime-handler}} to {{ic|1}} in {{ic|about:config}}. You should also change {{ic|widget.use-xdg-desktop-portal.file-picker}} from {{ic|2}} to {{ic|1}}.<br />
** Launch firefox with {{ic|1=GTK_USE_PORTAL=1}} [[environment variable]].<br />
::{{Note|1=Using {{ic|1=GTK_USE_PORTAL=1}} or setting {{ic|widget.use-xdg-desktop-portal.mime-handler}} to {{ic|1}} will result in [https://bugzilla.mozilla.org/show_bug.cgi?id=1516290 Firefox asking to set default browser every time Firefox starts].}}<br />
* For integration with [[KDE]] MIME type system, proxy and file dialog, one can use {{AUR|firefox-kde-opensuse}} variant from AUR with OpenSUSE’s patches applied. Alternatively, integration with MIME types can be achieved by creating a symbolic link to the MIME database {{ic|~/.config/mimeapps.list}} from the deprecated {{ic|~/.local/share/applications/mimeapps.list}} that is used by Firefox. See [[XDG MIME Applications#mimeapps.list]].<br />
* Extensions/add-ons may provide additional integration, such as:<br />
** Browser integration in [[Plasma]]: requires {{Pkg|plasma-browser-integration}} and the [https://addons.mozilla.org/firefox/addon/plasma-integration/ Plasma Integration add-on].<br />
::{{Tip|To prevent duplicate entries in the Media Player widget or tray icon, set {{ic|media.hardwaremediakeys.enabled}} to {{ic|false}}. This disables the media entry from Firefox and only uses the one from the Plasma integration add-on.}}<br />
<br />
== Tips and tricks ==<br />
<br />
For general enhancements see [[Firefox/Tweaks]], for privacy related enhancements see [[Firefox/Privacy]].<br />
<br />
=== Dark themes ===<br />
<br />
Firefox should respect your GTK theme settings and your OS-wide dark appearance settings (as in the Appearance section of GNOME's settings or KDE system settings). If the later does not work, make sure to have a suitable xdg-desktop-portal package installed.<br />
<br />
Starting with Firefox 68 you can make all the Firefox interfaces and even other websites respect dark themes, irrespective of the system GTK theme and Firefox theme. To do this, set {{ic|ui.systemUsesDarkTheme}} to {{ic|1}} in {{ic|about:config}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1488384#c23].<br />
<br />
As of Firefox 100, further control of the dark theme of web pages that opt-in (using the CSS media query [https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme prefers-color-scheme]) and Firefox's own in-content pages is possible with {{ic|layout.css.prefers-color-scheme.content-override}}. Setting this to {{ic|3}} will follow the browser theme, setting this to {{ic|2}} will follow the system wide dark-mode preference ({{ic|ui.systemUsesDarkTheme}} as above, which defaults to {{ic|0}} if the user has not changed the dark-mode preference or if a system does not support a system-wide dark-mode preference), while {{ic|1}} and {{ic|0}} will always force light-mode and dark-mode respectively. This setting can also be accessed through the user settings of Firefox under ''General'' > ''Language and Appearance'' > ''Website appearance''.<br />
<br />
=== Frame rate ===<br />
<br />
If Firefox is unable to automatically detect the right value, it will default to 60 fps. To manually correct this, set {{ic|layout.frame_rate}} to the refresh rate of your monitor (e.g. 144 for 144 Hz).<br />
<br />
=== Memory limit ===<br />
<br />
To prevent pages from abusing memory (and possible [[Wikipedia:Out_of_memory|OOM]]), we can use [[Firejail]] with the {{ic|rlimit-as}} option.<br />
<br />
=== New tabs position ===<br />
<br />
To control where new tabs appears (relative or absolute), use {{ic|browser.tabs.insertAfterCurrent}} and {{ic|browser.tabs.insertRelatedAfterCurrent}}. See [https://support.mozilla.org/en/questions/1229062] for more information.<br />
<br />
=== Screenshot of webpage ===<br />
<br />
You can ''Take a Screenshot'' by either using the screenshots button that can be added to the toolbar from the customize screen in the Hamburger menu at ''More tools'' > ''Customize toolbar'', by pressing ctrl + shift + s or by right-clicking on the webpage. See [https://support.mozilla.org/en-US/kb/firefox-screenshots] for more information.<br />
<br />
As an alternative you can use the screenshot button in the developer tools, which can be added through the developer tools ''Settings'' menu, under the ''Available Toolbox Buttons'' section. The settings for the developer tools are accessible through the three horizontal dots located at the top right of the developer tools pane.<br />
<br />
=== Wayland ===<br />
<br />
More recent versions of Firefox support opting into [[Wayland]] mode via an environment variable.<br />
<br />
$ MOZ_ENABLE_WAYLAND=1 firefox<br />
<br />
To make this permanent, see [[Environment variables#Graphical environment]] and start Firefox via the desktop launcher like you normally would.<br />
<br />
To verify it worked, look for {{ic|Window Protocol}} in {{ic|about:support}}. It should say {{ic|wayland}}. The presence of {{ic|x11}} means you are running Firefox under [[Xorg]] display server, while {{ic|xwayland}} means your system is running Wayland but executing Firefox as legacy X11 application. <br />
<br />
If it is necessary to be regularly switching between Wayland and X.org, it may be useful to add a conditional to your shell's login [[Command-line shell#Configuration files|startup script]], e.g. {{ic|~/.bash_profile}} for [[Bash]]:<br />
<br />
{{bc|1=<br />
if [ "$XDG_SESSION_TYPE" == "wayland" ]; then<br />
export MOZ_ENABLE_WAYLAND=1<br />
fi<br />
}}<br />
<br />
=== Window manager rules ===<br />
<br />
To apply different configurations to Firefox windows, change the WM_CLASS string by using Firefox's {{ic|--class}} option, to a custom one.<br />
<br />
=== Profiles ===<br />
<br />
To start new Firefox instances, multiple profiles are required. To create a new profile:<br />
<br />
$ firefox [--new-instance] -P<br />
<br />
Class can be specified when launching Firefox with a not-in-use profile:<br />
<br />
$ firefox [--new-instance] -P ''profile_name'' --class=''class_name''<br />
<br />
[https://ffprofile.com/ Firefox Profilemaker] can be used to create a Firefox profile with the defaults you like.<br />
<br />
=== Touchscreen gestures and pixel-perfect trackpad scrolling ===<br />
<br />
{{Merge|Firefox/Tweaks#Enable touchscreen gestures|Same solution.}}<br />
<br />
To enable touch gestures (like scrolling and pinch-to-zoom) and one-to-one trackpad scrolling (as can be witnessed with GTK3 applications like Nautilus), set the {{ic|1=MOZ_USE_XINPUT2=1}} [[environment variable]] before starting Firefox. On Wayland, {{ic|1=MOZ_ENABLE_WAYLAND=1}} may also need to be set.<br />
<br />
=== Multiple home pages ===<br />
<br />
To have multiple tabs opened when starting Firefox open a new window and then open the sites you want to have as "home tabs".<br />
<br />
Now go to ''Preferences > Home'' and under ''Homepage and new windows'' click the ''Use Current Pages'' button.<br />
<br />
Alternatively go directly to ''Preferences > Home'' and now under ''Homepage and new windows'' set the first field to ''Custom URLs..'' and enter the pages you want as new home pages in the following format:<br />
<br />
<nowiki>https://url1.com|https://url2.com|https://url3.com</nowiki><br />
<br />
== Troubleshooting ==<br />
<br />
=== Troubleshoot Mode ===<br />
<br />
The command line switch {{ic|-safe-mode}} starts Firefox in [https://support.mozilla.org/en-US/kb/diagnose-firefox-issues-using-troubleshoot-mode Troubleshoot Mode], which disables extensions, themes, hardware acceleration, the JIT and some other features for this session.<br />
<br />
This mode can also be enabled by pressing on the hamburger menu while Firefox is open, clicking ''Help'', selecting ''Troubleshoot Mode'' and confirming this on the modal dialog that appears. Please note this will require a browser restart.<br />
<br />
This mode was previously named Safe Mode until Firefox 88.<br />
<br />
=== Firefox refresh ===<br />
<br />
Some issues experienced by users in Firefox may be caused by profile issues, such as corruption.<br />
<br />
If you have ruled out other causes, it may be worth trying a new Firefox profile for testing purposes to see if this will resolve your issue. More information on how to create a new profile and switch between profiles can be found on the [https://support.mozilla.org/en-US/kb/profile-manager-create-remove-switch-firefox-profiles Firefox support page].<br />
<br />
If this resolves your issue, you should switch back to your original profile and consider refreshing your Firefox. <br />
<br />
Refreshing your profile will retain all browsing and download history, bookmarks, web form auto-fill data, cookies, personal dictionary and passwords, and will transfer them to a brand new profile without extensions, themes, extension data and preferences, among other data. A backup of your old profile will also be retained.<br />
<br />
To refresh your profile, navigate to {{ic|about:support}}, press ''Refresh Firefox'' and confirm this on the modal dialog that appears. {{ic|about:support}} can also be accessed by pressing the Hamburger menu, selecting ''Help'' and then clicking ''More troubleshooting information''.<br />
<br />
More information on refreshing your Firefox, including further details about what is transferred to the new profile, can be found on the [https://support.mozilla.org/en-US/kb/refresh-firefox-reset-add-ons-and-settings Firefox support page].<br />
<br />
=== Disable hardware video acceleration ===<br />
<br />
If you are having issues with hardware video acceleration in Firefox, e.g. in case of freezes or graphical corruption, start Firefox in [[#Troubleshoot Mode|Troubleshoot Mode]] for testing purposes to confirm that this is the issue. If this step resolves the issue, merely set {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|false}} in {{ic|about:config}} to disable hardware video acceleration, and restart Firefox.<br />
<br />
=== Extension X does not work on some Mozilla owned domains ===<br />
<br />
By default extensions will not affect pages designated by {{ic|extensions.webextensions.restrictedDomains}}. If this is not desired, this field can be cleared (special pages such as {{ic|about:*}} will not be affected).<br />
<br />
=== Firefox startup takes very long ===<br />
<br />
If Firefox takes much longer to start up than other browsers, it may be due to lacking configuration of the localhost in {{ic|/etc/hosts}}. See [[Network configuration#Local network hostname resolution]] on how to set it up.<br />
<br />
Misbehaving Firefox extensions, or too many extensions, may be another source of slow startup. This can be confirmed through the use of [[#Troubleshoot Mode|Troubleshoot Mode]], which will disable extensions on restart. <br />
<br />
A further cause of slow start-up may be a profile issue, such as corruption. For more troubleshooting steps around your Firefox profile see [[#Firefox refresh]].<br />
<br />
=== Font troubleshooting ===<br />
<br />
See [[Font configuration]].<br />
<br />
Firefox has a setting which determines how many replacements it will allow from Fontconfig. To allow it to use all your replacement rules, change {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|127}} (the highest possible value).<br />
<br />
Firefox ships with the ''Twemoji Mozilla'' font. To use the system emoji font, set {{ic|font.name-list.emoji}} to {{ic|emoji}} in {{ic|about:config}}. Additionally, to prevent the Mozilla font interfering with your system emoji font, change {{ic|gfx.font_rendering.opentype_svg.enabled}} to {{ic|false}} or remove {{ic|/usr/lib/firefox/fonts/TwemojiMozilla.ttf}} (see also [[pacman#Skip files from being installed to system]]).<br />
<br />
=== Setting an email client ===<br />
<br />
Inside the browser, {{ic|mailto}} links by default are opened by a web application such as Gmail or Yahoo Mail. To set an external email program, go to ''Preferences > Applications'' and modify the ''action'' corresponding to the {{ic|mailto}} content type; the file path will need to be designated (e.g. {{ic|/usr/bin/kmail}} for Kmail).<br />
<br />
Outside the browser, {{ic|mailto}} links are handled by the {{ic|x-scheme-handler/mailto}} mime type, which can be easily configured with [[xdg-mime]]. See [[Default applications]] for details and alternatives.<br />
<br />
=== File association ===<br />
<br />
See [[Default applications]].<br />
<br />
=== Firefox keeps creating ~/Desktop even when this is not desired ===<br />
<br />
Firefox uses {{ic|~/Desktop}} as the default place for download and upload files. To change it to another folder, set the {{ic|XDG_DESKTOP_DIR}} option as explained in [[XDG user directories]].<br />
<br />
=== Changes to userChrome.css and userContent.css are ignored ===<br />
<br />
Set {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|true}} in {{ic|about:config}}<br />
<br />
=== Middle-click behavior ===<br />
<br />
To use the middle mouse button to paste whatever text has been highlighted/added to the clipboard, as is common in UNIX-like operating systems, set either {{ic|middlemouse.contentLoadURL}} or {{ic|middlemouse.paste}} to {{ic|true}} in {{ic|about:config}}. Having {{ic|middlemouse.contentLoadURL}} enabled was the default behaviour prior to Firefox 57.<br />
<br />
To scroll on middle-click (default for Windows browsers) set {{ic|general.autoScroll}} to {{ic|true}}.<br />
<br />
=== Backspace does not work as the 'Back' button ===<br />
<br />
According to [http://kb.mozillazine.org/Browser.backspace_action MozillaZine], the {{ic|Backspace}} key was mapped based on which platform the browser was running on. As a compromise, this preference was created to allow the {{ic|Backspace}} key to either go back/forward, scroll up/down a page, or do nothing.<br />
<br />
To make {{ic|Backspace}} go back one page in the tab's history and {{ic|Shift+Backspace}} go forward, set {{ic|browser.backspace_action}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
To have the {{ic|Backspace}} key scroll up one page and {{ic|Shift+Backspace}} scroll down one page, set {{ic|browser.backspace_action}} to {{ic|1}}. Setting this property to any other value will leave the key unmapped (Arch Linux defaults to {{ic|2}}, in other words, it is unmapped by default).<br />
<br />
=== Firefox does not remember login information ===<br />
<br />
It may be due to a corrupted {{ic|cookies.sqlite}} file in [https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data Firefox's profile] folder. In order to fix this, just rename or remove {{ic|cookie.sqlite}} while Firefox is not running.<br />
<br />
Open a terminal of choice and type the following:<br />
<br />
$ rm -f ~/.mozilla/firefox/<profile id>.default/cookies.sqlite<br />
<br />
The profile id is a random 8 character string.<br />
<br />
Restart Firefox and see if it solved the problem.<br />
<br />
If it did not work, check if there exists a {{ic|cookies.sqlite.bak}} file that you could use to manually restore the cookies.<br />
<br />
=== Cannot enter/leave fullscreen ===<br />
<br />
If Firefox detects an [https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html EWMH/ICCCM] compliant window manager, it will try to send a WM_STATE message to the root window to request Firefox be made to enter (or leave) full-screen mode (as defined by the window manager). Window managers are allowed to ignore it, but if they do, Firefox will assume the request got denied and propagate it to the end user which results in nothing happening. This may result in not being able to full screen a video. A general workaround is to set the {{ic|full-screen-api.ignore-widgets}} to {{ic|true}} in {{ic|about:config}}. <br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=1189622 Bugzilla 1189622].<br />
<br />
=== JavaScript context menu does not appear on some sites ===<br />
<br />
You can try setting {{ic|dom.w3c_touch_events.enabled}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
=== Firefox does not remember default spell check language ===<br />
<br />
The default spell checking language can be set as follows:<br />
<br />
# Type {{ic|about:config}} in the address bar.<br />
# Set {{ic|spellchecker.dictionary}} to your language of choice, for instance {{ic|en_GB}}.<br />
# Notice that the for dictionaries installed as a Firefox plugin the notation is {{ic|en-GB}}, and for {{Pkg|hunspell}} dictionaries the notation is {{ic|en_GB}}.<br />
<br />
When you only have system wide dictionaries installed with {{Pkg|hunspell}}, Firefox might not remember your default dictionary language settings. This can be fixed by having at least one [https://addons.mozilla.org/firefox/language-tools/ dictionary] installed as a Firefox plugin. Notice that now you will also have a tab ''Dictionaries'' in ''Add-ons''. You may have to change the order of ''preferred language for displaying pages'' in {{ic|about:preferences#general}} to make the spell check default to the language of the addon dictionary.<br />
<br />
Related questions on the '''StackExchange''' platform: [https://stackoverflow.com/questions/26936792/change-firefox-spell-check-default-language/29446115], [https://stackoverflow.com/questions/21542515/change-default-language-on-firefox/29446353], [https://askubuntu.com/questions/184300/how-can-i-change-firefoxs-default-dictionary/576877]<br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=776028 Bugzilla 776028], [https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/1026869 Ubuntu bug 1026869]<br />
<br />
=== Some MathML symbols are missing ===<br />
<br />
You need some Math fonts, namely Latin Modern Math and STIX (see this MDN page: [https://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts#Linux]), to display MathML correctly.<br />
<br />
In Arch Linux, these fonts are provided by {{Pkg|texlive-core}} '''and''' {{Pkg|texlive-fontsextra}}, but they are not available to fontconfig by default. See [[TeX Live#Making fonts available to Fontconfig]] for details. You can also try other [[Fonts#Math|Math fonts]]. In case you encounter this bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1208776] installing {{Pkg|otf-latinmodern-math}} can help.<br />
<br />
=== YouTube videos load but does not play. This also happens on other web browsers. ===<br />
<br />
{{Accuracy|1=<br />
* If this applies to other browsers, then this info should be moved to the page corresponding with the component that is the root cause ([[PulseAudio]]?), and be linked to. See [[Firefox/Tweaks#Emacs_key_bindings]] for an example of this.<br />
* This solution verifies that PA is installed, only to just replace it with PipeWire. This should be solvable while keeping PA.<br />
* [https://bugzilla.mozilla.org/show_bug.cgi?id=1422073 This Firefox issue] was edited out of this section, but it appears to still be unresolved.}}<br />
<br />
Verify you have {{ic|pulseaudio}} installed. While the video is being loaded, in a terminal application.<br />
<br />
pulseaudio --kill<br />
# If there is no autostart<br />
pulseaudio --start<br />
<br />
This should ensure the video plays (albeit without sound at first). You should be able to select another video on YouTube and be able to view the video with sound, as long as you do not leave YouTube's single-page application. Once confirmed that {{ic|pulseaudio}} is the issue, replace {{ic|pulseaudio}} with {{ic|pipewire-pulse}} and re-login to see if it works. See [[PipeWire#PulseAudio clients]] for details.<br />
<br />
=== Tearing when scrolling ===<br />
<br />
Try disabling smooth scrolling in ''Preferences > Browsing''.<br />
<br />
=== Firefox WebRTC module cannot detect a microphone ===<br />
<br />
WebRTC applications for instance [https://mozilla.github.io/webrtc-landing/gum_test.html Firefox WebRTC getUserMedia test page] say that microphone cannot be found. Issue is reproducible for both ALSA or PulseAudio setup. Firefox debug logs show the following error:<br />
<br />
{{hc|1=$ NSPR_LOG_MODULES=MediaManager:5,GetUserMedia:5 firefox|2=<br />
...<br />
[Unnamed thread 0x7fd7c0654340]: D/GetUserMedia VoEHardware:GetRecordingDeviceName: Failed 1<br />
}}<br />
<br />
You can try setting {{ic|media.navigator.audio.full_duplex}} property to {{ic|false}} at {{ic|about:config}} Firefox page and restart Firefox.<br />
<br />
This can also help if you are using the PulseAudio [[PulseAudio#Microphone echo/noise cancellation|module-echo-cancel]] and Firefox does not recognise the virtual echo canceling source.<br />
<br />
=== Cannot login with my Chinese account ===<br />
<br />
Firefox provides a local service for Chinese users, with a local account totally different from the international one. Firefox installed with the {{Pkg|firefox}} package uses the international account system by default, to change into the Chinese local service, you should install the add-on manager on [http://mozilla.com.cn/thread-343905-1-1.html this page], then you can login with your Chinese account now.<br />
<br />
=== No audio on certain videos when using JACK and PulseAudio ===<br />
<br />
If you are using JACK in combination with PulseAudio and cannot hear any sound on some videos it could be because those videos have mono audio. This happens if your JACK setup uses more than just stereo, but you use normal headphones. To fix this you simply have to connect the {{ic|front-center}} port from the PulseAudio JACK Sink to both {{ic|playback_1}} and {{ic|playback_2}} ports of the system output.<br />
<br />
You can also do this automatically using a script:<br />
<br />
{{hc|jack-mono.sh<br />
|2=#!/bin/sh<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_1"<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_2"<br />
}}<br />
<br />
Keep in mind that the names for the sink and the ports might be different for you. You can check what your JACK setup looks like with a Patchbay like Catia from {{Pkg|cadence}}.<br />
<br />
=== Geolocation does not work ===<br />
<br />
Recently, Google limited the use of its location service with Arch Linux, which causes the following error when geolocation is enabled on a website: {{ic|Geolocation error: Unknown error acquiring position}}. Region-locked services such as [https://www.hulu.com/ Hulu] may display a similar error indicating that your location could not be determined even though you have allowed location services for the site.<br />
<br />
To avoid these problems, you can switch to use the [https://location.services.mozilla.com/ Mozilla Location Service]. In {{ic|about:config}} change the {{ic|geo.provider.network.url}} setting to:<br />
<br />
<nowiki>https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%</nowiki><br />
<br />
See {{Bug|65241}} for more details.<br />
<br />
=== Right mouse button instantly clicks the first option in window managers ===<br />
<br />
This problem has been observed in [[i3]], [[bspwm]] and [[xmonad]].<br />
<br />
To fix it, navigate to {{ic|about:config}} and change {{ic|ui.context_menus.after_mouseup}} to {{ic|true}}.<br />
<br />
See [https://www.reddit.com/r/i3wm/comments/88k0yt/right_mouse_btn_instantly_clicks_first_option_in/]<br />
<br />
=== Firefox window does not repaint after disabling or enabling compositing ===<br />
<br />
Unset the environment variable {{ic|MOZ_X11_EGL}}.<br />
<br />
Related bug report: [https://bugzilla.mozilla.org/show_bug.cgi?id=1711039 Bugzilla 1711039].<br />
<br />
=== Firefox continuously asks to be set as default browser upon launch ===<br />
<br />
There are a couple things you can try: if you are using a [[desktop environment]], check if Firefox is set as the default browser in your system settings. If it is not, then set it, otherwise you can run the following {{man|1|xdg-settings}} command, provided by the [[xdg-utils]] package, to query which browser is set as default on your system:<br />
<br />
$ xdg-settings get default-web-browser<br />
<br />
If no value is returned or it is not Firefox, then run this command to set it:<br />
<br />
$ xdg-settings set default-web-browser firefox.desktop<br />
<br />
If Firefox still asks to be set as the default browser, then it may be quieted if it is set to handle ''http'' and ''https'' URL schemes. To do so, run these {{man|1|xdg-mime}} commands: <br />
<br />
$ xdg-mime default firefox.desktop x-scheme-handler/http<br />
$ xdg-mime default firefox.desktop x-scheme-handler/https<br />
<br />
If those do not work either, check if you have set the environment variable {{ic|GTK_USE_PORTAL}} (all values trigger the bug), in which case, unset it. Related bug report: [https://bugzilla.mozilla.org/show_bug.cgi?id=1516290 Bugzilla 1516290]. If that does not work or you did not set it, navigate Firefox to {{ic|about:config}}, check if the variable {{ic|widget.use-xdg-desktop-portal}} is set to {{ic|true}} and, if so, set it to {{ic|false}}.<br />
<br />
If you wish to disable default browser check entirely, navigate Firefox to {{ic|about:config}} and set {{ic|browser.shell.checkDefaultBrowser}} to {{ic|false}}.<br />
<br />
=== Video stuttering ===<br />
<br />
If you experience video stuttering and you notice that Firefox is only hitting one core at 100% when watching videos (especially higher resolution videos), this might help you.<br />
<br />
Go into {{ic|about:config}} and search for {{ic|dom.ipc.processCount}} and change {{ic|dom.ipc.processCount.file}} from 1 to a higher number. An ad hoc method to find a good number is to increase it one at a time until you get good results, but 4 seems to be a good value.<br />
<br />
=== Bengali font broken in some pages ===<br />
<br />
In most cases, installing the {{Pkg|noto-fonts}} and making '''Noto Sans Bengali''' as defaults in '''Fonts and Colors''' settings solves it. However, in some social media sites, Bengali fonts may still be broken. In those cases, Mozilla provides a detailed guide on how to see all the fonts gets loaded in a page. By using [https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Open_the_Inspector Page Inspector], find out [https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Edit_fonts#all_fonts_on_page all the fonts] that are being loaded on that particular page. Removing fonts other than '''Noto Sans''' from the system will resolve the issue permanently.<br />
<br />
There will be some fonts that have been installed as dependency of other package. For example, {{Pkg|chromium}} installs {{Pkg|ttf-liberation}} as dependency, which loads itself in some Firefox pages automatically and breaks Bengali fonts on those pages. To solve this issue:<br />
<br />
{{Warning|This will briefly put your system in an incomplete state. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
* Temporarily forcibly remove {{Pkg|ttf-liberation}}:<br />
: {{bc|# pacman -R --nodeps --nodeps ttf-liberation}}<br />
* Launch Firefox and reload the problem website.<br />
* Install {{Pkg|ttf-liberation}} once more, as it is a hard Chromium dependency:<br />
: {{bc|# pacman -S --asdeps ttf-liberation}}<br />
<br />
=== Web Speech API has no voices ===<br />
<br />
Firefox uses for text to speech (tts) speechd. You can use the command {{ic|spd-say "some test sentence"}} to test if it reads the text or {{ic|spd-say -L}} to get a list of the voices. If there are no voices, too, you can install some with the package {{Pkg|espeak-ng}}. If they do not work out of the box, you maybe have to configure them. You can use the {{ic|spd-conf}} command or edit the config file {{ic|.config/speech-dispatcher/speechd.conf}}. There should be the following lines active (without # in front of it):<br />
<br />
AddModule "espeak-ng" "sd_espeak-ng" "espeak-ng.conf"<br />
DefaultModule espeak-ng<br />
<br />
== See also ==<br />
<br />
* [https://www.mozilla.org/firefox/ Official website]<br />
* [https://www.mozilla.org/ Mozilla Foundation]<br />
* [[MozillaWiki:Firefox]]<br />
* [[Wikipedia:Mozilla Firefox]]<br />
* [https://addons.mozilla.org/ Firefox Add-ons]<br />
* [https://addons.mozilla.org/firefox/themes/ Firefox themes]<br />
* [https://ftp.mozilla.org/pub/firefox/releases/ Mozilla's FTP]<br />
* [http://forums.mozillazine.org/ mozillaZine] unofficial forums</div>Progandyhttps://wiki.archlinux.org/index.php?title=Aurweb_RPC_interface&diff=725419Aurweb RPC interface2022-04-04T18:30:45Z<p>Progandy: /* Limitations */ Added note about metadata archives</p>
<hr />
<div>[[Category:Package management]]<br />
[[Category:Arch projects]]<br />
[[es:Aurweb RPC interface]]<br />
[[ja:Aurweb RPC インターフェース]]<br />
[[pt:Aurweb RPC interface]]<br />
{{Related articles start}}<br />
{{Related|Official repositories web interface}}<br />
{{Related articles end}}<br />
The [https://aur.archlinux.org/rpc Aurweb RPC interface] is a lightweight [[Wikipedia:Remote procedure call|RPC]] interface for the [[AUR]]. Queries are sent as HTTP GET requests and the server responds with [https://www.json.org/ JSON].<br />
{{Note|This article describes v5 of the RPC Interface API, as updated with AUR v4.7.0 on July 7, 2018.}}<br />
<br />
== API usage ==<br />
<br />
=== Query types ===<br />
<br />
There are two query types: <br />
<br />
* search<br />
* info<br />
<br />
==== search ====<br />
<br />
Package searches can be performed by issuing requests of the form:<br />
<br />
/rpc/?v=5&type=search&by=''field''&arg=''keywords''<br />
<br />
where {{ic|''keywords''}} is the search argument and {{ic|''field''}} is one of the following values:<br />
<br />
* {{ic|name}} (search by package name only)<br />
* {{ic|name-desc}} (search by package name and description)<br />
* {{ic|maintainer}} (search by package maintainer)<br />
* {{ic|depends}} (search for packages that depend on keywords)<br />
* {{ic|makedepends}} (search for packages that makedepend on keywords)<br />
* {{ic|optdepends}} (search for packages that optdepend on keywords)<br />
* {{ic|checkdepends}} (search for packages that checkdepend on keywords)<br />
<br />
The {{ic|by}} parameter can be skipped and defaults to {{ic|name-desc}}.<br />
Possible return types are {{ic|search}} and {{ic|error}}.<br />
<br />
If a maintainer search is performed and the search argument is left empty, a list of orphan packages is returned.<br />
<br />
Examples:<br />
<br />
Search for {{ic|foobar}}:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar</nowiki><br />
<br />
Search for packages maintained by {{ic|john}}:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john</nowiki><br />
<br />
Search for packages that have {{ic|foobar}} as `makedepends`:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&by=makedepends&arg=foobar</nowiki><br />
<br />
Search with callback:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103</nowiki><br />
<br />
==== info ====<br />
<br />
Package information can be performed by issuing requests of the form:<br />
<br />
/rpc/?v=5&type=info&arg[]=''pkg1''&arg[]=''pkg2''&…<br />
<br />
where {{ic|''pkg1''}}, {{ic|''pkg2''}}, … are the exact matches of names of packages to retrieve package details for.<br />
<br />
Possible return types are {{ic|multiinfo}} and {{ic|error}}.<br />
<br />
Examples:<br />
<br />
Info for single {{ic|foobar}} package:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar</nowiki><br />
<br />
Info for multiple {{ic|foobar}} and {{ic|bar}} packages:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar&arg[]=bar</nowiki><br />
<br />
=== Return types ===<br />
<br />
The return payload is of one format and currently has three main types. The response will always return a type so that the user can determine if the result of an operation was an error or not.<br />
<br />
The format of the return payload is:<br />
{"version":5,"type":''ReturnType'',"resultcount":0,"results":''ReturnData''}<br />
<br />
{{ic|''ReturnType''}} is a string, and the value is one of: <br />
<br />
* {{ic|search}}<br />
* {{ic|multiinfo}}<br />
* {{ic|error}}<br />
<br />
==== return data ====<br />
<br />
The type of {{ic|''ReturnData''}} is an array of dictionary objects for the {{ic|search}} and {{ic|multiinfo}} {{ic|''ReturnType''}}, and an empty array for {{ic|error}} {{ic|''ReturnType''}}.<br />
<br />
For the {{ic|''ReturnType''}} {{ic|''search''}}, {{ic|''ReturnData''}} may contain the following fields:<br />
<br />
* {{ic|ID}}<br />
* {{ic|Name}}<br />
* {{ic|PackageBaseID}}<br />
* {{ic|PackageBase}}<br />
* {{ic|Version}}<br />
* {{ic|Description}}<br />
* {{ic|URL}}<br />
* {{ic|NumVotes}}<br />
* {{ic|Popularity}}<br />
* {{ic|OutOfDate}}<br />
* {{ic|Maintainer}}<br />
* {{ic|FirstSubmitted}}<br />
* {{ic|LastModified}}<br />
* {{ic|URLPath}}<br />
<br />
For the {{ic|''ReturnType''}} {{ic|''info''}} and {{ic|''multiinfo''}}, {{ic|''ReturnData''}} may additionally contain the following fields:<br />
<br />
* {{ic|Depends}}<br />
* {{ic|MakeDepends}}<br />
* {{ic|OptDepends}}<br />
* {{ic|CheckDepends}}<br />
* {{ic|Conflicts}}<br />
* {{ic|Provides}}<br />
* {{ic|Replaces}}<br />
* {{ic|Groups}}<br />
* {{ic|License}}<br />
* {{ic|Keywords}}<br />
<br />
Fields that a package does not contain will be omitted from the output.<br />
<br />
==== error ====<br />
<br />
The error type has an error response string as the return value. An error response can be returned from either a {{ic|search}} or an {{ic|info}} query type.<br />
<br />
Example of {{ic|''ReturnType''}} {{ic|error}}:<br />
{"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}<br />
<br />
==== search ====<br />
<br />
The search type is the result returned from a search request operation.<br />
<br />
Example of {{ic|''ReturnType''}} {{ic|search}}:<br />
{"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}<br />
<br />
==== info ====<br />
<br />
The info type is the result returned from an info request operation.<br />
<br />
Example of {{ic|''ReturnType''}} {{ic|multiinfo}}:<br />
<nowiki><br />
{<br />
"version":5,<br />
"type":"multiinfo",<br />
"resultcount":1,<br />
"results":[{<br />
"ID":229417,<br />
"Name":"cower",<br />
"PackageBaseID":44921,<br />
"PackageBase":"cower",<br />
"Version":"14-2",<br />
"Description":"A simple AUR agent with a pretentious name",<br />
"URL":"http:\/\/github.com\/falconindy\/cower",<br />
"NumVotes":590,<br />
"Popularity":24.595536,<br />
"OutOfDate":null,<br />
"Maintainer":"falconindy",<br />
"FirstSubmitted":1293676237,<br />
"LastModified":1441804093,<br />
"URLPath":"\/cgit\/aur.git\/snapshot\/cower.tar.gz",<br />
"Depends":[<br />
"curl",<br />
"openssl",<br />
"pacman",<br />
"yajl"<br />
],<br />
"MakeDepends":[<br />
"perl"<br />
],<br />
"License":[<br />
"MIT"<br />
],<br />
"Keywords":[]<br />
}]<br />
}<br />
</nowiki><br />
<br />
=== jsonp ===<br />
<br />
If you are working with a javascript page, and need a JSON callback mechanism, you can do it.<br />
You just need to provide an additional callback variable. This callback is usually handled via the javascript library, but here is an example.<br />
<br />
Example Query:<br />
<nowiki>https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103</nowiki><br />
<br />
Example Result:<br />
/**/jsonp1192244621103({"version":5,"type":"search","resultcount":1,"results":[{"ID":250608,"Name":"foobar2000","PackageBaseID":37068,"PackageBase":"foobar2000","Version":"1.3.9-1","Description":"An advanced freeware audio player (uses Wine).","URL":"http:\/\/www.foobar2000.org\/","NumVotes":39,"Popularity":0.425966,"OutOfDate":null,"Maintainer":"supermario","FirstSubmitted":1273255356,"LastModified":1448326415,"URLPath":"\/cgit\/aur.git\/snapshot\/foobar2000.tar.gz"}]})<br />
<br />
This would automatically call the JavaScript function {{Ic|jsonp1192244621103}} with the parameter set to the results of the RPC call.<br />
<br />
== Limitations ==<br />
<br />
* HTTP GET requests are limited to URI of 8190 bytes maximum length. However, the official AUR instance running on a nginx server with HTTP/2 uses the [https://nginx.org/en/docs/http/ngx_http_v2_module.html#http2_max_field_size default URI maximum length] limit of 4443 bytes. Info requests with more than about 200 packages as an argument will need to be split.<br />
* Search queries must be at least two characters long.<br />
* Searches will fail if they contain 5000 or more results.<br />
* The API rate is limited to a maximum of 4000 requests per day per IP.<br />
<br />
{{Note|Some of the data is available in [https://lists.archlinux.org/pipermail/aur-general/2021-November/036659.html AUR metadata archives] for bulk processing.}}<br />
<br />
== Reference clients ==<br />
<br />
Sometimes things are easier to understand with examples. A few reference implementations (jQuery, python, ruby) are available at the following URL: https://github.com/cactus/random/tree/2b72a1723bfc8ae64eed6a3c40cb154accae3974/aurjson_examples</div>Progandyhttps://wiki.archlinux.org/index.php?title=Iwd&diff=714556Iwd2022-01-29T21:42:33Z<p>Progandy: /* iwctl */ fix grammar and spelling</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[ja:Iwd]]<br />
[[pt:Iwd]]<br />
[[ru:Iwd]]<br />
[[zh-hans:Iwd]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|wpa_supplicant}}<br />
{{Related articles end}}<br />
[https://iwd.wiki.kernel.org/ iwd] (iNet wireless daemon) is a wireless daemon for Linux written by Intel. The core goal of the project is to optimize resource utilization by not depending on any external libraries and instead utilizing features provided by the Linux Kernel to the maximum extent possible.<br />
<br />
iwd can work in standalone mode or in combination with comprehensive network managers like [[ConnMan]], [[systemd-networkd]] and [[NetworkManager#Using iwd as the Wi-Fi backend|NetworkManager]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|iwd}} package.<br />
<br />
== Usage ==<br />
<br />
The {{Pkg|iwd}} package provides the client program {{ic|iwctl}}, the daemon {{ic|iwd}} and the Wi-Fi monitoring tool {{ic|iwmon}}.<br />
<br />
[[Start/enable]] {{ic|iwd.service}} so it can be controlled using the {{ic|iwctl}} command.<br />
<br />
=== iwctl ===<br />
<br />
{{Note|As of version 1.23, only root and members of the {{ic|netdev}} or the {{ic|wheel}} group are allowed to access iwd. In order to use {{ic|iwctl}}, you need to add your user to one of those groups.}}<br />
<br />
To get an interactive prompt do:<br />
<br />
$ iwctl<br />
<br />
The interactive prompt is then displayed with a prefix of {{ic|[iwd]#}}.<br />
<br />
{{Tip|<br />
* In the {{ic|iwctl}} prompt you can auto-complete commands and device names by hitting {{ic|Tab}}.<br />
* To exit the interactive prompt, send [[Wikipedia:EOF character|EOF]] by pressing {{ic|Ctrl+d}}.<br />
* You can use all commands as command line arguments without entering an interactive prompt. For example: {{ic|iwctl device wlan0 show}}.<br />
}}<br />
<br />
To list all available commands:<br />
<br />
[iwd]# help<br />
<br />
==== Connect to a network ====<br />
<br />
First, if you do not know your wireless device name, list all Wi-Fi devices:<br />
<br />
[iwd]# device list<br />
<br />
Then, to scan for networks:<br />
<br />
[iwd]# station ''device'' scan<br />
<br />
You can then list all available networks:<br />
<br />
[iwd]# station ''device'' get-networks<br />
<br />
Finally, to connect to a network:<br />
<br />
[iwd]# station ''device'' connect ''SSID''<br />
<br />
{{Tip|The user interface supports autocomplete, by typing {{ic|station }} and {{ic|Tab}} {{ic|Tab}}, the available devices are displayed, type the first letters of the device and {{ic|Tab}} to complete. The same way, type {{ic|connect }} and {{ic|Tab}} {{ic|Tab}} in order to have the list of available networks displayed. Then, type the first letters of the chosen network followed by {{ic|Tab}} in order to complete the command.}} <br />
<br />
If a passphrase is required, you will be prompted to enter it. Alternatively, you can supply it as a command line argument:<br />
<br />
$ iwctl --passphrase ''passphrase'' station ''device'' connect ''SSID''<br />
<br />
{{Note|<br />
* {{ic|iwd}} automatically stores network passphrases in the {{ic|/var/lib/iwd}} directory and uses them to auto-connect in the future. See [[#Network configuration]].<br />
* To connect to a network with spaces in the SSID, the network name should be double quoted when connecting.<br />
* iwd only supports PSK pass-phrases from 8 to 63 ASCII-encoded characters. The following error message will be given if the requirements are not met: {{ic|PMK generation failed. Ensure Crypto Engine is properly configured}}.<br />
}}<br />
<br />
==== Connect to a network using WPS/WSC ====<br />
<br />
If your network is configured such that you can connect to it by pressing a button ([[Wikipedia:Wi-Fi Protected Setup]]), check first that your network device is also capable of using this setup procedure.<br />
<br />
[iwd]# wsc list<br />
<br />
Then, provided that your device appeared in the above list,<br />
<br />
[iwd]# wsc ''device'' push-button<br />
<br />
and push the button on your router. The procedure works also if the button was pushed beforehand, less than 2 minutes earlier.<br />
<br />
If your network requires to validate a PIN number to connect that way, check the {{ic|help}} command output to see how to provide the right options to the {{ic|wsc}} command.<br />
<br />
==== Disconnect from a network ====<br />
<br />
To disconnect from a network:<br />
<br />
[iwd]# station ''device'' disconnect<br />
<br />
==== Show device and connection information ====<br />
<br />
To display the details of a WiFi device, like MAC address:<br />
<br />
[iwd]# device ''device'' show<br />
<br />
To display the connection state, including the connected network of a Wi-Fi device:<br />
<br />
[iwd]# station ''device'' show<br />
<br />
==== Manage known networks ====<br />
<br />
To list networks you have connected to previously:<br />
<br />
[iwd]# known-networks list<br />
<br />
To forget a known network:<br />
<br />
[iwd]# known-networks ''SSID'' forget<br />
<br />
== Network configuration ==<br />
<br />
By default, ''iwd'' stores the network configuration in the directory {{ic|/var/lib/iwd}}. The configuration file is named as {{ic|''network''.''type''}}, where ''network'' is the network SSID and ''.type'' is the network type, either ''.open'', ''.psk'' or ''.8021x''. The file is used to store the encrypted {{ic|PreSharedKey}} and optionally the cleartext {{ic|Passphrase}} and can also be created by the user without invoking {{ic|iwctl}}. The file can be used for other configuration pertaining to that network SSID as well. For more settings, see {{man|5|iwd.network}}.<br />
<br />
{{Note|In string values, including identities and passwords, certain characters may be backslash-escaped. Leading spaces, \n, \r, and literal backslashes must be escaped. See {{man|5|iwd.network}}.}}<br />
<br />
=== WPA-PSK ===<br />
<br />
A minimal example file to connect to a WPA-PSK or WPA2-PSK secured network with SSID "spaceship" and passphrase "test1234":<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295}}<br />
<br />
{{Note|The SSID of the network is used as a filename only when it contains only alphanumeric characters or one of {{ic|- _}}. If it contains any other characters, the name will instead be an {{ic|1==}}-character followed by the hex-encoded version of the SSID.<br />
}}<br />
<br />
To calculate the pre-shared key from the passphrase, one of these two methods can be used:<br />
* Enter the passphrase in cleartext in the configuration file:<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
Passphrase=test1234}}<br />
The pre-shared key will be appended to the file at the first connect:<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
Passphrase=test1234<br />
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295}}<br />
<br />
* Or the pre-shared key can be calculated from the SSID and the passphrase using ''wpa_passphrase'' (from {{Pkg|wpa_supplicant}}) or {{AUR|wpa-psk}}. See [[wpa_supplicant#Connecting with wpa_passphrase]] for more details.<br />
<br />
=== WPA Enterprise ===<br />
<br />
==== EAP-PWD ====<br />
<br />
For connecting to a EAP-PWD protected enterprise access point you need to create a file called: {{ic|''essid''.8021x}} in the {{ic|/var/lib/iwd}} directory with the following content:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=PWD<br />
EAP-Identity=''your_enterprise_email''<br />
EAP-Password=''your_password''<br />
<br />
[Settings]<br />
AutoConnect=True<br />
}}<br />
<br />
If you do not want autoconnect to the AP you can set the option to False and connect manually to the access point via {{ic|iwctl}}. The same applies to the password, if you do not want to store it plaintext leave the option out of the file and just connect to the enterprise AP.<br />
<br />
==== EAP-PEAP ====<br />
<br />
Like EAP-PWD, you also need to create a {{ic|''essid''.8021x}} file in the directory. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses MSCHAPv2 password authentication:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=PEAP<br />
EAP-Identity=anonymous@realm.edu<br />
EAP-PEAP-CACert=/path/to/root.crt<br />
EAP-PEAP-ServerDomainMask=radius.realm.edu<br />
EAP-PEAP-Phase2-Method=MSCHAPV2<br />
EAP-PEAP-Phase2-Identity=johndoe@realm.edu<br />
EAP-PEAP-Phase2-Password=hunter2<br />
<br />
[Settings]<br />
AutoConnect=true<br />
}}<br />
<br />
MsCHAPv2 passwords can also be stored as a encrypted hash. The correct md4 hash can be calculated with: (insert an EOF after your password, do not hit enter)<br />
$ iconv -t utf16le | openssl md4<br />
The resulting hash needs to be stored inside the {{ic|EAP-PEAP-Phase2-Password-Hash}} key.<br />
<br />
{{Tip|If you are planning on using ''eduroam'', see also [[#eduroam]].}}<br />
<br />
==== TTLS-PAP ====<br />
<br />
Like EAP-PWD, you also need to create a {{ic|''essid''.8021x}} file in the directory. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses PAP password authentication:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=TTLS<br />
EAP-Identity=anonymous@uni-test.de<br />
EAP-TTLS-CACert=cert.pem<br />
EAP-TTLS-ServerDomainMask=*.uni-test.de<br />
EAP-TTLS-Phase2-Method=Tunneled-PAP<br />
EAP-TTLS-Phase2-Identity=user<br />
EAP-TTLS-Phase2-Password=password<br />
<br />
[Settings]<br />
AutoConnect=true<br />
}}<br />
<br />
==== eduroam ====<br />
<br />
eduroam offers a [https://cat.eduroam.org/ configuration assistant tool (CAT)], which unfortunately does not support iwd. However, the installer, which you can download by clicking on the download button then selecting your university, is just a Python script. It is easy to extract the necessary configuration options, including the certificate and server domain mask.<br />
<br />
The following table contains a mapping of iwd configuration options to eduroam CAT install script variables.<br />
<br />
{| class="wikitable<br />
! Iwd Configuration Option !! CAT Script Variable<br />
|-<br />
| file name || one of {{ic|Config.ssids}}<br />
|-<br />
| {{ic|EAP-Method}} || {{ic|Config.eap_outer}}<br />
|-<br />
| {{ic|EAP-Identity}} || {{ic|Config.anonymous_identity}}<br />
|-<br />
| {{ic|EAP-PEAP-CACert}} || {{ic|Config.CA}}<br />
|-<br />
| {{ic|EAP-PEAP-ServerDomainMask}} || one of {{ic|Config.servers}}<br />
|-<br />
| {{ic|EAP-PEAP-Phase2-Method}} || {{ic|Config.eap_inner}}<br />
|-<br />
| {{ic|EAP-PEAP-Phase2-Identity}} || username@{{ic|Config.user_realm}}<br />
|}<br />
<br />
{{Note|<br />
* {{ic|EAP-Identity}} may not be required by your eduroam provider, in which case you might have to use {{ic|anonymous@''Config.user_realm''}} in this field.<br />
* If your {{ic|EAP-PEAP-ServerDomainMask}} starts with {{ic|DNS:}}, use only the part after {{ic|DNS:}}.<br />
}}<br />
<br />
==== Other cases ====<br />
<br />
More example tests can be [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests found in the test cases] of the upstream repository.<br />
<br />
== Optional configuration ==<br />
<br />
File {{ic|/etc/iwd/main.conf}} can be used for main configuration. See {{man|5|iwd.config}}.<br />
<br />
=== Disable auto-connect for a particular network ===<br />
<br />
Create / edit file {{ic|/var/lib/iwd/''network''.''type''}}. Add the following section to it:<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk (for example)|2=<br />
[Settings]<br />
AutoConnect=false<br />
}}<br />
<br />
=== Disable periodic scan for available networks ===<br />
<br />
By default when {{ic|iwd}} is in disconnected state, it periodically scans for available networks. To disable periodic scan (so as to always scan manually), create / edit file {{ic|/etc/iwd/main.conf}} and add the following section to it:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Scan]<br />
DisablePeriodicScan=true<br />
}}<br />
<br />
=== Enable built-in network configuration ===<br />
<br />
Since version 0.19, iwd can assign IP address(es) and set up routes using a built-in DHCP client or with static configuration. It is a good alternative to [[Network configuration#DHCP|standalone DHCP clients]].<br />
<br />
To activate iwd's network configuration feature, create/edit {{ic|/etc/iwd/main.conf}} and add the following section to it:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[General]<br />
EnableNetworkConfiguration=true<br />
}}<br />
<br />
There is also ability to set route metric with {{ic|RoutePriorityOffset}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
RoutePriorityOffset=300<br />
}}<br />
<br />
==== IPv6 support ====<br />
<br />
Since version 1.10, iwd supports IPv6, but it is disabled by default. To enable it, add the following to the configuration file:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
EnableIPv6=true<br />
}}<br />
<br />
This setting is required whether you want to use DHCPv6 or static IPv6 configuration. It can also be set on a per-network basis.<br />
<br />
==== Setting static IP address in network configuration ====<br />
<br />
Add the following section to {{ic|/var/lib/iwd/''network''.''type''}} file. For example:<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[IPv4]<br />
Address=192.168.1.10<br />
Netmask=255.255.255.0<br />
Gateway=192.168.1.1<br />
Broadcast=192.168.1.255<br />
DNS=192.168.1.1<br />
}}<br />
<br />
==== Select DNS manager ====<br />
<br />
At the moment, iwd supports two DNS managers—[[systemd-resolved]] and [[resolvconf]].<br />
<br />
Add the following section to {{ic|/etc/iwd/main.conf}} for {{ic|systemd-resolved}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
NameResolvingService=systemd<br />
}}<br />
<br />
For {{ic|resolvconf}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
NameResolvingService=resolvconf<br />
}}<br />
<br />
{{Note|If not specified, [[systemd-resolved]] is used as default.}}<br />
<br />
=== Deny console (local) user from modifying the settings ===<br />
<br />
By default {{ic|iwd}} D-Bus interface allows ''any'' console user to connect to {{ic|iwd}} daemon and modify the settings, even if that user is not a ''root'' user.<br />
<br />
If you do not want to allow console user to modify the settings but allow reading the status information, then create a D-Bus configuration file as follows.<br />
<br />
{{hc|/etc/dbus-1/system.d/iwd-strict.conf|<nowiki><br />
<!-- prevent local users from changing iwd settings, but allow<br />
reading status information. overrides some part of<br />
/usr/share/dbus-1/system.d/iwd-dbus.conf. --><br />
<br />
<!-- This configuration file specifies the required security policies<br />
for iNet Wireless Daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<policy at_console="true"><br />
<deny send_destination="net.connman.iwd"/><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="GetAll" /><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="Get" /><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.ObjectManager" send_member="GetManagedObjects" /><br />
<allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="RegisterSignalLevelAgent" /><br />
<allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="UnregisterSignalLevelAgent" /><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
{{Tip|Remove ''<allow>'' lines above to deny reading the status information as well.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Verbose TLS debugging ===<br />
<br />
This can be useful, if you have trouble setting up MSCHAPv2 or TTLS. You can set the following [[environment variable]] via a [[drop-in snippet]]:<br />
<br />
{{hc|/etc/systemd/system/iwd.service.d/tls-debug.conf|2=<br />
[Service]<br />
Environment=IWD_TLS_DEBUG=TRUE<br />
}}<br />
<br />
Check the iwd logs afterwards by running {{ic|journalctl -u iwd.service}} as root.<br />
<br />
=== Restarting iwd.service after boot ===<br />
<br />
On some machines, it is reported that {{ic|iwd.service}} has to be restarted to work after boot. See {{Bug|63912}} and [https://bbs.archlinux.org/viewtopic.php?id=251432 thread 251432]. This probably occurs because the Linux kernel and services start too early and ''iwd'' starts before wireless network card powers on. As a workaround, [[extend the unit]] to add a delay:<br />
<br />
[Service]<br />
ExecStartPre=/usr/bin/sleep 2<br />
<br />
Then [[reload]] the ''systemd'' manager configuration.<br />
<br />
=== Connect issues after reboot ===<br />
<br />
A low entropy pool can cause connection problems in particular noticeable after reboot. See [[Random number generation]] for suggestions to increase the entropy pool.<br />
<br />
=== Wireless device is not renamed by udev ===<br />
<br />
Since version 1.0, iwd disables predictable renaming of wireless device. It installs the following systemd network link configuration file which prevents udev from renaming the interface to {{ic|wlp#s#}}:<br />
<br />
{{hc|1=/usr/lib/systemd/network/80-iwd.link|2=<br />
[Match]<br />
Type=wlan<br />
<br />
[Link]<br />
NamePolicy=keep kernel<br />
}}<br />
<br />
As a result the wireless link name {{ic|wlan#}} is kept after boot. This resolved a race condition between ''iwd'' and [[udev]] on interface renaming as explained in [https://iwd.wiki.kernel.org/interface_lifecycle#udev_interface_renaming iwd udev interface renaming].<br />
<br />
If this results in issues try masking it with:<br />
<br />
# ln -s /dev/null /etc/systemd/network/80-iwd.link<br />
<br />
=== No DHCP in AP mode ===<br />
<br />
Clients may not receive an IP address via DHCP when connecting to ''iwd'' in AP mode. It is therefore necessary to enable network configuration by ''iwd'' on managed interfaces:<br />
<br />
{{hc|1=/etc/iwd/main.conf|2=<br />
[General]<br />
EnableNetworkConfiguration=True<br />
}}<br />
<br />
The mentioned file has to be created if it does not already exist.<br />
<br />
== See also ==<br />
<br />
* [https://iwd.wiki.kernel.org/gettingstarted Getting Started with iwd]<br />
* [https://iwd.wiki.kernel.org/networkconfigurationsettings Network Configuration Settings]<br />
* [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests More Examples for WPA Enterprise]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=237074 The IWD thread on the Arch Linux Forums]<br />
* [https://www.youtube.com/watch?v=F2Q86cphKDo 2017 Update on new WiFi daemon for Linux by Marcel Holtmann - YouTube]<br />
* [https://www.youtube.com/watch?v=QIqT2obSPDk The New Wi-Fi Experience for Linux - Marcel Holtmann, Intel - YouTube]<br />
* [https://iwd.wiki.kernel.org/ap_mode How to set up a simple access point with iwd]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Iwd&diff=714555Iwd2022-01-29T21:37:37Z<p>Progandy: /* Usage */ Add a note about iwctl access restrictions.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[ja:Iwd]]<br />
[[pt:Iwd]]<br />
[[ru:Iwd]]<br />
[[zh-hans:Iwd]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|wpa_supplicant}}<br />
{{Related articles end}}<br />
[https://iwd.wiki.kernel.org/ iwd] (iNet wireless daemon) is a wireless daemon for Linux written by Intel. The core goal of the project is to optimize resource utilization by not depending on any external libraries and instead utilizing features provided by the Linux Kernel to the maximum extent possible.<br />
<br />
iwd can work in standalone mode or in combination with comprehensive network managers like [[ConnMan]], [[systemd-networkd]] and [[NetworkManager#Using iwd as the Wi-Fi backend|NetworkManager]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|iwd}} package.<br />
<br />
== Usage ==<br />
<br />
The {{Pkg|iwd}} package provides the client program {{ic|iwctl}}, the daemon {{ic|iwd}} and the Wi-Fi monitoring tool {{ic|iwmon}}.<br />
<br />
[[Start/enable]] {{ic|iwd.service}} so it can be controlled using the {{ic|iwctl}} command.<br />
<br />
=== iwctl ===<br />
<br />
{{Note|As of version 1.23, only root and members of the {{ic|netdev}} or {{ic|wheel}} groups are allowed to access iwd. To use {{ic|iwctl}}, you need to add you user to one of those groups.}}<br />
<br />
To get an interactive prompt do:<br />
<br />
$ iwctl<br />
<br />
The interactive prompt is then displayed with a prefix of {{ic|[iwd]#}}.<br />
<br />
{{Tip|<br />
* In the {{ic|iwctl}} prompt you can auto-complete commands and device names by hitting {{ic|Tab}}.<br />
* To exit the interactive prompt, send [[Wikipedia:EOF character|EOF]] by pressing {{ic|Ctrl+d}}.<br />
* You can use all commands as command line arguments without entering an interactive prompt. For example: {{ic|iwctl device wlan0 show}}.<br />
}}<br />
<br />
To list all available commands:<br />
<br />
[iwd]# help<br />
<br />
==== Connect to a network ====<br />
<br />
First, if you do not know your wireless device name, list all Wi-Fi devices:<br />
<br />
[iwd]# device list<br />
<br />
Then, to scan for networks:<br />
<br />
[iwd]# station ''device'' scan<br />
<br />
You can then list all available networks:<br />
<br />
[iwd]# station ''device'' get-networks<br />
<br />
Finally, to connect to a network:<br />
<br />
[iwd]# station ''device'' connect ''SSID''<br />
<br />
{{Tip|The user interface supports autocomplete, by typing {{ic|station }} and {{ic|Tab}} {{ic|Tab}}, the available devices are displayed, type the first letters of the device and {{ic|Tab}} to complete. The same way, type {{ic|connect }} and {{ic|Tab}} {{ic|Tab}} in order to have the list of available networks displayed. Then, type the first letters of the chosen network followed by {{ic|Tab}} in order to complete the command.}} <br />
<br />
If a passphrase is required, you will be prompted to enter it. Alternatively, you can supply it as a command line argument:<br />
<br />
$ iwctl --passphrase ''passphrase'' station ''device'' connect ''SSID''<br />
<br />
{{Note|<br />
* {{ic|iwd}} automatically stores network passphrases in the {{ic|/var/lib/iwd}} directory and uses them to auto-connect in the future. See [[#Network configuration]].<br />
* To connect to a network with spaces in the SSID, the network name should be double quoted when connecting.<br />
* iwd only supports PSK pass-phrases from 8 to 63 ASCII-encoded characters. The following error message will be given if the requirements are not met: {{ic|PMK generation failed. Ensure Crypto Engine is properly configured}}.<br />
}}<br />
<br />
==== Connect to a network using WPS/WSC ====<br />
<br />
If your network is configured such that you can connect to it by pressing a button ([[Wikipedia:Wi-Fi Protected Setup]]), check first that your network device is also capable of using this setup procedure.<br />
<br />
[iwd]# wsc list<br />
<br />
Then, provided that your device appeared in the above list,<br />
<br />
[iwd]# wsc ''device'' push-button<br />
<br />
and push the button on your router. The procedure works also if the button was pushed beforehand, less than 2 minutes earlier.<br />
<br />
If your network requires to validate a PIN number to connect that way, check the {{ic|help}} command output to see how to provide the right options to the {{ic|wsc}} command.<br />
<br />
==== Disconnect from a network ====<br />
<br />
To disconnect from a network:<br />
<br />
[iwd]# station ''device'' disconnect<br />
<br />
==== Show device and connection information ====<br />
<br />
To display the details of a WiFi device, like MAC address:<br />
<br />
[iwd]# device ''device'' show<br />
<br />
To display the connection state, including the connected network of a Wi-Fi device:<br />
<br />
[iwd]# station ''device'' show<br />
<br />
==== Manage known networks ====<br />
<br />
To list networks you have connected to previously:<br />
<br />
[iwd]# known-networks list<br />
<br />
To forget a known network:<br />
<br />
[iwd]# known-networks ''SSID'' forget<br />
<br />
== Network configuration ==<br />
<br />
By default, ''iwd'' stores the network configuration in the directory {{ic|/var/lib/iwd}}. The configuration file is named as {{ic|''network''.''type''}}, where ''network'' is the network SSID and ''.type'' is the network type, either ''.open'', ''.psk'' or ''.8021x''. The file is used to store the encrypted {{ic|PreSharedKey}} and optionally the cleartext {{ic|Passphrase}} and can also be created by the user without invoking {{ic|iwctl}}. The file can be used for other configuration pertaining to that network SSID as well. For more settings, see {{man|5|iwd.network}}.<br />
<br />
{{Note|In string values, including identities and passwords, certain characters may be backslash-escaped. Leading spaces, \n, \r, and literal backslashes must be escaped. See {{man|5|iwd.network}}.}}<br />
<br />
=== WPA-PSK ===<br />
<br />
A minimal example file to connect to a WPA-PSK or WPA2-PSK secured network with SSID "spaceship" and passphrase "test1234":<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295}}<br />
<br />
{{Note|The SSID of the network is used as a filename only when it contains only alphanumeric characters or one of {{ic|- _}}. If it contains any other characters, the name will instead be an {{ic|1==}}-character followed by the hex-encoded version of the SSID.<br />
}}<br />
<br />
To calculate the pre-shared key from the passphrase, one of these two methods can be used:<br />
* Enter the passphrase in cleartext in the configuration file:<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
Passphrase=test1234}}<br />
The pre-shared key will be appended to the file at the first connect:<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
Passphrase=test1234<br />
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295}}<br />
<br />
* Or the pre-shared key can be calculated from the SSID and the passphrase using ''wpa_passphrase'' (from {{Pkg|wpa_supplicant}}) or {{AUR|wpa-psk}}. See [[wpa_supplicant#Connecting with wpa_passphrase]] for more details.<br />
<br />
=== WPA Enterprise ===<br />
<br />
==== EAP-PWD ====<br />
<br />
For connecting to a EAP-PWD protected enterprise access point you need to create a file called: {{ic|''essid''.8021x}} in the {{ic|/var/lib/iwd}} directory with the following content:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=PWD<br />
EAP-Identity=''your_enterprise_email''<br />
EAP-Password=''your_password''<br />
<br />
[Settings]<br />
AutoConnect=True<br />
}}<br />
<br />
If you do not want autoconnect to the AP you can set the option to False and connect manually to the access point via {{ic|iwctl}}. The same applies to the password, if you do not want to store it plaintext leave the option out of the file and just connect to the enterprise AP.<br />
<br />
==== EAP-PEAP ====<br />
<br />
Like EAP-PWD, you also need to create a {{ic|''essid''.8021x}} file in the directory. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses MSCHAPv2 password authentication:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=PEAP<br />
EAP-Identity=anonymous@realm.edu<br />
EAP-PEAP-CACert=/path/to/root.crt<br />
EAP-PEAP-ServerDomainMask=radius.realm.edu<br />
EAP-PEAP-Phase2-Method=MSCHAPV2<br />
EAP-PEAP-Phase2-Identity=johndoe@realm.edu<br />
EAP-PEAP-Phase2-Password=hunter2<br />
<br />
[Settings]<br />
AutoConnect=true<br />
}}<br />
<br />
MsCHAPv2 passwords can also be stored as a encrypted hash. The correct md4 hash can be calculated with: (insert an EOF after your password, do not hit enter)<br />
$ iconv -t utf16le | openssl md4<br />
The resulting hash needs to be stored inside the {{ic|EAP-PEAP-Phase2-Password-Hash}} key.<br />
<br />
{{Tip|If you are planning on using ''eduroam'', see also [[#eduroam]].}}<br />
<br />
==== TTLS-PAP ====<br />
<br />
Like EAP-PWD, you also need to create a {{ic|''essid''.8021x}} file in the directory. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses PAP password authentication:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=TTLS<br />
EAP-Identity=anonymous@uni-test.de<br />
EAP-TTLS-CACert=cert.pem<br />
EAP-TTLS-ServerDomainMask=*.uni-test.de<br />
EAP-TTLS-Phase2-Method=Tunneled-PAP<br />
EAP-TTLS-Phase2-Identity=user<br />
EAP-TTLS-Phase2-Password=password<br />
<br />
[Settings]<br />
AutoConnect=true<br />
}}<br />
<br />
==== eduroam ====<br />
<br />
eduroam offers a [https://cat.eduroam.org/ configuration assistant tool (CAT)], which unfortunately does not support iwd. However, the installer, which you can download by clicking on the download button then selecting your university, is just a Python script. It is easy to extract the necessary configuration options, including the certificate and server domain mask.<br />
<br />
The following table contains a mapping of iwd configuration options to eduroam CAT install script variables.<br />
<br />
{| class="wikitable<br />
! Iwd Configuration Option !! CAT Script Variable<br />
|-<br />
| file name || one of {{ic|Config.ssids}}<br />
|-<br />
| {{ic|EAP-Method}} || {{ic|Config.eap_outer}}<br />
|-<br />
| {{ic|EAP-Identity}} || {{ic|Config.anonymous_identity}}<br />
|-<br />
| {{ic|EAP-PEAP-CACert}} || {{ic|Config.CA}}<br />
|-<br />
| {{ic|EAP-PEAP-ServerDomainMask}} || one of {{ic|Config.servers}}<br />
|-<br />
| {{ic|EAP-PEAP-Phase2-Method}} || {{ic|Config.eap_inner}}<br />
|-<br />
| {{ic|EAP-PEAP-Phase2-Identity}} || username@{{ic|Config.user_realm}}<br />
|}<br />
<br />
{{Note|<br />
* {{ic|EAP-Identity}} may not be required by your eduroam provider, in which case you might have to use {{ic|anonymous@''Config.user_realm''}} in this field.<br />
* If your {{ic|EAP-PEAP-ServerDomainMask}} starts with {{ic|DNS:}}, use only the part after {{ic|DNS:}}.<br />
}}<br />
<br />
==== Other cases ====<br />
<br />
More example tests can be [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests found in the test cases] of the upstream repository.<br />
<br />
== Optional configuration ==<br />
<br />
File {{ic|/etc/iwd/main.conf}} can be used for main configuration. See {{man|5|iwd.config}}.<br />
<br />
=== Disable auto-connect for a particular network ===<br />
<br />
Create / edit file {{ic|/var/lib/iwd/''network''.''type''}}. Add the following section to it:<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk (for example)|2=<br />
[Settings]<br />
AutoConnect=false<br />
}}<br />
<br />
=== Disable periodic scan for available networks ===<br />
<br />
By default when {{ic|iwd}} is in disconnected state, it periodically scans for available networks. To disable periodic scan (so as to always scan manually), create / edit file {{ic|/etc/iwd/main.conf}} and add the following section to it:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Scan]<br />
DisablePeriodicScan=true<br />
}}<br />
<br />
=== Enable built-in network configuration ===<br />
<br />
Since version 0.19, iwd can assign IP address(es) and set up routes using a built-in DHCP client or with static configuration. It is a good alternative to [[Network configuration#DHCP|standalone DHCP clients]].<br />
<br />
To activate iwd's network configuration feature, create/edit {{ic|/etc/iwd/main.conf}} and add the following section to it:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[General]<br />
EnableNetworkConfiguration=true<br />
}}<br />
<br />
There is also ability to set route metric with {{ic|RoutePriorityOffset}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
RoutePriorityOffset=300<br />
}}<br />
<br />
==== IPv6 support ====<br />
<br />
Since version 1.10, iwd supports IPv6, but it is disabled by default. To enable it, add the following to the configuration file:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
EnableIPv6=true<br />
}}<br />
<br />
This setting is required whether you want to use DHCPv6 or static IPv6 configuration. It can also be set on a per-network basis.<br />
<br />
==== Setting static IP address in network configuration ====<br />
<br />
Add the following section to {{ic|/var/lib/iwd/''network''.''type''}} file. For example:<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[IPv4]<br />
Address=192.168.1.10<br />
Netmask=255.255.255.0<br />
Gateway=192.168.1.1<br />
Broadcast=192.168.1.255<br />
DNS=192.168.1.1<br />
}}<br />
<br />
==== Select DNS manager ====<br />
<br />
At the moment, iwd supports two DNS managers—[[systemd-resolved]] and [[resolvconf]].<br />
<br />
Add the following section to {{ic|/etc/iwd/main.conf}} for {{ic|systemd-resolved}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
NameResolvingService=systemd<br />
}}<br />
<br />
For {{ic|resolvconf}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
NameResolvingService=resolvconf<br />
}}<br />
<br />
{{Note|If not specified, [[systemd-resolved]] is used as default.}}<br />
<br />
=== Deny console (local) user from modifying the settings ===<br />
<br />
By default {{ic|iwd}} D-Bus interface allows ''any'' console user to connect to {{ic|iwd}} daemon and modify the settings, even if that user is not a ''root'' user.<br />
<br />
If you do not want to allow console user to modify the settings but allow reading the status information, then create a D-Bus configuration file as follows.<br />
<br />
{{hc|/etc/dbus-1/system.d/iwd-strict.conf|<nowiki><br />
<!-- prevent local users from changing iwd settings, but allow<br />
reading status information. overrides some part of<br />
/usr/share/dbus-1/system.d/iwd-dbus.conf. --><br />
<br />
<!-- This configuration file specifies the required security policies<br />
for iNet Wireless Daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<policy at_console="true"><br />
<deny send_destination="net.connman.iwd"/><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="GetAll" /><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="Get" /><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.ObjectManager" send_member="GetManagedObjects" /><br />
<allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="RegisterSignalLevelAgent" /><br />
<allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="UnregisterSignalLevelAgent" /><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
{{Tip|Remove ''<allow>'' lines above to deny reading the status information as well.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Verbose TLS debugging ===<br />
<br />
This can be useful, if you have trouble setting up MSCHAPv2 or TTLS. You can set the following [[environment variable]] via a [[drop-in snippet]]:<br />
<br />
{{hc|/etc/systemd/system/iwd.service.d/tls-debug.conf|2=<br />
[Service]<br />
Environment=IWD_TLS_DEBUG=TRUE<br />
}}<br />
<br />
Check the iwd logs afterwards by running {{ic|journalctl -u iwd.service}} as root.<br />
<br />
=== Restarting iwd.service after boot ===<br />
<br />
On some machines, it is reported that {{ic|iwd.service}} has to be restarted to work after boot. See {{Bug|63912}} and [https://bbs.archlinux.org/viewtopic.php?id=251432 thread 251432]. This probably occurs because the Linux kernel and services start too early and ''iwd'' starts before wireless network card powers on. As a workaround, [[extend the unit]] to add a delay:<br />
<br />
[Service]<br />
ExecStartPre=/usr/bin/sleep 2<br />
<br />
Then [[reload]] the ''systemd'' manager configuration.<br />
<br />
=== Connect issues after reboot ===<br />
<br />
A low entropy pool can cause connection problems in particular noticeable after reboot. See [[Random number generation]] for suggestions to increase the entropy pool.<br />
<br />
=== Wireless device is not renamed by udev ===<br />
<br />
Since version 1.0, iwd disables predictable renaming of wireless device. It installs the following systemd network link configuration file which prevents udev from renaming the interface to {{ic|wlp#s#}}:<br />
<br />
{{hc|1=/usr/lib/systemd/network/80-iwd.link|2=<br />
[Match]<br />
Type=wlan<br />
<br />
[Link]<br />
NamePolicy=keep kernel<br />
}}<br />
<br />
As a result the wireless link name {{ic|wlan#}} is kept after boot. This resolved a race condition between ''iwd'' and [[udev]] on interface renaming as explained in [https://iwd.wiki.kernel.org/interface_lifecycle#udev_interface_renaming iwd udev interface renaming].<br />
<br />
If this results in issues try masking it with:<br />
<br />
# ln -s /dev/null /etc/systemd/network/80-iwd.link<br />
<br />
=== No DHCP in AP mode ===<br />
<br />
Clients may not receive an IP address via DHCP when connecting to ''iwd'' in AP mode. It is therefore necessary to enable network configuration by ''iwd'' on managed interfaces:<br />
<br />
{{hc|1=/etc/iwd/main.conf|2=<br />
[General]<br />
EnableNetworkConfiguration=True<br />
}}<br />
<br />
The mentioned file has to be created if it does not already exist.<br />
<br />
== See also ==<br />
<br />
* [https://iwd.wiki.kernel.org/gettingstarted Getting Started with iwd]<br />
* [https://iwd.wiki.kernel.org/networkconfigurationsettings Network Configuration Settings]<br />
* [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests More Examples for WPA Enterprise]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=237074 The IWD thread on the Arch Linux Forums]<br />
* [https://www.youtube.com/watch?v=F2Q86cphKDo 2017 Update on new WiFi daemon for Linux by Marcel Holtmann - YouTube]<br />
* [https://www.youtube.com/watch?v=QIqT2obSPDk The New Wi-Fi Experience for Linux - Marcel Holtmann, Intel - YouTube]<br />
* [https://iwd.wiki.kernel.org/ap_mode How to set up a simple access point with iwd]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Talk:Arch_User_Repository&diff=710525Talk:Arch User Repository2022-01-16T14:43:58Z<p>Progandy: /* Tips and Tricks */ re</p>
<hr />
<div>== contribute to existing package ==<br />
what is the best way to contribute to an existing AUR package? i cloned one and tried to push but it gave me a permission error --[[User:Soloturn|Soloturn]] ([[User talk:Soloturn|talk]]) 16:04, 28 January 2019 (UTC)<br />
<br />
:Users are not allowed to modify something owned by another user. It's no different from cloning a Github repository and trying to push to that. The equivalent of submitting an issue would be leaving a comment with a patch file. The AUR platform in particular allows collaboration features -- you may request that a maintainer grant you push access by adding your name as a co-maintainer. If the package is broken or out of date, see [[Arch User Repository#Foo in the AUR is outdated; what should I do?]]<br />
<br />
:This is possibly something that we should make clear in a FAQ entry. -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 19:49, 28 January 2019 (UTC)<br />
<br />
::I was thinking about this while writing a [[Talk:Arch User Repository#Proposal: Other requests|proposal regarding "Other requests"]]. It is possible to request a package be disowned with "Orphan"; why not add "Co-maintain" to send a request to ask for permission to assist with a package's maintenance? Of course, it would not be unnecessary to send that request to the mailing list, and there's always the AUR comments or the forums for users to contact a maintainer otherwise; but having the feature built in to the AUR would allow us to add a fourth subsection here to recommend ground rules and possibly expedite the process of adding co-maintainers when packagers are interested in doing so. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 14:45, 6 February 2019 (UTC)<br />
<br />
:::Rather than an FAQ, maybe add a bullet point under "Maintaining packages". Question: Who has the right to use "Manage Co-Maintainers"? [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:07, 27 May 2019 (UTC)<br />
<br />
::::<s>Closing proposal below, now implemented</s>. Leaving discussion open: in the future, we may want to break long bulleted lists like "Rules of Submission" and "Maintaining Packages" into subsections. This would make it more convenient to link to specific points in the list, which in turn would be convenient if we still want an FAQ such as "How can I contribute to an existing package?" (which should link to adopting orphaned packages, commenting on a package, and adding co-maintainters) [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 09:31, 4 June 2019 (UTC)<br />
<br />
:::::Since the reversion, documenting how to add co-maintainers has been absorbed into the proposal for [[User talk:Quequotion/AUR submission guidelines#Maintaining packages|AUR submission guidelines]]. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 12:07, 21 July 2019 (UTC)<br />
<br />
=== Proposal: How can I contribute to an existing package? ===<br />
{{Comment|No longer clear where this question would fit--splitting the content of the page between a "maintainter-oriented" page and a "user-oriented" page overlooks the fact that AUR package maintainers and AUR users ''may be the same people''.}}<br />
If the package is [[User:Quequotion/AUR submission guidelines#Orphan|orphaned]] you may [[User:Quequotion/AUR submission guidelines#Maintaining packages|adopt it]], otherwise you may post your idea [[User:Quequotion/Arch User Repository#Commenting on packages|in its comments]] or ask to be [[User:Quequotion/AUR submission guidelines#Maintaining packages|appointed as a co-maintainer]].<br />
<br />
== Integrate FAQ content ==<br />
<br />
Truncate FAQs' answers as much as possible, linking to an appropriate page or (proposed) section of the AUR page. Note that some content must be transferred to the [[AUR submission guidelines]].<br />
<br />
If you'd like to discuss the proposal as a whole, do so in this header; use [[Template:Comment|comments]] within individual subsections to discuss them. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 04:42, 11 June 2019 (UTC)<br />
<br />
If you'd like to see how this page should look, and get a history without other changes, I've restored its [[User:Quequotion/Arch User Repository|full page draft]]. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 10:14, 11 June 2019 (UTC)<br />
<br />
:There are a lot of changes to review; so I've compiled a rundown of them [[User talk:Quequotion/Arch User Repository#Breakdown_of_changes|on the talk page of the draft]]. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 13:45, 14 June 2019 (UTC)<br />
<br />
:Please keep drafts on a dedicated page. ([[Special:Diff/575147]]) Closing the sections below. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 13:18, 11 June 2019 (UTC)<br />
<br />
:Update on these proposals: The FAQ integration for [[Arch User Repository]] is more or less completed, however some of the FAQ on this page contain maintainer-oriented content that is better suited to subsections of [[AUR submission guidelines]]. I am aware that proposals for a page should be discussed only on that page's talk page. These proposals date back to when these two pages existed as one, and therefore concern both: several of the FAQ from ''this'' page need to be integrated into subsections of ''that'' page. To ease the review process, I compiled a [[User talk:Quequotion/AUR submission guidelines#Breakdown of changes|breakdown of the proposed changes]]. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 17:13, 5 January 2021 (UTC)<br />
<br />
== Split FAQ content to Arch User Repository/FAQ page. ==<br />
<br />
Have a look at the ratio of [https://i.postimg.cc/MHHcW5b3/aur-slashfaq.png FAQ to page content].<br />
<br />
I like the the idea of using ''Article''/FAQ for these. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 01:42, 18 June 2019 (UTC)<br />
<br />
: This makes sense to me. [[User:Jasonwryan|Jasonwryan]] ([[User talk:Jasonwryan|talk]]) 02:16, 18 June 2019 (UTC)<br />
<br />
:: An alternative which doesn't require a new page is merging this to [[FAQ]]. An issue with this approach (presented on IRC) however is that adding AUR content to the "official" FAQ may add some notion of supported-ness for the AUR (and its content in specific). A way around this would be to include the "AUR packages are user produced content. Any use of the provided files is at your own risk." warning as well. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 07:54, 24 June 2019 (UTC)<br />
<br />
::: This would also add a significant amount of content to the official FAQ page, which might be seen as clutter. However, to be honest I'm more interested in ''having this FAQ relocated'' than ''where it ultimately goes''. Also, not sure if I need to clarify, but this is not exclusive of the [[#Integrate FAQ content]] proposals; it would be in the best interest of wherever the FAQ ends up that it is as small as possible when it gets there. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 13:10, 21 July 2019 (UTC)<br />
<br />
== Meaning of the Popularity score? ==<br />
<br />
Can someone explain what the meaning of the Popularity score is, and how it's calculated? And maybe add that to the wiki?<br />
It doesn't seem to be derived from the number of votes, as some packages with more votes has a lower popularity than others with a lower vote count.<br />
Maybe it's number of installs? Maybe it's time dependent, so recent votes only temporarily increase popularity?<br />
<br />
I got curious about this as a helper like yay prominently displays this value, but I haven't seen it presented in yay's documentation, or here. Or maybe I skimmed them too fast.<br />
<br />
[[User:Biowaste|Biowaste]] ([[User talk:Biowaste|talk]]) 00:02, 2 November 2019 (UTC)<br />
<br />
:<s>This is one of many issues my proposal (Integrate FAQ content) for this page and the AUR submission guidelines page handles. If you dig around on the current page, you may find what you are looking for--or if someone could approve the changes we could have the information appropriately documented under [[User:Quequotion/Arch User Repository#Feedback|an improved feedback section]] here, and referenced in [[User:Quequotion/AUR submission guidelines#Promoting packages to the community repository|a section about promoting packages to community]] on the AUR submission guidelines page. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 04:23, 2 November 2019 (UTC)</s><br />
<br />
::Your proposal does not answer the question "What is the meaning of the Popularity score?" at all, so please stop pretending that it is a universal solution for every issue related to AUR documentation.<br />
::On the [https://aur.archlinux.org/packages/ AUR package list] page, the Popularity column is suffixed with a "?" symbol which has an HTML tooltip explaining how the values are calculated.<br />
::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:18, 2 November 2019 (UTC)<br />
::: I see. I mistook that this was about votes. Popularity score is a different thing. My mistake. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:22, 2 November 2019 (UTC)<br />
<br />
== Improve Comment syntax section ==<br />
<br />
It would be best to give examples of comments syntax right there. Currently there are 6 links in that small section, which would take a lot of time from users and may also be misleading.<br />
<br />
"Note this implementation has some occasional differences " - would be used much less often than how to just simply markup some code.<br />
I suggest main information should go first, and examples would be good.<br />
<br />
It would be good if comment syntax was given directly on AUR site, but at least here one should be able to very easily navigate to basic comment syntax.<br />
[[User:Ynikitenko|Ynikitenko]] ([[User talk:Ynikitenko|talk]]) 15:52, 17 November 2019 (UTC)<br />
:In particular those differences should be documented, such as aur-specific features. For example, it is noted that references to git commit hashes will be linkified, but not that this means specifically ''12-digit'' hash references ([https://aur.archlinux.org/packages/ido-ubuntu/#comment-710922 example]). No idea what the specific format expected for Flyspray tickets would be. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 06:52, 19 November 2019 (UTC)<br />
<br />
== Add context about package ecosystem ==<br />
I recently had the content below [https://wiki.archlinux.org/index.php?title=Arch_User_Repository&type=revision&diff=694215&oldid=694213 reverted].<br />
<br />
The justification was: "this is irrelevant to the technical description of the AUR"<br />
<br />
I see nothing in [[Help:Style]], nor do I believe it would be advisable to add, anything limiting the content of articles to being strictly technical. People go to pages in the Arch wiki wanting to learn about that topic, as it relates to Arch. They want technical content and context. What I've included is an extremely important detail for someone evaluating the merits of the Arch package system! Note that I just went around the last couple of hours evaluating other Linux distros for the wiki and thoroughly appreciate when projects are smart about including these sorts of details. That's specifically why I thought to include this now.<br />
[[User:Einr|Einr]] ([[User talk:Einr|talk]]) 07:01, 5 September 2021 (UTC)<br />
<br />
:This is not an ad board. This page describes what the AUR is and how to use it, your sentence does not help with any of these. Furthermore, your note is misleading because it indicates a combination with official repositories, which are managed independently and contain incomparably higher quality packages. The repository statistics don't consider package quality at all, in fact AUR is one of the few (if not the only one) community-driven and ''unsupported'' repositories in the top 10. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:39, 5 September 2021 (UTC)<br />
<br />
::Regarding, "May mislead to believe combination with official." Happy to rephrase it to make it explicit in the statement that's not the case if that suits you. [[User:Einr|Einr]] ([[User talk:Einr|talk]]) 08:07, 5 September 2021 (UTC)<br />
::Regarding, "Not an ad board." The open source world is built on open sharing. What I posted advertises nothing and highlights only that Arch, collectively, has a broader package coverage net than nearly anything else out there almost no matter how it's measured. People looking for '''''a''''' package know what they want and only want to know that it's available. [[User:Einr|Einr]] ([[User talk:Einr|talk]]) 08:07, 5 September 2021 (UTC)<br />
::Regarding, "Contrast to incomparably higher quality packages" The contrast in quality and implied security between official and AUR seems pretty obvious and well stated already. Also happy to make that more explicit in the statement if you believe it needs further re-iterating. I think it's covered well enough in these pages, but I'm ok with that as a compromise. [[User:Einr|Einr]] ([[User talk:Einr|talk]]) 08:07, 5 September 2021 (UTC)<br />
<br />
=== Reverted content ===<br />
Combined with the [https://repology.org/repository/arch official repositories], Arch is proud to be home to one of the [https://repology.org/repository/aur largest and most up-to-date] package repository ecosystems [https://entvibes.com/archwiki/Arch%20and%20AUR%20on%20Repology%20-%20highlighted%20-%202021-09-05%20162239.png in the Linux world].<br />
<br />
== Tips and Tricks ==<br />
<br />
Does this page really need a "Tips and Tricks" section? It seems a bit out-of-scope to me, especially the particular tip it was created for ([[Special:Diff/706567]]).<br />
<br />
This might fit more appropriately as a [[Template:Tip]] appended to [[Arch User Repository#Build the package]]. It also needs some proofreading. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 13:28, 14 January 2022 (UTC)<br />
<br />
==== Proposal ====<br />
{{Tip|Use {{ic| git clean -dfX}} in the build directory to delete all untracked files, such as previously built package files.}}<br />
<br />
<br />
:I like the idea of moving it. Having it as a tip directly after the description of {{ic|--clean}} makes sense. [[User:Progandy|Progandy]] ([[User talk:Progandy|talk]]) 14:43, 16 January 2022 (UTC)</div>Progandyhttps://wiki.archlinux.org/index.php?title=Removing_system_encryption&diff=693483Removing system encryption2021-08-30T09:26:43Z<p>Progandy: /* Decrypting LUKS2 devices in-place */ removed stray newline</p>
<hr />
<div>[[Category:Data-at-rest encryption]]<br />
[[es:Removing system encryption]]<br />
{{Style|written in first person, other style issues.}}<br />
<br />
Removing system encryption with [[dm-crypt|dm-crypt and LUKS]].<br />
<br />
== Removing LUKS Encryption in-place ==<br />
<br />
=== Overview ===<br />
<br />
Although not as safe as backing up your data and restoring it on to a reformatted device,<br />
cryptsetup does allow the user to permanently remove the LUKS encryption from a device in-place. For example, if you have an ext4 filesystem living inside a LUKS-encrypted partition,<br />
performing in-place decryption will remove the LUKS signature, and place the ext4 filesystem<br />
directly on the partition, so that you can mount it directly. Unless something goes wrong,<br />
the files in the filesystem will remain intact. The terms used by cryptsetup's documentation for this is "decryption."<br />
<br />
Support for non-destructive offline decryption of LUKS1 devices has been available starting with {{ic|cryptsetup}} version 1.5.0, which was released in 2012. LUKS1 decryption only supported offline mode decryption.<br />
<br />
For LUKS2 devices, both offline and online (i.e. unmount not required) decryption are supported. <br />
<br />
{{Warning|The procedures which follow are inherently risky and may cause catastrophic data loss. You should always backup your drive and LUKS headers before proceeding, to protect your data from accidents during decryption.}}<br />
<br />
=== Decrypting LUKS1 devices in-place ===<br />
<br />
Decryption is done in offline mode, using the (noq legacy) {{ic|cryptsetup-reencrypt}} command.<br />
The steps are:<br />
# Verify that your block device has a LUKS1 header (and not LUKS2) using {{ic|cryptsetup luksDump <dev>}}<br />
# reboot into a live environment using a USB stick.<br />
# Identify your block device using {{ic|blkid}}, {{ic|lsblk}}, etc'<br />
# Make sure that the block device to be decrypted has not been opened by cryptsetup (there is no entry under `/dev/mapper/`, let alone mounted. If it has been, unmount and use {{ic|cryptsetup luksClose}} to close it.<br />
# Use the legacy command {{ic|cryptsetup-reencrypt}}:<br />
cryptsetup-reencrypt --decrypt <device_path><br />
<br />
The process might take a while. If no problems occur, the contents of the encrypted block device should not be accessible directly from the block device. i.e., you should be able to mount it directly.<br />
<br />
=== Decrypting LUKS2 devices in-place ===<br />
<br />
Decryption can be done in either offline or online mode, using the {{ic|cryptsetup}} command.<br />
<br />
{{Note|As of 2020, and version 2.3.3, when using {{ic|cryptsetup}} to decrypt a LUKS2 block device the program requires you to provide a LUKS {{ic|--header}} file. If you do not use the "detached header" feature of LUKS, and naively try to pass the block device itself (which contains a LUKS2 header) as the subject of the `--header`, {{ic|cryptsetup}} will accept this and go ahead with alleged decryption. Afterwards the block device will show up as a LUKS2 device with no key-slots, and YOUR DATA WILL BE LOST. If you try to use {{ic|cryptsetup luksHeaderBackup}} as the header file used with {{ic|--header}}, YOUR DATA WILL BE LOST. If you try to restore a backed-up header after this faulty decryption, YOUR DATA WILL STILL BE LOST.<br />
<br />
If you still went ahead with the decryption, the data might be recoverable by shifting the partition start after the now defunct luks header: [https://gitlab.com/cryptsetup/cryptsetup/-/issues/614#note_454401132] STILL, DO NOT RELY ON THIS.<br />
}}<br />
<br />
Given the data loss risk just noted, you should avoid in-place decryption of LUKS2<br />
devices unless you use detached header. I have tested offline LUKS2 decryption for a device with a detached header file and the procedure went smoothly. This functionality is also part of the tests included in the cryptsetup source.<br />
<br />
If you do not use a detached header, your safest course is to use the safer backup-format-restore procedure described below. Alternatively, you can choose to convert your LUKS2 device to a LUKS1 device, and then proceed with the LUKS1 decryption procedure.<br />
<br />
The conversion with take a significant amount of time, the system should be connected to mains power and extreme care should be taken to avoid any event that may lead to a system crash or loss of power. DATA LOSS MAY OCCUR if interrupted.<br />
<br />
Steps:<br />
<br />
# Verify that your block device has a LUKS2 header (and not LUKS1) using {{ic|cryptsetup luksDump <dev>}}<br />
# Note what key slots are in use using {{ic|cryptsetup luksDump <dev>}}<br />
# Reboot into a live environment using a USB stick.<br />
# Identify your block device using {{ic|blkid}} or {{ic|lsblk}}.<br />
# Make sure that the block device to be decrypted has not been opened by {{ic|cryptsetup}} (there is no entry under {{ic|/dev/mapper/}}, let alone mounted). If it has been, unmount and use {{ic|cryptsetup luksClose}} to close it.<br />
# Before converting the device, you must convert the Password-Based Key Derivation Function (PBKDF) for all key-slots to be LUKS1 compatible. Use the following command for each key slot: {{ic|sudo cryptsetup luksConvertKey --key-slot <key slot number> --pbkdf pbkdf2 <device_path>}}<br />
# Verify that all key slots PBKDFs are convert to pbkdf2: {{ic|cryptsetup luksDump <dev>}}<br />
# Convert the device from LUKS2 to LUKS1: {{ic|sudo cryptsetup convert --type luks1 <device_path>}}<br />
# Decrypt the (now) LUKS1 device: {{ic|sudo cryptsetup-reencrypt --decrypt <device_path>}}<br />
<br />
If successful, you should now be able to mount whatever filesystem was previously inside the LUKS device, by mounting the block device directly.<br />
<br />
Hopefully, the {{ic|cryptsetup}} project will address these usability and data loss issues in a future release (written August 2020).<br />
<br />
=== Cleaning up system files ===<br />
<br />
Device names and UUIDs may change due to decryption, and you will likely need to update relevant configuration files. The files most likely to need updating are {{ic|/etc/crypttab}}, {{ic|/etc/fstab}} and, if your recently decrypted device appeared on the kernel command line, your bootloader's configuration (e.g, {{ic|/etc/default/grub}}). If you edit the latter, remember to regenerate the grub configuration as described in [[GRUB]].<br />
<br />
== Removing LUKS via Backup-Format-Restore ==<br />
<br />
=== Prerequisites ===<br />
<br />
*An encrypted root filesystem you wish to decrypt.<br />
*Enough drive space to store a backup.<br />
*An Arch Linux (or other) live CD/USB.<br />
*A few hours.<br />
<br />
=== Boot into a Live Environment ===<br />
<br />
Download and burn the latest Arch ISO to a CD or USB, reboot the system, and boot to cd.<br />
<br />
=== Activate Partitions ===<br />
<br />
{{Style|This uses too many HTML attributes instead of templates}}<br />
<br />
==== Note About Different Setups ====<br />
<br />
An example setup is shown here:<br />
{| class="wikitable" style="text-align: center;"<br />
|colspan="4"|disk<br />
|-<br />
|style="background-color: #888888;"| ntfs ||colspan=2|myvg(lvm) ||style="background-color: yellow;"| ntfs<br />
|-<br />
|rowspan="3" style="background-color: #888888;"| other os<br />
|cryptswap(lv) ||style="background-color: green;"| cryptroot(lv)<br />
|rowspan="3" style="background-color: yellow;"| Shared<br />
|-<br />
|luks ||style="background-color: green;"| luks<br />
|-<br />
|swap ||style="background-color: green;"| root(xfs)<br />
|}<br />
<br />
The grey sections only add a frame of reference and can be disregarded.<br />
The green partitions will be modified. Green text must match your system's setup.<br />
The yellow partition will be used as storage space and may be changed at will.<br />
In the example system:<br />
<span style="color: green;">myvg</span> contains lvs called <span style="color: green;">cryptroot</span> and <span style="color: green;">cryptswap</span>. they are located at <span style="color: green;">/dev/myvg/cryptroot</span> and <span style="color: green;">/dev/myvg/cryptswap</span>. Upon boot, luks is used along with a few crypttab entries to create <span style="color: green;">/dev/mapper/root</span> and <span style="color: green;">/dev/mapper/swap</span>. Swap will not be unencrypted as part of this guide, as undoing the swap encryption does not require any complex backup or restoration.<br />
<br />
The example system is not indicative of all systems. Different filesystems require different tools to effectively backup and restore their data. LVM can be ignored if not used.<br />
XFS requires xfs_copy to ensure an effective backup and restore, DD is insufficient. DD may be used with ext2,3,and 4. (Someone please comment on jfs, reiserfs and reiser4fs)<br />
<br />
==== Once Partitions Are Located ====<br />
<br />
Load necessary modules:<br />
modprobe dm-mod #device mapper/lvm<br />
modprobe dm-crypt #luks<br />
<br />
Activate lvm volume group:<br />
pvscan #scan for Physical Volumes<br />
vgscan #scan for volume groups<br />
lvscan #scan for logical volumes<br />
lvchange -ay <span style="color: green;">myvg/cryptroot</span><br />
Open the encrypted filesystem with luks so it can be read:<br />
cryptSetup luksOpen <span style="color: green;">/dev/myvg/cryptroot</span> root<br />
Enter password.<br />
Note: The only partition that will be operated on that should be mounted at this point is the backup partition. If a partition other than the backup partition is already mounted, it can be safely umounted it now.<br />
<br />
===== Mounting backup space =====<br />
<br />
Only if using NTFS to store the backup, install {{Pkg|ntfs-3g}}.<br />
<br />
The next step is important for backup storage.<br />
<br />
# mount -t ntfs-3g -o rw <u>/dev/sda5 /media/Shared</u><br />
or use netcat to store the backup on a remote system<br />
<br />
TODO: add netcat instructions.<br />
<br />
=== Backup Data ===<br />
<br />
Using xfs_copy:<br />
xfs_copy -db <span style="color: green;">/dev/mapper/root</span> <u>/media/Shared/backup_root.img</u><br />
Note: -d flag preserves uuids and -b ensures direct IO is not attempted to any of the target files.<br />
<br />
Using dd:<br />
dd if=<span style="color: green;">/dev/mapper/root</span> of=<u>/media/Shared/backup_root.img</u><br />
<br />
=== Undo Encryption ===<br />
<br />
Now the crucial moment, the point of no return if you will. Make sure you are ready to do this. If you plan to undo this later, you will have to almost start from scratch. You know how fun that is.<br />
cryptsetup luksClose root<br />
lvm lvremove <span style="color: green;">myvg/cryptroot</span><br />
<br />
=== Restore Data ===<br />
<br />
We have to create a new logical volume to house our root filesystem, then we restore our filesystem.<br />
lvm lvcreate <span style="color: green;">-l 100%FREE -n root myvg</span><br />
xfs_copy -db <u>/media/Shared/backup_root.img</u> <span style="color: green;">/dev/myvg/root</span> #notice the second drive name is changed now.<br />
<br />
=== Reconfigure the Operating System ===<br />
<br />
You need to boot into your operating system and edit /etc/crypttab, /etc/mkinitcpio.conf, /etc/fstab, and possibly /boot/grub/menu.lst.</div>Progandyhttps://wiki.archlinux.org/index.php?title=Removing_system_encryption&diff=693482Removing system encryption2021-08-30T09:21:11Z<p>Progandy: /* Decrypting LUKS2 devices in-place */ mention possible recovery option for decryption with attached headers.</p>
<hr />
<div>[[Category:Data-at-rest encryption]]<br />
[[es:Removing system encryption]]<br />
{{Style|written in first person, other style issues.}}<br />
<br />
Removing system encryption with [[dm-crypt|dm-crypt and LUKS]].<br />
<br />
== Removing LUKS Encryption in-place ==<br />
<br />
=== Overview ===<br />
<br />
Although not as safe as backing up your data and restoring it on to a reformatted device,<br />
cryptsetup does allow the user to permanently remove the LUKS encryption from a device in-place. For example, if you have an ext4 filesystem living inside a LUKS-encrypted partition,<br />
performing in-place decryption will remove the LUKS signature, and place the ext4 filesystem<br />
directly on the partition, so that you can mount it directly. Unless something goes wrong,<br />
the files in the filesystem will remain intact. The terms used by cryptsetup's documentation for this is "decryption."<br />
<br />
Support for non-destructive offline decryption of LUKS1 devices has been available starting with {{ic|cryptsetup}} version 1.5.0, which was released in 2012. LUKS1 decryption only supported offline mode decryption.<br />
<br />
For LUKS2 devices, both offline and online (i.e. unmount not required) decryption are supported. <br />
<br />
{{Warning|The procedures which follow are inherently risky and may cause catastrophic data loss. You should always backup your drive and LUKS headers before proceeding, to protect your data from accidents during decryption.}}<br />
<br />
=== Decrypting LUKS1 devices in-place ===<br />
<br />
Decryption is done in offline mode, using the (noq legacy) {{ic|cryptsetup-reencrypt}} command.<br />
The steps are:<br />
# Verify that your block device has a LUKS1 header (and not LUKS2) using {{ic|cryptsetup luksDump <dev>}}<br />
# reboot into a live environment using a USB stick.<br />
# Identify your block device using {{ic|blkid}}, {{ic|lsblk}}, etc'<br />
# Make sure that the block device to be decrypted has not been opened by cryptsetup (there is no entry under `/dev/mapper/`, let alone mounted. If it has been, unmount and use {{ic|cryptsetup luksClose}} to close it.<br />
# Use the legacy command {{ic|cryptsetup-reencrypt}}:<br />
cryptsetup-reencrypt --decrypt <device_path><br />
<br />
The process might take a while. If no problems occur, the contents of the encrypted block device should not be accessible directly from the block device. i.e., you should be able to mount it directly.<br />
<br />
=== Decrypting LUKS2 devices in-place ===<br />
<br />
Decryption can be done in either offline or online mode, using the {{ic|cryptsetup}} command.<br />
<br />
{{Note|As of 2020, and version 2.3.3, when using {{ic|cryptsetup}} to decrypt a LUKS2 block device <br />
the program requires you to provide a LUKS {{ic|--header}} file. If you do not use the "detached header" feature of LUKS, and naively try to pass the block device itself (which contains a LUKS2 header) as the subject of the `--header`, {{ic|cryptsetup}} will accept this and go ahead with alleged decryption. Afterwards the block device will show up as a LUKS2 device with no key-slots, and YOUR DATA WILL BE LOST. If you try to use {{ic|cryptsetup luksHeaderBackup}} as the header file used with {{ic|--header}}, YOUR DATA WILL BE LOST. If you try to restore a backed-up header after this faulty decryption, YOUR DATA WILL STILL BE LOST.<br />
<br />
If you still went ahead with the decryption, the data might be recoverable by shifting the partition start after the now defunct luks header: [https://gitlab.com/cryptsetup/cryptsetup/-/issues/614#note_454401132] STILL, DO NOT RELY ON THIS.<br />
}}<br />
<br />
Given the data loss risk just noted, you should avoid in-place decryption of LUKS2<br />
devices unless you use detached header. I have tested offline LUKS2 decryption for a device with a detached header file and the procedure went smoothly. This functionality is also part of the tests included in the cryptsetup source.<br />
<br />
If you do not use a detached header, your safest course is to use the safer backup-format-restore procedure described below. Alternatively, you can choose to convert your LUKS2 device to a LUKS1 device, and then proceed with the LUKS1 decryption procedure.<br />
<br />
The conversion with take a significant amount of time, the system should be connected to mains power and extreme care should be taken to avoid any event that may lead to a system crash or loss of power. DATA LOSS MAY OCCUR if interrupted.<br />
<br />
Steps:<br />
<br />
# Verify that your block device has a LUKS2 header (and not LUKS1) using {{ic|cryptsetup luksDump <dev>}}<br />
# Note what key slots are in use using {{ic|cryptsetup luksDump <dev>}}<br />
# Reboot into a live environment using a USB stick.<br />
# Identify your block device using {{ic|blkid}} or {{ic|lsblk}}.<br />
# Make sure that the block device to be decrypted has not been opened by {{ic|cryptsetup}} (there is no entry under {{ic|/dev/mapper/}}, let alone mounted). If it has been, unmount and use {{ic|cryptsetup luksClose}} to close it.<br />
# Before converting the device, you must convert the Password-Based Key Derivation Function (PBKDF) for all key-slots to be LUKS1 compatible. Use the following command for each key slot: {{ic|sudo cryptsetup luksConvertKey --key-slot <key slot number> --pbkdf pbkdf2 <device_path>}}<br />
# Verify that all key slots PBKDFs are convert to pbkdf2: {{ic|cryptsetup luksDump <dev>}}<br />
# Convert the device from LUKS2 to LUKS1: {{ic|sudo cryptsetup convert --type luks1 <device_path>}}<br />
# Decrypt the (now) LUKS1 device: {{ic|sudo cryptsetup-reencrypt --decrypt <device_path>}}<br />
<br />
If successful, you should now be able to mount whatever filesystem was previously inside the LUKS device, by mounting the block device directly.<br />
<br />
Hopefully, the {{ic|cryptsetup}} project will address these usability and data loss issues in a future release (written August 2020).<br />
<br />
=== Cleaning up system files ===<br />
<br />
Device names and UUIDs may change due to decryption, and you will likely need to update relevant configuration files. The files most likely to need updating are {{ic|/etc/crypttab}}, {{ic|/etc/fstab}} and, if your recently decrypted device appeared on the kernel command line, your bootloader's configuration (e.g, {{ic|/etc/default/grub}}). If you edit the latter, remember to regenerate the grub configuration as described in [[GRUB]].<br />
<br />
== Removing LUKS via Backup-Format-Restore ==<br />
<br />
=== Prerequisites ===<br />
<br />
*An encrypted root filesystem you wish to decrypt.<br />
*Enough drive space to store a backup.<br />
*An Arch Linux (or other) live CD/USB.<br />
*A few hours.<br />
<br />
=== Boot into a Live Environment ===<br />
<br />
Download and burn the latest Arch ISO to a CD or USB, reboot the system, and boot to cd.<br />
<br />
=== Activate Partitions ===<br />
<br />
{{Style|This uses too many HTML attributes instead of templates}}<br />
<br />
==== Note About Different Setups ====<br />
<br />
An example setup is shown here:<br />
{| class="wikitable" style="text-align: center;"<br />
|colspan="4"|disk<br />
|-<br />
|style="background-color: #888888;"| ntfs ||colspan=2|myvg(lvm) ||style="background-color: yellow;"| ntfs<br />
|-<br />
|rowspan="3" style="background-color: #888888;"| other os<br />
|cryptswap(lv) ||style="background-color: green;"| cryptroot(lv)<br />
|rowspan="3" style="background-color: yellow;"| Shared<br />
|-<br />
|luks ||style="background-color: green;"| luks<br />
|-<br />
|swap ||style="background-color: green;"| root(xfs)<br />
|}<br />
<br />
The grey sections only add a frame of reference and can be disregarded.<br />
The green partitions will be modified. Green text must match your system's setup.<br />
The yellow partition will be used as storage space and may be changed at will.<br />
In the example system:<br />
<span style="color: green;">myvg</span> contains lvs called <span style="color: green;">cryptroot</span> and <span style="color: green;">cryptswap</span>. they are located at <span style="color: green;">/dev/myvg/cryptroot</span> and <span style="color: green;">/dev/myvg/cryptswap</span>. Upon boot, luks is used along with a few crypttab entries to create <span style="color: green;">/dev/mapper/root</span> and <span style="color: green;">/dev/mapper/swap</span>. Swap will not be unencrypted as part of this guide, as undoing the swap encryption does not require any complex backup or restoration.<br />
<br />
The example system is not indicative of all systems. Different filesystems require different tools to effectively backup and restore their data. LVM can be ignored if not used.<br />
XFS requires xfs_copy to ensure an effective backup and restore, DD is insufficient. DD may be used with ext2,3,and 4. (Someone please comment on jfs, reiserfs and reiser4fs)<br />
<br />
==== Once Partitions Are Located ====<br />
<br />
Load necessary modules:<br />
modprobe dm-mod #device mapper/lvm<br />
modprobe dm-crypt #luks<br />
<br />
Activate lvm volume group:<br />
pvscan #scan for Physical Volumes<br />
vgscan #scan for volume groups<br />
lvscan #scan for logical volumes<br />
lvchange -ay <span style="color: green;">myvg/cryptroot</span><br />
Open the encrypted filesystem with luks so it can be read:<br />
cryptSetup luksOpen <span style="color: green;">/dev/myvg/cryptroot</span> root<br />
Enter password.<br />
Note: The only partition that will be operated on that should be mounted at this point is the backup partition. If a partition other than the backup partition is already mounted, it can be safely umounted it now.<br />
<br />
===== Mounting backup space =====<br />
<br />
Only if using NTFS to store the backup, install {{Pkg|ntfs-3g}}.<br />
<br />
The next step is important for backup storage.<br />
<br />
# mount -t ntfs-3g -o rw <u>/dev/sda5 /media/Shared</u><br />
or use netcat to store the backup on a remote system<br />
<br />
TODO: add netcat instructions.<br />
<br />
=== Backup Data ===<br />
<br />
Using xfs_copy:<br />
xfs_copy -db <span style="color: green;">/dev/mapper/root</span> <u>/media/Shared/backup_root.img</u><br />
Note: -d flag preserves uuids and -b ensures direct IO is not attempted to any of the target files.<br />
<br />
Using dd:<br />
dd if=<span style="color: green;">/dev/mapper/root</span> of=<u>/media/Shared/backup_root.img</u><br />
<br />
=== Undo Encryption ===<br />
<br />
Now the crucial moment, the point of no return if you will. Make sure you are ready to do this. If you plan to undo this later, you will have to almost start from scratch. You know how fun that is.<br />
cryptsetup luksClose root<br />
lvm lvremove <span style="color: green;">myvg/cryptroot</span><br />
<br />
=== Restore Data ===<br />
<br />
We have to create a new logical volume to house our root filesystem, then we restore our filesystem.<br />
lvm lvcreate <span style="color: green;">-l 100%FREE -n root myvg</span><br />
xfs_copy -db <u>/media/Shared/backup_root.img</u> <span style="color: green;">/dev/myvg/root</span> #notice the second drive name is changed now.<br />
<br />
=== Reconfigure the Operating System ===<br />
<br />
You need to boot into your operating system and edit /etc/crypttab, /etc/mkinitcpio.conf, /etc/fstab, and possibly /boot/grub/menu.lst.</div>Progandyhttps://wiki.archlinux.org/index.php?title=WireGuard&diff=673330WireGuard2021-05-25T06:49:48Z<p>Progandy: /* Peer setup */ mention where to find the key for PEER_X_PUBLIC_KEY</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[pl:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPsec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it is now cross-platform (Windows, macOS, BSD, iOS, Android) and widely deployable.<br />
<br />
A rough introduction to the main concepts used in this article can be found on [https://www.wireguard.com/ WireGuard] project homepage. Wireguard is in the Linux kernel since March 2020. <br />
<br />
== Installation ==<br />
<br />
{{Accuracy|{{Pkg|wireguard-tools}} is still required for [[#Key generation]]. Or do network managers take care of that as well?}}<br />
<br />
If using [[#systemd-networkd]] or [[#NetworkManager]] as network manager, no additional tools are required to set up a WireGuard interface. Else, [[install]] {{Pkg|wireguard-tools}}.<br />
<br />
=== Graphical clients ===<br />
<br />
* {{App|Qomui|OpenVPN Gui with advanced features and support for multiple providers|https://github.com/corrad1nho/qomui|{{aur|qomui}}}}<br />
<br />
== Usage ==<br />
<br />
{{Style|Useless section name – everything on this page is about WireGuard usage. Moving the 4 subsections to the top level would make sense.}}<br />
<br />
The commands below demonstrate how to set up a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
{{Tip|The same UDP port can be used for all peers.}}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its public IP address(es) and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
Create a private and public key for each peer. If connecting dozens of peers optionally consider a vanity keypair to personalize the Base64 encoded public key string. See [[#Vanity keys]].<br />
<br />
To create a private key run:<br />
<br />
$ (umask 0077; wg genkey > peer_A.key)<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner. The above alters the [[umask]] temporarily within a sub-shell to ensure that access (read/write permissions) is restricted to the owner.}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, three interconnected peers, A, B, and, C will need three separate pre-shared keys, one for each peer pair.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
=== Manual configuration ===<br />
<br />
==== Peer setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
{{Style|These examples use the pre-shared keys which were introduced as ''optional'' in [[#Key generation]].}}<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}} (the contents of {{ic|1=peer_X.pub}}).<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify at least one address range that contains the WireGuard connection's internal IP address(es).<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
==== Additional routes ====<br />
<br />
To establish connections more complicated than point-to-point, additional setup is necessary.<br />
<br />
===== Point-to-site =====<br />
<br />
To access the network of a peer, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
===== Site-to-point =====<br />
<br />
{{Expansion|Add {{ic|ip route}} examples; add alternative using NAT; mention the situation when the ''site''-peer is the network's gateway.}}<br />
<br />
If the intent is to connect a device to a network with WireGuard peer(s), set up routes on each device so they know that the peer(s) are reachable via the device.<br />
<br />
{{Tip|Deploy routes network-wide by configuring them in the router.}}<br />
<br />
Enable IP forwarding on the peer through which other devices on the network will connect to WireGuard peer(s):<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
{{Warning|Enabling IP forwarding without a properly configured [[firewall]] is a security risk.}}<br />
<br />
See [[sysctl#Configuration]] for instructions on how to set the ''sysctl'' parameters on boot.<br />
<br />
===== Site-to-site =====<br />
<br />
To connect two (or more) networks, apply both [[#Point-to-site]] and [[#Site-to-point]] on all ''sites''.<br />
<br />
===== Routing all traffic over WireGuard =====<br />
<br />
{{Expansion|Add instructions on how to ''route everything over VPN''.[https://www.wireguard.com/netns/] There is [[#systemd-networkd: routing all traffic over WireGuard]] already.}}<br />
<br />
==== DNS ====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise DNS lookups may fail.}}<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameters will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
=== Persistent configuration ===<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using a network manager. Network managers that support WireGuard are [[systemd-networkd]], [[netctl]][https://git.archlinux.org/netctl.git/tree/docs/examples/wireguard], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[netctl]] relies on {{man|8|wg}} from {{Pkg|wireguard-tools}} and {{ic|/etc/wireguard/''interfacename''.conf}} configuration files for establishing WireGuard connections.<br />
* [[ConnMan]] has a very limited support for WireGuard. It can connect to only one peer.[https://git.kernel.org/pub/scm/network/connman/connman.git/commit/?id=95b25140bec7c4d9b6ae4e479dc1b94b7d409b39]<br />
}}<br />
<br />
==== wg-quick ====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* Users configuring the WireGuard interface using ''wg-quick'', should make sure that no other [[network management]] software tries to manage it. To use [[NetworkManager]] and to not configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not provide a way to instruct [[resolvconf]] to set the WireGuard interface as ''private''. Even if there are search domains specified, all DNS queries from the system, not just those that match the search domains, will be sent to the DNS servers which are set in the WireGuard configuration.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
MTU = 1420<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}. wg-quick will automatically take care of setting up correct routing and fwmark[https://www.wireguard.com/netns/#routing-all-your-traffic] so that networking still functions.<br />
* To use a peer as a DNS server, set {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. [[Wikipedia:Search domain|Search domains]] are also set with the {{ic|1=DNS = }} option. Separate all values in the list with commas. <br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
MTU = 1420<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
MTU = 1420<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
==== systemd-networkd ====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For [[Wikipedia:Search domain|search domains]] use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|<nowiki>[NETWORK] SECTION OPTIONS</nowiki>|fragment=%5BNETWORK%5D_SECTION_OPTIONS}} for details.<br />
* To use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to {{ic|1=Domains=}} option.<br />
* To route additional subnets add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
{{Warning|In order to prevent the leaking of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
==== systemd-networkd: routing all traffic over WireGuard ====<br />
<br />
In this example Peer B connects to peer A with public IP address 89.0.99.9. Peer B routes all its traffic over WireGuard tunnel and uses Peer A for handling DNS requests.<br />
<br />
'''Peer A setup'''<br />
<br />
{{hc|/etc/systemd/network/20-wired.network|2=<br />
[Match]<br />
Name=en*<br />
<br />
[Network]<br />
DHCP=ipv4<br />
IPForward=ipv4<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.1<br />
<br />
[WireGuard]<br />
ListenPort=59998<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.50.0.2/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.1/24<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/systemd/network/50-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard peer 10.50.0.2<br />
<br />
[WireGuard]<br />
FirewallMark=0x8888<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=0.0.0.0/0<br />
Endpoint=89.0.99.9:59998<br />
}}<br />
<br />
{{hc|/etc/systemd/network/50-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.50.0.2/24<br />
DNS=10.50.0.1<br />
DNSDefaultRoute=true<br />
Domains=~.<br />
<br />
[RoutingPolicyRule]<br />
FirewallMark=0x8888<br />
InvertRule=true<br />
Table=1000<br />
Priority=10<br />
<br />
[Route]<br />
Gateway=10.50.0.1<br />
GatewayOnLink=true<br />
Table=1000<br />
}}<br />
<br />
{{Note|You must still enable IP Forwarding and IP masquerading rules in order to provide working internet to Peer B.<br />
<br />
Assumes [[ufw]], but you could do the same with [[iptables]] by using the rules outlined in the [[#Server_config|Server config]] section:<br />
<br />
$ ufw route allow in on wg0 out on enp5s0<br />
<br />
{{hc|/etc/ufw/before.rules|2=<br />
*nat<br />
:POSTROUTING ACCEPT [0:0]<br />
-A POSTROUTING -s 10.0.0.0/24 -o enp5s0 -j MASQUERADE<br />
COMMIT<br />
}}<br />
<br />
}}<br />
<br />
==== Netctl ====<br />
<br />
[[Netctl]] has native support for setting up WireGuard interfaces. A typical set of WireGuard netctl profile configuration files would look like this.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer A"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.1/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer B"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.2/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.3/32<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/netctl/wg0|2=<br />
Description="WireGuard tunnel on peer C"<br />
Interface=wg0<br />
Connection=wireguard<br />
WGConfigFile=/etc/wireguard/wg0.conf<br />
<br />
IP=static<br />
Address=('10.0.0.3/24')<br />
}}<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.1/32<br />
Endpoint = peer-a.example:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
AllowedIPs = 10.0.0.2/32<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
Then start and/or enable wg0 interface on every participating peer as needed, ie.<br />
<br />
# netctl start wg0<br />
<br />
To implement persistent site-to-peer, peer-to-site or site-to-site type of connection with WireGuard and Netctl, just add appropriate {{ic|1=Routes=}} line into netctl profile config file and add this network to {{ic|AllowedIPs}} in WireGuard profile, eg. {{ic|1=Routes=('192.168.10.0/24 dev wg0')}} in the {{ic|/etc/netctl/wg0}} and {{ic|1=AllowedIPs=10.0.0.1/32, 192.168.10.0/24}} in {{ic|/etc/wireguard/wg0.conf}} and then do not forget to enable [[Internet sharing#Enable packet forwarding|IP forwarding]].<br />
<br />
==== NetworkManager ====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To ''route all traffic'' through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}. Special handling of the default route in WireGuard connections is supported since NetworkManager 1.20.0.<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings. [[Wikipedia:Search domain|Search domains]] can be specified with the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
To use a peer as the '''only''' DNS server, set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the {{ic|1=dns-search=}} settings.<br />
<br />
'''Peer B setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C setup:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Specific use-case: VPN server ==<br />
<br />
{{Merge|#Routing all traffic over WireGuard|Same use case.}}<br />
<br />
{{Note|Usage of the terms "server" and "client" were purposefully chosen in this section specifically to help new users/existing OpenVPN users become familiar with the construction of WireGuard's configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The "server" runs on Linux and the "clients" can run on any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may also use [[#systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
{{Merge|#Site-to-point|Same use case.}}<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server has a public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on {{ic|51820/UDP}}).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, {{ic|51820/UDP}}) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receives traffic via NAT, these iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} has a netmask of {{ic|/24}} and the clients on {{ic|AllowedIPs}} {{ic|/32}}. The clients only use their IP and the server only sends back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/32<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/32<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
Endpoint = my.ddns.example.com:51820<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
{{Merge|#Basic checkups|Same topic.}}<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=type:wireguard<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1420<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}}<br />
<br />
=== Key is not the correct length or format ===<br />
<br />
To avoid the following error, put the key value in the configuration file and not the path to the key file.<br />
<br />
{{hc|# wg-quick up wg0|<br />
[#] ip link add wg0 type wireguard<br />
[#] wg setconf wg0 /dev/fd/63<br />
Key is not the correct length or format: `''/path/example.key'''<br />
Configuration parsing error<br />
[#] ip link delete dev wg0<br />
}}<br />
<br />
=== Unable to establish a persistent connection behind NAT / firewall ===<br />
<br />
By default WireGuard peers remain silent while they do not need to communicate, so peers located behind a NAT and/or [[firewall]] may be unreachable from other peers until they reach out to other peers themselves (or the connection may time out). Adding {{ic|1=PersistentKeepalive = 25}} to the {{ic|[Peer]}} setting of a peer located behind a NAT and/or firewall can ensure that the connection remains open. <br />
<br />
{{hc|# Set the persistent-keepalive via command line (temporarily)|<br />
[#] wg set wg0 peer $PUBKEY persistent-keepalive 25<br />
}}<br />
<br />
=== Loop routing ===<br />
<br />
Adding the endpoint IP to the allowed IPs list, the kernel will attempt to send handshakes to said device binding, rather than using the original route. This results in failed handshake attempts.<br />
<br />
As a workaround, the correct route to the endpoint needs to be manually added using<br />
<br />
ip route add <endpoint ip> via <gateway> dev <network interface><br />
<br />
e.g. for peer B from above in a standard LAN setup:<br />
<br />
ip route add 203.0.113.102 via 192.168.0.1 dev eth0<br />
<br />
To make this route persistent the command can be added as {{ic|1=PostUp = ip route ...}} to the {{ic|[Interface]}} section of {{ic|wg0.conf}}. However, on certain setups (e.g. using {{ic|wg-quick@.service}} in combination with NetworkManager) this might fail on resume. Furthermore, this only works for a static network setup and fails if gateways or devices change (e.g. using ethernet or wifi on a laptop).<br />
<br />
Using NetworkManager, a more flexible solution is to start wireguard using an dispatcher script. As root, create<br />
{{hc|/etc/NetworkManager/dispatcher.d/50-wg0.sh|2=<br />
#!/bin/sh<br />
case $2 in<br />
up)<br />
wg-quick up wg0<br />
ip route add <endpoint ip> via $IP4_GATEWAY dev $DEVICE_IP_IFACE<br />
;;<br />
pre-down)<br />
wg-quick down wg0<br />
;;<br />
esac<br />
}}<br />
If not already running, start and enable {{ic|NetworkManager-dispatcher.service}}.<br />
Also, make sure that NetworkManager is not manging routes for {{ic|wg0}} ([[#Routes are periodically reset|see above]]).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Vanity keys ===<br />
<br />
Currently, Wireguard does not support comments or attaching human-memorable names to keys. This makes identifying the key's owner difficult particularly when multiple keys are in use. One solution is to generate a public key that contains some familiar characters (perhaps the first few letters of the owner's name or of the hostname etc.), {{AUR|wireguard-vanity-address}} does this.<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, etc., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 -r ''client.conf''<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
=== Reload peer (server) configuration ===<br />
<br />
In case the WireGuard peer (mostly server) adding or removing another peers from its configuration and wants to reload it without stopping any active sessions, one can execute the following command to do it:<br />
<br />
# wg syncconf ${WGNET} <(wg-quick strip ${WGNET})<br />
<br />
Where {{ic|$WGNET}} is WireGuard interface name or configuration base name, for example {{ic|wg0}} (for server) or {{ic|client}} (without the ''.conf'' extension, for client).<br />
<br />
{{Expansion|Show how to do this with other network managers from [[#Persistent configuration]].}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Systemd-networkd&diff=655105Systemd-networkd2021-03-16T10:31:20Z<p>Progandy: /* Required services and setup */ Forgot rewording and manpage links for DHCP and IPv6AcceptRA</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Virtualization]]<br />
[[de:Systemd/systemd-networkd]]<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 />
<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 configure [[systemd-resolved]], which is a network name resolution service to local applications, considering the following points:<br />
<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 />
* ''systemd-resolved'' 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.<br>(by setting ({{ic|1=DHCP=}} and/or {{ic|1=IPv6AcceptRA=}} in the {{ic|[Network]}} section, and {{ic|1=UseDNS=yes}} (the default) in the corresponding section(s) {{ic|[DHCPv4]}}, {{ic|[DHCPv6]}}, {{ic|[IPv6AcceptRA]}}, see {{man|5|systemd.network}}).<br />
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.<br />
<br />
=== systemd-networkd-wait-online ===<br />
<br />
Enabling {{ic|systemd-networkd.service}} also enables {{ic|systemd-networkd-wait-online.service}}, which is a oneshot system service that waits for the network to be configured. The latter has {{ic|1=WantedBy=network-online.target}}, so it will be started only when {{ic|network-online.target}} itself is enabled or pulled in by some other unit. See also [[systemd#Running services after the network is up]].<br />
<br />
By default, {{ic|systemd-networkd-wait-online.service}} waits for all links it is aware of and which are managed by ''systemd-networkd'' to be fully configured or failed, and for at least one link to be online.<br />
<br />
If your system has multiple network interfaces, but some are not expected to be connected all the time (e.g. if you have a dual-port Ethernet card, but only one cable plugged in), starting {{ic|systemd-networkd-wait-online.service}} will fail after the default timeout of 2 minutes. This may cause an unwanted delay in the startup process. To change the behaviour to wait for ''any'' interface rather than ''all'' interfaces to become online, [[edit]] the service and add the {{ic|--any}} parameter to the {{ic|ExecStart}} line:<br />
<br />
{{hc|/etc/systemd/system/systemd-networkd-wait-online.service.d/wait-for-only-one-interface.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any<br />
}}<br />
<br />
Other behaviour such as ignored interfaces or the operational state can be configured as well. See {{man|8|systemd-networkd-wait-online}} for the available parameters.<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. See [[Network configuration#Network interfaces]] for checking your adapter names.<br />
* 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 />
}}<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 />
To authenticate to the wireless network, use e.g. [[wpa_supplicant]] or [[iwd]].<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, {{man|5|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, or for a user namespace (with {{ic|private-users}}). || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|powervm}}, {{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|proot}}, {{ic|pouch}}, {{ic|acrn}}), {{ic|private-users}} ||<br />
|}<br />
<br />
==== [Link] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=MACAddress=}} || Assign a hardware address to the device. Useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]. || full colon-, hyphen- or dot-delimited hexadecimal MAC addresses ||<br />
|-<br />
| {{ic|1=MTUBytes=}} || Maximum transmission unit in bytes to set for the device. Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value. Setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers || integer (usual suffixes K, M, G, are supported and are understood to the base of 1024) ||<br />
|-<br />
| {{ic|1=Multicast=}} || allows the usage of [[wikipedia:Multicast_address|multicast]] || boolean || ? not documented ?<br />
|}<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 />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Address=}} || Specify this key more than once to configure several addresses. Mandatory unless DHCP is used. If the specified address is {{ic|0.0.0.0}} (for IPv4) or {{ic|::}} (for IPv6), a new address range of the requested size is automatically allocated from a system-wide pool of unused ranges. || static IPv4 or IPv6 address and its prefix length (see {{man|3|inet_pton}}) ||<br />
|}<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 />
{{Tip|''systemd-networkd'' assigns a MAC address generated based on the interface name and the machine ID to the bridge. This may cause connection issues, for example in case of routing based on MAC filtering. To circumvent such problems you may assign a MAC address to your bridge, probably the same as your physical device, adding the line {{ic|1=MACAddress=xx:xx:xx:xx:xx:xx}} in the ''NetDev'' section above.}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.<br />
<br />
To see the newly created bridge on the host and on the container, type:<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 />
=== Speeding up TCP slow-start ===<br />
<br />
On a higher bandwidth link with moderate latency (typically a home Internet connection that is above 10 Mbit/s) the default settings for the TCP Slow Start algorithm are somewhat conservative. This issue exhibits as downloads starting slowly and taking a number of seconds to speed up before they reach the connection's full bandwidth. It is particularly noticeable with a pacman upgrade, where each package downloaded starts off slowly and often finishes before it has reached the connection's full speed.<br />
<br />
These settings can be adjusted to make TCP connections start with larger window sizes than the defaults, avoiding the time it takes for them to automatically increase on each new TCP connection[https://www.cdnplanet.com/blog/tune-tcp-initcwnd-for-optimum-performance/]. While this will usually decrease performance on slow connections (or if the values are increased too far) due to having to retransmit a larger number of lost packets, they can substantially increase performance on connections with sufficient bandwidth.<br />
<br />
It is important to benchmark before and after changing these values to ensure it is improving network speed and not reducing it. If you are not seeing downloads begin slowly and gradually speed up, then there is no need to change these values as they are already optimal for your connection speed. When benchmarking, be sure to test against both a high speed and low speed remote server to ensure you are not speeding up access to fast machines at the expense of making access to slow servers even slower.<br />
<br />
To adjust these values, edit the ''.network'' file for the connection:<br />
<br />
{{hc|/etc/systemd/network/eth0.network|2=<br />
[Match]<br />
Name=eth0<br />
<br />
#[Network]<br />
#Gateway=... <-- Remove this if you have it, and put it in the Gateway= line below<br />
<br />
[Route]<br />
# This will apply to the gateway supplied via DHCP. If you manually specify<br />
# your gateway, put it here instead.<br />
Gateway=_dhcp4<br />
<br />
# The defaults for these values is 10. They are a multiple of the MSS (1460 bytes).<br />
InitialCongestionWindow=10<br />
InitialAdvertisedReceiveWindow=10<br />
}}<br />
<br />
The defaults of {{ic|10}} work well for connections slower than 10 Mbit/s. For a 100 Mbit/s connection, a value of {{ic|30}} works well. The manual page {{man|5|systemd.network|<nowiki>[ROUTE] SECTION OPTIONS</nowiki>|fragment=%5BROUTE%5D_SECTION_OPTIONS}} says a value of {{ic|100}} is considered excessive.<br />
<br />
If the [[sysctl]] setting {{ic|net.ipv4.tcp_slow_start_after_idle}} is enabled then the connection will return to these initial settings after it has been idle for some time (and often a very small amount of time). If this setting is disabled then the connection will maintain a higher window if a larger one was negotiated during packet transfer. Regardless of the setting, each new TCP connection will begin with the {{ic|Initial*}} settings set above.<br />
<br />
The sysctl setting {{ic|net.ipv4.tcp_congestion_control}} is not directly related to these values, as it controls how the congestion and receive windows are adjusted while a TCP link is active, and particularly when the path between the two hosts is congested and throughput must be reduced. The above {{ic|Initial*}} values simply set the default window values selected for each new connection, before any congestion algorithm takes over and adjusts them as needed. Setting higher initial values simply shortcuts some negotiation while the congestion algorithm tries to find the optimum values (or, conversely, setting the wrong initial values adds additional negotiation time while the congestion algorithm works towards correcting them, slowing down each newly established TCP connection for a few seconds extra).<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>Progandyhttps://wiki.archlinux.org/index.php?title=Systemd-networkd&diff=655104Systemd-networkd2021-03-16T09:56:50Z<p>Progandy: /* Required services and setup */ IPv6 RA can advertise DNS servers https://tools.ietf.org/html/rfc8106 and systemd-networkd can use it (manpage systemd.network section [IPv6AcceptRA])</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Network managers]]<br />
[[Category:Virtualization]]<br />
[[de:Systemd/systemd-networkd]]<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 />
<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 configure [[systemd-resolved]], which is a network name resolution service to local applications, considering the following points:<br />
<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 />
* ''systemd-resolved'' 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=IPv6AcceptRA=}} in the {{ic|[Network]}} section, and, in their own section, setting {{ic|1=UseDNS=yes}} (the default)).<br />
* Note that ''systemd-resolved'' can also be used without ''systemd-networkd''.<br />
<br />
=== systemd-networkd-wait-online ===<br />
<br />
Enabling {{ic|systemd-networkd.service}} also enables {{ic|systemd-networkd-wait-online.service}}, which is a oneshot system service that waits for the network to be configured. The latter has {{ic|1=WantedBy=network-online.target}}, so it will be started only when {{ic|network-online.target}} itself is enabled or pulled in by some other unit. See also [[systemd#Running services after the network is up]].<br />
<br />
By default, {{ic|systemd-networkd-wait-online.service}} waits for all links it is aware of and which are managed by ''systemd-networkd'' to be fully configured or failed, and for at least one link to be online.<br />
<br />
If your system has multiple network interfaces, but some are not expected to be connected all the time (e.g. if you have a dual-port Ethernet card, but only one cable plugged in), starting {{ic|systemd-networkd-wait-online.service}} will fail after the default timeout of 2 minutes. This may cause an unwanted delay in the startup process. To change the behaviour to wait for ''any'' interface rather than ''all'' interfaces to become online, [[edit]] the service and add the {{ic|--any}} parameter to the {{ic|ExecStart}} line:<br />
<br />
{{hc|/etc/systemd/system/systemd-networkd-wait-online.service.d/wait-for-only-one-interface.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --any<br />
}}<br />
<br />
Other behaviour such as ignored interfaces or the operational state can be configured as well. See {{man|8|systemd-networkd-wait-online}} for the available parameters.<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. See [[Network configuration#Network interfaces]] for checking your adapter names.<br />
* 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 />
}}<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 />
To authenticate to the wireless network, use e.g. [[wpa_supplicant]] or [[iwd]].<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, {{man|5|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, or for a user namespace (with {{ic|private-users}}). || boolean, logical negation ({{ic|!}}), type ({{ic|vm}}, {{ic|container}}), implementation ({{ic|qemu}}, {{ic|kvm}}, {{ic|zvm}}, {{ic|vmware}}, {{ic|microsoft}}, {{ic|oracle}}, {{ic|powervm}}, {{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|proot}}, {{ic|pouch}}, {{ic|acrn}}), {{ic|private-users}} ||<br />
|}<br />
<br />
==== [Link] ====<br />
<br />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=MACAddress=}} || Assign a hardware address to the device. Useful for [[MAC_address_spoofing#systemd-networkd|MAC address spoofing]]. || full colon-, hyphen- or dot-delimited hexadecimal MAC addresses ||<br />
|-<br />
| {{ic|1=MTUBytes=}} || Maximum transmission unit in bytes to set for the device. Note that if IPv6 is enabled on the interface, and the MTU is chosen below 1280 (the minimum MTU for IPv6) it will automatically be increased to this value. Setting a larger MTU value (e.g. when using [[jumbo frames]]) can significantly speed up your network transfers || integer (usual suffixes K, M, G, are supported and are understood to the base of 1024) ||<br />
|-<br />
| {{ic|1=Multicast=}} || allows the usage of [[wikipedia:Multicast_address|multicast]] || boolean || ? not documented ?<br />
|}<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 />
{| class = "wikitable"<br />
! Parameter !! Description !! Accepted Values !! Default Value<br />
|-<br />
| {{ic|1=Address=}} || Specify this key more than once to configure several addresses. Mandatory unless DHCP is used. If the specified address is {{ic|0.0.0.0}} (for IPv4) or {{ic|::}} (for IPv6), a new address range of the requested size is automatically allocated from a system-wide pool of unused ranges. || static IPv4 or IPv6 address and its prefix length (see {{man|3|inet_pton}}) ||<br />
|}<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 />
{{Tip|''systemd-networkd'' assigns a MAC address generated based on the interface name and the machine ID to the bridge. This may cause connection issues, for example in case of routing based on MAC filtering. To circumvent such problems you may assign a MAC address to your bridge, probably the same as your physical device, adding the line {{ic|1=MACAddress=xx:xx:xx:xx:xx:xx}} in the ''NetDev'' section above.}}<br />
<br />
[[Restart]] {{ic|systemd-networkd.service}} to have systemd create the bridge.<br />
<br />
To see the newly created bridge on the host and on the container, type:<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 />
=== Speeding up TCP slow-start ===<br />
<br />
On a higher bandwidth link with moderate latency (typically a home Internet connection that is above 10 Mbit/s) the default settings for the TCP Slow Start algorithm are somewhat conservative. This issue exhibits as downloads starting slowly and taking a number of seconds to speed up before they reach the connection's full bandwidth. It is particularly noticeable with a pacman upgrade, where each package downloaded starts off slowly and often finishes before it has reached the connection's full speed.<br />
<br />
These settings can be adjusted to make TCP connections start with larger window sizes than the defaults, avoiding the time it takes for them to automatically increase on each new TCP connection[https://www.cdnplanet.com/blog/tune-tcp-initcwnd-for-optimum-performance/]. While this will usually decrease performance on slow connections (or if the values are increased too far) due to having to retransmit a larger number of lost packets, they can substantially increase performance on connections with sufficient bandwidth.<br />
<br />
It is important to benchmark before and after changing these values to ensure it is improving network speed and not reducing it. If you are not seeing downloads begin slowly and gradually speed up, then there is no need to change these values as they are already optimal for your connection speed. When benchmarking, be sure to test against both a high speed and low speed remote server to ensure you are not speeding up access to fast machines at the expense of making access to slow servers even slower.<br />
<br />
To adjust these values, edit the ''.network'' file for the connection:<br />
<br />
{{hc|/etc/systemd/network/eth0.network|2=<br />
[Match]<br />
Name=eth0<br />
<br />
#[Network]<br />
#Gateway=... <-- Remove this if you have it, and put it in the Gateway= line below<br />
<br />
[Route]<br />
# This will apply to the gateway supplied via DHCP. If you manually specify<br />
# your gateway, put it here instead.<br />
Gateway=_dhcp4<br />
<br />
# The defaults for these values is 10. They are a multiple of the MSS (1460 bytes).<br />
InitialCongestionWindow=10<br />
InitialAdvertisedReceiveWindow=10<br />
}}<br />
<br />
The defaults of {{ic|10}} work well for connections slower than 10 Mbit/s. For a 100 Mbit/s connection, a value of {{ic|30}} works well. The manual page {{man|5|systemd.network|<nowiki>[ROUTE] SECTION OPTIONS</nowiki>|fragment=%5BROUTE%5D_SECTION_OPTIONS}} says a value of {{ic|100}} is considered excessive.<br />
<br />
If the [[sysctl]] setting {{ic|net.ipv4.tcp_slow_start_after_idle}} is enabled then the connection will return to these initial settings after it has been idle for some time (and often a very small amount of time). If this setting is disabled then the connection will maintain a higher window if a larger one was negotiated during packet transfer. Regardless of the setting, each new TCP connection will begin with the {{ic|Initial*}} settings set above.<br />
<br />
The sysctl setting {{ic|net.ipv4.tcp_congestion_control}} is not directly related to these values, as it controls how the congestion and receive windows are adjusted while a TCP link is active, and particularly when the path between the two hosts is congested and throughput must be reduced. The above {{ic|Initial*}} values simply set the default window values selected for each new connection, before any congestion algorithm takes over and adjusts them as needed. Setting higher initial values simply shortcuts some negotiation while the congestion algorithm tries to find the optimum values (or, conversely, setting the wrong initial values adds additional negotiation time while the congestion algorithm works towards correcting them, slowing down each newly established TCP connection for a few seconds extra).<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>Progandyhttps://wiki.archlinux.org/index.php?title=Firefox&diff=650608Firefox2021-02-03T07:25:22Z<p>Progandy: /* Hardware video acceleration */ Disable media.rdd-vpx.enabled for FF85</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Mozilla]]<br />
[[ar:Firefox]]<br />
[[cs:Firefox]]<br />
[[de:Firefox]]<br />
[[es:Firefox]]<br />
[[fr:Firefox]]<br />
[[it:Firefox]]<br />
[[ja:Firefox]]<br />
[[ko:Firefox]]<br />
[[ru:Firefox]]<br />
[[zh-hans:Firefox]]<br />
{{Related articles start}}<br />
{{Related|Firefox/Tweaks}}<br />
{{Related|Firefox/Profile on RAM}}<br />
{{Related|Firefox/Privacy}}<br />
{{Related|Browser extensions}}<br />
{{Related|Chromium}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
[https://www.mozilla.org/firefox Firefox] is a popular open source graphical web browser from [https://www.mozilla.org Mozilla].<br />
<br />
== Installing ==<br />
<br />
Firefox can be [[install]]ed with the {{Pkg|firefox}} package.<br />
<br />
Other alternatives include:<br />
<br />
* {{App|Firefox Developer Edition|for developers|https://www.mozilla.org/firefox/developer/|{{Pkg|firefox-developer-edition}}}}<br />
* {{App|Firefox Extended Support Release|long-term supported version|https://www.mozilla.org/firefox/organizations/|{{AUR|firefox-esr}} or {{AUR|firefox-esr-bin}}}}<br />
* {{App|Firefox Beta|cutting-edge version|https://www.mozilla.org/firefox/channel/desktop/#beta|{{AUR|firefox-beta}} or {{AUR|firefox-beta-bin}}}}<br />
* {{App|Firefox Nightly|nightly builds for testing ([https://developer.mozilla.org/Firefox/Experimental_features experimental features])|https://www.mozilla.org/firefox/channel/desktop/#nightly|{{AUR|firefox-nightly}}}} <br />
* {{App|Firefox KDE|Version of Firefox that incorporates an OpenSUSE patch for better [[#KDE integration|KDE integration]] than is possible through simple Firefox plugins.|https://build.opensuse.org/package/show/mozilla:Factory/MozillaFirefox|{{AUR|firefox-kde-opensuse}}}}<br />
* On top of the different Mozilla build channels, a number of forks exist with more or less special features; see [[List of applications#Gecko-based]].<br />
<br />
A number of language packs are available for Firefox, other than the standard English. Language packs are usually named as {{ic|firefox-i18n-''languagecode''}} (where {{ic|''languagecode''}} can be any language code, such as '''de''', '''ja''', '''fr''', etc.). For a list of available language packs see [https://www.archlinux.org/packages/extra/any/firefox-i18n/ firefox-i18n] for {{Pkg|firefox}},[https://www.archlinux.org/packages/community/any/firefox-developer-edition-i18n/ firefox-developer-edition-i18n] for {{Pkg|firefox-developer-edition}} and [https://aur.archlinux.org/packages/?K=firefox-nightly- firefox-nightly-] for {{AUR|firefox-nightly}}.<br />
<br />
== Add-ons ==<br />
<br />
Firefox is well known for its large library of add-ons which can be used to add new features or modify the behavior of existing features. Firefox's "Add-ons Manager" is used to manage installed add-ons or find new ones. <br />
<br />
For instructions on how to install add-ons and a list of add-ons, see [[Browser extensions]].<br />
<br />
=== Adding search engines ===<br />
<br />
Search engines may be added to Firefox by creating bookmarks with the {{ic|Location}} field using search URLs completed with %s in place of the query and the {{ic|Keyword}} field completed with user-defined characters:<br />
<br />
Location:<br />
https://duckduckgo.com/html/?q=%s<br />
Keyword:<br />
d<br />
<br />
Searches are performed by pre-pending the search term with the keyword of the specified search engine: {{ic|d archwiki}} will query DuckDuckGo using the search term {{ic|archwiki}}<br />
<br />
Search engines may also be added to Firefox through add-on extensions, see [https://addons.mozilla.org/firefox/search-tools/ this page] for a list of available search tools and engines.<br />
<br />
A very extensive list of search engines can be found at the [https://mycroftproject.com/ Mycroft Project].<br />
<br />
Also, you can use the [https://firefox.maltekraus.de/extensions/add-to-search-bar add-to-searchbar] extension to add a search to your search bar from any web site, by simply right clicking on the site's search field and selecting ''Add to Search Bar...''<br />
<br />
==== firefox-extension-arch-search ====<br />
<br />
[[Install]] the {{AUR|firefox-extension-arch-search}} package to add Arch-specific searches (AUR, wiki, forum, packages, etc) to the Firefox search toolbar.<br />
<br />
== Plugins ==<br />
<br />
Support for all plugins, including Flash Player, was removed in Firefox 85.[https://support.mozilla.org/kb/npapi-plug-ins][https://support.mozilla.org/kb/end-support-adobe-flash]<br />
<br />
== Configuration ==<br />
<br />
Firefox exposes a number of configuration options. To examine them, enter in the Firefox address bar:<br />
<br />
about:config<br />
<br />
Once set, these affect the user's current profile, and may be synchronized across all devices via [https://www.mozilla.org/firefox/sync/ Firefox Sync]. Please note that only a subset of the {{ic|about:config}} entries are synchronized by this method, and the exact subset may be found by searching for {{ic|services.sync.prefs}} in {{ic|about:config}}. Additional preferences and third party preferences may be synchronized by creating new boolean entries prepending the config value with {{ic|services.sync.prefs.sync}} ([https://developer.mozilla.org/en-US/docs/Archive/Mozilla/Firefox_Sync/Syncing_custom_preferences documentation] is still applicable.) To synchronize the whitelist for the extension [https://addons.mozilla.org/firefox/addon/noscript/ NoScript]:<br />
<br />
services.sync.prefs.sync.capability.policy.maonoscript.sites<br />
<br />
The boolean {{ic|noscript.sync.enabled}} must be set to {{ic|true}} to synchronize the remainder of NoScript's preferences via Firefox Sync.<br />
<br />
Firefox also allows configuration for a profile via a {{ic|user.js}} file: [http://kb.mozillazine.org/User.js_file user.js] kept in the profile folder, usually {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/}}. For a useful starting point, see e.g [https://github.com/pyllyukko/user.js custom user.js] which is targeted at privacy/security conscious users.<br />
<br />
One drawback of the above approach is that it is not applied system-wide. Furthermore, this is not useful as a "pre-configuration", since the profile directory is created after first launch of the browser. You can, however, let ''firefox'' create a new profile and, after closing it again, [https://support.mozilla.org/en-US/kb/back-and-restore-information-firefox-profiles#w_restoring-a-profile-backup copy the contents] of an already created profile folder into it. <br />
<br />
Sometimes it may be desired to lock certain settings, a feature useful in widespread deployments of customized Firefox. In order to create a system-wide configuration, follow the steps outlined in [http://kb.mozillazine.org/Locking_preferences Locking preferences]:<br />
<br />
1. Create {{ic|/usr/lib/firefox/defaults/pref/local-settings.js}}:<br />
<br />
pref("general.config.obscure_value", 0);<br />
pref("general.config.filename", "mozilla.cfg");<br />
<br />
2. Create {{ic|/usr/lib/firefox/mozilla.cfg}} (this stores the actual configuration):<br />
<br />
//<br />
//...your settings...<br />
// e.g to disable Pocket, uncomment the following line<br />
// lockPref("browser.pocket.enabled", false);<br />
<br />
Please note that the first line must contain exactly {{ic|//}}. The syntax of the file is similar to that of {{ic|user.js}}.<br />
<br />
=== Multimedia playback ===<br />
<br />
Firefox uses [[FFmpeg]] for playing multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. Go to [http://demo.nimius.net/video_test/ video-test page] or [https://hpr.dogphilosophy.net/test/ audio-test page] to check which formats are actually supported.<br />
<br />
Firefox uses [[PulseAudio]] for audio playback and capture. For sound to work, you need to install the {{Pkg|pulseaudio}} package.<br />
<br />
In case, for whatever reason, [[PulseAudio]] is not an option for you, you can use [[Advanced Linux Sound Architecture#PulseAudio compatibility|apulse]] instead. To make this work, it is necessary to exclude {{ic|/dev/snd/}} from Firefox' sandboxing by adding it to the comma-separated list in {{ic|about:config}}:<br />
<br />
security.sandbox.content.write_path_whitelist<br />
<br />
{{Note|The trailing slash on {{ic|/dev/snd/}} is important, otherwise ''apulse'' will report "Permission denied" errors.}}<br />
<br />
If you have no audio even when using ''apulse'', try adding {{ic|16}} to {{ic|security.sandbox.content.syscall_whitelist}} in {{ic|about:config}}.<br />
<br />
==== HTML5 DRM/Widevine ====<br />
<br />
Widevine is a digital rights management tool that Netflix, Amazon Prime Video, and others use to protect their video content. It can be enabled in ''Preferences > General > Digital Rights Management (DRM) Content''. If you visit a Widevine-enabled page when this setting is disabled, Firefox will display a prompt below the address bar asking for permission to install DRM. Approve this and then wait for the "Downloading" bar to disappear, you are now able to watch videos from Widevine protected sites.<br />
<br />
It is also required that the private mode browsing is disabled, for the window and in the preferences.<br />
<br />
==== Open With extension ====<br />
<br />
# Install [https://addons.mozilla.org/firefox/addon/open-with/ Open With] add-on.<br />
# Go to ''Add-ons > Open With > Preferences''.<br />
# Proceed with instructions to install a file in your system and test the installation. <br />
# Click ''Add browser''.<br />
# In the dialog write a name for this menu entry and command to start a video streaming capable player (e.g. [[mpv|/usr/bin/mpv]]).<br />
# (Optional step) Add needed arguments to the player (e.g. you may want {{ic|--force-window --ytdl}} for ''mpv'')<br />
# Right click on links or visit pages containing videos. Select newly created entry from Open With's menu and if the site is supported, the player will open as expected.<br />
<br />
The same procedure can be used to associate video downloaders such as ''youtube-dl''.<br />
<br />
==== Hardware video acceleration ====<br />
<br />
[[Hardware video acceleration]] via VA-API is available under [[Wayland]] (see [https://mastransky.wordpress.com/2020/06/03/firefox-on-fedora-finally-gets-va-api-on-wayland/ Firefox gets VA-API on Wayland]) and X.org (see [https://bugzilla.mozilla.org/show_bug.cgi?id=1619523 bugzilla X11 implement VAAPI] and [https://www.phoronix.com/scan.php?page=news_item&px=Firefox-80-VA-API-X11 Phoronix news VA API X11]).<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[AMDGPU]] users under {{pkg|linux-hardened}} may need to rebuild ''linux-hardened'' with {{ic|1=CONFIG_CHECKPOINT_RESTORE=y}} due to {{pkg|mesa}} [https://gitweb.gentoo.org/repo/gentoo.git/tree/media-libs/mesa/mesa-9999.ebuild requiring the kcmp syscall].<br />
* Hardware video acceleration on multi-GPU systems is affected by a [https://bugzilla.mozilla.org/show_bug.cgi?id=1622132 device selection bug].<br />
* VP8/VP9 decoding is affected by a [https://bugzilla.mozilla.org/show_bug.cgi?id=1673184 sandboxing bug]. FF84+ users may set {{ic|media.rdd-vpx.enabled}} to {{ic|false}} to bypass the RDD process.<br />
}}<br />
<br />
Before trying VA-API support in Firefox be sure to:<br />
<br />
* Install correct VA-API driver for your video card and verify VA-API has been enabled and working correctly, see [[Hardware video acceleration]];<br />
** For Intel graphics, use the i965 driver {{Pkg|libva-intel-driver}} if your hardware supports it. <br />
** The iHD driver {{Pkg|intel-media-driver}} (needed by Broadwell or newer) is currently broken due to sandbox violations caused by the driver ([https://bugzilla.mozilla.org/show_bug.cgi?id=1619585 see Bugzilla 1619585]). This can be worked around by setting the {{ic|security.sandbox.content.level}} flag to {{ic|0}}, at the risk of losing sandbox protection.<br />
* Use a compositor that supports hardware acceleration, either:<br />
** Gecko's OpenGL back-end, which can be enabled as explained in [[/Tweaks#Enable OpenGL compositor]];<br />
** WebRender from the new Servo browser engine, which can be enabled as explained in [[/Tweaks#Enable WebRender compositor]];<br />
* Set the following flags in {{ic|about:config}}:<br />
** {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|true}} in order to enable the use of VA-API with FFmpeg;<br />
** {{ic|media.ffvpx.enabled}} to {{ic|false}} to disable the internal decoders for VP8/VP9.<br />
** {{ic|media.rdd-vpx.enabled}} to {{ic|false}} to disable the remote data decoder process for VP8/VP9. As of Firefox 85 its sandbox blocks VA-API access [https://bugzilla.mozilla.org/show_bug.cgi?id=1673184].<br />
** If your hardware doesn't support AV1, you can set {{ic|media.av1.enabled}} to {{ic|false}} to force sites like YouTube provide other formats.<br />
* Run Firefox with the following [[environment variable]] enabled:<br />
** In Wayland, with {{ic|1=MOZ_ENABLE_WAYLAND=1}}, see [[#Wayland]].<br />
** In X.org, with {{ic|1=MOZ_X11_EGL=1}}.<br />
<br />
{{Tip|<br />
* You can verify that VA-API is enabled by running Firefox with {{ic|1=MOZ_LOG="PlatformDecoderModule:5"}} environment variable and check in the log output that VA-API is enabled and used (search for the "VA-API" string) when playing a video for example. Pay attention to these logs as they might indicate that only one of the two possible compositors described before (OpenGL or WebRender) works with VA-API on your particular setup.<br />
* For Intel GPU, the {{ic|intel_gpu_top}} utility from package {{pkg|intel-gpu-tools}} can be used to monitor the GPU activity during video playback for example. For AMD GPU, use {{Pkg|radeontop}}.<br />
* To allow hardware decoding in YouTube, the video codec used must be supported by the hardware. The profiles supported by your GPU can be checked with [[Hardware video acceleration#Verifying VA-API]] and the YouTube codecs used can be controlled with the [https://addons.mozilla.org/firefox/addon/h264ify/ h264ify] or [https://addons.mozilla.org/firefox/addon/enhanced-h264ify/ enhanced-h264ify] extensions. Alternatively, you can install {{AUR|firefox-h264ify}}.}}<br />
<br />
{{Note|Some videos (i.e. YouTube VR) may show a black image after setting {{ic|media.ffvpx.enabled}} to {{ic|false}}.}}<br />
<br />
=== Spell checking ===<br />
<br />
Firefox can use system-wide installed [[Hunspell]] dictionaries as well as dictionaries installed through its own extension system.<br />
<br />
To enable spell checking for a specific language right click on any text field and check the ''Check Spelling'' box. To select a language for spell checking to you have right click again and select your language from the ''Languages'' sub-menu.<br />
<br />
When your default language choice does not stick, see [[#Firefox does not remember default spell check language]].<br />
<br />
==== System-wide Hunspell dictionaries ====<br />
<br />
Install [[Hunspell]] and its dictionaries for the languages you require.<br />
<br />
==== Dictionaries as extensions ====<br />
<br />
To get more languages right click on any text field and just click ''Add Dictionaries...'' and select the dictionary you want to install from the [https://addons.mozilla.org/firefox/language-tools/ Dictionaries and Language Packs list].<br />
<br />
{{Tip|For Russian, the extension is packaged as {{Pkg|firefox-spell-ru}}.}}<br />
<br />
=== KDE integration ===<br />
<br />
* To bring the [[KDE]] look to GTK apps (including Firefox), install {{Pkg|breeze-gtk}} and {{Pkg|kde-gtk-config}}. Afterwards, go to ''System Settings > Application Style > Configure GNOME/GTK Application Style…''. Choose 'Breeze' or 'Breeze-Dark' in 'GTK2 Theme' and 'GTK3 Theme'.<br />
* To use the KDE file selection and print dialogs in Firefox 64 or newer, install {{Pkg|xdg-desktop-portal}} and {{Pkg|xdg-desktop-portal-kde}}, then set {{ic|widget.use-xdg-desktop-portal}} to {{ic|true}} in {{ic|about:config}}.<br />
* For integration with [[KDE]] MIME type system, proxy and file dialog, one can use {{AUR|firefox-kde-opensuse}} variant from AUR with OpenSUSE’s patches applied. Alternatively, integration with MIME types can be achieved by creating a symbolic link to the MIME database {{ic|~/.config/mimeapps.list}} from the deprecated {{ic|~/.local/share/applications/mimeapps.list}} that is used by Firefox. See [[XDG MIME Applications#mimeapps.list]].<br />
* Extensions/add-ons may provide additional integration, such as:<br />
** Browser integration in [[Plasma]]: requires {{Pkg|plasma-browser-integration}} and the [https://addons.mozilla.org/firefox/addon/plasma-integration/ Plasma Integration add-on].<br />
<br />
== Tips and tricks ==<br />
<br />
For general enhancements see [[Firefox/Tweaks]], for privacy related enhancements see [[Firefox/Privacy]].<br />
<br />
=== Dark themes ===<br />
<br />
If a dark [[GTK]] theme is in use (e.g. Arc Dark), it is recommended to start Firefox with a brighter one (e.g. Adwaita). See [[GTK#Themes]] and [[Firefox/Tweaks#Unreadable input fields with dark GTK themes]] for more information.<br />
<br />
Alternatively, starting with Firefox 68 you can make all the Firefox interfaces and even other websites respect dark themes, irrespective of the system GTK theme and Firefox theme. To do this, set {{ic|browser.in-content.dark-mode}} to {{ic|true}} and {{ic|ui.systemUsesDarkTheme}} to {{ic|1}} in {{ic|about:config}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1488384#c23].<br />
<br />
=== Frame rate ===<br />
<br />
If Firefox is unable to automatically detect the right value, it will default to 60 fps. To manually correct this, set {{ic|layout.frame_rate}} to the refresh rate of your monitor (e.g. 144 for 144 Hz).<br />
<br />
=== Memory limit ===<br />
<br />
To prevent pages from abusing memory (and possible [[Wikipedia:Out_of_memory|OOM]]), we can use [[Firejail]] with the {{ic|rlimit-as}} option.<br />
<br />
=== New tabs position ===<br />
<br />
To control where new tabs appears (relative or absolute), use {{ic|browser.tabs.insertAfterCurrent}} and {{ic|browser.tabs.insertRelatedAfterCurrent}}. See [https://support.mozilla.org/en/questions/1229062] for more information.<br />
<br />
=== Screenshot of webpage ===<br />
<br />
You can ''Take a Screenshot'' by either clicking the ''Page actions'' button (the three horizontal dots) in the address bar or by right-clicking on the webpage. See [https://support.mozilla.org/en-US/kb/firefox-screenshots] for more information.<br />
<br />
As an alternative you can use the screenshot button in the [https://developer.mozilla.org/en-US/docs/Tools/Taking_screenshots Developer Tools].<br />
<br />
=== Wayland ===<br />
<br />
More recent versions of Firefox support opting into [[Wayland]] via an environment variable.<br />
<br />
$ MOZ_ENABLE_WAYLAND=1 firefox<br />
<br />
To make this permanent, see [[Environment variables#Graphical environment]] and start Firefox via the desktop launcher like you normally would. To verify it worked check the ''Window Protocol'' again.<br />
<br />
You may enter {{ic|about:support}} in the URL bar to check the ''Window Protocol''. It should say ''wayland'' instead of ''x11'' or ''xwayland''.<br />
<br />
=== Window manager rules ===<br />
<br />
To apply different configurations to Firefox windows, change the WM_CLASS string by using Firefox's {{ic|--class}} option, to a custom one.<br />
<br />
==== Profiles ====<br />
<br />
To start new Firefox instances, multiple profiles are required. To create a new profile:<br />
<br />
$ firefox [--new-instance] -P<br />
<br />
Class can be specified when launching Firefox with a not-in-use profile:<br />
<br />
$ firefox [--new-instance] -P ''profile_name'' --class=''class_name''<br />
<br />
=== Touchscreen gestures and pixel-perfect trackpad scrolling ===<br />
<br />
{{Merge|Firefox/Tweaks#Enable touchscreen gestures|Same solution.}}<br />
<br />
To enable touch gestures (like scrolling and pinch-to-zoom) and one-to-one trackpad scrolling (as can be witnessed with GTK3 applications like Nautilus), set the {{ic|1=MOZ_USE_XINPUT2=1}} [[environment variable]] before starting Firefox.<br />
<br />
=== Multiple home pages ===<br />
<br />
To have multiple tabs opened when starting Firefox open a new window and then open the sites you want to have as "home tabs".<br />
<br />
Now go to ''Preferences > Home'' and under ''Homepage and new windows'' click the ''Use Current Pages'' button.<br />
<br />
Alternatively go directly to ''Preferences > Home'' and now under ''Homepage and new windows'' set the first field to ''Custom URLs..'' and enter the pages you want as new home pages in the following format:<br />
<br />
<nowiki>https://url1.com|https://url2.com|https://url3.com</nowiki><br />
<br />
== Troubleshooting ==<br />
<br />
=== Extension X does not work on some Mozilla owned domains ===<br />
<br />
By default extensions will not affect pages designated by {{ic|extensions.webextensions.restrictedDomains}}. If this is not desired, this field can be cleared (special pages such as {{ic|about:*}} will not be affected).<br />
<br />
=== Firefox startup takes very long ===<br />
<br />
If Firefox takes much longer to start up than other browsers, it may be due to lacking configuration of the localhost in {{ic|/etc/hosts}}. See [[Network configuration#Local network hostname resolution]] on how to set it up. <br />
<br />
=== Font troubleshooting ===<br />
<br />
See [[Font configuration]].<br />
<br />
Firefox has a setting which determines how many replacements it will allow from fontconfig. To allow it to use all your replacement-rules, change {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|127}} (the highest possible value).<br />
<br />
Firefox ships with ''Twemoji Mozilla'' font. To use system emoji font set {{ic|font.name-list.emoji}} to {{ic|emoji}} in {{ic|about:config}}.<br />
<br />
Firefox has problems with [[Emoji]] presentation [https://bugzilla.mozilla.org/show_bug.cgi?id=1509988]. Set {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|0}} as workaround.<br />
<br />
=== Setting an email client ===<br />
<br />
Inside the browser, {{ic|mailto}} links by default are opened by a web application such as Gmail or Yahoo Mail. To set an external email program, go to ''Preferences > Applications'' and modify the ''action'' corresponding to the {{ic|mailto}} content type; the file path will need to be designated (e.g. {{ic|/usr/bin/kmail}} for Kmail).<br />
<br />
Outside the browser, {{ic|mailto}} links are handled by the {{ic|x-scheme-handler/mailto}} mime type, which can be easily configured with [[xdg-mime]]. See [[Default applications]] for details and alternatives.<br />
<br />
=== File association ===<br />
<br />
See [[Default applications]].<br />
<br />
=== Firefox keeps creating ~/Desktop even when this is not desired ===<br />
<br />
Firefox uses {{ic|~/Desktop}} as the default place for download and upload files. To change it to another folder, set the {{ic|XDG_DESKTOP_DIR}} option as explained in [[XDG user directories]].<br />
<br />
=== Make plugins respect blocked pop-ups ===<br />
<br />
Some plugins can misbehave and bypass the default settings, such as the Flash plugin. You can prevent this by doing the following:<br />
<br />
# Type {{ic|about:config}} into the address bar.<br />
# Right-click on the page and select ''New > Integer''.<br />
# Name it {{ic|privacy.popups.disable_from_plugins}}.<br />
# Set the value to {{ic|2}}.<br />
<br />
The possible values are:<br />
<br />
* {{ic|'''0'''}}: Allow all popups from plugins.<br />
* {{ic|'''1'''}}: Allow popups, but limit them to {{ic|dom.popup_maximum}}.<br />
* {{ic|'''2'''}}: Block popups from plugins.<br />
* {{ic|'''3'''}}: Block popups from plugins, even on whitelisted sites.<br />
<br />
=== Changes to userChrome.css and userContent.css are ignored ===<br />
<br />
Set {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|true}} in {{ic|about:config}}<br />
<br />
=== Middle-click behavior ===<br />
<br />
To use the middle mouse button to paste whatever text has been highlighted/added to the clipboard, as is common in UNIX-like operating systems, set either {{ic|middlemouse.contentLoadURL}} or {{ic|middlemouse.paste}} to {{ic|true}} in {{ic|about:config}}. Having {{ic|middlemouse.contentLoadURL}} enabled was the default behaviour prior to Firefox 57.<br />
<br />
To scroll on middle-click (default for Windows browsers) set {{ic|general.autoScroll}} to {{ic|true}}.<br />
<br />
=== Backspace does not work as the 'Back' button ===<br />
<br />
According to [http://kb.mozillazine.org/Browser.backspace_action MozillaZine], the {{ic|Backspace}} key was mapped based on which platform the browser was running on. As a compromise, this preference was created to allow the {{ic|Backspace}} key to either go back/forward, scroll up/down a page, or do nothing.<br />
<br />
To make {{ic|Backspace}} go back one page in the tab's history and {{ic|Shift+Backspace}} go forward, set {{ic|browser.backspace_action}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
To have the {{ic|Backspace}} key scroll up one page and {{ic|Shift+Backspace}} scroll down one page, set {{ic|browser.backspace_action}} to {{ic|1}}. Setting this property to any other value will leave the key unmapped (Arch Linux defaults to {{ic|2}}, in other words, it is unmapped by default).<br />
<br />
=== Firefox does not remember login information ===<br />
<br />
It may be due to a corrupted {{ic|cookies.sqlite}} file in [https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data Firefox's profile] folder. In order to fix this, just rename or remove {{ic|cookie.sqlite}} while Firefox is not running.<br />
<br />
Open a terminal of choice and type the following:<br />
<br />
$ rm -f ~/.mozilla/firefox/<profile id>.default/cookies.sqlite<br />
<br />
The profile id is a random 8 character string.<br />
<br />
Restart Firefox and see if it solved the problem.<br />
<br />
If it didn't work, check if there exists a {{ic|cookies.sqlite.bak}} file that you could use to manually restore the cookies.<br />
<br />
=== Cannot enter/leave fullscreen ===<br />
<br />
If Firefox detects an [https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html EWMH/ICCCM] compliant window manager, it will try to send a WM_STATE message to the root window to request Firefox be made to enter (or leave) full-screen mode (as defined by the window manager). Window managers are allowed to ignore it, but if they do, Firefox will assume the request got denied and propagate it to the end user which results in nothing happening. This may result in not being able to full screen a video. A general workaround is to set the {{ic|full-screen-api.ignore-widgets}} to {{ic|true}} in {{ic|about:config}}. <br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=1189622 Bugzilla 1189622].<br />
<br />
=== Firefox detects the wrong version of my plugin ===<br />
<br />
When you close Firefox, the latter saves the current timestamp and version of your plugins inside {{ic|pluginreg.dat}} located in your profile folder, typically in {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/}}.<br />
<br />
If you upgraded your plugin when Firefox was still running, you will thus have the wrong information inside that file. The next time you will restart Firefox you will get that message {{ic|Firefox has prevented the outdated plugin "XXXX" from running on ...}} when you will be trying to open content dedicated to that plugin on the web. This problem often appears with the official [[Browser plugins#Adobe Flash Player|Adobe Flash Player plugin]] which has been upgraded while Firefox was still running.<br />
<br />
The solution is to remove the file {{ic|pluginreg.dat}} from your profile and that is it. Firefox will not complain about the missing file as it will be recreated the next time Firefox will be closed. [https://bugzilla.mozilla.org/show_bug.cgi?id=1109795#c16]<br />
<br />
=== JavaScript context menu does not appear on some sites ===<br />
<br />
You can try setting {{ic|dom.w3c_touch_events.enabled}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
=== Firefox does not remember default spell check language ===<br />
<br />
The default spell checking language can be set as follows:<br />
<br />
# Type {{ic|about:config}} in the address bar.<br />
# Set {{ic|spellchecker.dictionary}} to your language of choice, for instance {{ic|en_GB}}.<br />
# Notice that the for dictionaries installed as a Firefox plugin the notation is {{ic|en-GB}}, and for {{Pkg|hunspell}} dictionaries the notation is {{ic|en_GB}}.<br />
<br />
When you only have system wide dictionaries installed with {{Pkg|hunspell}}, Firefox might not remember your default dictionary language settings. This can be fixed by having at least one [https://addons.mozilla.org/firefox/language-tools/ dictionary] installed as a Firefox plugin. Notice that now you will also have a tab ''Dictionaries'' in ''Add-ons''. You may have to change the order of ''preferred language for displaying pages'' in {{ic|about:preferences#general}} to make the spell check default to the language of the addon dictionary.<br />
<br />
Related questions on the '''StackExchange''' platform: [https://stackoverflow.com/questions/26936792/change-firefox-spell-check-default-language/29446115], [https://stackoverflow.com/questions/21542515/change-default-language-on-firefox/29446353], [https://askubuntu.com/questions/184300/how-can-i-change-firefoxs-default-dictionary/576877]<br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=776028 Bugzilla 776028], [https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/1026869 Ubuntu bug 1026869]<br />
<br />
=== Some MathML symbols are missing ===<br />
<br />
You need some Math fonts, namely Latin Modern Math and STIX (see this MDN page: [https://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts#Linux]), to display MathML correctly.<br />
<br />
In Arch Linux, these fonts are provided by {{Pkg|texlive-core}} '''and''' {{Pkg|texlive-fontsextra}}, but they are not available to fontconfig by default. See [[TeX Live#Making fonts available to Fontconfig]] for details. You can also try other [[Fonts#Math|Math fonts]].<br />
<br />
=== Tearing video in fullscreen mode ===<br />
<br />
If you are using the Xorg Intel or Nouveau drivers and experience tearing video in fullscreen mode, try [[Firefox/Tweaks#Enable OpenGL compositor]].<br />
<br />
=== Tearing when scrolling ===<br />
<br />
Try disabling smooth scrolling in ''Preferences > Browsing''.<br />
<br />
=== Firefox WebRTC module cannot detect a microphone ===<br />
<br />
WebRTC applications for instance [https://mozilla.github.io/webrtc-landing/gum_test.html Firefox WebRTC getUserMedia test page] say that microphone cannot be found. Issue is reproducible for both ALSA or PulseAudio setup. Firefox debug logs show the following error:<br />
<br />
{{hc|1=$ NSPR_LOG_MODULES=MediaManager:5,GetUserMedia:5 firefox|2=<br />
...<br />
[Unnamed thread 0x7fd7c0654340]: D/GetUserMedia VoEHardware:GetRecordingDeviceName: Failed 1<br />
}}<br />
<br />
You can try setting {{ic|media.navigator.audio.full_duplex}} property to {{ic|false}} at {{ic|about:config}} Firefox page and restart Firefox.<br />
<br />
This can also help if you are using the PulseAudio [[PulseAudio/Troubleshooting#Enable Echo/Noise-Cancellation|module-echo-cancel]] and Firefox does not recognise the virtual echo canceling source.<br />
<br />
=== Cannot login with my Chinese account ===<br />
<br />
Firefox provides a local service for Chinese users, with a local account totally different from the international one. Firefox installed with the {{Pkg|firefox}} package uses the international account system by default, to change into the Chinese local service, you should install the add-on manager on [http://mozilla.com.cn/thread-343905-1-1.html this page], then you can login with your Chinese account now.<br />
<br />
=== No audio on certain videos when using JACK and PulseAudio ===<br />
<br />
If you are using JACK in combination with PulseAudio and cannot hear any sound on some videos it could be because those videos have mono audio. This happens if your JACK setup uses more than just stereo, but you use normal headphones. To fix this you simply have to connect the {{ic|front-center}} port from the PulseAudio JACK Sink to both {{ic|playback_1}} and {{ic|playback_2}} ports of the system output.<br />
<br />
You can also do this automatically using a script:<br />
<br />
{{hc|jack-mono.sh<br />
|2=#!/bin/sh<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_1"<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_2"<br />
}}<br />
<br />
Keep in mind that the names for the sink and the ports might be different for you. You can check what your JACK setup looks like with a Patchbay like Catia from {{Pkg|cadence}}.<br />
<br />
=== Geolocation does not work ===<br />
<br />
Recently, Google limited the use of its location service with Arch Linux, which causes the following error when geolocation is enabled on a website: {{ic|Geolocation error: Unknown error acquiring position}}. Region-locked services such as [https://www.hulu.com/ Hulu] may display a similar error indicating that your location could not be determined even though you've allowed location services for the site.<br />
<br />
To avoid these problems, you can switch to use the [https://location.services.mozilla.com/ Mozilla Location Service]. In {{ic|about:config}} change the {{ic|geo.provider.network.url}} setting to:<br />
<br />
<nowiki>https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%</nowiki><br />
<br />
See {{Bug|65241}} for more details.<br />
<br />
=== Right mouse button instantly clicks the first option in window managers ===<br />
<br />
This problem has been observed in [[i3]], [[bspwm]] and [[xmonad]].<br />
<br />
To fix it, navigate to {{ic|about:config}} and change {{ic|ui.context_menus.after_mouseup}} to {{ic|true}}.<br />
<br />
See [https://www.reddit.com/r/i3wm/comments/88k0yt/right_mouse_btn_instantly_clicks_first_option_in/]<br />
<br />
== See also ==<br />
<br />
* [https://www.mozilla.org/firefox/ Official website]<br />
* [https://www.mozilla.org/ Mozilla Foundation]<br />
* [[MozillaWiki:Firefox]]<br />
* [[Wikipedia:Mozilla Firefox]]<br />
* [https://addons.mozilla.org/ Firefox Add-ons]<br />
* [https://addons.mozilla.org/firefox/themes/ Firefox themes]<br />
* [https://ftp.mozilla.org/pub/firefox/releases/ Mozilla's FTP]<br />
* [http://forums.mozillazine.org/ mozillaZine] unofficial forums</div>Progandyhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=647459Network configuration/Wireless2020-12-28T11:16:59Z<p>Progandy: /* rtl88xxau */ aircrack-ng split driver for rtl8814au</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Network configuration (Česky)/Wireless]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Network configuration (Ελληνικά)/Wireless]]<br />
[[es:Network configuration (Español)/Wireless]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Wifi]]<br />
[[it:Network configuration (Italiano)/Wireless]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Network configuration (Nederlands)/Wireless]]<br />
[[pt:Network configuration (Português)/Wireless]]<br />
[[ru:Network configuration (Русский)/Wireless]]<br />
[[zh-hans:Network configuration (简体中文)/Wireless]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
{{Note|<br />
* If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.<br />
* If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
}}<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List]{{Dead link|2020|04|01|status=403}} (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64]<br />
|-<br />
| [http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{pkg|wireless_tools}} || {{yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.wiki.kernel.org/en/users/documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[WPA supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [https://wireless.wiki.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iw list''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [https://wireless.wiki.kernel.org/en/users/documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== Authentication ==<br />
<br />
{{Expansion|Add [[Wikipedia:WPA3|WPA3 Enterprise]] ({{Bug|65314}}) and [[Wikipedia:Opportunistic Wireless Encryption|Opportunistic Wireless Encryption (OWE) a.k.a. Enhanced Open]]. Warn against WEP and open networks.}}<br />
<br />
=== WPA2 Personal ===<br />
<br />
WPA2 Personal, a.k.a. WPA2-PSK, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
You can authenticate to WPA2 Personal networks using [[WPA supplicant]] or [[iwd]], or connect using a [[network manager]]. If you only authenticated to the network, then to have a fully functional connection you will still need to assign the IP address(es) and routes either [[Network configuration#Static IP address|manually]] or using a [[DHCP]] client.<br />
<br />
=== WPA2 Enterprise ===<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option.<br />
<br />
==== eduroam ====<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
==== Manual/automatic setup ====<br />
<br />
* [[WPA supplicant#Advanced usage|WPA supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
* [[NetworkManager]] can create WPA2 Enterprise profiles with ''nmcli'' or the [[NetworkManager#Front-ends|graphical front ends]]. ''nmtui'' does not support this ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/376 NetworkManager issue 376]), but may use existing profiles.<br />
* [[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting to eduroam (802.1X)]] for details.<br />
* [[netctl]] supports wpa_supplicant configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
: {{Warning|Special quoting rules apply: see the {{ic|''SPECIAL QUOTING RULES''}} section in {{man|5|netctl.profile}}.}}<br />
: {{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== WPA3 Personal ===<br />
<br />
{{Expansion|Does [[iwd]] support WPA3?}}<br />
<br />
WPA3 Personal, a.k.a. WPA3-SAE, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
[[wpa_supplicant]] supports WPA3 Personal ({{ic|CONFIG_SAE}} is enabled in {{Pkg|wpa_supplicant}} since version 2:2.9-4).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dBm-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [https://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|<br />
* Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.<br />
* According to [https://git.kernel.org/pub/scm/linux/kernel/git/mcgrof/crda.git/tree/README CRDA's README], it is no longer needed since kernel v4.15 as kernel will automatically load regulatory database from firmware. However [https://bugs.gentoo.org/462032#c17 it is also said] specific kernel setup is needed for the loading to work.<br />
}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[WPA supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [https://wireless.wiki.kernel.org/en/developers/documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} as [[Kernel_modules#Setting module options|module options]]. However, this is part of the [https://wireless.wiki.kernel.org/en/developers/regulatory#the_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [https://wireless.wiki.kernel.org/en/developers/regulatory kernel.org regulatory documentation].<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [https://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Observing Logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card. Try disabling the wireless card's [[Power_management#Network_interfaces|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Disable {{ic|40MHz}} channel bandwidth (lower throughput but less likely collisions) <br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
==== Cause #5 ====<br />
<br />
On some wireless network adapters (e.g. Qualcomm Atheros AR9485), random disconnects can happen with a DMA error:<br />
<br />
{{hc|# journalctl -xb|<nowiki><br />
ath: phy0: DMA failed to stop in 10 ms AR_CR=0x00000024 AR_DIAG_SW=0x02000020 DMADBG_7=0x0000a400<br />
wlp1s0: authenticate with 56:e7:ee:7b:55:bc<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 1/3)<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 2/3)<br />
wlp1s0: send auth to 56:e7:ee:7b:55:bc (try 3/3)<br />
wlp1s0: authentication with 56:e7:ee:7b:55:bc timed out<br />
</nowiki>}}<br />
<br />
A possible solution is to disable the [https://www.kernel.org/doc/html/latest/x86/intel-iommu.html Intel IOMMU driver (DMA)], adding {{ic|1=intel_iommu=off}} to the [[kernel parameters]] [https://bbs.archlinux.org/viewtopic.php?pid=1907446#p1907446].<br />
<br />
{{Note|The Intel IOMMU driver is needed for some advanced virtual machine features, like PCI pass-through.}}<br />
<br />
==== Cause #6 ====<br />
<br />
If you're using a device with iwlwifi and iwlmvm for wireless connectivity, and your Wi-Fi card appears to disappear when on battery power (perhaps after a reboot or resuming from suspend), this can be fixed by configuring power saving settings in iwlmvm.<br />
<br />
Create the file "/etc/modprobe.d/iwlmvm.conf" if it doesn't exist already, then add the following line to it:<br />
<br />
{{bc|1=options iwlmvm power_scheme=1}}<br />
<br />
A {{ic|power_scheme}} of 1 sets iwlmvm to "Always Active." Available options are:<br />
<br />
{| class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 1 || Always Active<br />
|-<br />
| 2 || Balanced<br />
|-<br />
| 3 || Low-power<br />
|}<br />
<br />
This fix was discovered at [http://forums.debian.net/viewtopic.php?t=121696#p576208].<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, some in-range Wi-Fi networks might be invisible, because they use wireless channels that are not allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}} [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3].<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs]{{Dead link|2018|08|15}} available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]. As of kernel 5.5 it should be supported by the included {{ic|mt76}} driver.<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723ae.conf|2=<br />
options rtl8723ae fwlps=0<br />
}}<br />
or<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au/rtl8812au/rtl8814au/rtl8821au designed for various USB adapters ranging from AC600 to AC1900.<br />
<br />
Several packages provide various kernel drivers:<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8821au || 5.6.4.2 || {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au and 8821au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8814au || 5.8.5.1 || {{AUR|rtl8814au-aircrack-dkms-git}} || Aircrack-ng kernel module for 8814au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8812au || 5.2.20 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au ''only''.<br />
|-<br />
| rtl8811au, rtl8812au and rtl8821au || 5.1.5 || {{AUR|rtl8821au-dkms-git}} || For rtl8812au versions 5.6.4.1 or 5.2.20 are recommended instead.<br />
|-<br />
| rtl8814au || 4.3.21 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too. Reportedly has better performance than {{AUR|rtl88xxau-aircrack-dkms-git}}. Seems to be deprecated in favor of {{AUR|rtl8814au-aircrack-dkms-git}}<br />
|}<br />
<br />
These require [[DKMS]] so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8811cu/rtl8821cu ====<br />
<br />
{{AUR|rtl8821cu-dkms-git}} provides a kernel module for the Realtek 8811cu and 8821cu chipset.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8821ce ====<br />
<br />
{{AUR|rtl8821ce-dkms-git}} provides a kernel module for the Realtek 8821ce chipset found in the Asus X543UA.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} or {{AUR|rtl88x2bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3, Asus AC53 Nano USB 802.11ac and TP-Link Archer T3U adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [https://wireless.wiki.kernel.org/en/users/Drivers/Atheros#pcipci-eahb_driversrs Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath5k<br />
* https://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath9k<br />
* https://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [http://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list]{{Dead link|2020|04|01|status=SSL error}} exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [https://wireless.wiki.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi#supported_devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{Aur|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
If your router only supports modes up to 802.11n, using 11n_disable=0 will limit your download and upload speeds at ~20Mbps (802.11g limit). If you need more than that and your card supports 802.11ac and/or 802.11ax modes (e.g. Intel® Wi-Fi 6 AX200 160MHz), consider replacing your router with the one that also supports 802.11ac and/or 802.11ax.<br />
<br />
If you have an 802.11ax (WiFi 6) access point and have problems detecting the beacons or an unreliable connection, review [https://www.intel.com/content/www/us/en/support/articles/000054799/network-and-i-o/wireless.html Intel Article 54799].<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wi-fibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
===== Firmware stack traces =====<br />
<br />
{{Accuracy|What is the last note about ignored packages trying to say?}}<br />
<br />
You may have some issue where the driver outputs stack traces & errors, which can cause some stuttering.<br />
<br />
{{hc|dmesg|2=<br />
Microcode SW error detected. Restarting 0x2000000.<br />
}}<br />
<br />
To fix those errors, you may downgrade the package {{Pkg|linux-firmware}} or rename the last version of the firmware used by your device so that an older version is loaded (which keeps it out of pacman's ignored packages).<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [https://wireless.wiki.kernel.org/en/users/drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [https://sourceforge.net/projects/acx100/ official page] for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[https://sourceforge.net/projects/zd1211/ zd1211rw] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[https://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [https://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [https://wireless.wiki.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]<br />
* [https://wikidevi.wi-cat.ru Wireless Device Database Wiki] (This fork is hosted by wi-cat.ru since the original wiki has shut down. There are two less complete versions available: [http://en.techinfodepot.shoutwiki.com TechInfoDepot], [https://deviwiki.com/ deviwiki])</div>Progandyhttps://wiki.archlinux.org/index.php?title=Firefox&diff=647381Firefox2020-12-28T02:04:04Z<p>Progandy: /* Hardware video acceleration */ mention possible issues with disabling ffvpx (black VR videos)</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Mozilla]]<br />
[[ar:Firefox]]<br />
[[cs:Firefox]]<br />
[[de:Firefox]]<br />
[[es:Firefox]]<br />
[[fr:Firefox]]<br />
[[it:Firefox]]<br />
[[ja:Firefox]]<br />
[[ko:Firefox]]<br />
[[ru:Firefox]]<br />
[[zh-hans:Firefox]]<br />
{{Related articles start}}<br />
{{Related|Browser plugins}}<br />
{{Related|Firefox/Tweaks}}<br />
{{Related|Firefox/Profile on RAM}}<br />
{{Related|Firefox/Privacy}}<br />
{{Related|Chromium}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
[https://www.mozilla.org/firefox Firefox] is a popular open source graphical web browser from [https://www.mozilla.org Mozilla].<br />
<br />
== Installing ==<br />
<br />
Firefox can be [[install]]ed with the {{Pkg|firefox}} package.<br />
<br />
Other alternatives include:<br />
<br />
* {{App|Firefox Developer Edition|for developers|https://www.mozilla.org/firefox/developer/|{{Pkg|firefox-developer-edition}}}}<br />
* {{App|Firefox Extended Support Release|long-term supported version|https://www.mozilla.org/firefox/organizations/|{{AUR|firefox-esr}} or {{AUR|firefox-esr-bin}}}}<br />
* {{App|Firefox Beta|cutting-edge version|https://www.mozilla.org/firefox/channel/desktop/#beta|{{AUR|firefox-beta}} or {{AUR|firefox-beta-bin}}}}<br />
* {{App|Firefox Nightly|nightly builds for testing ([https://developer.mozilla.org/Firefox/Experimental_features experimental features])|https://www.mozilla.org/firefox/channel/desktop/#nightly|{{AUR|firefox-nightly}}}} <br />
* {{App|Firefox KDE|Version of Firefox that incorporates an OpenSUSE patch for better [[#KDE/GNOME integration|KDE integration]] than is possible through simple Firefox plugins.|https://build.opensuse.org/package/show/mozilla:Factory/MozillaFirefox|{{AUR|firefox-kde-opensuse}}}}<br />
* On top of the different Mozilla build channels, a number of forks exist with more or less special features; see [[List of applications#Gecko-based]].<br />
<br />
A number of language packs are available for Firefox, other than the standard English. Language packs are usually named as {{ic|firefox-i18n-''languagecode''}} (where {{ic|''languagecode''}} can be any language code, such as '''de''', '''ja''', '''fr''', etc.). For a list of available language packs see [https://www.archlinux.org/packages/extra/any/firefox-i18n/ firefox-i18n] for {{Pkg|firefox}},[https://www.archlinux.org/packages/community/any/firefox-developer-edition-i18n/ firefox-developer-edition-i18n] for {{Pkg|firefox-developer-edition}} and [https://aur.archlinux.org/packages/?K=firefox-nightly- firefox-nightly-] for {{AUR|firefox-nightly}}.<br />
<br />
== Add-ons ==<br />
<br />
Firefox is well known for its large library of add-ons which can be used to add new features or modify the behavior of existing features. Firefox's "Add-ons Manager" is used to manage installed add-ons or find new ones. <br />
<br />
For instructions on how to install add-ons and a list of add-ons, see [[Browser extensions]].<br />
<br />
=== Adding search engines ===<br />
<br />
Search engines may be added to Firefox by creating bookmarks with the {{ic|Location}} field using search URLs completed with %s in place of the query and the {{ic|Keyword}} field completed with user-defined characters:<br />
<br />
Location:<br />
https://duckduckgo.com/html/?q=%s<br />
Keyword:<br />
d<br />
<br />
Searches are performed by pre-pending the search term with the keyword of the specified search engine: {{ic|d archwiki}} will query DuckDuckGo using the search term {{ic|archwiki}}<br />
<br />
Search engines may also be added to Firefox through add-on extensions, see [https://addons.mozilla.org/firefox/search-tools/ this page] for a list of available search tools and engines.<br />
<br />
A very extensive list of search engines can be found at the [https://mycroftproject.com/ Mycroft Project].<br />
<br />
Also, you can use the [https://firefox.maltekraus.de/extensions/add-to-search-bar add-to-searchbar] extension to add a search to your search bar from any web site, by simply right clicking on the site's search field and selecting ''Add to Search Bar...''<br />
<br />
==== firefox-extension-arch-search ====<br />
<br />
[[Install]] the {{AUR|firefox-extension-arch-search}} package to add Arch-specific searches (AUR, wiki, forum, packages, etc) to the Firefox search toolbar.<br />
<br />
== Plugins ==<br />
<br />
The only plugin supported by Firefox is [[Browser plugins#Adobe Flash Player|Adobe Flash Player]] (NPAPI version). Support for Flash will be [https://groups.google.com/g/mozilla.dev.platform/c/NsdReYslBU4/m/b9FwjVAbBAAJ removed] in Firefox 85. Other plugins are [https://support.mozilla.org/en-US/kb/npapi-plugins no longer supported].<br />
<br />
To find out what plugins are installed/enabled, enter:<br />
<br />
about:plugins<br />
<br />
in the Firefox address bar or go to the ''Add-ons'' entry in the Firefox Menu and select the ''Plugins'' tab.<br />
<br />
== Configuration ==<br />
<br />
Firefox exposes a number of configuration options. To examine them, enter in the Firefox address bar:<br />
<br />
about:config<br />
<br />
Once set, these affect the user's current profile, and may be synchronized across all devices via [https://www.mozilla.org/firefox/sync/ Firefox Sync]. Please note that only a subset of the {{ic|about:config}} entries are synchronized by this method, and the exact subset may be found by searching for {{ic|services.sync.prefs}} in {{ic|about:config}}. Additional preferences and third party preferences may be synchronized by creating new boolean entries prepending the config value with {{ic|services.sync.prefs.sync}} ([https://developer.mozilla.org/en-US/docs/Archive/Mozilla/Firefox_Sync/Syncing_custom_preferences documentation] is still applicable.) To synchronize the whitelist for the extension [https://addons.mozilla.org/firefox/addon/noscript/ NoScript]:<br />
<br />
services.sync.prefs.sync.capability.policy.maonoscript.sites<br />
<br />
The boolean {{ic|noscript.sync.enabled}} must be set to {{ic|true}} to synchronize the remainder of NoScript's preferences via Firefox Sync.<br />
<br />
Firefox also allows configuration for a profile via a {{ic|user.js}} file: [http://kb.mozillazine.org/User.js_file user.js] kept in the profile folder, usually {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/}}. For a useful starting point, see e.g [https://github.com/pyllyukko/user.js custom user.js] which is targeted at privacy/security conscious users.<br />
<br />
One drawback of the above approach is that it is not applied system-wide. Furthermore, this is not useful as a "pre-configuration", since the profile directory is created after first launch of the browser. You can, however, let ''firefox'' create a new profile and, after closing it again, [https://support.mozilla.org/en-US/kb/back-and-restore-information-firefox-profiles#w_restoring-a-profile-backup copy the contents] of an already created profile folder into it. <br />
<br />
Sometimes it may be desired to lock certain settings, a feature useful in widespread deployments of customized Firefox. In order to create a system-wide configuration, follow the steps outlined in [http://kb.mozillazine.org/Locking_preferences Locking preferences]:<br />
<br />
1. Create {{ic|/usr/lib/firefox/defaults/pref/local-settings.js}}:<br />
<br />
pref("general.config.obscure_value", 0);<br />
pref("general.config.filename", "mozilla.cfg");<br />
<br />
2. Create {{ic|/usr/lib/firefox/mozilla.cfg}} (this stores the actual configuration):<br />
<br />
//<br />
//...your settings...<br />
// e.g to disable Pocket, uncomment the following line<br />
// lockPref("browser.pocket.enabled", false);<br />
<br />
Please note that the first line must contain exactly {{ic|//}}. The syntax of the file is similar to that of {{ic|user.js}}.<br />
<br />
=== Multimedia playback ===<br />
<br />
Firefox uses [[FFmpeg]] for playing multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. Go to [http://demo.nimius.net/video_test/ video-test page] or [https://hpr.dogphilosophy.net/test/ audio-test page] to check which formats are actually supported.<br />
<br />
Firefox uses [[PulseAudio]] for audio playback and capture. For sound to work, you need to install the {{Pkg|pulseaudio}} package.<br />
<br />
In case, for whatever reason, [[PulseAudio]] is not an option for you, you can use [[Advanced Linux Sound Architecture#PulseAudio compatibility|apulse]] instead. To make this work, it is necessary to exclude {{ic|/dev/snd/}} from Firefox' sandboxing by adding it to the comma-separated list in {{ic|about:config}}:<br />
<br />
security.sandbox.content.write_path_whitelist<br />
<br />
{{Note|The trailing slash on {{ic|/dev/snd/}} is important, otherwise ''apulse'' will report "Permission denied" errors.}}<br />
<br />
If you have no audio even when using ''apulse'', try adding {{ic|16}} to {{ic|security.sandbox.content.syscall_whitelist}} in {{ic|about:config}}.<br />
<br />
==== HTML5 DRM/Widevine ====<br />
<br />
Widevine is a digital rights management tool that Netflix, Amazon Prime Video, and others use to protect their video content. It can be enabled in ''Preferences > General > Digital Rights Management (DRM) Content''. If you visit a Widevine-enabled page when this setting is disabled, Firefox will display a prompt below the address bar asking for permission to install DRM. Approve this and then wait for the "Downloading" bar to disappear, you are now able to watch videos from Widevine protected sites.<br />
<br />
It is also required that the private mode browsing is disabled, for the window and in the preferences.<br />
<br />
==== Open With extension ====<br />
<br />
# Install [https://addons.mozilla.org/firefox/addon/open-with/ Open With] add-on.<br />
# Go to ''Add-ons > Open With > Preferences''.<br />
# Proceed with instructions to install a file in your system and test the installation. <br />
# Click ''Add browser''.<br />
# In the dialog write a name for this menu entry and command to start a video streaming capable player (e.g. [[mpv|/usr/bin/mpv]]).<br />
# (Optional step) Add needed arguments to the player (e.g. you may want {{ic|--force-window --ytdl}} for ''mpv'')<br />
# Right click on links or visit pages containing videos. Select newly created entry from Open With's menu and if the site is supported, the player will open as expected.<br />
<br />
The same procedure can be used to associate video downloaders such as ''youtube-dl''.<br />
<br />
==== Hardware video acceleration ====<br />
<br />
[[Hardware video acceleration]] via VA-API is available under [[Wayland]] (see [https://mastransky.wordpress.com/2020/06/03/firefox-on-fedora-finally-gets-va-api-on-wayland/ Firefox gets VA-API on Wayland]) and X.org (see [https://bugzilla.mozilla.org/show_bug.cgi?id=1619523 bugzilla X11 implement VAAPI] and [https://www.phoronix.com/scan.php?page=news_item&px=Firefox-80-VA-API-X11 Phoronix news VA API X11]).<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* [[AMDGPU]] users under {{pkg|linux-hardened}} may need to rebuild ''linux-hardened'' with {{ic|1=CONFIG_CHECKPOINT_RESTORE=y}} due to {{pkg|mesa}} [https://gitweb.gentoo.org/repo/gentoo.git/tree/media-libs/mesa/mesa-9999.ebuild requiring the kcmp syscall].<br />
* Hardware video acceleration on multi-GPU systems is affected by a [https://bugzilla.mozilla.org/show_bug.cgi?id=1622132 device selection bug].<br />
}}<br />
<br />
Before trying VA-API support in Firefox be sure to:<br />
<br />
* Install correct VA-API driver for your video card and verify VA-API has been enabled and working correctly, see [[Hardware video acceleration]];<br />
** For Intel graphics, use the i965 driver {{Pkg|libva-intel-driver}} if your hardware supports it. <br />
** The iHD driver {{Pkg|intel-media-driver}} (needed by Broadwell or newer) is currently broken due to sandbox violations caused by the driver ([https://bugzilla.mozilla.org/show_bug.cgi?id=1619585 see Bugzilla 1619585]). This can be worked around by setting the {{ic|security.sandbox.content.level}} flag to {{ic|0}}, at the risk of losing sandbox protection.<br />
* Use a compositor that supports hardware acceleration, either:<br />
** Gecko's OpenGL back-end, which can be enabled as explained in [[/Tweaks#Enable OpenGL compositor]];<br />
** WebRender from the new Servo browser engine, which can be enabled as explained in [[/Tweaks#Enable WebRender compositor]];<br />
* Set the following flags in {{ic|about:config}}:<br />
** {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|true}} in order to enable the use of VA-API with FFmpeg;<br />
** {{ic|media.ffvpx.enabled}} to {{ic|false}} to disable the internal decoders for VP8/VP9.<br />
** If your hardware doesn't support AV1, you can set {{ic|media.av1.enabled}} to {{ic|false}} to force sites like YouTube provide other formats.<br />
* Run Firefox with the following [[environment variable]] enabled:<br />
** In Wayland, with {{ic|1=MOZ_ENABLE_WAYLAND=1}}, see [[#Wayland]].<br />
** In X.org, with {{ic|1=MOZ_X11_EGL=1}}.<br />
<br />
{{Tip|<br />
* You can verify that VA-API is enabled by running Firefox with {{ic|1=MOZ_LOG="PlatformDecoderModule:5"}} environment variable and check in the log output that VA-API is enabled and used (search for the "VA-API" string) when playing a video for example. Pay attention to these logs as they might indicate that only one of the two possible compositors described before (OpenGL or WebRender) works with VA-API on your particular setup.<br />
* For Intel GPU, the {{ic|intel_gpu_top}} utility from package {{pkg|intel-gpu-tools}} can be used to monitor the GPU activity during video playback for example.<br />
* To allow hardware decoding in YouTube, the video codec used must be supported by the hardware. The profiles supported by your GPU can be checked with [[Hardware video acceleration#Verifying VA-API]] and the YouTube codecs used can be controlled with the [https://addons.mozilla.org/firefox/addon/h264ify/ h264ify] or [https://addons.mozilla.org/firefox/addon/enhanced-h264ify/ enhanced-h264ify] extensions. Alternatively, you can install {{AUR|firefox-h264ify}}.}}<br />
<br />
{{Note|Some videos (i.e. YouTube VR) may show a black image after setting {{ic|media.ffvpx.enabled}} to {{ic|false}} }}<br />
<br />
=== Spell checking ===<br />
<br />
Firefox can use system-wide installed [[Hunspell]] dictionaries as well as dictionaries installed through its own extension system.<br />
<br />
To enable spell checking for a specific language right click on any text field and check the ''Check Spelling'' box. To select a language for spell checking to you have right click again and select your language from the ''Languages'' sub-menu.<br />
<br />
When your default language choice does not stick, see [[#Firefox does not remember default spell check language]].<br />
<br />
==== System-wide Hunspell dictionaries ====<br />
<br />
Install [[Hunspell]] and its dictionaries for the languages you require.<br />
<br />
==== Dictionaries as extensions ====<br />
<br />
To get more languages right click on any text field and just click ''Add Dictionaries...'' and select the dictionary you want to install from the [https://addons.mozilla.org/firefox/language-tools/ Dictionaries and Language Packs list].<br />
<br />
{{Tip|For Russian, the extension is packaged as {{Pkg|firefox-spell-ru}}.}}<br />
<br />
=== KDE/GNOME integration ===<br />
<br />
* To bring the [[KDE]] look to GTK apps (including Firefox), install {{Pkg|breeze-gtk}} and {{Pkg|kde-gtk-config}}. Afterwards, go to ''System Settings > Application Style > Configure GNOME/GTK Application Style…''. Choose 'Breeze' or 'Breeze-Dark' in 'GTK2 Theme' and 'GTK3 Theme'.<br />
* To use the KDE file selection and print dialogs in Firefox 64 or newer, install {{Pkg|xdg-desktop-portal}} and {{Pkg|xdg-desktop-portal-kde}}, then add {{ic|1=GTK_USE_PORTAL=1}} to the [[Desktop entries#Modify environment variables|application startup command]].<br />
* For integration with [[KDE]] MIME type system, proxy and file dialog, one can use {{AUR|firefox-kde-opensuse}} variant from AUR with OpenSUSE’s patches applied. Alternatively, integration with MIME types can be achieved by creating a symbolic link to the MIME database {{ic|~/.config/mimeapps.list}} from the deprecated {{ic|~/.local/share/applications/mimeapps.list}} that is used by Firefox. See [[XDG MIME Applications#mimeapps.list]].<br />
* Extensions/add-ons may provide additional integration, such as:<br />
** Browser integration in [[Plasma]]: requires {{Pkg|plasma-browser-integration}} and the [https://addons.mozilla.org/firefox/addon/plasma-integration/ Plasma Integration add-on].<br />
** {{AUR|mozilla-extension-gnome-keyring-git}}{{Broken package link|package not found}} (all-JavaScript implementation) to integrate Firefox with [[GNOME Keyring]]. To make firefox-gnome-keyring use your login keychain, set {{ic|extensions.gnome-keyring.keyringName}} to {{ic|login}} in {{ic|about:config}}. Note the lowercase 'l' despite the the keychain name having an uppercase 'L' in Seahorse.<br />
<br />
== Tips and tricks ==<br />
<br />
For general enhancements see [[Firefox/Tweaks]], for privacy related enhancements see [[Firefox/Privacy]].<br />
<br />
=== Dark themes ===<br />
<br />
If a dark [[GTK]] theme is in use (e.g. Arc Dark), it is recommended to start Firefox with a brighter one (e.g. Adwaita). See [[GTK#Themes]] and [[Firefox/Tweaks#Unreadable input fields with dark GTK themes]] for more information.<br />
<br />
Alternatively, starting with Firefox 68 you can make the all Firefox interfaces and even other websites respect dark themes, irrespective of the system GTK theme and Firefox theme. To do this, set {{ic|browser.in-content.dark-mode}} to {{ic|true}} and {{ic|ui.systemUsesDarkTheme}} to {{ic|1}} in {{ic|about:config}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1488384#c23].<br />
<br />
=== Frame rate ===<br />
<br />
If Firefox is unable to automatically detect the right value, it will default to 60 fps. To manually correct this, set {{ic|layout.frame_rate}} to the refresh rate of your monitor (e.g. 144 for 144 Hz).<br />
<br />
=== Memory limit ===<br />
<br />
To prevent pages from abusing memory (and possible [[Wikipedia:Out_of_memory|OOM]]), we can use [[Firejail]] with the {{ic|rlimit-as}} option.<br />
<br />
=== New tabs position ===<br />
<br />
To control where new tabs appears (relative or absolute), use {{ic|browser.tabs.insertAfterCurrent}} and {{ic|browser.tabs.insertRelatedAfterCurrent}}. See [https://support.mozilla.org/en/questions/1229062] for more information.<br />
<br />
=== Screenshot of webpage ===<br />
<br />
You can ''Take a Screenshot'' by either clicking the ''Page actions'' button (the three horizontal dots) in the address bar or by right-clicking on the webpage. See [https://support.mozilla.org/en-US/kb/firefox-screenshots] for more information.<br />
<br />
As an alternative you can use the screenshot button in the [https://developer.mozilla.org/en-US/docs/Tools/Taking_screenshots Developer Tools].<br />
<br />
=== Wayland ===<br />
<br />
More recent versions of Firefox support opting into [[Wayland]] via an environment variable.<br />
<br />
$ MOZ_ENABLE_WAYLAND=1 firefox<br />
<br />
To make this permanent, see [[Environment variables#Graphical environment]] and start Firefox via the desktop launcher like you normally would. To verify it worked check the ''Window Protocol'' again.<br />
<br />
You may enter {{ic|about:support}} in the URL bar to check the ''Window Protocol''. It should say ''wayland/drm'' instead of ''x11'' nor ''xwayland''.<br />
<br />
=== Window manager rules ===<br />
<br />
To apply different configurations to Firefox windows, change the WM_CLASS string by using Firefox's {{ic|--class}} option, to a custom one.<br />
<br />
==== Profiles ====<br />
<br />
To start new Firefox instances, multiple profiles are required. To create a new profile:<br />
<br />
$ firefox [--new-instance] -P<br />
<br />
Class can be specified when launching Firefox with a not-in-use profile:<br />
<br />
$ firefox [--new-instance] -P ''profile_name'' --class=''class_name''<br />
<br />
=== Touchscreen gestures and pixel-perfect trackpad scrolling ===<br />
<br />
{{Merge|Firefox/Tweaks#Enable touchscreen gestures|Same solution.}}<br />
<br />
To enable touch gestures (like scrolling and pinch-to-zoom) and one-to-one trackpad scrolling (as can be witnessed with GTK3 applications like Nautilus), set the {{ic|1=MOZ_USE_XINPUT2=1}} [[environment variable]] before starting Firefox.<br />
<br />
=== Multiple home pages ===<br />
<br />
To have multiple tabs opened when starting Firefox open a new window and then open the sites you want to have as "home tabs".<br />
<br />
Now go to ''Preferences > Home'' and under ''Homepage and new windows'' click the ''Use Current Pages'' button.<br />
<br />
Alternatively go directly to ''Preferences > Home'' and now under ''Homepage and new windows'' set the first field to ''Custom URLs..'' and enter the pages you want as new home pages in the following format:<br />
<br />
<nowiki>https://url1.com|https://url2.com|https://url3.com</nowiki><br />
<br />
== Troubleshooting ==<br />
<br />
=== Extension X does not work on some Mozilla owned domains ===<br />
<br />
By default extensions will not affect pages designated by {{ic|extensions.webextensions.restrictedDomains}}. If this is not desired, this field can be cleared (special pages such as {{ic|about:*}} will not be affected).<br />
<br />
=== Firefox startup takes very long ===<br />
<br />
If Firefox takes much longer to start up than other browsers, it may be due to lacking configuration of the localhost in {{ic|/etc/hosts}}. See [[Network configuration#Local network hostname resolution]] on how to set it up. <br />
<br />
=== Font troubleshooting ===<br />
<br />
See [[Font configuration]].<br />
<br />
Firefox has a setting which determines how many replacements it will allow from fontconfig. To allow it to use all your replacement-rules, change {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|127}} (the highest possible value).<br />
<br />
Firefox ships with ''Twemoji Mozilla'' font. To use system emoji font set {{ic|font.name-list.emoji}} to {{ic|emoji}} in {{ic|about:config}}.<br />
<br />
Firefox has problems with [[Emoji]] presentation [https://bugzilla.mozilla.org/show_bug.cgi?id=1509988]. Set {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|0}} as workaround.<br />
<br />
=== Setting an email client ===<br />
<br />
Inside the browser, {{ic|mailto}} links by default are opened by a web application such as Gmail or Yahoo Mail. To set an external email program, go to ''Preferences > Applications'' and modify the ''action'' corresponding to the {{ic|mailto}} content type; the file path will need to be designated (e.g. {{ic|/usr/bin/kmail}} for Kmail).<br />
<br />
Outside the browser, {{ic|mailto}} links are handled by the {{ic|x-scheme-handler/mailto}} mime type, which can be easily configured with [[xdg-mime]]. See [[Default applications]] for details and alternatives.<br />
<br />
=== File association ===<br />
<br />
See [[Default applications]].<br />
<br />
=== Firefox keeps creating ~/Desktop even when this is not desired ===<br />
<br />
Firefox uses {{ic|~/Desktop}} as the default place for download and upload files. To change it to another folder, set the {{ic|XDG_DESKTOP_DIR}} option as explained in [[XDG user directories]].<br />
<br />
=== Make plugins respect blocked pop-ups ===<br />
<br />
Some plugins can misbehave and bypass the default settings, such as the Flash plugin. You can prevent this by doing the following:<br />
<br />
# Type {{ic|about:config}} into the address bar.<br />
# Right-click on the page and select ''New > Integer''.<br />
# Name it {{ic|privacy.popups.disable_from_plugins}}.<br />
# Set the value to {{ic|2}}.<br />
<br />
The possible values are:<br />
<br />
* {{ic|'''0'''}}: Allow all popups from plugins.<br />
* {{ic|'''1'''}}: Allow popups, but limit them to {{ic|dom.popup_maximum}}.<br />
* {{ic|'''2'''}}: Block popups from plugins.<br />
* {{ic|'''3'''}}: Block popups from plugins, even on whitelisted sites.<br />
<br />
=== Changes to userChrome.css and userContent.css are ignored ===<br />
<br />
Set {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|true}} in {{ic|about:config}}<br />
<br />
=== Middle-click behavior ===<br />
<br />
To use the middle mouse button to paste whatever text has been highlighted/added to the clipboard, as is common in UNIX-like operating systems, set either {{ic|middlemouse.contentLoadURL}} or {{ic|middlemouse.paste}} to {{ic|true}} in {{ic|about:config}}. Having {{ic|middlemouse.contentLoadURL}} enabled was the default behaviour prior to Firefox 57.<br />
<br />
To scroll on middle-click (default for Windows browsers) set {{ic|general.autoScroll}} to {{ic|true}}.<br />
<br />
=== Backspace does not work as the 'Back' button ===<br />
<br />
According to [http://kb.mozillazine.org/Browser.backspace_action MozillaZine], the {{ic|Backspace}} key was mapped based on which platform the browser was running on. As a compromise, this preference was created to allow the {{ic|Backspace}} key to either go back/forward, scroll up/down a page, or do nothing.<br />
<br />
To make {{ic|Backspace}} go back one page in the tab's history and {{ic|Shift+Backspace}} go forward, set {{ic|browser.backspace_action}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
To have the {{ic|Backspace}} key scroll up one page and {{ic|Shift+Backspace}} scroll down one page, set {{ic|browser.backspace_action}} to {{ic|1}}. Setting this property to any other value will leave the key unmapped (Arch Linux defaults to {{ic|2}}, in other words, it is unmapped by default).<br />
<br />
=== Firefox does not remember login information ===<br />
<br />
It may be due to a corrupted {{ic|cookies.sqlite}} file in [https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data Firefox's profile] folder. In order to fix this, just rename or remove {{ic|cookie.sqlite}} while Firefox is not running.<br />
<br />
Open a terminal of choice and type the following:<br />
<br />
$ rm -f ~/.mozilla/firefox/<profile id>.default/cookies.sqlite<br />
<br />
The profile id is a random 8 character string.<br />
<br />
Restart Firefox and see if it solved the problem.<br />
<br />
If it didn't work, check if there exists a {{ic|cookies.sqlite.bak}} file that you could use to manually restore the cookies.<br />
<br />
=== Cannot enter/leave fullscreen ===<br />
<br />
If Firefox detects an [https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html EWMH/ICCCM] compliant window manager, it will try to send a WM_STATE message to the root window to request Firefox be made to enter (or leave) full-screen mode (as defined by the window manager). Window managers are allowed to ignore it, but if they do, Firefox will assume the request got denied and propagate it to the end user which results in nothing happening. This may result in not being able to full screen a video. A general workaround is to set the {{ic|full-screen-api.ignore-widgets}} to {{ic|true}} in {{ic|about:config}}. <br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=1189622 Bugzilla 1189622].<br />
<br />
=== Firefox detects the wrong version of my plugin ===<br />
<br />
When you close Firefox, the latter saves the current timestamp and version of your plugins inside {{ic|pluginreg.dat}} located in your profile folder, typically in {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/}}.<br />
<br />
If you upgraded your plugin when Firefox was still running, you will thus have the wrong information inside that file. The next time you will restart Firefox you will get that message {{ic|Firefox has prevented the outdated plugin "XXXX" from running on ...}} when you will be trying to open content dedicated to that plugin on the web. This problem often appears with the official [[Browser plugins#Adobe Flash Player|Adobe Flash Player plugin]] which has been upgraded while Firefox was still running.<br />
<br />
The solution is to remove the file {{ic|pluginreg.dat}} from your profile and that is it. Firefox will not complain about the missing file as it will be recreated the next time Firefox will be closed. [https://bugzilla.mozilla.org/show_bug.cgi?id=1109795#c16]<br />
<br />
=== JavaScript context menu does not appear on some sites ===<br />
<br />
You can try setting {{ic|dom.w3c_touch_events.enabled}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
=== Firefox does not remember default spell check language ===<br />
<br />
The default spell checking language can be set as follows:<br />
<br />
# Type {{ic|about:config}} in the address bar.<br />
# Set {{ic|spellchecker.dictionary}} to your language of choice, for instance {{ic|en_GB}}.<br />
# Notice that the for dictionaries installed as a Firefox plugin the notation is {{ic|en-GB}}, and for {{Pkg|hunspell}} dictionaries the notation is {{ic|en_GB}}.<br />
<br />
When you only have system wide dictionaries installed with {{Pkg|hunspell}}, Firefox might not remember your default dictionary language settings. This can be fixed by having at least one [https://addons.mozilla.org/firefox/language-tools/ dictionary] installed as a Firefox plugin. Notice that now you will also have a tab ''Dictionaries'' in ''Add-ons''. You may have to change the order of ''preferred language for displaying pages'' in {{ic|about:preferences#general}} to make the spell check default to the language of the addon dictionary.<br />
<br />
Related questions on the '''StackExchange''' platform: [https://stackoverflow.com/questions/26936792/change-firefox-spell-check-default-language/29446115], [https://stackoverflow.com/questions/21542515/change-default-language-on-firefox/29446353], [https://askubuntu.com/questions/184300/how-can-i-change-firefoxs-default-dictionary/576877]<br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=776028 Bugzilla 776028], [https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/1026869 Ubuntu bug 1026869]<br />
<br />
=== Some MathML symbols are missing ===<br />
<br />
You need some Math fonts, namely Latin Modern Math and STIX (see this MDN page: [https://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts#Linux]), to display MathML correctly.<br />
<br />
In Arch Linux, these fonts are provided by {{Pkg|texlive-core}} '''and''' {{Pkg|texlive-fontsextra}}, but they are not available to fontconfig by default. See [[TeX Live#Making fonts available to Fontconfig]] for details. You can also try other [[Fonts#Math|Math fonts]].<br />
<br />
=== Tearing video in fullscreen mode ===<br />
<br />
If you are using the Xorg Intel or Nouveau drivers and experience tearing video in fullscreen mode, try [[Firefox/Tweaks#Enable OpenGL compositor]].<br />
<br />
=== Tearing when scrolling ===<br />
<br />
Try disabling smooth scrolling in ''Preferences > Browsing''.<br />
<br />
=== Firefox WebRTC module cannot detect a microphone ===<br />
<br />
WebRTC applications for instance [https://mozilla.github.io/webrtc-landing/gum_test.html Firefox WebRTC getUserMedia test page] say that microphone cannot be found. Issue is reproducible for both ALSA or PulseAudio setup. Firefox debug logs show the following error:<br />
<br />
{{hc|1=$ NSPR_LOG_MODULES=MediaManager:5,GetUserMedia:5 firefox|2=<br />
...<br />
[Unnamed thread 0x7fd7c0654340]: D/GetUserMedia VoEHardware:GetRecordingDeviceName: Failed 1<br />
}}<br />
<br />
You can try setting {{ic|media.navigator.audio.full_duplex}} property to {{ic|false}} at {{ic|about:config}} Firefox page and restart Firefox.<br />
<br />
This can also help if you are using the PulseAudio [[PulseAudio/Troubleshooting#Enable Echo/Noise-Cancellation|module-echo-cancel]] and Firefox does not recognise the virtual echo canceling source.<br />
<br />
=== Cannot login with my Chinese account ===<br />
<br />
Firefox provides a local service for Chinese users, with a local account totally different from the international one. Firefox installed with the {{Pkg|firefox}} package uses the international account system by default, to change into the Chinese local service, you should install the add-on manager on [http://mozilla.com.cn/thread-343905-1-1.html this page], then you can login with your Chinese account now.<br />
<br />
=== No audio on certain videos when using JACK and PulseAudio ===<br />
<br />
If you are using JACK in combination with PulseAudio and cannot hear any sound on some videos it could be because those videos have mono audio. This happens if your JACK setup uses more than just stereo, but you use normal headphones. To fix this you simply have to connect the {{ic|front-center}} port from the PulseAudio JACK Sink to both {{ic|playback_1}} and {{ic|playback_2}} ports of the system output.<br />
<br />
You can also do this automatically using a script:<br />
<br />
{{hc|jack-mono.sh<br />
|2=#!/bin/sh<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_1"<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_2"<br />
}}<br />
<br />
Keep in mind that the names for the sink and the ports might be different for you. You can check what your JACK setup looks like with a Patchbay like Catia from {{Pkg|cadence}}.<br />
<br />
=== Geolocation does not work ===<br />
<br />
Recently, Google limited the usage its location service for Arch Linux, which causes the following error when geolocation is enabled on a website: {{ic|Geolocation error: Unknown error acquiring position}}. Region-locked services such as [https://www.hulu.com/ Hulu] may display a similar error indicating that your location could not be determined even though you've allowed location services for the site.<br />
<br />
To avoid these problems, you can switch to use the [https://location.services.mozilla.com/ Mozilla Location Service]. In {{ic|about:config}} change the {{ic|geo.provider.network.url}} setting to:<br />
<br />
<nowiki>https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%</nowiki><br />
<br />
See {{Bug|65241}} for more details.<br />
<br />
=== Right mouse button instantly clicks the first option in window managers ===<br />
<br />
This problem has been observed in [[i3]], [[bspwm]] and [[xmonad]].<br />
<br />
To fix it, navigate to {{ic|about:config}} and change {{ic|ui.context_menus.after_mouseup}} to {{ic|true}}.<br />
<br />
See [https://www.reddit.com/r/i3wm/comments/88k0yt/right_mouse_btn_instantly_clicks_first_option_in/]<br />
<br />
== See also ==<br />
<br />
* [https://www.mozilla.org/firefox/ Official website]<br />
* [https://www.mozilla.org/ Mozilla Foundation]<br />
* [[MozillaWiki:Firefox]]<br />
* [[Wikipedia:Mozilla Firefox]]<br />
* [https://addons.mozilla.org/ Firefox Add-ons]<br />
* [https://addons.mozilla.org/firefox/themes/ Firefox themes]<br />
* [https://ftp.mozilla.org/pub/firefox/releases/ Mozilla's FTP]<br />
* [http://forums.mozillazine.org/ mozillaZine] unofficial forums</div>Progandyhttps://wiki.archlinux.org/index.php?title=ConnMan&diff=642759ConnMan2020-11-28T21:04:10Z<p>Progandy: /* Avoiding conflicts with local DNS server */ Mention a way to preserve DHCP DNS servers in /var/run/connman</p>
<hr />
<div>[[Category:Network managers]]<br />
[[fr:Connman]]<br />
[[it:ConnMan]]<br />
[[ja:ConnMan]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related articles end}}<br />
<br />
[https://01.org/connman ConnMan] is a command-line network manager designed for use with embedded devices and fast resolve times. It is modular through a [https://git.kernel.org/cgit/network/connman/connman.git/tree/plugins plugin architecture], but has native [[Wikipedia:DHCP|DHCP]] and [[NTP]] support.[https://git.kernel.org/cgit/network/connman/connman.git/tree/src/]<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|connman}} package. {{Pkg|wpa_supplicant}}, {{Pkg|bluez}}, and {{pkg|openvpn}} are optional dependencies required for Wi-Fi, Bluetooth, and VPN functionality respectively.<br />
<br />
Before [[enabling]] {{ic|connman.service}}, ensure any existing [[network configuration]] is disabled.<br />
<br />
ConnMan comes with the {{man|1|connmanctl}} CLI, there are various [[#Front-ends]] available.<br />
<br />
=== Front-ends ===<br />
<br />
* {{App|cmst|Qt GUI for ConnMan.|https://github.com/andrew-bibb/cmst|{{Pkg|cmst}}}}<br />
* {{App|connman-ncurses|Simple ncurses UI for ConnMan; not all of connman functionality is implemented, but usable (with X or from terminal without X), see the [https://github.com/eurogiciel-oss/connman-json-client/wiki wiki].|https://github.com/eurogiciel-oss/connman-json-client|{{AUR|connman-ncurses-git}}}}<br />
* {{App|ConnMan-UI|GTK3 client applet.|https://github.com/tbursztyka/connman-ui|{{AUR|connman-ui-git}}}}<br />
* {{App|connman_dmenu|Client/frontend for dmenu.|https://github.com/taylorchu/connman_dmenu|{{AUR|connman_dmenu-git}}}}<br />
* {{App|Econnman|Enlightenment desktop panel applet.|http://www.enlightenment.org|{{AUR|econnman}}}}<br />
* {{App|LXQt-Connman-Applet|LXQt desktop panel applet.|https://github.com/lxqt/lxqt-connman-applet|{{AUR|lxqt-connman-applet}}}}<br />
* {{App|connman-gtk| GTK client.|https://github.com/jgke/connman-gtk|{{AUR|connman-gtk}}}}<br />
* {{App|gnome-extension-connman| Gnome3 extension for connman; it contains only some of the functionality without installing connman-gtk.|https://github.com/jgke/gnome-extension-connman|https://extensions.gnome.org/extension/981/connman-extension/}}<br />
<br />
== Usage ==<br />
<br />
{{Expansion|Only Wired and Wi-Fi plugins are described.}}<br />
<br />
ConnMan comes with the {{ic|connmanctl}} command-line interface, see {{man|1|connmanctl}}.<br />
If you do not provide any commands {{ic|connmanctl}} starts as an interactive shell.<br />
<br />
''ConnMan'' automatically handles wired connections.<br />
<br />
=== Wi-Fi ===<br />
<br />
==== Enabling and disabling wifi ====<br />
<br />
To check if wifi is enabled you can run {{ic|connmanctl technologies}} and check for the line that says {{ic|Powered: True/False}}.<br />
To power the wifi on you can run {{ic|connmanctl enable wifi}} or if you need to disable it you can run {{ic|connmanctl disable wifi}}.<br />
Other ways to enable wifi could include using the {{ic|Fn}} keys on the laptop to turn it on or running {{ic|ip link set <interface> up}}.<br />
<br />
==== Connecting to an open access point ====<br />
<br />
To scan the network {{ic|connmanctl}} accepts simple names called ''technologies''. To scan for nearby Wi-Fi networks:<br />
<br />
$ connmanctl scan wifi<br />
<br />
To list the available networks found after a scan run (example output): <br />
<br />
{{hc|$ connmanctl services|<br />
*AO MyNetwork wifi_dc85de828967_68756773616d_managed_psk<br />
OtherNET wifi_dc85de828967_38303944616e69656c73_managed_psk <br />
AnotherOne wifi_dc85de828967_3257495245363836_managed_wep<br />
FourthNetwork wifi_dc85de828967_4d7572706879_managed_wep<br />
AnOpenNetwork wifi_dc85de828967_4d6568657272696e_managed_none<br />
}}<br />
<br />
To connect to an open network, use the second field beginning with {{ic|wifi_}}:<br />
<br />
$ connmanctl connect wifi_dc85de828967_4d6568657272696e_managed_none<br />
<br />
{{Tip|Network names can be tab-completed.}}<br />
<br />
You should now be connected to the network. Check using {{ic|connmanctl state}} or {{ic|ip addr}}.<br />
<br />
==== Connecting to a protected access point ====<br />
<br />
For protected access points you will need to provide some information to the ConnMan daemon, at the very least a password or a passphrase.<br />
<br />
The commands in this section show how to run {{ic|connmanctl}} in interactive mode, it is required for running the {{ic|agent}} command. To start interactive mode simply type: <br />
<br />
$ connmanctl<br />
<br />
You then proceed almost as above, first scan for any Wi-Fi ''technologies'':<br />
<br />
connmanctl> scan wifi<br />
<br />
To list services:<br />
<br />
connmanctl> services<br />
<br />
Now you need to register the agent to handle user requests. The command is:<br />
<br />
connmanctl> agent on<br />
<br />
You now need to connect to one of the protected services. To do this easily, just use tab completion for the wifi_ service. If you were connecting to OtherNET in the example above you would type:<br />
<br />
connmanctl> connect wifi_dc85de828967_38303944616e69656c73_managed_psk<br />
<br />
The agent will then ask you to provide any information the daemon needs to complete the connection. The <br />
information requested will vary depending on the type of network you are connecting to. The agent<br />
will also print additional data about the information it needs as shown in the example below.<br />
<br />
Agent RequestInput wifi_dc85de828967_38303944616e69656c73_managed_psk<br />
Passphrase = [ Type=psk, Requirement=mandatory ]<br />
Passphrase? <br />
<br />
Provide the information requested, in this example the passphrase, and then type:<br />
<br />
connmanctl> quit<br />
<br />
If the information you provided is correct you should now be connected to the protected access point.<br />
<br />
==== Using iwd instead of wpa_supplicant ====<br />
<br />
ConnMan can use {{pkg|iwd}} to connect to wireless networks. The package which is available in community already supports using {{pkg|iwd}} for connecting to wireless networks. As {{pkg|connman}} will start {{pkg|wpa_supplicant}} when it finds it, it is recommended to uninstall {{pkg|wpa_supplicant}}.<br />
<br />
Currently the {{ic|-i}}-option of {{pkg|iwd}} seems to cause that the WiFi-interface gets hidden from {{pkg|connman}}.<br />
<br />
Create the following two service files which should cause {{pkg|connman}} to use {{pkg|iwd}} to connect to wireless networks, regardless if {{pkg|wpa_supplicant}} is installed.<br />
<br />
{{hc|/etc/systemd/system/iwd.service|output=<br />
[Unit]<br />
Description=Internet Wireless Daemon (IWD)<br />
Before=network.target<br />
Wants=network.target<br />
<br />
[Service]<br />
ExecStart=/usr/lib/iwd/iwd<br />
<br />
[Install]<br />
Alias=multi-user.target.wants/iwd.service<br />
}}<br />
<br />
{{hc|/etc/systemd/system/connman_iwd.service|output=<br />
[Unit]<br />
Description=Connection service<br />
DefaultDependencies=false<br />
Conflicts=shutdown.target<br />
RequiresMountsFor=/var/lib/connman<br />
After=dbus.service network-pre.target systemd-sysusers.service iwd.service<br />
Before=network.target multi-user.target shutdown.target<br />
Wants=network.target<br />
Requires=iwd.service<br />
<br />
[Service]<br />
Type=dbus<br />
BusName=net.connman<br />
Restart=on-failure<br />
ExecStart=/usr/bin/connmand --wifi=iwd_agent -n <br />
StandardOutput=null<br />
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SYS_TIME CAP_SYS_MODULE<br />
ProtectHome=true<br />
ProtectSystem=true<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
Then [[enable]]/[[start]] the {{ic|connman_iwd}} service.<br />
<br />
Advantage of using {{pkg|iwd}} instead of {{pkg|wpa_supplicant}} is, that the ping times seem to be much more consistent and the connection seems to be more reliable.<br />
<br />
=== Settings ===<br />
<br />
Settings and profiles are automatically created for networks the user connects to often. They contain fields for the passphrase, essid and other information. Profile settings are stored in directories under {{ic|/var/lib/connman/}} by their service name. To view all network profiles run this command from [[Help:Reading#Regular_user_or_root|root shell]]: <br />
<br />
# cat /var/lib/connman/*/settings<br />
<br />
{{Note|VPN settings can be found in {{ic|/var/lib/connman-vpn/}}.}}<br />
<br />
=== Technologies ===<br />
<br />
Various hardware interfaces are referred to as ''Technologies'' by ConnMan.<br />
<br />
To list available ''technologies'' run: <br />
<br />
$ connmanctl technologies<br />
<br />
To get just the types by their name one can use this one liner:<br />
<br />
$ connmanctl technologies | awk '/Type/ { print $NF }'<br />
<br />
{{Note| The field {{ic|1=Type = tech_name}} provides the technology type used with {{ic|connmanctl}} commands}}<br />
<br />
To interact with them one must refer to the technology by type. ''Technologies'' can be toggled on/off with: <br />
<br />
$ connmanctl enable ''technology_type''<br />
<br />
and:<br />
<br />
$ connmanctl disable ''technology_type''<br />
<br />
For example to toggle off wifi:<br />
<br />
$ connmanctl disable wifi<br />
<br />
{{Warning|connman grabs rfkill events. It is most likely impossible to use {{ic|rfkill}} or {{ic|bluetoothctl}} to (un)block devices, yet hardware keys may still work.[https://git.kernel.org/cgit/network/connman/connman.git/tree/doc/overview-api.txt#n406] Always use {{ic|connmanctl enable{{!}}disable}} }}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Avoid changing the hostname ===<br />
<br />
By default, ConnMan changes the transient hostname (see {{man|1|hostnamectl}}) on a per network basis. This can create problems with X authority: If ConnMan changes your hostname to something else than the one used to generate the xauth magic cookie, then it will become impossible to create new windows. Symptoms are error messages like "No protocol specified" and "Can't open display: :0.0". Manually resetting the host name fixes this, but a permanent solution is to prevent ConnMan from changing your host name in the first place. This can be accomplished by adding the following to {{ic|/etc/connman/main.conf}}:<br />
<br />
[General]<br />
AllowHostnameUpdates=false<br />
<br />
Make sure to [[restart]] the {{ic|connman.service}} after changing this file.<br />
<br />
For testing purposes it is recommended to watch the [[systemd journal]] and plug the network cable a few times to see the action.<br />
<br />
=== Prefer ethernet to wireless ===<br />
<br />
By default ConnMan does not prefer ethernet over wireless, which can lead to it deciding to stick with a slow wireless network even when ethernet is available. You can tell connman to prefer ethernet adding the following to {{ic|/etc/connman/main.conf}}:<br />
<br />
[General]<br />
PreferredTechnologies=ethernet,wifi<br />
<br />
=== Exclusive connection ===<br />
<br />
ConnMan allows you to be connected to both ethernet and wireless at the same time. This can be useful as it allows programs that established a connection over wifi to stay connected even after you connect to ethernet. But some people prefer to have only a single unambiguous connection active at a time. That behavior can be activated by adding the following to {{ic|/etc/connman/main.conf}}:<br />
<br />
[General]<br />
SingleConnectedTechnology=true<br />
<br />
=== Connecting to eduroam (802.1X) ===<br />
<br />
[[WPA2 Enterprise]] networks such as eduroam require a separate configuration file before [[#Wi-Fi|connecting]] to the network. For example, create {{ic|/var/lib/connman/eduroam.config}}:<br />
<br />
{{hc|1=eduroam.config|2=<br />
[service_eduroam]<br />
Type=wifi<br />
Name=eduroam<br />
EAP=peap<br />
CACertFile=/etc/ssl/certs/''certificate.cer''<br />
Phase2=''MSCHAPV2''<br />
Identity=''user@foo.edu''<br />
AnonymousIdentity=''anonymous@foo.edu''<br />
Passphrase=''password''<br />
}}<br />
<br />
[[Restart]] {{ic|wpa_supplicant.service}} and {{ic|connman.service}} to connect to the new network.<br />
<br />
{{Note|<br />
* Options are case-sensitive, e.g. {{ic|1=EAP = ttls}} instead of {{ic|1=EAP = TTLS}}.[https://together.jolla.com/question/55969/connman-fails-due-to-case-sensitive-settings/]<br />
* Consult the institution hosting the eduroam network for various settings such as username, password, {{ic|EAP}}, {{ic|Phase2output}}, and needed certificates.<br />
}}<br />
<br />
For more information, see {{man|5|connman-service.config}} and [[Wireless network configuration#eduroam]].<br />
<br />
=== Avoiding conflicts with local DNS server ===<br />
<br />
If you are running a local DNS server, it will likely have problems binding to port 53 (TCP and/or UDP) after installing Connman. This is because Connman includes its own DNS proxy which also tries to bind to those ports. If you see log messages from [[BIND]] or [[dnsmasq]] like <br />
<br />
"named[529]: could not listen on UDP socket: address in use"<br />
<br />
this could be the problem. To verify which application is listening on the ports, you can execute {{ic|ss -tulpn}} as root.<br />
<br />
To fix this connmand can be started with the options {{ic|-r}} or {{ic|--nodnsproxy}} by [[Systemd#Editing provided units|overriding]] the systemd service file. Create the folder {{ic|/etc/systemd/system/connman.service.d/}} and add the file {{ic|disable_dns_proxy.conf}}:<br />
<br />
{{hc|/etc/systemd/system/connman.service.d/disable_dns_proxy.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/connmand -n --nodnsproxy<br />
}}<br />
<br />
If you want to know the DNS servers received from DHCP while keeping a custom {{ic|/etc/resolv.conf}}, then append {{ic|<nowiki>RuntimeDirectory=connman</nowiki>}} to the same file. Now connman will write them to {{ic|/var/run/connman/resolv.conf}} instead.<br />
<br />
Make sure to [[reload]] the systemd daemon and [[restart]] the {{ic|connman.service}}, and your DNS proxy, after adding this file.<br />
<br />
=== Blacklist interfaces ===<br />
<br />
If something like [[Docker]] is creating virtual interfaces Connman may attempt to connect to one of these instead of your physical adapter if the connection drops. A simple way of avoiding this is to blacklist the interfaces you do not want to use. Connman will by default blacklist interfaces starting with {{ic|vmnet}}, {{ic|vboxnet}}, {{ic|virbr}} and {{ic|ifb}}, so those need to be included in the new blacklist as well.<br />
<br />
Blacklisting interface names is also useful to avoid a race condition where connman may access {{ic|eth#}} or {{ic|wlan#}} before systemd/udev can change it to use a [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names] like {{ic|enp4s0}}. Blacklisting the conventional (and unpredictable) interface prefixes makes connman wait until they are renamed.<br />
<br />
If it does not already exist, create {{ic|/etc/connman/main.conf}}:<br />
<br />
[General]<br />
NetworkInterfaceBlacklist=vmnet,vboxnet,virbr,ifb,docker,veth,eth,wlan<br />
<br />
Once {{ic|connman.service}} has been [[systemd#Using units|restarted]] this will also hide all the {{ic|veth#######}} interfaces from GUI tools like Econnman.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Error /net/connman/technology/wifi: Not supported ===<br />
<br />
Currently, connman doesn't support scanning for WiFi networks with {{Pkg|iwd}}, at the moment this functionality is available with {{ic|wpa_supplicant}} only (see [https://lists.01.org/pipermail/connman/2018-August/022915.html]). In order to have Wifi Scanning support from within connman, install {{Pkg|wpa_supplicant}} and then [[restart]] {{ic|connman.service}} after you stop {{ic|iwd.service}}.<br />
<br />
=== Error /net/connman/technology/wifi: No carrier ===<br />
<br />
You have enabled your wifi with:<br />
<br />
$ connmanctl enable wifi<br />
<br />
If wireless scanning leads to above error, this may be due to an unresolved bug.[https://01.org/jira/browse/CM-670]<br />
If it does not resolve even though wireless [https://lists.01.org/pipermail/connman/2014-December/019203.html preconditions] are met, try again after disabling competing network managers and rebooting.<br />
<br />
This may also simply be caused by the wireless interface being blocked by [[rfkill]], which can occur after restarting wpa_supplicant. Use {{ic|rfkill list}} to check.<br />
<br />
=== "Not registered", or "Method "Connect" with signature ... doesn't exist" ===<br />
<br />
When issuing commands, you may see errors like the following:<br />
<br />
From a {{ic|connmanctl}} prompt:<br />
<br />
connmanctl> connect <service_id><br />
Error /net/connman/service/<SSID>: Method "Connect" with signature "" on interface "net.connman.Service" doesn't exist<br />
<br />
From the shell:<br />
<br />
# connmanctl connect <service_id><br />
Error /net/connman/service/<service_id>: Not registered<br />
<br />
These errors are produced because the agent is not running. Start the agent from a {{ic|connmanctl}} prompt with {{ic|agent on}}, and try again.<br />
<br />
=== Error Failed to set hostname/domainname ===<br />
<br />
connman can failed to set hostname or domainname due to lack of CAP_SYS_ADMIN.<br />
<br />
You will need to edit connman.service (and other like connman-vpn.service , etc ...) to modify the CapabilityBoundingSet line to add CAP_SYS_ADMIN.<br />
<br />
See EPERM error of sethostname(2)/setdomainname(2) manpages for more details.<br />
<br />
=== Unknown route on connection ===<br />
<br />
A log entry for an unknown route appears each time a connect is done. For example: <br />
<br />
...<br />
connmand[473]: wlp2s0 {add} route 82.165.8.211 gw 10.20.30.4 scope 0 <UNIVERSE><br />
connmand[473]: wlp2s0 {del} route 82.165.8.211 gw 10.20.30.4 scope 0 <UNIVERSE><br />
...<br />
<br />
It likely is Connman performing a connectivity check to the ipv4.connman.net host (which resolves to the IP address {{ic|82.165.8.211}} at current).[https://01.org/jira/browse/CM-657] See the [https://git.kernel.org/pub/scm/network/connman/connman.git/tree/README#n388 Connman README] for more information on why and what - apart from the connecting IP - it transmits.<br />
This behaviour can be prevented by adding the following to {{ic|/etc/connman/main.conf}}:<br />
<br />
[General]<br />
EnableOnlineCheck=false<br />
<br />
This setting will cause that the default device will not switch to ONLINE, but stay in READY state.[https://www.mankier.com/5/connman.conf] However, the connection will still be functional.<br />
<br />
The connection itself is also functional (unless behind a captive portal) if the check is blocked by a firewall rule: <br />
<br />
# ip6tables -A OUTPUT -d ipv6.connman.net -j REJECT<br />
# iptables -A OUTPUT -d ipv4.connman.net,ipv6.connman.net -j REJECT<br />
<br />
=== File /proc/net/pnp doesn't exist ===<br />
<br />
If you see this in your error log it is caused by bug in connman [https://bbs.archlinux.org/viewtopic.php?id=227689#p1766928] and can be ignored. [https://01.org/jira/browse/CM-690 Bug Report]<br />
<br />
== See also ==<br />
<br />
* [https://git.kernel.org/cgit/network/connman/connman.git/tree/doc git repo documentation] - for further detailed documentation</div>Progandyhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=640341GnuPG2020-11-02T12:19:32Z<p>Progandy: /* Key servers */ Change to hkps pool certificate to the one from the gnupg package.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set the {{ic|GNUPGHOME}} [[environment variable]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/doc/gnupg/}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[Wikipedia:Elliptic-curve cryptography]]. GnuPG supports elliptic curve keys as mentioned in [https://www.gnupg.org/faq/whats-new-in-2.1.html#ecc GnuPG - what's new in 2.1].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
==== Sending keys ====<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lkml.org/lkml/2016/8/15/445 fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://sks-keyservers.net SKS Keyserver Pool]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://pool.sks-keyservers.net<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver https://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If your network blocks connection to port 11371 used for hkp, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually (such as in this pam_env example), keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. There is a out of tree patch in [https://github.com/GPGTools/MacGPG2/blob/dev/patches/gnupg/scdaemon_shared-access.patch GPGTools/MacGPG2] git repo that enables {{ic|scdaemon}} to use shared access but GnuPG developers are against allowing this because when one {{ic|pcscd}} client authenticates the smartcard then some other malicious {{ic|pcscd}} clients could do authenticated operations with the card without you knowing. You can read full mailing list thread [https://lists.gnupg.org/pipermail/gnupg-devel/2015-September/030247.html here].<br />
<br />
If you accept the security risk then you can use the patch from [https://github.com/GPGTools/MacGPG2/blob/dev/patches/gnupg/scdaemon_shared-access.patch GPGTools/MacGPG2] git repo or use {{AUR|gnupg-scdaemon-shared-access}} package. After patching your {{ic|scdaemon}} you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|shared-access}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It's possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]{{Dead link|2020|02|24}}. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
{{Accuracy|The {{ic|gpg-agent*.socket}} systemd sockets provided by the {{Pkg|gnupg}} package create the sockets in {{ic|/run/user/$UID/gnupg/}} which is guaranteed to be an appropriate file system.}}<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
If your keyring is stored on a vFat filesystem (e.g. a USB drive), {{ic|gpg-agent}} will fail to create the required sockets (vFat does not support sockets), you can create redirects to a location that handles sockets, e.g. {{ic|/dev/shm}}:<br />
<br />
# export GNUPGHOME=/custom/gpg/home<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent\n' > $GNUPGHOME/S.gpg-agent<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.browser\n' > $GNUPGHOME/S.gpg-agent.browser<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.extra\n' > $GNUPGHOME/S.gpg-agent.extra<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.ssh\n' > $GNUPGHOME/S.gpg-agent.ssh<br />
<br />
Test that gpg-agent starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Progandyhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=640340GnuPG2020-11-02T12:08:27Z<p>Progandy: /* Key servers */ Add a tip on how to make the sks-keyserver hkps pool usable again.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set the {{ic|GNUPGHOME}} [[environment variable]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/doc/gnupg/}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[Wikipedia:Elliptic-curve cryptography]]. GnuPG supports elliptic curve keys as mentioned in [https://www.gnupg.org/faq/whats-new-in-2.1.html#ecc GnuPG - what's new in 2.1].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
==== Sending keys ====<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lkml.org/lkml/2016/8/15/445 fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://sks-keyservers.net SKS Keyserver Pool]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://pool.sks-keyservers.net<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver https://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you download and verify the [https://sks-keyservers.net/verify_tls.php HKPS pool verification certificate] and set it as {{ic|hkp-cacert}} in {{ic|dirmngr.conf}}.<br />
* If your network blocks connection to port 11371 used for hkp, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually (such as in this pam_env example), keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. There is a out of tree patch in [https://github.com/GPGTools/MacGPG2/blob/dev/patches/gnupg/scdaemon_shared-access.patch GPGTools/MacGPG2] git repo that enables {{ic|scdaemon}} to use shared access but GnuPG developers are against allowing this because when one {{ic|pcscd}} client authenticates the smartcard then some other malicious {{ic|pcscd}} clients could do authenticated operations with the card without you knowing. You can read full mailing list thread [https://lists.gnupg.org/pipermail/gnupg-devel/2015-September/030247.html here].<br />
<br />
If you accept the security risk then you can use the patch from [https://github.com/GPGTools/MacGPG2/blob/dev/patches/gnupg/scdaemon_shared-access.patch GPGTools/MacGPG2] git repo or use {{AUR|gnupg-scdaemon-shared-access}} package. After patching your {{ic|scdaemon}} you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|shared-access}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It's possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]{{Dead link|2020|02|24}}. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
{{Accuracy|The {{ic|gpg-agent*.socket}} systemd sockets provided by the {{Pkg|gnupg}} package create the sockets in {{ic|/run/user/$UID/gnupg/}} which is guaranteed to be an appropriate file system.}}<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
If your keyring is stored on a vFat filesystem (e.g. a USB drive), {{ic|gpg-agent}} will fail to create the required sockets (vFat does not support sockets), you can create redirects to a location that handles sockets, e.g. {{ic|/dev/shm}}:<br />
<br />
# export GNUPGHOME=/custom/gpg/home<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent\n' > $GNUPGHOME/S.gpg-agent<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.browser\n' > $GNUPGHOME/S.gpg-agent.browser<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.extra\n' > $GNUPGHOME/S.gpg-agent.extra<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.ssh\n' > $GNUPGHOME/S.gpg-agent.ssh<br />
<br />
Test that gpg-agent starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Progandyhttps://wiki.archlinux.org/index.php?title=OpenSSH&diff=631824OpenSSH2020-08-13T14:31:17Z<p>Progandy: /* Troubleshooting */ Add help to accept the changed key of an ssh server (as necessary for the AUR)</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[Category:Servers]]<br />
[[Category:OpenBSD]]<br />
[[de:SSH]]<br />
[[es:OpenSSH]]<br />
[[fa:SSH]]<br />
[[fr:ssh]]<br />
[[ja:Secure Shell]]<br />
[[pt:Secure Shell]]<br />
[[ru:OpenSSH]]<br />
[[zh-hans:OpenSSH]]<br />
{{Related articles start}}<br />
{{Related|SSH keys}}<br />
{{Related|Pam abl}}<br />
{{Related|fail2ban}}<br />
{{Related|sshguard}}<br />
{{Related|Sshfs}}<br />
{{Related|Syslog-ng}}<br />
{{Related|SFTP chroot}}<br />
{{Related|SCP and SFTP}}<br />
{{Related|VPN over SSH}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:OpenSSH|OpenSSH]] (OpenBSD Secure Shell) is a set of computer programs providing encrypted communication sessions over a computer network using the [[Secure Shell]] (SSH) protocol. It was created as an open source alternative to the proprietary Secure Shell software suite offered by SSH Communications Security. OpenSSH is developed as part of the OpenBSD project, which is led by Theo de Raadt.<br />
<br />
OpenSSH is occasionally confused with the similarly-named OpenSSL; however, the projects have different purposes and are developed by different teams, the similar name is drawn only from similar goals.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|openssh}} package.<br />
<br />
== Client usage ==<br />
<br />
To connect to a server, run:<br />
<br />
$ ssh -p ''port'' ''user''@''server-address''<br />
<br />
If the server only allows public-key authentication, follow [[SSH keys]].<br />
<br />
=== Configuration ===<br />
<br />
The client can be configured to store common options and hosts. All options can be declared globally or restricted to specific hosts. For example:<br />
<br />
{{hc|~/.ssh/config|# global options<br />
User ''user''<br />
<br />
# host-specific options<br />
Host ''myserver''<br />
Hostname ''server-address''<br />
Port ''port''<br />
}}<br />
<br />
With such a configuration, the following commands are equivalent<br />
<br />
$ ssh -p ''port'' ''user''@''server-address''<br />
$ ssh ''myserver''<br />
<br />
See {{man|5|ssh_config}} for more information.<br />
<br />
Some options do not have command line switch equivalents, but you can specify config options on the command line with {{ic|-o}}. For example {{ic|1=-oKexAlgorithms=+diffie-hellman-group1-sha1}}.<br />
<br />
== Server usage ==<br />
<br />
{{ic|sshd}} is the OpenSSH server daemon, configured with {{ic|/etc/ssh/sshd_config}} and managed by {{ic|sshd.service}}. Whenever changing the configuration, use {{ic|sshd}} in test mode before restarting the service to ensure it will be able to start cleanly. Valid configurations produce no output.<br />
<br />
# sshd -t<br />
<br />
=== Configuration ===<br />
<br />
To allow access only for some users add this line:<br />
<br />
AllowUsers ''user1 user2''<br />
<br />
To allow access only for some groups:<br />
<br />
AllowGroups ''group1 group2''<br />
<br />
To add a nice welcome message (e.g. from the {{ic|/etc/issue}} file), configure the {{ic|Banner}} option:<br />
<br />
Banner /etc/issue<br />
<br />
Public and private host keys are automatically generated in {{ic|/etc/ssh}} by the ''sshd'' [[#Daemon management|service files]] on the first run after installation. Four key pairs are provided based on the algorithms [[SSH keys#Choosing the authentication key type|dsa, rsa, ecdsa and ed25519]]. To have sshd use a particular key, specify the following option:<br />
<br />
HostKey /etc/ssh/ssh_host_rsa_key<br />
<br />
If the server is to be exposed to the WAN, it is recommended to change the default port from 22 to a random higher one like this:<br />
Port 39901<br />
<br />
{{Tip|<br />
* To help select an alternative port that is not already assigned to a common service, review the [[Wikipedia:List of TCP and UDP port numbers|list of TCP and UDP port numbers]]. You can also find port information locally in {{ic|/etc/services}}. A port change from default port 22 will reduce the number of log entries caused by automated authentication attempts but will not eliminate them. See [[Port knocking]] for related information.<br />
* It is recommended to disable password logins entirely. This will greatly increase security, see [[#Force public key authentication]] for more information. See [[#Protection]] for more recommend security methods.<br />
* OpenSSH can listen to multiple ports simply by having multiple {{ic|Port ''port_number''}} lines in the config file.<br />
* New (or missing) host key pairs can be generated by removing the pair(s) that you want to replace from {{ic|/etc/ssh}} and running {{ic|ssh-keygen -A}} as root.<br />
}}<br />
<br />
=== Daemon management ===<br />
<br />
[[Start/enable]] {{ic|sshd.service}}. It will keep the SSH daemon permanently active and fork for each incoming connection.[https://github.com/archlinux/svntogit-packages/blob/packages/openssh/trunk/sshd.service].<br />
<br />
{{Note|{{Pkg|openssh}} 8.0p1-3 removed {{ic|sshd.socket}} that used systemd's socket activation due to it being susceptible to denial of service. See {{Bug|62248}} for details. If {{ic|sshd.socket}} is enabled when updating to {{Pkg|openssh}} 8.0p1-3, the {{ic|sshd.socket}} and {{ic|sshd@.service}} units will be copied to {{ic|/etc/systemd/system/}} and [[systemd#Replacement unit files|reenabled]]. This is only done to not break existing setups, users are still advised to migrate to {{ic|sshd.service}}.}}<br />
<br />
{{Warning|If you continue using {{ic|sshd.socket}}, be aware of its issues:<br />
* {{ic|sshd.socket}} unit may fail (e.g. due to out-of-memory situation) and {{ic|1=Restart=always}} cannot be specified on socket units. See [https://github.com/systemd/systemd/issues/11553 systemd issue 11553].<br />
* Using socket activation can result in denial of service, as too many connections can cause refusal to further activate the service. See {{Bug|62248}}.<br />
}}<br />
<br />
{{Note|Using {{ic|sshd.socket}} negates the {{ic|ListenAddress}} setting, so it will allow connections over any address. To achieve the effect of setting {{ic|ListenAddress}}, you must specify the port ''and'' IP for {{ic|ListenStream}} (e.g. {{ic|1=ListenStream=192.168.1.100:22}}) by [[edit]]ing {{ic|sshd.socket}}. You must also add {{ic|1=FreeBind=true}} under {{ic|[Socket]}} or else setting the IP address will have the same drawback as setting {{ic|ListenAddress}}: the socket will fail to start if the network is not up in time.}}<br />
<br />
{{Tip|When using socket activation a transient instance of {{ic|sshd@.service}} will be started for each connection (with different instance names). Therefore, neither {{ic|sshd.socket}} nor the daemon's regular {{ic|sshd.service}} allow to monitor connection attempts in the log. The logs of socket-activated instances of SSH can be seen with {{ic|journalctl -u "sshd@*"}} or with {{ic|journalctl /usr/bin/sshd}}.}}<br />
<br />
=== Protection ===<br />
<br />
Allowing remote log-on through SSH is good for administrative purposes, but can pose a threat to your server's security. Often the target of brute force attacks, SSH access needs to be limited properly to prevent third parties gaining access to your server.<br />
<br />
Several other good guides and tools are available on the topic, for example:<br />
<br />
* [[MozillaWiki:Security/Guidelines/OpenSSH|Article by Mozilla Infosec Team]]<br />
* [https://github.com/mozilla/ssh_scan Mozilla ssh_scan]<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure sshd]<br />
<br />
==== Force public key authentication ====<br />
<br />
If a client cannot authenticate through a public key, by default the SSH server falls back to password authentication, thus allowing a malicious user to attempt to gain access by [[#Protecting against brute force attacks|brute-forcing]] the password. One of the most effective ways to protect against this attack is to disable password logins entirely, and force the use of [[SSH keys]]. This can be accomplished by disabling the following options in the daemon configuration file:<br />
<br />
{{hc|/etc/ssh/sshd_config|PasswordAuthentication no}}<br />
<br />
{{Warning|Before adding this to your configuration, make sure that all accounts which require SSH access have public-key authentication set up in the corresponding {{ic|authorized_keys}} files. See [[SSH keys#Copying the public key to the remote server]] for more information.}}<br />
<br />
==== Two-factor authentication and public keys ====<br />
<br />
SSH can be set up to require multiple ways of authentication, you can tell which authentication methods are required using the {{ic|AuthenticationMethods}} option. This enables you to use public keys as well as a two-factor authorization.<br />
<br />
See [[Google Authenticator]] to set up Google Authenticator.<br />
<br />
To use [[PAM]] with OpenSSH, edit the following files:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
ChallengeResponseAuthentication yes<br />
AuthenticationMethods publickey keyboard-interactive:pam<br />
}}<br />
<br />
Then you can log in with either a publickey '''or''' the user authentication as required by your PAM setup.<br />
<br />
If, on the other hand, you want to authenticate the user on both a publickey '''and''' the user authentication as required by your PAM setup, use a comma instead of a space to separate the AuthenticationMethods:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
ChallengeResponseAuthentication yes<br />
AuthenticationMethods publickey''','''keyboard-interactive:pam<br />
}}<br />
<br />
With required pubkey '''and''' pam authentication you may wish to disable the password requirement:<br />
<br />
{{hc|/etc/pam.d/sshd|<br />
auth required pam_securetty.so #disable remote root<br />
#Require google authenticator<br />
auth required pam_google_authenticator.so<br />
#But not password<br />
#auth include system-remote-login<br />
account include system-remote-login<br />
password include system-remote-login<br />
session include system-remote-login<br />
}}<br />
<br />
==== Protecting against brute force attacks ====<br />
<br />
Brute forcing is a simple concept: one continuously tries to log in to a webpage or server log-in prompt like SSH with a high number of random username and password combinations.<br />
<br />
See [[ufw#Rate limiting with ufw]] or [[Simple stateful firewall#Bruteforce attacks]] for [[iptables]].<br />
<br />
Alternatively, you can protect yourself from brute force attacks by using an automated script that blocks anybody trying to brute force their way in, for example [[fail2ban]] or [[sshguard]].<br />
<br />
* Only allow incoming SSH connections from trusted locations<br />
* Use [[fail2ban]] or [[sshguard]] to automatically block IP addresses that fail password authentication too many times.<br />
* Use [https://github.com/jtniehof/pam_shield pam_shield] to block IP addresses that perform too many login attempts within a certain period of time. In contrast to [[fail2ban]] or [[sshguard]], this program does not take login success or failure into account.<br />
<br />
==== Limit root login ====<br />
<br />
{{Out of date|Root login has been disabled by default upstream in the current version. Unclear to me what parts of this section and subsections are redundant.}}<br />
<br />
It is generally considered bad practice to allow the root user to log in without restraint over SSH. There are two methods by which SSH root access can be restricted for increased security.<br />
<br />
===== Deny =====<br />
<br />
Sudo selectively provides root rights for actions requiring these without requiring authenticating against the root account. This allows locking the root account against access via SSH and potentially functions as a security measure against brute force attacks, since now an attacker must guess the account name in addition to the password.<br />
<br />
SSH can be configured to deny remote logins with the root user by editing the "Authentication" section in the daemon configuration file. Simply set {{ic|PermitRootLogin}} to {{ic|no}}:<br />
<br />
{{hc|/etc/ssh/sshd_config|PermitRootLogin no}}<br />
<br />
Next, [[restart]] the SSH daemon.<br />
<br />
You will now be unable to log in through SSH under root, but will still be able to log in with your normal user and use [[su]] or [[sudo]] to do system administration.<br />
<br />
===== Restrict =====<br />
<br />
Some automated tasks such as remote, full-system backup require full root access. To allow these in a secure way, instead of disabling root login via SSH, it is possible to only allow root logins for selected commands. This can be achieved by editing {{ic|~root/.ssh/authorized_keys}}, by prefixing the desired key, e.g. as follows:<br />
<br />
command="/usr/lib/rsync/rrsync -ro /" ssh-rsa …<br />
<br />
This will allow any login with this specific key only to execute the command specified between the quotes.<br />
<br />
The increased attack surface created by exposing the root user name at login can be compensated by adding the following to {{ic|sshd_config}}:<br />
<br />
PermitRootLogin forced-commands-only<br />
<br />
This setting will not only restrict the commands which root may execute via SSH, but it will also disable the use of passwords, forcing use of public key authentication for the root account.<br />
<br />
A slightly less restrictive alternative will allow any command for root, but makes brute force attacks infeasible by enforcing public key authentication. For this option, set:<br />
<br />
PermitRootLogin prohibit-password<br />
<br />
==== Securing the authorized_keys file ====<br />
<br />
{{Accuracy|The immutable bit can be simply removed, so it does not "secure" anything".}}<br />
<br />
For additional protection, you can prevent users from adding new public keys and connecting from them.<br />
<br />
In the server, make the {{ic|authorized_keys}} file read-only for the user and deny all other permissions:<br />
<br />
$ chmod 400 ~/.ssh/authorized_keys<br />
<br />
To keep the user from simply changing the permissions back, [[File permissions and attributes#chattr and lsattr|set the immutable bit]] on the {{ic|authorized_keys}} file. After that the user could rename the {{ic|~/.ssh}} directory to something else and create a new {{ic|~/.ssh}} directory and {{ic|authorized_keys}} file. To prevent this, set the immutable bit on the {{ic|~/.ssh}} directory too.<br />
<br />
{{Note|If you find yourself needing to add a new key, you will first have to remove the immutable bit from {{ic|authorized_keys}} and make it writable. Follow the steps above to secure it again.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Encrypted SOCKS tunnel ===<br />
<br />
This is highly useful for laptop users connected to various unsafe wireless connections. The only thing you need is an SSH server running at a somewhat secure location, like your home or at work. It might be useful to use a dynamic DNS service like [https://dyn.com/dns/ DynDNS] so you do not have to remember your IP-address.<br />
<br />
==== Step 1: start the connection ====<br />
<br />
You only have to execute this single command to start the connection:<br />
<br />
$ ssh -TND 4711 ''user''@''host''<br />
<br />
where {{Ic|''user''}} is your username at the SSH server running at the {{Ic|''host''}}. It will ask for your password, and then you are connected. The {{Ic|N}} flag disables the interactive prompt, and the {{Ic|D}} flag specifies the local port on which to listen on (you can choose any port number if you want). The {{Ic|T}} flag disables pseudo-tty allocation.<br />
<br />
It is nice to add the verbose ({{Ic|-v}}) flag, because then you can verify that it is actually connected from that output.<br />
<br />
==== Step 2 (Variant A): configure your browser (or other programs) ====<br />
<br />
The above step is useful only in combination with a web browser or another program that uses this newly created SOCKS tunnel. Since SSH currently supports both SOCKS v4 and SOCKS v5, you can use either of them.<br />
<br />
* For Firefox: At ''Preferences > General'' navigates to the bottom of the page and click ''Settings...'', which is to the right of the Network Settings title. Next, within the new semi window, check the ''Manual proxy configuration'' option and enter {{ic|localhost}} in the ''SOCKS host'' text field, and the port number in the ''Port'' text field ({{ic|4711}} in the example above) next to it.<br />
:Firefox does not automatically make DNS requests through the socks tunnel. This potential privacy concern can be mitigated by scrolling further down, checking in the ''Proxy DNS when using SOCKS v5''. Obviously, this will only work if you chooses SOCKS v5 rather then v4.<br />
: Restart Firefox to activate these settings.<br />
<br />
* For Chromium: You can set the SOCKS settings as environment variables or as command line options. I recommend to add one of the following functions to your {{ic|.bashrc}}:<br />
<br />
function secure_chromium {<br />
port=4711<br />
export SOCKS_SERVER=localhost:$port<br />
export SOCKS_VERSION=5<br />
chromium &<br />
exit<br />
}<br />
<br />
OR<br />
<br />
function secure_chromium {<br />
port=4711<br />
chromium --proxy-server="socks://localhost:$port" &<br />
exit<br />
}<br />
<br />
Now open a terminal and just do:<br />
<br />
$ secure_chromium<br />
<br />
Enjoy your secure tunnel!<br />
<br />
==== Step 2 (Variant B): set up a local TUN interface ====<br />
<br />
This variant is slightly more involved upfront but results in you not having to manually configure every single application one by one to use the SOCKS proxy. It involves setting up a local TUN interface and routing traffic through it.<br />
<br />
See [[VPN over SSH#Set up badvpn and tunnel interface]].<br />
<br />
=== X11 forwarding ===<br />
<br />
X11 forwarding is a mechanism that allows graphical interfaces of X11 programs running on a remote system to be displayed on a local client machine. For X11 forwarding the remote host does not need to have a full X11 system installed, however it needs at least to have ''xauth'' installed. ''xauth'' is a utility that maintains {{ic|Xauthority}} configurations used by server and client for authentication of X11 session ([http://xmodulo.com/2012/11/how-to-enable-x11-forwarding-using-ssh.html source]).<br />
<br />
{{Warning|X11 forwarding has important security implications which should be at least acknowledged by reading relevant sections of {{man|1|ssh}}, {{man|5|sshd_config}}, and {{man|5|ssh_config}} manual pages. See also [https://security.stackexchange.com/questions/14815/security-concerns-with-x11-forwarding this StackExchange question.]}}<br />
<br />
==== Setup ====<br />
<br />
===== Remote =====<br />
<br />
* [[install]] the {{Pkg|xorg-xauth}} and {{Pkg|xorg-xhost}} packages<br />
* in {{ic|/etc/ssh/ssh'''d'''_config}}:<br />
** set {{ic|X11Forwarding}} to ''yes''<br />
** verify that {{ic|AllowTcpForwarding}} and {{ic|X11UseLocalhost}} options are set to ''yes'', and that {{ic|X11DisplayOffset}} is set to ''10'' (those are the default values if nothing has been changed, see {{man|5|sshd_config}})<br />
* then [[restart]] the [[#Daemon management|''sshd'' daemon]].<br />
<br />
===== Client =====<br />
<br />
* [[install]] the {{Pkg|xorg-xauth}} package<br />
* enable the {{ic|ForwardX11}} option by either specifying the {{ic|-X}} switch on the command line for opportunistic connections, or by setting {{ic|ForwardX11}} to ''yes'' in the [[#Configuration|client's configuration]].<br />
<br />
{{Tip|You can enable the {{ic|ForwardX11Trusted}} option ({{ic|-Y}} switch on the command line) if GUI is drawing badly or you receive errors; this will prevent X11 forwardings from being subjected to the [http://www.x.org/wiki/Development/Documentation/Security/ X11 SECURITY extension] controls. Be sure you have read [[#X11 forwarding|the warning]] at the beginning of this section if you do so.}}<br />
<br />
==== Usage ====<br />
<br />
{{Accuracy|{{ic|xhost}} is [https://unix.stackexchange.com/questions/12755/how-to-forward-x-over-ssh-from-ubuntu-machine#comment17148_12772 generally not needed]|section=X11 forwarding}}<br />
<br />
Log on to the remote machine normally, specifying the {{ic|-X}} switch if ''ForwardX11'' was not enabled in the client's configuration file:<br />
<br />
$ ssh -X ''user@host''<br />
<br />
If you receive errors trying to run graphical applications, try ''ForwardX11Trusted'' instead:<br />
<br />
$ ssh -Y ''user@host''<br />
<br />
You can now start any X program on the remote server, the output will be forwarded to your local session:<br />
<br />
$ xclock<br />
<br />
If you get "Cannot open display" errors try the following command as the non root user:<br />
<br />
$ xhost +<br />
<br />
The above command will allow anybody to forward X11 applications. To restrict forwarding to a particular host type:<br />
<br />
$ xhost +hostname<br />
<br />
where hostname is the name of the particular host you want to forward to. See {{man|1|xhost}} for more details.<br />
<br />
Be careful with some applications as they check for a running instance on the local machine. [[Firefox]] is an example: either close the running Firefox instance or use the following start parameter to start a remote instance on the local machine:<br />
<br />
$ firefox --no-remote<br />
<br />
If you get "X11 forwarding request failed on channel 0" when you connect (and the server {{ic|/var/log/errors.log}} shows "Failed to allocate internet-domain X11 display socket"), make sure package {{Pkg|xorg-xauth}} is installed. If its installation is not working, try to either:<br />
<br />
* enable the {{ic|AddressFamily any}} option in {{ic|ssh'''d'''_config}} on the ''server'', or<br />
* set the {{ic|AddressFamily}} option in {{ic|ssh'''d'''_config}} on the ''server'' to inet.<br />
Setting it to inet may fix problems with Ubuntu clients on IPv4.<br />
<br />
For running X applications as other user on the SSH server you need to {{Ic|xauth add}} the authentication line taken from {{Ic|xauth list}} of the SSH logged in user.<br />
<br />
{{Tip|[https://unix.stackexchange.com/a/12772/29867 Here] are [https://unix.stackexchange.com/a/46748/29867 some] useful [https://superuser.com/a/805060/185665 links] for troubleshooting {{ic|X11 Forwarding}} issues.}}<br />
<br />
=== Forwarding other ports ===<br />
<br />
In addition to SSH's built-in support for X11, it can also be used to securely tunnel any TCP connection, by use of local forwarding or remote forwarding.<br />
<br />
Local forwarding opens a port on the local machine, connections to which will be forwarded to the remote host and from there on to a given destination. Very often, the forwarding destination will be the same as the remote host, thus providing a secure shell and, e.g. a secure [[VNC]] connection, to the same machine. Local forwarding is accomplished by means of the {{Ic|-L}} switch and it is accompanying forwarding specification in the form of {{Ic|<tunnel port>:<destination address>:<destination port>}}.<br />
<br />
Thus:<br />
<br />
$ ssh -L 1000:mail.google.com:25 192.168.0.100<br />
<br />
will use SSH to login to and open a shell on {{ic|192.168.0.100}}, and will also create a tunnel from the local machine's TCP port 1000 to mail.google.com on port 25. Once established, connections to {{ic|localhost:1000}} will connect to the Gmail SMTP port. To Google, it will appear that any such connection (though not necessarily the data conveyed over the connection) originated from {{ic|192.168.0.100}}, and such data will be secure between the local machine and 192.168.0.100, but not between {{ic|192.168.0.100}} and Google, unless other measures are taken.<br />
<br />
Similarly:<br />
<br />
$ ssh -L 2000:192.168.0.100:6001 192.168.0.100<br />
<br />
will allow connections to {{ic|localhost:2000}} which will be transparently sent to the remote host on port 6001. The preceding example is useful for VNC connections using the vncserver utility--part of the [[tightvnc]] package--which, though very useful, is explicit about its lack of security.<br />
<br />
Remote forwarding allows the remote host to connect to an arbitrary host via the SSH tunnel and the local machine, providing a functional reversal of local forwarding, and is useful for situations where, e.g., the remote host has limited connectivity due to firewalling. It is enabled with the {{Ic|-R}} switch and a forwarding specification in the form of {{Ic|<tunnel port>:<destination address>:<destination port>}}.<br />
<br />
Thus:<br />
<br />
$ ssh -R 3000:irc.freenode.net:6667 192.168.0.200<br />
<br />
will bring up a shell on {{ic|192.168.0.200}}, and connections from {{ic|192.168.0.200}} to itself on port 3000 (the remote host's {{ic|localhost:3000}}) will be sent over the tunnel to the local machine and then on to irc.freenode.net on port 6667, thus, in this example, allowing the use of IRC programs on the remote host to be used, even if port 6667 would normally be blocked to it.<br />
<br />
Both local and remote forwarding can be used to provide a secure "gateway", allowing other computers to take advantage of an SSH tunnel, without actually running SSH or the SSH daemon by providing a bind-address for the start of the tunnel as part of the forwarding specification, e.g. {{Ic|<tunnel address>:<tunnel port>:<destination address>:<destination port>}}. The {{Ic|<tunnel address>}} can be any address on the machine at the start of the tunnel. The address {{Ic|localhost}} allows connections via the {{ic|localhost}} or loopback interface, and an empty address or {{Ic|*}} allow connections via any interface. By default, forwarding is limited to connections from the machine at the "beginning" of the tunnel, i.e. the {{Ic|<tunnel address>}} is set to {{Ic|localhost}}. Local forwarding requires no additional configuration, however remote forwarding is limited by the remote server's SSH daemon configuration. See the {{Ic|GatewayPorts}} option in {{man|5|sshd_config}} and {{ic|-L address}} option in {{man|1|ssh}} for more information about remote forwarding and local forwarding, respectively.<br />
<br />
=== Jump hosts ===<br />
<br />
In certain scenarios, there might not be a direct connection to your target SSH daemon, and the use of a jump server (or bastion server) is required. Thus, we attempt to connect together two or more SSH tunnels, and assuming your local keys are authorized against each server in the chain. This is possible using SSH agent forwarding ({{ic|-A}}) and pseudo-terminal allocation ({{ic|-t}}) which forwards your local key with the following syntax:<br />
<br />
$ ssh -A -t -l user1 bastion1 \<br />
ssh -A -t -l user2 intermediate2 \<br />
ssh -A -t -l user3 target<br />
<br />
An easier way to do this is using the {{ic|-J}} flag:<br />
<br />
$ ssh -J user1@bastion1,user2@intermediate2 user3@target<br />
<br />
Multiple hosts in the {{ic|-J}} directive can be separted with a comma, they will be connected to in the order listed. The {{ic|user...@}} part is not required, but can be used. The host specifications for {{ic|-J}} use the ssh configuration file, so specific per-host options can be set there, if needed.<br />
<br />
An equivalent of the {{ic|-J}} flag in the configuration file is the {{ic|ProxyJump}} option, see {{man|5|ssh_config}} for details.<br />
<br />
=== Reverse SSH through a relay ===<br />
<br />
{{Style|The idea of SSH tunneling is classic, so some references for detailed explanation would be nice. E.g. [https://unix.stackexchange.com/questions/46235/how-does-reverse-ssh-tunneling-work/118650#118650] which includes other scenarios.}}<br />
<br />
The idea is that client connects to the server via another relay, while the server is connected to the same relay using a reverse SSH tunnel. This is for example useful when the server is behind a NAT and relay is a publicly accessible SSH server used as a proxy to which the user has access. So the prerequisite is that client's keys are authorized against both the relay and the server and server's need to be authorized against the relay as well for the reverse SSH connection.<br />
<br />
The following configuration example assumes that user1 is the user account used on client, user2 on relay and user3 on server. First the server needs to establish the reverse tunnel with:<br />
<br />
ssh -R 2222:localhost:22 -N user2@relay<br />
<br />
Which can also be automated with a startup script, systemd service or [[#Autossh - automatically restarts SSH sessions and tunnels|autossh]].<br />
<br />
{{Expansion|Explain why {{ic|ssh user3@relay -p 2222}} is not sufficient.}}<br />
<br />
At the client side the connection is established with:<br />
<br />
ssh -t user2@relay ssh user3@localhost -p 2222<br />
<br />
The remote command to establish the connection to reverse tunnel can also be defined in relay's {{ic|~/.ssh/authorized_keys}} by including the {{ic|command}} field as follows:<br />
<br />
command="ssh user3@localhost -p 2222" ssh-rsa KEY2 user1@client<br />
<br />
In this case the connection is established with:<br />
<br />
ssh user2@relay<br />
<br />
Note that SCP's autocomplete function in client's terminal is not working and even the SCP transfers themselves are not working under some configurations.<br />
<br />
=== Multiplexing ===<br />
<br />
The SSH daemon usually listens on port 22. However, it is common practice for many public internet hotspots to block all traffic that is not on the regular HTTP/S ports (80 and 443, respectively), thus effectively blocking SSH connections. The immediate solution for this is to have {{ic|sshd}} listen additionally on one of the whitelisted ports:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
Port 22<br />
Port 443<br />
}}<br />
<br />
However, it is likely that port 443 is already in use by a web server serving HTTPS content, in which case it is possible to use a multiplexer, such as {{Pkg|sslh}}, which listens on the multiplexed port and can intelligently forward packets to many services.<br />
<br />
=== Speeding up SSH ===<br />
<br />
There are several [[#Configuration|client configuration]] options which can speed up connections either globally or for specific hosts. See {{man|5|ssh_config}} for full descriptions of these options.<br />
<br />
* ''Use a faster cipher'': on modern CPUs with AESNI instructions, {{ic|aes128-gcm@openssh.com}} and {{ic|aes256-gcm@openssh.com}} should offer significantly better performance over openssh's default preferred cipher, usually {{ic|chacha20-poly1305@openssh.com}}. Cipher can be selected {{ic|-c}} flag. For a permanent effect, put {{ic|Ciphers}} option in your ~/.ssh/config with ciphers in new preferred order, e.g.:<br />
*: {{bc|Ciphers aes128-gcm@openssh.com,aes256-gcm@openssh.com,chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr}}<br />
<br />
* ''Enable or disable compression'': compression can increase speed on slow connections, it is enabled with the {{ic|Compression yes}} option or the {{ic|-C}} flag. However the compression algorithm used is the relatively slow {{man|1|gzip}} which becomes the bottleneck on fast networks. In order to speed up the connection one should use the {{ic|Compression no}} option on local or fast networks.<br />
<br />
* ''Connection sharing'': you can make all sessions to the same host share a single connection using these options:<br />
*: {{bc|<nowiki><br />
ControlMaster auto<br />
ControlPersist yes<br />
ControlPath ~/.ssh/sockets/socket-%r@%h:%p<br />
</nowiki>}}<br />
: where {{ic|~/.ssh/sockets}} can be any directory not writable by other users.<br />
<br />
* {{ic|ControlPersist}} specifies how long the master should wait in the background for new clients after the initial client connection has been closed. Possible values are either: <br />
** {{ic|no}} to close the connection immediately after the last client disconnects, <br />
** a time in seconds,<br />
** {{ic|yes}} to wait forever, the connection will never be closed automatically.<br />
<br />
* Login time can be shortened by bypassing IPv6 lookup using the {{ic|AddressFamily inet}} option or {{ic|-4}} flag.<br />
<br />
* Last, if you intend to use SSH for SFTP or SCP, [https://www.psc.edu/index.php/hpn-ssh High Performance SSH/SCP] can significantly increase throughput by dynamically raising the SSH buffer sizes. Install the package {{AUR|openssh-hpn-git}} to use a patched version of OpenSSH with this enhancement.<br />
<br />
=== Mounting a remote filesystem with SSHFS ===<br />
<br />
Please refer to the [[SSHFS]] article to mount a SSH-accessible remote system to a local folder, so you will be able to do any operation on the mounted files with any tool (copy, rename, edit with vim, etc.). ''sshfs'' is generally preferred over ''shfs'', the latter has not been updated since 2004.<br />
<br />
=== Keep alive ===<br />
<br />
By default, the SSH session automatically logs out if it has been idle for a certain time. To keep the session up, the client can send a keep-alive signal to the server if no data has been received for some time, or symmetrically the server can send messages at regular intervals if it has not heard from the client.<br />
<br />
* On the '''server''' side, {{ic|ClientAliveInterval}} sets the timeout in seconds after which if no data has been received from the client, ''sshd'' will send a request for response. The default is 0, no message is sent. For example to request a response every 60 seconds from the client, set the {{ic|ClientAliveInterval 60}} option in your [[#Configuration_2|server configuration]]. See also the {{ic|ClientAliveCountMax}} and {{ic|TCPKeepAlive}} options.<br />
* On the '''client''' side, {{ic|ServerAliveInterval}} controls the interval between the requests for response sent from the client to the server. For example to request a response every 120 seconds from the server, add the {{ic|ServerAliveInterval 120}} option to your [[#Configuration|client configuration]]. See also the {{ic|ServerAliveCountMax}} and {{ic|TCPKeepAlive}} options.<br />
<br />
{{Note| To ensure a session is kept alive, only one of either the client or the server needs to send keep alive requests. If ones control both the servers and the clients, a reasonable choice is to only configure the clients that require a persistent session with a positive {{ic|ServerAliveInterval}} and leave other clients and servers in their default configuration.}}<br />
<br />
=== Automatically restart SSH tunnels with systemd ===<br />
<br />
[[systemd]] can automatically start SSH connections on boot/login ''and'' restart them when they fail. This makes it a useful tool for maintaining SSH tunnels.<br />
<br />
The following service can start an SSH tunnel on login using the connection settings in your [[#Configuration|ssh configuration]]. If the connection closes for any reason, it waits 10 seconds before restarting it:<br />
<br />
{{hc|~/.config/systemd/user/tunnel.service|<nowiki><br />
[Unit]<br />
Description=SSH tunnel to myserver<br />
<br />
[Service]<br />
Type=simple<br />
Restart=always<br />
RestartSec=10<br />
ExecStart=/usr/bin/ssh -F %h/.ssh/config -N myserver<br />
</nowiki>}}<br />
<br />
Then [[enable]] and [[start]] the [[Systemd/User]] service. See [[#Keep alive]] for how to prevent the tunnel from timing out. If you wish to start the tunnel on boot, you might want to [[Systemd#Writing_unit_files|rewrite the unit]] as a system service.<br />
<br />
=== Autossh - automatically restarts SSH sessions and tunnels ===<br />
<br />
When a session or tunnel cannot be kept alive, for example due to bad network conditions causing client disconnections, you can use {{Pkg|autossh}} to automatically restart them.<br />
<br />
Usage examples:<br />
<br />
$ autossh -M 0 -o "ServerAliveInterval 45" -o "ServerAliveCountMax 2" username@example.com<br />
<br />
Combined with [[SSHFS]]:<br />
<br />
$ sshfs -o reconnect,compression=yes,transform_symlinks,ServerAliveInterval=45,ServerAliveCountMax=2,ssh_command='autossh -M 0' username@example.com: /mnt/example <br />
<br />
Connecting through a SOCKS-proxy set by [[Proxy settings]]:<br />
<br />
$ autossh -M 0 -o "ServerAliveInterval 45" -o "ServerAliveCountMax 2" -NCD 8080 username@example.com <br />
<br />
With the {{ic|-f}} option autossh can be made to run as a background process. Running it this way however means the passphrase cannot be entered interactively.<br />
<br />
The session will end once you type {{ic|exit}} in the session, or the autossh process receives a SIGTERM, SIGINT of SIGKILL signal.<br />
<br />
==== Run autossh automatically at boot via systemd ====<br />
<br />
If you want to automatically start autossh, you can create a systemd unit file:<br />
<br />
{{hc|/etc/systemd/system/autossh.service|2=<br />
[Unit]<br />
Description=AutoSSH service for port 2222<br />
After=network.target<br />
<br />
[Service]<br />
Environment="AUTOSSH_GATETIME=0"<br />
ExecStart=/usr/bin/autossh -M 0 -NL 2222:localhost:2222 -o TCPKeepAlive=yes foo@bar.com<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
Here {{ic|1=AUTOSSH_GATETIME=0}} is an environment variable specifying how long ssh must be up before autossh considers it a successful connection, setting it to 0 autossh also ignores the first run failure of ssh. This may be useful when running autossh at boot. Other environment variables are available at {{man|1|autossh}}. Of course, you can make this unit more complex if necessary (see the systemd documentation for details), and obviously you can use your own options for autossh, but note that the {{ic|-f}} implying {{ic|1=AUTOSSH_GATETIME=0}} does not work with systemd. <br />
<br />
Remember to [[start]] and/or [[enable]] the service afterwards.<br />
<br />
You may also need to disable ControlMaster e.g.<br />
<br />
ExecStart=/usr/bin/autossh -M 0 -o ControlMaster=no -NL 2222:localhost:2222 -o TCPKeepAlive=yes foo@bar.com<br />
<br />
{{Tip|It is also easy to maintain several autossh processes, to keep several tunnels alive. Just create multiple service files with different names.}}<br />
<br />
=== Alternative service should SSH daemon fail ===<br />
<br />
For remote or headless servers which rely exclusively on SSH, a failure to start the SSH daemon (e.g., after a system upgrade) may prevent administration access. [[systemd]] offers a simple solution via {{ic|OnFailure}} option.<br />
<br />
Let us suppose the server runs {{ic|sshd}} and [[telnet]] is the fail-safe alternative of choice. Create a file as follows. Do '''not''' [[enable]] telnet.socket!<br />
<br />
{{hc|/etc/systemd/system/sshd.service.d/override.conf|2=<br />
[Unit]<br />
OnFailure=telnet.socket<br />
}}<br />
<br />
That's it. Telnet is not available when {{ic|sshd}} is running. Should {{ic|sshd}} fail to start, a telnet session can be opened for recovery.<br />
<br />
=== Terminal background color based on host ===<br />
<br />
To better distinguish when you are on different hosts, you can set a [https://bryangilbert.com/post/etc/term/dynamic-ssh-terminal-background-colors/ different background color based on the kind of host].<br />
<br />
This solution works, but is not universal (ZSH only).<br />
<br />
=== Network specific configuration ===<br />
<br />
You can use host configuration specific to the network you are connected to using a {{ic|Match exec}}.<br />
<br />
For example, when using nmcli, and the connection is configured (manually or through DHCP) to use a search-domain:<br />
<br />
{{bc|1=<br />
Match exec "nmcli {{!}} grep domains: {{!}} grep example.com"<br />
CanonicalDomains example.com<br />
# Should you use a different username on this network<br />
#User username<br />
# Use a different known_hosts file (for private network or synchronisation)<br />
#UserKnownHostsFile <network>_known_hosts<br />
}}<br />
<br />
=== Private networks hostkeys verification ===<br />
<br />
Because different servers on different networks are likely to share a common private IP address, you might want to handle them differently.<br />
<br />
{{Accuracy|The best solution would not need a warning to use something else in practice.}}<br />
<br />
The best solution is to use the [[#Network specific configuration]] to use a different {{ic|UserKnownHostsFile}} depending on the network you are on. The second solution, best used as default when you are working on new/prototype networks, would be to simply ignore hostkeys for private networks:<br />
<br />
{{bc|1=<br />
Host 10.* 192.168.*.* 172.31.* 172.30.* 172.2?.* 172.1?.*<br />
# Disable HostKey verification<br />
# Trust HostKey automatically<br />
StrictHostKeyChecking no<br />
# Do not save the HostKey<br />
UserKnownHostsFile=/dev/null<br />
# Do not display: "Warning: Permanently Added ..."<br />
LogLevel Error<br />
}}<br />
<br />
{{Accuracy|The {{ic|known_hosts}} file records an IP address even when you use hostname to access the server.}}<br />
<br />
{{Warning|In a production environment, make sure to either use the hostname to access the host and/or to use network specific known_hosts files.}}<br />
<br />
=== Run command at login ===<br />
<br />
If you are using an interactive session, there are multiple ways to execute a command on login:<br />
<br />
* use the {{ic|authorized_keys}} file on the remote host (see {{ic|AUTHORIZED_KEYS FILE FORMAT}} in {{man|8|sshd}})<br />
* use {{ic|~/.ssh/rc}} on the remote host if the server has enabled the {{ic|PermitUserRC}} option<br />
* use your shell config file on the remote host, e.g. {{ic|.bashrc}}<br />
<br />
=== Agent forwarding ===<br />
<br />
SSH agent forwarding allows you to use your local keys when connected to a server. It is recommended to only enable agent forwarding for selected hosts.<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''myserver.com''<br />
ForwardAgent yes<br />
}}<br />
<br />
Next, configure an [[SSH agent]] and add your local key with ''ssh-add''.<br />
<br />
If you now connect to a remote server you will be able to connect to other services using your local keys.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Checklist ===<br />
<br />
Check these simple issues before you look any further.<br />
<br />
# The config directory {{ic|~/.ssh}}, its contents should be accessible only by the user (check this on both the client and the server), and the user's home folder should only be writable by the user: {{bc|<nowiki><br />
$ chmod go-w ~<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/*<br />
$ chown -R $USER ~/.ssh<br />
</nowiki>}}<br />
# Check that the client's public key (e.g. {{ic|id_rsa.pub}}) is in {{ic|~/.ssh/authorized_keys}} on the server.<br />
# Check that you did not limit SSH access with {{ic|AllowUsers}} or {{ic|AllowGroups}} in the [[#Configuration_2|server config]].<br />
# Check if the user has set a password. Sometimes new users who have not yet logged in to the server do not have a password.<br />
# [[Append]] {{ic|LogLevel DEBUG}} to {{ic|/etc/ssh/sshd_config}}.<br />
# Use {{ic|journalctl -xe}} for possible (error) messages.<br />
# [[Restart]] {{ic|sshd}} and logout/login on both client and server.<br />
<br />
=== Connection refused or timeout problem ===<br />
<br />
==== Port forwarding ====<br />
<br />
If you are behind a NAT mode/router (which is likely unless you are on a VPS or publicly addressed host), make sure that your router is forwarding incoming ssh connections to your machine. Find the server's internal IP address with {{ic|$ ip addr}} and set up your router to forward TCP on your SSH port to that IP. [http://portforward.com portforward.com] can help with that.<br />
<br />
==== Is SSH running and listening? ====<br />
<br />
The [[ss]] utility shows all the processes listening to a TCP port with the following command line:<br />
<br />
$ ss --tcp --listening<br />
<br />
If the above command do not show the system is listening to the port {{ic|ssh}}, then SSH is not running: check the [[journal]] for errors etc.<br />
<br />
==== Are there firewall rules blocking the connection? ====<br />
<br />
[[Iptables]] may be blocking connections on port {{ic|22}}. Check this with:<br />
{{bc|# iptables -nvL}}<br />
and look for rules that might be dropping packets on the {{ic|INPUT}} chain. Then, if necessary, unblock the port with a command like: <br />
{{bc|<br />
# iptables -I INPUT 1 -p tcp --dport 22 -j ACCEPT<br />
}}<br />
For more help configuring firewalls, see [[firewalls]].<br />
<br />
==== Is the traffic even getting to your computer? ====<br />
<br />
Start a traffic dump on the computer you are having problems with:<br />
<br />
# tcpdump -lnn -i any port ssh and tcp-syn<br />
<br />
This should show some basic information, then wait for any matching traffic to happen before displaying it. Try your connection now. If you do not see any output when you attempt to connect, then something outside of your computer is blocking the traffic (e. g., hardware firewall, NAT router etc.).<br />
<br />
==== Your ISP or a third party blocking default port? ====<br />
<br />
{{Note|Try this step if you '''know''' you are not running any firewalls and you know you have configured the router for DMZ or have forwarded the port to your computer and it still does not work. Here you will find diagnostic steps and a possible solution.}}<br />
<br />
In some cases, your ISP might block the default port (SSH port 22) so whatever you try (opening ports, hardening the stack, defending against flood attacks, et al) ends up useless. To confirm this, create a server on all interfaces (0.0.0.0) and connect remotely. <br />
<br />
If you get an error message comparable to this:<br />
<br />
ssh: connect to host www.inet.hr port 22: Connection refused<br />
<br />
That means the port is '''not''' being blocked by the ISP, but the server does not run SSH on that port (See [[wikipedia:Security through obscurity|security through obscurity]]).<br />
<br />
However, if you get an error message comparable to this:<br />
<br />
ssh: connect to host 111.222.333.444 port 22: Operation timed out <br />
<br />
That means that something is rejecting your TCP traffic on port 22. Basically that port is stealth, either by your firewall or 3rd party intervention (like an ISP blocking and/or rejecting incoming traffic on port 22). If you know you are not running any firewall on your computer, and you know that Gremlins are not growing in your routers and switches, then your ISP is blocking the traffic.<br />
<br />
To double check, you can run Wireshark on your server and listen to traffic on port 22. Since Wireshark is a Layer 2 Packet Sniffing utility, and TCP/UDP are Layer 3 and above (see [[wikipedia:Internet protocol suite|IP Network stack]]), if you do not receive anything while connecting remotely, a third party is most likely to be blocking the traffic on that port to your server.<br />
<br />
===== Diagnosis =====<br />
<br />
[[Install]] either {{Pkg|tcpdump}} or Wireshark with the {{Pkg|wireshark-cli}} package.<br />
<br />
For tcpdump:<br />
<br />
# tcpdump -ni ''interface'' "port 22"<br />
<br />
For Wireshark:<br />
<br />
$ tshark -f "tcp port 22" -i ''interface''<br />
<br />
where {{ic|''interface''}} is the network interface for a WAN connection (see {{ic|ip a}} to check). If you are not receiving any packets while trying to connect remotely, you can be very sure that your ISP is blocking the incoming traffic on port 22.<br />
<br />
===== Possible solution =====<br />
<br />
The solution is just to use some other port that the ISP is not blocking. Open the {{ic|/etc/ssh/sshd_config}} and configure the file to use different ports. For example, add:<br />
<br />
Port 22<br />
Port 1234<br />
<br />
Also make sure that other "Port" configuration lines in the file are commented out. Just commenting "Port 22" and putting "Port 1234" will not solve the issue because then sshd will only listen on port 1234. Use both lines to run the SSH server on both ports. <br />
<br />
[[Restart]] the server {{ic|sshd.service}} and you are almost done. You still have to configure your client(s) to use the other port instead of the default port. There are numerous solutions to that problem, but let us cover two of them here.<br />
<br />
==== Read from socket failed: connection reset by peer ====<br />
<br />
Recent versions of openssh sometimes fail with the above error message when connecting to older ssh servers. This can be worked around by setting various [[#Configuration|client options]] for that host. See {{man|5|ssh_config}} for more information about the following options.<br />
<br />
The problem could be the {{ic|ecdsa-sha2-nistp*-cert-v01@openssh}} elliptical host key algorithms. These can be disabled by setting {{ic|HostKeyAlgorithms}} to a list excluding those algorithms.<br />
<br />
If that does not work, it could be that the list of ciphers is too long. Set the {{ic|Ciphers}} option to a shorter list (fewer than 80 characters should be enough). Similarly, you can also try shortening the list of {{ic|MACs}}.<br />
<br />
See also the [http://www.gossamer-threads.com/lists/openssh/dev/51339 discussion] on the openssh bug forum.<br />
<br />
=== "[your shell]: No such file or directory" / ssh_exchange_identification problem ===<br />
<br />
One possible cause for this is the need of certain SSH clients to find an absolute path (one returned by {{Ic|whereis -b [your shell]}}, for instance) in {{Ic|$SHELL}}, even if the shell's binary is located in one of the {{Ic|$PATH}} entries.<br />
<br />
==="Terminal unknown" or "Error opening terminal" error message===<br />
<br />
If you receive the above errors upon logging in, this means the server does not recognize your terminal. Ncurses applications like nano may fail with the message "Error opening terminal".<br />
<br />
The correct solution is to install the client terminal's terminfo file on the server. This tells console programs on the server how to correctly interact with your terminal. You can get info about current terminfo using {{ic|$ infocmp}} and then find out [[pacman#Querying package databases|which package owns it]].<br />
<br />
If you cannot [[install]] it normally, you can copy your terminfo to your home directory on the server:<br />
<br />
$ ssh myserver mkdir -p ~/.terminfo/${TERM:0:1}<br />
$ scp /usr/share/terminfo/${TERM:0:1}/$TERM myserver:~/.terminfo/${TERM:0:1}/<br />
<br />
After logging in and out from the server the problem should be fixed.<br />
<br />
==== TERM hack ====<br />
<br />
{{Note|This should only be used as a last resort.}}<br />
<br />
Alternatively, you can simply set {{ic|1=TERM=xterm}} in your environment on the server (e.g. in {{ic|.bash_profile}}). This will silence the error and allow ncurses applications to run again, but you may experience strange behavior and graphical glitches unless your terminal's control sequences exactly match xterm's.<br />
<br />
=== Connection closed by x.x.x.x [preauth] ===<br />
<br />
If you are seeing this error in your sshd logs, make sure you have set a valid HostKey<br />
<br />
HostKey /etc/ssh/ssh_host_rsa_key<br />
<br />
=== id_dsa refused by OpenSSH 7.0 ===<br />
<br />
OpenSSH 7.0 deprecated DSA public keys for security reasons. If you absolutely must enable them, set the [[#Configuration|config]] option {{ic|PubkeyAcceptedKeyTypes +ssh-dss}} (http://www.openssh.com/legacy.html does not mention this).<br />
<br />
=== No matching key exchange method found by OpenSSH 7.0 ===<br />
<br />
OpenSSH 7.0 deprecated the diffie-hellman-group1-sha1 key algorithm because it is weak and within theoretical range of the so-called Logjam attack (see http://www.openssh.com/legacy.html). If the key algorithm is needed for a particular host, ssh will produce an error message like this:<br />
<br />
Unable to negotiate with 127.0.0.1: no matching key exchange method found.<br />
Their offer: diffie-hellman-group1-sha1<br />
<br />
The best resolution for these failures is to upgrade/configure the server to not use deprecated algorithms. If that is not possible, you can force the client to reenable the algorithm with the [[#Configuration|client option]] {{ic|KexAlgorithms +diffie-hellman-group1-sha1}}.<br />
<br />
=== tmux/screen session killed when disconnecting from SSH ===<br />
<br />
If your processes get killed at the end of the session, it is possible that you are using socket activation and it gets killed by {{Pkg|systemd}} when it notices that the SSH session process exited. In that case there are two solutions. One is to avoid using socket activation by using {{ic|ssh.service}} instead of {{ic|ssh.socket}}. The other is to set {{ic|1=KillMode=process}} in the Service section of {{ic|ssh@.service}}.<br />
<br />
The {{ic|1=KillMode=process}} setting may also be useful with the classic {{ic|ssh.service}}, as it avoids killing the SSH session process or the {{Pkg|screen}} or {{Pkg|tmux}} processes when the server gets stopped or restarted.<br />
<br />
=== SSH session stops responding ===<br />
<br />
SSH responds to [[Wikipedia:Software flow control|flow control commands]] {{ic|XON}} and {{ic|XOFF}}. It will freeze/hang/stop responding when you hit {{ic|Ctrl+s}}. Use {{ic|Ctrl+q}} to resume your session.<br />
<br />
=== Broken pipe ===<br />
<br />
If you attempt to create a connection which results in a {{ic|Broken pipe}} response for {{ic|packet_write_wait}}, you should reattempt the connection in debug mode and see if the output ends in error:<br />
{{bc|debug3: send packet: type 1<br />
packet_write_wait: Connection to A.B.C.D port 22: Broken pipe}}<br />
The {{ic|send packet}} line above indicates that the reply packet was never received. So, it follows that this is a ''QoS'' issue. To decrease the likely-hood of a packet being dropped, set {{ic|IPQoS}}:<br />
{{hc|/etc/ssh/ssh_config|Host *<br />
IPQoS reliability}}<br />
The {{ic|reliability}} ({{ic|0x04}}) type-of-service should resolve the issue, as well as {{ic|0x00}} and {{ic|throughput}} ({{ic|0x08}}).<br />
<br />
=== Slow daemon startup after reboot ===<br />
<br />
If you are experiencing excessively long daemon startup times after reboots (e.g. several minutes before the daemon starts accepting connections), especially on headless or virtualized servers, it may be due to a lack of entropy.[https://bbs.archlinux.org/viewtopic.php?id=241954] This can be remedied by installing either [[Rng-tools]] or [[Haveged]], as appropriate for your system. However, take note of the associated security implications discussed in each package's respective wiki page.<br />
<br />
=== Terminate unresponsive SSH connection ===<br />
<br />
If a client session is no longer responding and cannot be terminated by instructing the running program (e.g. [[shell]]), you can still terminate the session by pressing {{ic|Enter}}, {{ic|~}} and {{ic|.}} one after another in that order.<br />
<br />
The {{ic|~}} is a pseudo-terminal escape character (see {{man|1|ssh|ESCAPE CHARACTERS}}), which can be added multiple times depending on the client session to terminate. For example, if you connected from A to B and then from B to C and the session from B to C freezes, you can terminate it by pressing {{ic|Enter}} and typing {{ic|~~.}}, which will leave you in a working session on B.<br />
<br />
=== WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! ===<br />
<br />
If the client warns that the key of an ssh server has changed, you should verify that the newly offered key really belongs to the server operator. Then remove the old key from the {{ic|known_hosts}} file with {{ic|ssh-keygen -R $SSH_HOST}} and accept the new key as if it was a new server.<br />
<br />
== See also ==<br />
<br />
* [http://www.la-samhna.de/library/brutessh.html Defending against brute force ssh attacks]<br />
* OpenSSH key management: [http://www.ibm.com/developerworks/library/l-keyc/index.html Part 1] on IBM developerWorks, [https://www.funtoo.org/OpenSSH_Key_Management,_Part_2 Part 2], [https://www.funtoo.org/OpenSSH_Key_Management,_Part_3 Part 3] on funtoo.org<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Improving_performance&diff=626666Improving performance2020-07-24T18:16:15Z<p>Progandy: /* Alternative CPU schedulers */ Replaced link to C.Kolivas. Source: https://lore.kernel.org/lkml/CABqErrE2Sfj0wGFoVgYEu-4rpZ3KwgfHwZdinbip5Wqr=gRoNA@mail.gmail.com/</p>
<hr />
<div>[[Category:Hardware]]<br />
[[Category:System administration]]<br />
[[ar:Improving performance]]<br />
[[es:Improving performance]]<br />
[[ja:パフォーマンスの最大化]]<br />
[[pt:Improving performance]]<br />
[[ru:Improving performance]]<br />
[[zh-hans:Improving performance]]<br />
{{Related articles start}}<br />
{{Related|/Boot process}}<br />
{{Related|Pacman/Tips and tricks#Performance}}<br />
{{Related|OpenSSH#Speeding up SSH}}<br />
{{Related|Openoffice#Speed up OpenOffice}}<br />
{{Related|Laptop}}<br />
{{Related|Preload}}<br />
{{Related articles end}}<br />
This article provides information on basic system diagnostics relating to performance as well as steps that may be taken to reduce resource consumption or to otherwise optimize the system with the end-goal being either perceived or documented improvements to a system's performance.<br />
<br />
== The basics ==<br />
<br />
=== Know your system ===<br />
<br />
The best way to tune a system is to target bottlenecks, or subsystems which limit overall speed. The system specifications can help identify them.<br />
<br />
* If the computer becomes slow when large applications (such as LibreOffice and Firefox) run at the same time, check if the amount of RAM is sufficient. Use the following command, and check the "available" column:<br />
<br />
$ free -h<br />
<br />
* If boot time is slow, and applications take a long time to load at first launch (only), then the hard drive is likely to blame. The speed of a hard drive can be measured with the {{ic|hdparm}} command:<br />
{{Note|{{Pkg|hdparm}} indicates only the pure read speed of a hard drive, and is not a valid benchmark. A value higher than 40MB/s (while idle) is however acceptable on an average system.}}<br />
<br />
# hdparm -t /dev/sdX<br />
<br />
* If CPU load is consistently high even with enough RAM available, then try to lower CPU usage by disabling running [[daemons]] and/or processes. This can be monitored in several ways, for example with {{Pkg|htop}}, {{ic|pstree}} or any other [[List_of_applications#System monitors|system monitoring]] tool:<br />
<br />
$ htop<br />
<br />
* If applications using direct rendering are slow (i.e those which use the GPU, such as video players, games, or even a [[window manager]]), then improving GPU performance should help. The first step is to verify if direct rendering is actually enabled. This is indicated by the {{ic|glxinfo}} command, part of the {{Pkg|mesa-demos}} package:<br />
<br />
{{hc|<nowiki>$ glxinfo | grep "direct rendering"</nowiki>|<br />
direct rendering: Yes<br />
}}<br />
<br />
* When running a [[desktop environment]], disabling (unused) visual desktop effects may reduce GPU usage. Use a more lightweight environment or create a [[Desktop_environment#Custom_environments|custom environment]] if the current does not meet the hardware and/or personal requirements.<br />
<br />
=== Benchmarking ===<br />
<br />
The effects of optimization are often difficult to judge. They can however be measured by [[benchmarking]] tools.<br />
<br />
== Storage devices ==<br />
<br />
=== Multiple hardware paths ===<br />
<br />
{{Style|Subjective writing}}<br />
<br />
An internal hardware path is how the storage device is connected to your motherboard. There are different ways to connect to the motherboard such as TCP/IP through a NIC, plugged in directly using PCIe/PCI, Firewire, Raid Card, USB, etc. By spreading your storage devices across these multiple connection points you maximize the capabilities of your motherboard, for example 6 hard-drives connected via USB would be much much slower than 3 over USB and 3 over Firewire. The reason is that each entry path into the motherboard is like a pipe, and there is a set limit to how much can go through that pipe at any one time. The good news is that the motherboard usually has several pipes.<br />
<br />
More Examples<br />
<br />
# Directly to the motherboard using PCI/PCIe/ATA<br />
# Using an external enclosure to house the disk over USB/Firewire<br />
# Turn the device into a network storage device by connecting over TCP/IP<br />
<br />
Note also that if you have a 2 USB ports on the front of your machine, and 4 USB ports on the back, and you have 4 disks, it would probably be fastest to put 2 on front/2 on back than 3 on back/1 on front. This is because internally the front ports are likely a separate Root Hub than the back, meaning you can send twice as much data by using both than just 1. Use the following commands to determine the various paths on your machine.<br />
<br />
{{hc|USB Device Tree|$ lsusb -t}}<br />
<br />
{{hc|PCI Device Tree|$ lspci -tv}}<br />
<br />
=== Partitioning ===<br />
<br />
Make sure that your partitions are [[Partitioning#Partition_alignment|properly aligned]].<br />
<br />
==== Multiple drives ====<br />
<br />
If you have multiple disks available, you can set them up as a software [[RAID]] for serious speed improvements.<br />
<br />
Creating [[swap]] on a separate disk can also help quite a bit, especially if your machine swaps frequently.<br />
<br />
==== Layout on HDDs ====<br />
<br />
If using a traditional spinning HDD, your partition layout can influence the system's performance. Sectors at the beginning of the drive (closer to the outside of the disk) are faster than those at the end. Also, a smaller partition requires less movements from the drive's head, and so speed up disk operations. Therefore, it is advised to create a small partition (10GB, more or less depending on your needs) only for your system, as near to the beginning of the drive as possible. Other data (pictures, videos) should be kept on a separate partition, and this is usually achieved by separating the home directory ({{ic|/home/''user''}}) from the system ({{ic|/}}).<br />
<br />
=== Choosing and tuning your filesystem ===<br />
<br />
Choosing the best filesystem for a specific system is very important because each has its own strengths. The [[File systems]] article provides a short summary of the most popular ones. You can also find relevant articles in [[:Category:File systems]].<br />
<br />
==== Mount options ====<br />
<br />
The [[fstab#atime options|noatime]] option is known to improve performance of the filesystem.<br />
<br />
Other mount options are filesystem specific, therefore see the relevant articles for the filesystems:<br />
<br />
* [[Ext3]]<br />
* [[Ext4#Improving performance]]<br />
* [[JFS Filesystem#Optimizations]]<br />
* [[XFS#Performance]]<br />
* [[Btrfs#Defragmentation]], [[Btrfs#Compression]], and {{man|5|btrfs}}<br />
* [[ZFS#Tuning]]<br />
<br />
===== Reiserfs =====<br />
<br />
The {{Ic|1=data=writeback}} mount option improves speed, but may corrupt data during power loss. The {{Ic|notail}} mount option increases the space used by the filesystem by about 5%, but also improves overall speed. You can also reduce disk load by putting the journal and data on separate drives. This is done when creating the filesystem: <br />
<br />
# mkreiserfs –j /dev/sd'''a1''' /dev/sd'''b1'''<br />
<br />
Replace {{ic|/dev/sd'''a1'''}} with the partition reserved for the journal, and {{ic|/dev/sd'''b1'''}} with the partition for data. You can learn more about reiserfs with this [http://www.funtoo.org/Funtoo_Filesystem_Guide,_Part_2 article].<br />
<br />
=== Tuning kernel parameters ===<br />
<br />
There are several key tunables affecting the performance of block devices, see [[sysctl#Virtual memory]] for more information.<br />
<br />
=== Input/output schedulers ===<br />
<br />
==== Background information ====<br />
<br />
The input/output ''(I/O)'' scheduler is the kernel component that decides in which order the block I/O operations are submitted to storage devices. It is useful to remind here some specifications of two main drive types because the goal of the I/O scheduler is to optimize the way these are able to deal with read requests:<br />
<br />
* An HDD has spinning disks and a head that moves physically to the required location. Therefore, random latency is quite high ranging between 3 and 12ms (whether it is a high end server drive or a laptop drive and bypassing the disk controller write buffer) while sequential access provides much higher throughput. The typical HDD throughput is about 200 I/O operations per second ''(IOPS)''.<br />
<br />
* An SSD does not have moving parts, random access is as fast as sequential one, typically under 0.1ms, and it can handle multiple concurrent requests. The typical SSD throughput is greater than 10,000 IOPS, which is more than needed in common workload situations.<br />
<br />
If there are many processes making I/O requests to different storage parts, thousands of IOPS can be generated while a typical HDD can handle only about 200 IOPS. There is a queue of requests that have to wait for access to the storage. This is where the I/O schedulers plays an optimization role.<br />
<br />
==== The scheduling algorithms ====<br />
<br />
One way to improve throughput is to linearize access: by ordering waiting requests by their logical address and grouping the closest ones. Historically this was the first Linux I/O scheduler called [[Wikipedia:Elevator algorithm|elevator]].<br />
<br />
One issue with the elevator algorithm is that it is not optimal for a process doing sequential access: reading a block of data, processing it for several microseconds then reading next block and so on. The elevator scheduler does not know that the process is about to read another block nearby and, thus, moves to another request by another process at some other location. The [[Wikipedia:Anticipatory scheduling|anticipatory]] I/O scheduler overcomes the problem: it pauses for a few milliseconds in anticipation of another close-by read operation before dealing with another request.<br />
<br />
While these schedulers try to improve total throughput, they might leave some unlucky requests waiting for a very long time. As an example, imagine the majority of processes make requests at the beginning of the storage space while an unlucky process makes a request at the other end of storage. This potentially infinite postponement of the process is called starvation. To improve fairness, the [[Wikipedia:Deadline scheduler|deadline]] algorithm was developed. It has a queue ordered by address, similar to the elevator, but if some request sits in this queue for too long then it moves to an "expired" queue ordered by expire time. The scheduler checks the expire queue first and processes requests from there and only then moves to the elevator queue. Note that this fairness has a negative impact on overall throughput.<br />
<br />
The [[Wikipedia:CFQ|Completely Fair Queuing (CFQ)]] approaches the problem differently by allocating a timeslice and a number of allowed requests by queue depending on the priority of the process submitting them. It supports [[cgroup]] that allows to reserve some amount of I/O to a specific collection of processes. It is in particular useful for shared and cloud hosting: users who paid for some IOPS want to get their share whenever needed. Also, it idles at the end of synchronous I/O waiting for other nearby operations, taking over this feature from the ''anticipatory'' scheduler and bringing some enhancements. Both the ''anticipatory'' and the ''elevator'' schedulers were decommissioned from the Linux kernel replaced by the more advanced alternatives presented above.<br />
<br />
The [https://algo.ing.unimo.it/people/paolo/disk_sched/ Budget Fair Queuing (BFQ)] is based on CFQ code and brings some enhancements. It does not grant the disk to each process for a fixed time-slice but assigns a "budget" measured in number of sectors to the process and uses heuristics. It is a relatively complex scheduler, it may be more adapted to rotational drives and slow SSDs because its high per-operation overhead, especially if associated with a slow CPU, can slow down fast devices. The objective of BFQ on personal systems is that for interactive tasks, the storage device is virtually as responsive as if it was idle. In its default configuration it focuses on delivering the lowest latency rather than achieving the maximum throughput.<br />
<br />
[https://lwn.net/Articles/720675/ Kyber] is a recent scheduler inspired by active queue management techniques used for network routing. The implementation is based on "tokens" that serve as a mechanism for limiting requests. A queuing token is required to allocate a request, this is used to prevent starvation of requests. A dispatch token is also needed and limits the operations of a certain priority on a given device. Finally, a target read latency is defined and the scheduler tunes itself to reach this latency goal. The implementation of the algorithm is relatively simple and it is deemed efficient for fast devices.<br />
<br />
==== Kernel's I/O schedulers ====<br />
<br />
While some of the early algorithms have now been decommissioned, the official Linux kernel supports a number of I/O schedulers which can be split into two categories:<br />
<br />
*The '''multi-queue schedulers''' are available by default with the kernel. The [https://www.thomas-krenn.com/en/wiki/Linux_Multi-Queue_Block_IO_Queueing_Mechanism_(blk-mq) Multi-Queue Block I/O Queuing Mechanism (blk-mq)] maps I/O queries to multiple queues, the tasks are distributed across threads and therefore CPU cores. Within this framework the following schedulers are available:<br />
**''None'', where no queuing algorithm is applied.<br />
**''mq-deadline'', the adaptation of the deadline scheduler (see below) to multi-threading.<br />
**''Kyber''<br />
**''BFQ''<br />
<br />
*The '''single-queue schedulers''' are legacy schedulers:<br />
**[[w:Noop scheduler|NOOP]] is the simplest scheduler, it inserts all incoming I/O requests into a simple FIFO queue and implements request merging. In this algorithm, there is no re-ordering of the request based on the sector number. Therefore it can be used if the ordering is dealt with at another layer, at the device level for example, or if it does not matter, for SSDs for instance.<br />
**[[w:Deadline scheduler|Deadline]]<br />
**[[w:CFQ|CFQ]]<br />
<br />
:{{Note|1=Single-queue schedulers [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f382fb0bcef4c37dc049e9f6963e3baf204d815c were removed from kernel since Linux 5.0].}}<br />
<br />
==== Changing I/O scheduler ====<br />
<br />
{{Note|<br />
* The best choice of scheduler depends on both the device and the exact nature of the workload. Also, the throughput in MB/s is not the only measure of performance: deadline or fairness deteriorate the overall throughput but may improve system responsiveness. [[Benchmarking]] may be useful to indicate each I/O scheduler performance.<br />
}}<br />
<br />
To list the available schedulers for a device and the active scheduler (in brackets):<br />
<br />
{{hc|$ cat /sys/block/'''''sda'''''/queue/scheduler|<br />
mq-deadline kyber [bfq] none<br />
}}<br />
<br />
To list the available schedulers for all devices:<br />
<br />
{{hc|$ grep "" /sys/block/'''*'''/queue/scheduler|<br />
/sys/block/pktcdvd0/queue/scheduler:none<br />
/sys/block/sda/queue/scheduler:mq-deadline kyber [bfq] none<br />
/sys/block/sr0/queue/scheduler:[mq-deadline] kyber bfq none<br />
}}<br />
<br />
To change the active I/O scheduler to ''bfq'' for device ''sda'', use:<br />
<br />
# echo '''''bfq''''' > /sys/block/'''''sda'''''/queue/scheduler<br />
<br />
The process to change I/O scheduler, depending on whether the disk is rotating or not can be automated and persist across reboots. For example the [[udev]] rule below sets the scheduler to ''none'' for [[NVMe]], ''mq-deadline'' for [[SSD]]/eMMC, and ''bfq'' for rotational drives:<br />
<br />
{{hc|/etc/udev/rules.d/60-ioschedulers.rules|2=<br />
# set scheduler for NVMe<br />
ACTION=="add{{!}}change", KERNEL=="nvme[0-9]*", ATTR{queue/scheduler}="none"<br />
# set scheduler for SSD and eMMC<br />
ACTION=="add{{!}}change", KERNEL=="sd[a-z]{{!}}mmcblk[0-9]*", ATTR{queue/rotational}=="0", ATTR{queue/scheduler}="mq-deadline"<br />
# set scheduler for rotating disks<br />
ACTION=="add{{!}}change", KERNEL=="sd[a-z]", ATTR{queue/rotational}=="1", ATTR{queue/scheduler}="bfq"<br />
}}<br />
<br />
Reboot or force [[udev#Loading new rules]].<br />
<br />
==== Tuning I/O scheduler ====<br />
<br />
Each of the kernel's I/O scheduler has its own tunables, such as the latency time, the expiry time or the FIFO parameters. They are helpful in adjusting the algorithm to a particular combination of device and workload. This is typically to achieve a higher throughput or a lower latency for a given utilization.<br />
The tunables and their description can be found within the [https://www.kernel.org/doc/html/latest/block/index.html kernel documentation].<br />
<br />
To list the available tunables for a device, in the example below ''sdb'' which is using ''deadline'', use:<br />
<br />
{{hc|$ ls /sys/block/'''''sdb'''''/queue/iosched|<br />
fifo_batch front_merges read_expire write_expire writes_starved}}<br />
<br />
To improve ''deadline'''s throughput at the cost of latency, one can increase {{ic|fifo_batch}} with the command:<br />
<br />
{{bc|# echo ''32'' > /sys/block/'''''sdb'''''/queue/iosched/'''fifo_batch'''}}<br />
<br />
=== Power management configuration ===<br />
<br />
When dealing with traditional rotational disks (HDD's) you may want to [[Hdparm#Power_management_configuration|lower or disable power saving features]] completely.<br />
<br />
=== Reduce disk reads/writes ===<br />
<br />
Avoiding unnecessary access to slow storage drives is good for performance and also increasing lifetime of the devices, although on modern hardware the difference in life expectancy is usually negligible.<br />
<br />
{{Note|A 32GB SSD with a mediocre 10x write amplification factor, a standard 10000 write/erase cycle, and '''10GB of data written per day''', would get an '''8 years life expectancy'''. It gets better with bigger SSDs and modern controllers with less write amplification. Also compare [http://techreport.com/review/25889/the-ssd-endurance-experiment-500tb-update] when considering whether any particular strategy to limit disk writes is actually needed.}}<br />
<br />
==== Show disk writes ====<br />
<br />
The {{Pkg|iotop}} package can sort by disk writes, and show how much and how frequently programs are writing to the disk. See {{man|8|iotop}} for details.<br />
<br />
==== Relocate files to tmpfs ====<br />
<br />
Relocate files, such as your browser profile, to a [[tmpfs]] file system, for improvements in application response as all the files are now stored in RAM:<br />
<br />
* Refer to [[Profile-sync-daemon]] for syncing browser profiles. Certain browsers might need special attention, see e.g. [[Firefox on RAM]].<br />
* Refer to [[Anything-sync-daemon]] for syncing any specified folder.<br />
* Refer to [[Makepkg#Improving compile times]] for improving compile times by building packages in tmpfs.<br />
<br />
==== File systems ====<br />
<br />
Refer to corresponding [[file system]] page in case there were performance improvements instructions, e.g. [[Ext4#Improving performance]] and [[XFS#Performance]].<br />
<br />
==== Swap space ====<br />
<br />
See [[Swap#Performance]].<br />
<br />
==== Writeback interval and buffer size ====<br />
<br />
See [[Sysctl#Virtual memory]] for details.<br />
<br />
=== Storage I/O scheduling with ionice ===<br />
<br />
Many tasks such as backups do not rely on a short storage I/O delay or high storage I/O bandwidth to fulfil their task, they can be classified as background tasks. On the other hand quick I/O is necessary for good UI responsiveness on the desktop. Therefore it is beneficial to reduce the amount of storage bandwidth available to background tasks, whilst other tasks are in need of storage I/O. This can be achieved by making use of the linux I/O scheduler CFQ, which allows setting different priorities for processes.<br />
<br />
The I/O priority of a background process can be reduced to the "Idle" level by starting it with<br />
<br />
# ionice -c 3 command<br />
<br />
See {{man|1|ionice}} and [https://www.cyberciti.biz/tips/linux-set-io-scheduling-class-priority.html] for more information.<br />
<br />
== CPU ==<br />
<br />
=== Overclocking ===<br />
<br />
[[Wikipedia:Overclocking|Overclocking]] improves the computational performance of the CPU by increasing its peak clock frequency. The ability to overclock depends on the combination of CPU model and motherboard model. It is most frequently done through the BIOS. Overclocking also has disadvantages and risks. It is neither recommended nor discouraged here.<br />
<br />
Many Intel chips will not correctly report their clock frequency to acpi_cpufreq and most other utilities. This will result in excessive messages in dmesg, which can be avoided by unloading and blacklisting the kernel module {{ic|acpi_cpufreq}}.<br />
To read their clock speed use ''i7z'' from the {{Pkg|i7z}} package. To check for correct operation of an overclocked CPU, it is recommended to do [[stress testing]].<br />
<br />
=== Frequency scaling ===<br />
<br />
See [[CPU frequency scaling]].<br />
<br />
=== Alternative CPU schedulers ===<br />
<br />
{{Expansion|MuQSS is not the only alternative scheduler.}}<br />
<br />
The default CPU scheduler in the mainline Linux kernel is [[Wikipedia:Completely_Fair_Scheduler|CFS]]. Alternative schedulers are available.<br />
<br />
One alternative scheduler focused on desktop interactivity and responsiveness is [http://ck.kolivas.org/patches/muqss/sched-MuQSS.txt MuQSS], developed by [http://kernel.kolivas.org/ Con Kolivas]. MuQSS is included in the {{Pkg|linux-zen}} kernel package. It is also available as a stand-alone patch or as part of the wider '''-ck''' patchset. See [[Linux-ck]] and [[Linux-pf]] for more information on the patchset.<br />
<br />
=== Real-time kernel ===<br />
<br />
Some applications such as running a TV tuner card at full HD resolution (1080p) may benefit from using a [[realtime kernel]].<br />
<br />
=== Adjusting priorities of processes ===<br />
<br />
See also {{man|1|nice}} and {{man|1|renice}}.<br />
<br />
==== Ananicy ====<br />
<br />
[https://github.com/Nefelim4ag/Ananicy Ananicy] is a daemon, available in the {{AUR|ananicy-git}} package, for auto adjusting the nice levels of executables. The nice level represents the priority of the executable when allocating CPU resources.<br />
<br />
==== cgroups ====<br />
<br />
See [[cgroups]].<br />
<br />
==== Cpulimit ====<br />
<br />
[https://github.com/opsengine/cpulimit Cpulimit] is a program to limit the CPU usage percentage of a specific process. After installing {{Pkg|cpulimit}}, you may limit the CPU usage of a processes' PID using a scale of 0 to 100 times the number of CPU cores that the computer has. For example, with eight CPU cores the precentage range will be 0 to 800. Usage:<br />
<br />
$ cpulimit -l 50 -p 5081<br />
<br />
=== irqbalance ===<br />
<br />
The purpose of {{Pkg|irqbalance}} is distribute hardware interrupts across processors on a multiprocessor system in order to increase performance. It can be [[systemd#Using units|controlled]] by the provided {{ic|irqbalance.service}}.<br />
<br />
=== Turn off CPU exploit mitigations ===<br />
<br />
{{Warning|1=Do not apply this setting without considering the vulnerabilities it opens up. See [https://phoronix.com/scan.php?page=news_item&px=Linux-Improve-CPU-Spec-Switches this] and [https://linuxreviews.org/HOWTO_make_Linux_run_blazing_fast_(again)_on_Intel_CPUs this] for more information.}}<br />
<br />
Turning off CPU exploit mitigations improves performance (sometimes up to 50%). Use below [[kernel parameter]] to disable them all:<br />
<br />
mitigations=off<br />
<br />
The explanations of all the switches it toggles are given at [https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html kernel.org]. You can use {{AUR|spectre-meltdown-checker}} for vulnerability check.<br />
<br />
== Graphics ==<br />
<br />
=== Xorg configuration ===<br />
<br />
Graphics performance may depend on the settings in {{man|5|xorg.conf}}; see the [[NVIDIA]], [[ATI]], [[AMDGPU]] and [[Intel]] articles. Improper settings may stop Xorg from working, so caution is advised.<br />
<br />
=== Mesa configuration ===<br />
<br />
The performance of the Mesa drivers can be configured via [https://dri.freedesktop.org/wiki/ConfigurationInfrastructure/ drirc]. GUI configuration tools are available:<br />
<br />
* {{App|adriconf (Advanced DRI Configurator)|GUI tool to configure Mesa drivers by setting options and writing them to the standard drirc file.|https://gitlab.freedesktop.org/mesa/adriconf/|{{Pkg|adriconf}}}}<br />
* {{App|DRIconf|Configuration applet for the Direct Rendering Infrastructure. It allows customizing performance and visual quality settings of OpenGL drivers on a per-driver, per-screen and/or per-application level.|https://dri.freedesktop.org/wiki/DriConf/|{{AUR|driconf}}}}<br />
<br />
=== Overclocking ===<br />
<br />
As with CPUs, overclocking can directly improve performance, but is generally recommended against. There are several packages in the [[AUR]], such as {{AUR|amdoverdrivectrl}} (old AMD/ATI cards), {{AUR|rocm-smi}} (recent AMD cards), {{AUR|nvclock}} (old NVIDIA - up to Geforce 9), and {{Pkg|nvidia-utils}} for recent NVIDIA cards.<br />
<br />
See [[AMDGPU#Overclocking]] or [[NVIDIA/Tips and tricks#Enabling overclocking]].<br />
<br />
== RAM, swap and OOM handling ==<br />
<br />
=== Clock frequency and timings ===<br />
<br />
RAM can run at different clock frequencies and timings, which can be configured in the BIOS. Memory performance depends on both values. Selecting the highest preset presented by the BIOS usually improves the performance over the default setting. Note that increasing the frequency to values not supported by both motherboard and RAM vendor is overclocking, and similar risks and disadvantages apply, see [[#Overclocking]].<br />
<br />
=== Root on RAM overlay ===<br />
<br />
If running off a slow writing medium (USB, spinning HDDs) and storage requirements are low, the root may be run on a RAM overlay ontop of read only root (on disk). This can vastly improve performance at the cost of a limited writable space to root. See {{AUR|liveroot}}.<br />
<br />
=== Zram or zswap ===<br />
<br />
The [https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html zram] kernel module (previously called '''compcache''') provides a compressed block device in RAM. If you use it as swap device, the RAM can hold much more information but uses more CPU. Still, it is much quicker than swapping to a hard drive. If a system often falls back to swap, this could improve responsiveness. Using zram is also a good way to reduce disk read/write cycles due to swap on SSDs.<br />
<br />
Similar benefits (at similar costs) can be achieved using [[zswap]] rather than zram. The two are generally similar in intent although not operation: zswap operates as a compressed RAM cache and neither requires (nor permits) extensive userspace configuration.<br />
<br />
Example: To set up one lz4 compressed zram device with 32GiB capacity and a higher-than-normal priority (only for the current session):<br />
<br />
# modprobe zram<br />
# echo lz4 > /sys/block/zram0/comp_algorithm<br />
# echo 32G > /sys/block/zram0/disksize<br />
# mkswap --label zram0 /dev/zram0<br />
# swapon --priority 100 /dev/zram0<br />
<br />
To disable it again, either reboot or run<br />
<br />
# swapoff /dev/zram0<br />
# rmmod zram<br />
<br />
A detailed explanation of all steps, options and potential problems is provided in the [https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html official documentation of the zram module].<br />
<br />
The {{Pkg|systemd-swap}} package provides a {{ic|systemd-swap.service}} unit to automatically initialize zram devices. Configuration is possible in {{ic|/etc/systemd/swap.conf}}.<br />
<br />
The package {{AUR|zramswap}} provides an automated script for setting up a swap with a higher priority and a default size of 20% of the RAM size of your system. To do this automatically on every boot, [[enable]] {{ic|zramswap.service}}.<br />
<br />
==== Swap on zRAM using a udev rule ====<br />
<br />
The example below describes how to set up swap on zRAM automatically at boot with a single udev rule. No extra package should be needed to make this work.<br />
<br />
First, enable the module:<br />
<br />
{{hc|/etc/modules-load.d/zram.conf|<nowiki><br />
zram<br />
</nowiki>}}<br />
<br />
Configure the number of /dev/zram nodes you need.<br />
<br />
{{hc|/etc/modprobe.d/zram.conf|<nowiki><br />
options zram num_devices=2<br />
</nowiki>}}<br />
<br />
Create the udev rule as shown in the example.<br />
<br />
{{hc|/etc/udev/rules.d/99-zram.rules|<nowiki><br />
KERNEL=="zram0", ATTR{disksize}="512M" RUN="/usr/bin/mkswap /dev/zram0", TAG+="systemd"<br />
KERNEL=="zram1", ATTR{disksize}="512M" RUN="/usr/bin/mkswap /dev/zram1", TAG+="systemd"<br />
</nowiki>}}<br />
<br />
Add /dev/zram to your fstab.<br />
<br />
{{hc|/etc/fstab|<nowiki><br />
/dev/zram0 none swap defaults 0 0<br />
/dev/zram1 none swap defaults 0 0<br />
</nowiki>}}<br />
<br />
=== Using the graphic card's RAM ===<br />
<br />
In the unlikely case that you have very little RAM and a surplus of video RAM, you can use the latter as swap. See [[Swap on video RAM]].<br />
<br />
=== Improving system responsiveness under low-memory conditions ===<br />
<br />
On traditional GNU/Linux system, especially for graphical workstations, when allocated memory is overcommitted, the overall system's responsiveness may degrade to a nearly unusable state before either triggering the in-kernel OOM-killer or a sufficient amount of memory got free (which is unlikely to happen quickly when the system is unresponsive, as you can hardly close any memory-hungry applications which may continue to allocate more memory). The behaviour also depends on specific setups and conditions, returning to a normal responsive state may take from a few seconds to more than half an hour, which could be a pain to wait in serious scenario like during a conference presentation.<br />
<br />
While the behaviour of the kernel as well as the userspace things under low-memory conditions may improve in the future as discussed on kernel[https://lore.kernel.org/lkml/d9802b6a-949b-b327-c4a6-3dbca485ec20@gmx.com/T/] and fedora[https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/XUZLHJ5O32OX24LG44R7UZ2TMN6NY47N/] mailing list, users can use more feasible and effective options than hard-resetting the system or tuning the {{ic|vm.overcommit_*}} [[sysctl]] parameters:<br />
<br />
* Manually trigger the kernel OOM-killer with [https://www.kernel.org/doc/html/latest/admin-guide/sysrq.html Magic SysRq key], namely {{ic|Alt+SysRq+f}}.<br />
* Use a userspace OOM daemon to tackle these automatically (or interactively).<br />
<br />
{{Warning|Triggering OOM killer to kill running applications may lose your unsaved works. It is up to you that either you are patient enough to wait in hope that applications will finally free the memory normally, or you want to bring back unresponsive system as soon as possible.}}<br />
<br />
Sometimes a user may prefer OOM daemon to SysRq because with kernel OOM-killer you cannot prioritize the process to (or not) terminate. To list some OOM daemons:<br />
<br />
* {{App|earlyoom|Simple userspace OOM-killer implementation written in C. Fedora is going to have this in their default Workstation installation [https://pagure.io/fedora-workstation/issue/119].|https://github.com/rfjakob/earlyoom|{{Pkg|earlyoom}}}}<br />
* {{App|oomd|OOM-killer implementation based on [https://lwn.net/Articles/759781/ PSI], requires Linux kernel version 4.20+. Configuration is in JSON and is quite complex. Confirmed to work in Facebook's production environment.|https://github.com/facebookincubator/oomd|{{aur|oomd}}}}<br />
* {{App|nohang|Sophisticated OOM handler written in Python, with optional PSI support, more configurable than earlyoom.|https://github.com/hakavlad/nohang|{{aur|nohang-git}}}}<br />
* {{App|low-memory-monitor|GNOME developer's effort that aims to provides better communication to userspace applications to indicate the low memory state, besides that it could be configured to trigger the kernel OOM-killer. Based on PSI, requires Linux 5.2+.|https://gitlab.freedesktop.org/hadess/low-memory-monitor/|{{aur|low-memory-monitor-git}}}}<br />
<br />
== Network ==<br />
<br />
* Kernel networking: see [[Sysctl#Improving performance]]<br />
* NIC: see [[Network configuration#Set device MTU and queue length]]<br />
* DNS: consider using a caching DNS resolver, see [[Domain name resolution#DNS servers]]<br />
* Samba: see [[Samba#Improve throughput]]<br />
<br />
== Watchdogs ==<br />
<br />
According to [[Wikipedia:Watchdog timer]]:<br />
<br />
:A watchdog timer [...] is an electronic timer that is used to detect and recover from computer malfunctions. During normal operation, the computer regularly resets the watchdog timer [...]. If, [...], the computer fails to reset the watchdog, the timer will elapse and generate a timeout signal [...] used to initiate corrective [...] actions [...] typically include placing the computer system in a safe state and restoring normal system operation.<br />
<br />
Many users need this feature due to their system's mission-critical role (i.e. servers), or because of the lack of power reset (i.e. embedded devices). Thus, this feature is required for a good operation in some situations. On the other hand, normal users (i.e. desktop and laptop) do not need this feature and can disable it.<br />
<br />
To disable watchdog timers (both software and hardware), append {{ic|nowatchdog}} to your boot parameters.<br />
<br />
To check the new configuration do:<br />
<br />
# cat /proc/sys/kernel/watchdog<br />
<br />
or use:<br />
<br />
# wdctl<br />
<br />
After you disabled watchdogs, you can ''optionally'' avoid the loading of the module responsible of the hardware watchdog, too. Do it by [[blacklisting]] the related module, e.g. {{ic|iTCO_wdt}}.<br />
<br />
{{Note|1=Some users [https://bbs.archlinux.org/viewtopic.php?id=221239 reported] the {{ic|nowatchdog}} parameter does not work as expected but they have successfully disabled the watchdog (at least the hardware one) by blacklisting the above-mentioned module.}}<br />
<br />
Either action will speed up your boot and shutdown, because one less module is loaded. Additionally disabling watchdog timers increases performance and [[Power management#Disabling NMI watchdog|lowers power consumption]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?id=163768], [https://bbs.archlinux.org/viewtopic.php?id=165834], [http://0pointer.de/blog/projects/watchdog.html], and [https://www.kernel.org/doc/html/latest/watchdog/watchdog-parameters.html] for more information.<br />
<br />
== See also ==<br />
<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Performance_Tuning_Guide/index.html Red Hat Performance Tuning Guide]<br />
* [https://www.thomas-krenn.com/en/wiki/Linux_Performance_Measurements_using_vmstat Linux Performance Measurements using vmstat]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Rip_Audio_CDs&diff=625035Rip Audio CDs2020-07-13T10:17:37Z<p>Progandy: /* Ripping */ Add a link to gnudb.org</p>
<hr />
<div>[[Category:Optical disc]]<br />
{{Related articles start}}<br />
{{Related|Convert FLAC to MP3}}<br />
{{Related|MEncoder}}<br />
{{Related|Codecs}}<br />
{{Related articles end}}<br />
<br />
CD rippers are designed to extract ("rip") the raw digital audio (in a format commonly called CDDA) from a compact disc to a file or other output.<br />
<br />
== Introduction ==<br />
<br />
Music is usually stored on audio CDs in an uncompressed format which requires a lot of space (e.g. 700MB for only 80 minutes of audio). This is because they have a constant high bitrate of over one megabyte per second. Extracting the audio from the CD usually involves compressing it so that it requires less space using either:<br />
<br />
; Lossless compression: same quality, roughly 1/2 the size. Examples: APE and FLAC<br />
; Lossy compression: lower quality, roughly 1/10 the size. Examples: MP3 and OGG<br />
<br />
== Ripping ==<br />
<br />
See [[Optical disc drive#Ripping]] for a list of available software. For example, to extract audio with the community package {{pkg|cdrtools}}:<br />
<br />
$ cdda2wav -vall cddb=0 speed=4 -paranoia paraopts=proof -B -D /dev/sr0<br />
<br />
Some CD rippers support burning audio to a CD and transcoding on-the-fly (e.g. ''cdda2mp3'').<br />
<br />
{{Note|<br />
By default cdda2wav uses freedb.freedb.org as its cddbp server to lookup CDs. Freedb.org was shutdown on May 28th 2020 and as of 13th of June 2020, this URL used for lookups no longer seems to operate. [[Wikipedia:freedb]]<br />
An alternative cddbp service provided by [http://gnudb.org/ gnudb.org] does exist and the parameters cddbp-server and cddbp-port could be used to access that instead.<br />
}}<br />
<br />
=== Creating cue files ===<br />
<br />
To allow ''cdda2wav'' to create CUE files, you must also specify {{ic|-t all}} to switch ''cdda2wav'' into a mode that creates a single audio data file for the whole CD.<br />
<br />
Alternatively to create a bin and cue file pair from an audio CD use {{Pkg|cdrdao}}. For example:<br />
<br />
$ cdrdao read-cd --read-raw --datafile cdimage.bin cdimage.cue<br />
<br />
The cue file generated by this method is not the same as some may expect from tools like [[Wikipedia:Exact_Audio_Copy|EAC]]. To convert the ''cdrdao'' formatted cue files to a "standard" cue file, try {{AUR|yatoc2cue}}.<br />
<br />
== Post-processing ==<br />
<br />
=== Tag editors ===<br />
<br />
For some examples of audio tag editors see [[List of applications/Multimedia#Audio tag editors]].<br />
<br />
=== Converting to other formats ===<br />
<br />
Re-encoding to another format can be done with {{pkg|lame}}, {{pkg|flac}} or [[FFmpeg]]. For example, to convert the output raw audio files from [[#Ripping]] to highest quality variable bitrate MP3:<br />
<br />
$ lame -V0 ''input''.wav<br />
<br />
To convert them to FLAC instead:<br />
<br />
$ flac ''input''.wav<br />
<br />
== See also ==<br />
<br />
* RIAA allow backup of physically obtained media under [https://www.riaa.com/physicalpiracy.php?content_selector=piracy_online_the_law these] conditions.<br />
* {{man|1|lame}} manual page, for options and presets.<br />
* Hydrogenaudio's [http://wiki.hydrogenaud.io/index.php?title=LAME#Recommended_encoder_settings description] of recommended LAME encoder settings.</div>Progandyhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=625031Network configuration/Wireless2020-07-13T08:47:39Z<p>Progandy: /* See also */ Link to WikiDevi alternatives.</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Network configuration (Česky)/Wireless]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Network configuration (Ελληνικά)/Wireless]]<br />
[[es:Network configuration (Español)/Wireless]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Wifi]]<br />
[[it:Network configuration (Italiano)/Wireless]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Network configuration (Nederlands)/Wireless]]<br />
[[pt:Network configuration (Português)/Wireless]]<br />
[[ru:Network configuration (Русский)/Wireless]]<br />
[[zh-hans:Network configuration (简体中文)/Wireless]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
{{Note|<br />
* If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.<br />
* If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
}}<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List]{{Dead link|2020|04|01|status=403}} (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64]<br />
|-<br />
| [http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{pkg|wireless_tools}} || {{yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.wiki.kernel.org/en/users/documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[WPA supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [https://wireless.wiki.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iw list''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [https://wireless.wiki.kernel.org/en/users/documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== Authentication ==<br />
<br />
{{Expansion|Add [[Wikipedia:WPA3|WPA3 Enterprise]] ({{Bug|65314}}) and [[Wikipedia:Opportunistic Wireless Encryption|Opportunistic Wireless Encryption (OWE) a.k.a. Enhanced Open]]. Warn against WEP and open networks.}}<br />
<br />
=== WPA2 Personal ===<br />
<br />
WPA2 Personal, a.k.a. WPA2-PSK, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
You can authenticate to WPA2 Personal networks using [[WPA supplicant]] or [[iwd]], or connect using a [[network manager]]. If you only authenticated to the network, then to have a fully functional connection you will still need to assign the IP address(es) and routes either [[Network configuration#Static IP address|manually]] or using a [[DHCP]] client.<br />
<br />
=== WPA2 Enterprise ===<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option.<br />
<br />
==== eduroam ====<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
==== Manual/automatic setup ====<br />
<br />
* [[WPA supplicant#Advanced usage|WPA supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
* [[NetworkManager]] can create WPA2 Enterprise profiles with ''nmcli'' or the [[NetworkManager#Front-ends|graphical front ends]]. ''nmtui'' does not support this ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/376 NetworkManager issue 376]), but may use existing profiles.<br />
* [[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting to eduroam (802.1X)]] for details.<br />
* [[netctl]] supports wpa_supplicant configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
: {{Warning|Special quoting rules apply: see the {{ic|''SPECIAL QUOTING RULES''}} section in {{man|5|netctl.profile}}.}}<br />
: {{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== WPA3 Personal ===<br />
<br />
{{Expansion|Does [[iwd]] support WPA3?}}<br />
<br />
WPA3 Personal, a.k.a. WPA3-SAE, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
[[wpa_supplicant]] supports WPA3 Personal ({{ic|CONFIG_SAE}} is enabled in {{Pkg|wpa_supplicant}} since version 2:2.9-4).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dBm-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [http://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|<br />
* Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.<br />
* According to [https://git.kernel.org/pub/scm/linux/kernel/git/mcgrof/crda.git/tree/README CRDA's README], it is no longer needed since kernel v4.15 as kernel will automatically load regulatory database from firmware. However [https://bugs.gentoo.org/462032#c17 it is also said] specific kernel setup is needed for the loading to work.<br />
}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[WPA supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [https://wireless.wiki.kernel.org/en/developers/documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} as [[Kernel_modules#Setting module options|module options]]. However, this is part of the [https://wireless.wiki.kernel.org/en/developers/regulatory#the_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [https://wireless.wiki.kernel.org/en/developers/regulatory kernel.org regulatory documentation].<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [http://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Observing Logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card. Try disabling the wireless card's [[Power_management#Network_interfaces|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Disable {{ic|40MHz}} channel bandwidth (lower throughput but less likely collisions) <br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, some in-range Wi-Fi networks might be invisible, because they use wireless channels that are not allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}} [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3].<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs]{{Dead link|2018|08|15}} available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]. As of kernel 5.5 it should be supported by the included {{ic|mt76}} driver.<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723ae.conf|2=<br />
options rtl8723ae fwlps=0<br />
}}<br />
or<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au/rtl8812au/rtl8814au/rtl8821au designed for various USB adapters ranging from AC600 to AC1900.<br />
<br />
Several packages provide various kernel drivers:<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8814au and rtl8821au || 5.6.4.1 || {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au, 8814au and 8821au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8812au || 5.2.20 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au ''only''.<br />
|-<br />
| rtl8811au, rtl8812au and rtl8821au || 5.1.5 || {{AUR|rtl8821au-dkms-git}} || For rtl8812au versions 5.6.4.1 or 5.2.20 are recommended instead.<br />
|-<br />
| rtl8814au || 4.3.21 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too. Reportedly has better performance than {{AUR|rtl88xxau-aircrack-dkms-git}}<br />
|}<br />
<br />
These require [[DKMS]] so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8811cu/rtl8821cu ====<br />
<br />
{{AUR|rtl8821cu-dkms-git}} provides a kernel module for the Realtek 8811cu and 8821cu chipset.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8821ce ====<br />
<br />
{{AUR|rtl8821ce-dkms-git}} provides a kernel module for the Realtek 8821ce chipset found in the Asus X543UA.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} or {{AUR|rtl88x2bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3, Asus AC53 Nano USB 802.11ac and TP-Link Archer T3U adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [https://wireless.wiki.kernel.org/en/users/Drivers/Atheros#pcipci-eahb_driversrs Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath5k<br />
* https://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath9k<br />
* https://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [http://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list]{{Dead link|2020|04|01|status=SSL error}} exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [https://wireless.wiki.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi#supported_devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{Aur|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
If your router only supports modes up to 802.11n, using 11n_disable=0 will limit your download and upload speeds at ~20Mbps (802.11g limit). If you need more than that and your card supports 802.11ac and/or 802.11ax modes (e.g. Intel® Wi-Fi 6 AX200 160MHz), consider replacing your router with the one that also supports 802.11ac and/or 802.11ax.<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wi-fibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
===== Firmware stack traces =====<br />
<br />
{{Accuracy|What is the last note about ignored packages trying to say?}}<br />
<br />
You may have some issue where the driver outputs stack traces & errors, which can cause some stuttering.<br />
<br />
{{hc|dmesg|2=<br />
Microcode SW error detected. Restarting 0x2000000.<br />
}}<br />
<br />
To fix those errors, you may downgrade the package {{Pkg|linux-firmware}} or rename the last version of the firmware used by your device so that an older version is loaded (which keeps it out of pacman's ignored packages).<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd#Temporary files|systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [https://wireless.wiki.kernel.org/en/users/drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [https://sourceforge.net/projects/acx100/ official page] for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[https://sourceforge.net/projects/zd1211/ zd1211rw] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[http://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [http://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [https://wireless.wiki.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]<br />
* [https://wikidevi.wi-cat.ru Wireless Device Database Wiki] (This fork is hosted by wi-cat.ru since the original wiki has shut down. There are two less complete versions available: [http://en.techinfodepot.shoutwiki.com TechInfoDepot], [https://deviwiki.com/ deviwiki])</div>Progandyhttps://wiki.archlinux.org/index.php?title=Network_configuration/Wireless&diff=625027Network configuration/Wireless2020-07-13T08:23:37Z<p>Progandy: /* mt7612u */ Mention in-tree driver</p>
<hr />
<div>[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[cs:Network configuration (Česky)/Wireless]]<br />
[[de:(W)LAN und Arch Linux]]<br />
[[el:Network configuration (Ελληνικά)/Wireless]]<br />
[[es:Network configuration (Español)/Wireless]]<br />
[[fa:تنظیمات شبکه ی بی سیم]]<br />
[[fr:Wifi]]<br />
[[it:Network configuration (Italiano)/Wireless]]<br />
[[ja:ワイヤレス設定]]<br />
[[nl:Network configuration (Nederlands)/Wireless]]<br />
[[pt:Network configuration (Português)/Wireless]]<br />
[[ru:Network configuration (Русский)/Wireless]]<br />
[[zh-hans:Network configuration (简体中文)/Wireless]]<br />
{{Related articles start}}<br />
{{Related|Software access point}}<br />
{{Related|Ad-hoc networking}}<br />
{{Related|Internet sharing}}<br />
{{Related|Wireless bonding}}<br />
{{Related|Network Debugging}}<br />
{{Related|Bluetooth}}<br />
{{Related articles end}}<br />
<br />
The main article on network configuration is [[Network configuration]].<br />
<br />
Configuring wireless is a two-part process; the first part is to identify and ensure the correct driver for your wireless device is installed (they are available on the installation media, but often have to be installed explicitly), and to configure the interface. The second is choosing a method of managing wireless connections. This article covers both parts, and provides additional links to wireless management tools.<br />
<br />
The [[#iw]] section describes how to manually manage your wireless network interface / your wireless LANs using {{Pkg|iw}}. The [[Network configuration#Network managers]] section describes several programs that can be used to automatically manage your wireless interface, some of which include a GUI and all of which include support for network profiles (useful when frequently switching wireless networks, like with laptops).<br />
<br />
== Device driver ==<br />
<br />
The default Arch Linux kernel is ''modular'', meaning many of the drivers for machine hardware reside on the hard drive and are available as [[Kernel modules|modules]]. At boot, [[udev]] takes an inventory of your hardware and loads appropriate modules (drivers) for your corresponding hardware, which will in turn allow creation of a network ''interface''.<br />
<br />
Some wireless chipsets also require firmware, in addition to a corresponding driver. Many firmware images are provided by the {{Pkg|linux-firmware}} package, however, proprietary firmware images are not included and have to be installed separately. This is described in [[#Installing driver/firmware]].<br />
<br />
{{Note|If the proper module is not loaded by udev on boot, simply [[Kernel modules#Manual module handling|load it manually]]. If udev loads more than one driver for a device, the resulting conflict may prevent successful configuration. Make sure to [[blacklist]] the unwanted module.}}<br />
<br />
=== Check the driver status ===<br />
<br />
To check if the driver for your card has been loaded, check the output of the {{ic|lspci -k}} or {{ic|lsusb -v}} command, depending on if the card is connected by PCI(e) or USB. You should see that some kernel driver is in use, for example:<br />
<br />
{{hc|$ lspci -k|<nowiki><br />
06:00.0 Network controller: Intel Corporation WiFi Link 5100<br />
Subsystem: Intel Corporation WiFi Link 5100 AGN<br />
Kernel driver in use: iwlwifi<br />
Kernel modules: iwlwifi<br />
</nowiki>}}<br />
<br />
{{Note|If the card is a USB device, running {{ic|dmesg {{!}} grep usbcore}} should give something like {{ic|usbcore: registered new interface driver rtl8187}} as output.}}<br />
<br />
Also check the output of the {{ic|ip link}} command to see if a wireless interface was created; usually the naming of the wireless [[network interfaces]] starts with the letter "w", e.g. {{ic|wlan0}} or {{ic|wlp2s0}}. Then bring the interface up with:<br />
<br />
# ip link set ''interface'' up<br />
<br />
For example, assuming the interface is {{ic|wlan0}}, this is {{ic|ip link set wlan0 up}}.<br />
<br />
{{Note|<br />
* If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.<br />
* If you get the error message {{ic|SIOCSIFFLAGS: No such file or directory}}, it most certainly means that your wireless chipset requires a firmware to function.<br />
}}<br />
<br />
Check kernel messages for firmware being loaded:<br />
<br />
{{hc|<nowiki>$ dmesg | grep firmware</nowiki>|<nowiki><br />
[ 7.148259] iwlwifi 0000:02:00.0: loaded firmware version 39.30.4.1 build 35138 op_mode iwldvm<br />
</nowiki>}}<br />
<br />
If there is no relevant output, check the messages for the full output for the module you identified earlier ({{ic|iwlwifi}} in this example) to identify the relevant message or further issues:<br />
<br />
{{hc|<nowiki>$ dmesg | grep iwlwifi</nowiki>|<nowiki><br />
[ 12.342694] iwlwifi 0000:02:00.0: irq 44 for MSI/MSI-X<br />
[ 12.353466] iwlwifi 0000:02:00.0: loaded firmware version 39.31.5.1 build 35138 op_mode iwldvm<br />
[ 12.430317] iwlwifi 0000:02:00.0: CONFIG_IWLWIFI_DEBUG disabled<br />
...<br />
[ 12.430341] iwlwifi 0000:02:00.0: Detected Intel(R) Corporation WiFi Link 5100 AGN, REV=0x6B<br />
</nowiki>}}<br />
<br />
If the kernel module is successfully loaded and the interface is up, you can skip the next section.<br />
<br />
=== Installing driver/firmware ===<br />
<br />
Check the following lists to discover if your card is supported:<br />
<br />
* See the table of [https://wireless.wiki.kernel.org/en/users/drivers existing Linux wireless drivers] and follow to the specific driver's page, which contains a list of supported devices. There is also a [https://wikidevi.com/wiki/List_of_Wi-Fi_Device_IDs_in_Linux List of Wi-Fi Device IDs in Linux].<br />
* The [https://help.ubuntu.com/community/WifiDocs/WirelessCardsSupported Ubuntu Wiki] has a good list of wireless cards and whether or not they are supported either in the Linux kernel or by a user-space driver (includes driver name).<br />
* [http://linux-wless.passys.nl/ Linux Wireless Support] and The Linux Questions' [http://www.linuxquestions.org/hcl/index.php?cat=10 Hardware Compatibility List]{{Dead link|2020|04|01|status=403}} (HCL) also have a good database of kernel-friendly hardware.<br />
<br />
Note that some vendors ship products that may contain different chip sets, even if the product identifier is the same. Only the usb-id (for USB devices) or pci-id (for PCI devices) is authoritative.<br />
<br />
If your wireless card is listed above, follow the [[#Troubleshooting drivers and firmware]] subsection of this page, which contains information about installing drivers and firmware of some specific wireless cards. Then [[#Check the driver status|check the driver status]] again.<br />
<br />
If your wireless card is not listed above, it is likely supported only under Windows (some Broadcom, 3com, etc). For these, you can try to use [[#ndiswrapper]].<br />
<br />
== Utilities ==<br />
<br />
Just like other network interfaces, the wireless ones are controlled with ''ip'' from the {{Pkg|iproute2}} package.<br />
<br />
Managing a wireless connection requires a basic set of tools. Either use a [[network manager]] or use one of the following directly:<br />
<br />
{| class="wikitable"<br />
! Software !! Package !! [https://wireless.wiki.kernel.org/en/developers/documentation/wireless-extensions WEXT] !! [https://wireless.wiki.kernel.org/en/developers/documentation/nl80211 nl80211] !! WEP !! WPA/WPA2 !! [[Archiso]] [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/configs/releng/packages.x86_64]<br />
|-<br />
| [http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html wireless_tools]<sup>1</sup> || {{pkg|wireless_tools}} || {{yes}} || {{no}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [https://wireless.wiki.kernel.org/en/users/documentation/iw iw] || {{Pkg|iw}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}}<br />
|-<br />
| [[WPA supplicant]] || {{Pkg|wpa_supplicant}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|-<br />
| [[iwd]] || {{Pkg|iwd}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
# Deprecated.<br />
<br />
Note that some cards only support WEXT.<br />
<br />
=== iw and wireless_tools comparison ===<br />
<br />
The table below gives an overview of comparable commands for ''iw'' and ''wireless_tools''. See [https://wireless.wiki.kernel.org/en/users/Documentation/iw/replace-iwconfig iw replaces iwconfig] for more examples.<br />
<br />
{| class="wikitable"<br />
! ''iw'' command<br />
! ''wireless_tools'' command<br />
! Description<br />
|-<br />
| iw dev ''wlan0'' link<br />
| iwconfig ''wlan0''<br />
| Getting link status.<br />
|-<br />
| iw dev ''wlan0'' scan<br />
| iwlist ''wlan0'' scan<br />
| Scanning for available access points.<br />
|-<br />
| iw dev ''wlan0'' set type ibss<br />
| iwconfig ''wlan0'' mode ad-hoc<br />
| Setting the operation mode to ''ad-hoc''.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid''<br />
| iwconfig ''wlan0'' essid ''your_essid''<br />
| Connecting to open network.<br />
|-<br />
| iw dev ''wlan0'' connect ''your_essid'' 2432<br />
| iwconfig ''wlan0'' essid ''your_essid'' freq 2432M<br />
| Connecting to open network specifying channel.<br />
|-<br />
| rowspan="2" | iw dev ''wlan0'' connect ''your_essid'' key 0:''your_key''<br />
| iwconfig ''wlan0'' essid ''your_essid'' key ''your_key''<br />
| Connecting to WEP encrypted network using hexadecimal key.<br />
|-<br />
| iwconfig ''wlan0'' essid ''your_essid'' key s:''your_key''<br />
| Connecting to WEP encrypted network using ASCII key.<br />
|-<br />
| iw dev ''wlan0'' set power_save on<br />
| iwconfig ''wlan0'' power on<br />
| Enabling power save.<br />
|}<br />
<br />
== iw ==<br />
<br />
{{Note|<br />
* Note that most of the commands have to be executed with [[Users and groups|root permissions]]. Executed with normal user rights, some of the commands (e.g. ''iw list''), will exit without error but not produce the correct output either, which can be confusing.<br />
* Depending on your hardware and encryption type, some of these steps may not be necessary. Some cards are known to require interface activation and/or access point scanning before being associated to an access point and being given an IP address. Some experimentation may be required. For instance, WPA/WPA2 users may try to directly activate their wireless network from step [[#Connect to an access point]].}}<br />
<br />
Examples in this section assume that your wireless device interface is {{ic|''interface''}} and that you are connecting to {{ic|''your_essid''}} wifi access point. Replace both accordingly.<br />
<br />
=== Get the name of the interface ===<br />
<br />
{{Tip|See [https://wireless.wiki.kernel.org/en/users/documentation/iw official documentation] of the ''iw'' tool for more examples.}}<br />
<br />
To get the name of your wireless interface do:<br />
<br />
$ iw dev<br />
<br />
The name of the interface will be output after the word "Interface". For example, it is commonly {{ic|wlan0}}.<br />
<br />
=== Get the status of the interface ===<br />
<br />
To check link status, use following command.<br />
<br />
$ iw dev ''interface'' link<br />
<br />
You can get statistic information, such as the amount of tx/rx bytes, signal strength etc., with following command:<br />
<br />
$ iw dev ''interface'' station dump<br />
<br />
=== Activate the interface ===<br />
<br />
{{Tip|Usually this step is not required.}}<br />
<br />
Some cards require that the kernel interface be activated before you can use ''iw'' or ''wireless_tools'':<br />
<br />
# ip link set ''interface'' up<br />
<br />
{{Note|If you get errors like {{ic|RTNETLINK answers: Operation not possible due to RF-kill}}, make sure that hardware switch is ''on''. See [[#Rfkill caveat]] for details.}}<br />
<br />
To verify that the interface is up, inspect the output of the following command:<br />
<br />
{{hc|$ ip link show ''interface''|<br />
3: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state DOWN mode DORMANT group default qlen 1000<br />
link/ether 12:34:56:78:9a:bc brd ff:ff:ff:ff:ff:ff<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
=== Discover access points ===<br />
<br />
To see what access points are available:<br />
<br />
# iw dev ''interface'' scan | less<br />
<br />
{{Note|If it displays {{ic|Interface does not support scanning}}, then you probably forgot to install the firmware. In some cases this message is also displayed when not running ''iw'' as root.}}<br />
<br />
{{Tip|Depending on your location, you might need to set the correct [[#Respecting the regulatory domain|regulatory domain]] in order to see all available networks.}}<br />
<br />
The important points to check:<br />
* '''SSID:''' the name of the network.<br />
* '''Signal:''' is reported in a wireless power ratio in dBm (e.g. from -100 to 0). The closer the negative value gets to zero, the better the signal. Observing the reported power on a good quality link and a bad one should give an idea about the individual range. <br />
* '''Security:''' it is not reported directly, check the line starting with {{ic|capability}}. If there is {{ic|Privacy}}, for example {{ic|capability: ESS Privacy ShortSlotTime (0x0411)}}, then the network is protected somehow.<br />
** If you see an {{ic|RSN}} information block, then the network is protected by [[Wikipedia:IEEE 802.11i-2004|Robust Security Network]] protocol, also known as WPA2.<br />
** If you see an {{ic|WPA}} information block, then the network is protected by [[Wikipedia:Wi-Fi Protected Access|Wi-Fi Protected Access]] protocol.<br />
** In the {{ic|RSN}} and {{ic|WPA}} blocks you may find the following information:<br />
*** '''Group cipher:''' value in TKIP, CCMP, both, others.<br />
*** '''Pairwise ciphers:''' value in TKIP, CCMP, both, others. Not necessarily the same value than Group cipher.<br />
*** '''Authentication suites:''' value in PSK, 802.1x, others. For home router, you will usually find PSK (''i.e.'' passphrase). In universities, you are more likely to find 802.1x suite which requires login and password. Then you will need to know which key management is in use (e.g. EAP), and what encapsulation it uses (e.g. PEAP). See [[#WPA2 Enterprise]] and [[Wikipedia:Authentication protocol]] for details.<br />
** If you see neither {{ic|RSN}} nor {{ic|WPA}} blocks but there is {{ic|Privacy}}, then WEP is used.<br />
<br />
=== Set operating mode ===<br />
<br />
You might need to set the proper operating mode of the wireless card. More specifically, if you are going to connect an [[Ad-hoc networking|ad-hoc network]], you need to set the operating mode to {{ic|ibss}}:<br />
<br />
# iw dev ''interface'' set type ibss<br />
<br />
{{Note|Changing the operating mode on some cards might require the wireless interface to be ''down'' ({{ic|ip link set ''interface'' down}}).}}<br />
<br />
=== Connect to an access point ===<br />
<br />
Depending on the encryption, you need to associate your wireless device with the access point to use and pass the encryption key:<br />
<br />
* '''No encryption''' {{bc|# iw dev ''interface'' connect "''your_essid''"}}<br />
* '''WEP'''<br />
** using a hexadecimal or ASCII key (the format is distinguished automatically, because a WEP key has a fixed length): {{bc|# iw dev ''interface'' connect "''your_essid''" key 0:''your_key''}}<br />
** using a hexadecimal or ASCII key, specifying the third set up key as default (keys are counted from zero, four are possible): {{bc|# iw dev ''interface'' connect "''your_essid''" key d:2:''your_key''}}<br />
<br />
Regardless of the method used, you can check if you have associated successfully:<br />
<br />
# iw dev ''interface'' link<br />
<br />
== Authentication ==<br />
<br />
{{Expansion|Add [[Wikipedia:WPA3|WPA3 Enterprise]] ({{Bug|65314}}) and [[Wikipedia:Opportunistic Wireless Encryption|Opportunistic Wireless Encryption (OWE) a.k.a. Enhanced Open]]. Warn against WEP and open networks.}}<br />
<br />
=== WPA2 Personal ===<br />
<br />
WPA2 Personal, a.k.a. WPA2-PSK, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
You can authenticate to WPA2 Personal networks using [[WPA supplicant]] or [[iwd]], or connect using a [[network manager]]. If you only authenticated to the network, then to have a fully functional connection you will still need to assign the IP address(es) and routes either [[Network configuration#Static IP address|manually]] or using a [[DHCP]] client.<br />
<br />
=== WPA2 Enterprise ===<br />
<br />
''WPA2 Enterprise'' is a mode of [[Wikipedia:Wi-Fi_Protected_Access|Wi-Fi Protected Access]]. It provides better security and key management than ''WPA2 Personal'', and supports other enterprise-type functionality, such as VLANs and [[wikipedia:Network Access Protection|NAP]]. However, it requires an external authentication server, called [[wikipedia:RADIUS|RADIUS]] server to handle the authentication of users. This is in contrast to Personal mode which does not require anything beyond the wireless router or access points (APs), and uses a single passphrase or password for all users.<br />
<br />
The Enterprise mode enables users to log onto the Wi-Fi network with a username and password and/or a digital certificate. Since each user has a dynamic and unique encryption key, it also helps to prevent user-to-user snooping on the wireless network, and improves encryption strength.<br />
<br />
This section describes the configuration of [[List of applications#Network managers|network clients]] to connect to a wireless access point with WPA2 Enterprise mode. See [[Software access point#RADIUS]] for information on setting up an access point itself. <br />
<br />
{{Note|Enterprise mode requires a more complex client configuration, whereas Personal mode only requires entering a passphrase when prompted. Clients likely need to install the server’s CA certificate (plus per-user certificates if using EAP-TLS), and then manually configure the wireless security and 802.1X authentication settings.}}<br />
<br />
For a comparison of protocols see the following [http://deployingradius.com/documents/protocols/compatibility.html table].<br />
<br />
{{Warning|It is possible to use WPA2 Enterprise without the client checking the server CA certificate. However, you should always seek to do so, because without authenticating the access point the connection can be subject to a man-in-the-middle attack. This may happen because while the connection handshake itself may be encrypted, the most widely used setups transmit the password itself either in plain text or the easily breakable [[#MS-CHAPv2]]. Hence, the client might send the password to a malicious access point which then proxies the connection.}}<br />
<br />
==== MS-CHAPv2 ====<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require {{Pkg|pptpclient}} in addition to the stock {{Pkg|ppp}} package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option.<br />
<br />
==== eduroam ====<br />
<br />
[[Wikipedia:eduroam|eduroam]] is an international roaming service for users in research, higher education and further education, based on WPA2 Enterprise.<br />
<br />
{{Note|<br />
* Check connection details '''first''' with your institution before applying any profiles listed in this section. Example profiles are not guaranteed to work or match any security requirements.<br />
* When storing connection profiles unencrypted, it is recommended restrict read access to the root account by specifying {{ic|chmod 600 ''profile''}} as root.<br />
}}<br />
<br />
{{Tip|Configuration for [[NetworkManager]] can be generated with the [https://cat.eduroam.org/ eduroam Configuration Assistant Tool].}}<br />
<br />
==== Manual/automatic setup ====<br />
<br />
* [[WPA supplicant#Advanced usage|WPA supplicant]] can be configured directly by its configuration file or using its CLI/GUI front ends and used in combination with a DHCP client. See the examples in {{ic|/usr/share/doc/wpa_supplicant/wpa_supplicant.conf}} for configuring the connection details.<br />
* [[NetworkManager]] can create WPA2 Enterprise profiles with ''nmcli'' or the [[NetworkManager#Front-ends|graphical front ends]]. ''nmtui'' does not support this ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/376 NetworkManager issue 376]), but may use existing profiles.<br />
* [[ConnMan]] needs a separate configuration file before [[ConnMan#Wi-Fi|connecting]] to the network. See {{man|5|connman-service.config}} and [[ConnMan#Connecting to eduroam (802.1X)]] for details.<br />
* [[netctl]] supports wpa_supplicant configuration through blocks included with {{ic|1=WPAConfigSection=}}. See {{man|5|netctl.profile}} for details.<br />
: {{Warning|Special quoting rules apply: see the {{ic|''SPECIAL QUOTING RULES''}} section in {{man|5|netctl.profile}}.}}<br />
: {{Tip|Custom certificates can be specified by adding the line {{ic|1='ca_cert="/path/to/special/certificate.cer"'}} in {{ic|WPAConfigSection}}.}}<br />
<br />
=== WPA3 Personal ===<br />
<br />
{{Expansion|Does [[iwd]] support WPA3?}}<br />
<br />
WPA3 Personal, a.k.a. WPA3-SAE, is a mode of [[Wikipedia:Wi-Fi Protected_Access|Wi-Fi Protected Access]].<br />
<br />
[[wpa_supplicant]] supports WPA3 Personal ({{ic|CONFIG_SAE}} is enabled in {{Pkg|wpa_supplicant}} since version 2:2.9-4).<br />
<br />
== Tips and tricks ==<br />
<br />
=== Respecting the regulatory domain ===<br />
<br />
The [[wikipedia:IEEE_802.11#Regulatory_domains_and_legal_compliance|regulatory domain]], or "regdomain", is used to reconfigure wireless drivers to make sure that wireless hardware usage complies with local laws set by the FCC, ETSI and other organizations. Regdomains use [[wikipedia:ISO_3166-1_alpha-2|ISO 3166-1 alpha-2 country codes]]. For example, the regdomain of the United States would be "US", China would be "CN", etc.<br />
<br />
Regdomains affect the availability of wireless channels. In the 2.4GHz band, the allowed channels are 1-11 for the US, 1-14 for Japan, and 1-13 for most of the rest of the world. In the 5GHz band, the rules for allowed channels are much more complex. In either case, consult [[wikipedia:List_of_WLAN_channels|this list of WLAN channels]] for more detailed information.<br />
<br />
Regdomains also affect the limit on the [[wikipedia:Equivalent_isotropically_radiated_power|effective isotropic radiated power (EIRP)]] from wireless devices. This is derived from transmit power/"tx power", and is measured in [[wikipedia:DBm|dBm/mBm (1dBm=100mBm) or mW (log scale)]]. In the 2.4GHz band, the maximum is 30dBm in the US and Canada, 20dBm in most of Europe, and 20dBm-30dBm for the rest of the world. In the 5GHz band, maximums are usually lower. Consult the [http://git.kernel.org/cgit/linux/kernel/git/linville/wireless-regdb.git/tree/db.txt wireless-regdb] for more detailed information (EIRP dBm values are in the second set of brackets for each line).<br />
<br />
Misconfiguring the regdomain can be useful - for example, by allowing use of an unused channel when other channels are crowded, or by allowing an increase in tx power to widen transmitter range. However, '''this is not recommended''' as it could break local laws and cause interference with other radio devices.<br />
<br />
To configure the regdomain, install {{Pkg|crda}} and reboot (to reload the {{ic|cfg80211}} module and all related drivers). Check the boot log to make sure that CRDA is being called by {{ic|cfg80211}}:<br />
<br />
$ dmesg | grep cfg80211<br />
<br />
The current regdomain can be set to the United States with:<br />
<br />
# iw reg set US<br />
<br />
And queried with:<br />
<br />
$ iw reg get<br />
<br />
{{Note|<br />
* Your device may be set to country "00", which is the "world regulatory domain" and contains generic settings. If this cannot be unset, CRDA may be misconfigured.<br />
* According to [https://git.kernel.org/pub/scm/linux/kernel/git/mcgrof/crda.git/tree/README CRDA's README], it is no longer needed since kernel v4.15 as kernel will automatically load regulatory database from firmware. However [https://bugs.gentoo.org/462032#c17 it is also said] specific kernel setup is needed for the loading to work.<br />
}}<br />
<br />
However, setting the regdomain may not alter your settings. Some devices have a regdomain set in firmware/EEPROM, which dictates the limits of the device, meaning that setting regdomain in software [http://wiki.openwrt.org/doc/howto/wireless.utilities#iw can only increase restrictions], not decrease them. For example, a CN device could be set in software to the US regdomain, but because CN has an EIRP maximum of 20dBm, the device will not be able to transmit at the US maximum of 30dBm.<br />
<br />
For example, to see if the regdomain is being set in firmware for an Atheros device:<br />
<br />
$ dmesg | grep ath:<br />
<br />
For other chipsets, it may help to search for "EEPROM", "regdomain", or simply the name of the device driver.<br />
<br />
To see if your regdomain change has been successful, and to query the number of available channels and their allowed transmit power:<br />
<br />
$ iw list | grep -A 15 Frequencies:<br />
<br />
A more permanent configuration of the regdomain can be achieved through editing {{ic|/etc/conf.d/wireless-regdom}} and uncommenting the appropriate domain.<br />
<br />
[[WPA supplicant]] can also use a regdomain in the {{ic|1=country=}} line of {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.<br />
<br />
It is also possible to configure the [https://wireless.wiki.kernel.org/en/developers/documentation/cfg80211 cfg80211] kernel module to use a specific regdomain by adding, for example, {{ic|1=options cfg80211 ieee80211_regdom=EU}} as [[Kernel_modules#Setting module options|module options]]. However, this is part of the [https://wireless.wiki.kernel.org/en/developers/regulatory#the_ieee80211_regdom_module_parameter old regulatory implementation].<br />
<br />
For further information, read the [https://wireless.wiki.kernel.org/en/developers/regulatory kernel.org regulatory documentation].<br />
<br />
=== Rfkill caveat ===<br />
<br />
Many laptops have a hardware button (or switch) to turn off wireless card, however, the card can also be blocked by kernel. This can be handled by ''rfkill''. To show the current status:<br />
<br />
{{hc|# rfkill list|<br />
0: phy0: Wireless LAN<br />
Soft blocked: yes<br />
Hard blocked: yes<br />
}}<br />
<br />
If the card is ''hard-blocked'', use the hardware button (switch) to unblock it. If the card is not ''hard-blocked'' but ''soft-blocked'', use the following command:<br />
<br />
# rfkill unblock wifi<br />
<br />
{{Note|It is possible that the card will go from ''hard-blocked'' and ''soft-unblocked'' state into ''hard-unblocked'' and ''soft-blocked'' state by pressing the hardware button (i.e. the ''soft-blocked'' bit is just switched no matter what). This can be adjusted by tuning some options of the {{ic|rfkill}} [[kernel module]].}}<br />
<br />
Hardware buttons to toggle wireless cards are handled by a vendor specific [[kernel module]], frequently these are [https://lwn.net/Articles/391230/ WMI] modules. Particularly for very new hardware models, it happens that the model is not fully supported in the latest stable kernel yet. In this case it often helps to search the kernel bug tracker for information and report the model to the maintainer of the respective vendor kernel module, if it has not happened already. <br />
<br />
See also [http://askubuntu.com/questions/62166/siocsifflags-operation-not-possible-due-to-rf-kill].<br />
<br />
=== Power saving ===<br />
<br />
See [[Power saving#Network interfaces]].<br />
<br />
== Troubleshooting ==<br />
<br />
This section contains general troubleshooting tips, not strictly related to problems with drivers or firmware. For such topics, see next section [[#Troubleshooting drivers and firmware]].<br />
<br />
=== Temporary internet access ===<br />
<br />
If you have problematic hardware and need internet access to, for example, download some software or get help in forums, you can make use of Android's built-in feature for internet sharing via USB cable. See [[Android tethering#USB tethering]] for more information.<br />
<br />
=== Observing Logs ===<br />
<br />
A good first measure to troubleshoot is to analyze the system's logfiles first. In order not to manually parse through them all, it can help to open a second terminal/console window and watch the kernels messages with <br />
$ dmesg -w<br />
while performing the action, e.g. the wireless association attempt. <br />
<br />
When using a tool for network management, the same can be done for systemd with <br />
# journalctl -f <br />
<br />
Frequently a wireless error is accompanied by a deauthentication with a particular reason code, for example: <br />
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)<br />
<br />
Looking up [http://www.aboutcher.co.uk/2012/07/linux-wifi-deauthenticated-reason-codes/ the reason code] might give a first hint. Maybe it also helps you to look at the control message [https://wireless.wiki.kernel.org/en/developers/documentation/mac80211/auth-assoc-deauth flowchart], the journal messages will follow it. <br />
<br />
The individual tools used in this article further provide options for more detailed debugging output, which can be used in a second step of the analysis, if required.<br />
<br />
=== Failed to get IP address ===<br />
<br />
* If getting an IP address repeatedly fails using the default {{Pkg|dhcpcd}} client, try installing and using {{Pkg|dhclient}} instead. Do not forget to select ''dhclient'' as the primary DHCP client in the [[#Manual/automatic setup|connection manager]].<br />
<br />
* If you can get an IP address for a wired interface and not for a wireless interface, try disabling the wireless card's [[#Power saving|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
* If you get a timeout error due to a ''waiting for carrier'' problem, then you might have to set the channel mode to {{ic|auto}} for the specific device:<br />
<br />
# iwconfig wlan0 channel auto<br />
<br />
Before changing the channel to auto, make sure your wireless interface is down. After it has successfully changed it, you can bring the interface up again and continue from there.<br />
<br />
=== Valid IP address but cannot resolve host ===<br />
<br />
If you are on a public wireless network that may have a [[wikipedia:Captive_portal|captive portal]], make sure to query an HTTP page (not an HTTPS page) from your web browser, as some captive portals only redirect HTTP.<br />
If this is not the issue, [[check if you can resolve domain names]], it may be necessary to use the DNS server advertised via DHCP.<br />
<br />
=== Setting RTS and fragmentation thresholds ===<br />
<br />
Wireless hardware disables RTS and fragmentation by default. These are two different methods of increasing throughput at the expense of bandwidth (i.e. reliability at the expense of speed). These are useful in environments with wireless noise or many adjacent access points, which may create interference leading to timeouts or failing connections. <br />
<br />
Packet fragmentation improves throughput by splitting up packets with size exceeding the fragmentation threshold. The maximum value (2346) effectively disables fragmentation since no packet can exceed it. The minimum value (256) maximizes throughput, but may carry a significant bandwidth cost.<br />
<br />
# iw phy0 set frag 512<br />
<br />
[[Wikipedia:IEEE 802.11 RTS/CTS|RTS]] improves throughput by performing a handshake with the access point before transmitting packets with size exceeding the RTS threshold. The maximum threshold (2347) effectively disables RTS since no packet can exceed it. The minimum threshold (0) enables RTS for all packets, which is probably excessive for most situations.<br />
<br />
# iw phy0 set rts 500<br />
<br />
{{Note|{{ic|phy0}} is the name of the wireless device as listed by {{ic|$ iw phy}}.}}<br />
<br />
=== Random disconnections ===<br />
<br />
==== Cause #1 ====<br />
<br />
If dmesg says {{ic|1=wlan0: deauthenticating from MAC by local choice (reason=3)}} and you lose your Wi-Fi connection, it is likely that you have a bit too aggressive power-saving on your Wi-Fi card. Try disabling the wireless card's [[Power_management#Network_interfaces|power saving]] features (specify {{ic|off}} instead of {{ic|on}}).<br />
<br />
If your card does not support enabling/disabling power save mode, check the BIOS for power management options. Disabling PCI-Express power management in the BIOS of a Lenovo W520 resolved this issue.<br />
<br />
==== Cause #2 ====<br />
<br />
If you are experiencing frequent disconnections and dmesg shows messages such as <br />
<br />
{{ic|1=ieee80211 phy0: wlan0: No probe response from AP xx:xx:xx:xx:xx:xx after 500ms, disconnecting}}<br />
<br />
try changing the channel bandwidth to {{ic|20MHz}} through your router's settings page.<br />
<br />
==== Cause #3 ====<br />
<br />
On some laptop models with hardware rfkill switches (e.g., Thinkpad X200 series), due to wear or bad design, the switch (or its connection to the mainboard) might become loose over time resulting in seemingly random hardblocks/disconnects when you accidentally touch the switch or move the laptop.<br />
There is no software solution to this, unless your switch is electrical and the BIOS offers the option to disable the switch.<br />
If your switch is mechanical (most are), there are lots of possible solutions, most of which aim to disable the switch: Soldering the contact point on the mainboard/wifi-card, glueing or blocking the switch, using a screw nut to tighten the switch or removing it altogether.<br />
<br />
==== Cause #4 ====<br />
<br />
Another cause for frequent disconnects or a complete failure to connect may also be a sub-standard router, incomplete settings of the router, or interference by other wireless devices. <br />
<br />
To troubleshoot, first best try to connect to the router with no authentication. <br />
<br />
If that works, enable WPA/WPA2 again but choose fixed and/or limited router settings. For example: <br />
* If the router is considerably older than the wireless device you use for the client, test if it works with setting the router to one wireless mode <br />
* Disable mixed-mode authentication (e.g. only WPA2 with AES, or TKIP if the router is old) <br />
* Try a fixed/free channel rather than "auto" channel (maybe the router next door is old and interfering) <br />
* Disable [[Wikipedia:Wi-Fi Protected Setup|WPS]]<br />
* Disable {{ic|40MHz}} channel bandwidth (lower throughput but less likely collisions) <br />
* If the router has quality of service settings, check completeness of settings (e.g. Wi-Fi Multimedia (WMM) is part of optional QoS flow control. An erroneous router firmware may advertise its existence although the setting is not enabled)<br />
<br />
=== Wi-Fi networks invisible because of incorrect regulatory domain===<br />
<br />
If the computer's Wi-Fi channels do not match those of the user's country, some in-range Wi-Fi networks might be invisible, because they use wireless channels that are not allowed by default. The solution is to configure the regulatory domain correctly, see [[#Respecting the regulatory domain]].<br />
<br />
== Troubleshooting drivers and firmware ==<br />
<br />
This section covers methods and procedures for installing kernel modules and ''firmware'' for specific chipsets, that differ from generic method.<br />
<br />
See [[Kernel modules]] for general information on operations with modules.<br />
<br />
=== Ralink/Mediatek ===<br />
<br />
==== rt2x00 ====<br />
<br />
Unified driver for Ralink chipsets (it replaces {{ic|rt2500}}, {{ic|rt61}}, {{ic|rt73}}, etc). This driver has been in the Linux kernel since 2.6.24, you only need to load the right module for the chip: {{ic|rt2400pci}}, {{ic|rt2500pci}}, {{ic|rt2500usb}}, {{ic|rt61pci}} or {{ic|rt73usb}} which will autoload the respective {{ic|rt2x00}} modules too.<br />
<br />
A list of devices supported by the modules is available at the project's [https://web.archive.org/web/20150507023412/http://rt2x00.serialmonkey.com/wiki/index.php/Hardware homepage].<br />
<br />
; Additional notes<br />
* Since kernel 3.0, rt2x00 includes also these drivers: {{ic|rt2800pci}}, {{ic|rt2800usb}}.<br />
* Since kernel 3.0, the staging drivers {{ic|rt2860sta}} and {{ic|rt2870sta}} are replaced by the mainline drivers {{ic|rt2800pci}} and {{ic|rt2800usb}} [https://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commitdiff;h=fefecc6989b4b24276797270c0e229c07be02ad3].<br />
* Some devices have a wide range of options that can be configured with {{ic|iwpriv}}. These are documented in the [http://web.ralinktech.com/ralink/Home/Support/Linux.html source tarballs]{{Dead link|2018|08|15}} available from Ralink.<br />
<br />
==== rt3090 ====<br />
<br />
For devices which are using the rt3090 chipset it should be possible to use {{ic|rt2800pci}} driver, however, is not working with this chipset very well (e.g. sometimes it is not possible to use higher rate than 2Mb/s).<br />
<br />
==== rt3290 ====<br />
<br />
The rt3290 chipset is recognised by the kernel {{ic|rt2800pci}} module. However, some users experience problems and reverting to a patched Ralink driver seems to be beneficial in these [https://bbs.archlinux.org/viewtopic.php?id=161952 cases].<br />
<br />
==== rt3573 ====<br />
<br />
New chipset as of 2012. It may require proprietary drivers from Ralink. Different manufacturers use it, see the [https://bbs.archlinux.org/viewtopic.php?pid=1164228#p1164228 Belkin N750 DB wireless usb adapter] forums thread.<br />
<br />
==== mt7612u ====<br />
<br />
New chipset as of 2014, released under their new commercial name Mediatek. It is an AC1200 or AC1300 chipset. Manufacturer provides drivers for Linux on their [https://www.mediatek.com/products/broadbandWifi/mt7612u support page]<br />
As of kernel 5.5 it should be supported by the included mt76 driver.<br />
<br />
=== Realtek ===<br />
<br />
See [https://wikidevi.com/wiki/Realtek] for a list of Realtek chipsets and specifications.<br />
<br />
==== rtl8192cu ====<br />
<br />
The driver is now in the kernel, but many users have reported being unable to make a connection although scanning for networks does work.<br />
<br />
{{AUR|8192cu-dkms}} includes many patches, try this if it does not work fine with the driver in kernel.<br />
<br />
==== rtl8723ae/rtl8723be ====<br />
<br />
The {{ic|rtl8723ae}} and {{ic|rtl8723be}} modules are included in the mainline Linux kernel.<br />
<br />
Some users may encounter errors with powersave on this card. This is shown with occasional disconnects that are not recognized by high level network managers ([[netctl]], [[NetworkManager]]). This error can be confirmed by running {{ic|dmesg -w}} or {{ic|journalctl -f}} and looking for output related to powersave and the {{ic|rtl8723ae}}/{{ic|rtl8723be}} module. If you are having this issue, use the {{ic|1=fwlps=0}} kernel option, which should prevent the WiFi card from automatically sleeping and halting connection.<br />
<br />
{{hc|/etc/modprobe.d/rtl8723ae.conf|2=<br />
options rtl8723ae fwlps=0<br />
}}<br />
or<br />
{{hc|/etc/modprobe.d/rtl8723be.conf|2=<br />
options rtl8723be fwlps=0<br />
}}<br />
<br />
If you have poor signal, perhaps your device has only one physical antenna connected, and antenna autoselection is broken. You can force the choice of antenna with {{ic|1=ant_sel=1}} or {{ic|1=ant_sel=2}} kernel option. [https://bbs.archlinux.org/viewtopic.php?id=208472]<br />
<br />
==== rtl88xxau ====<br />
<br />
Realtek chipsets rtl8811au/rtl8812au/rtl8814au/rtl8821au designed for various USB adapters ranging from AC600 to AC1900.<br />
<br />
Several packages provide various kernel drivers:<br />
<br />
{| class="wikitable"<br />
! Chipset || Driver version || Package || Notes<br />
|-<br />
| rtl8811au, rtl8812au, rtl8814au and rtl8821au || 5.6.4.1 || {{AUR|rtl88xxau-aircrack-dkms-git}} || Aircrack-ng kernel module for 8811au, 8812au, 8814au and 8821au chipsets with monitor mode and injection support.<br />
|-<br />
| rtl8812au || 5.2.20 || {{AUR|rtl8812au-dkms-git}} || Latest official Realtek driver version for rtl8812au ''only''.<br />
|-<br />
| rtl8811au, rtl8812au and rtl8821au || 5.1.5 || {{AUR|rtl8821au-dkms-git}} || For rtl8812au versions 5.6.4.1 or 5.2.20 are recommended instead.<br />
|-<br />
| rtl8814au || 4.3.21 || {{AUR|rtl8814au-dkms-git}} || Possibly works for rtl8813au too. Reportedly has better performance than {{AUR|rtl88xxau-aircrack-dkms-git}}<br />
|}<br />
<br />
These require [[DKMS]] so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8811cu/rtl8821cu ====<br />
<br />
{{AUR|rtl8821cu-dkms-git}} provides a kernel module for the Realtek 8811cu and 8821cu chipset.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8821ce ====<br />
<br />
{{AUR|rtl8821ce-dkms-git}} provides a kernel module for the Realtek 8821ce chipset found in the Asus X543UA.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8822bu ====<br />
<br />
{{AUR|rtl8822bu-dkms-git}} or {{AUR|rtl88x2bu-dkms-git}} provides a kernel module for the Realtek 8822bu chipset found in the Edimax EW7822ULC USB3, Asus AC53 Nano USB 802.11ac and TP-Link Archer T3U adapter.<br />
<br />
This requires [[DKMS]], so make sure you have your proper kernel headers installed.<br />
<br />
==== rtl8xxxu ====<br />
<br />
{{Expansion|Specific issues with the mainline module and kernel versions should be stated.}}<br />
<br />
Issues with the {{ic|rtl8xxxu}} mainline kernel module may be solved by compiling a third-party module for the specific chipset. The source code can be found in [https://github.com/lwfinger?tab=repositories GitHub repositories].<br />
<br />
Some drivers may be already prepared in the AUR, e.g. {{AUR|rtl8723bu-git-dkms}}.<br />
<br />
=== Atheros ===<br />
<br />
The [http://madwifi-project.org/ MadWifi team] currently maintains three different drivers for devices with Atheros chipset:<br />
<br />
* {{ic|madwifi}} is an old, obsolete driver. Not present in Arch kernel since 2.6.39.1<sup>[https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html]</sup>.<br />
* {{ic|ath5k}} is newer driver, which replaces the {{ic|madwifi}} driver. Currently a better choice for some chipsets, but not all chipsets are supported (see below)<br />
* {{ic|ath9k}} is the newest of these three drivers, it is intended for newer Atheros chipsets. All of the chips with 802.11n capabilities are supported.<br />
<br />
There are some other drivers for some Atheros devices. See [https://wireless.wiki.kernel.org/en/users/Drivers/Atheros#pcipci-eahb_driversrs Linux Wireless documentation] for details.<br />
<br />
==== ath5k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath5k<br />
* https://wiki.debian.org/ath5k<br />
<br />
If you find web pages randomly loading very slow, or if the device is unable to lease an IP address, try to switch from hardware to software encryption by loading the {{ic|ath5k}} module with {{ic|1=nohwcrypt=1}} option. See [[Kernel modules#Setting module options]] for details.<br />
<br />
Some laptops may have problems with their wireless LED indicator flickering red and blue. To solve this problem, do:<br />
<br />
# echo none > /sys/class/leds/ath5k-phy0::tx/trigger<br />
# echo none > /sys/class/leds/ath5k-phy0::rx/trigger<br />
<br />
For alternatives, see [https://bugzilla.redhat.com/show_bug.cgi?id=618232 this bug report].<br />
<br />
==== ath9k ====<br />
<br />
External resources:<br />
* https://wireless.wiki.kernel.org/en/users/drivers/ath9k<br />
* https://wiki.debian.org/ath9k<br />
<br />
As of Linux 3.15.1, some users have been experiencing a decrease in bandwidth. In some cases this can fixed by editing {{ic|/etc/modprobe.d/ath9k.conf}} and adding the line:<br />
options ath9k nohwcrypt=1<br />
<br />
{{Note|Check with the command lsmod what module(-name) is in use and change it if named otherwise (e.g. ath9k_htc).}}<br />
<br />
In the unlikely event that you have stability issues that trouble you, you could try using the {{AUR|backports-patched}} package. An [http://lists.ath9k.org/mailman/listinfo/ath9k-devel ath9k mailing list]{{Dead link|2020|04|01|status=SSL error}} exists for support and development related discussions.<br />
<br />
===== Power saving =====<br />
<br />
Although [https://wireless.wiki.kernel.org/en/users/Documentation/dynamic-power-save Linux Wireless] says that dynamic power saving is enabled for Atheros ath9k single-chips newer than AR9280, for some devices (e.g. AR9285) {{Pkg|powertop}} might still report that power saving is disabled. In this case enable it manually.<br />
<br />
On some devices (e.g. AR9285), enabling the power saving might result in the following error:<br />
<br />
{{hc|# iw dev wlan0 set power_save on|<br />
command failed: Operation not supported (-95)<br />
}}<br />
<br />
The solution is to set the {{ic|1=ps_enable=1}} option for the {{ic|ath9k}} module:<br />
<br />
{{hc|/etc/modprobe.d/ath9k.conf|2=<br />
options ath9k ps_enable=1<br />
}}<br />
<br />
=== Intel ===<br />
<br />
==== ipw2100 and ipw2200 ====<br />
<br />
These modules are fully supported in the kernel, but they require additional firmware. Depending on which of the chipsets you have, [[install]] either {{Pkg|ipw2100-fw}} or {{Pkg|ipw2200-fw}}. Then [[Kernel modules#Manual module handling|reload]] the appropriate module.<br />
<br />
{{Tip|You may use the following [[Kernel modules#Setting module options|module options]]:<br />
* use the {{ic|1=rtap_iface=1}} option to enable the radiotap interface<br />
* use the {{ic|1=led=1}} option to enable a front LED indicating when the wireless is connected or not<br />
}}<br />
<br />
==== iwlegacy ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/Drivers/iwlegacy iwlegacy] is the wireless driver for Intel's 3945 and 4965 wireless chips. The firmware is included in the {{Pkg|linux-firmware}} package.<br />
<br />
[[udev]] should load the driver automatically, otherwise load {{ic|iwl3945}} or {{ic|iwl4965}} manually. See [[Kernel modules]] for details.<br />
<br />
If you have problems connecting to networks in general, random failures with your card on bootup or your link quality is very poor, try to disable 802.11n:<br />
<br />
{{hc|/etc/modprobe.d/iwl4965.conf|2=<br />
options iwl4965 11n_disable=1<br />
}}<br />
<br />
If the failures persist during bootup and you are using Nouveau driver, try [[Nouveau#Enable_early_KMS|enabling early KMS]] to prevent the conflict [https://bbs.archlinux.org/viewtopic.php?pid=1748667#p1748667].<br />
<br />
==== iwlwifi ====<br />
<br />
[https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi iwlwifi] is the wireless driver for Intel's current wireless chips, such as 5100AGN, 5300AGN, and 5350AGN. See the [https://wireless.wiki.kernel.org/en/users/drivers/iwlwifi#supported_devices full list of supported devices]. The firmware is included in the {{Pkg|linux-firmware}} package. The {{Aur|linux-firmware-iwlwifi-git}} may contain some updates sooner.<br />
<br />
If you have problems connecting to networks in general or your link quality is very poor, try to disable 802.11n, and perhaps also enable software encryption:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=1 swcrypto=1<br />
}}<br />
<br />
If you have a problem with slow uplink speed in 802.11n mode, for example 20Mbps, try to enable antenna aggregation:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi 11n_disable=8<br />
}}<br />
<br />
Do not be confused with the option name, when the value is set to {{ic|8}} it does not disable anything but re-enables transmission antenna aggregation.[http://forums.gentoo.org/viewtopic-t-996692.html?sid=81bdfa435c089360bdfd9368fe0339a9] [https://bugzilla.kernel.org/show_bug.cgi?id=81571]<br />
<br />
In case this does not work for you, you may try disabling [[Power saving#Network interfaces|power saving]] for your wireless adapter.<br />
<br />
[http://ubuntuforums.org/showthread.php?t=2183486&p=12845473#post12845473 Some] have never gotten this to work. [http://ubuntuforums.org/showthread.php?t=2205733&p=12935783#post12935783 Others] found salvation by disabling N in their router settings after trying everything. This is known to have be the only solution on more than one occasion. The second link there mentions a 5ghz option that might be worth exploring.<br />
<br />
If your router only supports modes up to 802.11n, using 11n_disable=0 will limit your download and upload speeds at ~20Mbps (802.11g limit). If you need more than that and your card supports 802.11ac and/or 802.11ax modes (e.g. Intel® Wi-Fi 6 AX200 160MHz), consider replacing your router with the one that also supports 802.11ac and/or 802.11ax.<br />
<br />
===== Bluetooth coexistence =====<br />
<br />
If you have difficulty connecting a bluetooth headset and maintaining good downlink speed, try disabling bluetooth coexistence [https://wireless.wiki.kernel.org/en/users/Drivers/iwlwifi#wi-fibluetooth_coexistence]:<br />
<br />
{{hc|/etc/modprobe.d/iwlwifi.conf|2=<br />
options iwlwifi bt_coex_active=0<br />
}}<br />
<br />
===== Firmware stack traces =====<br />
<br />
{{Accuracy|What is the last note about ignored packages trying to say?}}<br />
<br />
You may have some issue where the driver outputs stack traces & errors, which can cause some stuttering.<br />
<br />
{{hc|dmesg|2=<br />
Microcode SW error detected. Restarting 0x2000000.<br />
}}<br />
<br />
To fix those errors, you may downgrade the package {{Pkg|linux-firmware}} or rename the last version of the firmware used by your device so that an older version is loaded (which keeps it out of pacman's ignored packages).<br />
<br />
==== Disabling LED blink ====<br />
<br />
{{Note|This works with the {{ic|iwlegacy}} and {{ic|iwlwifi}} drivers.}}<br />
<br />
The default settings on the module are to have the LED blink on activity. Some people find this extremely annoying. To have the LED on solid when Wi-Fi is active, you can use the [[systemd#Temporary files|systemd-tmpfiles]]:<br />
<br />
{{hc|/etc/tmpfiles.d/phy0-led.conf|<br />
w /sys/class/leds/phy0-led/trigger - - - - phy0radio<br />
}}<br />
<br />
Run {{ic|systemd-tmpfiles --create phy0-led.conf}} for the change to take effect, or reboot.<br />
<br />
To see all the possible trigger values for this LED:<br />
<br />
# cat /sys/class/leds/phy0-led/trigger<br />
<br />
{{Tip|If you do not have {{ic|/sys/class/leds/phy0-led}}, you may try to use the {{ic|1=led_mode="1"}} [[Kernel modules#Setting module options|module option]]. It should be valid for both {{ic|iwlwifi}} and {{ic|iwlegacy}} drivers.}}<br />
<br />
=== Broadcom ===<br />
<br />
See [[Broadcom wireless]].<br />
<br />
=== Other drivers/devices ===<br />
<br />
==== Tenda w322u ====<br />
<br />
Treat this Tenda card as an {{ic|rt2870sta}} device. See [[#rt2x00]].<br />
<br />
==== orinoco ====<br />
<br />
This should be a part of the kernel package and be installed already.<br />
<br />
Some Orinoco chipsets are Hermes II. You can use the {{ic|wlags49_h2_cs}} driver instead of {{ic|orinoco_cs}} and gain WPA support. To use the driver, [[blacklist]] {{ic|orinoco_cs}} first.<br />
<br />
==== prism54 ====<br />
<br />
The driver {{ic|p54}} is included in kernel, but you have to download the appropriate firmware for your card from [https://wireless.wiki.kernel.org/en/users/drivers/p54#firmware this site] and install it into the {{ic|/usr/lib/firmware}} directory.<br />
<br />
{{Note|There is also older, deprecated driver {{ic|prism54}}, which might conflict with the newer driver ({{ic|p54pci}} or {{ic|p54usb}}). Make sure to [[blacklist]] {{ic|prism54}}.}}<br />
<br />
==== ACX100/111 ====<br />
<br />
{{Warning|The drivers for these devices [https://mailman.archlinux.org/pipermail/arch-dev-public/2011-June/020669.html are broken] and do not work with newer kernel versions.}}<br />
<br />
Packages: {{ic|tiacx}} {{ic|tiacx-firmware}} (deleted from official repositories and AUR)<br />
<br />
See [https://sourceforge.net/projects/acx100/ official page] for details.<br />
<br />
==== zd1211rw ====<br />
<br />
[https://sourceforge.net/projects/zd1211/ zd1211rw] is a driver for the ZyDAS ZD1211 802.11b/g USB WLAN chipset, and it is included in recent versions of the Linux kernel. See [http://www.linuxwireless.org/en/users/Drivers/zd1211rw/devices] for a list of supported devices. You only need to [[install]] the firmware for the device, provided by the {{AUR|zd1211-firmware}} package.<br />
<br />
==== hostap_cs ====<br />
<br />
[http://hostap.epitest.fi/ Host AP] is a Linux driver for wireless LAN cards based on Intersil's Prism2/2.5/3 chipset. The driver is included in Linux kernel.<br />
<br />
{{Note|Make sure to [[blacklist]] the {{ic|orinico_cs}} driver, it may cause problems.}}<br />
<br />
=== ndiswrapper ===<br />
<br />
Ndiswrapper is a wrapper script that allows you to use some Windows drivers in Linux. You will need the {{ic|.inf}} and {{ic|.sys}} files from your Windows driver. <br />
{{Warning|Be sure to use drivers appropriate to your architecture (x86 vs. x86_64).}}<br />
<br />
{{Tip|If you need to extract these files from an {{ic|*.exe}} file, you can use {{Pkg|cabextract}}.}}<br />
<br />
Follow these steps to configure ndiswrapper.<br />
<br />
1. Install {{pkg|ndiswrapper-dkms}}<br />
<br />
2. Install the driver to {{ic|/etc/ndiswrapper/*}}<br />
# ndiswrapper -i filename.inf<br />
<br />
3. List all installed drivers for ndiswrapper<br />
$ ndiswrapper -l<br />
<br />
4. Let ndiswrapper write its configuration in {{ic|/etc/modprobe.d/ndiswrapper.conf}}:<br />
# ndiswrapper -m<br />
# depmod -a<br />
<br />
Now the ndiswrapper install is almost finished; follow the instructions on [[Kernel modules#Automatic module loading with systemd]] to automatically load the module at boot.<br />
<br />
The important part is making sure that ndiswrapper exists on this line, so just add it alongside the other modules. It would be best to test that ndiswrapper will load now, so:<br />
# modprobe ndiswrapper<br />
# iwconfig<br />
<br />
and ''wlan0'' should now exist. If you have problems, some help is available at:<br />
[http://sourceforge.net/p/ndiswrapper/ndiswrapper/HowTos/ ndiswrapper howto] and [http://sourceforge.net/p/ndiswrapper/ndiswrapper/FAQ/ ndiswrapper FAQ].<br />
<br />
=== backports-patched ===<br />
<br />
{{AUR|backports-patched}} provide drivers released on newer kernels backported for usage on older kernels. The project started since 2007 and was originally known as compat-wireless, evolved to compat-drivers and was recently renamed simply to backports. <br />
<br />
If you are using old kernel and have wireless issue, drivers in this package may help.<br />
<br />
== See also ==<br />
<br />
* [https://wireless.wiki.kernel.org/ The Linux Wireless project]<br />
* [http://aircrack-ng.org/doku.php?id=install_drivers Aircrack-ng guide on installing drivers]</div>Progandyhttps://wiki.archlinux.org/index.php?title=NetworkManager&diff=622090NetworkManager2020-06-26T06:57:09Z<p>Progandy: /* Appindicator */ Appindicator is compiled in since 1.18.0</p>
<hr />
<div>[[Category:Network managers]]<br />
[[Category:Red Hat]]<br />
[[cs:NetworkManager]]<br />
[[de:Networkmanager]]<br />
[[es:NetworkManager]]<br />
[[fr:NetworkManager]]<br />
[[it:NetworkManager]]<br />
[[ja:NetworkManager]]<br />
[[pt:NetworkManager]]<br />
[[zh-hans:NetworkManager]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related articles end}}<br />
[https://wiki.gnome.org/Projects/NetworkManager/ NetworkManager] is a program for providing detection and configuration for systems to automatically connect to networks. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the [[GNOME]] project.<br />
<br />
{{Expansion|Clear text storage of secrets is not limited to just Wi-Fi passwords. The secrets are stored in files (and folder) only accesible to root.}}<br />
<br />
{{Warning|By default, Wi-Fi passwords are stored in clear text, see [[#Encrypted Wi-Fi passwords]].}}<br />
<br />
== Installation ==<br />
<br />
NetworkManager can be [[install]]ed with the package {{Pkg|networkmanager}}, which contains a daemon, a command line interface ({{ic|nmcli}}) and a curses‐based interface ({{ic|nmtui}}). <br />
<br />
=== Enable NetworkManager ===<br />
<br />
After installation, you should [[start/enable]] {{ic|NetworkManager.service}}. Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need ''nmcli'' or an applet to configure and connect.<br />
<br />
=== Additional interfaces ===<br />
<br />
* {{Pkg|nm-connection-editor}} for a graphical user interface,<br />
* {{Pkg|network-manager-applet}} for a system tray applet ({{ic|nm-applet}}).<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. See [[#Configuration]] to enable the NetworkManager service.}}<br />
<br />
=== Mobile broadband support ===<br />
<br />
[[Install]] {{Pkg|modemmanager}}, {{Pkg|mobile-broadband-provider-info}} and {{Pkg|usb_modeswitch}} packages for mobile broadband connection support. See [[USB 3G Modem#NetworkManager]] for details.<br />
<br />
=== PPPoE / DSL support ===<br />
<br />
[[Install]] {{Pkg|rp-pppoe}} package for PPPoE / DSL connection support. To actually add PPPoE connection, use {{ic|1=nm-connection-editor}} and add new DSL/PPPoE connection.<br />
<br />
=== VPN support ===<br />
<br />
NetworkManager since version 1.16 has native support for [[WireGuard]], all it needs is the {{ic|wireguard}} kernel module. Read the [https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager blog post] for details.<br />
<br />
Support for other VPN types is based on a plug-in system. They are provided in the following packages:<br />
<br />
* {{Pkg|networkmanager-openconnect}} for [[OpenConnect]]<br />
* [[networkmanager-openvpn]] for [[OpenVPN]]<br />
* {{Pkg|networkmanager-pptp}} for [[PPTP Client]]<br />
* {{Pkg|networkmanager-vpnc}} for [[Vpnc]]<br />
* {{Pkg|networkmanager-strongswan}} for [[strongSwan]]<br />
* {{AUR|networkmanager-fortisslvpn-git}}<br />
* {{AUR|networkmanager-iodine-git}}<br />
* {{AUR|networkmanager-libreswan}}<br />
* {{AUR|networkmanager-l2tp}}<br />
* {{AUR|networkmanager-ssh-git}}<br />
* {{Pkg|network-manager-sstp}}<br />
<br />
{{Warning|1=There are a lot of [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues?search=VPN&state=opened bugs] (and [https://bugzilla.gnome.org/buglist.cgi?bug_status=__open__&content=VPN&product=NetworkManager old bugs]) related to VPN support. Check the daemon processes options set via the GUI correctly and double-check with each package release.}}<br />
<br />
{{Note|To have fully functioning DNS resolution when using VPN, you should set up [[#DNS caching and conditional forwarding|conditional forwarding]].}}<br />
<br />
== Usage ==<br />
<br />
NetworkManager comes with {{man|1|nmcli}} and {{man|1|nmtui}}.<br />
<br />
=== nmcli examples ===<br />
<br />
List nearby wifi networks:<br />
<br />
$ nmcli device wifi list<br />
<br />
Connect to a wifi network:<br />
<br />
$ nmcli device wifi connect ''SSID'' password ''password''<br />
<br />
Connect to a hidden network:<br />
<br />
$ nmcli device wifi connect ''SSID'' password ''password'' hidden yes<br />
<br />
Connect to a wifi on the {{ic|wlan1}} wifi interface:<br />
<br />
$ nmcli device wifi connect ''SSID'' password ''password'' ifname wlan1 ''profile_name''<br />
<br />
Disconnect an interface:<br />
<br />
$ nmcli device disconnect ifname eth0<br />
<br />
Reconnect an interface marked as disconnected:<br />
<br />
$ nmcli connection up uuid ''UUID''<br />
<br />
Get a list of UUIDs:<br />
<br />
$ nmcli connection show<br />
<br />
See a list of network devices and their state:<br />
<br />
$ nmcli device<br />
<br />
Turn off wifi:<br />
<br />
$ nmcli radio wifi off<br />
<br />
=== Edit a connection ===<br />
<br />
For a comprehensive list of settings, see {{man|5|nm-settings}}.<br />
<br />
Firstly you need to get list of connections:<br />
<br />
{{hc|$ nmcli connection|<nowiki><br />
NAME UUID TYPE DEVICE<br />
Wired connection 2 e7054040-a421-3bef-965d-bb7d60b7cecf ethernet enp5s0<br />
Wired connection 1 997f2782-f0fc-301d-bfba-15421a2735d8 ethernet enp0s25<br />
MY-HOME-WIFI-5G 92a0f7b3-2eba-49ab-a899-24d83978f308 wifi --<br />
</nowiki>}}<br />
<br />
Here you can use the first column as connection-id used later. In this example we pick {{ic|Wired connection 2}} as a connection-id.<br />
<br />
You have three methods to configure a connection {{ic|Wired connection 2}} after it has been created:<br />
<br />
; nmcli interactive editor<br />
: {{ic|nmcli connection edit 'Wired connection 2'}}.<br> Usage is well documented from the editor.<br />
<br />
; nmcli command line interface<br />
: {{ic|nmcli connection modify 'Wired connection 2' ''setting''.''property'' ''value''}}. See {{man|1|nmcli}} for usage. For example you can change its IPv4 route metric to 200 using {{ic|nmcli connection modify 'Wired connection 2' ipv4.route-metric 200}} command.<br />
<br />
; Connection file<br />
: In {{ic|/etc/NetworkManager/system-connections/}}, modify the corresponding {{ic|Wired connection 2.nmconnection}} file .<br> Do not forget to reload the configuration file with {{ic|nmcli connection reload}}.<br />
<br />
== Front-ends ==<br />
<br />
To configure and have easy access to NetworkManager, most users will want to install an applet. This GUI front-end usually resides in the system tray (or notification area) and allows network selection and configuration of NetworkManager. Various desktop environments have their own applet. Otherwise you can use [[#nm-applet]].<br />
<br />
=== GNOME ===<br />
<br />
[[GNOME]] has a built-in tool, accessible from the Network settings.<br />
<br />
=== KDE Plasma ===<br />
<br />
[[Install]] the {{Pkg|plasma-nm}} package. After that, add it to the KDE taskbar via the ''Panel options > Add widgets > Networks'' menu.<br />
<br />
=== nm-applet ===<br />
<br />
{{Pkg|network-manager-applet}} is a GTK 3 front-end which works under Xorg environments with a systray.<br />
<br />
To store connection secrets install and configure [[GNOME/Keyring]].<br />
<br />
Be aware that after enabling the tick-box option {{ic|Make available to other users}} for a connection, NetworkManager stores the password in plain-text, though the respective file is accessible only to root (or other users via {{ic|nm-applet}}). See [[#Encrypted Wi-Fi passwords]].<br />
<br />
In order to run {{ic|nm-applet}} without a systray, you can use {{Pkg|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:<br />
<br />
{{hc|nmgui|<nowiki><br />
#!/bin/sh<br />
nm-applet 2>&1 > /dev/null &<br />
stalonetray 2>&1 > /dev/null<br />
killall nm-applet<br />
</nowiki>}}<br />
<br />
When you close the ''stalonetray'' window, it closes {{ic|nm-applet}} too, so no extra memory is used once you are done with network settings.<br />
<br />
The applet can show notifications for events such as connecting to or disconnecting from a WiFi network. For these notifications to display, ensure that you have a notification server installed - see [[Desktop notifications]]. If you use the applet without a notification server, you might see some messages in stdout/stderr, and the app might hang. See [https://bugzilla.gnome.org/show_bug.cgi?id=788313].<br />
<br />
In order to run {{ic|nm-applet}} with such notifications disabled, start the applet with the following command:<br />
<br />
$ nm-applet --no-agent<br />
<br />
{{Tip|{{ic|nm-applet}} might be started automatically with a [[XDG Autostart|autostart desktop file]], to add the --no-agent option modify the Exec line there, i.e.<br />
<br />
{{bc|1=Exec=nm-applet --no-agent}}<br />
<br />
}}<br />
<br />
{{Warning|On [[i3]], if nm-applet is started with the {{ic|--no-agent}} option, it is not possible to connect to a new encrypted WiFi network by clicking on the item list because no password input dialogue window will pop out. [[journal]] will show {{ic|no secrets: No agents were available for this request}}.}}<br />
<br />
==== Appindicator ====<br />
<br />
As of version 1.18.0 Appindicator support is [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/network-manager-applet&id=7640a2bd557fe84813207ef4d5e35bb5aece6c54 available] in the official {{Pkg|network-manager-applet}} package. To use nm-applet in an Appindicator environment start the applet with the following command:<br />
<br />
$ nm-applet --indicator<br />
<br />
=== networkmanager-dmenu ===<br />
<br />
Alternatively there is {{AUR|networkmanager-dmenu-git}} which is a small script to manage NetworkManager connections with [[dmenu]] or [[rofi]] instead of {{ic|nm-applet}}. It provides all essential features such as connection to existing NetworkManager wifi or wired connections, connect to new wifi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch ''nm-connection-editor'' GUI, connect to Bluetooth networks.<br />
<br />
== Configuration ==<br />
<br />
NetworkManager will require some additional steps to be able run properly. Make sure you have configured {{ic|/etc/hosts}} as described in [[Network configuration#Set the hostname]] section.<br />
<br />
NetworkManager has a global configuration file at {{ic|/etc/NetworkManager/NetworkManager.conf}}. Addition configuration files can be placed in {{ic|/etc/NetworkManager/conf.d/}}. Usually no configuration needs to be done to the global defaults.<br />
<br />
After editing a configuration file, the changes can be applied by running:<br />
<br />
# nmcli general reload<br />
<br />
=== Enable NetworkManager Wait Online ===<br />
<br />
{{Out of date|{{ic|NetworkManager.service}} has {{ic|1=Also=NetworkManager-wait-online.service}} in the {{ic|[Install]}} section.[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/167e42a87e97ed7fb26a4263c22f1774716ac51b] If {{ic|NetworkManager.service}} was [[enable]]d before the change, it needs to be [[enable|reenabled]].}}<br />
<br />
If you have services which fail if they are started before the network is up, you may use {{ic|NetworkManager-wait-online.service}} in addition to {{ic|NetworkManager.service}}. This is, however, rarely necessary because most networked daemons start up okay, even if the network has not been configured yet.<br />
<br />
In some cases, the service will still fail to start successfully on boot due to the timeout setting in {{ic|/usr/lib/systemd/system/NetworkManager-wait-online.service}} being too short. Change the default timeout from 30 to a higher value.<br />
<br />
=== Set up PolicyKit permissions ===<br />
<br />
See [[General troubleshooting#Session permissions]] for setting up a working session.<br />
<br />
With a working session, you have several options for granting the necessary privileges to NetworkManager:<br />
<br />
* ''Option 1.'' Run a [[Polkit]] authentication agent when you log in, such as {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}} (part of {{Pkg|polkit-gnome}}). You will be prompted for your password whenever you add or remove a network connection.<br />
* ''Option 2.'' [[Users and groups#Group management|Add]] yourself to the {{ic|wheel}} group. You will not have to enter your password, but your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.<br />
* ''Option 3.'' [[Users and groups#Group management|Add]] yourself to the {{ic|network}} group and create the following file:<br />
<br />
{{hc|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
</nowiki>}}<br />
<br />
: All users in the {{ic|network}} group will be able to add and remove networks without a password. This will not work under [[systemd]] if you do not have an active session with ''systemd-logind''.<br />
<br />
=== Proxy settings ===<br />
<br />
NetworkManager does not directly handle proxy settings, but if you are using [[GNOME]] or [[KDE]], you could use [http://marin.jb.free.fr/proxydriver/ proxydriver] which handles proxy settings using NetworkManager's information. proxydriver is found in the package {{AUR|proxydriver}}.<br />
<br />
In order for ''proxydriver'' to be able to change the proxy settings, you would need to execute this command, as part of the GNOME startup process (see [[GNOME#Autostart]]).<br />
<br />
xhost +si:localuser:''username''<br />
<br />
See also [[Proxy settings]].<br />
<br />
=== Checking connectivity ===<br />
<br />
NetworkManager can try to reach a page on Internet when connecting to a network. {{Pkg|networkmanager}} is configured by default in {{ic|/usr/lib/NetworkManager/conf.d/20-connectivity.conf}} to check connectivity to archlinux.org. To use a different webserver or disable connectivity checking create {{ic|/etc/NetworkManager/conf.d/20-connectivity.conf}}, see {{man|5|NetworkManager.conf|CONNECTIVITY SECTION}}. Below is an example of using GNOME servers (it does not require the use of [[GNOME]]):<br />
<br />
{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki><br />
[connectivity]<br />
uri=http://nmcheck.gnome.org/check_network_status.txt<br />
</nowiki>}}<br />
<br />
{{Note|Although automatic connectivity checks are a potential privacy leak, the official archlinux.org default connectivity URL is committed to not logging any access. See [https://gitlab.archlinux.org/archlinux/infrastructure/-/commit/68fbaca2ef9f31f624f117899848f4288d6b39d1].}}<br />
<br />
=== Captive portals ===<br />
<br />
{{Style|Complex scripts should not be maintained on the wiki.}}<br />
<br />
For those behind a [[Wikipedia:Captive portal|captive portal]], the desktop manager may automatically open a window asking for credentials. If your desktop does not, you can use {{Pkg|capnet-assist}} package (however, it currently it has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/90-open_captive_portal|<nowiki><br />
#!/bin/sh -e<br />
# Script to dispatch NetworkManager events<br />
#<br />
# Runs shows a login webpage on walled garden networks.<br />
# See NetworkManager(8) for further documentation of the dispatcher events.<br />
<br />
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin<br />
<br />
if [ -x "/usr/bin/logger" ]; then<br />
logger="/usr/bin/logger -s -t captive-portal"<br />
else<br />
logger=":"<br />
fi<br />
<br />
wait_for_process() {<br />
PNAME=$1<br />
while [ -z "$(/usr/bin/pgrep $PNAME)" ]; do<br />
sleep 3;<br />
done<br />
}<br />
<br />
#launch the browser, but on boot we need to wait that nm-applet starts<br />
start_browser() {<br />
local user="$1"<br />
local display="$2"<br />
<br />
export DISPLAY="$display"<br />
wait_for_process nm-applet<br />
<br />
export XAUTHORITY="/home/$user/.Xauthority"<br />
<br />
$logger "Running browser as '$user' with display '$display' to login in captive portal"<br />
sudo -u "$user" --preserve-env=DISPLAY,XAUTHORITY -H xdg-open http://capnet.elementary.io 2>&1 > /dev/null<br />
}<br />
<br />
# Run the right scripts<br />
case "$2" in<br />
connectivity-change)<br />
$logger -p user.debug "dispatcher script triggered on connectivity change: $CONNECTIVITY_STATE"<br />
if [ "$CONNECTIVITY_STATE" = "PORTAL" ]; then<br />
# Match last column of who's output with ' :[at least one digit] '<br />
who | awk '$NF ~ /\(:[0-9]+\)/ { print $1 " " substr($NF, 2, length($NF)-2) };' | \<br />
while read user display; do<br />
start_browser $user $display || $logger -p user.err "Failed for user: '$user' display: '$display'"<br />
done<br />
fi<br />
;;<br />
*)<br />
# In a down phase<br />
exit 0<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
You will need to [[restart]] {{ic|NetworkManager.service}} or reboot for this to start working. Once you do, the dispatcher script should open a login window once it detects you are behind a captive portal.<br />
<br />
Another solution is {{AUR|captive-browser-git}} based on Google Chrome.<br />
<br />
=== DHCP client ===<br />
<br />
By default NetworkManager uses its internal DHCP client. The internal DHCPv4 plugin is based on the [https://nettools.github.io/n-dhcp4/ nettools' n-dhcp4] library, while the internal DHCPv6 plugin is made from code based on systemd-networkd.<br />
<br />
To use ISC’s DHCP client, [[install]] {{Pkg|dhclient}}. To change the DHCP client backend, set the option {{ic|1=main.dhcp=''dhcp_client_name''}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}. E.g.:<br />
<br />
{{hc|1=/etc/NetworkManager/conf.d/dhcp-client.conf|2=<br />
[main]<br />
dhcp=dhclient<br />
}}<br />
<br />
{{Note|<br />
* Do not enable the systemd units shipped with the {{Pkg|dhclient}} and {{Pkg|dhcpcd}} packages. They will conflict with NetworkManager, see the note in [[#Installation]] for details.<br />
* NetworkManger does not support dhcpcd ≥ 9.0.0. See {{Bug|66231}}.<br />
}}<br />
<br />
=== DNS management ===<br />
<br />
NetworkManager's DNS management is described in the GNOME project's wiki page—[https://wiki.gnome.org/Projects/NetworkManager/DNS Projects/NetworkManager/DNS].<br />
<br />
==== DNS caching and conditional forwarding ====<br />
<br />
NetworkManager has a plugin to enable DNS caching and conditional forwarding ([https://gitlab.freedesktop.org/NetworkManager/NetworkManager/merge_requests/143 previously] called "split DNS" in NetworkManager's documentation) using [[dnsmasq]] or [[systemd-resolved]]. The advantages of this setup is that DNS lookups will be cached, shortening resolve times, and DNS lookups of VPN hosts will be routed to the relevant VPN's DNS servers. This is especially useful if you are connected to more than one VPN.<br />
<br />
===== dnsmasq =====<br />
<br />
Make sure {{Pkg|dnsmasq}} has been installed. Then set {{ic|1=main.dns=dnsmasq}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns.conf|2=<br />
[main]<br />
dns=dnsmasq<br />
}}<br />
<br />
Now run {{ic|nmcli general reload}} as root. NetworkManager will automatically start dnsmasq and add {{ic|127.0.0.1}} to {{ic|/etc/resolv.conf}}. The original DNS servers can be found in {{ic|/run/NetworkManager/no-stub-resolv.conf}}. You can verify dnsmasq is being used by doing the same DNS lookup twice with {{ic|drill example.com}} and verifying the server and query times.<br />
<br />
{{Note|<br />
* You do not need to start {{ic|dnsmasq.service}} or edit {{ic|/etc/dnsmasq.conf}}. NetworkManager will start dnsmasq without using the systemd service and without reading the dnsmasq's default configuration file(s).<br />
* The dnsmasq instance started by NetworkManager will bind to {{ic|127.0.0.1:53}}, you cannot run any other software (including {{ic|dnsmasq.service}}) on the same address and port.<br />
}}<br />
<br />
====== Custom dnsmasq configuration ======<br />
<br />
Custom configurations can be created for ''dnsmasq'' by creating configuration files in {{ic|/etc/NetworkManager/dnsmasq.d/}}. For example, to change the size of the DNS cache (which is stored in RAM):<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=<br />
cache-size=1000<br />
}}<br />
<br />
{{Tip|Check the configuration file syntax with {{ic|1=dnsmasq --test --conf-file=/dev/null --conf-dir=/etc/NetworkManager/dnsmasq.d}}.}}<br />
<br />
See {{man|8|dnsmasq}} for all available options.<br />
<br />
====== IPv6 ======<br />
<br />
{{Accuracy|This does not solve the issue because NetworkManager does not add {{ic|::1}} to {{ic|/etc/resolv.conf}}. Unless {{ic|@::1}} is manually passed to drill, it will still fail with {{ic|Error: error sending query: No (valid) nameservers defined in the resolver}}.}}<br />
<br />
Enabling {{ic|dnsmasq}} in NetworkManager may break IPv6-only DNS lookups (i.e. {{ic|drill -6 [hostname]}}) which would otherwise work. In order to resolve this, creating the following file will configure ''dnsmasq'' to also listen to the IPv6 loopback:<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/ipv6-listen.conf|2=<br />
listen-address=::1<br />
}}<br />
<br />
In addition, {{ic|dnsmasq}} also does not prioritize upstream IPv6 DNS. Unfortunately NetworkManager does not do this ([https://bugs.launchpad.net/ubuntu/+source/network-manager/+bug/936712 Ubuntu Bug]). A workaround would be to disable IPv4 DNS in the NetworkManager config, assuming one exists<br />
<br />
====== DNSSEC ======<br />
<br />
The dnsmasq instance started by NetworkManager by default will not validate [[DNSSEC]] since it is started with the {{ic|--proxy-dnssec}} option. It will trust whatever DNSSEC information it gets from the upstream DNS server.<br />
<br />
For dnsmasq to properly validate DNSSEC, thus breaking DNS resolution with name servers that do not support it, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/dnsmasq.d/dnssec.conf|2=<br />
conf-file=/usr/share/dnsmasq/trust-anchors.conf<br />
dnssec<br />
}}<br />
<br />
===== systemd-resolved =====<br />
<br />
{{Expansion|NetworkManager 1.16 adds a new setting {{ic|main.systemd-resolved}}[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/d4eb4cb45f41b1751cacf71da558bf8f0988f383] (enabled by default). It unconditionally sends DNS configuration to systemd-resolved. Related to "Preserving resolv.conf" from [[systemd-resolved#DNS]]?}}<br />
<br />
NetworkManager can use [[systemd-resolved]] as a DNS resolver and cache. Make sure that ''systemd-resolved'' is properly configured and that {{ic|systemd-resolved.service}} is [[started]] before using it.<br />
<br />
systemd-resolved will be used automatically if {{ic|/etc/resolv.conf}} is a [[Systemd-resolved#DNS|symlink]] to {{ic|/run/systemd/resolve/stub-resolv.conf}}, {{ic|/run/systemd/resolve/resolv.conf}} or {{ic|/usr/lib/systemd/resolv.conf}}.<br />
<br />
You can enable it explicitly by setting {{ic|1=main.dns=systemd-resolved}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns.conf|2=<br />
[main]<br />
dns=systemd-resolved<br />
}}<br />
<br />
===== DNS resolver with an openresolv subscriber =====<br />
<br />
If [[openresolv]] has a subscriber for your local [[DNS resolver]], set up the subscriber and [[#Use openresolv|configure NetworkManager to use openresolv]].<br />
<br />
Because NetworkManager advertises a single "interface" to ''resolvconf'', it is not possible to implement conditional forwarding between two NetworkManager connections. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 NetworkManager issue 153].<br />
<br />
This can be partially mitigated if you set {{ic|1=private="*"}} in {{ic|/etc/resolvconf.conf}}[https://roy.marples.name/projects/openresolv/configuration.html]. Any queries for domains that are not in search domain list will not get forwarded. They will be handled according to the local resolver's configuration, for example, forwarded to another DNS server or resolved recursively from the DNS root.<br />
<br />
==== Custom DNS servers ====<br />
<br />
===== Setting custom global DNS servers =====<br />
<br />
To set DNS servers for all connections, specify them in {{man|5|NetworkManager.conf}} using the syntax {{ic|1=servers=''serveripaddress1'',''serveripaddress2'',''serveripaddress3''}} in a section named {{ic|[global-dns-domain-*]}}. For example:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns-servers.conf|2=<br />
[global-dns-domain-*]<br />
servers=::1,127.0.0.1<br />
}}<br />
<br />
{{Note|<br />
* If you use [[#DNS caching and conditional forwarding|NetworkManager's dnsmasq or systemd-resolved plugin]] or [[#DNS resolver with an openresolv subscriber|openresolv subscribers]], then do not specify loopback addresses with the {{ic|1=servers=}} option, it can break DNS resolution.<br />
* The specified servers do not get sent to [[systemd-resolved]], the connection's DNS servers are used instead.<br />
}}<br />
<br />
===== Setting custom DNS servers in a connection =====<br />
<br />
====== Setting custom DNS servers in a connection (GUI) ======<br />
<br />
Setup will depend on the type of front-end used; the process usually involves right-clicking on the applet, editing (or creating) a profile, and then choosing DHCP type as ''Automatic (specify addresses)''. The DNS addresses will need to be entered and are usually in this form: {{ic|127.0.0.1, ''DNS-server-one'', ...}}.<br />
<br />
====== Setting custom DNS servers in a connection (nmcli / connection file) ======<br />
<br />
To setup DNS Servers per connection, you can use the {{ic|dns}} field (and the associated {{ic|dns-search}} and {{ic|dns-options}}) in the [[#Edit a connection|connection settings]]. <br />
<br />
If {{ic|method}} is set to {{ic|auto}} (when you use DHCP), you need to set {{ic|ignore-auto-dns}} to {{ic|yes}}.<br />
<br />
==== /etc/resolv.conf ====<br />
<br />
By default {{ic|/etc/resolv.conf}} is managed by ''NetworkManager'' unless it is a symlink.<br />
<br />
It can be configured to write it through [[#Use openresolv|openresolv]] or to [[#Unmanaged /etc/resolv.conf|not touch it at all]].<br />
<br />
Using openresolv allows NetworkManager to coexists with other ''resolvconf'' supporting software or, for example, to run a local DNS caching and split-DNS resolver for which openresolv has a [[openresolv#Subscribers|subscriber]].<br />
<br />
{{Note|Conditional forwarding is [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 not yet fully supported] when using NetworkManager with openresolv.}}<br />
<br />
''NetworkManager'' also offers hooks via so called dispatcher scripts that can be used to alter the {{ic|/etc/resolv.conf}} after network changes. See [[#Network services with NetworkManager dispatcher]] and {{man|8|NetworkManager}} for more information.<br />
<br />
{{Note|<br />
* If NetworkManager is configured to use either [[#dnsmasq|dnsmasq]] or [[#systemd-resolved|systemd-resolved]], then the appropriate loopback addresses will be written to {{ic|/etc/resolv.conf}}.<br />
* The {{ic|resolv.conf}} file NetworkManager writes or would write to {{ic|/etc/resolv.conf}} can be found at {{ic|/run/NetworkManager/resolv.conf}}.<br />
* A {{ic|resolv.conf}} file with the acquired name servers and search domains can be found at {{ic|/run/NetworkManager/no-stub-resolv.conf}}.<br />
}}<br />
<br />
===== Unmanaged /etc/resolv.conf =====<br />
<br />
To stop NetworkManager from touching {{ic|/etc/resolv.conf}}, set {{ic|1=main.dns=none}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/dns.conf|2=<br />
[main]<br />
dns=none<br />
}}<br />
<br />
{{Tip|You might also want to set {{ic|1=main.systemd-resolved=false}}, so that NetworkManager does not send the DNS configuration to [[systemd-resolved]].}}<br />
<br />
{{Note|See [[#DNS caching and conditional forwarding]], to configure NetworkManager using other DNS backends like [[dnsmasq]] and [[systemd-resolved]], instead of using {{ic|1=main.dns=none}}.}}<br />
<br />
After that {{ic|/etc/resolv.conf}} might be a broken symlink that you will need to remove. Then, just create a new {{ic|/etc/resolv.conf}} file.<br />
<br />
===== Use openresolv =====<br />
<br />
{{Note|Do not set {{ic|1=rc-manager=resolvconf}} when {{Pkg|systemd-resolvconf}} is installed. ''systemd-resolved'' provides limited support for the ''resolvconf'' interface and NetworkManager supports communicating with systemd-resolved through D-Bus without using ''resolvconf''.}}<br />
<br />
To configure NetworkManager to use [[openresolv]], set {{ic|1=main.rc-manager=resolvconf}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/rc-manager.conf|2=<br />
[main]<br />
rc-manager=resolvconf<br />
}}<br />
<br />
=== Firewall ===<br />
<br />
You can assign a [[firewalld]] zone based on your current connection. For example a restrictive firewall when at work, and a less restrictive one when at home.<br />
<br />
This can also be done with [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher]].<br />
<br />
=== 802.1x / PEAP configuration ===<br />
<br />
A PEAP and 802.1x network can be added by adding a config file to {{ic|/etc/NetworkManager/system-connections/''name''}}.<br />
<br />
Here is an example configuration file for IPv4 with IPv6 disabled:<br />
<br />
{{hc|/etc/NetworkManager/system-connections/''name''|2=<br />
[ipv6]<br />
method=ignore<br />
<br />
[ipv4]<br />
method=auto<br />
<br />
[connection]<br />
#id=XXXXXXXXX<br />
#uuid=XXXXXXXXX<br />
type=802-11-wireless<br />
#timestamp=XXXX<br />
<br />
[802-11-wireless-security]<br />
key-mgmt=wpa-eap<br />
<br />
[802-11-wireless]<br />
ssid=ssid<br />
mode=infrastructure<br />
#seen-bssids=XXXXXXXXX<br />
security=802-11-wireless-security<br />
<br />
[802-1x]<br />
eap=peap;<br />
identity=user<br />
password=password<br />
phase2-auth=mschapv2<br />
}}<br />
<br />
The number sign (#) defines comments.<br />
<br />
== Network services with NetworkManager dispatcher ==<br />
<br />
There are quite a few network services that you will not want running until NetworkManager brings up an interface. NetworkManager has the ability to start services when you connect to a network and stop them when you disconnect (e.g. when using [[NFS]], [[SMB]] and [[NTPd]]).<br />
<br />
To activate the feature you need to [[enable]] and [[start]] the {{ic|NetworkManager-dispatcher.service}}.<br />
<br />
Once the service is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory.<br />
<br />
Scripts must be owned by '''root''', otherwise the dispatcher will not execute them. For added security, set group [[ownership]] to root as well:<br />
<br />
# chown root:root /etc/NetworkManager/dispatcher.d/''10-script.sh''<br />
<br />
Make sure the file has correct permissions:<br />
<br />
# chmod 755 /etc/NetworkManager/dispatcher.d/''10-script.sh''<br />
<br />
The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. {{ic|10-portmap}} or {{ic|30-netfs}} (which ensures that the ''portmapper'' is up before NFS mounts are attempted).<br />
<br />
Scripts will receive the following arguments:<br />
<br />
* '''Interface name:''' e.g. {{ic|eth0}}<br />
* '''Interface status:''' ''up'' or ''down''<br />
* '''VPN status:''' ''vpn-up'' or ''vpn-down''<br />
<br />
{{Warning|If you connect to foreign or public networks, be aware of what services you are starting and what servers you expect to be available for them to connect to. You could make a security hole by starting the wrong services while connected to a public network.}}<br />
<br />
=== Avoiding the dispatcher timeout ===<br />
<br />
If the above is working, then this section is not relevant. However, there is a general problem related to running dispatcher scripts which take longer to be executed. Initially an internal timeout of three seconds only was used. If the called script did not complete in time, it was killed. Later the timeout was extended to about 20 seconds (see the [https://bugzilla.redhat.com/show_bug.cgi?id=982734 Bugtracker] for more information). If the timeout still creates the problem, a work around may be to modify the dispatcher service file {{ic|/usr/lib/systemd/system/NetworkManager-dispatcher.service}} to remain active after exit: <br />
<br />
{{hc|/etc/systemd/system/NetworkManager-dispatcher.service.d/remain_after_exit.conf|2=<br />
[Service]<br />
RemainAfterExit=yes<br />
}}<br />
<br />
Now start and enable the modified {{ic|NetworkManager-dispatcher}} service.<br />
<br />
{{Warning|Adding the {{ic|RemainAfterExit}} line to it will prevent the dispatcher from closing. Unfortunately, the dispatcher '''has''' to close before it can run your scripts again. With it the dispatcher will not time out but it also will not close, which means that the scripts will only run once per boot. Therefore, do not add the line unless the timeout is definitely causing a problem.}}<br />
<br />
=== Dispatcher examples ===<br />
<br />
==== Mount remote folder with sshfs ====<br />
<br />
As the script is run in a very restrictive environment, you have to export {{ic|SSH_AUTH_SOCK}} in order to connect to your SSH agent. There are different ways to accomplish this, see [https://bbs.archlinux.org/viewtopic.php?pid=1042030#p1042030 this message] for more information. The example below works with [[GNOME Keyring]], and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely ''gnome-keyring'' has not yet started and the export will fail (hence the sleep). The {{ic|UUID}} to match can be found with the command {{ic|nmcli connection status}} or {{ic|nmcli connection list}}. <br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
USER='username'<br />
REMOTE='user@host:/remote/path'<br />
LOCAL='/local/path'<br />
<br />
interface=$1 status=$2<br />
if [ "$CONNECTION_UUID" = "</nowiki>''uuid''<nowiki>" ]; then<br />
case $status in<br />
up)<br />
SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')<br />
export SSH_AUTH_SOCK<br />
su "$USER" -c "sshfs $REMOTE $LOCAL"<br />
;;<br />
down)<br />
fusermount -u "$LOCAL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
==== Mounting of SMB shares ====<br />
<br />
Some [[SMB]] shares are only available on certain networks or locations (e.g. at home). You can use the dispatcher to only mount SMB shares that are present at your current location.<br />
<br />
The following script will check if we connected to a specific network and mount shares accordingly:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-mount-smb.sh|<nowiki><br />
#!/bin/sh<br />
<br />
# Find the connection UUID with "nmcli connection show" in terminal.<br />
# All NetworkManager connection types are supported: wireless, VPN, wired...<br />
if [ "$2" = "up" ]; then<br />
if [ "$CONNECTION_UUID" = "uuid" ]; then<br />
mount /your/mount/point & <br />
# add more shares as needed<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
The following script will unmount all SMB shares before a software initiated disconnect from a specific network:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/pre-down.d/30-umount-smb.sh|<nowiki><br />
#!/bin/sh<br />
<br />
if [ "$CONNECTION_UUID" = "uuid" ]; then<br />
umount -a -l -t cifs<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|Make sure this script is located in the {{ic|pre-down.d}} sub-directory as shown above, otherwise it will unmount all shares on any connection state change.}}<br />
<br />
The following script will attempt to unmount all SMB shares following an unexpected disconnect from a specific network:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/40-umount-smb.sh|<nowiki><br />
#!/bin/sh<br />
<br />
if [ "$CONNECTION_UUID" = "uuid" ]; then<br />
if [ "$2" = "down" ]; then<br />
umount -a -l -t cifs<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|<br />
* Since NetworkManager 0.9.8, the ''pre-down'' and ''down'' events are not executed on shutdown or restart, see [https://bugzilla.gnome.org/show_bug.cgi?id&#61;701242 this bug report] for more info.<br />
* The previous ''umount'' scripts are still prone to leaving applications actually accessing the mount to 'hang'.<br />
}}<br />
<br />
An alternative is to use the script as seen in [[NFS#Using a NetworkManager dispatcher]]:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/30-smb.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Find the connection UUID with "nmcli con show" in terminal.<br />
# All NetworkManager connection types are supported: wireless, VPN, wired...<br />
WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"<br />
<br />
if [[ "$CONNECTION_UUID" == "$WANTED_CON_UUID" ]]; then<br />
<br />
# Script parameter $1: NetworkManager connection name, not used<br />
# Script parameter $2: dispatched event<br />
<br />
case "$2" in<br />
"up")<br />
mount -a -t cifs<br />
;;<br />
"pre-down");&<br />
"vpn-pre-down")<br />
umount -l -a -t cifs >/dev/null<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|This script ignores mounts with the {{ic|noauto}} option, remove this mount option or use {{ic|auto}} to allow the dispatcher to manage these mounts.}}<br />
<br />
Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down/}} to catch the {{ic|pre-down}} events:<br />
<br />
# ln -s ../30-smb.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-smb.sh<br />
<br />
==== Mounting of NFS shares ====<br />
<br />
See [[NFS#Using a NetworkManager dispatcher]].<br />
<br />
==== Use dispatcher to automatically toggle wireless depending on LAN cable being plugged in ====<br />
<br />
The idea is to only turn Wi-Fi on when the LAN cable is unplugged (for example when detaching from a laptop dock), and for Wi-Fi to be automatically disabled, once a LAN cable is plugged in again. <br />
<br />
Create the following dispatcher script[https://superuser.com/questions/233448/disable-wlan-if-wired-cable-network-is-available], replacing {{ic|1=LAN_interface}} with yours.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/wlan_auto_toggle.sh|<nowiki><br />
#!/bin/sh<br />
<br />
if [ "$1" = "LAN_interface" ]; then<br />
case "$2" in<br />
up)<br />
nmcli radio wifi off<br />
;;<br />
down)<br />
nmcli radio wifi on<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|You can get a list of interfaces using [[#nmcli examples|nmcli]]. The ethernet (LAN) interfaces start with {{ic|en}}, e.g. {{ic|1=enp0s5}}}}<br />
<br />
==== Use dispatcher to connect to a VPN after a network connection is established ====<br />
<br />
In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network.<br />
<br />
{{Note|This script will require {{Pkg|wireless_tools}} in order to use {{ic|iwgetid}}.}}<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="Wi-Fi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli connection up id "$VPN_NAME"<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli connection show --active | grep "$VPN_NAME"; then<br />
nmcli connection down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
If you would like to attempt to automatically connect to VPN for all Wi-Fi networks, you can use the following definition of the ESSID: {{ic|1=ESSID=$(iwgetid -r)}}. Remember to set the script's permissions [[#Network services with NetworkManager dispatcher|accordingly]]. <br />
<br />
Trying to connect with the above script may still fail with {{ic|NetworkManager-dispatcher.service}} complaining about 'no valid VPN secrets', because of [https://developer.gnome.org/NetworkManager/0.9/secrets-flags.html the way VPN secrets are stored]. Fortunately, there are different options to give the above script access to your VPN password.<br />
<br />
1: One of them requires editing the VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring [https://bugzilla.redhat.com/show_bug.cgi?id=710552 that will be inaccessible for root]: open up {{ic|/etc/NetworkManager/system-connections/''name of your VPN connection''}} and change the {{ic|password-flags}} and {{ic|secret-flags}} from {{ic|1}} to {{ic|0}}.<br />
<br />
If that alone does not work, you may have to create a {{ic|passwd-file}} in a safe location with the same permissions and ownership as the dispatcher script, containing the following:<br />
<br />
{{hc|/path/to/passwd-file|<br />
vpn.secrets.password:YOUR_PASSWORD<br />
}}<br />
<br />
The script must be changed accordingly, so that it gets the password from the file:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="Wi-Fi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli connection up id "$VPN_NAME" passwd-file /path/to/passwd-file<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli connection show --active | grep "$VPN_NAME"; then<br />
nmcli connection down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
2: Alternatively, change the {{ic|password-flags}} and put the password directly in the configuration file adding the section {{ic|vpn-secrets}}:<br />
<br />
[vpn]<br />
....<br />
password-flags=0<br />
<br />
[vpn-secrets]<br />
password=''your_password''<br />
<br />
{{Note|It may now be necessary to re-open the NetworkManager connection editor and save the VPN passwords/secrets again.}}<br />
<br />
==== Use dispatcher to disable IPv6 on VPN provider connections ====<br />
<br />
Many [[:Category:VPN providers|commercial VPN providers]] support only IPv4. That means all IPv6 traffic bypasses the VPN and renders it virtually useless. To avoid this, dispatcher can be used to disable all IPv6 traffic for the time a VPN connection is up.<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki><br />
#!/bin/sh<br />
<br />
case "$2" in<br />
vpn-up)<br />
echo 1 > /proc/sys/net/ipv6/conf/all/disable_ipv6<br />
;;<br />
vpn-down)<br />
echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
==== OpenNTPD ====<br />
<br />
See [[OpenNTPD#Using NetworkManager dispatcher]].<br />
<br />
== Testing ==<br />
<br />
NetworkManager applets are designed to load upon login so no further configuration should be necessary for most users. If you have already disabled your previous network settings and disconnected from your network, you can now test if NetworkManager will work. The first step is to [[start]] {{ic|NetworkManager.service}}.<br />
<br />
Some applets will provide you with a {{ic|.desktop}} file so that the NetworkManager applet can be loaded through the application menu. If it does not, you are going to either have to discover the command to use or logout and login again to start the applet. Once the applet is started, it will likely begin polling network connections with for auto-configuration with a DHCP server.<br />
<br />
To start the GNOME applet in non-xdg-compliant window managers like [[awesome]]:<br />
<br />
nm-applet --sm-disable &<br />
<br />
For static IP addresses, you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Encrypted Wi-Fi passwords ===<br />
<br />
By default, NetworkManager stores passwords in clear text in the connection files at {{ic|/etc/NetworkManager/system-connections/}}. To print the stored passwords, use the following command:<br />
<br />
# grep -r '^psk=' /etc/NetworkManager/system-connections/<br />
<br />
The passwords are accessible to the root user in the filesystem and to users with access to settings via the GUI (e.g. {{ic|nm-applet}}). <br />
<br />
It is preferable to save the passwords in encrypted form in a keyring instead of clear text. The downside of using a keyring is that the connections have to be set up for each user.<br />
<br />
==== Using GNOME Keyring ====<br />
<br />
The keyring daemon has to be started and the keyring needs to be unlocked for the following to work.<br />
<br />
Furthermore, NetworkManager needs to be configured not to store the password for all users. Using GNOME {{ic|nm-applet}}, run {{ic|nm-connection-editor}} from a terminal, select a network connection, click {{ic|Edit}}, select the {{ic|Wifi-Security}} tab and click on the right icon of password and check {{ic|Store the password only for this user}}.<br />
<br />
==== Using KDE Wallet ====<br />
<br />
Using KDE's {{Pkg|plasma-nm}}, click the applet, click on the top right {{ic|Settings}} icon, click on a network connection, in the {{ic|General settings}} tab, untick {{ic|all users may connect to this network}}. If the option is ticked, the passwords will still be stored in clear text, even if a keyring daemon is running.<br />
<br />
If the option was selected previously and you un-tick it, you may have to use the {{ic|reset}} option first to make the password disappear from the file. Alternatively, delete the connection first and set it up again.<br />
<br />
=== Sharing internet connection over Wi-Fi ===<br />
<br />
You can share your internet connection (e.g. 3G or wired) with a few clicks. Please note that a [[firewall]] may interfere with internet sharing.<br />
<br />
You will need a Wi-Fi card which supports AP mode, see [[Software access point#Wi-Fi device must support AP mode]] for details.<br />
<br />
[[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection.<br />
<br />
Create the shared connection:<br />
<br />
* Click on applet and choose ''Create new wireless network''.<br />
* Follow wizard (chose WPA2 or higher, be sure to use at least 8 character long password, lower lengths will fail).<br />
** Choose either [[Fedora:Features/RealHotspot|Hotspot]] or Ad-hoc as Wi-Fi mode.<br />
<br />
The connection will be saved and remain stored for the next time you need it.<br />
<br />
{{Note|Android does not support connecting to Ad-hoc networks. To share a connection with Android use infrastructure mode (i.e. set Wi-Fi mode to "Hotspot").}}<br />
<br />
=== Sharing internet connection over Ethernet ===<br />
<br />
Scenario: your device has internet connection over wi-fi and you want to share the internet connection to other devices over ethernet.<br />
<br />
Requirements:<br />
<br />
* [[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection.<br />
* Your internet connected device and the other devices are connected over a suitable ethernet cable (this usually means a cross over cable or a switch in between).<br />
* Internet sharing is not blocked by a [[firewall]].<br />
<br />
Steps:<br />
<br />
{{Style|{{Pkg|nm-connection-editor}} is not a dependency of {{Pkg|networkmanager}} and needs to be installed separately.}}<br />
<br />
* Run {{ic|nm-connection-editor}} from terminal.<br />
* Add a new ethernet connection.<br />
* Give it some sensible name. For example "Shared Internet"<br />
* Go to "IPv4 Settings".<br />
* For "Method:" select "Shared to other computers".<br />
* Save<br />
<br />
Now you should have a new option "Shared Internet" under the Wired connections in NetworkManager.<br />
<br />
=== Checking if networking is up inside a cron job or script ===<br />
<br />
{{Out of date|''nm-tool'' was remove from NetworkManager for long time now[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/bb8c75bd536d4f8fb80a4366025a279078f0ec81]. ''nmcli'' should be used instead.}}<br />
<br />
Some ''cron'' jobs require networking to be up to succeed. You may wish to avoid running these jobs when the network is down. To accomplish this, add an '''if''' test for networking that queries NetworkManager's ''nm-tool'' and checks the state of networking. The test shown here succeeds if any interface is up, and fails if they are all down. This is convenient for laptops that might be hardwired, might be on wireless, or might be off the network.<br />
<br />
{{bc|<nowiki><br />
if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then<br />
#Whatever you want to do if the network is online<br />
else<br />
#Whatever you want to do if the network is offline - note, this and the else above are optional<br />
fi<br />
</nowiki>}}<br />
<br />
This useful for a {{ic|cron.hourly}} script that runs ''fpupdate'' for the F-Prot virus scanner signature update, as an example. Another way it might be useful, with a little modification, is to differentiate between networks using various parts of the output from ''nm-tool''; for example, since the active wireless network is denoted with an asterisk, you could grep for the network name and then grep for a literal asterisk.<br />
<br />
=== Connect to network with secret on boot ===<br />
<br />
By default, NetworkManager will not connect to networks requiring a secret automatically on boot. This is because it locks such connections to the user who makes it by default, only connecting after they have logged in. To change this, do the following:<br />
<br />
# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab<br />
# Select the connection you want to work with and click the Edit button<br />
# Check the boxes “Connect Automatically” and “Available to all users”<br />
# Additionally, ensure that under "Wi-Fi Security", "Store password for all users (not encrypted)" is selected<br />
Log out and log back in to complete.<br />
<br />
=== OpenConnect with password in KWallet ===<br />
<br />
While you may type both values at connection time, {{Pkg|plasma-nm}} 0.9.3.2-1 and above are capable of retrieving OpenConnect username and password directly from [[KWallet]].<br />
<br />
Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and <br />
enter your credentials in key "VpnSecrets" in this form (replace ''username'' and ''password'' accordingly):<br />
<br />
form:main:username%SEP%''username''%SEP%form:main:password%SEP%''password''<br />
<br />
Next time you connect, username and password should appear in the "VPN secrets" dialog box.<br />
<br />
=== Ignore specific devices ===<br />
<br />
Sometimes it may be desired that NetworkManager ignores specific devices and does not try to configure addresses and routes for them. You can quickly and easily ignore devices by MAC or interface-name by using the following in {{ic|/etc/NetworkManager/conf.d/unmanaged.conf}}:<br />
<br />
[keyfile]<br />
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth0<br />
<br />
After editing the file, run {{ic|nmcli general reload}} as root. Afterwards you should be able to configure interfaces without NetworkManager altering what you have set.<br />
<br />
=== Configuring MAC address randomization ===<br />
<br />
{{Note|1=Disabling MAC address randomization may be needed to get (stable) link connection [https://bbs.archlinux.org/viewtopic.php?id=220101] and/or networks that restrict devices based on their MAC Address or have a limit network capacity.}}<br />
<br />
MAC randomization can be used for increased privacy by not disclosing your real MAC address to the network.<br />
<br />
NetworkManager supports two types MAC Address Randomization: randomization during scanning, and for network connections. Both modes can be configured by modifying {{ic|/etc/NetworkManager/NetworkManager.conf}} or by creating a separate configuration file in {{ic|/etc/NetworkManager/conf.d/}} which is recommended since the aforementioned config file may be overwritten by NetworkManager.<br />
<br />
Randomization during Wi-Fi scanning is enabled by default, but it may be disabled by adding the following lines to {{ic|/etc/NetworkManager/NetworkManager.conf}} or a dedicated configuration file under {{ic|/etc/NetworkManager/conf.d}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=<br />
[device]<br />
wifi.scan-rand-mac-address=no<br />
}}<br />
<br />
MAC randomization for network connections can be set to different modes for both wireless and ethernet interfaces. See the [https://blogs.gnome.org/thaller/2016/08/26/mac-address-spoofing-in-networkmanager-1-4-0/ GNOME blog post] for more details on the different modes. <br />
<br />
In terms of MAC randomization the most important modes are {{ic|stable}} and {{ic|random}}. {{ic|stable}} generates a random MAC address when you connect to a new network and associates the two permanently. This means that you will use the same MAC address every time you connect to that network. In contrast, {{ic|random}} will generate a new MAC address every time you connect to a network, new or previously known. You can configure the MAC randomization by adding the desired configuration under {{ic|/etc/NetworkManager/conf.d}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=<br />
[device-mac-randomization]<br />
# "yes" is already the default for scanning<br />
wifi.scan-rand-mac-address=yes<br />
<br />
[connection-mac-randomization]<br />
# Randomize MAC for every ethernet connection<br />
ethernet.cloned-mac-address=random<br />
# Generate a random MAC for each WiFi and associate the two permanently.<br />
wifi.cloned-mac-address=stable<br />
}}<br />
<br />
See the following [https://blogs.gnome.org/thaller/2016/08/26/mac-address-spoofing-in-networkmanager-1-4-0/ GNOME blog post] for more details.<br />
<br />
=== Enable IPv6 Privacy Extensions ===<br />
<br />
See [[IPv6#NetworkManager]].<br />
<br />
=== Working with wired connections ===<br />
<br />
By default, NetworkManager generates a connection profile for each wired ethernet connection it finds. At the point when generating the connection, it does not know whether there will be more ethernet adapters available. Hence, it calls the first wired connection "Wired connection 1". You can avoid generating this connection, by configuring {{ic|no-auto-default}} (see {{man|5|NetworkManager.conf}}), or by simply deleting it. Then NetworkManager will remember not to generate a connection for this interface again.<br />
<br />
You can also edit the connection (and persist it to disk) or delete it. NetworkManager will not re-generate a new connection. Then you can change the name to whatever you want. You can use something like nm-connection-editor for this task.<br />
<br />
=== Using iwd as the Wi-Fi backend ===<br />
<br />
Install {{AUR|networkmanager-iwd}} or enable the experimental [[iwd]] backend creating the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/wifi_backend.conf|2=<br />
[device]<br />
wifi.backend=iwd<br />
}}<br />
<br />
=== Running in a network namespace ===<br />
<br />
If you would like to run NetworkManager inside a network namespace (e.g., to manage a specific device which should be use by selected applications), bring the device down before moving it to the namespace:<br />
<br />
$ ip link set dev ''MY_DEVICE'' down<br />
$ ip link set dev ''MY_DEVICE'' netns ''MY_NAMESPACE''<br />
$ ip netns exec ''MY_NAMESPACE'' NetworkManager<br />
...<br />
$ ip netns exec ''MY_NAMESPACE'' killall NetworkManager<br />
<br />
otherwise NetworkManager will later fail to establish the connection with a {{ic|device is strictly unmanaged}} error.<br />
<br />
== Troubleshooting ==<br />
<br />
=== No prompt for password of secured Wi-Fi networks ===<br />
<br />
When trying to connect to a secured Wi-Fi network, no prompt for a password is shown and no connection is established. This happens when no keyring package is installed. An easy solution is to install {{Pkg|gnome-keyring}}. If you want the passwords to be stored in encrypted form, follow [[GNOME Keyring]] to set up the ''gnome-keyring-daemon''.<br />
<br />
=== Network management disabled ===<br />
<br />
When NetworkManager shuts down but the pid (state) file is not removed, you will see a {{ic|Network management disabled}} message. If this happens, remove the file manually:<br />
<br />
# rm /var/lib/NetworkManager/NetworkManager.state<br />
<br />
=== Problems with internal DHCP client ===<br />
<br />
If you have problems with getting an IP address using the internal DHCP client, consider using another DHCP client, see [[#DHCP client]] for instructions. This workaround might solve problems in big wireless networks like eduroam.<br />
<br />
=== DHCP problems with dhclient ===<br />
<br />
If you have problems with getting an IP address via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:<br />
<br />
interface "eth0" {<br />
send dhcp-client-identifier 01:''aa:bb:cc:dd:ee:ff'';<br />
}<br />
<br />
Where {{ic|''aa:bb:cc:dd:ee:ff''}} is the MAC address of this NIC. The MAC address can be found using the {{ic|ip link show ''interface''}} command from the {{Pkg|iproute2}} package.<br />
<br />
=== 3G modem not detected ===<br />
<br />
See [[USB 3G Modem#NetworkManager]].<br />
<br />
=== Switching off WLAN on laptops ===<br />
<br />
Sometimes NetworkManager will not work when you disable your Wi-Fi adapter with a switch on your laptop and try to enable it again afterwards. This is often a problem with ''rfkill''. To check if the driver notifies ''rfkill'' about the wireless adapter's status, use:<br />
<br />
$ watch -n1 rfkill list all<br />
<br />
If one identifier stays blocked after you switch on the adapter you could try to manually unblock it with (where X is the number of the identifier provided by the above output):<br />
<br />
# rfkill event unblock X<br />
<br />
=== Static IP address settings revert to DHCP ===<br />
<br />
Due to an unresolved bug, when changing default connections to a static IP address, {{ic|nm-applet}} may not properly store the configuration change, and will revert to automatic DHCP.<br />
<br />
To work around this issue you have to edit the default connection (e.g. "Auto eth0") in {{ic|nm-applet}}, change the connection name (e.g. "my eth0"), uncheck the "Available to all users" checkbox, change your static IP address settings as desired, and click '''Apply'''. This will save a new connection with the given name.<br />
<br />
Next, you will want to make the default connection not connect automatically. To do so, run {{ic|nm-connection-editor}} ('''not''' as root). In the connection editor, edit the default connection (e.g. "Auto eth0") and uncheck "Connect automatically". Click '''Apply''' and close the connection editor.<br />
<br />
=== Cannot edit connections as normal user ===<br />
<br />
See [[#Set up PolicyKit permissions]].<br />
<br />
=== Forget hidden wireless network ===<br />
<br />
Since hidden networks are not displayed in the selection list of the Wireless view, they cannot be forgotten (removed) with the GUI. You can delete one with the following command:<br />
<br />
# rm /etc/NetworkManager/system-connections/''SSID''<br />
<br />
This works for any other connection.<br />
<br />
=== VPN not working in GNOME ===<br />
<br />
When setting up OpenConnect or vpnc connections in NetworkManager while using GNOME, you will sometimes never see the dialog box pop up and the following error appears in {{ic|/var/log/errors.log}}:<br />
<br />
localhost NetworkManager[399]: <error> [1361719690.10506] [nm-vpn-connection.c:1405] get_secrets_cb(): Failed to request VPN secrets #3: (6) No agents were available for this request.<br />
<br />
This is caused by the GNOME NM Applet expecting dialog scripts to be at {{ic|/usr/lib/gnome-shell}}, when NetworkManager's packages put them in {{ic|/usr/lib/networkmanager}}.<br />
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):<br />
<br />
* For OpenConnect: {{ic|ln -s /usr/lib/networkmanager/nm-openconnect-auth-dialog /usr/lib/gnome-shell/}}<br />
* For VPNC (i.e. Cisco VPN): {{ic|ln -s /usr/lib/networkmanager/nm-vpnc-auth-dialog /usr/lib/gnome-shell/}}<br />
<br />
This may need to be done for any other NM VPN plugins as well, but these are the two most common.<br />
<br />
=== Unable to connect to visible European wireless networks ===<br />
<br />
WLAN chips are shipped with a default [[Wireless network configuration#Respecting the regulatory domain|regulatory domain]]. If your access point does not operate within these limitations, you will not be able to connect to the network. Fixing this is easy:<br />
<br />
# [[Install]] {{Pkg|crda}}<br />
# Uncomment the correct Country Code in {{ic|/etc/conf.d/wireless-regdom}}<br />
# Reboot the system, because the setting is only read on boot<br />
<br />
=== Automatic connect to VPN on boot is not working ===<br />
<br />
The problem occurs when the system (i.e. NetworkManager running as the root user) tries to establish a VPN connection, but the password is not accessible because it is stored in the GNOME keyring of a particular user. <br />
<br />
A solution is to keep the password to your VPN in plaintext, as described in step (2.) of [[#Use dispatcher to connect to a VPN after a network connection is established]]. <br />
<br />
You do not need to use the dispatcher described in step (1.) to auto-connect anymore, if you use the new "auto-connect VPN" option from the {{ic|nm-applet}} GUI.<br />
<br />
=== Systemd Bottleneck ===<br />
<br />
Over time the log files ({{ic|/var/log/journal}}) can become very large. This can have a big impact on boot performance when using NetworkManager, see: [[Systemd#Boot time increasing over time]].<br />
<br />
=== Regular network disconnects, latency and lost packets (WiFi) ===<br />
<br />
NetworkManager does a scan every 2 minutes.<br />
<br />
Some WiFi drivers have issues when scanning for base stations whilst connected/associated. Symptoms include VPN disconnects/reconnects and lost packets, web pages failing to load and then refresh fine.<br />
<br />
Running {{ic|journalctl -f}} will indicate that this is taking place, messages like the following will be contained in the logs at regular intervals.<br />
<br />
NetworkManager[410]: <info> (wlp3s0): roamed from BSSID 00:14:48:11:20:CF (my-wifi-name) to (none) ((none))<br />
<br />
There is a patched version of NetworkManager which should prevent this type of scanning: {{AUR|networkmanager-noscan}}.<br />
<br />
Alternatively, if roaming is not important, the periodic scanning behavior can be disabled by locking the BSSID of the access point in the WiFi connection profile.<br />
<br />
=== Unable to turn on wi-fi with Lenovo laptop (IdeaPad, Legion, etc.) ===<br />
<br />
There is an issue with the {{ic|ideapad_laptop}} module on some Lenovo models due to the wi-fi driver incorrectly reporting a soft block. The card can still be manipulated with {{ic|netctl}}, but managers like NetworkManager break. You can verify that this is the problem by checking the output of {{ic|rfkill list}} after toggling your hardware switch and seeing that the soft block persists.<br />
<br />
{{Accuracy|Try to use {{ic|rfkill.default_state}} and {{ic|rfkill.master_switch_mode}} (see [https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/kernel-parameters.txt kernel-parameters.txt]) to fix the rfkill problem.}}<br />
<br />
[[modprobe|Unloading]] the {{ic|ideapad_laptop}} module should fix this. ('''warning''': this may disable the laptop keyboard and touchpad also!).<br />
<br />
=== Turn off hostname sending ===<br />
<br />
NetworkManager by default sends the hostname to the DHCP server. Hostname sending can only be disabled per connection not globally ([https://bugzilla.gnome.org/show_bug.cgi?id=768076 GNOME Bug 768076]).<br />
<br />
To disable sending your hostname to the DHCP server for a specific connection, add the following to your network connection file:<br />
<br />
{{hc|/etc/NetworkManager/system-connections/''your_connection_file''|2=<br />
...<br />
[ipv4]<br />
dhcp-send-hostname=false<br />
...<br />
[ipv6]<br />
dhcp-send-hostname=false<br />
...<br />
}}<br />
<br />
=== nm-applet disappears in i3wm ===<br />
<br />
If you use the {{ic|xfce4-notifyd.service}} for notifications you must [[edit]] the unit and add the following:<br />
<br />
{{hc|/etc/systemd/user/xfce4-notifyd.service.d/display_env.conf|2=<br />
[Service]<br />
Environment="DISPLAY=:0.0"<br />
}}<br />
<br />
After reloading the daemons [[restart]] {{ic|xfce4-notifyd.service}}. Exit i3 and start it back up again and the applet should show on the tray.<br />
<br />
=== nm-applet tray icons display wrongly ===<br />
<br />
Currently the tray icons of nm-applet are drawn on top of one another, i.e. the icon displaying wireless strength might show on top of the icon indicating no wired connection.<br />
This is apparently a GTK3 bug/problem: https://gitlab.gnome.org/GNOME/gtk/issues/1280 .<br />
<br />
A patched version of GTK3 exists in AUR, which apparently fixes the tray icon bug: {{AUR|gtk3-mushrooms}} .<br />
<br />
=== Unit dbus-org.freedesktop.resolve1.service not found ===<br />
<br />
If {{ic|systemd-resolved.service}} is not started, NetworkManager will try to start it using D-Bus and fail:<br />
<br />
dbus-daemon[991]: [system] Activating via systemd: service name='org.freedesktop.resolve1' unit='dbus-org.freedesktop.resolve1.service' requested by ':1.23' (uid=0 pid=1012 comm="/usr/bin/NetworkManager --no-daemon ")<br />
dbus-daemon[991]: [system] Activation via systemd failed for unit 'dbus-org.freedesktop.resolve1.service': Unit dbus-org.freedesktop.resolve1.service not found.<br />
dbus-daemon[991]: [system] Activating via systemd: service name='org.freedesktop.resolve1' unit='dbus-org.freedesktop.resolve1.service' requested by ':1.23' (uid=0 pid=1012 comm="/usr/bin/NetworkManager --no-daemon ")<br />
<br />
This is because NetworkManager will try to send DNS information to [[systemd-resolved]] regardless of the {{ic|1=main.dns=}} setting in {{man|5|NetworkManager.conf}}.[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/d4eb4cb45f41b1751cacf71da558bf8f0988f383]<br />
<br />
This can be disabled with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/no-systemd-resolved.conf|2=<br />
[main]<br />
systemd-resolved=false<br />
}}<br />
<br />
See {{Bug|62138}}.<br />
<br />
=== Secrets were required, but not provided ===<br />
<br />
If you attempt to connect to a network using {{ic|nmcli device wifi connect ''SSID'' password ''password''}} and received the following error:<br />
<br />
Error: Connection activation failed: (7) Secrets were required, but not provided<br />
<br />
The error can be resolved by deleting the connection profile and creating a new one:<br />
<br />
$ nmcli connection delete ''SSID''<br />
$ nmcli device wifi connect ''SSID'' password ''password''<br />
<br />
=== WPA Enterprise connection with NetworkManager ===<br />
<br />
If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the [[iwd]] backend then you will get the following error from NetworkManager:<br />
<br />
Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)<br />
<br />
This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd config file {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[iwd#WPA Enterprise]].<br />
<br />
== See also ==<br />
<br />
* [https://blogs.gnome.org/dcbw/2015/02/16/networkmanager-for-administrators-part-1/ NetworkManager for Administrators Part 1]<br />
* [[Wikipedia:NetworkManager]]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Wicd&diff=597736Wicd2020-02-16T19:39:07Z<p>Progandy: Add out of date warning, wicd has been dropped.</p>
<hr />
<div>{{Out of date|wicd depends on python2 and is unmaintained. It has been removed from the repositories. [https://lists.archlinux.org/pipermail/arch-dev-public/2020-January/029787.html]}}<br />
<br />
[[Category:Network managers]]<br />
[[de:Wicd]]<br />
[[es:Wicd]]<br />
[[fr:Wicd]]<br />
[[it:Wicd]]<br />
[[ja:Wicd]]<br />
[[zh-hans:Wicd]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related articles end}}<br />
<br />
[https://launchpad.net/wicd Wicd] is a network connection manager that can manage wireless and wired interfaces, similar and an alternative to [[NetworkManager]]. Wicd is written in [[Python]] and [[GTK]]. Wicd can also run from the terminal in a curses interface, requiring no X server session or task panel (see [[#Running Wicd in Text Mode]]).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|wicd}}{{Broken package link|package not found}} package, or {{AUR|wicd-git}} for the development version. It includes everything needed to run the wicd daemon and the {{ic|wicd-cli}} and {{ic|wicd-curses}} interfaces.<br />
<br />
There is also an official GTK front-end, available as {{Pkg|wicd-gtk}}{{Broken package link|package not found}}.<br />
<br />
=== Notifications ===<br />
<br />
To enable visual notifications about network status, you need to install the packages {{Pkg|notification-daemon}} and {{AUR|python2-notify}}.<br />
<br />
If you are not using [[GNOME]], you may want to install {{Pkg|xfce4-notifyd}} instead of the notification-daemon, because it pulls a lot of unnecessary GNOME packages.<br />
<br />
== Getting started ==<br />
<br />
=== Initial setup ===<br />
<br />
Wicd provides a daemon that must be started. <br />
<br />
{{Warning | Running multiple network managers ''will'' cause problems, so it is important to ''disable all other network management daemons''.}}<br />
<br />
First, stop all previously running network daemons (like netctl, netcfg, dhcpcd, NetworkManager).<br />
<br />
Disable any existing network management services, including {{ic|netctl}}, {{ic|netcfg}}, {{ic|dhcpcd}}, and {{ic|networkmanager}}. Refer to [[Systemd#Using units]].<br />
<br />
{{Note|You might need to stop and disable the '''network''' daemon instead of '''netctl''', which is a current replacement for '''network''' service. If unsure, try disabling both.}}<br />
<br />
[[Start/enable]] the {{ic|wicd.service}} systemd unit.<br />
<br />
Add your account to '''users''' group:<br />
<br />
# gpasswd -a USERNAME users<br />
<br />
{{Note|The Unix group that D-Bus allows to access ''wicd'' is subject to change, and it may be different than ''users''. Check which policy group is specified in {{ic|/etc/dbus-1/system.d/wicd.conf}}, and add your user to that group.}}<br />
<br />
If you added your user to a new group, log out and then log in.<br />
<br />
=== Running Wicd in Desktop Environment===<br />
<br />
If you have installed the {{pkg|wicd-gtk}}{{Broken package link|package not found}} and entered the desktop environment. Open a virtual terminal to run one of the following commands.<br />
<br />
* To start Wicd as system service, [[start]] the {{ic|wicd.service}} systemd unit.<br />
<br />
* To load Wicd, run:<br />
<br />
$ wicd-client<br />
<br />
* To force it to start minimized in the notification area, run:<br />
<br />
$ wicd-client --tray<br />
<br />
* If your desktop environment does not have a notification area, or if you don't want wicd to show tray icon, run:<br />
<br />
$ wicd-client -n<br />
<br />
=== Running Wicd in Text Mode===<br />
<br />
If you did not install {{pkg|wicd-gtk}}{{Broken package link|package not found}} then use wicd-cli or wicd-curses:<br />
<br />
$ wicd-curses<br />
<br />
{{Note | Wicd does not prompt you for a passkey. To use encrypted connections (WPA/WEP), expand the network you want to connect to, click '''Advanced''' and enter the needed info.}}<br />
<br />
{{Note|''wicd-curses'' is less stable than ''wicd-gtk'', and is known to crash regularly. If a crash occurs when attempting to configure a wireless network, try {{AUR|wicd-patched}}}}<br />
<br />
=== Connecting with wicd-cli ===<br />
<br />
If wicd-curses is failing for some reason you can connect using wicd-cli.<br />
Wireless example (sudo may be required):<br />
<br />
scan networks:<br />
$ wicd-cli --wireless -S<br />
<br />
list networks:<br />
$ wicd-cli --wireless -l<br />
<br />
get network Bssid (use '#' index from previous command in place of '0')<br />
$ wicd-cli -n 0 -d<br />
<br />
select network (replace bssid with your network's bssid from previous command)<br />
$ wicd-cli -n 0 -p bssid "D0:13:FD:3F:78:4A"<br />
<br />
set network password or key (example is for passphrase, remove "s:" for key"<br />
$ wicd-cli -n 0 -p key s:"password"<br />
<br />
connect <br />
$ wicd-cli -n 0 -c<br />
<br />
=== Switching WPA supplicant driver ===<br />
<br />
''Wicd'' still suggests to "almost always" use Wext as WPA supplicant driver and defaults to it. This is [http://linuxwireless.org/en/developers/Documentation/Wireless-Extensions/index.html#Do_we_still_use_WE_.3F outdated behavior]. One should use nl80211 instead, except with old drivers that do not support it. The relevant option is located in ''Preferences > Advanced Settings''.<br />
<br />
=== Autostart ===<br />
<br />
The {{Pkg|wicd-gtk}}{{Broken package link|package not found}} package puts a file in {{ic|/etc/xdg/autostart/wicd-tray.desktop}}, which will autostart {{ic|wicd-client}} upon login to your DE/WM. If so, [[enable]] the {{ic|wicd}} systemd unit.<br />
<br />
If {{ic|/etc/xdg/autostart/wicd-tray.desktop}} does not exist, you can add '''wicd-client''' to your DE/WM startup to have the application start when you log in.<br />
<br />
{{Note|If '''wicd-client''' is added to DE/WM startup when {{ic|/etc/xdg/autostart/wicd-tray.desktop}} exists, you will have an issue of two {{ic|wicd-client}} instances running.}}<br />
<br />
=== Scripts ===<br />
<br />
Wicd has the ability to run scripts during all stages of the connection process (post/pre connect/disconnect).<br />
Simply place a script inside the relevant stage folder within {{ic|/etc/wicd/scripts/}} and make it executable.<br />
<br />
The scripts are able to receive three parameters, these being: <br />
$1 - the connection type (wireless/wired).<br />
$2 - the ESSID (network name).<br />
$3 - the BSSID (gateway MAC).<br />
<br />
==== Stop ARP spoofing attacks ====<br />
<br />
The script below can be used to set a static ARP, to stop ARP spoofing attacks.<br />
Simply change the values within the case statement to match those of the networks you want to set static ARP entries for. Launch it as root:<br />
<br />
#!/bin/bash<br />
#Set the parameters passed to this script to meaningful variable names.<br />
connection_type="$1"<br />
essid="$2"<br />
bssid="$3"<br />
<br />
if [ "${connection_type}" == "wireless" ]; then<br />
<br />
#Change below to match your networks.<br />
case "$essid" in<br />
YOUR-NETWORK-NAME-ESSID)<br />
arp -s 192.168.0.1 00:11:22:33:44:55<br />
;;<br />
Netgear01923)<br />
arp -s 192.168.0.1 10:11:20:33:40:50<br />
;;<br />
ANOTHER-ESSID)<br />
arp -s 192.168.0.1 11:33:55:77:99:00<br />
;;<br />
*)<br />
echo "Static ARP not set. No network defined."<br />
;;<br />
esac<br />
fi<br />
<br />
==== Change MAC using macchanger ====<br />
<br />
See [[MAC address spoofing#macchanger_2]].<br />
<br />
The script below can be used to change the MAC address of your network interfaces.<br />
<br />
To change the MAC whenever you connect to a network, place this script under {{ic|/etc/wicd/scripts/preconnect/}}.<br />
<br />
Take a look at {{ic|macchanger --help}} to adjust the macchanger command to your liking.<br />
<br />
{{bc|<nowiki><br />
#!/usr/bin/env bash<br />
<br />
connection_type="$1"<br />
<br />
if [[ "${connection_type}" == "wireless" ]]; then<br />
ip link set wlp2s0 down<br />
macchanger -A wlp2s0<br />
ip link set wlp2s0 up<br />
elif [[ "${connection_type}" == "wired" ]]; then<br />
ip link set enp1s0 down<br />
macchanger -A enp1s0<br />
ip link set enp1s0 up<br />
fi<br />
</nowiki>}}<br />
<br />
==== Start/stop openvpn client ====<br />
<br />
Put the following script in {{ic|/etc/wicd/scripts/postconnect/}}, to be able to restart openvpn client when wireless connected to specific ESSID, and replace the {{ic|YOUR_WIFI_ESSID}} with your ESSID.<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
<br />
ESSID="YOUR_WIFI_ESSID"<br />
<br />
if [ $1 == "wireless" ]; then<br />
if [ $2 == "$ESSID" ]; then<br />
systemctl restart openvpn-client@client<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
Put the following script in {{ic|/etc/wicd/scripts/predisconnect/}}, to stop openvpn client when wireless disconnected from specific ESSID and replace the {{ic|YOUR_WIFI_ESSID}} with your ESSID.<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
<br />
ESSID="YOUR_WIFI_ESSID"<br />
<br />
if [ $1 == "wireless" ]; then<br />
if [ $2 == "$ESSID" ]; then<br />
systemctl stop openvpn-client@client<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
== Troubleshooting ==<br />
<br />
See [[Network configuration#Troubleshooting]] for troubleshooting wired connections and [[Wireless network configuration#Troubleshooting]] for troubleshooting wireless connections. This section covers only problems specific to ''wicd''.<br />
<br />
=== Autoconnect on resume from hibernation/suspension ===<br />
<br />
If for some reasons autoconnect on resume from hibernation or suspension does not work automatically, you can manually restart Wicd by enabling the following service file for your user; see [[systemd/User#Basic setup]].<br />
<br />
{{hc|~/.config/systemd/user/wicd@resume.service|<nowiki><br />
[Unit]<br />
Description=Restart Wicd autoconnect service on resume<br />
After=suspend.target<br />
<br />
[Service]<br />
Type=oneshot<br />
User=%i<br />
RemainAfterExit=no<br />
ExecStart=/usr/share/wicd/daemon/autoconnect.py<br />
<br />
[Install]<br />
WantedBy=suspend.target<br />
</nowiki>}}<br />
<br />
=== Importing pynotify failed, notifications disabled ===<br />
<br />
In case the {{AUR|python2-notify}} package did not get installed automatically. You can [[install]] it from [[official repositories]].<br />
<br />
=== D-Bus connection error message ===<br />
<br />
If wicd suddenly stopped working and it complains about D-Bus, it is quite likely that you just need to remove wicd fully, including and all its configuration files, and re-install it from scratch by first removing {{pkg|wicd}}{{Broken package link|package not found}}. Then remove its configuration files:<br />
# rm -rf /etc/wicd /var/log/wicd /etc/dbus-1/system.d/wicd*<br />
Then reinstall the package.<br />
Check this link for more details: https://bbs.archlinux.org/viewtopic.php?pid=577141#p577141 <br />
<br />
Wicd-client also throws a D-Bus connection error message ("Could not connect to wicd's D-Bus interface.") when wicd is not running due to a problem with a config file. It seems that sometimes an empty account gets added to {{ic|/etc/wicd/wired-settings.conf}} in which case you simply have to remove the<br />
[] <br />
and restart wicd.<br />
<br />
If the above does not work, you could try https://bbs.archlinux.org/viewtopic.php?pid=1268721<br />
<br />
=== Problems after package update ===<br />
<br />
Sometimes the wicd client fails to load after a package update due to D-Bus errors. A solution is to [[stop]] {{ic|wicd.service}}, remove the configuration files in the {{ic|/etc/wicd/}} directory, and [[start]] {{ic|wicd.service}}.<br />
<br />
=== Note about graphical sudo programs ===<br />
<br />
If you are receiving an error about wicd failing to find a graphical sudo program, install {{Pkg|kdesu}} or {{AUR|ktsuss}}, then use the relative command:<br />
<br />
$ kdesu wicd-client -n<br />
<br />
$ ktsuss wicd-client -n<br />
<br />
=== Eduroam ===<br />
<br />
See [[Wireless network configuration#eduroam]].<br />
<br />
=== Two instances of wicd-client (and possibly two icons in tray) ===<br />
<br />
See the note in [[#Autostart]] about the autostart file in {{ic|/etc/xdg/autostart}} and the forum post and bug report provided in [[#See also]]. Essentially, if {{ic|/etc/xdg/autostart/wicd-tray.desktop}} exists, remove it. You only need the {{ic|wicd}} service enabled in systemd.<br />
<br />
=== Bad password using PEAP with TKIP/MS-CHAPv2 ===<br />
<br />
The connection template PEAP with TKIP/MS-CHAPv2 requires the user to enter the path to a CA certificate besides entering username and password. However this can cause troubles resulting in an error message of a bad password [https://bbs.archlinux.org/viewtopic.php?pid=990385]. A possible solution is the usage of PEAP with GTC instead of TKIP/MS-CHAPv2 which does not require one to enter the path of the CA cert.<br />
<br />
=== Wicd skips obtaining IP address on wlp ===<br />
<br />
This can be caused by dhcpcd running alongside wicd as systemd service. A solution would be to stop/disable '''dhcpcd'''.<br />
<br />
=== dhcpcd not running ===<br />
<br />
Normally it should not be required, nor recommended to run the dhcpcd service next to wicd. However, if you encounter the error message that dhcpcd is not running, then you can try [[start]]ing the {{ic|dhcpcd}} systemd unit and see if you encounter any incompatibilities when using both services at the same time.<br />
<br />
Alternatively, as a workaround you might consider switching to {{Pkg|dhclient}} in the Wicd settings.<br />
<br />
{{Note|If you get ''send_packet: Network is unreachable'' errors, then try increasing the timeout in /usr/share/dhclient/dhclient.conf.}}<br />
<br />
== See also ==<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=114803 Forum post] about two instances of wicd-client and {{ic|/etc/xdg/autostart}}<br />
* [https://bugs.archlinux.org/task/22423 Bug report mentioning /etc/xdg/autostart and wicd-client behavior]</div>Progandyhttps://wiki.archlinux.org/index.php?title=IPv6&diff=584542IPv62019-10-06T13:24:07Z<p>Progandy: /* For clients */ Add a note about configuring DNS. netctl with IP6=stateless needs an additional service.</p>
<hr />
<div>[[Category:Networking]]<br />
[[es:IPv6]]<br />
[[ja:IPv6]]<br />
[[pt:IPv6]]<br />
[[ru:IPv6]]<br />
[[zh-hans:IPv6]]<br />
{{Related articles start}}<br />
{{Related|IPv6 tunnel broker setup}}<br />
{{Related articles end}}<br />
<br />
In Arch Linux, IPv6 is enabled by default.<br />
<br />
== Neighbor discovery ==<br />
<br />
Pinging the multicast address {{ic|ff02::1}} results in all hosts in link-local scope responding. An interface has to be specified:<br />
<br />
$ ping ff02::1%eth0<br />
<br />
After that, you can get a list of all the neighbors in the local network with:<br />
<br />
$ ip -6 neigh<br />
<br />
With a ping to the multicast address {{ic|ff02::2}} only routers will respond.<br />
<br />
If you add an option {{ic|-I ''your-global-ipv6''}}, link-local hosts will respond with their link-global scope addresses. The interface can be omitted in this case:<br />
<br />
$ ping -I 2001:4f8:fff6::21 ff02::1<br />
<br />
== Stateless autoconfiguration (SLAAC) ==<br />
<br />
The easiest way to acquire an IPv6 address as long as your network is configured is through ''Stateless address autoconfiguration'' (SLAAC for short). The address is automatically inferred from the prefix that your router advertises and requires neither further configuration nor specialized software such as a DHCP client.<br />
<br />
=== For clients ===<br />
<br />
If you are using [[netctl]] you just need to add the following line to your ethernet or wireless configuration.<br />
<br />
IP6=stateless<br />
<br />
If you are using [[NetworkManager]] then it automatically enables IPv6 addresses if there are advertisements for them in the network.<br />
<br />
Please note that stateless autoconfiguration works on the condition that IPv6 icmp packets are allowed throughout the network. So for the client side the {{ic|ipv6-icmp}} packets must be accepted. If you are using the [[Simple stateful firewall]]/[[iptables]] you only need to add:<br />
<br />
-A INPUT -p ipv6-icmp -j ACCEPT<br />
<br />
If you are using an other firewall frontend (ufw, shorewall, etc) consult their documentation on how to enable the {{ic|ipv6-icmp}} packets.<br />
<br />
If your chosen network management solution does not support configuring the DNS resolver with stateless IPv6 (e.g. netctl), then it is possible to use {{man|8|rdnssd}} from the {{pkg|ndisc6}} package for that.<br />
<br />
=== For gateways ===<br />
<br />
To properly hand out IPv6s to the network clients we will need to use an advertising daemon. The standard tool for this job is {{Pkg|radvd}} and is available in [[official repositories]]. Configuration of radvd is fairly simple. Edit {{ic|/etc/radvd.conf}} to include<br />
<br />
# replace LAN with your LAN facing interface<br />
interface LAN {<br />
AdvSendAdvert on;<br />
MinRtrAdvInterval 3;<br />
MaxRtrAdvInterval 10;<br />
prefix ::/64 {<br />
AdvOnLink on;<br />
AdvAutonomous on;<br />
AdvRouterAddr on;<br />
};<br />
};<br />
<br />
The above configuration will tell clients to autoconfigure themselves using addresses from the advertised /64 block. Please note that the above configuration advertises ''all available prefixes'' assigned to the LAN facing interface. If you want to limit the advertised prefixes instead of {{ic|::/64}} use the desired prefix, eg {{ic|2001:DB8::/64}}. The {{ic|prefix}} block can be repeated many times for more prefixes.<br />
<br />
The gateway must also allow the traffic of {{ic|ipv6-icmp}} packets on all basic chains. For the [[Simple stateful firewall]]/[[iptables]] add:<br />
<br />
-A INPUT -p ipv6-icmp -j ACCEPT<br />
-A OUTPUT -p ipv6-icmp -j ACCEPT<br />
-A FORWARD -p ipv6-icmp -j ACCEPT<br />
<br />
Adjust accordingly for other firewall frontends and do not forget to enable {{ic|radvd.service}}.<br />
<br />
== Privacy extensions ==<br />
<br />
When a client acquires an address through SLAAC its IPv6 address is derived from the advertised prefix and the MAC address of the network interface of the client. This may raise security concerns as the MAC address of the computer can be easily derived by the IPv6 address. In order to tackle this problem the ''IPv6 Privacy Extensions'' standard ([https://tools.ietf.org/html/rfc4941 RFC 4941]) has been developed. With privacy extensions the kernel generates a ''temporary'' address that is mangled from the original autoconfigured address. Private addresses are preferred when connecting to a remote server so the original address is hidden. To enable Privacy Extensions reproduce the following steps:<br />
<br />
Add these lines to {{ic|/etc/sysctl.d/40-ipv6.conf}}:<br />
<br />
# Enable IPv6 Privacy Extensions<br />
net.ipv6.conf.all.use_tempaddr = 2<br />
net.ipv6.conf.default.use_tempaddr = 2<br />
net.ipv6.conf.''nic0''.use_tempaddr = 2<br />
...<br />
net.ipv6.conf.''nicN''.use_tempaddr = 2<br />
<br />
Where {{ic|nic0}} to {{ic|nicN}} are your '''N'''etwork '''I'''nterface '''C'''ards. You can find their names using the instructions in [[Network configuration#Listing network interfaces]]. The {{ic|all.use_tempaddr}} or {{ic|default.use_tempaddr}} parameters are not applied to nic's that already exist when the [[sysctl]] settings are executed. <br />
<br />
After a reboot, at the latest, Privacy Extensions should be enabled.<br />
<br />
=== dhcpcd ===<br />
<br />
[[dhcpcd]] includes in its default configuration file since version 6.4.0 the option {{ic|slaac private}}, which enables "Stable Private IPv6 Addresses instead of hardware based ones", implementing [https://tools.ietf.org/html/rfc7217 RFC 7217] ([http://roy.marples.name/projects/dhcpcd/info/8aa9dab00dc72c453aeccbde885ecce27a3d81ff commit]). Therefore, it is not necessary to change anything, except if it is desired to change of IPv6 address more often than each time the system is connected to a new network. Set it to {{ic|slaac hwaddr}} for a stable address.<br />
<br />
=== NetworkManager ===<br />
<br />
NetworkManager does not honour the settings placed in {{ic|/etc/sysctl.d/40-ipv6.conf}}. This can be verified by running {{ic|$ ip -6 addr show ''interface''}} after rebooting: no {{ic|scope global '''temporary'''}} address appears besides the regular one.<br />
<br />
To enable IPv6 Privacy Extensions by default, add these lines to {{ic|/etc/NetworkManager/NetworkManager.conf}}<br />
<br />
{{hc|/etc/NetworkManager/NetworkManager.conf|2=<br />
...<br />
'''[connection]'''<br />
'''ipv6.ip6-privacy=2'''<br />
}}<br />
<br />
In order to enable IPv6 Privacy Extensions for individual NetworkManager-managed connections, edit the desired connection keyfile in {{ic|/etc/NetworkManager/system-connections/}} and append to its {{ic|[ipv6]}} section the key-value pair {{ic|1=ip6-privacy=2}}:<br />
<br />
{{hc|/etc/NetworkManager/system-connections/''example_connection''|2=<br />
...<br />
[ipv6]<br />
method=auto<br />
'''ip6-privacy=2'''<br />
}}<br />
<br />
{{Note|Although it may seem the {{ic|scope global temporary}} IPv6 address created by enabling Privacy Extensions never gets renewed (it never shifts to {{ic|deprecated}} status at the term of its {{ic|valid_lft}} lifetime), it is to be verified over a longer period of time that this address '''does''' indeed change.}}<br />
<br />
=== systemd-networkd ===<br />
<br />
Systemd-networkd also does not honor the settings {{ic|net.ipv6.conf.xxx.use_tempaddr}} placed in {{ic|/etc/sysctl.d/40-ipv6.conf}} unless the option {{ic|IPv6PrivacyExtensions}} is set with the value {{ic|kernel}} in the .network file(s). <br />
<br />
Other options for the IPv6 Privacy Extensions like:<br />
<br />
net.ipv6.conf.xxx.temp_prefered_lft<br />
net.ipv6.conf.xxx.temp_valid_lft<br />
<br />
are honored, however.<br />
<br />
{{Note|{{ic|temp_prefered_lft}} is the variable name, preferred has to be misspelled.}}<br />
<br />
See [[systemd-networkd]] and {{man|5|systemd.network}} for details.<br />
<br />
=== connman ===<br />
<br />
{{Out of date|{{ic|IPv6.privacy}} is not supported in the {{ic|[global]}} section.|section=IPv6#connman}}<br />
<br />
Add to {{ic|/var/lib/connman/settings}} under the global section:<br />
<br />
[global]<br />
IPv6.privacy=preferred<br />
<br />
== Stable private addresses ==<br />
<br />
Another option is a stable private IP address ([https://tools.ietf.org/html/rfc7217 RFC 7217]). This allows for IPs that are stable within a network without exposing the MAC address of the interface.<br />
<br />
In order to have the kernel generate a key (for {{ic|wlan0}}, for example) we can set:<br />
<br />
sysctl net.ipv6.conf.wlan0.addr_gen_mode=3<br />
<br />
Bring the interface down and up and you should see {{ic|stable-privacy}} next to each IPv6 address after running {{ic|ip addr show dev wlan0}}. The kernel has generated a 128-bit secret for generating ip addresses for this interface, to see it run {{ic|sysctl net.ipv6.conf.wlan0.stable_secret}}. We're going to persist this value so add the following lines to {{ic|/etc/sysctl.d/40-ipv6.conf}}:<br />
<br />
# Enable IPv6 stable privacy mode<br />
net.ipv6.conf.wlan0.stable_secret = <output from previous command><br />
net.ipv6.conf.wlan0.addr_gen_mode = 2<br />
<br />
=== NetworkManager ===<br />
<br />
The above settings are not honored by NetworkManager, but NetworkManager uses stable private addresses by default.<br />
<br />
== Static address ==<br />
<br />
Sometimes, using a static address can improve security. For example, if your local router uses Neighbor Discovery or radvd ([http://www.apps.ietf.org/rfc/rfc2461.html RFC 2461]), your interface will automatically be assigned an address based on its MAC address (using IPv6's Stateless Autoconfiguration). This may be less than ideal for security since it allows a system to be tracked even if the network portion of the IP address changes.<br />
<br />
To assign a static IP address using [[netctl]], look at the example profile in {{ic|/etc/netctl/examples/ethernet-static}}. The following lines are important:<br />
<br />
...<br />
# For IPv6 static address configuration<br />
IP6=static<br />
Address6=('1234:5678:9abc:def::1/64' '1234:3456::123/96')<br />
Routes6=('abcd::1234')<br />
Gateway6='1234:0:123::abcd'<br />
<br />
{{Note|1=If you are connected IPv6-only, then you need to determine your IPv6 DNS server. For example:<br />
<br />
DNS=('6666:6666::1' '6666:6666::2')<br />
<br />
If your provider did not give you IPv6 DNS and you are not running your own, you can choose from the [[resolv.conf]] article. <br />
}}<br />
<br />
== IPv6 and PPPoE ==<br />
<br />
The standard tool for PPPoE, {{ic|pppd}}, provides support for IPv6 on PPPoE as long as your ISP and your modem support it. Just add the following to {{ic|/etc/ppp/options}}<br />
<br />
+ipv6<br />
<br />
If you are using [[netctl]] for PPPoE then just add the following to your netctl configuration instead<br />
<br />
PPPoEIP6=yes<br />
<br />
== Prefix delegation (DHCPv6-PD) ==<br />
<br />
{{Note|This section is targeted towards custom gateway configuration, not client machines. For standard market routers please consult the documentation of your router on how to enable prefix delegation.}}<br />
<br />
Prefix delegation is a common IPv6 deployment technique used by many ISPs. It is a method of assigning a network prefix to a user site (ie. local network). A router can be configured to assign different network prefixes to various subnetworks. The ISP hands out a network prefix using DHCPv6 (usually a {{ic|/56}} or {{ic|/64}}) and a dhcp client assigns the prefixes to the local network. For a simple two interface gateway it practically assigns an IPv6 prefix to the interface connected to to the local network from an address acquired through the interface connected to WAN (or a pseudo-interface such as ppp).<br />
<br />
=== With dibbler ===<br />
<br />
[http://klub.com.pl/dhcpv6/ Dibbler] is a portable DHCPv6 client and server which can be used for Prefix delegation. It can be [[install]]ed with {{AUR|dibbler}} package.<br />
<br />
If you are using {{ic|dibbler}} edit {{ic|/etc/dibbler/client.conf}}<br />
<br />
log-mode short<br />
log-level 7<br />
# use the interface connected to your WAN<br />
iface "WAN" {<br />
ia<br />
pd<br />
}<br />
<br />
{{Tip|Read {{man|8|dibbler-client|url=}} for more information.}}<br />
<br />
=== With dhcpcd ===<br />
<br />
[[dhcpcd]] apart from IPv4 dhcp support also provides a fairly complete implementation of the DHCPv6 client standard which includes DHCPv6-PD. If you are using {{ic|dhcpcd}} edit {{ic|/etc/dhcpcd.conf}}. You might already be using dhcpcd for IPv4 so just update your existing configuration.<br />
<br />
duid<br />
noipv6rs<br />
waitip 6<br />
# Uncomment this line if you are running dhcpcd for IPv6 only.<br />
#ipv6only<br />
<br />
# use the interface connected to WAN<br />
interface WAN<br />
ipv6rs<br />
iaid 1<br />
# use the interface connected to your LAN<br />
ia_pd 1 LAN<br />
#ia_pd 1/::/64 LAN/0/64<br />
<br />
This configuration will ask for a prefix from WAN interface ({{ic|WAN}}) and delegate it to the internal interface ({{ic|LAN}}).<br />
In the event that a {{ic|/64}} range is issued, you will need to use the 2nd {{ic|ia_pd instruction}} that is commented out instead.<br />
It will also disable router solicitations on all interfaces except for the WAN interface ({{ic|WAN}}).<br />
<br />
{{Tip|Also read {{man|8|dhcpcd}} and {{man|5|dhcpcd.conf}}.}}<br />
<br />
=== With WIDE-DHCPv6 ===<br />
<br />
[http://wide-dhcpv6.sourceforge.net/ WIDE-DHCPv6] is an open-source implementation of Dynamic Host Configuration Protocol for IPv6 (DHCPv6) originally developed by the KAME project. It can be [[install]]ed with {{AUR|wide-dhcpv6}}.<br />
<br />
If you are using {{ic|wide-dhcpv6}} edit {{ic|/etc/wide-dhcpv6/dhcp6c.conf}}<br />
<br />
# use the interface connected to your WAN<br />
interface WAN {<br />
send ia-pd 0;<br />
};<br />
<br />
id-assoc pd 0 {<br />
# use the interface connected to your LAN<br />
prefix-interface LAN {<br />
sla-id 1;<br />
sla-len 8;<br />
};<br />
};<br />
<br />
{{Note|1={{ic|sla-len}} should be set so that {{ic|1=(WAN-prefix) + (sla-len) = 64}}. In this case it is set up for a {{ic|/56}} prefix 56+8=64. For a {{ic|/64}} prefix {{ic|sla-len}} should be {{ic|0}}.}}<br />
<br />
The wide-dhcpv6 client can be [[started/enabled]] using the {{ic|dhcp6c@''interface''.service}} systemd unit file, where {{ic|''interface''}} is the interface name in the configuration file, e.g. for a interface name "WAN" use {{ic|dhcp6c@WAN.service}}.<br />
<br />
{{Tip|Read {{man|8|dhcp6c|url=}} and {{man|5|dhcp6c.conf|url=}} for more information.}}<br />
<br />
=== Other clients ===<br />
<br />
[[systemd-networkd]] claims to be capable of DHCPv6-PD but is lacking documentation on how to do it.<br />
<br />
[[dhclient]] can also request a prefix, but assigning that prefix, or parts of that prefix to interfaces must be done using a dhclient exit script. For example: https://github.com/jaymzh/v6-gw-scripts/blob/master/dhclient-ipv6.<br />
<br />
== Disable IPv6 ==<br />
<br />
{{Note|The Arch kernel has IPv6 support built in directly, therefore a module cannot be blacklisted.}}<br />
<br />
{{Expansion|Add reasons why users may want to disable IPv6, such as low-quality DNS servers or firewall rules}}<br />
<br />
=== Disable functionality ===<br />
<br />
{{Warning|Disabling the IPv6 stack can break certain programs which expect it to be enabled. {{bug|46297}}}}<br />
<br />
Adding {{ic|1=ipv6.disable=1}} to the kernel line disables the whole IPv6 stack, which is likely what you want if you are experiencing issues. See [[Kernel parameters]] for more information.<br />
<br />
Alternatively, adding {{ic|1=ipv6.disable_ipv6=1}} instead will keep the IPv6 stack functional but will not assign IPv6 addresses to any of your network devices.<br />
<br />
One can also avoid assigning IPv6 addresses to specific network interfaces by adding the following sysctl config to {{ic|/etc/sysctl.d/40-ipv6.conf}}:<br />
<br />
# Disable IPv6<br />
net.ipv6.conf.all.disable_ipv6 = 1<br />
net.ipv6.conf.''nic0''.disable_ipv6 = 1<br />
...<br />
net.ipv6.conf.''nicN''.disable_ipv6 = 1<br />
<br />
Note that you must list all of the targeted interfaces explicitly, as disabling {{ic|all.disable_ipv6}} does not apply to interfaces that are already "up" when sysctl settings are applied.<br />
<br />
Note 2, if disabling IPv6 by sysctl, you should comment out the IPv6 hosts in your {{ic|/etc/hosts}}:<br />
<br />
#<ip-address> <hostname.domain.org> <hostname><br />
127.0.0.1 localhost.localdomain localhost<br />
#::1 localhost.localdomain localhost<br />
<br />
otherwise there could be some connection errors because hosts are resolved to their IPv6 address which is not reachable.<br />
<br />
=== Other programs ===<br />
<br />
Disabling IPv6 functionality in the kernel does not prevent other programs from trying to use IPv6. In most cases, this is completely harmless, but if you find yourself having issues with that program, you should consult the program's manual pages for a way to disable that functionality.<br />
<br />
==== dhcpcd ====<br />
<br />
''dhcpcd'' will continue to harmlessly attempt to perform IPv6 router solicitation. To disable this, as stated in the {{man|5|dhcpcd.conf}} [[man page]], add the following to {{ic|/etc/dhcpcd.conf}}:<br />
<br />
noipv6rs<br />
noipv6<br />
<br />
==== NetworkManager ====<br />
<br />
{{Style|Specific approach to disable via GUI}}<br />
<br />
To disable IPv6 in NetworkManager, right click the network status icon, and select ''Edit Connections > Wired > ''Network name'' > Edit > IPv6 Settings > Method > Ignore/Disabled''<br />
<br />
Then click "Save".<br />
<br />
==== ntpd ====<br />
<br />
Following advice in [[systemd#Drop-in files]], [[edit]] {{ic|ntpd.service}} to define how systemd starts it.<br />
<br />
This will create a drop-in snippet that will be run instead of the default {{ic|ntpd.service}}. The {{ic|-4}} flag prevents IPv6 from being used by the ntp daemon. Put the following into the drop-in snippet:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/ntpd -4 -g -u ntp:ntp<br />
<br />
which first clears the previous {{ic|ExecStart}}, and then replaces it with one that includes the {{ic|-4}} flag.<br />
<br />
=== systemd-networkd ===<br />
<br />
networkd supports disabling IPv6 on a per-interface basis. When a network unit's {{ic|[Network]}} section has either {{ic|1=LinkLocalAddressing=ipv4}} or {{ic|1=LinkLocalAddressing=no}}, networkd will not try to configure IPv6 on the matching interfaces.<br />
<br />
Note however that even when using the above option, networkd will still be expecting to receive router advertisements if IPv6 is not disabled globally. If IPv6 traffic is not being received by the interface (e.g. due to sysctl or ip6tables settings), it will remain in the configuring state and potentially cause timeouts for services waiting for the network to be fully configured. To avoid this, the {{ic|1=IPv6AcceptRA=no}} option should also be set in the {{ic|[Network]}} section.<br />
<br />
== Prefer IPv4 over IPv6 ==<br />
<br />
{{Accuracy|This disables the other default rules. [https://serverfault.com/a/93782/]|section=Factual accuracy - Prefer IPv4 over IPv6}}<br />
<br />
Uncomment the following line in {{ic|/etc/gai.conf}}:<br />
#<br />
# For sites which prefer IPv4 connections change the last line to<br />
#<br />
precedence ::ffff:0:0/96 100<br />
<br />
== See also ==<br />
<br />
* [https://www.kernel.org/doc/Documentation/networking/ipv6.txt IPv6] - kernel.org documentation<br />
* [http://www.ipsidixit.net/2012/08/09/ipv6-temporary-addresses-and-privacy-extensions/ IPv6 temporary addresses] - a summary about temporary addresses and privacy extensions<br />
* [http://tldp.org/HOWTO/Linux+IPv6-HOWTO/ch03s02.html IPv6 prefixes] - a summary of prefix types<br />
* [http://tldp.org/HOWTO/Linux+IPv6-HOWTO/ch11s02.html net.ipv6 options] - documentation of kernel parameters</div>Progandyhttps://wiki.archlinux.org/index.php?title=HiDPI&diff=570513HiDPI2019-04-05T11:31:41Z<p>Progandy: /* See also */ Link to an article about Mixed DPI and the X Window System</p>
<hr />
<div>[[Category:Graphics]]<br />
[[ja:HiDPI]]<br />
[[zh-hans:HiDPI]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related articles end}}<br />
HiDPI (High Dots Per Inch) displays, also known by Apple's "[[wikipedia:Retina Display|Retina Display]]" marketing name, are screens with a high resolution in a relatively small format. They are mostly found in high-end laptops and monitors.<br />
<br />
Not all software behaves well in high-resolution mode yet. Here are listed most common tweaks which make work on a HiDPI screen more pleasant.<br />
<br />
== Desktop environments ==<br />
<br />
=== GNOME ===<br />
To enable HiDPI, ''Settings > Devices > Displays'',or use gsettings:<br />
<br />
$ gsettings set org.gnome.desktop.interface scaling-factor 2<br />
<br />
{{Note|1={{ic|scaling-factor}} only allows whole numbers to be set. 1 = 100%, 2 = 200%, etc...}}<br />
<br />
==== Fractional Scaling ====<br />
<br />
A setting of {{ic|2, 3, etc}}, which is all you can do with {{ic|scaling-factor}}, may not be ideal for certain HiDPI displays and smaller screens (e.g. small tablets). <br />
<br />
* Wayland<br />
<br />
Enable fractional Scaling experimental-feature:<br />
<br />
$ gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"<br />
<br />
then open ''Settings > Devices > Displays'' (the new options may only appear after a restart)<br />
<br />
* Xorg<br />
<br />
You can achieve any non-integer scale factor by using a combination of GNOME's {{ic|scaling-factor}} and [[xrandr]]. This combination keeps the TTF fonts properly scaled so that they do not become blurry if using {{ic|xrandr}} alone. You specify zoom-in factor with {{ic|gsettings}} and zoom-out factor with [[xrandr]].<br />
<br />
First scale GNOME up to the minimum size which is too big. Usually "2" is already too big, otherwise try "3" etc. Then start scaling down by setting zoom-out factor with [[xrandr]]. First get the relevant output name, the examples below use {{ic|eDP1}}. Start e.g. with zoom-out 1.25 times. If the UI is still too big, increase the scale factor; if it is too small decrease the scale factor.<br />
<br />
$ xrandr --output eDP1 --scale 1.25x1.25<br />
<br />
{{Note|To allow the mouse to reach the whole screen, you may need to use the {{ic|--panning}} option as explained in [[#Side display]].}}<br />
<br />
{{Accuracy|The following was initially added under [[#X Resources]]. Clarify how it integrates with the info there or that above for GNOME.|section=GNOME ignores X settings}}<br />
<br />
GNOME ignores X settings due to its xsettings Plugin in Gnome Settings Daemon, where DPI setting is hard coded.<br />
There is blog entry for [http://blog.drtebi.com/2012/12/changing-dpi-setting-on-gnome-34.html recompiling Gnome Settings Daemon].<br />
In the source documentation there is another way mentioned to set X settings DPI:<br />
<br />
You can use the dconf Editor and navigate to key <br />
<br />
/org/gnome/settings-daemon/plugins/xsettings/overrides<br />
<br />
and complement the entry with the value<br />
<br />
'Xft/DPI': <153600><br />
<br />
From README.xsettings<br />
<br />
Noting that variants must be specified in the usual way (wrapped in <>).<br />
<br />
Note also that DPI in the above example is expressed in 1024ths of an inch.<br />
<br />
==== Text Scaling ====<br />
<br />
Alternatively or additionally to above solution, you can scale only text by factor not limited by whole numbers, for example:<br />
<br />
$ gsettings set org.gnome.desktop.interface text-scaling-factor 1.5<br />
<br />
=== KDE ===<br />
<br />
You can use KDE's settings to fine tune font, icon, and widget scaling. This solution affects both Qt and Gtk+ applications.<br />
<br />
To adjust font, widget, and icon scaling together:<br />
<br />
# ''System Settings > Display and Monitor > Display Configuration > Scale Display''<br />
# Drag the slider to the desired size<br />
# Restart for the settings to take effect<br />
<br />
To adjust only font scaling:<br />
<br />
# ''System Settings > Fonts''<br />
# Check "Force fonts DPI" and adjust the DPI level to the desired value. This setting should take effect immediately for newly started applications. You will have to logout and login for it to take effect on Plasma desktop.<br />
<br />
To adjust only icon scaling:<br />
<br />
# ''System Settings > Icons > Advanced''<br />
# Choose the desired icon size for each category listed. This should take effect immediately.<br />
<br />
'''Display Scale not integer bug :'''<br />
<br />
When you use not integer values for Display Scale it causes font render issue in some QT application ( ex. Okular ).<br />
<br />
A workaround for this is to:<br />
<br />
# Set the scale value to {{ic|1}}<br />
# Adjust your font and icons and use the "Force fonts DPI" ( this affects all apps, also GTK but not create issue with the fonts )<br />
# Restart KDE<br />
# If required tune the GTK apps using the variables {{ic|GDK_SCALE}}/{{ic|GDK_DPI_SCALE}} (as described above)<br />
<br />
==== Tray icons with fixed size ====<br />
<br />
The tray icons are not scaled with the rest of the desktop, since Plasma ignores the Qt scaling settings by default. To make Plasma respect the Qt settings, set {{ic|PLASMA_USE_QT_SCALING}} to {{ic|1}}.<br />
<br />
=== Xfce ===<br />
<br />
Xfce uses the DPI given by the X server. There is an option to override Font DPI (''Settings Manager > Appearance > Fonts > DPI > Custom DPI setting'') but it's better to adjust X server DPI instead. See [[Xorg#Display size and DPI]] for how to fix it.<br />
<br />
To enlarge icons in system tray, ''right-click on it (aim for empty space / top pixels / bottom pixels, so that you will not activate icons themselves) > Properties'', set “Maximum icon size” to 32, 48 or 64.<br />
<br />
Xfwm comes with two hidpi themes: Default-hdpi and Default-xhdpi. You can set them under ''Settings Manager > Window Manager > Style > Theme''.<br />
<br />
You can set the default icon sizes of gtk2 menus, buttons and so on under ''Settings Manager > Settings Editor > xsettings > Gtk > IconSizes'', with a line like this: {{ic|1=gtk-large-toolbar=96,96:gtk-small-toolbar=64,64:gtk-menu=64,64:gtk-dialog=96,96:gtk-button=64,64:gtk-dnd=64,64}}. "gtk-dnd" is for the icons during drag'n'drop, the others are quite self-explanatory. You can use any value your icon theme supports.<br />
<br />
=== Cinnamon ===<br />
<br />
Has good support out of the box.<br />
<br />
=== Enlightenment ===<br />
<br />
For E18, go to the E Setting panel. In ''Look > Scaling'', you can control the UI scaling ratios. A ratio of 1.2 seems to work well for the native resolution of the MBPr 15" screen.<br />
<br />
== X Server ==<br />
<br />
Some programs use the DPI given by the X server. Examples are i3 ([https://github.com/i3/i3/blob/next/libi3/dpi.c source]) and Chromium ([https://code.google.com/p/chromium/codesearch#chromium/src/ui/views/widget/desktop_aura/desktop_screen_x11.cc source]).<br />
<br />
To verify that the X Server has properly detected the physical dimensions of your monitor, use the ''xdpyinfo'' utility from the {{Pkg|xorg-xdpyinfo}} package:<br />
<br />
{{hc|$ xdpyinfo {{!}} grep -B 2 resolution|<br />
screen #0:<br />
dimensions: 3200x1800 pixels (423x238 millimeters)<br />
resolution: 192x192 dots per inch<br />
}}<br />
<br />
This example uses inaccurate dimensions (423mm x 328mm, even though the Dell XPS 9530 has 346mm x 194mm) to have a clean multiple of 96 dpi, in this case 192 dpi. This tends to work better than using the correct DPI — Pango renders fonts crisper in i3 for example.<br />
<br />
If the DPI displayed by xdpyinfo is not correct, see [[Xorg#Display size and DPI]] for how to fix it.<br />
<br />
== X Resources ==<br />
<br />
If you are not using a desktop environment such as KDE, Xfce, or other that manipulates the X settings for you, you can set the desired DPI setting manually via the {{ic|Xft.dpi}} variable in [[Xresources]]:<br />
<br />
{{hc|~/.Xresources|2=<br />
Xft.dpi: 180<br />
Xft.autohint: 0<br />
Xft.lcdfilter: lcddefault<br />
Xft.hintstyle: hintfull<br />
Xft.hinting: 1<br />
Xft.antialias: 1<br />
Xft.rgba: rgb<br />
}}<br />
<br />
Make sure the settings are loaded properly when X starts, for instance in your {{ic|~/.xinitrc}} with {{ic|xrdb -merge ~/.Xresources}} (see [[Xresources]] for more information).<br />
<br />
This will make the font render properly in most toolkits and applications, it will however not affect things such as icon size!<br />
Setting {{ic|Xft.dpi}} at the same time as toolkit scale (e.g. {{ic|GDK_SCALE}}) may cause interface elements to be much larger than intended in some programs like firefox.<br />
<br />
== GUI toolkits ==<br />
<br />
=== Qt 5 ===<br />
<br />
Since Qt 5.6, Qt 5 applications can be instructed to honor screen DPI by setting the {{ic|QT_AUTO_SCREEN_SCALE_FACTOR}} environment variable:<br />
<br />
export QT_AUTO_SCREEN_SCALE_FACTOR=1<br />
<br />
If automatic detection of DPI does not produce the desired effect, scaling can be set manually per-screen ({{ic|QT_SCREEN_SCALE_FACTORS}}) or globally ({{ic|QT_SCALE_FACTOR}}). For more details see the [https://blog.qt.io/blog/2016/01/26/high-dpi-support-in-qt-5-6/ Qt blog post].<br />
<br />
{{Note|<br />
* If you manually set the screen factor, it is important to set {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} otherwise some applications which explicitly force high DPI enabling get scaled twice.<br />
* {{ic|QT_SCALE_FACTOR}} scales fonts, but {{ic|QT_SCREEN_SCALE_FACTORS}} does not scale fonts.<br />
* If you also set the font DPI manually in ''xrdb'' to support other toolkits, {{ic|QT_SCALE_FACTORS}} will give you huge fonts.<br />
* If you have multiple screens of differing DPI ie: [[#Side display]] you may need to do {{ic|1=QT_SCREEN_SCALE_FACTORS="2;2"}}<br />
}}<br />
<br />
An [https://bugreports.qt.io/browse/QTBUG-53022 alternative] is e.g.:<br />
<br />
QT_FONT_DPI=96 vym<br />
<br />
=== GDK 3 (GTK+ 3) ===<br />
<br />
If you are using a window manager other than Gnome and have scaled the fonts using Xft.dpi, you must tell GDK to scale the UI as well. This will result in a further increase of the font-size for GDK apps, so you must undo the scaling of the text only.<br />
<br />
To scale UI elements by a factor of two:<br />
<br />
export GDK_SCALE=2<br />
<br />
To undo scaling of text:<br />
<br />
export GDK_DPI_SCALE=0.5<br />
<br />
=== GTK+ 2 ===<br />
<br />
Scaling of UI elements is not supported by the toolkit itself, however it's possible to generate a theme with elements pre-scaled for HiDPI display using {{AUR|oomox-git}}.<br />
<br />
=== Elementary (EFL) ===<br />
<br />
To scale UI elements by a factor of 1.5:<br />
<br />
export ELM_SCALE=1.5<br />
<br />
For more details see https://phab.enlightenment.org/w/elementary/<br />
<br />
== Boot managers ==<br />
<br />
=== GRUB ===<br />
<br />
==== Lower the framebuffer resolution ====<br />
<br />
Set a lower resolution for the framebuffer as explained in [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
==== Change GRUB font size ====<br />
<br />
Find a ttf font that you like in {{ic|/usr/share/fonts/}}.<br />
<br />
Convert the font to a format that GRUB can utilize:<br />
<br />
# grub-mkfont -s 30 -o /boot/grubfont.pf2 /usr/share/fonts/FontFamily/FontName.ttf<br />
<br />
{{Note|Change the {{ic|-s 30}} parameter to modify the font size}}<br />
<br />
Edit {{ic|/etc/default/grub}} to set the new font as shown in [[GRUB/Tips and tricks#Background image and bitmap fonts]]:<br />
<br />
GRUB_FONT="/boot/grubfont.pf2"<br />
<br />
Update GRUB configuration by running {{ic|grub-mkconfig -o /boot/grub/grub.cfg}}<br />
<br />
== Applications ==<br />
<br />
{{Accuracy|{{ic|--force-device-scale-factor}} only works on Chromium based (including Electron) applications.}}<br />
<br />
As a general rule, applications can be launched with a custom scaling value, e.g. {{ic|1=$ atom --force-device-scale-factor=2}}. A more permanent solution is to add this scaling factor as a flag to the relevant .conf or .desktop file (normally located at {{ic|/usr/share/applications/}}). In the latter instance, the flag should be added to the line beginning with "Exec=", e.g. {{ic|1=Exec=/usr/bin/atom --force-device-scale-factor=2 %F}}. The next section provides more details on implementing this for specific applications.<br />
<br />
=== Atom ===<br />
<br />
Add {{ic|1=--force-device-scale-factor=2}} as a flag to the atom.desktop file:<br />
<br />
{{hc|/usr/share/applications/atom.desktop|2=<br />
Exec=/usr/bin/atom --force-device-scale-factor=2 %F<br />
}}<br />
<br />
=== Browsers ===<br />
<br />
==== Firefox ====<br />
<br />
Firefox should use the [[#GDK 3 (GTK+ 3)]] settings. However, the suggested {{ic|GDK_SCALE}} suggestion does not consistently scale the entirety of Firefox, and does not work for fractional values (e.g., a factor of 158DPI/96DPI = 1.65 for a 1080p 14" laptop). You may want to use {{ic|GDK_DPI_SCALE}} instead. Another option, which will avoid Firefox-specific settings in many setups is to use the settings in [[#X Resources]] as Firefox should respect the {{ic|Xft.dpi}} value defined there.<br />
<br />
To override those, open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|layout.css.devPixelsPerPx}} to {{ic|2}} (or find the one that suits you better; {{ic|2}} is a good choice for Retina screens), but it also does not consistently scale the entirety of Firefox. If Firefox is not scaling fonts, you may want to create {{ic|userChrome.css}} and add appropriate styles to it. More information about {{ic|userChrome.css}} at [http://kb.mozillazine.org/index.php?title=UserChrome.css mozillaZine].<br />
<br />
{{hc|~/.mozilla/firefox/<em><profile></em>/chrome/userChrome.css|<br />
@namespace url("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");<br />
<br />
/* #tabbrowser-tabs, #navigator-toolbox, menuitem, menu, ... */<br />
* {<br />
font-size: 15px !important;<br />
}<br />
<br />
/* exception for badge on adblocker */<br />
.toolbarbutton-badge {<br />
font-size: 8px !important;<br />
}<br />
}}<br />
<br />
{{Warning|The following extension is not compatible with Firefox Quantum (version 57 and above).}}<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use [https://addons.mozilla.org/en-US/firefox/addon/autohidpi/ AutoHiDPI] add-on in order to automatically adjust {{ic|layout.css.devPixelsPerPx}} setting for the active screen. Also, since Firefox version 49, it auto-scales based on your screen resolution, making it easier to deal with 2 or more screens.<br />
<br />
If you use Wayland, you can also use the Wayland-enabled packages of Firefox from the AUR: {{AUR|firefox-wayland}} (compiles from source) or {{AUR|fedora-firefox-wayland-bin}} (binary from Fedora). You might experience some minor visual glitches with these packages.<br />
<br />
==== Chromium / Google Chrome ====<br />
<br />
Chromium should use the [[#GDK 3 (GTK+ 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--force-device-scale-factor}} flag with a scaling value. This will scale all content and ui, including tab and font size. For example {{ic|1=chromium --force-device-scale-factor=2}}.<br />
<br />
Using this option, a scaling factor of 1 would be normal scaling. Floating point values can be used. To make the change permanent, for Chromium, you can add it to {{ic|~/.config/chromium-flags.conf}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|2=<br />
--force-device-scale-factor=2<br />
}}<br />
<br />
To make this work for Chrome, add the same option to {{ic|~/.config/chrome-flags.conf}} instead.<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use the [https://chrome.google.com/webstore/detail/resolution-zoom/enjjhajnmggdgofagbokhmifgnaophmh reszoom] extension in order to automatically adjust the zoom level for the active screen.<br />
<br />
==== Opera ====<br />
<br />
Opera should use the [[#GDK 3 (GTK+ 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--alt-high-dpi-setting=X}} command line option, where X is the desired DPI. For example, with {{ic|1=--alt-high-dpi-setting=144}} Opera will assume that DPI is 144. Newer versions of opera will auto detect the DPI using the font DPI setting (in KDE: the force font DPI setting.)<br />
<br />
=== Gimp 2.8 ===<br />
<br />
Use a high DPI theme, or adjust {{ic|1=gtkrc}} of an existing theme. (Change all occurrences of the size {{ic|1=button}} to {{ic|1=dialog}}, for example {{ic|1=GimpToolPalette::tool-icon-size}}.)<br />
<br />
There is also the [https://github.com/jedireza/gimp-hidpi gimp-hidpi].<br />
<br />
=== IntelliJ IDEA ===<br />
<br />
IntelliJ IDEA 15 and above should include HiDPI support.[http://blog.jetbrains.com/idea/2015/07/intellij-idea-15-eap-comes-with-true-hidpi-support-for-windows-and-linux/] If it does not work, the most convenient way to fix the problem in this case seems to be changing the Override Default Fonts setting:<br />
<br />
:''File > Settings > Behaviour & Appearance > Appearance''<br />
<br />
The addition of {{ic|1=-Dhidpi=true}} to the vmoptions file in either {{ic|$HOME/.IdeaC14/}} or {{ic|/usr/share/intelligj-idea-ultimate-edition/bin/}} of [https://youtrack.jetbrains.com/issue/IDEA-114944 release 14] should not be required anymore.<br />
<br />
=== Java applications ===<br />
<br />
Java applications using the AWT/Swing framework can be scaled by defining the sun.java2d.uiScale variable when invoking java. For example,<br />
<br />
java -Dsun.java2d.uiScale=2 -jar some_application.jar<br />
<br />
Since Java 9 the GDK_SCALE environment variable is used to scale Swing applications accordingly.<br />
<br />
=== MATLAB ===<br />
<br />
Recent versions (R2017b) of [[MATLAB]] allow to set the scale factor[https://www.mathworks.com/matlabcentral/answers/406956-does-matlab-support-high-dpi-screens-on-linux]:<br />
<br />
>> s = settings;s.matlab.desktop.DisplayScaleFactor<br />
>> s.matlab.desktop.DisplayScaleFactor.PersonalValue = 2<br />
<br />
The settings take effect after MATLAB is restarted.<br />
<br />
=== Mono applications ===<br />
<br />
According to [https://bugzilla.xamarin.com/show_bug.cgi?id=35870], Mono applications should be scalable like [[#GDK 3 (GTK+ 3)|GTK3]] applications.<br />
<br />
=== NetBeans ===<br />
<br />
NetBeans allows the font size of its interface to be controlled using the {{ic|1=--fontsize}} parameter during startup. To make this change permanent edit the {{ic|1=/usr/share/netbeans/etc/netbeans.conf}} file and append the {{ic|1=--fontsize}} parameter to the {{ic|1=netbeans_default_options}} property.[http://wiki.netbeans.org/FaqFontSize]<br />
<br />
The editor fontsize can be controlled from ''Tools > Option > Fonts & Colors''.<br />
<br />
The output window fontsize can be controlled from ''Tools > Options > Miscelaneous > Output''<br />
<br />
=== Skype ===<br />
<br />
Skype for Linux ({{AUR|skypeforlinux-stable-bin}} package) uses [[#GDK 3 (GTK+ 3)]].<br />
<br />
=== Slack ===<br />
<br />
Slack ({{AUR|slack-desktop}}), like all [https://electronjs.org/ Electron] apps, can be configured to use a custom scaling value by adding a {{ic|1=--force-device-scale-factor}} flag to the .desktop file. This is normally located at {{ic|/usr/share/applications/}}. The flag should be added to the line beginning with "Exec=". For example:<br />
<br />
{{hc|/usr/share/applications/slack.desktop|2=<br />
Exec=env LD_PRELOAD=/usr/lib/libcurl.so.3 /usr/bin/slack --force-device-scale-factor=1.5 %U<br />
}}<br />
<br />
=== Spotify ===<br />
<br />
You can change scale factor by simple {{ic|Ctrl++}} for zoom in, {{ic|Ctrl+-}} for zoom out and {{ic|Ctrl+0}} for default scale. Scaling setting will be saved in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}:<br />
<br />
{{hc|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs|2=<br />
app.browser.zoom-level=100<br />
}}<br />
<br />
Also Spotify can be launched with a custom scaling factor which will be multiplied with setting specified in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, for example<br />
<br />
$ spotify --force-device-scale-factor=1.5<br />
<br />
=== Steam ===<br />
<br />
==== Official HiDPI support ====<br />
<br />
* Starting on 25 of January 2018 in the beta program there is actual support for HiDPI and it should be automatically detected.<br />
* ''Steam > Settings > Interface'', check "Enlarge text and icons based on monitor size" (restart required)<br />
* If it not automatically detected use {{ic|1=GDK_SCALE=2}} to set the desired scale factor.<br />
<br />
==== Unofficial ====<br />
<br />
The [https://github.com/MoriTanosuke/HiDPI-Steam-Skin HiDPI-Steam-Skin] can be installed to increase the font size of the interface. While not perfect, it does improve usability. <br />
<br />
{{Note|The README for the HiDPI skin lists several possible locations for where to place the skin. The correct folder out of these can be identified by the presence of a file named {{ic|1=skins_readme.txt}}.}}<br />
<br />
[http://steamcommunity.com/groups/metroskin/discussions/0/517142253861033946/ MetroSkin Unofficial Patch] also helps with HiDPI on Steam with Linux.<br />
<br />
=== Sublime Text 3 ===<br />
<br />
Sublime Text 3 has full support for display scaling. Go to ''Preferences > Settings > User Settings'' and add {{ic|"ui_scale": 2.0}} to your settings.<br />
<br />
=== Thunderbird ===<br />
<br />
See [[#Firefox]]. To access {{ic|about:config}}, go to ''Edit > Preferences > Advanced >Config editor''.<br />
<br />
=== VirtualBox ===<br />
<br />
{{Note|This only applies to KDE with scaling enabled.}}<br />
<br />
VirtualBox also applies the system-wide scaling to the virtual monitor, which reduces the maximum resolution inside VMs by your scaling factor (see [https://www.virtualbox.org/ticket/16604]).<br />
<br />
This can be worked around by calculating the inverse of your scaling factor and manually setting this new scaling factor for the VirtualBox execution, e.g.<br />
<br />
$ QT_SCALE_FACTOR=0.5 VirtualBox --startvm vm-name<br />
<br />
=== Wine applications ===<br />
<br />
Run<br />
<br />
$ winecfg<br />
<br />
and change the "dpi" setting found in the "Graphics" tab. This only affects the font size.<br />
<br />
=== Zathura document viewer ===<br />
<br />
No modifications required for document viewing.<br />
<br />
UI text scaling is specified via [https://pwmt.org/projects/zathura/documentation/ configuration file] (note that "font" is a [https://pwmt.org/projects/girara/options/ girara option]):<br />
<br />
set font "monospace normal 20"<br />
<br />
=== Zoom ===<br />
<br />
Zoom can be started with a proper scaling by overriding the {{ic|1=QT_SCALE_FACTOR}} environment variable.<br />
<br />
$ QT_SCALE_FACTOR=2 zoom<br />
<br />
=== Unsupported applications ===<br />
<br />
{{AUR|run_scaled-git}} can be used to scale applications (which uses {{Pkg|xpra}} internally).<br />
<br />
Another approach is to run the application full screen and without decoration in its own VNC desktop. Then scale the viewer. With Vncdesk ({{AUR|vncdesk-git}} from the [[AUR]]) you can set up a desktop per application, then start server and client with a simple command such as {{ic|vncdesk 2}}.<br />
<br />
[[x11vnc]] has an experimental option {{ic|-appshare}}, which opens one viewer per application window. Perhaps something could be hacked up with that.<br />
<br />
== Multiple displays ==<br />
<br />
The HiDPI setting applies to the whole desktop, so non-HiDPI external displays show everything too large. However, note that setting different scaling factors for different monitors is already supported in [[Wayland]].<br />
<br />
=== Side display ===<br />
<br />
One workaround is to use [[xrandr]]'s scale option. To have a non-HiDPI monitor (on DP1) right of an internal HiDPI display (eDP1), one could run:<br />
<br />
$ xrandr --output eDP-1 --auto --output DP-1 --auto --scale 2x2 --right-of eDP-1<br />
<br />
When extending above the internal display, you may see part of the internal display on the external monitor. In that case, specify the position manually.<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
{{Note|1=Above solution with {{ic|--scale 2x2}} does not work on some Nvidia cards. No solution is currently available. [https://bbs.archlinux.org/viewtopic.php?pid=1670840] A potential workaround exists with configuring {{ic|1=ForceFullCompositionPipeline=On}} on the {{ic|CurrentMetaMode}} via {{ic|nvidia-settings}}. For more info see [https://askubuntu.com/a/979551/763549].}}<br />
<br />
{{Note|If you are using the {{ic|modesetting}} driver you will get mouse flickering. This can be solved by scaling your non-scaled screen by 0.9999x0.9999.}}<br />
<br />
=== Multiple external monitors ===<br />
<br />
There might be some problems in scaling more than one external monitors which have lower dpi than the built-in HiDPI display. In that case, you may want to try downscaling the HiDPI display instead, with e.g.<br />
<br />
$ xrandr --output eDP1 --scale 0.5x0.5 --output DP2 --right-of eDP1 --output HDMI1 --right-of DP2<br />
<br />
In addition, when you downscale the HiDPI display, the font on the HiDPI display will be slightly blurry, but it's a different kind of bluriness compared with the one introduced by upscaling the external displays. You may compare and see which kind of bluriness is less problematic for you.<br />
<br />
=== Mirroring ===<br />
<br />
If all you want is to mirror ("unify") displays, this is easy as well:<br />
<br />
With AxB your native HiDPI resolution (for ex 3200x1800) and CxD your external screen resolution (e.g. 1920x1200)<br />
<br />
$ xrandr --output HDMI --scale [A/C]x[B/D]<br />
<br />
In this example which is QHD (3200/1920 = 1.66 and 1800/1200 = 1.5)<br />
<br />
$ xrandr --output HDMI --scale 1.66x1.5<br />
<br />
For UHD to 1080p (3840/1920=2 2160/1080=2)<br />
<br />
$ xrandr --output HDMI --scale 2x2<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
=== Tools ===<br />
<br />
There are several tools which automate the commands described above.<br />
<br />
* [https://gist.github.com/wvengen/178642bbc8236c1bdb67 This script] extend a non-HiDPI external display above a HiDPI internal display.<br />
* [https://github.com/ashwinvis/xrandr-extend xrandr-extend].<br />
* {{AUR|xlayoutdisplay}} is a CLI front end for xrandr which detects and sets correct DPI: [https://github.com/alex-courtis/xlayoutdisplay README]<br />
<br />
== Linux console ==<br />
<br />
The default [[w:Linux console|Linux console]] font will be very small on hidpi displays, the largest font present in the {{Pkg|kbd}} package is {{ic|latarcyrheb-sun32}} and other packages like {{Pkg|terminus-font}} contain further alternatives, such as {{ic|ter-132n}}(normal) and {{ic|ter-132b}}(bold). See [[Linux console#Fonts]] for configuration details.<br />
<br />
After changing the font, it is often garbled and unreadable when changing to other virtual consoles ({{ic|tty2-6}}). To fix this you can [[Kernel_mode_setting#Forcing_modes_and_EDID|force specific mode]] for KMS, such as {{ic|1=video=2560x1600@60}} (substitute in the native resolution of your HiDPI display), and reboot.<br />
<br />
== See also ==<br />
<br />
* [http://www.phoronix.com/scan.php?page=article&item=linux_uhd4k_gpus Ultra HD 4K Linux Graphics Card Testing] (Nov 2013)<br />
* [http://www.eizo.com/library/basics/pixel_density_4k/ Understanding pixel density]<br />
* [http://wok.oblomov.eu/tecnologia/mixed-dpi-x11/ Mixed DPI and the X Window System]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Linux_Containers&diff=557321Linux Containers2018-11-25T17:44:30Z<p>Progandy: /* Enable support to run unprivileged containers (optional) */ pam_cgfs is not an alternative to the sysctl setting, so split it in its own paragraph</p>
<hr />
<div>[[Category:Virtualization]]<br />
[[Category:Sandboxing]]<br />
[[ja:Linux Containers]]<br />
[[pt:Linux Containers]]<br />
{{Related articles start}}<br />
{{Related|AirVPN}}<br />
{{Related|ABS}}<br />
{{Related|Cgroups}}<br />
{{Related|Docker}}<br />
{{Related|LXD}}<br />
{{Related|OpenVPN}}<br />
{{Related|OpenVPN (client) in Linux containers}}<br />
{{Related|OpenVPN (server) in Linux containers}}<br />
{{Related|PeerGuardian Linux}}<br />
{{Related|systemd-nspawn}}<br />
{{Related articles end}}<br />
<br />
[https://linuxcontainers.org/ Linux Containers] (LXC) is an operating-system-level virtualization method for running multiple isolated Linux systems (containers) on a single control host (LXC host). It does not provide a virtual machine, but rather provides a virtual environment that has its own CPU, memory, block I/O, network, etc. space and the resource control mechanism. This is provided by [[Wikipedia:Linux namespaces|namespaces]] and [[cgroups]] features in Linux kernel on LXC host. It is similar to a chroot, but offers much more isolation.<br />
<br />
Alternatives for using containers are [[systemd-nspawn]], [[docker]] or {{Pkg|rkt}}.<br />
<br />
== Privileged containers or unprivileged containers ==<br />
LXCs can be setup to run in either ''privileged'' or ''unprivileged'' configurations.<br />
<br />
In general, running an ''unprivileged'' container is [https://www.stgraber.org/2014/01/17/lxc-1-0-unprivileged-containers considered safer] than running a ''privileged'' container since ''unprivileged'' containers have an increased degree of isolation by virtue of their design. Key to this is the mapping of the root UID in the container to a non-root UID on the host which makes it more difficult for a hack within the container to lead to consequences on host system. In other words, if an attacker manages to escape the container, he or she should find themselves with no rights on the host.<br />
<br />
The Arch packages currently provide out-of-the-box support for ''privileged'' containers. ''Unprivileged'' containers are only available for the system administrator with additional kernel configuration. This is due to the current Arch {{pkg|linux}} kernel shipping with user namespaces disabled for normal users. This article contains information for users to run either type of container, but additional setup is required to use ''unprivileged'' containers.<br />
<br />
=== An example to illustrate unprivileged containers ===<br />
<br />
To illustrate the power of UID mapping, consider the output below from a running, ''unprivileged'' container. Therein, we see the containerized processes owned by the containerized root user in the output of {{ic|ps}}:<br />
<br />
[root@unprivileged_container /]# ps -ef | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
root 1 0 0 17:49 ? 00:00:00 /sbin/init<br />
root 14 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
dbus 25 1 0 17:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
systemd+ 26 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-networkd<br />
<br />
On the host however, those containerized root processes are running as the mapped user (ID>100000) on the host, not as the root user on the host:<br />
[root@host /]# lxc-info -Ssip --name sandbox<br />
State: RUNNING<br />
PID: 26204<br />
CPU use: 10.51 seconds<br />
BlkIO use: 244.00 KiB<br />
Memory use: 13.09 MiB<br />
KMem use: 7.21 MiB<br />
<br />
[root@host /]# ps -ef | grep 26204 | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
100000 26204 26200 0 12:49 ? 00:00:00 /sbin/init<br />
100000 26256 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
100081 26282 26204 0 12:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
100000 26284 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-logind<br />
<br />
== Setup ==<br />
=== Required software ===<br />
Installing {{Pkg|lxc}} and {{Pkg|arch-install-scripts}} will allow the host system to run privileged lxcs.<br />
<br />
==== Enable support to run unprivileged containers (optional) ====<br />
Users wishing to run ''unprivileged'' containers need to complete several additional setup steps.<br />
<br />
Firstly, a kernel is required that has support for '''User Namespaces''' (a kernel with {{ic|CONFIG_USER_NS}}). All Arch Linux kernels have support for {{ic|CONFIG_USER_NS}}. However, due to more general security concerns, the default Arch kernel does ship with User Namespaces enabled only for the ''root'' user. You have two options to create ''unprivileged'' containers:<br />
<br />
* Start your unprivileged containers only as ''root''.<br />
* Enable the ''sysctl'' setting {{ic|kernel.unprivileged_userns_clone}} to allow normal users to run unprivileged containers. This can be done for the current session with {{ic|1=sysctl kernel.unprivileged_userns_clone=1}} and can be made permanent with {{man|5|sysctl.d}}.<br />
<br />
Enable the cgfs pam module by modifying {{ic|/etc/pam.d/system-login}} to '''additionally''' contain the following line:<br />
session optional pam_cgfs.so -c freezer,memory,name=systemd,unified<br />
<br />
Secondly, modify {{ic|/etc/lxc/default.conf}} to contain the following lines:<br />
lxc.idmap = u 0 100000 65536<br />
lxc.idmap = g 0 100000 65536<br />
<br />
Finally, create both {{ic|/etc/subuid}} and {{ic|/etc/subgid}} to contain the mapping to the containerized uid/gid pairs for each user who shall be able to run the containers. The example below is simply for the root user (and systemd system unit):<br />
<br />
{{hc|/etc/subuid|<br />
root:100000:65536<br />
}}<br />
<br />
{{hc|/etc/subgid|<br />
root:100000:65536<br />
}}<br />
<br />
=== Host network configuration ===<br />
LXCs support different virtual network types and devices (see {{man|5|lxc.container.conf}}). A bridge device on the host is required for most types of virtual networking.<br />
<br />
LXC comes with its own NAT Bridge (lxcbr0).<br />
{{Note|A NAT bridge is a standalone bridge with a private network that is not bridged to the host eth0 or a physical network. It exists as a private subnet in the host.}}<br />
{{Tip|This is quite useful when WIFI is the only option. There have been various attempts of creating Bridges on WIFI without much success.}}<br />
<br />
To use LXC's NAT Bridge you need to create its configuration file:<br />
<br />
{{hc|/etc/default/lxc-net|<br />
2=# Leave USE_LXC_BRIDGE as "true" if you want to use lxcbr0 for your<br />
# containers. Set to "false" if you'll use virbr0 or another existing<br />
# bridge, or mavlan to your host's NIC.<br />
USE_LXC_BRIDGE="true"<br />
<br />
# If you change the LXC_BRIDGE to something other than lxcbr0, then<br />
# you will also need to update your /etc/lxc/default.conf as well as the<br />
# configuration (/var/lib/lxc/<container>/config) for any containers<br />
# already created using the default config to reflect the new bridge<br />
# name.<br />
# If you have the dnsmasq daemon installed, you'll also have to update<br />
# /etc/dnsmasq.d/lxc and restart the system wide dnsmasq daemon.<br />
LXC_BRIDGE="lxcbr0"<br />
LXC_ADDR="10.0.3.1"<br />
LXC_NETMASK="255.255.255.0"<br />
LXC_NETWORK="10.0.3.0/24"<br />
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"<br />
LXC_DHCP_MAX="253"<br />
# Uncomment the next line if you'd like to use a conf-file for the lxcbr0<br />
# dnsmasq. For instance, you can use 'dhcp-host=mail1,10.0.3.100' to have<br />
# container 'mail1' always get ip address 10.0.3.100.<br />
#LXC_DHCP_CONFILE=/etc/lxc/dnsmasq.conf<br />
<br />
# Uncomment the next line if you want lxcbr0's dnsmasq to resolve the .lxc<br />
# domain. You can then add "server=/lxc/10.0.3.1' (or your actual $LXC_ADDR)<br />
# to your system dnsmasq configuration file (normally /etc/dnsmasq.conf,<br />
# or /etc/NetworkManager/dnsmasq.d/lxc.conf on systems that use NetworkManager).<br />
# Once these changes are made, restart the lxc-net and network-manager services.<br />
# 'container1.lxc' will then resolve on your host.<br />
#LXC_DOMAIN="lxc"<br />
}}<br />
<br />
{{Tip| Make sure the bridges ip-range does not interfere with your local network.}}<br />
<br />
Then we need to modify the LXC container template so our containers use our bridge:<br />
<br />
{{hc|/etc/lxc/default.conf|<br />
2=lxc.net.0.type = veth<br />
lxc.net.0.link = lxcbr0<br />
lxc.net.0.flags = up<br />
lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx<br />
}}<br />
<br />
You also need to [[install]] {{pkg|dnsmasq}} which is a dependency for lxcbr0.<br />
<br />
[[Enable]] and/or [[start]] {{ic|lxc-net.service}} to use the bridge:<br />
<br />
See [[Network bridge]] for more information.<br />
<br />
=== Alternate Network - Bridge on same network as host ===<br />
<br />
{{Remove|Duplicates [[Bridge with netctl]].}}<br />
<br />
If you would like the containers to be on the same network as your host machine and not utilize NAT and firewall forwarding rules you can do the following.<br />
<br />
You will setup a manual bridge using netctl that includes the hosts ethernet adapter. You set your ethernet to not have an ip address and instead assign an ip address to the bridge that it is binded to. <br />
<br />
In this scenario you will not be using the lxc-net service stop it if you enabled it.<br />
<br />
# systemctl stop lxc-net<br />
# systemctl disable lxc-net<br />
<br />
{{hc|/etc/netctl/ethernet|<br />
2=Description="Manual Ethernet setup for bridge"<br />
Interface=eno1 # your interface<br />
Connection=ethernet<br />
IP=no<br />
}}<br />
<br />
{{hc|/etc/netctl/bridge|<br />
2=Description="Bridge Interface"<br />
Interface=br0<br />
Connection=bridge<br />
BindsToInterfaces=(eno1)<br />
IP=dhcp<br />
}}<br />
<br />
Make sure to first shutdown your current ethernet connections prior to bringing these up.<br />
<br />
# netctl stop-all<br />
# netctl start ethernet<br />
# netctl start bridge<br />
# netctl enable ethernet<br />
# netctl enable bridge<br />
<br />
Now change the default config for your containers.<br />
<br />
{{hc|/etc/lxc/default.conf|<br />
2=lxc.idmap = u 0 100000 65536<br />
lxc.idmap = g 0 100000 65536<br />
<br />
lxc.net.0.type = veth<br />
lxc.net.0.link = br0<br />
lxc.net.0.flags = up<br />
}}<br />
<br />
Now when you create a new container and start it, it should get an DHCP ip from the same network as the host.<br />
<br />
=== Container creation ===<br />
Containers are built using {{ic|lxc-create}}. With the release of lxc-3.0.0-1, upstream has deprecated locally stored templates.<br />
<br />
To build an Arch container, invoke like this:<br />
# lxc-create -n playtime -t download -- --dist archlinux --release current --arch amd64<br />
<br />
For other distros, invoke like this and select options from the supported distros displayed in the list:<br />
# lxc-create -n playtime -t download<br />
<br />
{{Tip|Users may optionally install {{Pkg|haveged}} and [[start]] {{ic|haveged.service}} to avoid a perceived hang during the setup process while waiting for system entropy to be seeded. Without it, the generation of private/GPG keys can add a lengthy wait to the process.}}<br />
<br />
{{Tip|Users of [[Btrfs]] can append {{ic|-B btrfs}} to create a Btrfs subvolume for storing containerized rootfs. This comes in handy if cloning containers with the help of {{ic|lxc-clone}} command. [[ZFS]] users may use {{ic|-B zfs}}, correspondingly.}}<br />
<br />
{{Note|Users wanting the legacy templates can find them in {{AUR|lxc-templates}} or alternatively, users can build their own templates with {{AUR|distrobuilder}}.}}<br />
<br />
=== Container configuration ===<br />
The examples below can be used with ''privileged'' and ''unprivileged'' containers alike. Note that for unprivileged containers, additional lines will be present by default which are not shown in the examples, including the {{ic|1=lxc.idmap = u 0 100000 65536}} and the {{ic|1=lxc.idmap = g 0 100000 65536}} values optionally defined in the [[#Enable support to run unprivileged containers (optional)]] section.<br />
<br />
==== Basic config with networking ====<br />
{{Note|With the release of lxc-1:2.1.0-1, many of the configuration options have changed. Existing containers need to be updated; users are directed to the table of these changes in the [https://discuss.linuxcontainers.org/t/lxc-2-1-has-been-released/487 v2.1 release notes].}}<br />
<br />
System resources to be virtualized/isolated when a process is using the container are defined in {{ic|/var/lib/lxc/CONTAINER_NAME/config}}. By default, the creation process will make a minimum setup without networking support. Below is an example config with networking:<br />
<br />
{{hc|/var/lib/lxc/playtime/config|<nowiki><br />
# Template used to create this container: /usr/share/lxc/templates/lxc-archlinux<br />
# Parameters passed to the template:<br />
# For additional config options, please look at lxc.container.conf(5)<br />
<br />
## default values<br />
lxc.rootfs.path = /var/lib/lxc/playtime/rootfs<br />
lxc.uts.name = playtime<br />
lxc.arch = x86_64<br />
lxc.include = /usr/share/lxc/config/common.conf<br />
<br />
## network<br />
lxc.net.0.type = veth<br />
lxc.net.0.link = br0<br />
lxc.net.0.flags = up<br />
lxc.net.0.name = eth0<br />
lxc.net.0.hwaddr = ee:ec:fa:e9:56:7d<br />
# uncomment the next two lines if static IP addresses are needed<br />
# leaving these commented will imply DHCP networking<br />
#<br />
#lxc.net.0.ipv4.address = 192.168.0.3/24<br />
#lxc.net.0.ipv4.gateway = 192.168.0.1<br />
</nowiki>}}<br />
<br />
{{Note|The lxc.network.hwaddr entry is optional and if skipped, a random MAC address will be created automatically. It can be advantageous to define a MAC address for the container to allow the DHCP server to always assign the same IP to the container's NIC (beyond the scope of this article but worth mentioning).}}<br />
<br />
==== Mounts within the container ====<br />
For ''privileged'' containers, one can select directories on the host to bind mount to the container. This can be advantageous for example if the same architecture is being containerize and one wants to share pacman packages between the host and container. Another example could be shared directories. The syntax is simple:<br />
<br />
lxc.mount.entry = /var/cache/pacman/pkg var/cache/pacman/pkg none bind 0 0<br />
<br />
{{Note|This will not work without filesystem permission modifications on the host if using ''unprivileged'' containers.}}<br />
==== Xorg program considerations (optional) ====<br />
In order to run programs on the host's display, some bind mounts need to be defined so that the containerized programs can access the host's resources. Add the following section to {{ic|/var/lib/lxc/playtime/config}}:<br />
## for xorg<br />
lxc.mount.entry = /dev/dri dev/dri none bind,optional,create=dir<br />
lxc.mount.entry = /dev/snd dev/snd none bind,optional,create=dir<br />
lxc.mount.entry = /tmp/.X11-unix tmp/.X11-unix none bind,optional,create=dir,ro<br />
lxc.mount.entry = /dev/video0 dev/video0 none bind,optional,create=file<br />
<br />
If you still get a permission denied error in your LXC guest, then you may need to call {{ic|xhost +}} in your host to allow the guest to connect to the host's display server. Take note of the security concerns of opening up your display server by doing this.<br />
In addition you might need to add the following line '''before''' the above bind mount lines.<br />
lxc.mount.entry = tmpfs tmp tmpfs defaults<br />
<br />
{{Note|This will not work if using ''unprivileged'' containers.}}<br />
<br />
==== OpenVPN considerations ====<br />
<br />
Users wishing to run [[OpenVPN]] within the container are requested to direct to either [[OpenVPN (client) in Linux containers]] and/or [[OpenVPN (server) in Linux containers]].<br />
<br />
== Managing containers ==<br />
=== Basic usage ===<br />
To list all installed LXC containers:<br />
# lxc-ls -f<br />
<br />
Systemd can be used to [[start]] and to [[stop]] LXCs via {{ic|lxc@CONTAINER_NAME.service}}. [[Enable]] {{ic|lxc@CONTAINER_NAME.service}} to have it start when the host system boots.<br />
<br />
Users can also start/stop LXCs without systemd.<br />
Start a container:<br />
# lxc-start -n CONTAINER_NAME<br />
<br />
Stop a container:<br />
# lxc-stop -n CONTAINER_NAME<br />
<br />
To login into a container:<br />
# lxc-console -n CONTAINER_NAME<br />
<br />
If when login you get pts/0 and lxc/tty1 use:<br />
# lxc-console -n CONTAINER_NAME -t 0<br />
<br />
Once logged, treat the container like any other linux system, set the root password, create users, install packages, etc.<br />
<br />
To attach to a container:<br />
# lxc-attach -n CONTAINER_NAME --clear-env<br />
<br />
It works nearly the same as lxc-console, but you are automatically accessing root prompt inside the container, bypassing login. Without the {{ic| --clear-env}} flag, the host will pass its own environment variables into the container (including {{ic|$PATH}}, so some commands will not work when the containers are based on another distribution).<br />
<br />
=== Advanced usage ===<br />
<br />
==== LXC clones ====<br />
Users with a need to run multiple containers can simplify administrative overhead (user management, system updates, etc.) by using snapshots. The strategy is to setup and keep up-to-date a single base container, then, as needed, clone (snapshot) it. The power in this strategy is that the disk space and system overhead are truly minimized since the snapshots use an overlayfs mount to only write out to disk, only the differences in data. The base system is read-only but changes to it in the snapshots are allowed via the overlayfs.<br />
<br />
{{Expansion|The note needs a reference.}}<br />
<br />
{{Note|overlayfs for unprivileged containers is not supported in the current mainline Arch Linux kernel due to security considerations.}}<br />
<br />
For example, setup a container as outlined above. We will call it "base" for the purposes of this guide. Now create 2 snapshots of "base" which we will call "snap1" and "snap2" with these commands:<br />
# lxc-copy -n base -N snap1 -B overlayfs -s<br />
# lxc-copy -n base -N snap2 -B overlayfs -s<br />
<br />
{{Note|If a static IP was defined for the "base" lxc, that will need to manually changed in the config for "snap1" and for "snap2" before starting them. If the process is to be automated, a script using sed can do this automatically although this is beyond the scope of this wiki section.}}<br />
<br />
The snapshots can be started/stopped like any other container. Users can optionally destroy the snapshots and all new data therein with the following command. Note that the underlying "base" lxc is untouched:<br />
# lxc-destroy -n snap1 -f<br />
<br />
Systemd units and wrapper scripts to manage snapshots for [[pi-hole]] and [[OpenVPN]] are available to automate the process in [https://github.com/graysky2/lxc-snapshots lxc-snapshots].<br />
<br />
=== Converting a privileged container to an unprivileged container ===<br />
Once the system has been configured to use unprivileged containers (see, [[#Enable support to run unprivileged containers (optional)]]), {{AUR|nsexec-bzr}} contains a utility called {{ic|uidmapshift}} which is able to convert an existing ''privileged'' container to an ''unprivileged'' container to avoid a total rebuild of the image.<br />
<br />
{{Warning|<br />
* It is recommended to backup the existing image before using this utility!<br />
* This utility will not shift UIDs and GIDs in [[ACL]], you will need to shift them on your own.<br />
}}<br />
<br />
Invoke the utility to convert over like so:<br />
# uidmapshift -b /var/lib/lxc/foo 0 100000 65536<br />
<br />
Additional options are available simply by calling {{ic|uidmapshift}} without any arguments.<br />
<br />
== Running Xorg programs ==<br />
Either attach to or [[SSH]] into the target container and prefix the call to the program with the DISPLAY ID of the host's X session. For most simple setups, the display is always 0.<br />
<br />
An example of running Firefox from the container in the host's display:<br />
$ DISPLAY=:0 firefox<br />
<br />
Alternatively, to avoid directly attaching to or connecting to the container, the following can be used on the host to automate the process:<br />
# lxc-attach -n playtime --clear-env -- sudo -u YOURUSER env DISPLAY=:0 firefox<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root login fails ===<br />
<br />
If you get the following error when you try to login using lxc-console:<br />
<br />
login: root<br />
Login incorrect<br />
<br />
And the container's {{ic|journalctl}} shows:<br />
<br />
pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !<br />
<br />
Add {{ic|pts/0}} to the list of terminal names in {{ic|/etc/securetty}} on the '''container''' filesystem, see [http://unix.stackexchange.com/questions/41840/effect-of-entries-in-etc-securetty/41939#41939]. You can also opt to delete {{ic|/etc/securetty}} on the '''container''' to allow always root to login, see [https://github.com/systemd/systemd/issues/852].<br />
<br />
Alternatively, create a new user in lxc-attach and use it for logging in to the system, then switch to root.<br />
<br />
# lxc-attach -n playtime<br />
[root@playtime]# useradd -m -Gwheel newuser<br />
[root@playtime]# passwd newuser<br />
[root@playtime]# passwd root<br />
[root@playtime]# exit<br />
# lxc-console -n playtime<br />
[newuser@playtime]$ su<br />
<br />
=== No network-connection with veth in container config===<br />
<br />
If you cannot access your LAN or WAN with a networking interface configured as '''veth''' and setup through {{ic|/etc/lxc/''containername''/config}}.<br />
If the virtual interface gets the ip assigned and should be connected to the network correctly.<br />
ip addr show veth0 <br />
inet 192.168.1.111/24<br />
You may disable all the relevant static ip formulas and try setting the ip through the booted container-os like you would normaly do.<br />
<br />
Example {{ic|''container''/config}}<br />
<br />
...<br />
lxc.net.0.type = veth<br />
lxc.net.0.name = veth0<br />
lxc.net.0.flags = up<br />
lxc.net.0.link = {{ic|bridge}}<br />
...<br />
<br />
And then assign your IP through your preferred method '''inside''' the container, see also [[Network configuration#Network management]].<br />
<br />
=== Error: unknown command ===<br />
<br />
The error may happen when you type a basic command (''ls'', ''cat'', etc.) on an attached container that have different Linux distribution from the host system (e.g. Debian container in Arch Linux host system). When you attach, use the argument {{ic|--clear-env}}: <br />
<br />
# lxc-attach -n ''container_name'' --clear-env<br />
<br />
=== Error: Failed at step KEYRING spawning... ===<br />
<br />
Services in an unprivileged container may fail with the following message<br />
<br />
some.service: Failed to change ownership of session keyring: Permission denied<br />
some.service: Failed to set up kernel keyring: Permission denied<br />
some.service: Failed at step KEYRING spawning ....: Permission denied<br />
<br />
Create a file {{ic|/etc/lxc/unpriv.seccomp}} containing<br />
<br />
{{hc|/etc/lxc/unpriv.seccomp|<br />
2<br />
blacklist<br />
[all]<br />
keyctl errno 38}}<br />
<br />
Then add the following line to the container configuration '''after''' lxc.idmap<br />
<br />
lxc.seccomp.profile = /etc/lxc/unpriv.seccomp<br />
<br />
=== Errors due to mknod changes in linux 4.18 kernel ===<br />
<br />
Applications may have errors such as the following with nginx:<br />
<br />
nginx failes with [emerg]: open("/dev/null") failed (13: Permission denied) <br />
<br />
There has been changes in linux 4.18 kernel with how mknod is handled and how it interacts with systemd's Privatedevice feature.<br />
<br />
Workaround is to revert to a 4.17 version kernel until fixed upstream<br />
<br />
* [https://github.com/lxc/lxd/issues/4950 After upgrading to 3.4 nginx won't start on container because it can't open /dev/null #4950]<br />
<br />
=== Error: Failed to initialize cgroup driver / PAM unable to open pam_cgfs.so ===<br />
<br />
There is a bug in LXC 3.0.2. If you get these errors:<br />
<br />
lxc-start: $NAME: cgroups/cgfsng.c: all_controllers_found: 701 No freezer controller mountpoint found<br />
lxc-start: $NAME: cgroups/cgroup.c: cgroup_init: 44 Failed to initialize cgroup driver <br />
lxc-start: $NAME: start.c: lxc_init: 861 Failed to initialize cgroup driver<br />
lxc-start: $NAME: start.c: __lxc_start: 1876 Failed to initialize container "$NAME"<br />
lxc-start: $NAME: tools/lxc_start.c: main: 330 The container failed to start<br />
lxc-start: $NAME: tools/lxc_start.c: main: 336 Additional information can be obtained by setting the --logfile and --logpriority options<br />
<br />
associated with these errors in the output of journalctl:<br />
<br />
Aug 17 16:06:25 localhost sshd[747]: PAM unable to dlopen(/usr/lib/security/pam_cgfs.so): /usr/lib/security/pam_cgfs.so: undefined symbol: strlcat<br />
Aug 17 16:06:25 localhost sshd[747]: PAM adding faulty module: /usr/lib/security/pam_cgfs.so<br />
<br />
It is because of [https://github.com/lxc/lxc/issues/2556 issue 2556], which has been fixed upstream already, but has not been backported to Arch (see {{Bug|59689}}).<br />
<br />
[[Downgrading]] to LXC 3.0.1 may solve the problem until the fix is packaged.<br />
<br />
== See also ==<br />
<br />
* [https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/ LXC 1.0 Blog Post Series]<br />
* [https://stgraber.org/2016/03/11/lxd-2-0-blog-post-series-012/ LXD 2.0: Blog post series]<br />
* [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/ LXC@developerWorks]<br />
* [http://l3net.wordpress.com/tag/lxc/ LXC articles on l3net]</div>Progandyhttps://wiki.archlinux.org/index.php?title=HP_Spectre_x360_15-ch025nd&diff=535927HP Spectre x360 15-ch025nd2018-08-17T19:01:28Z<p>Progandy: Tablet mode works as well with linux 4.18.1</p>
<hr />
<div>[[Category:HP]]<br />
{| class="wikitable" style="float: right;"<br />
| '''Device''' || '''Status''' || '''Modules'''<br />
|-<br />
| Integrated Video || {{G|Working}} || i915<br />
|-<br />
| Video || {{G|Working}} || amdgpu<br />
|-<br />
| Wireless || {{G|Working}} || iwlwifi<br />
|-<br />
| Bluetooth || {{G|Working}}|| bluetooth<br />
|-<br />
| Audio || {{Y|Mostly Working}} || snd_hda_intel<br />
|-<br />
| Touchpad || {{G|Working}} || serio<br />
|-<br />
| Touchscreen || {{G|Working}} || hid_multitouch<br />
|-<br />
| Card Reader || {{G|Working}} || rtsx_pci<br />
|-<br />
| Wireless switch || {{G|Working}} || intel-hid<br />
|-<br />
| Function/Multimedia Keys || {{G|Working}} || intel-vbtn<br />
|-<br />
| Tablet-Mode || {{G|Working}} || intel-vbtn<br />
|-<br />
| Accelerometer || {{Y|Manual binding}} || intel-ish-ipc<br />
|}<br />
== Hardware info ==<br />
<br />
=== Specifications ===<br />
<br />
This model was released in February 2016.<br />
<br />
* Intel Core i7-8705G with Intel HD Graphics 630 (3.1 GHz, up to 4.1 GHz, 8 MB cache, 4 cores)<br />
* 15.6" 4K (3840x2160) Ultra HD IPS WLED multitouch display<br />
* 16 GB LPDDR3-1866 SDRAM<br />
* 2 TB M.2 SDD<br />
* 2 USB Type C Thunderbolt port, 1 USB 3.0 Type A ports, 1 HDMI port, 1 headphone/microphone jack<br />
* 1 SD media card reader<br />
* 802.11ac (2x2) and Bluetooth 4.0<br />
* Bang & Olufsen quad speakers<br />
* 6-cell, 64.5 Wh Li-ion battery<br />
* Webcam<br />
* Backlit keyboard<br />
<br />
=== lspci ===<br />
*v00:00.0 Host bridge: Intel Corporation Xeon E3-1200 v6/7th Gen Core Processor Host Bridge/DRAM Registers (rev 05)<br />
00:01.0 PCI bridge: Intel Corporation Xeon E3-1200 v5/E3-1500 v5/6th Gen Core Processor PCIe Controller (x16) (rev 05)<br />
* 00:02.0 VGA compatible controller: Intel Corporation Device 591b (rev 04)<br />
* 00:04.0 Signal processing controller: Intel Corporation Xeon E3-1200 v5/E3-1500 v5/6th Gen Core Processor Thermal Subsystem (rev 05)<br />
* 00:13.0 Non-VGA unclassified device: Intel Corporation Sunrise Point-H Integrated Sensor Hub (rev 31)<br />
* 00:14.0 USB controller: Intel Corporation Sunrise Point-H USB 3.0 xHCI Controller (rev 31)<br />
* 00:14.2 Signal processing controller: Intel Corporation Sunrise Point-H Thermal subsystem (rev 31)<br />
* 00:15.0 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO I2C Controller #0 (rev 31)<br />
* 00:16.0 Communication controller: Intel Corporation Sunrise Point-H CSME HECI #1 (rev 31)<br />
* 00:17.0 SATA controller: Intel Corporation Sunrise Point-H SATA Controller [AHCI mode] (rev 31)<br />
* 00:1c.0 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #1 (rev f1)<br />
* 00:1c.4 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #5 (rev f1)<br />
* 00:1c.5 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #6 (rev f1)<br />
* 00:1d.0 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #9 (rev f1)<br />
* 00:1e.0 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO UART #0 (rev 31)<br />
* 00:1e.2 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO SPI #0 (rev 31)<br />
* 00:1f.0 ISA bridge: Intel Corporation Sunrise Point-H LPC Controller (rev 31)<br />
* 00:1f.2 Memory controller: Intel Corporation Sunrise Point-H PMC (rev 31)<br />
* 00:1f.3 Audio device: Intel Corporation CM238 HD Audio Controller (rev 31)<br />
* 00:1f.4 SMBus: Intel Corporation Sunrise Point-H SMBus (rev 31)<br />
* 01:00.0 Display controller: Advanced Micro Devices, Inc. [AMD/ATI] Polaris 22 [Radeon RX Vega M GL] (rev ff)<br />
* 6d:00.0 Unassigned class [ff00]: Realtek Semiconductor Co., Ltd. RTS525A PCI Express Card Reader (rev 01)<br />
* 6e:00.0 Network controller: Intel Corporation Wireless 8265 / 8275 (rev 78)<br />
* 6f:00.0 Non-Volatile memory controller: Toshiba America Info Systems Device 0116<br />
}}<br />
<br />
=== lsusb ===<br />
<br />
* Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub<br />
* Bus 001 Device 003: ID 8087:0a2b Intel Corp. <br />
* Bus 001 Device 002: ID 05c8:0815 Cheng Uei Precision Industry Co., Ltd (Foxlink) <br />
* Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
<br />
== Installation ==<br />
Installing Arch was mostly without hiccup; you do need to disable secure boot (F10 for BIOS options; F9 for boot options). Dual boot was not tested. The laptop does not have a CD drive, so you have to use a USB stick. The UEFI also would not startup from the USB stick, but you can browse the USB, and choose the loader.efi to startup from.<br />
<br />
== Issues ==<br />
=== Speaker ===<br />
Only the front speakers work out of the box right now. <br />
<br />
=== Accelerometer ===<br />
The accelerometer is not found by any userspace programs, Running <pre>G_MESSAGES_DEBUG=all /usr/sbin/iio-sensor-proxy </pre> from {{aur|iio-sensor-proxy}} gives <pre> ** (process:12472): DEBUG: 11:45:31.305: Could not find any supported sensors </pre><br />
<br />
The accelerometer is connected to a new Intel Integrated Sensor Hub which is not supported by the kernel yet, but can be manually bound to the {{ic|intel-ish-ipc}} driver.<br />
{{hc|$ lspci -nn|...<br />
00:13.0 Non-VGA unclassified device [0000]: Intel Corporation Sunrise Point-H Integrated Sensor Hub [8086:a135] (rev 31)<br />
...}}<br />
<br />
{{bc|# modprobe intel-ish-ipc<br />
# echo "8086 a135" > /sys/bus/pci/drivers/intel_ish_ipc/new_id<br />
}}<br />
{{hc|$ monitor-sensor| Waiting for iio-sensor-proxy to appear<br />
+++ iio-sensor-proxy appeared<br />
=== Has accelerometer (orientation: undefined)<br />
=== No ambient light sensor<br />
Accelerometer orientation changed: normal<br />
}}</div>Progandyhttps://wiki.archlinux.org/index.php?title=HP_Spectre_x360_15-ch025nd&diff=535898HP Spectre x360 15-ch025nd2018-08-17T16:21:19Z<p>Progandy: Discrete Video is now working with 3.18, and accelerometer can be manually enabled</p>
<hr />
<div>[[Category:HP]]<br />
{| class="wikitable" style="float: right;"<br />
| '''Device''' || '''Status''' || '''Modules'''<br />
|-<br />
| Integrated Video || {{G|Working}} || i915<br />
|-<br />
| Video || {{G|Working}} || amdgpu<br />
|-<br />
| Wireless || {{G|Working}} || iwlwifi<br />
|-<br />
| Bluetooth || {{G|Working}}|| bluetooth<br />
|-<br />
| Audio || {{Y|Mostly Working}} || snd_hda_intel<br />
|-<br />
| Touchpad || {{G|Working}} || serio<br />
|-<br />
| Touchscreen || {{G|Working}} || hid_multitouch<br />
|-<br />
| Card Reader || {{G|Working}} || rtsx_pci<br />
|-<br />
| Wireless switch || {{G|Working}} || intel-hid<br />
|-<br />
| Function/Multimedia Keys || {{G|Working}} || intel-vbtn<br />
|-<br />
| Tablet-Mode || {{R|Not working}} || intel-vbtn<br />
|-<br />
| Accelerometer || {{Y|Manual binding}} || intel-ish-ipc<br />
|}<br />
== Hardware info ==<br />
<br />
=== Specifications ===<br />
<br />
This model was released in February 2016.<br />
<br />
* Intel Core i7-8705G with Intel HD Graphics 630 (3.1 GHz, up to 4.1 GHz, 8 MB cache, 4 cores)<br />
* 15.6" 4K (3840x2160) Ultra HD IPS WLED multitouch display<br />
* 16 GB LPDDR3-1866 SDRAM<br />
* 2 TB M.2 SDD<br />
* 2 USB Type C Thunderbolt port, 1 USB 3.0 Type A ports, 1 HDMI port, 1 headphone/microphone jack<br />
* 1 SD media card reader<br />
* 802.11ac (2x2) and Bluetooth 4.0<br />
* Bang & Olufsen quad speakers<br />
* 6-cell, 64.5 Wh Li-ion battery<br />
* Webcam<br />
* Backlit keyboard<br />
<br />
=== lspci ===<br />
*v00:00.0 Host bridge: Intel Corporation Xeon E3-1200 v6/7th Gen Core Processor Host Bridge/DRAM Registers (rev 05)<br />
00:01.0 PCI bridge: Intel Corporation Xeon E3-1200 v5/E3-1500 v5/6th Gen Core Processor PCIe Controller (x16) (rev 05)<br />
* 00:02.0 VGA compatible controller: Intel Corporation Device 591b (rev 04)<br />
* 00:04.0 Signal processing controller: Intel Corporation Xeon E3-1200 v5/E3-1500 v5/6th Gen Core Processor Thermal Subsystem (rev 05)<br />
* 00:13.0 Non-VGA unclassified device: Intel Corporation Sunrise Point-H Integrated Sensor Hub (rev 31)<br />
* 00:14.0 USB controller: Intel Corporation Sunrise Point-H USB 3.0 xHCI Controller (rev 31)<br />
* 00:14.2 Signal processing controller: Intel Corporation Sunrise Point-H Thermal subsystem (rev 31)<br />
* 00:15.0 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO I2C Controller #0 (rev 31)<br />
* 00:16.0 Communication controller: Intel Corporation Sunrise Point-H CSME HECI #1 (rev 31)<br />
* 00:17.0 SATA controller: Intel Corporation Sunrise Point-H SATA Controller [AHCI mode] (rev 31)<br />
* 00:1c.0 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #1 (rev f1)<br />
* 00:1c.4 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #5 (rev f1)<br />
* 00:1c.5 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #6 (rev f1)<br />
* 00:1d.0 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #9 (rev f1)<br />
* 00:1e.0 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO UART #0 (rev 31)<br />
* 00:1e.2 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO SPI #0 (rev 31)<br />
* 00:1f.0 ISA bridge: Intel Corporation Sunrise Point-H LPC Controller (rev 31)<br />
* 00:1f.2 Memory controller: Intel Corporation Sunrise Point-H PMC (rev 31)<br />
* 00:1f.3 Audio device: Intel Corporation CM238 HD Audio Controller (rev 31)<br />
* 00:1f.4 SMBus: Intel Corporation Sunrise Point-H SMBus (rev 31)<br />
* 01:00.0 Display controller: Advanced Micro Devices, Inc. [AMD/ATI] Polaris 22 [Radeon RX Vega M GL] (rev ff)<br />
* 6d:00.0 Unassigned class [ff00]: Realtek Semiconductor Co., Ltd. RTS525A PCI Express Card Reader (rev 01)<br />
* 6e:00.0 Network controller: Intel Corporation Wireless 8265 / 8275 (rev 78)<br />
* 6f:00.0 Non-Volatile memory controller: Toshiba America Info Systems Device 0116<br />
}}<br />
<br />
=== lsusb ===<br />
<br />
* Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub<br />
* Bus 001 Device 003: ID 8087:0a2b Intel Corp. <br />
* Bus 001 Device 002: ID 05c8:0815 Cheng Uei Precision Industry Co., Ltd (Foxlink) <br />
* Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
<br />
== Installation ==<br />
Installing Arch was mostly without hiccup; you do need to disable secure boot (F10 for BIOS options; F9 for boot options). Dual boot was not tested. The laptop does not have a CD drive, so you have to use a USB stick. The UEFI also would not startup from the USB stick, but you can browse the USB, and choose the loader.efi to startup from.<br />
<br />
== Issues ==<br />
=== Tablet Mode ===<br />
The kernel does not receive any ACPI events when trying to switch to tablet mode. Adding the acpi_osi="!Windows*" acpi_osi="Windows 2015" does not make a difference. The following is the relevant section of the DSDT table: <br />
<pre><br />
Device (VBPA)<br />
{<br />
Name (_HID, "INT33D6" /* Intel Virtual Buttons Device */) // _HID: Hardware ID<br />
Method (_STA, 0, NotSerialized) // _STA: Status<br />
{<br />
If ((OSYS >= 0x07DD))<br />
{<br />
Return (0x0F)<br />
}<br />
Else<br />
{<br />
Return (Zero)<br />
}<br />
}<br />
<br />
Name (VBST, Zero)<br />
Method (VBDL, 0, NotSerialized)<br />
{<br />
If ((^^PCI0.LPCB.EC0.ECOK == One))<br />
{<br />
If ((^^PCI0.LPCB.EC0.CVTS == Zero))<br />
{<br />
VBST = 0x40<br />
}<br />
Else<br />
{<br />
VBST = Zero<br />
}<br />
}<br />
}<br />
<br />
Method (VGBS, 0, NotSerialized)<br />
{<br />
If ((^^PCI0.LPCB.EC0.ECOK == One))<br />
{<br />
If ((^^PCI0.LPCB.EC0.CVTS == Zero))<br />
{<br />
VBST = 0x40<br />
}<br />
Else<br />
{<br />
VBST = Zero<br />
}<br />
}<br />
<br />
Return (VBST) /* \_SB_.VBPA.VBST */<br />
}<br />
}<br />
</pre><br />
<br />
=== Speaker ===<br />
Only the front speakers work out of the box right now. <br />
<br />
=== Accelerometer ===<br />
The accelerometer is not found by any userspace programs, Running <pre>G_MESSAGES_DEBUG=all /usr/sbin/iio-sensor-proxy </pre> from {{aur|iio-sensor-proxy}} gives <pre> ** (process:12472): DEBUG: 11:45:31.305: Could not find any supported sensors </pre><br />
<br />
The accelerometer is connected to a new Intel Integrated Sensor Hub which is not supported by the kernel yet, but can be manually bound to the {{ic|intel-ish-ipc}} driver.<br />
{{hc|$ lspci -nn|...<br />
00:13.0 Non-VGA unclassified device [0000]: Intel Corporation Sunrise Point-H Integrated Sensor Hub [8086:a135] (rev 31)<br />
...}}<br />
<br />
{{bc|# modprobe intel-ish-ipc<br />
# echo "8086 a135" > /sys/bus/pci/drivers/intel_ish_ipc/new_id<br />
}}<br />
{{hc|$ monitor-sensor| Waiting for iio-sensor-proxy to appear<br />
+++ iio-sensor-proxy appeared<br />
=== Has accelerometer (orientation: undefined)<br />
=== No ambient light sensor<br />
Accelerometer orientation changed: normal<br />
}}</div>Progandyhttps://wiki.archlinux.org/index.php?title=HP_Spectre_x360_15-ch025nd&diff=535893HP Spectre x360 15-ch025nd2018-08-17T16:14:18Z<p>Progandy: /* Accelerometer */ Add a way to enable the accelerometer</p>
<hr />
<div>[[Category:HP]]<br />
{| class="wikitable" style="float: right;"<br />
| '''Device''' || '''Status''' || '''Modules'''<br />
|-<br />
| Integrated Video || {{G|Working}} || i915<br />
|-<br />
| Video || {{R|Not working}} || amdgpu<br />
|-<br />
| Wireless || {{G|Working}} || iwlwifi<br />
|-<br />
| Bluetooth || {{G|Working}}|| bluetooth<br />
|-<br />
| Audio || {{Y|Mostly Working}} || snd_hda_intel<br />
|-<br />
| Touchpad || {{G|Working}} || serio<br />
|-<br />
| Touchscreen || {{G|Working}} || hid_multitouch<br />
|-<br />
| Card Reader || {{G|Working}} || rtsx_pci<br />
|-<br />
| Wireless switch || {{G|Working}} || intel-hid<br />
|-<br />
| Function/Multimedia Keys || {{G|Working}} || intel-vbtn<br />
|-<br />
| Tablet-Mode || {{R|Not working}} || intel-vbtn<br />
|-<br />
| Accelerometer || {{R|Not working}} || ?<br />
|}<br />
== Hardware info ==<br />
<br />
=== Specifications ===<br />
<br />
This model was released in February 2016.<br />
<br />
* Intel Core i7-8705G with Intel HD Graphics 630 (3.1 GHz, up to 4.1 GHz, 8 MB cache, 4 cores)<br />
* 15.6" 4K (3840x2160) Ultra HD IPS WLED multitouch display<br />
* 16 GB LPDDR3-1866 SDRAM<br />
* 2 TB M.2 SDD<br />
* 2 USB Type C Thunderbolt port, 1 USB 3.0 Type A ports, 1 HDMI port, 1 headphone/microphone jack<br />
* 1 SD media card reader<br />
* 802.11ac (2x2) and Bluetooth 4.0<br />
* Bang & Olufsen quad speakers<br />
* 6-cell, 64.5 Wh Li-ion battery<br />
* Webcam<br />
* Backlit keyboard<br />
<br />
=== lspci ===<br />
*v00:00.0 Host bridge: Intel Corporation Xeon E3-1200 v6/7th Gen Core Processor Host Bridge/DRAM Registers (rev 05)<br />
00:01.0 PCI bridge: Intel Corporation Xeon E3-1200 v5/E3-1500 v5/6th Gen Core Processor PCIe Controller (x16) (rev 05)<br />
* 00:02.0 VGA compatible controller: Intel Corporation Device 591b (rev 04)<br />
* 00:04.0 Signal processing controller: Intel Corporation Xeon E3-1200 v5/E3-1500 v5/6th Gen Core Processor Thermal Subsystem (rev 05)<br />
* 00:13.0 Non-VGA unclassified device: Intel Corporation Sunrise Point-H Integrated Sensor Hub (rev 31)<br />
* 00:14.0 USB controller: Intel Corporation Sunrise Point-H USB 3.0 xHCI Controller (rev 31)<br />
* 00:14.2 Signal processing controller: Intel Corporation Sunrise Point-H Thermal subsystem (rev 31)<br />
* 00:15.0 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO I2C Controller #0 (rev 31)<br />
* 00:16.0 Communication controller: Intel Corporation Sunrise Point-H CSME HECI #1 (rev 31)<br />
* 00:17.0 SATA controller: Intel Corporation Sunrise Point-H SATA Controller [AHCI mode] (rev 31)<br />
* 00:1c.0 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #1 (rev f1)<br />
* 00:1c.4 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #5 (rev f1)<br />
* 00:1c.5 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #6 (rev f1)<br />
* 00:1d.0 PCI bridge: Intel Corporation Sunrise Point-H PCI Express Root Port #9 (rev f1)<br />
* 00:1e.0 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO UART #0 (rev 31)<br />
* 00:1e.2 Signal processing controller: Intel Corporation Sunrise Point-H Serial IO SPI #0 (rev 31)<br />
* 00:1f.0 ISA bridge: Intel Corporation Sunrise Point-H LPC Controller (rev 31)<br />
* 00:1f.2 Memory controller: Intel Corporation Sunrise Point-H PMC (rev 31)<br />
* 00:1f.3 Audio device: Intel Corporation CM238 HD Audio Controller (rev 31)<br />
* 00:1f.4 SMBus: Intel Corporation Sunrise Point-H SMBus (rev 31)<br />
* 01:00.0 Display controller: Advanced Micro Devices, Inc. [AMD/ATI] Polaris 22 [Radeon RX Vega M GL] (rev ff)<br />
* 6d:00.0 Unassigned class [ff00]: Realtek Semiconductor Co., Ltd. RTS525A PCI Express Card Reader (rev 01)<br />
* 6e:00.0 Network controller: Intel Corporation Wireless 8265 / 8275 (rev 78)<br />
* 6f:00.0 Non-Volatile memory controller: Toshiba America Info Systems Device 0116<br />
}}<br />
<br />
=== lsusb ===<br />
<br />
* Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub<br />
* Bus 001 Device 003: ID 8087:0a2b Intel Corp. <br />
* Bus 001 Device 002: ID 05c8:0815 Cheng Uei Precision Industry Co., Ltd (Foxlink) <br />
* Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
<br />
== Installation ==<br />
Installing Arch was mostly without hiccup; you do need to disable secure boot (F10 for BIOS options; F9 for boot options). Dual boot was not tested. The laptop does not have a CD drive, so you have to use a USB stick. The UEFI also would not startup from the USB stick, but you can browse the USB, and choose the loader.efi to startup from.<br />
<br />
== Issues ==<br />
=== Tablet Mode ===<br />
The kernel does not receive any ACPI events when trying to switch to tablet mode. Adding the acpi_osi="!Windows*" acpi_osi="Windows 2015" does not make a difference. The following is the relevant section of the DSDT table: <br />
<pre><br />
Device (VBPA)<br />
{<br />
Name (_HID, "INT33D6" /* Intel Virtual Buttons Device */) // _HID: Hardware ID<br />
Method (_STA, 0, NotSerialized) // _STA: Status<br />
{<br />
If ((OSYS >= 0x07DD))<br />
{<br />
Return (0x0F)<br />
}<br />
Else<br />
{<br />
Return (Zero)<br />
}<br />
}<br />
<br />
Name (VBST, Zero)<br />
Method (VBDL, 0, NotSerialized)<br />
{<br />
If ((^^PCI0.LPCB.EC0.ECOK == One))<br />
{<br />
If ((^^PCI0.LPCB.EC0.CVTS == Zero))<br />
{<br />
VBST = 0x40<br />
}<br />
Else<br />
{<br />
VBST = Zero<br />
}<br />
}<br />
}<br />
<br />
Method (VGBS, 0, NotSerialized)<br />
{<br />
If ((^^PCI0.LPCB.EC0.ECOK == One))<br />
{<br />
If ((^^PCI0.LPCB.EC0.CVTS == Zero))<br />
{<br />
VBST = 0x40<br />
}<br />
Else<br />
{<br />
VBST = Zero<br />
}<br />
}<br />
<br />
Return (VBST) /* \_SB_.VBPA.VBST */<br />
}<br />
}<br />
</pre><br />
<br />
=== Speaker ===<br />
Only the front speakers work out of the box right now. <br />
<br />
=== Accelerometer ===<br />
The accelerometer is not found by any userspace programs, Running <pre>G_MESSAGES_DEBUG=all /usr/sbin/iio-sensor-proxy </pre> from {{aur|iio-sensor-proxy}} gives <pre> ** (process:12472): DEBUG: 11:45:31.305: Could not find any supported sensors </pre><br />
<br />
The accelerometer is connected to a new Intel Integrated Sensor Hub which is not supported by the kernel yet, but can be manually bound to the {{ic|intel-ish-ipc}} driver.<br />
{{hc|$ lspci -nn|...<br />
00:13.0 Non-VGA unclassified device [0000]: Intel Corporation Sunrise Point-H Integrated Sensor Hub [8086:a135] (rev 31)<br />
...}}<br />
<br />
{{bc|# modprobe intel-ish-ipc<br />
# echo "8086 a135" > /sys/bus/pci/drivers/intel_ish_ipc/new_id<br />
}}<br />
{{hc|$ monitor-sensor| Waiting for iio-sensor-proxy to appear<br />
+++ iio-sensor-proxy appeared<br />
=== Has accelerometer (orientation: undefined)<br />
=== No ambient light sensor<br />
Accelerometer orientation changed: normal<br />
}}<br />
<br />
=== Discrete Video ===<br />
Support for this will be available with Mesa 18.1, and linux 4.18.</div>Progandyhttps://wiki.archlinux.org/index.php?title=Dhcpcd&diff=531772Dhcpcd2018-07-31T10:03:29Z<p>Progandy: /* dhcpcd and systemd network interfaces */ describe denyinterfaces as an alternative to binding on a single interface.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:DHCP]]<br />
[[ja:Dhcpcd]]<br />
[[ru:Dhcpcd]]<br />
[[zh-hans:Dhcpcd]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|dhcpd}}<br />
{{Related articles end}}<br />
<br />
''dhcpcd'' is a DHCP and DHCPv6 client. It is currently the most feature-rich open source DHCP client, see the [https://roy.marples.name/projects/dhcpcd home page] for the full list of features.<br />
<br />
{{Note|''dhcpcd'' (DHCP '''client''' daemon) is not the same as [[dhcpd]] (DHCP '''(server)''' daemon).}}<br />
<br />
== Installation ==<br />
<br />
The {{Pkg|dhcpcd}} package is part of the {{Grp|base}} group, so it is likely already [[install]]ed on your system.<br />
<br />
{{AUR|dhcpcd-ui}} is a [[GTK+]] frontend for the ''dhcpcd'' daemon, and optionally [[WPA supplicant]]. It features a configuration dialogue and the ability to enter a pass phrase for wireless networks.<br />
<br />
{{AUR|dhcpcd-ui-patched}} is a patched version of the {{AUR|dhcpcd-ui}} package. It uses AppIndicator instead of GtkStatusIcon and compiles with gtk3. Has a sharp tray icon when used with [[KDE]].<br />
<br />
== Running ==<br />
<br />
To start the daemon for ''all'' network interfaces, [[start/enable]] {{ic|dhcpcd.service}}.<br />
<br />
To start the daemon for a specific interface alone, [[start/enable]] the template unit {{ic|dhcpcd@''interface''.service}}, where ''interface'' can be found with [[Network configuration#Listing network interfaces]].<br />
<br />
Using the template unit is recommended; see [[#dhcpcd and systemd network interfaces]] for details.<br />
<br />
Alternatively, to start ''dhcpcd'' manually, run the following command:<br />
<br />
# dhcpcd ''interface''<br />
<br />
In all of the above, you will be assigned a dynamic IP address. To assign a static IP address, see [[#Static profile]].<br />
<br />
== Configuration ==<br />
<br />
The main configuration is done in {{ic|/etc/dhcpcd.conf}}. See {{man|5|dhcpcd.conf}} for details. Some of the frequently used options are highlighted below.<br />
<br />
=== DHCP static route(s) ===<br />
<br />
If you need to add a static route client-side, add it to {{ic|/etc/dhcpcd.exit-hook}}. The example shows a new hook-script which adds a static route to a VPN subnet on {{ic|10.11.12.0/24}} via a gateway machine at {{ic|192.168.192.5}}:<br />
<br />
{{hc|/etc/dhcpcd.exit-hook|<br />
ip route add 10.11.12.0/24 via 192.168.192.5<br />
}}<br />
<br />
You can add multiple routes to this file.<br />
=== DHCP Client Identifier ===<br />
<br />
The DHCP client may be uniquely identified in different ways by the server: <br />
# hostname (or the hostname value sent by the client), <br />
# MAC address of the network interface controller through which the connection is being made, linked to this is the third, <br />
# Identity Association ID (IAID), which is an abstraction layer to differentiate different use-cases and/or interfaces on a single host, <br />
# DHCP Unique Identifier (DUID). <br />
For a further description, see [https://tools.ietf.org/html/rfc3315#section-4.2 RFC 3315]. <br />
<br />
It depends on the DHCP-server configuration which options are optional or required to request a DHCP IP lease. <br />
{{Note|The ''dhcpcd'' default configuration should be sufficient usually. The listed identifiers are determined automatically and manual configuration changes only be required in case of problems.}} <br />
<br />
If the ''dhcpcd'' default configuration fails to obtain an IP, the following options are available to use in {{ic|dhcpcd.conf}}: <br />
* {{ic|hostname}} sends the hostname set in {{ic|/etc/hostname}}<br />
* {{ic|clientid}} sends the MAC address as identifier<br />
* {{ic|iaid <interface>}} derives the IAID to use for DHCP discovery. It has to be used in an interface block (started by {{ic|interface <interface>}}, see [https://bbs.archlinux.org/viewtopic.php?pid=1388376#p1388376]), but more frequently the next option is used: <br />
* {{ic|duid}} triggers using a combination of DUID and IAID as identifier. <br />
<br />
The DUID value is set in {{ic|/var/lib/dhcpcd/duid}}. For efficient DHCP lease operation it is important that it is unique for the system and applies to all network interfaces alike, while the IAID represents an identifier for each of the systems' interfaces (see [https://tools.ietf.org/html/rfc4361#section-6.1 RFC 4361]). <br />
<br />
Care must be taken on a network running [[Wikipedia:Dynamic DNS|Dynamic DNS]] to ensure that all three IDs are unique. If duplicate DUID values are presented to the DNS server, e.g. in the case where a virtual machine has been cloned and the hostname and MAC have been made unique but the DUID has not been changed, then the result will be that as each client with the duplicated DUID requests a lease the server will remove the predecessor from the DNS record.<br />
<br />
=== Static profile ===<br />
<br />
Required settings are explained in [[Network configuration]]. These typically include the [[network interface]] name, ''IP address'', ''router address'', and ''name server''.<br />
<br />
Configure a static profile for ''dhcpcd'' in {{ic|/etc/dhcpcd.conf}}, for example: <br />
<br />
{{hc|1=/etc/dhcpcd.conf|2=<br />
interface eth0<br />
static ip_address=192.168.0.10/24 <br />
static routers=192.168.0.1<br />
static domain_name_servers=192.168.0.1 8.8.8.8<br />
}}<br />
<br />
More complicated configurations are possible, for example combining with the {{ic|arping}} option. See {{man|5|dhcpcd.conf}} for details.<br />
<br />
==== Fallback profile ====<br />
<br />
It is possible to configure a static profile within ''dhcpcd'' and fall back to it when DHCP lease fails. This is useful particularly for [[wikipedia:Headless computer|headless machines]], where the static profile can be used as "recovery" profile to ensure that it is always possible to connect to the machine.<br />
<br />
The following example configures a {{ic|static_eth0}} profile with {{ic|192.168.1.23}} as IP address, {{ic|192.168.1.1}} as gateway and name server, and makes this profile fallback for interface {{ic|eth0}}.<br />
<br />
{{hc|1=/etc/dhcpcd.conf|2=<br />
# define static profile<br />
profile static_eth0<br />
static ip_address=192.168.1.23/24<br />
static routers=192.168.1.1<br />
static domain_name_servers=192.168.1.1<br />
<br />
# fallback to static profile on eth0<br />
interface ''eth0''<br />
fallback static_eth0<br />
}}<br />
<br />
== Hooks ==<br />
<br />
''dhcpcd'' executes all scripts found in {{ic|/usr/lib/dhcpcd/dhcpcd-hooks/}} in a lexical order. See {{man|5|dhcpcd.conf}} and {{man|8|dhcpcd-run-hooks}} for details.<br />
<br />
{{Note|<br />
* Each script can be disabled using the {{ic|nohook}} option in {{ic|dhcpcd.conf}}.<br />
* The {{ic|env}} option can be used to set an environment variable for '''all''' hooks. For example, you can force the hostname hook to always set the hostname with {{ic|1=env force_hostname=YES}}.<br />
}}<br />
<br />
{{Expansion|describe (at least some) provided hooks.}}<br />
<br />
=== 10-wpa_supplicant ===<br />
<br />
Enable this hook by creating a symbolic link (to ensure that always the current version is used, even after package updates):<br />
<br />
# ln -s /usr/share/dhcpcd/hooks/10-wpa_supplicant /usr/lib/dhcpcd/dhcpcd-hooks/<br />
<br />
The {{ic|10-wpa_supplicant}} hook, if enabled, automatically launches [[WPA supplicant]] on wireless interfaces. It is started only if:<br />
<br />
* no ''wpa_supplicant'' process is already listening on that interface.<br />
* a ''wpa_supplicant'' configuration file exists. ''dhcpcd'' checks<br />
<br />
/etc/wpa_supplicant/wpa_supplicant-''interface''.conf<br />
/etc/wpa_supplicant/wpa_supplicant.conf<br />
/etc/wpa_supplicant-''interface''.conf<br />
/etc/wpa_supplicant.conf<br />
<br />
by default, in that order, but a custom path can be set by adding {{ic|1=env wpa_supplicant_conf=''configuration_file_path''}} into {{ic|/etc/dhcpcd.conf}}.<br />
<br />
{{Note|The hook stops at the first configuration file found, thus you should take this into consideration if you have several ''wpa_supplicant'' configuration files, otherwise ''dhcpcd'' might end up using the wrong file.}}<br />
<br />
If you manage wireless connections with ''wpa_supplicant'' itself, the hook may create unwanted connection events. For example, if you stop ''wpa_supplicant'' the hook may bring the interface up again. Also, if you use [[Netctl#Special systemd units|netctl-auto]], ''wpa_supplicant'' is started automatically with {{ic|/run/network/wpa_supplicant_''interface''.conf}} for config, so starting it again from the hook is unnecessary and may result in boot-time parse errors of the {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} file, which only contains dummy values in the default packaged version. <br />
<br />
To disable the hook, add {{ic|nohook wpa_supplicant}} to {{ic|dhcpcd.conf}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Speed up DHCP by disabling ARP probing ===<br />
<br />
''dhcpcd'' contains an implementation of a recommendation of the DHCP standard ([https://www.ietf.org/rfc/rfc2131.txt RFC2131] section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to {{ic|/etc/dhcpcd.conf}}:<br />
<br />
noarp<br />
<br />
This is equivalent to passing {{ic|--noarp}} to {{ic|dhcpcd}}, and disables the described ARP probing, speeding up connections to networks with DHCP.<br />
<br />
=== Remove old DHCP lease ===<br />
<br />
The file {{ic|/var/lib/dhcpcd/''interface''.lease}}, where {{ic|''interface''}} is the name of the interface on which you have a lease, contains the actual DHCP lease reply sent by the DHCP server. For a wireless interface, the filename is {{ic|/var/lib/dhcpcd/''interface''-''ssid''.lease}}, where {{ic|''ssid''}} is the name of the wireless network. It is used to determine the last lease from the server, and its {{ic|mtime}} attribute is used to determine when it was issued. This last lease information is then used to request the same IP address previously held on a network, if it is available. If you do not want that, simply delete this file. <br />
<br />
If the DHCP server still assigns the same IP address, this may happen because it is configured to keep the assignment stable and recognizes the requesting DHCP client id or DUID (see [[#DHCP Client Identifier]]). You can test it by stopping ''dhcpcd'' and removing or renaming {{ic|/var/lib/dhcpcd/duid}}. ''dhcpcd'' will generate a new one on next run. <br />
<br />
Keep in mind that the DUID is intended as persistent machine identifier across reboots and interfaces. If you are transferring the system to new computer, preserving this file should make it appear as old one.<br />
<br />
=== Different IPs when multi-booting ===<br />
<br />
If you are dualbooting Arch and OS X or Windows and want each to receive different IP addresses, you can exert control about the IPs leased by specifying a different DUID in each operating system installation. <br />
<br />
In Windows (post XP) the DUID should be stored in the <br />
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters\Dhcpv6DUID <br />
registry key. <br />
<br />
On OS X it is directly accessible in {{ic|Network\adapter\dhcp preferences panel}}.<br />
<br />
If you are using a [[dnsmasq]] DHCP server, the different DUIDs can be used in appropriate {{ic|1=dhcp-host=}} rules in its configuration.<br />
<br />
=== resolv.conf ===<br />
<br />
''dhcpcd''' by default overwrites [[resolv.conf]].<br />
<br />
This can be stopped by adding the following to the last section of {{ic|/etc/dhcpcd.conf}}: <br />
<br />
nohook resolv.conf<br />
<br />
Alternatively, you can create a file called {{ic|/etc/resolv.conf.head}} containing your DNS servers. ''dhcpcd'' will prepend this file to the beginning of {{ic|/etc/resolv.conf}}.<br />
<br />
Or you can configure dhcpcd to use the same DNS servers every time. To do this, add the following line at the end of your {{ic|/etc/dhcpcd.conf}}, where {{ic|''dns-server-ip-addressses''}} is a space separated list of DNS IP addresses.<br />
<br />
static domain_name_servers=''dns-server-ip-addresses''<br />
<br />
For example, to set it to Google's DNS servers:<br />
<br />
static domain_name_servers=8.8.8.8 8.8.4.4<br />
<br />
== Troubleshooting ==<br />
<br />
=== Client ID ===<br />
<br />
If you are on a network with DHCPv4 that filters Client IDs based on MAC addresses, you may need to change the following line:<br />
<br />
{{hc|/etc/dhcpcd.conf|<br />
# Use the same DUID + IAID as set in DHCPv6 for DHCPv4 Client ID as per RFC4361. <br />
duid<br />
}}<br />
<br />
To:<br />
<br />
{{hc|/etc/dhcpcd.conf|<br />
# Use the hardware address of the interface for the Client ID (DHCPv4).<br />
clientid<br />
}}<br />
<br />
Else, you may not obtain a lease since the DHCP server may not read your [[wikipedia:DHCPv6|DHCPv6-style]] Client ID correctly. See [https://tools.ietf.org/html/rfc4361 RFC 4361] for more information.<br />
<br />
=== Check DHCP problem by releasing IP first ===<br />
<br />
A problem may occur when DHCP gets a wrong IP assignment, such as when two routers are tied together through a VPN. The router that is connected through the VPN may be assigning IP address. To fix it, as root, release the IP address:<br />
<br />
# dhcpcd -k<br />
<br />
Then request a new one:<br />
<br />
# dhcpcd<br />
<br />
You may have to run those two commands many times.<br />
<br />
=== Problems with noncompliant routers ===<br />
<br />
For some (noncompliant) routers, you will not be able to connect properly unless you comment the line<br />
<br />
require dhcp_server_identifier<br />
<br />
in {{ic|/etc/dhcpcd.conf}}. This should not cause issues unless you have multiple DHCP servers on your network (not typical); see [https://technet.microsoft.com/en-us/library/cc977442.aspx this page] for more information.<br />
<br />
=== dhcpcd and systemd network interfaces ===<br />
<br />
{{ic|dhcpcd.service}} can be [[enabled]] without specifying an interface. This may, however, create a race condition at boot with ''systemd-udevd'' trying to apply a predictable network interface name: <br />
error changing net interface name wlan0 to wlp4s0: Device or resource busy" <br />
<br />
To avoid it, enable ''dhcpcd'' per interface it should bind to as described in [[#Running]]. The downside of the template unit is, however, that it does not support hot-plugging of a wired connection and will fail if the network cable is not connected. To work-around the failure, see [[#Timeout delay]].<br />
<br />
It is also possible to use {{ic|denyinterfaces}} or {{ic|allowinterfaces}} in {{man|5|dhcpcd.conf}} to stop dhcpcd from binding to kernel names, for example<br />
<br />
denyinterfaces wlan* eth*<br />
<br />
=== Timeout delay ===<br />
<br />
If ''dhcpcd'' operates on a single interface and fails to obtain a lease after 30 seconds (for example when the server is not ready or the cable not plugged), it will exit with an error. <br />
<br />
To have ''dhcpcd'' wait indefinitely for one-time, [[edit]] the unit and set the {{ic|timeout}} option to {{ic|0}}:<br />
<br />
{{hc|/etc/systemd/system/dhcpcd@.service.d/timeout.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/dhcpcd -w -q '''-t 0''' %I<br />
}}<br />
<br />
To have it wait indefinitely, let the unit restart after it exited: <br />
<br />
{{hc|/etc/systemd/system/dhcpcd@.service.d/dhcpcdrestart.conf|2=<br />
[Service]<br />
Restart=always<br />
}}<br />
<br />
== Known issues ==<br />
<br />
=== dhcpcd@.service causes slow startup ===<br />
<br />
By default the {{ic|dhcpcd@.service}} waits to get an IP address before forking into the background via the {{ic|-w}} flag for ''dhcpcd''. If the unit is enabled, this may cause the boot to wait for an IP address before continuing. To fix this, create a [[systemd#Drop-in files|drop-in file]] for the unit with the following:<br />
<br />
{{hc|/etc/systemd/system/dhcpcd@.service.d/no-wait.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/dhcpcd -b -q %I<br />
}}<br />
<br />
See also {{Bug|49685}}.<br />
<br />
=== dhcpcd does not remove IP address from interface on release ===<br />
<br />
The issue is described in https://roy.marples.name/archives/dhcpcd-discuss/0002131.html. It will be fixed in dhcpcd version 7.0.6.<br />
<br />
== See also ==<br />
<br />
* {{man|8|dhcpcd}}<br />
* {{man|5|dhcpcd.conf}}</div>Progandyhttps://wiki.archlinux.org/index.php?title=HiDPI&diff=529558HiDPI2018-07-14T08:03:31Z<p>Progandy: /* Side display */ xorg 1.20 should fix the mouse bug</p>
<hr />
<div>[[Category:Graphics]]<br />
[[ja:HiDPI]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related articles end}}<br />
HiDPI (High Dots Per Inch) displays, also known by Apple's "[[wikipedia:Retina Display|Retina Display]]" marketing name, are screens with a high resolution in a relatively small format. They are mostly found in high-end laptops and monitors.<br />
<br />
Not all software behaves well in high-resolution mode yet. Here are listed most common tweaks which make work on a HiDPI screen more pleasant.<br />
<br />
== Desktop environments ==<br />
<br />
=== GNOME ===<br />
To enable HiDPI, Settings > Devices > Displays,or use gsettings:<br />
<br />
$ gsettings set org.gnome.desktop.interface scaling-factor 2<br />
<br />
{{Note|1={{ic|scaling-factor}} only allows whole numbers to be set. 1 = 100%, 2 = 200%, etc...}}<br />
<br />
==== Fractional Scaling ====<br />
<br />
A setting of {{ic|2, 3, etc}}, which is all you can do with {{ic|scaling-factor}}, may not be ideal for certain HiDPI displays and smaller screens (e.g. small tablets). <br />
<br />
*wayland<br />
Enable fractional Scaling experimental-feature:<br />
<br />
$ gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"<br />
<br />
then open Settings > Devices > Displays<br />
<br />
*xorg<br />
<br />
You can achieve any non-integer scale factor by using a combination of GNOME's {{ic|scaling-factor}} and [[xrandr]]. This combination keeps the TTF fonts properly scaled so that they do not become blurry if using {{ic|xrandr}} alone. You specify zoom-in factor with {{ic|gsettings}} and zoom-out factor with [[xrandr]].<br />
<br />
First scale GNOME up to the minimum size which is too big. Usually "2" is already too big, otherwise try "3" etc. Then start scaling down by setting zoom-out factor with [[xrandr]]. First get the relevant output name, the examples below use {{ic|eDP1}}. Start e.g. with zoom-out 1.25 times. If the UI is still too big, increase the scale factor; if it is too small decrease the scale factor.<br />
$ xrandr --output eDP1 --scale 1.25x1.25<br />
<br />
{{Note|To allow the mouse to reach the whole screen, you may need to use the {{ic|--panning}} option as explained in [[#Side display]].}}<br />
<br />
{{Accuracy|The following was initially added under [[#X Resources]]. Clarify how it integrates with the info there or that above for GNOME.|section=GNOME ignores X settings}}<br />
<br />
GNOME ignores X settings due to its xsettings Plugin in Gnome Settings Daemon, where DPI setting is hard coded.<br />
There is blog entry for [http://blog.drtebi.com/2012/12/changing-dpi-setting-on-gnome-34.html recompiling Gnome Settings Daemon].<br />
In the source documentation there is another way mentioned to set X settings DPI:<br />
<br />
You can use the dconf Editor and navigate to key <br />
<br />
/org/gnome/settings-daemon/plugins/xsettings/overrides<br />
<br />
and complement the entry with the value<br />
<br />
'Xft/DPI': <153600><br />
<br />
From README.xsettings<br />
<br />
Noting that variants must be specified in the usual way (wrapped in <>).<br />
<br />
Note also that DPI in the above example is expressed in 1024ths of an inch.<br />
<br />
=== KDE ===<br />
<br />
You can use KDE's settings to fine tune font, icon, and widget scaling. This solution affects both Qt and Gtk+ applications.<br />
<br />
To adjust font, widget, and icon scaling together:<br />
<br />
# System Settings → Display and Monitor → Display Configuration → Scale Display <br />
# Drag the slider to the desired size<br />
# Restart for the settings to take effect<br />
<br />
To adjust only font scaling:<br />
<br />
# System Settings → Fonts<br />
# Check "Force fonts DPI" and adjust the DPI level to the desired value. This setting should take effect immediately for newly started applications. You will have to logout and login for it to take effect on Plasma desktop.<br />
<br />
To adjust only icon scaling:<br />
<br />
# System Settings → Icons → Advanced<br />
# Choose the desired icon size for each category listed. This should take effect immediately.<br />
<br />
'''Display Scale not integer bug :'''<br />
<br />
When you use not integer values for Display Scale it causes font render issue in some QT application ( ex. okular ).<br />
<br />
A workaround for this is to:<br />
# Set the scale value to 1<br />
# Adjust your font and icons and use the "Force fonts DPI" ( this affects all apps, also GTK but not create issue with the fonts )<br />
# Restart KDE<br />
# If required tune the GTK apps using the variables GDK_SCALE/GDK_DPI_SCALE (as described above)<br />
<br />
==== Tray icons with fixed size ====<br />
<br />
The tray icons are not scaled with the rest of the desktop, since Plasma ignores the Qt scaling settings by default. To make Plasma respect the Qt settings, set {{ic|PLASMA_USE_QT_SCALING}} to {{ic|1}}.<br />
<br />
=== Xfce ===<br />
<br />
Go to Settings Manager → Appearance → Fonts, and change the DPI parameter. The value of 180 or 192 seems to work well on Retina screens. To get a more precise number, you can use {{ic|<nowiki>xdpyinfo | grep resolution</nowiki>}}, and then double it.<br />
<br />
To enlarge icons in system tray, right-click on it (aim for empty space / top pixels / bottom pixels, so that you will not activate icons themselves) → “Properties” → set “Maximum icon size” to 32, 48 or 64.<br />
<br />
=== Cinnamon ===<br />
<br />
Has good support out of the box.<br />
<br />
=== Enlightenment ===<br />
<br />
For E18, go to the E Setting panel. In Look → Scaling, you can control the UI scaling ratios. A ratio of 1.2 seems to work well for the native resolution of the MBPr 15" screen.<br />
<br />
== X Server ==<br />
<br />
Some programs use the DPI given by the X server. Examples are i3 ([https://github.com/i3/i3/blob/next/libi3/dpi.c source]) and Chromium ([https://code.google.com/p/chromium/codesearch#chromium/src/ui/views/widget/desktop_aura/desktop_screen_x11.cc source]).<br />
<br />
To verify that the X Server has properly detected the physical dimensions of your monitor, use the ''xdpyinfo'' utility from the {{Pkg|xorg-xdpyinfo}} package:<br />
<br />
$ xdpyinfo | grep -B 2 resolution<br />
screen #0:<br />
dimensions: 3200x1800 pixels (423x238 millimeters)<br />
resolution: 192x192 dots per inch<br />
<br />
This example uses inaccurate dimensions (423mm x 328mm, even though the Dell XPS 9530 has 346mm x 194mm) to have a clean multiple of 96 dpi, in this case 192 dpi. This tends to work better than using the correct DPI — Pango renders fonts crisper in i3 for example.<br />
<br />
If the DPI displayed by xdpyinfo is not correct, see [[Xorg#Display size and DPI]] for how to fix it.<br />
<br />
== X Resources ==<br />
<br />
If you are not using a desktop environment such as KDE, Xfce, or other that manipulates the X settings for you, you can set the desired DPI setting manually via the {{ic|Xft.dpi}} variable in [[Xresources]]:<br />
<br />
{{hc|~/.Xresources|<nowiki><br />
Xft.dpi: 180<br />
Xft.autohint: 0<br />
Xft.lcdfilter: lcddefault<br />
Xft.hintstyle: hintfull<br />
Xft.hinting: 1<br />
Xft.antialias: 1<br />
Xft.rgba: rgb<br />
</nowiki>}}<br />
<br />
Make sure the settings are loaded properly when X starts, for instance in your {{ic|~/.xinitrc}} with {{ic|xrdb -merge ~/.Xresources}} (see [[Xresources]] for more information).<br />
<br />
This will make the font render properly in most toolkits and applications, it will however not affect things such as icon size!<br />
Setting {{ic|Xft.dpi}} at the same time as toolkit scale (e.g. {{ic|GDK_SCALE}}) may cause interface elements to be much larger than intended in some programs like firefox.<br />
<br />
== GUI toolkits ==<br />
<br />
=== Qt 5 ===<br />
<br />
Since Qt 5.6, Qt 5 applications can be instructed to honor screen DPI by setting the {{ic|QT_AUTO_SCREEN_SCALE_FACTOR}} environment variable:<br />
<br />
export QT_AUTO_SCREEN_SCALE_FACTOR=1<br />
<br />
If automatic detection of DPI does not produce the desired effect, scaling can be set manually per-screen ({{ic|QT_SCREEN_SCALE_FACTORS}}) or globally ({{ic|QT_SCALE_FACTOR}}). For more details see the [https://blog.qt.io/blog/2016/01/26/high-dpi-support-in-qt-5-6/ Qt blog post].<br />
<br />
{{Note|<br />
* If you manually set the screen factor, it is important to set {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} otherwise some applications which explicitly force high DPI enabling get scaled twice.<br />
* {{ic|QT_SCALE_FACTOR}} scales fonts, but {{ic|QT_SCREEN_SCALE_FACTORS}} does not scale fonts.<br />
* If you also set the font DPI manually in ''xrdb'' to support other toolkits, {{ic|QT_SCALE_FACTORS}} will give you huge fonts.<br />
}}<br />
<br />
=== GDK 3 (GTK+ 3) ===<br />
<br />
To scale UI elements by a factor of two:<br />
<br />
export GDK_SCALE=2<br />
<br />
To undo scaling of text:<br />
<br />
export GDK_DPI_SCALE=0.5<br />
<br />
=== GTK+ 2 ===<br />
<br />
Scaling of UI elements is not supported by the toolkit itself, however it's possible to generate a theme with elements pre-scaled for HiDPI display using {{AUR|oomox-git}}.<br />
<br />
=== Elementary (EFL) ===<br />
<br />
To scale UI elements by a factor of 1.5:<br />
<br />
export ELM_SCALE=1.5<br />
<br />
For more details see https://phab.enlightenment.org/w/elementary/<br />
<br />
== Boot managers ==<br />
<br />
=== GRUB ===<br />
<br />
==== Lower the framebuffer resolution ====<br />
Set a lower resolution for the framebuffer as explained in [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
==== Change GRUB font size ====<br />
Find a ttf font that you like in {{ic|/usr/share/fonts/}}.<br />
<br />
Convert the font to a format that GRUB can utilize:<br />
<br />
# grub-mkfont -s 30 -o /boot/grubfont.pf2 /usr/share/fonts/FontFamily/FontName.ttf<br />
<br />
{{Note|Change the {{ic|-s 30}} parameter to modify the font size}}<br />
<br />
Edit {{ic|/etc/default/grub}} to set the new font as shown in [[GRUB/Tips and tricks#Background image and bitmap fonts]]:<br />
<br />
GRUB_FONT="/boot/grubfont.pf2"<br />
<br />
Update GRUB configuration by running {{ic|grub-mkconfig -o /boot/grub/grub.cfg}}<br />
<br />
== Applications ==<br />
<br />
=== Browsers ===<br />
<br />
==== Firefox ====<br />
<br />
Firefox should use the [[#GDK 3 (GTK+ 3)]] settings. However, the suggested {{ic|GDK_SCALE}} suggestion doesn't consistently scale the entirety of Firefox, and doesn't work for fractional values (e.g., a factor of 158DPI/96DPI = 1.65 for a 1080p 14" laptop). You may want to use {{ic|GDK_DPI_SCALE}} instead.<br />
<br />
To override those, open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|layout.css.devPixelsPerPx}} to {{ic|2}} (or find the one that suits you better; {{ic|2}} is a good choice for Retina screens), but it also doesn't consistently scale the entirety of Firefox. If Firefox is not scaling fonts, you may want to create {{ic|userChrome.css}} and add appropriate styles to it. More information about {{ic|userChrome.css}} at [http://kb.mozillazine.org/index.php?title=UserChrome.css mozillaZine].<br />
<br />
{{hc|~/.mozilla/firefox/<em><profile></em>/chrome/userChrome.css|@namespace url("http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");<br />
<br />
/* #tabbrowser-tabs, #navigator-toolbox, menuitem, menu, ... */<br />
* {<br />
font-size: 15px !important;<br />
}<br />
<br />
/* exception for badge on adblocker */<br />
.toolbarbutton-badge {<br />
font-size: 8px !important;<br />
}<br />
}}<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use [https://addons.mozilla.org/en-US/firefox/addon/autohidpi/ AutoHiDPI] add-on in order to automatically adjust {{ic|layout.css.devPixelsPerPx}} setting for the active screen. Also, since Firefox version 49, it auto-scales based on your screen resolution, making it easier to deal with 2 or more screens.<br />
<br />
==== Chromium / Google Chrome ====<br />
<br />
Chromium should use the [[#GDK 3 (GTK+ 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--force-device-scale-factor}} flag with a scaling value. This will scale all content and ui, including tab and font size. For example {{ic|1=chromium --force-device-scale-factor=2}}.<br />
<br />
Using this option, a scaling factor of 1 would be normal scaling. Floating point values can be used. To make the change permanent, for Chromium, you can add it to {{ic|~/.config/chromium-flags.conf}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|2=--force-device-scale-factor=2}}<br />
<br />
To make this work for Chrome, add the same option to {{ic|~/.config/chrome-flags.conf}} instead.<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use the [https://chrome.google.com/webstore/detail/resolution-zoom/enjjhajnmggdgofagbokhmifgnaophmh reszoom] extension in order to automatically adjust the zoom level for the active screen.<br />
<br />
==== Opera ====<br />
<br />
Opera should use the [[#GDK 3 (GTK+ 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--alt-high-dpi-setting=X}} command line option, where X is the desired DPI. For example, with {{ic|1=--alt-high-dpi-setting=144}} Opera will assume that DPI is 144. Newer versions of opera will auto detect the DPI using the font DPI setting (in KDE: the force font DPI setting.)<br />
<br />
=== Thunderbird ===<br />
<br />
See [[#Firefox]]. To access {{ic|about:config}}, go to Edit → Preferences → Advanced → Config editor.<br />
<br />
=== Wine applications ===<br />
<br />
Run<br />
$ winecfg<br />
and change the "dpi" setting found in the "Graphics" tab. This only affects the font size.<br />
<br />
=== Skype ===<br />
<br />
Skype for Linux ({{AUR|skypeforlinux-stable-bin}} package) uses [[#GDK 3 (GTK+ 3)]].<br />
<br />
=== Spotify ===<br />
<br />
You can change scale factor by simple {{ic|Ctrl++}} for zoom in, {{ic|Ctrl+-}} for zoom out and {{ic|Ctrl+0}} for default scale. Scaling setting will be saved in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}:<br />
<br />
{{hc|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs|<nowiki><br />
app.browser.zoom-level=100<br />
</nowiki>}}<br />
<br />
Also Spotify can be launched with a custom scaling factor which will be multiplied with setting specified in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, for example<br />
$ spotify --force-device-scale-factor=1.5<br />
<br />
=== Zathura document viewer ===<br />
<br />
No modifications required for document viewing.<br />
<br />
UI text scaling is specified via [https://pwmt.org/projects/zathura/documentation/ configuration file] (note that "font" is a [https://pwmt.org/projects/girara/options/ girara option]):<br />
<br />
set font "monospace normal 20"<br />
<br />
=== Sublime Text 3 ===<br />
Sublime Text 3 has full support for display scaling. Go to Preferences > Settings > User Settings and add {{ic|"dpi_scale": 2.0}} to your settings [http://blog.wxm.be/2014/08/30/sublime-text-3-and-high-dpi-on-linux.html (source)].<br />
<br />
=== IntelliJ IDEA ===<br />
<br />
IntelliJ IDEA 15 and above should include HiDPI support.[http://blog.jetbrains.com/idea/2015/07/intellij-idea-15-eap-comes-with-true-hidpi-support-for-windows-and-linux/] If it does not work, the most convenient way to fix the problem in this case seems to be changing the Override Default Fonts setting:<br />
<br />
:''File -> Settings -> Behaviour & Appearance -> Appearance''<br />
<br />
The addition of {{ic|1=-Dhidpi=true}} to the vmoptions file in either {{ic|$HOME/.IdeaC14/}} or {{ic|/usr/share/intelligj-idea-ultimate-edition/bin/}} of [https://youtrack.jetbrains.com/issue/IDEA-114944 release 14] should not be required anymore.<br />
<br />
=== NetBeans ===<br />
<br />
NetBeans allows the font size of its interface to be controlled using the {{ic|1=--fontsize}} parameter during startup. To make this change permanent edit the {{ic|1=/usr/share/netbeans/etc/netbeans.conf}} file and append the {{ic|1=--fontsize}} parameter to the {{ic|1=netbeans_default_options}} property.[http://wiki.netbeans.org/FaqFontSize]<br />
<br />
The editor fontsize can be controlled from Tools → Option → Fonts & Colors.<br />
<br />
The output window fontsize can be controlled from Tools → Options → Miscelaneous → Output<br />
<br />
=== Gimp 2.8 ===<br />
<br />
Use a high DPI theme, or adjust {{ic|1=gtkrc}} of an existing theme. (Change all occurrences of the size {{ic|1=button}} to {{ic|1=dialog}}, for example {{ic|1=GimpToolPalette::tool-icon-size}}.)<br />
<br />
There is also the [https://github.com/jedireza/gimp-hidpi gimp-hidpi].<br />
<br />
=== Steam ===<br />
<br />
==== Official HiDPI support ====<br />
* Starting on 25 of January 2018 in the beta program there is actual support for HiDPI and it should be automatically detected.<br />
* Steam -> Settings -> Interface -> check "Enlarge text and icons based on monitor size" (restart required)<br />
* If it not automatically detected use {{ic|1=GDK_SCALE=2}} to set the desired scale factor.<br />
<br />
==== Unofficial ====<br />
The [https://github.com/MoriTanosuke/HiDPI-Steam-Skin HiDPI-Steam-Skin] can be installed to increase the font size of the interface. While not perfect, it does improve usability. <br />
<br />
{{Note|The README for the HiDPI skin lists several possible locations for where to place the skin. The correct folder out of these can be identified by the presence of a file named {{ic|1=skins_readme.txt}}.}}<br />
<br />
[http://steamcommunity.com/groups/metroskin/discussions/0/517142253861033946/ MetroSkin Unofficial Patch] also helps with HiDPI on Steam with Linux.<br />
<br />
=== Java applications ===<br />
<br />
Java applications using the AWT/Swing framework can be scaled by defining the sun.java2d.uiScale variable when invoking java. For example,<br />
<br />
java -Dsun.java2d.uiScale=2 -jar some_application.jar<br />
<br />
Since Java 9 the GDK_SCALE environment variable is used to scale Swing applications accordingly.<br />
<br />
=== Mono applications ===<br />
<br />
According to [https://bugzilla.xamarin.com/show_bug.cgi?id=35870], Mono applications should be scalable like [[#GDK 3 (GTK+ 3)|GTK3]] applications.<br />
<br />
=== MATLAB ===<br />
<br />
Recent versions (R2017b) of [[Matlab]] allow to set the scale factor:<br />
>> s = settings;s.matlab.desktop.DisplayScaleFactor<br />
>> s.matlab.desktop.DisplayScaleFactor.PersonalValue = 2<br />
The settings take effect after MATLAB is restarted.<br />
<br />
=== VirtualBox ===<br />
<br />
{{Note|This ony applies to KDE with scaling enabled.}}<br />
VirtualBox also applies the system-wide scaling to the virtual monitor, which reduces the maximum resolution inside VMs by your scaling factor (see [https://www.virtualbox.org/ticket/16604]).<br />
<br />
This can be worked around by calculating the inverse of your scaling factor and manually setting this new scaling factor for the VirtualBox execution, e.g.<br />
$ QT_SCALE_FACTOR=0.5 VirtualBox --startvm vm-name<br />
<br />
=== Zoom ===<br />
<br />
Zoom can be started with a proper scaling by overriding the {{ic|1=QT_SCALE_FACTOR}} environment variable.<br />
<br />
$ QT_SCALE_FACTOR=2 zoom<br />
<br />
=== Unsupported applications ===<br />
<br />
{{AUR|run_scaled-git}} can be used to scale applications (which uses {{Pkg|xpra}} internally).<br />
<br />
Another approach is to run the application full screen and without decoration in its own VNC desktop. Then scale the viewer. With Vncdesk ({{AUR|vncdesk-git}} from the [[AUR]]) you can set up a desktop per application, then start server and client with a simple command such as {{ic|vncdesk 2}}.<br />
<br />
[[x11vnc]] has an experimental option {{ic|-appshare}}, which opens one viewer per application window. Perhaps something could be hacked up with that.<br />
<br />
== Multiple displays ==<br />
The HiDPI setting applies to the whole desktop, so non-HiDPI external displays show everything too large. However, note that setting different scaling factors for different monitors is already supported in [[Wayland]].<br />
<br />
=== Side display ===<br />
{{Out of date|1=The bug with the mouse unable to reach the whole screen should be [https://bugs.freedesktop.org/show_bug.cgi?id=39949#c80 fixed in xorg 1.20].}}<br />
<br />
One workaround is to use [[xrandr]]'s scale option. To have a non-HiDPI monitor (on DP1) right of an internal HiDPI display (eDP1), one could run:<br />
<br />
xrandr --output eDP-1 --auto --output DP-1 --auto --scale 2x2 --right-of eDP-1<br />
<br />
When extending above the internal display, you may see part of the internal display on the external monitor. In that case, specify the position manually, e.g. using [https://gist.github.com/wvengen/178642bbc8236c1bdb67 this script].<br />
<br />
You may run into problems with your mouse not being able to reach the whole screen. That is a [https://bugs.freedesktop.org/show_bug.cgi?id=39949 known bug] with an xserver-org patch (or try the panning option, but that might cause other problems).<br />
<br />
An example of the panning syntax for a 4k laptop with an external 1920x1080 monitor to the right:<br />
<br />
xrandr --output eDP-1 --auto --output HDMI-1 --auto --panning 3840x2160+3840+0 --scale 2x2 --right-of eDP-1<br />
<br />
Generically if your HiDPI monitor is AxB pixels and your regular monitor is CxD and you are scaling by [ExF], the commandline for right-of is:<br />
<br />
xrandr --output eDP-1 --auto --output HDMI-1 --auto --panning [C*E]x[D*F]+[A]+0 --scale [E]x[F] --right-of eDP-1<br />
<br />
If panning is not a solution for you it may be better to set position of monitors and fix manually the total display screen.<br />
<br />
An example of the syntax for a 2560x1440 WQHD 210 DPI laptop monitor (eDP1) using native resolution placed below a 1920x1080 FHD 96 DPI external monitor (HDMI) scaled to match global DPI settings:<br />
<br />
xrandr --output eDP-1 --auto --pos 0x1458 --output HDMI-1 --scale 1.35x1.35 --auto --pos 0x0 --fb 2592x2898<br />
<br />
The total screen size (--fb) and positioning (--pos) are to be calculated taking into account the scaling factor.<br />
<br />
In this case laptop monitor (eDP1) has no scaling and uses native mode for resolution so it will total 2560x1440, but external monitor (HDMI) is scaled and it has to be considered a larger screen so (1920*1.35)x(1080*1.35) from where the eDP1 Y position came 1080*1.35=1458 and the total screen size: since one on top of the other X=(greater between eDP1 and HDMI, so 1920*1.35=2592) and Y=(sum of the calculated heights of eDP1 and HDMI, so 1440+(1080*1.35)=2898).<br />
<br />
Generically if your hidpi monitor is AxB pixels and your regular monitor is CxD and you are scaling by [ExF] and hidpi is placed below regular one, the commandline for right-of is:<br />
<br />
xrandr --output eDP-1 --auto --pos 0x(DxF) --output HDMI-1 --auto --scale [E]x[F] --pos 0x0 --fb [greater between A and (C*E)]x[B+(D*F)]<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
{{Note|1=Above solution with {{ic|--scale 2x2}} does not work on some Nvidia cards. No solution is currently available. [https://bbs.archlinux.org/viewtopic.php?pid=1670840] A potential workaround exists with configuring {{ic|1=ForceFullCompositionPipeline=On}} on the {{ic|CurrentMetaMode}} via {{ic|nvidia-settings}}. For more info see [https://askubuntu.com/a/979551/763549].}}<br />
<br />
=== Multiple external monitors ===<br />
There might be some problems in scaling more than one external monitors which have lower dpi than the built-in HiDPI display. In that case, you may want to try downscaling the HiDPI display instead, with e.g.<br />
<br />
xrandr --output eDP1 --scale 0.5x0.5 --output DP2 --right-of eDP1 --output HDMI1 --right-of DP2<br />
<br />
In addition, when you downscale the HiDPI display, the font on the HiDPI display will be slightly blurry, but it's a different kind of bluriness compared with the one introduced by upscaling the external displays. You may compare and see which kind of bluriness is less problematic for you.<br />
<br />
=== Mirroring ===<br />
<br />
If all you want is to mirror ("unify") displays, this is easy as well:<br />
<br />
With AxB your native HiDPI resolution (for ex 3200x1800) and CxD your external screen resolution (for ex 1920x1200)<br />
<br />
xrandr --output HDMI --scale [A/C]x[B/D]<br />
<br />
In this example which is QHD (3200/1920 = 1.66 and 1800/1200 = 1.5)<br />
<br />
xrandr --output HDMI --scale 1.66x1.5<br />
<br />
For UHD to 1080p (3840/1920=2 2160/1080=2)<br />
<br />
xrandr --output HDMI --scale 2x2<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
== Linux console ==<br />
<br />
The default [[w:Linux console|Linux console]] font will be very small on hidpi displays, the largest font present in the {{Pkg|kbd}} package is {{ic|latarcyrheb-sun32}} and other packages like {{Pkg|terminus-font}} contain further alternatives, such as {{ic|ter-132n}}(normal) and {{ic|ter-132b}}(bold). See [[Fonts#Console fonts]] for configuration details.<br />
<br />
After changing the font, it is often garbled and unreadable when changing to other virtual consoles ({{ic|tty2-6}}). To fix this you can [[Kernel_mode_setting#Forcing_modes_and_EDID|force specific mode]] for KMS, such as {{ic|1=video=2560x1600@60}} (substitute in the native resolution of your HiDPI display), and reboot.<br />
<br />
== See also ==<br />
<br />
* [http://www.phoronix.com/scan.php?page=article&item=linux_uhd4k_gpus Ultra HD 4K Linux Graphics Card Testing] (Nov 2013)<br />
* [http://www.eizo.com/library/basics/pixel_density_4k/ Understanding pixel density]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Isync&diff=529297Isync2018-07-11T22:30:47Z<p>Progandy: /* Configuring */ Link to possible XOAUTH2 login procedure. Method not fully tested and therefore only linked.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Mail retrieval agents]]<br />
[[ja:Isync]]<br />
[http://isync.sourceforge.net/ isync] is a command line application to synchronize mailboxes; it supports Maildir and IMAP4 mailboxes. New messages, message deletions and flag changes can be propagated both ways.<br />
<br />
Synchronization is based on unique message identifiers (UIDs), so no identification conflicts can occur (as opposed to some other mail synchronizers).<br />
Synchronization state is kept in one local text file per mailbox pair; multiple replicas of a mailbox can be maintained.<br />
{{note|isync is the name of the project, mbsync is the name of the executable}}<br />
<br />
==Installing==<br />
<br />
[[Install]] the {{Pkg|isync}} package.<br />
<br />
==Configuring==<br />
<br />
{{Note| Google appears to block isync from downloading emails by default. If you have 2-step authentication enabled, you need to [https://myaccount.google.com/apppasswords set up an app password] and use that with isync, otherwise you need to go to [https://myaccount.google.com/security Google's Security Page] and toggle "Allow less secure apps" to "on".}}<br />
{{Note|1=It might be possible to use XOAUTH2 to authenticate with Google. Some hints are in this [https://bbs.archlinux.org/viewtopic.php?id=238727 forum thread]}}<br />
<br />
{{Note|'''Subfolders''' setting in MaildirStore now seems to be required to be set: [http://isync.sourceforge.net/mbsync.html iSync Config SubFolders] '''SubFolders Legacy''' worked as previous unset - Oct 2017}}<br />
<br />
First create and customize the main configuration file using this example {{ic|~/.mbsyncrc}}:<br />
{{hc|~/.mbsyncrc|2=<br />
<nowiki><br />
IMAPAccount gmail<br />
# Address to connect to<br />
Host imap.gmail.com<br />
User username@gmail.com<br />
Pass ***************<br />
# To store the password in an encrypted file use PassCmd instead of Pass<br />
# PassCmd "gpg2 -q --for-your-eyes-only --no-tty -d ~/.mailpass.gpg"<br />
#<br />
# Use SSL<br />
SSLType IMAPS<br />
# The following line should work. If get certificate errors, uncomment the two following lines and read the "Troubleshooting" section.<br />
CertificateFile /etc/ssl/certs/ca-certificates.crt<br />
#CertificateFile ~/.cert/imap.gmail.com.pem<br />
#CertificateFile ~/.cert/Equifax_Secure_CA.pem<br />
<br />
IMAPStore gmail-remote<br />
Account gmail<br />
<br />
MaildirStore gmail-local<br />
Subfolders Verbatim<br />
# The trailing "/" is important<br />
Path ~/.mail/gmail/<br />
Inbox ~/.mail/gmail/Inbox<br />
<br />
Channel gmail<br />
Master :gmail-remote:<br />
Slave :gmail-local:<br />
# Exclude everything under the internal [Gmail] folder, except the interesting folders<br />
Patterns * ![Gmail]* "[Gmail]/Sent Mail" "[Gmail]/Starred" "[Gmail]/All Mail"<br />
# Or include everything<br />
#Patterns *<br />
# Automatically create missing mailboxes, both locally and on the server<br />
Create Both<br />
# Save the synchronization state files in the relevant directory<br />
SyncState *<br />
</nowiki><br />
}}<br />
<br />
To get rid of the [Gmail]-Stuff (or [Google Mail] as in my case) in each mailbox name, it's possible to use separate Channels for each directory, and later merge them to a group:<br />
{{hc|~/.mbsyncrc|2=<br />
<nowiki><br />
Channel sync-googlemail-default<br />
Master :googlemail-remote:<br />
Slave :googlemail-local:<br />
# Select some mailboxes to sync<br />
Patterns "INBOX" "arch"<br />
<br />
Channel sync-googlemail-sent<br />
Master :googlemail-remote:"[Google Mail]/Gesendet"<br />
Slave :googlemail-local:sent<br />
<br />
Channel sync-googlemail-trash<br />
Master :googlemail-remote:"[Google Mail]/Papierkorb"<br />
Slave :googlemail-local:trash<br />
<br />
# Get all the channels together into a group.<br />
Group googlemail<br />
Channel sync-googlemail-default<br />
Channel sync-googlemail-sent<br />
Channel sync-googlemail-trash<br />
</nowiki><br />
}}<br />
As you can see, name-translations are possible this way, as well.<br />
<br />
==Usage==<br />
First make any folders that were specified as Maildirs.<br />
$ mkdir -p ~/.mail/gmail<br />
Then to retrieve the mail for a specific channel run:<br />
$ mbsync gmail<br />
or to retrive the mail for all channels:<br />
$ mbsync -a<br />
<br />
==Tips and tricks==<br />
=== Automatic synchronization ===<br />
If you want to automatically synchronize your mailboxes, isync can be started automatically with a [[systemd/User]] unit. The following service file can start the {{ic|mbsync}} command:<br />
<br />
{{hc|~/.config/systemd/user/mbsync.service|2=<br />
[Unit]<br />
Description=Mailbox synchronization service<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/mbsync -Va<br />
}}<br />
<br />
{{Note|It's possible this service could trigger without an internet connection. A solution is to add the following into the Unit section:<br />
{{ic|1=After=network.target network-online.target dbus.socket}} }}<br />
<br />
The following timer configures {{ic|mbsync}} to be started 2 minutes after boot, and then every 5 minutes:<br />
<br />
{{hc|~/.config/systemd/user/mbsync.timer|2=<br />
[Unit]<br />
Description=Mailbox synchronization timer<br />
<br />
[Timer]<br />
OnBootSec=2m<br />
OnUnitActiveSec=5m<br />
Unit=mbsync.service<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
Once those two files are created, [[reload]] systemd, then [[enable]] and [[start]] {{ic|mbsync.timer}}, adding the {{ic|--user}} flag to {{ic|systemctl}}.<br />
<br />
{{Tip|The mbsync service now only runs after login. It's also possible to launch the systemd-user instances after boot if you configure [[Systemd/User#Automatic start-up of systemd user instances]].<br />
}}<br />
<br />
====Integration with notmuch or mu4e====<br />
<br />
If you want to run [[notmuch]] or mu/mu4e after automatically synchronizing your mails, it is preferable to modify the above {{ic|mbsync.service}} by adding a post-start hook, like below:<br />
<br />
{{hc|~/.config/systemd/user/mbsync.service|2=<br />
[Unit]<br />
Description=Mailbox synchronization service<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/mbsync -Va<br />
ExecStartPost=/usr/bin/notmuch new<br />
}}<br />
<br />
You can also index {{ic|mu}} by changing the {{ic|ExecStartPost}} line to {{ic|1=ExecStartPost=/usr/bin/mu index}}, or to {{ic|1=ExecStartPost=/usr/bin/emacsclient -e '(mu4e-update-index)'}} if you are running emacsclient and would like to index {{ic|mu4e}}.<br />
<br />
This modification assumes that you have already setup notmuch or mu/mu4e for your user. If the ExecStart command does not execute successfully, the ExecStartPost command will not execute, so be aware of this!<br />
<br />
==Troubleshooting==<br />
<br />
=== SSL error ===<br />
<br />
If you get certificate related errors like<br />
{{bc|<br />
<nowiki><br />
SSL error connecting pop.mail.com (193.222.111.111:143): error:00000012:lib(0):func(0):reason(18) <br />
</nowiki><br />
}}<br />
<br />
you may need to retrieve the server's certificates manually in order for mbsync to correctly verify it.<br />
<br />
==== Step #1: Get the certificates ====<br />
<br />
{{Accuracy|This may not always be needed, e.g. for gmail {{ic|CertificateFile /etc/ssl/certs/ca-certificates.crt}} in the config file may be suffcient|section=Step #1: Get the certificates}}<br />
<br />
{{bc|<br />
<nowiki><br />
$ mkdir ~/.cert<br />
$ openssl s_client -connect some.imap.server:port -showcerts 2>&1 < /dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sed -ne '1,/-END CERTIFICATE-/p' > ~/.cert/some.imap.server.pem<br />
</nowiki><br />
}}<br />
<br />
This will create a certificate file called {{ic|~/.cert/some.imap.server.pem}} (e.g. {{ic|~/.cert/imap.gmail.com.pem}}). Alternatively one can download [https://gist.githubusercontent.com/petRUShka/af96ae25ce8280729b9ea049b929f31d/raw/a79471ce8aee3f6d04049039adf870a53a524f7f/get_certs.sh get_certs.sh] and run it:<br />
<br />
{{bc|<br />
<nowiki><br />
$ mkdir ~/.cert<br />
$ wget https://gist.githubusercontent.com/petRUShka/af96ae25ce8280729b9ea049b929f31d/raw/a79471ce8aee3f6d04049039adf870a53a524f7f/get_certs.sh<br />
$ sh get_certs.sh some.imap.server port ~/.cert/<br />
</nowiki><br />
}}<br />
<br />
<br />
If you wish to do this manually, you may enter:<br />
<br />
{{bc|<br />
<nowiki><br />
$ openssl s_client -connect some.imap.server:port -showcerts<br />
</nowiki><br />
}}<br />
<br />
and it will display output something like:<br />
<br />
{{bc|<br />
<nowiki><br />
CONNECTED(00000003)<br />
depth=1 C = US, O = Google Inc, CN = Google Internet Authority<br />
verify error:num=20:unable to get local issuer certificate<br />
verify return:0<br />
---<br />
Certificate chain<br />
0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=imap.gmail.com<br />
i:/C=US/O=Google Inc/CN=Google Internet Authority<br />
-----BEGIN CERTIFICATE-----<br />
MIIDgDCCAumgAwIBAgIKO3MmiwAAAABopTANBgkqhkiG9w0BAQUFADBGMQswCQYD<br />
VQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZR29vZ2xlIElu<br />
dGVybmV0IEF1dGhvcml0eTAeFw0xMjA5MTIxMTU1NDlaFw0xMzA2MDcxOTQzMjda<br />
MGgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1N<br />
b3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRcwFQYDVQQDEw5pbWFw<br />
LmdtYWlsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2OmU9DjI+DFQ<br />
ThqIN4vL6EqZbzH0ejLKcc+zhxsq9BU5hXohSJ1sS5FUU2vReDKk8fd+ZR3cWtpf<br />
CTYAUSvdnz1ZFjESSzyUBmGRqByhoc0yqdfb61NosA4CDaO+z7DtAgKyecqnAJad<br />
TPYYf9aLk/UgJuc6GseitjzFYonXi6ECAwEAAaOCAVEwggFNMB0GA1UdJQQWMBQG<br />
CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQUFuLyTg2NcsyaEESytZbLbQan<br />
YIowHwYDVR0jBBgwFoAUv8Aw6/VDET5nup6R+/xq2uNrEiQwWwYDVR0fBFQwUjBQ<br />
oE6gTIZKaHR0cDovL3d3dy5nc3RhdGljLmNvbS9Hb29nbGVJbnRlcm5ldEF1dGhv<br />
cml0eS9Hb29nbGVJbnRlcm5ldEF1dGhvcml0eS5jcmwwZgYIKwYBBQUHAQEEWjBY<br />
MFYGCCsGAQUFBzAChkpodHRwOi8vd3d3LmdzdGF0aWMuY29tL0dvb2dsZUludGVy<br />
bmV0QXV0aG9yaXR5L0dvb2dsZUludGVybmV0QXV0aG9yaXR5LmNydDAMBgNVHRMB<br />
Af8EAjAAMBkGA1UdEQQSMBCCDmltYXAuZ21haWwuY29tMA0GCSqGSIb3DQEBBQUA<br />
A4GBAC1LV7tM6pcyVJLcwdPml4DomtowsjTrqvy5ZFa3SMKANK0iZBgFu74O0THX<br />
8SxP/vn4eAs0yRQxcT1ZuoishLGQl5NoimLaQ4BGQnzFQHDJendfaVKDl21GenJp<br />
is72sIrAeprsVU8PbNsllUamWsIjKr3DH5xQdH54hDtzQojY<br />
-----END CERTIFICATE-----<br />
1 s:/C=US/O=Google Inc/CN=Google Internet Authority<br />
i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority<br />
-----BEGIN CERTIFICATE-----<br />
MIICsDCCAhmgAwIBAgIDC2dxMA0GCSqGSIb3DQEBBQUAME4xCzAJBgNVBAYTAlVT<br />
MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0<br />
aWZpY2F0ZSBBdXRob3JpdHkwHhcNMDkwNjA4MjA0MzI3WhcNMTMwNjA3MTk0MzI3<br />
WjBGMQswCQYDVQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZ<br />
R29vZ2xlIEludGVybmV0IEF1dGhvcml0eTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw<br />
gYkCgYEAye23pIucV+eEPkB9hPSP0XFjU5nneXQUr0SZMyCSjXvlKAy6rWxJfoNf<br />
NFlOCnowzdDXxFdF7dWq1nMmzq0yE7jXDx07393cCDaob1FEm8rWIFJztyaHNWrb<br />
qeXUWaUr/GcZOfqTGBhs3t0lig4zFEfC7wFQeeT9adGnwKziV28CAwEAAaOBozCB<br />
oDAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFL/AMOv1QxE+Z7qekfv8atrjaxIk<br />
MB8GA1UdIwQYMBaAFEjmaPkr0rKV10fYIyAQTzOYkJ/UMBIGA1UdEwEB/wQIMAYB<br />
Af8CAQAwOgYDVR0fBDMwMTAvoC2gK4YpaHR0cDovL2NybC5nZW90cnVzdC5jb20v<br />
Y3Jscy9zZWN1cmVjYS5jcmwwDQYJKoZIhvcNAQEFBQADgYEAuIojxkiWsRF8YHde<br />
BZqrocb6ghwYB8TrgbCoZutJqOkM0ymt9e8kTP3kS8p/XmOrmSfLnzYhLLkQYGfN<br />
0rTw8Ktx5YtaiScRhKqOv5nwnQkhClIZmloJ0pC3+gz4fniisIWvXEyZ2VxVKfml<br />
UUIuOss4jHg7y/j7lYe8vJD5UDI=<br />
-----END CERTIFICATE-----<br />
---<br />
Server certificate<br />
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=imap.gmail.com<br />
issuer=/C=US/O=Google Inc/CN=Google Internet Authority<br />
---<br />
No client certificate CA names sent<br />
---<br />
SSL handshake has read 2108 bytes and written 350 bytes<br />
---<br />
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-RC4-SHA<br />
Server public key is 1024 bit<br />
Secure Renegotiation IS supported<br />
Compression: NONE<br />
Expansion: NONE<br />
SSL-Session:<br />
Protocol : TLSv1.1<br />
Cipher : ECDHE-RSA-RC4-SHA<br />
Session-ID: 77136647F42633D82DEDFBB9EB62AB516547A3697D83BD1884726034613C1C09<br />
Session-ID-ctx: <br />
Master-Key: 635957FBA0762B10694560488905F73BDD2DB674C41970542ED079446F27234E2CA51CF26938B8CA56DF5BBC71E429A7<br />
Key-Arg : None<br />
PSK identity: None<br />
PSK identity hint: None<br />
SRP username: None<br />
TLS session ticket lifetime hint: 100800 (seconds)<br />
TLS session ticket:<br />
0000 - d6 5b a0 a7 10 0e 64 04-72 93 7c 9f 94 fa 07 57 .[....d.r.|....W<br />
0010 - f1 8b 9d 24 8b 9d 1b f3-a8 b1 4d 2c a9 00 e1 82 ...$......M,....<br />
0020 - 00 83 1e 3f e5 f2 b2 2c-d2 a8 87 83 16 02 0d 1e ...?...,........<br />
0030 - bf b6 c1 d6 75 21 04 e6-63 6b ab 5b ed 94 7a 30 ....u!..ck.[..z0<br />
0040 - 1a d0 aa 44 c2 04 9b 10-06 28 b5 7b a0 43 a6 0d ...D.....(.{.C..<br />
0050 - 3b 4a 85 1f 2e 07 0a e1-32 9b bd 5d 65 41 4c e2 ;J......2..]eAL.<br />
0060 - 7c d7 43 ec c4 18 77 53-b5 d4 84 b4 c9 bd 51 d6 |.C...wS......Q.<br />
0070 - 2d 4f 2e 10 a6 ed 38 c5-8e 9d f8 8b 8a 63 3f 7b -O....8......c?{<br />
0080 - ee e6 b8 bf 7a f8 b8 e8-47 92 84 f1 9b 0c 63 30 ....z...G.....c0<br />
0090 - 76 d8 e1 44 v..D<br />
<br />
Start Time: 1352632558<br />
Timeout : 300 (sec)<br />
Verify return code: 20 (unable to get local issuer certificate)<br />
---<br />
* OK Gimap ready for requests from 108.78.162.240 o67if11168976yhc.67<br />
</nowiki><br />
}}<br />
<br />
Simply copy the first block that begins with {{ic|-----BEGIN CERTIFICATE-----}} and ends with {{ic|-----END CERTIFICATE-----}}, paste into a file, and save with a .pem extension (this is necessary for the next step). Older instructions state that, with Gmail, both certificate blocks must be saved but on testing this was found to be unnecessary.<br />
<br />
Now, copy the root issuer certificate to your local certificate folder. In this example (Gmail), the root issuer is Equifax Secure Certificate Authority. This certificate is included in the {{pkg|ca-certificates}} package.<br />
<br />
{{bc|<br />
<nowiki><br />
cp /usr/share/ca-certificates/mozilla/Equifax_Secure_CA.crt ~/.cert/Equifax_Secure_CA.pem<br />
</nowiki><br />
}}<br />
<br />
==== Step #2: Setup mbsync ====<br />
<br />
Configure mbsync to use that certificate:<br />
<br />
{{hc|~/.mbsyncrc|2=<br />
<nowiki><br />
IMAPAccount gmail<br />
Host imap.gmail.com<br />
# ...<br />
CertificateFile ~/.cert/imap.gmail.com.pem<br />
<br />
</nowiki><br />
}}<br />
<br />
=== BAD Command with Exchange 2003 ===<br />
<br />
When connecting to an MS Exchange 2003 server, there could be problems when using pipelining (i.e. executing multiple imap commands concurrently). Such an issue could look as follows:<br />
{{bc|sample output of `mbsync -V exchange'<br />
<nowiki><br />
>>> 9 SELECT "arch"^M<br />
* 250 EXISTS<br />
* 0 RECENT<br />
* FLAGS (\Seen \Answered \Flagged \Deleted \Draft $MDNSent)<br />
* OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft $MDNSent)] Permanent flags<br />
* OK [UNSEEN 241] Is the first unseen message<br />
* OK [UIDVALIDITY 4352] UIDVALIDITY value<br />
9 OK [READ-WRITE] SELECT completed.<br />
>>> 10 UID FETCH 1:1000000000 (UID FLAGS)^M<br />
* 1 FETCH (UID 1 FLAGS (\Seen \Answered))<br />
* 2 FETCH (UID 2 FLAGS (\Seen \Answered))<br />
...<br />
* 249 FETCH (UID 696 FLAGS ())<br />
* 250 FETCH (UID 697 FLAGS (\Seen))<br />
10 OK FETCH completed.<br />
>>> 11 APPEND "arch" (\Seen) {4878+}^M<br />
(1 in progress) >>> 12 UID FETCH 697 (BODY.PEEK[])^M<br />
(2 in progress) >>> 13 UID STORE 696 +FLAGS.SILENT (\Deleted)^M<br />
12 BAD Command is not valid in this state.<br />
</nowiki><br />
}}<br />
So command 9 is to select a new folder, command 10 checks the mail and commands 11, 12 and 13 run in parallel, writing/getting/flagging a mail. In this case, the Exchange server would terminate the connection after the BAD return value and go on to the next channel. (And if all went well in this channel, mbsync would return with 0.) After setting<br />
PipelineDepth 1<br />
in the IMAPStore config part of the Exchange, this problem did not occur any more.<br />
<br />
==External links==<br />
*[http://isync.sourceforge.net/ Home page]<br />
*[https://sourceforge.net/projects/isync/ Sourceforge page]<br />
*[https://kevin.deldycke.com/2012/08/gmail-backup-mbsync/ backing up gmail with mbsync]<br />
*[https://www.cyberciti.biz/faq/test-ssl-certificates-diagnosis-ssl-certificate/ How To Verify SSL Certificate From A Shell Prompt]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=528192Pacman/Tips and tricks2018-06-30T01:25:41Z<p>Progandy: /* Listing packages */ mention foreign packages include removal from the repositories.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Tips and tricks]]<br />
[[fa:Pacman tips]]<br />
[[fr:Astuces Pacman]]<br />
[[it:Pacman/Tips and tricks]]<br />
[[ja:Pacman ヒント]]<br />
[[pt:Pacman/Tips and tricks]]<br />
[[ru:Pacman/Tips and tricks]]<br />
[[zh-hans:Pacman/Tips and tricks]]<br />
{{Related articles start}}<br />
{{Related|Mirrors}}<br />
{{Related|Creating packages}}<br />
{{Related articles end}}<br />
For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].<br />
<br />
== Maintenance ==<br />
<br />
{{Expansion|{{ic|1=Usage=}} introduced with pacman 4.2, see [http://allanmcrae.com/2014/12/pacman-4-2-released/]}}<br />
<br />
{{Note|Instead of using ''comm'' (which requires sorted input with ''sort'') in the sections below, you may also use {{ic|grep -Fxf}} or {{ic|grep -Fxvf}}.}}<br />
<br />
See also [[System maintenance]].<br />
<br />
=== Listing packages ===<br />
<br />
You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.<br />
<br />
* List all explicitly installed packages: {{ic|pacman -Qe}}.<br />
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}.<br />
* List all foreign packages (typically manually downloaded and installed or packages removed from the repositories): {{ic|pacman -Qm}}.<br />
* List all native packages (installed from the sync database(s)): {{ic|pacman -Qn}}.<br />
* List packages by regex: {{ic|pacman -Qs ''regex''}}.<br />
* List packages by regex with custom output format: {{ic|expac -s "%-30n %v" ''regex''}} (needs {{Pkg|expac}}).<br />
<br />
==== With size ====<br />
<br />
Figuring out which packages are largest can be useful when trying to free space on your hard drive. There are two options here: get the size of individual packages, or get the size of packages and their dependencies.<br />
<br />
===== Individual packages =====<br />
<br />
The following command will list all installed packages and their individual sizes:<br />
<br />
$ pacman -Qi | awk '/^Name/{name=$3} /^Installed Size/{print $4$5, name}' | sort -h<br />
<br />
===== Packages and dependencies =====<br />
<br />
To list package sizes with their dependencies,<br />
<br />
* Install {{Pkg|expac}} and run {{ic|<nowiki>expac -H M '%m\t%n' | sort -h</nowiki>}}.<br />
* Run {{Pkg|pacgraph}} with the {{ic|-c}} option.<br />
<br />
To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):<br />
<br />
$ expac -S -H M '%k\t%n' ''packages''<br />
<br />
To list explicitly installed packages not in {{Grp|base}} nor {{Grp|base-devel}} with size and description:<br />
<br />
$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <(pacman -Qqg base base-devel | sort)) | sort -n<br />
<br />
==== By date ====<br />
<br />
To list the 20 last installed packages with {{Pkg|expac}}, run:<br />
<br />
$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20<br />
<br />
or, with seconds since the epoch (1970-01-01 UTC):<br />
<br />
$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20<br />
<br />
==== Not in a specified group or repository ====<br />
<br />
{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].}}<br />
<br />
List explicitly installed packages not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qeq | sort) <(pacman -Qgq base base-devel | sort)<br />
<br />
List all installed packages unrequired by other packages, and which are not in the {{Grp|base}} or {{Grp|base-devel}} groups:<br />
<br />
$ comm -23 <(pacman -Qqt | sort) <(pacman -Sqg base base-devel | sort)<br />
<br />
As above, but with descriptions:<br />
<br />
$ expac -HM '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <(pacman -Qqg base base-devel | sort))<br />
<br />
List all installed packages that are ''not'' in the specified repository ''repo_name''<br />
<br />
$ comm -23 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all installed packages that are in the ''repo_name'' repository:<br />
<br />
$ comm -12 <(pacman -Qq | sort) <(pacman -Slq ''repo_name'' | sort)<br />
<br />
List all packages on the Arch Linux ISO that are not in the base group:<br />
<br />
<nowiki>$ comm -23 <(curl https://git.archlinux.org/archiso.git/plain/configs/releng/packages.both) <(pacman -Qqg base | sort)</nowiki><br />
<br />
==== Development packages ====<br />
<br />
To list all development/unstable packages, run:<br />
<br />
$ pacman -Qq | grep -Ee '-(cvs|svn|git|hg|bzr|darcs)$'<br />
<br />
=== Listing files owned by a package with size ===<br />
<br />
This one might come in handy if you have found that a specific package uses a huge amount of space and you want to find out which files make up the most of that.<br />
<br />
$ pacman -Qlq ''package'' | grep -v '/$' | xargs du -h | sort -h<br />
<br />
=== Identify files not owned by any package ===<br />
<br />
If your system has stray files not owned by any package (a common case if you do not [[Enhance system stability#Use the package manager to install software|use the package manager to install software]]), you may want to find such files in order to clean them up. The general process for doing so is:<br />
<br />
# Create a sorted list of the files you want to check ownership of: {{bc|<nowiki>$ find /etc /opt /usr | sort > all_files.txt</nowiki>}}<br />
# Create a sorted list of the files tracked by ''pacman'' (and remove the trailing slashes from directories): {{bc|<nowiki>$ pacman -Qlq | sed 's|/$||' | sort > owned_files.txt</nowiki>}}<br />
# Find lines in the first list that are not in the second: {{bc|$ comm -23 all_files.txt owned_files.txt}}<br />
<br />
This process is tricky in practice because many important files are not part of any package (e.g. files generated at runtime, custom configs) and so will be included in the final output, making it difficult to pick out the files that can be safely deleted.<br />
<br />
{{Tip|The {{Pkg|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output. [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) also allows tracking orphaned files using a configuration script.}}<br />
<br />
=== Removing unused packages (orphans) ===<br />
<br />
For recursively removing orphans and their configuration files:<br />
<br />
# pacman -Rns $(pacman -Qtdq)<br />
<br />
If no orphans were found ''pacman'' outputs {{ic|error: no targets specified}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}.<br />
<br />
{{Note|The arguments {{ic|-Qt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qtt}}).}}<br />
<br />
=== Removing everything but base group ===<br />
<br />
If it is ever necessary to remove all packages except the base group, try this one-liner (requires {{Pkg|pacman-contrib}}):<br />
<br />
# pacman -R $(comm -23 <(pacman -Qq | sort) <((for i in $(pacman -Qqg base); do pactree -ul "$i"; done) | sort -u))<br />
<br />
The one-liner was originally devised in [https://bbs.archlinux.org/viewtopic.php?id=130176 this discussion], and later improved in this article.<br />
<br />
=== Getting the dependencies list of several packages ===<br />
<br />
Dependencies are alphabetically sorted and doubles are removed.<br />
<br />
{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}<br />
<br />
$ pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u<br />
<br />
Alternatively, with {{Pkg|expac}}: <br />
<br />
$ expac -l '\n' %E -S ''packages'' | sort -u<br />
<br />
=== Listing changed backup files ===<br />
<br />
If you want to backup your system configuration files you could copy all files in {{ic|/etc/}}, but usually you are only interested in the files that you have changed. Modified [[Pacnew_and_Pacsave_files#Package_backup_files|backup files]] can be viewed with the following command:<br />
<br />
# pacman -Qii | awk '/^MODIFIED/ {print $2}'<br />
<br />
Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.<br />
<br />
{{Tip|See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows, not only backup files.}}<br />
<br />
=== Back-up the pacman database ===<br />
<br />
The following command can be used to back up the local ''pacman'' database:<br />
<br />
$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local<br />
<br />
Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.<br />
<br />
The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:<br />
<br />
# tar -xjvf pacman_database.tar.bz2<br />
<br />
{{Note|If the ''pacman'' database files are corrupted, and there is no backup file available, there exists some hope of rebuilding the ''pacman'' database. Consult [[#Restore pacman's local database]].}}<br />
<br />
{{Tip|The {{AUR|pakbak-git}} package provides a script and a [[systemd]] service to automate the task. Configuration is possible in {{ic|/etc/pakbak.conf}}.}}<br />
<br />
=== Check changelogs easily ===<br />
<br />
When maintainers update packages, commits are often commented in a useful fashion. Users can quickly check these from the command line by installing {{AUR|pacolog}}. This utility lists recent commit messages for packages from the official repositories or the AUR, by using {{ic|pacolog <package>}}.<br />
<br />
== Installation and recovery ==<br />
<br />
Alternative ways of getting and restoring packages.<br />
<br />
=== Installing packages from a CD/DVD or USB stick ===<br />
<br />
{{Merge|#Custom local repository|Use as an example and avoid duplication}}<br />
<br />
To download packages, or groups of packages:<br />
<br />
# cd ~/Packages<br />
# pacman -Syw base base-devel grub-bios xorg gimp --cachedir .<br />
# repo-add ./custom.db.tar.gz ./*<br />
<br />
Then you can burn the "Packages" folder to a CD/DVD or transfer it to a USB stick, external HDD, etc.<br />
<br />
To install:<br />
<br />
'''1.''' Mount the media:<br />
<br />
# mkdir /mnt/repo<br />
# mount /dev/sr0 /mnt/repo #For a CD/DVD.<br />
# mount /dev/sdxY /mnt/repo #For a USB stick.<br />
<br />
'''2.''' Edit {{ic|pacman.conf}} and add this repository ''before'' the other ones (e.g. extra, core, etc.). This is important. Do not just uncomment the one on the bottom. This way it ensures that the files from the CD/DVD/USB take precedence over those in the standard repositories:<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
[custom]<br />
SigLevel = PackageRequired<br />
Server = file:///mnt/repo/Packages}}<br />
<br />
'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:<br />
<br />
# pacman -Syu<br />
<br />
=== Custom local repository ===<br />
<br />
Use the ''repo-add'' script included with ''pacman'' to generate a database for a personal repository. Use {{ic|repo-add --help}} for more details on its usage. To add a new package to the database, or to replace the old version of an existing package in the database, run:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/package-1.0-1-x86_64.pkg.tar.xz''<br />
<br />
{{Note|A package database is a tar file, optionally compressed. Valid extensions are ''.db'' or ''.files'' followed by an archive extension of ''.tar'', ''.tar.gz'', ''.tar.bz2'', ''.tar.xz'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.}}<br />
<br />
The database and the packages do not need to be in the same directory when using ''repo-add'', but keep in mind that when using ''pacman'' with that database, they should be together. Storing all the built packages to be included in the repository in one directory also allows to use shell glob expansion to add or update multiple packages at once:<br />
<br />
$ repo-add ''/path/to/repo.db.tar.gz /path/to/*.pkg.tar.xz''<br />
<br />
{{Warning|''repo-add'' adds the entries into the database in the same order as passed on the command line. If multiple versions of the same package are involved, care must be taken to ensure that the correct version is added last. In particular, note that lexical order used by the shell depends on the locale and differs from the [https://www.archlinux.org/pacman/vercmp.8.html vercmp] ordering used by ''pacman''.}}<br />
<br />
''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.<br />
<br />
$ repo-remove ''/path/to/repo.db.tar.gz pkgname''<br />
<br />
Once the local repository database has been created, add the repository to {{ic|pacman.conf}} for each system that is to use the repository. An example of a custom repository is in {{ic|pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the case of the example above the repository's name would simply be ''repo''. Reference the repository's location using a {{ic|file://}} url, or via FTP using ftp://localhost/path/to/directory.<br />
<br />
If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.<br />
<br />
=== Network shared pacman cache ===<br />
<br />
If you happen to run several Arch boxes on your LAN, you can share packages so that you can greatly decrease your download times. Keep in mind you should not share between different architectures (i.e. i686 and x86_64) or you will run into problems.<br />
<br />
==== Read-only cache ====<br />
<br />
If you are looking for a quick solution, you can simply run a standalone webserver which other computers can use as a first mirror:<br />
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg<br />
$ sudo -u http darkhttpd /var/cache/pacman/pkg --no-server-id<br />
You could also run darkhttpd as a systemd service for convenience. Just add this server at the top of your {{ic|/etc/pacman.d/mirrorlist}} in client machines with {{ic|1=Server = http&#58;//mymirror:8080}}. Make sure to keep your mirror updated.<br />
<br />
==== Distributed read-only cache ====<br />
<br />
There are Arch-specific tools for automatically discovering other computers on your network offering a package cache. Try {{Pkg|pacredir}}, [[pacserve]], {{AUR|pkgdistcache}}, or {{AUR|paclan}}. pkgdistcache uses Avahi instead of plain UDP which may work better in certain home networks that route instead of bridge between WiFi and Ethernet.<br />
<br />
Historically, there was [https://bbs.archlinux.org/viewtopic.php?id=64391 PkgD] and [https://github.com/toofishes/multipkg multipkg], but they are no longer maintained.<br />
<br />
==== Read-write cache ====<br />
<br />
In order to share packages between multiple computers, simply share {{ic|/var/cache/pacman/}} using any network-based mount protocol. This section shows how to use [[shfs]] or [[SSHFS]] to share a package cache plus the related library-directories between multiple computers on the same local network. Keep in mind that a network shared cache can be slow depending on the file-system choice, among other factors.<br />
<br />
First, install any network-supporting filesystem packages: {{pkg|shfs-utils}}, {{pkg|sshfs}}, {{pkg|curlftpfs}}, {{pkg|samba}} or {{pkg|nfs-utils}}.<br />
<br />
{{Tip|<br />
* To use ''sshfs'' or ''shfs'', consider reading [[Using SSH Keys]].<br />
* By default, ''smbfs'' does not serve filenames that contain colons, which results in the client downloading the offending package afresh. To prevent this, use the {{ic|mapchars}} mount option on the client.<br />
}}<br />
<br />
Then, to share the actual packages, mount {{ic|/var/cache/pacman/pkg}} from the server to {{ic|/var/cache/pacman/pkg}} on every client machine.<br />
<br />
{{Note|Do not make {{ic|/var/cache/pacman/pkg}} or any of its ancestors (e.g., {{ic|/var}}) a symlink. ''Pacman'' expects these to be directories. When ''pacman'' re-installs or upgrades itself, it will remove the symlinks and create empty directories instead. However during the transaction ''pacman'' relies on some files residing there, hence breaking the update process. Refer to {{bug|50298}} for further details.}}<br />
<br />
==== two-way with rsync ====<br />
<br />
Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#rsync daemon]]. On clients synchronize two-way with this share via rsync protocol. Filenames that contain colons are no problem for the rsync protocol.<br />
<br />
Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture dependant sync:<br />
# rsync rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/ ...<br />
# pacman ...<br />
# paccache ...<br />
# rsync /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/ ...<br />
<br />
==== Dynamic reverse proxy cache using nginx ====<br />
<br />
[[nginx]] can be used to proxy requests to official upstream mirrors and cache the results to local disk. All subsequent requests for that file will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of servers with minimal effort. <br />
<br />
{{Warning| This method has a limitation. You must use mirrors that use the same relative path to package files and you must configure your cache to use that same path. In this example, we are using mirrors that use the relative path {{ic|/archlinux/$repo/os/$arch}} and our cache's {{ic|Server}} setting in {{ic|mirrorlist}} is configured similarly.}}<br />
<br />
In this example, we will run the cache server on {{ic|<nowiki>http://cache.domain.local:8080/</nowiki>}} and storing the packages in {{ic|/srv/http/pacman-cache/}}. <br />
<br />
Create the directory for the cache and adjust the permissions so nginx can write files to it:<br />
<br />
# mkdir /srv/http/pacman-cache<br />
# chown http:http /srv/http/pacman-cache<br />
<br />
Next, configure nginx as the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d dynamic cache] (read the comments for an explanation of the commands).<br />
<br />
Finally, update your other Arch Linux servers to use this new cache by adding the following line to the {{ic|mirrorlist}} file:<br />
<br />
{{hc|/etc/pacman.d/mirrorlist|<nowiki><br />
Server = http://cache.domain.local:8080/archlinux/$repo/os/$arch<br />
...<br />
</nowiki>}}<br />
<br />
{{Note| You will need to create a method to clear old packages, as this directory will continue to grow over time. {{ic|paccache}} (which is provided by {{pkg|pacman-contrib}}) can be used to automate this using retention criteria of your choosing. For example, {{ic|find /srv/http/pacman-cache/ -type d -exec paccache -v -r -k 2 -c {} \;}} will keep the last 2 versions of packages in your cache directory.}}<br />
<br />
==== Synchronize pacman package cache using synchronization programs ====<br />
<br />
Use [[Resilio Sync]] or [[Syncthing]] to synchronize the ''pacman'' cache folders (i.e. {{ic|/var/cache/pacman/pkg}}).<br />
<br />
==== Preventing unwanted cache purges ====<br />
<br />
By default, {{Ic|pacman -Sc}} removes package tarballs from the cache that correspond to packages that are not installed on the machine the command was issued on. Because ''pacman'' cannot predict what packages are installed on all machines that share the cache, it will end up deleting files that should not be.<br />
<br />
To clean up the cache so that only ''outdated'' tarballs are deleted, add this entry in the {{ic|[options]}} section of {{ic|/etc/pacman.conf}}:<br />
<br />
CleanMethod = KeepCurrent<br />
<br />
=== Recreate a package from the file system ===<br />
<br />
To recreate a package from the file system, use ''bacman'' (included with ''pacman''). Files from the system are taken as they are, hence any modifications will be present in the assembled package. Distributing the recreated package is therefore discouraged; see [[ABS]] and [[Arch Linux Archive]] for alternatives.<br />
<br />
{{Tip|''bacman'' honours the {{ic|PACKAGER}}, {{ic|PKGDEST}} and {{ic|PKGEXT}} options from {{ic|makepkg.conf}}. Bacman does not currently honor the {{ic|COMPRESS}} options in {{ic|makepkg.conf}}.}}<br />
<br />
An alternative tool would be {{AUR|fakepkg}}. It supports parallelization and can handle multiple input packages in one command, which ''bacman'' both does not support.<br />
<br />
=== List of installed packages ===<br />
<br />
Keeping a list of explicitly installed packages can be useful to speed up installation on a new system:<br />
<br />
$ pacman -Qqe > pkglist.txt<br />
<br />
{{Note|If the option {{ic|-t}} was used, when reinstalling the list all the non-top-level packages would be set as dependencies. With option {{ic|-n}}, foreign packages (e.g. from AUR) would be omitted from the list.}}<br />
<br />
To install packages from the list backup, run:<br />
<br />
# pacman -S - < pkglist.txt<br />
<br />
{{Tip|<br />
* To skip already installed packages, use {{ic|--needed}}.<br />
* Use {{ic|<nowiki>comm -13 <(pacman -Qqdt | sort) <(pacman -Qqdtt | sort) > optdeplist.txt</nowiki>}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.<br />
}}<br />
<br />
In case the list includes foreign packages, such as [[AUR]] packages, remove them first:<br />
<br />
# pacman -S $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))<br />
<br />
To remove all the packages on your system that are not mentioned in the list:<br />
<br />
# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))<br />
<br />
{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}<br />
<br />
If you would like to keep an up-to-date list of explicitly installed packages (e.g. in combination with a versioned {{ic|/etc/}}), you can set up a [[Pacman#Hooks|hook]]. Example:<br />
<br />
[Trigger]<br />
Operation = Install<br />
Operation = Remove<br />
Type = Package<br />
Target = *<br />
<br />
[Action]<br />
When = PostTransaction<br />
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/packages.txt'<br />
<br />
=== Listing all changed files from packages ===<br />
<br />
If you are suspecting file corruption (e.g. by software/hardware failure), but are unsure if files were corrupted, you might want to compare with the hash sums in the packages. This can be done with {{Pkg|pacutils}}:<br />
<br />
# paccheck --md5sum --quiet<br />
<br />
For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing a single file inside a .pkg file|extracted as {{ic|.MTREE}} from the respective package files]].<br />
<br />
{{Note|This should '''not''' be used as is when suspecting malicious changes! In this case security precautions such as using a live medium and an independent source for the hash sums are advised.}}<br />
<br />
=== Reinstalling all packages ===<br />
To reinstall all native packages, use:<br />
<br />
# pacman -Qnq | pacman -S -<br />
<br />
Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qmq}}.<br />
<br />
''Pacman'' preserves the [[installation reason]] by default.<br />
<br />
=== Restore pacman's local database ===<br />
<br />
See [[Pacman/Restore local database]].<br />
<br />
=== Recovering a USB key from existing install ===<br />
<br />
If you have Arch installed on a USB key and manage to mess it up (e.g. removing it while it is still being written to), then it is possible to re-install all the packages and hopefully get it back up and working again (assuming USB key is mounted in {{ic|/newarch}})<br />
<br />
# pacman -S $(pacman -Qq --dbpath /newarch/var/lib/pacman) --root /newarch --dbpath /newarch/var/lib/pacman<br />
<br />
=== Viewing a single file inside a .pkg file ===<br />
<br />
For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:<br />
<br />
$ tar -xOf /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz etc/systemd/logind.conf<br />
<br />
Or you can use {{pkg|vim}} to browse the archive:<br />
<br />
$ vim /var/cache/pacman/pkg/systemd-204-3-x86_64.pkg.tar.xz<br />
<br />
=== Find applications that use libraries from older packages ===<br />
<br />
Even if you installed a package the existing long-running programs (like daemons and servers) still keep using code from old package libraries. And it is a bad idea to let these programs running if the old library contains a security bug.<br />
<br />
Here is a way how to find all the programs that use old packages code:<br />
<br />
# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u<br />
It will print running program name and old library that was removed or replaced with newer content.<br />
<br />
== Performance ==<br />
<br />
=== Download speeds ===<br />
<br />
{{Note|If your download speeds have been reduced to a crawl, ensure you are using one of the many [[mirrors]] and not ftp.archlinux.org, which is [https://www.archlinux.org/news/302/ throttled since March 2007].}}<br />
<br />
When downloading packages ''pacman'' uses the mirrors in the order they are in {{ic|/etc/pacman.d/mirrorlist}}. The mirror which is at the top of the list by default however may not be the fastest for you. To select a faster mirror, see [[Mirrors]].<br />
<br />
''Pacman''<nowiki>'</nowiki>s speed in downloading packages can also be improved by using a different application to download packages, instead of ''pacman''<nowiki>'</nowiki>s built-in file downloader.<br />
<br />
In all cases, make sure you have the latest ''pacman'' before doing any modifications.<br />
<br />
# pacman -Syu<br />
<br />
==== Powerpill ====<br />
<br />
[[Powerpill]] is a ''pacman'' wrapper that uses parallel and segmented downloading to try to speed up downloads for ''pacman''.<br />
<br />
==== wget ====<br />
<br />
This is also very handy if you need more powerful proxy settings than ''pacman''<nowiki>'</nowiki>s built-in capabilities. <br />
<br />
To use {{ic|wget}}, first [[install]] the {{Pkg|wget}} package then modify {{ic|/etc/pacman.conf}} by uncommenting the following line in the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/wget --passive-ftp -c -O %o %u<br />
<br />
Instead of uncommenting the {{ic|wget}} parameters in {{ic|/etc/pacman.conf}}, you can also modify the {{ic|wget}} configuration file directly (the system-wide file is {{ic|/etc/wgetrc}}, per user files are {{ic|$HOME/.wgetrc}}.<br />
<br />
==== aria2 ====<br />
<br />
[[aria2]] is a lightweight download utility with support for resumable and segmented HTTP/HTTPS and FTP downloads. aria2 allows for multiple and simultaneous HTTP/HTTPS and FTP connections to an Arch mirror, which should result in an increase in download speeds for both file and package retrieval.<br />
<br />
{{Note|Using aria2c in ''pacman''<nowiki>'</nowiki>s XferCommand will '''not''' result in parallel downloads of multiple packages. ''Pacman'' invokes the XferCommand with a single package at a time and waits for it to complete before invoking the next. To download multiple packages in parallel, see [[Powerpill]].}}<br />
<br />
Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:<br />
<br />
XferCommand = /usr/bin/aria2c --allow-overwrite=true --continue=true --file-allocation=none --log-level=error --max-tries=2 --max-connection-per-server=2 --max-file-not-found=5 --min-split-size=5M --no-conf --remote-time=true --summary-interval=60 --timeout=5 --dir=/ --out %o %u<br />
<br />
{{Tip|1=[https://bbs.archlinux.org/viewtopic.php?pid=1491879#p1491879 This alternative configuration for using ''pacman'' with aria2] tries to simplify configuration and adds more configuration options.}}<br />
<br />
See [http://aria2.sourceforge.net/manual/en/html/aria2c.html#options OPTIONS] in {{man|1|aria2c}} for used aria2c options.<br />
<br />
* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.<br />
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s). <br />
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.<br />
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.<br />
<br />
==== Other applications ====<br />
<br />
There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:<br />
<br />
* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}<br />
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}<br />
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}<br />
* {{ic|hget}}: {{ic|1=XferCommand = /usr/bin/hget %u -n 2 -skip-tls false}} (please read the [https://github.com/huydx/hget documentation on the Github project page] for more info)<br />
<br />
== Utilities ==<br />
<br />
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{Pkg|lostfiles}}}}<br />
* {{App|Pacmatic|''Pacman'' wrapper to check Arch News before upgrading, avoid partial upgrades, and warn about configuration file changes.|http://kmkeen.com/pacmatic|{{Pkg|pacmatic}}}}<br />
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}<br />
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|http://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}<br />
* {{App|pkgtools|Collection of scripts for Arch Linux packages.|https://github.com/Daenyth/pkgtools|{{AUR|pkgtools}}}}<br />
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}<br />
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}<br />
* {{App|[[Snapper#Wrapping_pacman_transactions_in_snapshots|snap-pac]]|Make ''pacman'' automatically use snapper to create pre/post snapshots like openSUSE's YaST.|https://github.com/wesbarnett/snap-pac|{{pkg|snap-pac}}}}<br />
<br />
=== Graphical front-ends ===<br />
<br />
{{Warning|1=Some front-ends such as {{AUR|octopi}} [https://github.com/aarnt/octopi/issues/134#issuecomment-142099266] perform [[partial upgrade]]s periodically.}}<br />
<br />
* {{App|1=Aarchup|2=Fork of archup. Has the same options as archup plus a few other features. For differences between both please check [https://bbs.archlinux.org/viewtopic.php?id=119129 changelog].|3=https://github.com/aericson/aarchup/|4={{AUR|aarchup}}}}<br />
* {{App|Apper|Application and package manager for KDE using PackageKit.|https://www.kde.org/applications/system/apper/|{{Pkg|apper}}}}<br />
* {{App|Arch-Update|Update indicator for Gnome-Shell.|https://github.com/RaphaelRochet/arch-update|{{AUR|gnome-shell-extension-arch-update}}}}<br />
* {{App|Arch-Update-Notifier| Update indicator for KDE.|https://github.com/I-Dream-in-Code/kde-arch-update-plasmoid|{{AUR|plasma5-applets-kde-arch-update-notifier-git}}}}<br />
* {{App|Discover|Collection of package management tools for KDE, using PackageKit.|https://projects.kde.org/projects/kde/workspace/discover|{{Pkg|discover}}}}<br />
* {{App|GNOME Packagekit|GTK+ based package management tool.|https://freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}<br />
* {{App|GNOME Software|Application manager for GNOME.|https://wiki.gnome.org/Apps/Software|{{pkg|gnome-software}}}}<br />
* {{App|kalu|Small application that will add an icon to your systray and sit there, regularly checking if there's anything new for you to upgrade.|https://jjacky.com/kalu/|{{aur|kalu}}}}<br />
* {{App|pcurses|Package management in a curses frontend.|https://github.com/schuay/pcurses|{{Pkg|pcurses}}}}<br />
* {{App|1=PkgBrowser|2=Application for searching and browsing Arch packages, showing details on selected packages.|3=https://bitbucket.org/kachelaqa/pkgbrowser/wiki/Home|4={{AUR|pkgbrowser}}}}<br />
* {{App|tkPacman|Depends only on Tcl/Tk and X11, and interacts with the package database via the CLI of ''pacman''.|http://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}</div>Progandyhttps://wiki.archlinux.org/index.php?title=Talk:Power_management&diff=527366Talk:Power management2018-06-23T08:43:45Z<p>Progandy: /* Userspace tools */ re</p>
<hr />
<div>== Suspend/resume service files ==<br />
<br />
I have the slight suspicion that the service files posted in the section [[Power Management#Suspend/resume service files]] might not work. Has anybody tried them or is actually using them? <br><br />
-- [[User:Jakobh|jakobh]] [[User talk:Jakobh|✉]] 03:12, 10 May 2013 (UTC)<br />
<br />
: (Mod: the section was moved from [[systemd]] into [[Power Management]], so I moved this post too, fixed link along the way. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:24, 21 August 2013 (UTC))<br />
<br />
== Sleep hooks ==<br />
<br />
Where is the exact difference between '''Suspend/resume service files''' approach and '''Hooks in /usr/lib/systemd/system-sleep'''?<br />
<br />
Is the latter obsolete?<br />
<br />
-- [[User:Orschiro|Orschiro]] 07:33, 17 January 2014<br />
<br />
:From {{ic|systemd-sleep(8)}}:<br />
::"Note that scripts or binaries dropped in {{ic|/usr/lib/systemd/system-sleep/}} are intended for local use only and should be considered hacks."<br />
:It's always preferred to use service files, they are much more flexible in handling the dependencies etc.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:52, 31 January 2014 (UTC)<br />
<br />
== Delayed hibernation service ==<br />
<br />
I have found that the service file given in this section does not work. My laptop hibernates immediately after resuming from suspend. I have also found that the older version of this service found in the forum post does indeed work perfectly. Does anyone know why this is?<br />
[[User:Aouellette|Aouellette]] ([[User talk:Aouellette|talk]]) 16:16, 30 May 2015 (UTC)<br />
<br />
== Resume file does not work after resuming from hibernation ==<br />
<br />
The systemd unit {{ic|User resume actions}} presented on this page only worked for me after resuming from sleep, not from hibernate. <br />
After adding {{ic|hibernate.target}} to the {{ic|After}} and {{ic|WantedBy}} lines it works both ways.<br />
However this is the first time I've done anything with such service files so I ain't sure if this is the optimal way.<br />
Can anyone confirm?<br />
<br />
{{unsigned|18:30, 12 October 2015|PhilippD}}<br />
<br />
:Actually, the {{ic|suspend@.service}} in [[Power_management#Suspend.2Fresume_service_files]] binds to {{ic|sleep.target}}, but {{ic|resume@.service}} binds to {{ic|suspend.target}}. They are not synonyms, systemd triggers {{ic|suspend.target}} and {{ic|sleep.target}} when the system is suspended to RAM, and {{ic|hibernate.target}} and {{ic|sleep.target}} when it is suspended to disk. This way you can bind your service to either one or both suspend methods using just a single target. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:17, 12 October 2015 (UTC)<br />
<br />
== Bluetooth rfkill ==<br />
<br />
Systemd now provides {{ic|systemd-rkfill.service}}. If you use {{ic|rfkill block}} to disable bluetooth, {{ic|systemd-rfkill.service}} will remember this and restore this state on next boot -- [[User:robtaylor|robtaylor]] ([[User talk:robtaylor|talk]]) Wed 18 May 16:10:05 BST 2016<br />
<br />
== A "sensible value" for the laptop mode ==<br />
<br />
The vast amount of specific information carried in this part, I find it a bit surprising. It seems "A sensible value for the laptop mode 'knob' is 5 seconds." could be heard in the mouth of a politician kicking the ball into touch.<br />
<br />
From Documentation/laptops/laptop-mode.txt:<br />
<br />
> The value of the laptop_mode knob determines the time between the occurrence of disk I/O <br />
and when the flush is triggered. A sensible value for the knob is 5 seconds. Setting the knob<br />
to 0 disables laptop mode.<br />
<br />
So "5 (seconds)" is related to the virtual memory subsystem (in direct relation to ''vm.dirty_writeback_centisecs''). Then "0" turns laptop mode off, aha. It'd be cool to know *what* is laptop_mode is in the first place: Is it the whole vm configuration settings that are described in the docs? I believe not, as e.g. the conf files are not to be seen in present Arch (nor in other distros I know of).<br />
<br />
A few things changed a bit since the Documentation/laptops/laptop-mode.txt was last edited, in 2004. I've searched extensively which part of it might still be up to date, without success so far. ''TLP'' has many if not most of the settings the doc explains. And so looks as an evolution of ''laptop_mode''. Would a guru or someone with knowledge about that be kind enough to specify the effect of ''vm.laptop_mode''? [[User:Kozaki|kozaki]] ([[User talk:Kozaki|talk]]) 23:33, 1 September 2016 (UTC)<br />
<br />
:The effect of the {{ic|vm.laptop_mode}} is described in the kernel docs in "The Details" section. The scripts that the docs talk about are probably [[Laptop Mode Tools]] nowadays. They are needed only to switch settings based on the current power source (and as a "bonus" they integrate most of the things in the [[Power_management#Power_saving]] section), but I bet the kernel settings are mostly the same as in 2004. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:41, 2 September 2016 (UTC)<br />
<br />
:: I now see that, thank you Lahwaacz. Now as we may increase flush time to disk (to, say, ten minutes) via {{ic|vm.dirty_writeback_centisecs}}, delaying the flush up to five seconds via the {{ic|vm.laptop_mode}} knob doesn't make much sense regarding the ''disk'' power-savings... But it may help the ''cpu'' staying idle longer. Hence, whether set via [[laptop-mode-tools]], [[tlp]] or proper self-made [[udev]] rules. I.e. {{ic|vm.laptop_mode}} and {{ic|vm.dirty_*}} together help delaying and grouping system's activity ''as a whole'', allowing for longer power-saving efficient idle times. Please correct me if I'm wrong. [[User:Kozaki|kozaki]] ([[User talk:Kozaki|talk]]) 19:37, 4 September 2016 (UTC)<br />
<br />
::: True, but the delay via {{ic|vm.laptop_mode}} makes sense also for other reasons. Let's say {{ic|vm.dirty_writeback_centisecs}} is set to something like 10 minutes and the disk is spun down due to inactivity and stays like that for e.g. 8 minutes, when it spins up due to user activity. Flushing all the cummulated dirty pages to the disk immediately might delay the request which caused the disk to spin up, so it's better to wait couple of seconds until there is chance that small high-priority requests have been serviced. Also, it might take couple of seconds to spin up the disk. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 4 September 2016 (UTC)<br />
<br />
== <s>xss-lock</s> ==<br />
<br />
First of all I'm wondering why we are linking {{AUR|xss-lock-git}} instead of {{AUR|xss-lock}}. Secondly I wonder why we recommend the {{ic|-n}} flag; don't we want it to fork if we are closing the lid so presumably putting the computer into suspend/hibernate?<br />
<br />
--[[User:Lindhe|Lindhe]] ([[User talk:Lindhe|talk]]) 20:09, 25 April 2017 (UTC)<br />
<br />
:xss-lock-git is used because the release version has some bugs such as 100% CPU with certain window managers (for details, see upstream). The -n option is as used in the man page; a separate option is provided if you want to use the i3lock forking mode. The computer should however suspend regardless. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:57, 25 April 2017 (UTC)<br />
<br />
::As of 23rd Jan 2018, the official package is even with git master so this is resolved. Closing now. -- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 10:25, 21 June 2018 (UTC)<br />
<br />
== suspend to hibernate require fix ==<br />
<br />
Rather than overriding the <code>suspend.target</code>, I think we should just add <code>RequiredBy=suspend.target</code> in the <code>[Install]</code> section of the service. It works for me, and I think this is cleaner. Can anyone else confirm that this works?<br />
--[[User:Svvac|Svvac]] ([[User talk:Svvac|talk]]) 14:16, 28 May 2017 (UTC)<br />
<br />
== network interfaces: udev rule does not work ==<br />
<br />
At least a few other wiki pages point to this rule for how an example of how to turn off power management, because power mananagement breaks some current cards using the iwlwifi driver. Unfortunately the given udev rule does not work due to persistent device names. There is a note here about persistent device names, but it is really confusing. It stresses the importance of the number in the file name, but then states that it actually wont work anyway and to use the persistent name instead of the wildcard?? However even that won't work because the udev rule above has ACTION="add". At least in my case, that ACTION clause causes the rule to only trigger for the original device name (wlan0), and not the persistent name (wlp5s0). So if I use wlan0 everywhere, it triggers but has no effect. If I use wlp5s0 everywhere it never triggers. One solution is to remove the ACTION="add" clause and use the persistent name everywhere. Another solution is to continue using a wildcard in KERNEL, such as KERNEL="wl*", and then use the persistent name instead of %k in the RUN command. I chose the second solution and my full udev rule was this:<br />
<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", RUN+="/usr/bin/iw dev wlp5s0 set power_save off"<br />
<br />
Note that I also tried using 99 instead of 70 for the filename with the original udev rule, but that did not work. [[User:Lllars|Lllars]] ([[User talk:Lllars|talk]]) 23:10, 5 August 2017 (UTC)<br />
<br />
:What the note tries to say is that you can't "use wlan0" everywhere as you did. In any case, the command is run ''after'' the interface gets a persistent name, so you need to run {{ic|iw dev wlp5s0 set power_save off}} (or, as the note says, {{ic|iw dev $name set power_save off}} to make it generic). As for the matching, {{ic|KERNEL}} is the "old name" and {{ic|NAME}} is the "new name", which is assigned in {{ic|80-net-setup-link.rules}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:57, 6 August 2017 (UTC)<br />
<br />
::Ok. In a way it's nice to have so much detail about how udev manages the initial and persistent names. But the way this is currently written is still very confusing. Thanks to $name, it sounds like we could just change the given udev rule to:<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", RUN+="/usr/bin/iw dev $name set power_save on"<br />
::with a note about how some people will need to use "eth*" instead of "wl*", or off instead of on. Then the whole section about persistent names is unnecessary extra info, and could either be ommitted or clarified and kept as an informational side note.[[User:Lllars|Lllars]] ([[User talk:Lllars|talk]]) 02:22, 7 August 2017 (UTC)<br />
<br />
:::Note that there are people who [[Network_configuration#Revert_to_traditional_device_names|don't use the persistent names]] at all. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:17, 7 August 2017 (UTC)<br />
<br />
== RTC drift bug in suspend-to-hibernate script ==<br />
<br />
For some time now I have been trying to figure out an issue with my laptop that seems to happen when I use the suspend-to-hibernate script: the laptop would immediately wake up after hibernating.<br />
<br />
I took some more time to investigate today, and I think (unfortunately not confirmed 100% yet - the issue was fairly rare) that there is a race in the script that causes the RTC to immediately wake up the computer after it gets suspended. Specifically, the RTC is reset after the hibernate has started, so it is possible that the reset does not happen before the computer hibernates.<br />
<br />
Further, the source for the current time is the command {{ic|date}}, whereas the RTC's idea of time might be a little different. I confirmed this by outputting {{ic|/sys/class/rtc/rtc0/since_epoch}} at the same time as {{ic|date +%s}} and saw delays as large as 4 seconds, but I suppose it could also get larger.<br />
<br />
Combining the RTC drift and the fact that the RTC wakealarm reset happens after the hibernate has started, it is possible for the computer to immediately wake up from hibernation right after it hibernates if that happens quickly enough. This was especially noticeable in my case as it would then wait for me to enter my encryption password and drain my battery, overheating the CPU and the insides of my backpack.<br />
<br />
I have two proposed changes to the script to make it better, but I suppose either one would fix the issue:<br />
<br />
# Use {{ic|/sys/class/rtc/rtc0/since_epoch}} as a base for the wakeup time, rather than {{ic|date}};<br />
# Reset the RTC wakealarm before hibernating (right after reading it would be ideal).<br />
<br />
<br />
I will keep investigating to see if I don't get the issue anymore (as I said, it was fairly rare and thus hard to confirm that it has definitely stopped happening), but if I don't see it in the next week, I'll submit an edit to the wiki.<br />
<br />
--[[User:Cynary|Cynary]] ([[User talk:Cynary|talk]]) 09:16, 20 February 2018 (UTC)<br />
<br />
== Userspace tools ==<br />
<br />
[[Power management#Userspace tools]] now provides a list of graphical power managers and statistics tools as well as laptop power managers for the commandline. The recommendation to use only one of the listed tools because they conflict doesn't really fit anymore, how should that be changed? <br />
-- [[User:Progandy|Progandy]] ([[User talk:Progandy|talk]]) 12:42, 20 June 2018 (UTC)<br />
<br />
:It could be changed to something like this: ''Be aware that using some of these tools in combination can result in unexpected behavior, such as double suspends. Please consult the documentation of the tool in question to see if there are any possible conflicts.''<br />
:-- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 16:12, 20 June 2018 (UTC)<br />
<br />
::That sounds good. I looked a bit closer and most (all?) of the GUI tools do not have anything to do with power saving, they only monitor and sometimes react to low battery charge states. Maybe it would be better to split the list between power saving and power monitoring instead of GUI/Console? acpid and powertop do both, though.<br />
::[[User:Progandy|Progandy]] ([[User talk:Progandy|talk]]) 18:37, 22 June 2018 (UTC)<br />
<br />
:::Most GUI tools are not just monitors, e.g. MATE Power Manager can be used to turn off the screen and suspend the system after specified time, which definitely saves the power. On the other hand, most console tools are more advanced solutions, allowing more detailed power tweaks.<br />
:::--[[User:City-busz|City-busz]] ([[User talk:City-busz|talk]]) 22:02, 22 June 2018 (UTC)<br />
<br />
::::Oh right, I somehow missed backlight and sleep management.<br />
::::[[User:Progandy|Progandy]] ([[User talk:Progandy|talk]]) 08:43, 23 June 2018 (UTC)</div>Progandyhttps://wiki.archlinux.org/index.php?title=Talk:Power_management&diff=527335Talk:Power management2018-06-22T18:37:12Z<p>Progandy: /* Userspace tools */ re</p>
<hr />
<div>== Suspend/resume service files ==<br />
<br />
I have the slight suspicion that the service files posted in the section [[Power Management#Suspend/resume service files]] might not work. Has anybody tried them or is actually using them? <br><br />
-- [[User:Jakobh|jakobh]] [[User talk:Jakobh|✉]] 03:12, 10 May 2013 (UTC)<br />
<br />
: (Mod: the section was moved from [[systemd]] into [[Power Management]], so I moved this post too, fixed link along the way. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:24, 21 August 2013 (UTC))<br />
<br />
== Sleep hooks ==<br />
<br />
Where is the exact difference between '''Suspend/resume service files''' approach and '''Hooks in /usr/lib/systemd/system-sleep'''?<br />
<br />
Is the latter obsolete?<br />
<br />
-- [[User:Orschiro|Orschiro]] 07:33, 17 January 2014<br />
<br />
:From {{ic|systemd-sleep(8)}}:<br />
::"Note that scripts or binaries dropped in {{ic|/usr/lib/systemd/system-sleep/}} are intended for local use only and should be considered hacks."<br />
:It's always preferred to use service files, they are much more flexible in handling the dependencies etc.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:52, 31 January 2014 (UTC)<br />
<br />
== Delayed hibernation service ==<br />
<br />
I have found that the service file given in this section does not work. My laptop hibernates immediately after resuming from suspend. I have also found that the older version of this service found in the forum post does indeed work perfectly. Does anyone know why this is?<br />
[[User:Aouellette|Aouellette]] ([[User talk:Aouellette|talk]]) 16:16, 30 May 2015 (UTC)<br />
<br />
== Resume file does not work after resuming from hibernation ==<br />
<br />
The systemd unit {{ic|User resume actions}} presented on this page only worked for me after resuming from sleep, not from hibernate. <br />
After adding {{ic|hibernate.target}} to the {{ic|After}} and {{ic|WantedBy}} lines it works both ways.<br />
However this is the first time I've done anything with such service files so I ain't sure if this is the optimal way.<br />
Can anyone confirm?<br />
<br />
{{unsigned|18:30, 12 October 2015|PhilippD}}<br />
<br />
:Actually, the {{ic|suspend@.service}} in [[Power_management#Suspend.2Fresume_service_files]] binds to {{ic|sleep.target}}, but {{ic|resume@.service}} binds to {{ic|suspend.target}}. They are not synonyms, systemd triggers {{ic|suspend.target}} and {{ic|sleep.target}} when the system is suspended to RAM, and {{ic|hibernate.target}} and {{ic|sleep.target}} when it is suspended to disk. This way you can bind your service to either one or both suspend methods using just a single target. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:17, 12 October 2015 (UTC)<br />
<br />
== Bluetooth rfkill ==<br />
<br />
Systemd now provides {{ic|systemd-rkfill.service}}. If you use {{ic|rfkill block}} to disable bluetooth, {{ic|systemd-rfkill.service}} will remember this and restore this state on next boot -- [[User:robtaylor|robtaylor]] ([[User talk:robtaylor|talk]]) Wed 18 May 16:10:05 BST 2016<br />
<br />
== A "sensible value" for the laptop mode ==<br />
<br />
The vast amount of specific information carried in this part, I find it a bit surprising. It seems "A sensible value for the laptop mode 'knob' is 5 seconds." could be heard in the mouth of a politician kicking the ball into touch.<br />
<br />
From Documentation/laptops/laptop-mode.txt:<br />
<br />
> The value of the laptop_mode knob determines the time between the occurrence of disk I/O <br />
and when the flush is triggered. A sensible value for the knob is 5 seconds. Setting the knob<br />
to 0 disables laptop mode.<br />
<br />
So "5 (seconds)" is related to the virtual memory subsystem (in direct relation to ''vm.dirty_writeback_centisecs''). Then "0" turns laptop mode off, aha. It'd be cool to know *what* is laptop_mode is in the first place: Is it the whole vm configuration settings that are described in the docs? I believe not, as e.g. the conf files are not to be seen in present Arch (nor in other distros I know of).<br />
<br />
A few things changed a bit since the Documentation/laptops/laptop-mode.txt was last edited, in 2004. I've searched extensively which part of it might still be up to date, without success so far. ''TLP'' has many if not most of the settings the doc explains. And so looks as an evolution of ''laptop_mode''. Would a guru or someone with knowledge about that be kind enough to specify the effect of ''vm.laptop_mode''? [[User:Kozaki|kozaki]] ([[User talk:Kozaki|talk]]) 23:33, 1 September 2016 (UTC)<br />
<br />
:The effect of the {{ic|vm.laptop_mode}} is described in the kernel docs in "The Details" section. The scripts that the docs talk about are probably [[Laptop Mode Tools]] nowadays. They are needed only to switch settings based on the current power source (and as a "bonus" they integrate most of the things in the [[Power_management#Power_saving]] section), but I bet the kernel settings are mostly the same as in 2004. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:41, 2 September 2016 (UTC)<br />
<br />
:: I now see that, thank you Lahwaacz. Now as we may increase flush time to disk (to, say, ten minutes) via {{ic|vm.dirty_writeback_centisecs}}, delaying the flush up to five seconds via the {{ic|vm.laptop_mode}} knob doesn't make much sense regarding the ''disk'' power-savings... But it may help the ''cpu'' staying idle longer. Hence, whether set via [[laptop-mode-tools]], [[tlp]] or proper self-made [[udev]] rules. I.e. {{ic|vm.laptop_mode}} and {{ic|vm.dirty_*}} together help delaying and grouping system's activity ''as a whole'', allowing for longer power-saving efficient idle times. Please correct me if I'm wrong. [[User:Kozaki|kozaki]] ([[User talk:Kozaki|talk]]) 19:37, 4 September 2016 (UTC)<br />
<br />
::: True, but the delay via {{ic|vm.laptop_mode}} makes sense also for other reasons. Let's say {{ic|vm.dirty_writeback_centisecs}} is set to something like 10 minutes and the disk is spun down due to inactivity and stays like that for e.g. 8 minutes, when it spins up due to user activity. Flushing all the cummulated dirty pages to the disk immediately might delay the request which caused the disk to spin up, so it's better to wait couple of seconds until there is chance that small high-priority requests have been serviced. Also, it might take couple of seconds to spin up the disk. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 4 September 2016 (UTC)<br />
<br />
== <s>xss-lock</s> ==<br />
<br />
First of all I'm wondering why we are linking {{AUR|xss-lock-git}} instead of {{AUR|xss-lock}}. Secondly I wonder why we recommend the {{ic|-n}} flag; don't we want it to fork if we are closing the lid so presumably putting the computer into suspend/hibernate?<br />
<br />
--[[User:Lindhe|Lindhe]] ([[User talk:Lindhe|talk]]) 20:09, 25 April 2017 (UTC)<br />
<br />
:xss-lock-git is used because the release version has some bugs such as 100% CPU with certain window managers (for details, see upstream). The -n option is as used in the man page; a separate option is provided if you want to use the i3lock forking mode. The computer should however suspend regardless. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:57, 25 April 2017 (UTC)<br />
<br />
::As of 23rd Jan 2018, the official package is even with git master so this is resolved. Closing now. -- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 10:25, 21 June 2018 (UTC)<br />
<br />
== suspend to hibernate require fix ==<br />
<br />
Rather than overriding the <code>suspend.target</code>, I think we should just add <code>RequiredBy=suspend.target</code> in the <code>[Install]</code> section of the service. It works for me, and I think this is cleaner. Can anyone else confirm that this works?<br />
--[[User:Svvac|Svvac]] ([[User talk:Svvac|talk]]) 14:16, 28 May 2017 (UTC)<br />
<br />
== network interfaces: udev rule does not work ==<br />
<br />
At least a few other wiki pages point to this rule for how an example of how to turn off power management, because power mananagement breaks some current cards using the iwlwifi driver. Unfortunately the given udev rule does not work due to persistent device names. There is a note here about persistent device names, but it is really confusing. It stresses the importance of the number in the file name, but then states that it actually wont work anyway and to use the persistent name instead of the wildcard?? However even that won't work because the udev rule above has ACTION="add". At least in my case, that ACTION clause causes the rule to only trigger for the original device name (wlan0), and not the persistent name (wlp5s0). So if I use wlan0 everywhere, it triggers but has no effect. If I use wlp5s0 everywhere it never triggers. One solution is to remove the ACTION="add" clause and use the persistent name everywhere. Another solution is to continue using a wildcard in KERNEL, such as KERNEL="wl*", and then use the persistent name instead of %k in the RUN command. I chose the second solution and my full udev rule was this:<br />
<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", RUN+="/usr/bin/iw dev wlp5s0 set power_save off"<br />
<br />
Note that I also tried using 99 instead of 70 for the filename with the original udev rule, but that did not work. [[User:Lllars|Lllars]] ([[User talk:Lllars|talk]]) 23:10, 5 August 2017 (UTC)<br />
<br />
:What the note tries to say is that you can't "use wlan0" everywhere as you did. In any case, the command is run ''after'' the interface gets a persistent name, so you need to run {{ic|iw dev wlp5s0 set power_save off}} (or, as the note says, {{ic|iw dev $name set power_save off}} to make it generic). As for the matching, {{ic|KERNEL}} is the "old name" and {{ic|NAME}} is the "new name", which is assigned in {{ic|80-net-setup-link.rules}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:57, 6 August 2017 (UTC)<br />
<br />
::Ok. In a way it's nice to have so much detail about how udev manages the initial and persistent names. But the way this is currently written is still very confusing. Thanks to $name, it sounds like we could just change the given udev rule to:<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", RUN+="/usr/bin/iw dev $name set power_save on"<br />
::with a note about how some people will need to use "eth*" instead of "wl*", or off instead of on. Then the whole section about persistent names is unnecessary extra info, and could either be ommitted or clarified and kept as an informational side note.[[User:Lllars|Lllars]] ([[User talk:Lllars|talk]]) 02:22, 7 August 2017 (UTC)<br />
<br />
:::Note that there are people who [[Network_configuration#Revert_to_traditional_device_names|don't use the persistent names]] at all. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:17, 7 August 2017 (UTC)<br />
<br />
== RTC drift bug in suspend-to-hibernate script ==<br />
<br />
For some time now I have been trying to figure out an issue with my laptop that seems to happen when I use the suspend-to-hibernate script: the laptop would immediately wake up after hibernating.<br />
<br />
I took some more time to investigate today, and I think (unfortunately not confirmed 100% yet - the issue was fairly rare) that there is a race in the script that causes the RTC to immediately wake up the computer after it gets suspended. Specifically, the RTC is reset after the hibernate has started, so it is possible that the reset does not happen before the computer hibernates.<br />
<br />
Further, the source for the current time is the command {{ic|date}}, whereas the RTC's idea of time might be a little different. I confirmed this by outputting {{ic|/sys/class/rtc/rtc0/since_epoch}} at the same time as {{ic|date +%s}} and saw delays as large as 4 seconds, but I suppose it could also get larger.<br />
<br />
Combining the RTC drift and the fact that the RTC wakealarm reset happens after the hibernate has started, it is possible for the computer to immediately wake up from hibernation right after it hibernates if that happens quickly enough. This was especially noticeable in my case as it would then wait for me to enter my encryption password and drain my battery, overheating the CPU and the insides of my backpack.<br />
<br />
I have two proposed changes to the script to make it better, but I suppose either one would fix the issue:<br />
<br />
# Use {{ic|/sys/class/rtc/rtc0/since_epoch}} as a base for the wakeup time, rather than {{ic|date}};<br />
# Reset the RTC wakealarm before hibernating (right after reading it would be ideal).<br />
<br />
<br />
I will keep investigating to see if I don't get the issue anymore (as I said, it was fairly rare and thus hard to confirm that it has definitely stopped happening), but if I don't see it in the next week, I'll submit an edit to the wiki.<br />
<br />
--[[User:Cynary|Cynary]] ([[User talk:Cynary|talk]]) 09:16, 20 February 2018 (UTC)<br />
<br />
== Userspace tools ==<br />
<br />
[[Power management#Userspace tools]] now provides a list of graphical power managers and statistics tools as well as laptop power managers for the commandline. The recommendation to use only one of the listed tools because they conflict doesn't really fit anymore, how should that be changed? <br />
-- [[User:Progandy|Progandy]] ([[User talk:Progandy|talk]]) 12:42, 20 June 2018 (UTC)<br />
<br />
:It could be changed to something like this: ''Be aware that using some of these tools in combination can result in unexpected behavior, such as double suspends. Please consult the documentation of the tool in question to see if there are any possible conflicts.''<br />
:-- [[User:Chazza|Chazza]] ([[User talk:Chazza|talk]]) 16:12, 20 June 2018 (UTC)<br />
<br />
::That sounds good. I looked a bit closer and most (all?) of the GUI tools do not have anything to do with power saving, they only monitor and sometimes react to low battery charge states. Maybe it would be better to split the list between power saving and power monitoring instead of GUI/Console? acpid and powertop do both, though.<br />
::[[User:Progandy|Progandy]] ([[User talk:Progandy|talk]]) 18:37, 22 June 2018 (UTC)</div>Progandyhttps://wiki.archlinux.org/index.php?title=Talk:Power_management&diff=527059Talk:Power management2018-06-20T11:42:03Z<p>Progandy: /* Userspace tools */ new section</p>
<hr />
<div>== Suspend/resume service files ==<br />
<br />
I have the slight suspicion that the service files posted in the section [[Power Management#Suspend/resume service files]] might not work. Has anybody tried them or is actually using them? <br><br />
-- [[User:Jakobh|jakobh]] [[User talk:Jakobh|✉]] 03:12, 10 May 2013 (UTC)<br />
<br />
: (Mod: the section was moved from [[systemd]] into [[Power Management]], so I moved this post too, fixed link along the way. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 10:24, 21 August 2013 (UTC))<br />
<br />
== Sleep hooks ==<br />
<br />
Where is the exact difference between '''Suspend/resume service files''' approach and '''Hooks in /usr/lib/systemd/system-sleep'''?<br />
<br />
Is the latter obsolete?<br />
<br />
-- [[User:Orschiro|Orschiro]] 07:33, 17 January 2014<br />
<br />
:From {{ic|systemd-sleep(8)}}:<br />
::"Note that scripts or binaries dropped in {{ic|/usr/lib/systemd/system-sleep/}} are intended for local use only and should be considered hacks."<br />
:It's always preferred to use service files, they are much more flexible in handling the dependencies etc.<br />
:-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 23:52, 31 January 2014 (UTC)<br />
<br />
== Delayed hibernation service ==<br />
<br />
I have found that the service file given in this section does not work. My laptop hibernates immediately after resuming from suspend. I have also found that the older version of this service found in the forum post does indeed work perfectly. Does anyone know why this is?<br />
[[User:Aouellette|Aouellette]] ([[User talk:Aouellette|talk]]) 16:16, 30 May 2015 (UTC)<br />
<br />
== Resume file does not work after resuming from hibernation ==<br />
<br />
The systemd unit {{ic|User resume actions}} presented on this page only worked for me after resuming from sleep, not from hibernate. <br />
After adding {{ic|hibernate.target}} to the {{ic|After}} and {{ic|WantedBy}} lines it works both ways.<br />
However this is the first time I've done anything with such service files so I ain't sure if this is the optimal way.<br />
Can anyone confirm?<br />
<br />
{{unsigned|18:30, 12 October 2015|PhilippD}}<br />
<br />
:Actually, the {{ic|suspend@.service}} in [[Power_management#Suspend.2Fresume_service_files]] binds to {{ic|sleep.target}}, but {{ic|resume@.service}} binds to {{ic|suspend.target}}. They are not synonyms, systemd triggers {{ic|suspend.target}} and {{ic|sleep.target}} when the system is suspended to RAM, and {{ic|hibernate.target}} and {{ic|sleep.target}} when it is suspended to disk. This way you can bind your service to either one or both suspend methods using just a single target. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:17, 12 October 2015 (UTC)<br />
<br />
== Bluetooth rfkill ==<br />
<br />
Systemd now provides {{ic|systemd-rkfill.service}}. If you use {{ic|rfkill block}} to disable bluetooth, {{ic|systemd-rfkill.service}} will remember this and restore this state on next boot -- [[User:robtaylor|robtaylor]] ([[User talk:robtaylor|talk]]) Wed 18 May 16:10:05 BST 2016<br />
<br />
== A "sensible value" for the laptop mode ==<br />
<br />
The vast amount of specific information carried in this part, I find it a bit surprising. It seems "A sensible value for the laptop mode 'knob' is 5 seconds." could be heard in the mouth of a politician kicking the ball into touch.<br />
<br />
From Documentation/laptops/laptop-mode.txt:<br />
<br />
> The value of the laptop_mode knob determines the time between the occurrence of disk I/O <br />
and when the flush is triggered. A sensible value for the knob is 5 seconds. Setting the knob<br />
to 0 disables laptop mode.<br />
<br />
So "5 (seconds)" is related to the virtual memory subsystem (in direct relation to ''vm.dirty_writeback_centisecs''). Then "0" turns laptop mode off, aha. It'd be cool to know *what* is laptop_mode is in the first place: Is it the whole vm configuration settings that are described in the docs? I believe not, as e.g. the conf files are not to be seen in present Arch (nor in other distros I know of).<br />
<br />
A few things changed a bit since the Documentation/laptops/laptop-mode.txt was last edited, in 2004. I've searched extensively which part of it might still be up to date, without success so far. ''TLP'' has many if not most of the settings the doc explains. And so looks as an evolution of ''laptop_mode''. Would a guru or someone with knowledge about that be kind enough to specify the effect of ''vm.laptop_mode''? [[User:Kozaki|kozaki]] ([[User talk:Kozaki|talk]]) 23:33, 1 September 2016 (UTC)<br />
<br />
:The effect of the {{ic|vm.laptop_mode}} is described in the kernel docs in "The Details" section. The scripts that the docs talk about are probably [[Laptop Mode Tools]] nowadays. They are needed only to switch settings based on the current power source (and as a "bonus" they integrate most of the things in the [[Power_management#Power_saving]] section), but I bet the kernel settings are mostly the same as in 2004. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:41, 2 September 2016 (UTC)<br />
<br />
:: I now see that, thank you Lahwaacz. Now as we may increase flush time to disk (to, say, ten minutes) via {{ic|vm.dirty_writeback_centisecs}}, delaying the flush up to five seconds via the {{ic|vm.laptop_mode}} knob doesn't make much sense regarding the ''disk'' power-savings... But it may help the ''cpu'' staying idle longer. Hence, whether set via [[laptop-mode-tools]], [[tlp]] or proper self-made [[udev]] rules. I.e. {{ic|vm.laptop_mode}} and {{ic|vm.dirty_*}} together help delaying and grouping system's activity ''as a whole'', allowing for longer power-saving efficient idle times. Please correct me if I'm wrong. [[User:Kozaki|kozaki]] ([[User talk:Kozaki|talk]]) 19:37, 4 September 2016 (UTC)<br />
<br />
::: True, but the delay via {{ic|vm.laptop_mode}} makes sense also for other reasons. Let's say {{ic|vm.dirty_writeback_centisecs}} is set to something like 10 minutes and the disk is spun down due to inactivity and stays like that for e.g. 8 minutes, when it spins up due to user activity. Flushing all the cummulated dirty pages to the disk immediately might delay the request which caused the disk to spin up, so it's better to wait couple of seconds until there is chance that small high-priority requests have been serviced. Also, it might take couple of seconds to spin up the disk. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:14, 4 September 2016 (UTC)<br />
<br />
== xss-lock ==<br />
<br />
First of all I'm wondering why we are linking {{AUR|xss-lock-git}} instead of {{AUR|xss-lock}}. Secondly I wonder why we recommend the {{ic|-n}} flag; don't we want it to fork if we are closing the lid so presumably putting the computer into suspend/hibernate?<br />
<br />
--[[User:Lindhe|Lindhe]] ([[User talk:Lindhe|talk]]) 20:09, 25 April 2017 (UTC)<br />
<br />
:xss-lock-git is used because the release version has some bugs such as 100% CPU with certain window managers (for details, see upstream). The -n option is as used in the man page; a separate option is provided if you want to use the i3lock forking mode. The computer should however suspend regardless. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 21:57, 25 April 2017 (UTC)<br />
<br />
== suspend to hibernate require fix ==<br />
<br />
Rather than overriding the <code>suspend.target</code>, I think we should just add <code>RequiredBy=suspend.target</code> in the <code>[Install]</code> section of the service. It works for me, and I think this is cleaner. Can anyone else confirm that this works?<br />
--[[User:Svvac|Svvac]] ([[User talk:Svvac|talk]]) 14:16, 28 May 2017 (UTC)<br />
<br />
== network interfaces: udev rule does not work ==<br />
<br />
At least a few other wiki pages point to this rule for how an example of how to turn off power management, because power mananagement breaks some current cards using the iwlwifi driver. Unfortunately the given udev rule does not work due to persistent device names. There is a note here about persistent device names, but it is really confusing. It stresses the importance of the number in the file name, but then states that it actually wont work anyway and to use the persistent name instead of the wildcard?? However even that won't work because the udev rule above has ACTION="add". At least in my case, that ACTION clause causes the rule to only trigger for the original device name (wlan0), and not the persistent name (wlp5s0). So if I use wlan0 everywhere, it triggers but has no effect. If I use wlp5s0 everywhere it never triggers. One solution is to remove the ACTION="add" clause and use the persistent name everywhere. Another solution is to continue using a wildcard in KERNEL, such as KERNEL="wl*", and then use the persistent name instead of %k in the RUN command. I chose the second solution and my full udev rule was this:<br />
<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", RUN+="/usr/bin/iw dev wlp5s0 set power_save off"<br />
<br />
Note that I also tried using 99 instead of 70 for the filename with the original udev rule, but that did not work. [[User:Lllars|Lllars]] ([[User talk:Lllars|talk]]) 23:10, 5 August 2017 (UTC)<br />
<br />
:What the note tries to say is that you can't "use wlan0" everywhere as you did. In any case, the command is run ''after'' the interface gets a persistent name, so you need to run {{ic|iw dev wlp5s0 set power_save off}} (or, as the note says, {{ic|iw dev $name set power_save off}} to make it generic). As for the matching, {{ic|KERNEL}} is the "old name" and {{ic|NAME}} is the "new name", which is assigned in {{ic|80-net-setup-link.rules}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:57, 6 August 2017 (UTC)<br />
<br />
::Ok. In a way it's nice to have so much detail about how udev manages the initial and persistent names. But the way this is currently written is still very confusing. Thanks to $name, it sounds like we could just change the given udev rule to:<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", RUN+="/usr/bin/iw dev $name set power_save on"<br />
::with a note about how some people will need to use "eth*" instead of "wl*", or off instead of on. Then the whole section about persistent names is unnecessary extra info, and could either be ommitted or clarified and kept as an informational side note.[[User:Lllars|Lllars]] ([[User talk:Lllars|talk]]) 02:22, 7 August 2017 (UTC)<br />
<br />
:::Note that there are people who [[Network_configuration#Revert_to_traditional_device_names|don't use the persistent names]] at all. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:17, 7 August 2017 (UTC)<br />
<br />
== RTC drift bug in suspend-to-hibernate script ==<br />
<br />
For some time now I have been trying to figure out an issue with my laptop that seems to happen when I use the suspend-to-hibernate script: the laptop would immediately wake up after hibernating.<br />
<br />
I took some more time to investigate today, and I think (unfortunately not confirmed 100% yet - the issue was fairly rare) that there is a race in the script that causes the RTC to immediately wake up the computer after it gets suspended. Specifically, the RTC is reset after the hibernate has started, so it is possible that the reset does not happen before the computer hibernates.<br />
<br />
Further, the source for the current time is the command {{ic|date}}, whereas the RTC's idea of time might be a little different. I confirmed this by outputting {{ic|/sys/class/rtc/rtc0/since_epoch}} at the same time as {{ic|date +%s}} and saw delays as large as 4 seconds, but I suppose it could also get larger.<br />
<br />
Combining the RTC drift and the fact that the RTC wakealarm reset happens after the hibernate has started, it is possible for the computer to immediately wake up from hibernation right after it hibernates if that happens quickly enough. This was especially noticeable in my case as it would then wait for me to enter my encryption password and drain my battery, overheating the CPU and the insides of my backpack.<br />
<br />
I have two proposed changes to the script to make it better, but I suppose either one would fix the issue:<br />
<br />
# Use {{ic|/sys/class/rtc/rtc0/since_epoch}} as a base for the wakeup time, rather than {{ic|date}};<br />
# Reset the RTC wakealarm before hibernating (right after reading it would be ideal).<br />
<br />
<br />
I will keep investigating to see if I don't get the issue anymore (as I said, it was fairly rare and thus hard to confirm that it has definitely stopped happening), but if I don't see it in the next week, I'll submit an edit to the wiki.<br />
<br />
--[[User:Cynary|Cynary]] ([[User talk:Cynary|talk]]) 09:16, 20 February 2018 (UTC)<br />
<br />
== Userspace tools ==<br />
<br />
[[Power management#Userspace tools]] now provides a list of graphical power managers and statistics tools as well as laptop power managers for the commandline. The recommendation to use only one of the listed tools because they conflict doesn't really fit anymore, how should that be changed?</div>Progandyhttps://wiki.archlinux.org/index.php?title=PKGBUILD&diff=524299PKGBUILD2018-06-01T12:31:04Z<p>Progandy: /* Integrity */ updpkgsums is part of pacman-contrib</p>
<hr />
<div>[[Category:Package development]]<br />
[[cs:PKGBUILD]]<br />
[[da:PKGBUILD]]<br />
[[el:PKGBUILD]]<br />
[[es:PKGBUILD]]<br />
[[fa:PKGBUILD]]<br />
[[fr:PKGBUILD]]<br />
[[it:PKGBUILD]]<br />
[[ja:PKGBUILD]]<br />
[[pl:PKGBUILD]]<br />
[[pt:PKGBUILD]]<br />
[[ru:PKGBUILD]]<br />
[[sr:PKGBUILD]]<br />
[[zh-hans:PKGBUILD]]<br />
[[zh-hant:PKGBUILD]]<br />
{{Related articles start}}<br />
{{Related|Arch packaging standards}}<br />
{{Related|Creating packages}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Arch User Repository}}<br />
{{Related|:Category:Package development}}<br />
{{Related|Arch Build System}}<br />
{{Related|makepkg}}<br />
{{Related|pacman}}<br />
{{Related|Pacman/Tips and tricks}}<br />
{{Related articles end}}<br />
<br />
This article discusses variables definable by the maintainer in a PKGBUILD. For information on the PKGBUILD functions and creating packages in general, refer to [[Creating packages]]. Also read {{man|5|PKGBUILD}}.<br />
<br />
A PKGBUILD is a shell script containing the build information required by [[Arch Linux]] packages.<br />
<br />
Packages in Arch Linux are built using the [[makepkg]] utility. When ''makepkg'' is run, it searches for a {{ic|PKGBUILD}} file in the current directory and follows the instructions therein to either compile or otherwise acquire the files to build a package archive ({{ic|''pkgname''.pkg.tar.xz}}). The resulting package contains binary files and installation instructions, readily installable with [[pacman]].<br />
<br />
Mandatory variables are {{ic|pkgname}}, {{ic|pkgver}}, {{ic|pkgrel}}, and {{ic|arch}}. {{ic|license}} is not strictly necessary to build a package, but is recommended for any PKGBUILDs shared with others, as ''makepkg'' will produce a warning if not present.<br />
<br />
It is a common practice to define the variables in the PKGBUILD in same order as given here. However, this is not mandatory, as long as correct [[Bash]] syntax is used.<br />
<br />
== Package name ==<br />
<br />
=== pkgbase ===<br />
<br />
An optional global directive is available when building a split package. {{ic|pkgbase}} is used to refer to the group of packages in the output of ''makepkg'' and in the naming of source-only tarballs. If not specified, the first element in the {{ic|pkgname}} array is used. The variable is not allowed to begin with a hyphen. All values for split packages default to the global ones given in the PKGBUILD. Everything, except [[#makedepends]], [[#Sources]], and [[#Integrity]] variables can be overridden within each split package's {{ic|package()}} function.<br />
<br />
=== pkgname ===<br />
<br />
The name(s) of the package(s). Package names should only consist of lowercase alphanumerics and the following characters: {{ic|@._+-}} (at symbol, dot, underscore, plus, hyphen). Names are not allowed to start with hyphens or dots. For the sake of consistency, {{ic|pkgname}} should match the name of the source tarball of the software: for instance, if the software is in {{ic|foobar-2.5.tar.gz}}, use {{ic|1=pkgname=foobar}}. The name of the directory containing the PKGBUILD should also match the {{ic|pkgname}}.<br />
<br />
Split packages should be defined as an array, e.g. {{ic|1=pkgname=('foo' 'bar')}}.<br />
<br />
== Version ==<br />
<br />
=== pkgver ===<br />
<br />
The version of the package. This should be the same as the version released by the author of the package. It can contain letters, numbers, periods and underscores, but '''not''' a hyphen ({{ic|-}}). If the author of the software uses one, replace it with an underscore ({{ic|_}}). If the {{ic|pkgver}} variable is used later in the PKGBUILD, then the underscore can easily be substituted for a hyphen, e.g. {{ic|1=source=("$pkgname-${pkgver//_/-}.tar.gz")}}.<br />
<br />
{{Note|If upstream uses a timestamp versioning such as {{ic|30102014}}, ensure to use the reversed date, i.e. {{ic|20141030}} ([[Wikipedia:ISO 8601|ISO 8601]] format). Otherwise it will not appear as a newer version.}}<br />
<br />
{{Tip|<br />
* The ordering of uncommon values can be tested with {{man|8|vercmp}}, which is provided by the [[pacman]] package.<br />
* [[makepkg]] can automatically [http://allanmcrae.com/2013/04/pacman-4-1-released/ update] this variable by defining a {{ic|pkgver()}} function in the PKGBUILD. See [[VCS package guidelines#The pkgver() function]] for details.<br />
}}<br />
<br />
=== pkgrel ===<br />
<br />
The release number. This is usually a positive integer number that allows to differentiate between consecutive builds of the same version of a package. As fixes and additional features are added to the PKGBUILD that influence the resulting package, the {{ic|pkgrel}} should be incremented by 1. When a new version of the software is released, this value must be reset to 1. In exceptional cases other formats can be found in use, such as ''major.minor''.<br />
<br />
=== epoch ===<br />
<br />
{{Warning|{{ic|epoch}} should only be used when absolutely required to do so.}}<br />
<br />
Used to force the package to be seen as newer than any previous version with a lower epoch. This value is required to be a positive integer; the default is 0. It is used when the version numbering scheme of a package changes (or is alphanumeric), breaking normal version comparison logic. For example:<br />
<br />
{{hc|1=<br />
pkgver=5.13<br />
pkgrel=2<br />
epoch=1<br />
|2=<br />
1:5.13-2<br />
}}<br />
<br />
See {{man|8|pacman}} for more information on version comparisons.<br />
<br />
== Generic ==<br />
<br />
=== pkgdesc ===<br />
<br />
The description of the package. This is recommended to be 80 characters or less and should not include the package name in a self-referencing way, unless the application name differs from the package name. For example, use {{ic|1=pkgdesc="Text editor for X11"}} instead of {{ic|1=pkgdesc="Nedit is a text editor for X11"}}.<br />
<br />
Also it is important to use keywords wisely to increase the chances of appearing in relevant search queries.<br />
<br />
=== arch ===<br />
<br />
An array of architectures that the PKGBUILD is intended to build and work on. Arch officially supports only {{ic|x86_64}}, but other projects may support other architectures. For example, [https://archlinux32.org/ Arch Linux 32] provides support for {{ic|i686}} and [http://archlinuxarm.org/ Arch Linux ARM] provides support for {{ic|arm}} (armv5), {{ic|armv6h}} (armv6 hardfloat), {{ic|armv7h}} (armv7 hardfloat), and {{ic|aarch64}} (armv8 64bit).<br />
<br />
If a package is architecture-independent in its compiled state (shell scripts, fonts, themes, many types of extensions, etc.) then use {{ic|1=arch=('any')}}. Please note that, as this is intended for packages that can be built once and used on any architecture, it will cause the package to be labeled {{ic|-any}} as opposed to {{ic|-x86_64}}, etc.<br />
<br />
If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. {{ic|1=arch=('x86_64')}}.<br />
<br />
The target architecture can be accessed with the variable {{ic|$CARCH}} during a build.<br />
<br />
=== url ===<br />
The URL of the official site of the software being packaged.<br />
<br />
=== license ===<br />
The license under which the software is distributed. The {{pkg|licenses}} package contains many commonly used licenses, which are installed under {{ic|/usr/share/licenses/common/}}. If a package is licensed under one of these licenses, the value should be set to the directory name, e.g. {{ic|1=license=('GPL')}}. If the appropriate license is not included, several things must be done:<br />
<br />
# Add {{ic|custom}} to the {{ic|license}} array. Optionally, you can replace {{ic|custom}} with {{ic|custom:''name of license''}}. Once a license is used in two or more packages in an official repository (including [[community]]), it becomes a part of the {{Pkg|licenses}} package.<br />
# Install the license in: {{ic|/usr/share/licenses/''pkgname''/}}, e.g. {{ic|/usr/share/licenses/foobar/LICENSE}}. One good way to do this is by using: {{bc|install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"}}<br />
# If the license is only found in a website, then you need to separately include it in the package.<br />
<br />
* The [[Wikipedia:BSD License|BSD]], [[Wikipedia:MIT License|MIT]], [[Wikipedia:ZLIB license|zlib/png]] and [[Wikipedia:Python License|Python]] licenses are special cases and could not be included in the {{pkg|licenses}} package. For the sake of the {{ic|license}} array, it is treated as a common license ({{ic|1=license=('BSD')}}, {{ic|1=license=('MIT')}}, {{ic|1=license=('ZLIB')}} and {{ic|1=license=('Python')}}), but technically each one is a custom license, because each one has its own copyright line. Any packages licensed under these four should have its own unique license stored in {{ic|/usr/share/licenses/''pkgname''}}. <br />
* Some packages may not be covered by a single license. In these cases, multiple entries may be made in the {{ic|license}} array, e.g. {{ic|1=license=('GPL' 'custom:''name of license''')}}.<br />
* (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:<br />
** (L)GPL — (L)GPLv2 or any later version<br />
** (L)GPL2 — (L)GPL2 only<br />
** (L)GPL3 — (L)GPL3 or any later version<br />
* If after researching the issue no license can be determined, [https://projects.archlinux.org/pacman.git/tree/proto/PKGBUILD.proto PKGBUILD.proto] suggests using {{ic|unknown}}. However, upstream should be contacted about the conditions under which the software is (and is not) available.<br />
<br />
{{Tip|Some software authors do not provide separate license file and describe distribution rules in section of common {{ic|ReadMe.txt}}. This information can be extracted to a separate file during {{ic|build()}} with something like {{ic|sed -n '/'''This software'''/,/''' thereof.'''/p' ReadMe.txt > LICENSE}}}}<br />
<br />
Additional information and perspectives on free and open source software licenses may be found on the following pages:<br />
<br />
*[[w:Free software licence]]<br />
*[[w:Comparison of free and open-source software licenses]]<br />
*[https://www.softwarefreedom.org/resources/2008/foss-primer.html A Legal Issues Primer for Open Source and Free Software Projects]<br />
*[https://www.gnu.org/licenses/license-list.html GNU Project - Various Licenses and Comments about Them]<br />
*[https://www.debian.org/legal/licenses/ Debian - License information]<br />
*[http://www.opensource.org/licenses/alphabetical Open Source Initiative - Licenses by Name]<br />
<br />
=== groups ===<br />
<br />
The [[Creating packages#Meta packages and groups|group]] the package belongs in. For instance, when installing the {{Grp|kdebase}} package, it installs all packages belonging in that group.<br />
<br />
== Dependencies ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=optdepends_x86_64=()}}.<br />
}}<br />
<br />
=== depends ===<br />
An array of packages that must be installed before the software can be run. Version restrictions can be specified with comparison operators, e.g. {{ic|1=depends=('foobar>=1.8.0')}}; if multiple restrictions are needed, the dependency can be repeated for each, e.g. {{ic|1=depends=('foobar>=1.8.0' 'foobar<2.0.0')}}. <br />
<br />
Dependencies that are provided by other dependencies do not need to be listed. For instance, if a package ''foo'' depends on both ''bar'' and ''baz'', and the ''bar'' package depends in turn on ''baz'' too, ''baz'' does not need to be included in ''foo'''s {{ic|depends}} array.<br />
<br />
If the dependency name appears to be a library, e.g. {{ic|1=depends=('libfoobar.so')}}, makepkg will try to find a binary that depends on the library in the built package and append the version needed by the binary. Appending the version yourself disables automatic detection, e.g. {{ic|1=depends=('libfoobar.so=2')}}.<br />
<br />
=== optdepends ===<br />
<br />
An array of packages that are not needed for the software to function, but provide additional features. This may imply that not all executables provided by a package will function without the respective optdepends.[https://lists.archlinux.org/pipermail/arch-general/2014-December/038124.html] If the software works on multiple alternative dependencies, all of them can be listed here, instead of the {{ic|depends}} array.<br />
<br />
A short description of the extra functionality each optdepend provides should also be noted:<br />
<br />
optdepends=('cups: printing support'<br />
'sane: scanners support'<br />
'libgphoto2: digital cameras support'<br />
'alsa-lib: sound support'<br />
'giflib: GIF images support'<br />
'libjpeg: JPEG images support'<br />
'libpng: PNG images support')<br />
<br />
=== makedepends ===<br />
An array of packages that are '''only''' required to build the software. The minimum dependency version can be specified in the same format as in the {{ic|depends}} array. The packages in the {{ic|depends}} array are implicitly required to build the package, they should not be duplicated here.<br />
<br />
{{Tip|The following can be used to check whether a particular package is either in the {{Grp|base-devel}} group or is pulled in by a member of the group:<br />
<br />
<nowiki>$ LC_ALL=C pacman -Si $(pactree -rl ''package'') 2>/dev/null | grep -q "^Groups *:.*base-devel"</nowiki><br />
<br />
}}<br />
<br />
{{Note|The group {{Grp|base-devel}} is assumed to be already installed when building with ''makepkg''. Members of this group '''should not''' be included in {{ic|makedepends}} array.}}<br />
<br />
=== checkdepends ===<br />
An array of packages that the software depends on to run its test suite, but are not needed at runtime. Packages in this list follow the same format as {{ic|depends}}. These dependencies are only considered when the [[Creating packages#check()|check()]] function is present and is to be run by makepkg. <br />
<br />
{{Note|The group {{Grp|base-devel}} is assumed to be already installed when building with ''makepkg''. Members of this group '''should not''' be included in {{ic|checkdepends}} array.}}<br />
<br />
== Package relations ==<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=conflicts_x86_64=()}}.}}<br />
<br />
=== provides ===<br />
An array of additional packages that the software provides the features of (or a virtual package such as {{Ic|cron}} or {{Ic|sh}}). Packages providing the same item can be installed side-by-side, unless at least one of them uses a {{ic|conflicts}} array.<br />
{{Note|The version that the package provides should be mentioned ({{ic|pkgver}} and potentially the {{ic|pkgrel}}), in case packages referencing the software require one. For instance, a modified ''qt'' package version 3.3.8, named ''qt-foobar'', should use {{ic|1=provides=('qt=3.3.8')}}; omitting the version number would cause the dependencies that require a specific version of ''qt'' to fail. Do not add {{ic|pkgname}} to the {{ic|provides}} array, as it is done automatically.}}<br />
<br />
=== conflicts ===<br />
<br />
An array of packages that conflict with, or cause problems with the package, if installed. All these packages and packages providing this item will need to be removed. The version properties of the conflicting packages can also be specified in the same format as the {{ic|depends}} array.<br />
<br />
This means when you write a package for which an alternate version is available (be it in the official repositories or in the [[AUR]]) and your package conflicts that version, you need to put the other versions in your {{ic|conflicts}} array as well.<br />
<br />
However, there is an exception to this rule. Defining conflicting packages in all directions is not always applicable especially if all these packages are maintained by different people. Indeed, having to contact all package maintainers of packages conflicting with your own version and ask them to include your package name in their {{ic|conflicts}} array is a cumbersome process.<br />
<br />
This is why, in this context, if your package {{ic|provides}} a feature and another package {{ic|provides}} the same feature, you do not need to specify that conflicting package in your {{ic|conflicts}} array. Let us take a concrete example:<br />
<br />
* {{pkg|netbeans}} provides {{ic|netbeans}}<br />
* {{aur|netbeans-javase}} provides {{ic|netbeans}} and conflicts with {{ic|netbeans}}<br />
* {{aur|netbeans-php}} provides {{ic|netbeans}} and conflicts with {{ic|netbeans}} but does not need to conflicts with {{aur|netbeans-javase}} since pacman is smart enough to figure out these packages are incompatible as they provide the same feature and are in conflict with it.<br />
:The same applies in the reverse order: {{aur|netbeans-javase}} does not need to conflict with {{aur|netbeans-php}}, because they provide the same feature.<br />
<br />
=== replaces ===<br />
An array of obsolete packages that are replaced by the package, e.g. {{pkg|wireshark-gtk}} uses {{ic|1=replaces=('wireshark')}}. When syncing, ''pacman'' will immediately replace an installed package upon encountering another package with the matching {{ic|replaces}} in the repositories. If providing an alternate version of an already existing package or uploading to the AUR, use the {{ic|conflicts}} and {{ic|provides}} arrays, which are only evaluated when actually installing the conflicting package.<br />
<br />
== Others ==<br />
<br />
=== backup ===<br />
<br />
An array of files that can contain user-made changes and should be preserved during upgrade or removal of a package, primarily intended for configuration files in {{ic|/etc}}.<br />
<br />
Files in this array should use '''relative''' paths without the leading slash ({{ic|/}}) (e.g. {{ic|etc/pacman.conf}}, instead of {{ic|/etc/pacman.conf}}).<br />
<br />
When updating, new versions may be saved as {{ic|file.pacnew}} to avoid overwriting a file which already exists and was previously modified by the user. Similarly, when the package is removed, user-modified files will be preserved as {{ic|file.pacsave}} unless the package was removed with the {{ic|pacman -Rn}} command.<br />
<br />
See also [[Pacnew and Pacsave files]].<br />
<br />
=== options ===<br />
This array allows overriding some of the default behavior of ''makepkg'', defined in {{Ic|/etc/makepkg.conf}}. To set an option, include the name in the array. To disable an option, place an '''{{ic|!}}''' before it.<br />
<br />
The full list of the available options can be found in {{man|5|PKGBUILD}}.<br />
<br />
=== install ===<br />
The name of the ''.install'' script to be included in the package. This should be the same as {{ic|pkgname}}. ''pacman'' has the ability to store and execute a package-specific script when it installs, removes or upgrades a package. The script contains the following functions which run at different times:<br />
<br />
* {{ic|pre_install}} — The script is run right before files are extracted. One argument is passed: new package version.<br />
* {{ic|post_install}} — The script is run right after files are extracted. One argument is passed: new package version.<br />
* {{ic|pre_upgrade}} — The script is run right before files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
* {{ic|post_upgrade}} — The script is run right after files are extracted. Two arguments are passed in the following order: new package version, old package version.<br />
* {{ic|pre_remove}} — The script is run right before files are removed. One argument is passed: old package version.<br />
* {{ic|post_remove}} — The script is run right after files are removed. One argument is passed: old package version.<br />
<br />
Each function is run [[chroot]]ed inside the ''pacman'' install directory. See [https://bbs.archlinux.org/viewtopic.php?pid=913891 this thread].<br />
<br />
{{Tip|<br />
* A prototype ''.install'' is provided at [https://projects.archlinux.org/pacman.git/plain/proto/proto.install /usr/share/pacman/proto.install].<br />
* [[pacman#Hooks]] provide similar functionality.<br />
}}<br />
<br />
{{Note|Do not end the script with {{ic|exit}}. This would prevent the contained functions from executing.}}<br />
<br />
=== changelog ===<br />
<br />
The name of the package changelog. To view changelogs for installed packages (that have this file):<br />
<br />
$ pacman -Qc ''pkgname''<br />
<br />
== Sources ==<br />
<br />
=== source ===<br />
<br />
An array of files needed to build the package. It must contain the location of the software source, which in most cases is a full HTTP or FTP URL. The previously set variables {{ic|pkgname}} and {{ic|pkgver}} can be used effectively here; e.g. {{ic|<nowiki>source=("https://example.com/$pkgname-$pkgver.tar.gz")</nowiki>}}.<br />
<br />
Files can also be supplied in the same directory where the {{ic|PKGBUILD}} is located, and their names added to this array. Before the actual build process starts, all the files referenced in this array will be downloaded or checked for existence, and ''makepkg'' will not proceed if any is missing.<br />
<br />
''.install'' files are recognized automatically by ''makepkg'' and should not be included in the source array. Files in the source array with extensions ''.sig'', ''.sign'', or ''.asc'' are recognized by ''makepkg'' as PGP signatures and will be automatically used to verify the integrity of the corresponding source file.<br />
<br />
{{Warning|The downloaded source filename must be unique because the [[makepkg#Package_output|SRCDEST]] directory can be the same for all packages. For instance, using the version number of the project as a filename potentially conflicts with other projects with the same version number. In this case, the alternative unique filename to be used is provided with the syntax {{ic|1=source=(<nowiki>'</nowiki>''unique_package_name'''''::'''''file_uri''<nowiki>'</nowiki>)}}; e.g. {{ic|<nowiki>source=("$pkgname-$pkgver.tar.gz::https://github.com/coder/program/archive/v$pkgver.tar.gz")</nowiki>}}.<br />
}}<br />
<br />
{{Tip|<br />
* Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=source_x86_64=()}}. There must be a corresponding integrity array with checksums, e.g. {{ic|1=sha256sums_x86_64=()}}.<br />
* Some servers restrict download by filtering the ''User-Agent'' string of the client, this can be circumvented with [[Nonfree applications package guidelines#Custom DLAGENTS|DLAGENTS]].}}<br />
<br />
=== noextract ===<br />
<br />
An array of files listed under {{ic|source}}, which should not be extracted from their archive format by ''makepkg''. This can be used with archives that cannot be handled by {{ic|/usr/bin/bsdtar}} or those that need to be installed as-is. If an alternative unarchiving tool is used (e.g. {{Pkg|lrzip}}), it should be added in the {{ic|makedepends}} array and the first line of the [[Creating packages#prepare()|prepare()]] function should extract the source archive manually; for example:<br />
<br />
prepare() {<br />
lrzip -d ''source''.tar.lrz<br />
}<br />
<br />
Note that while the {{ic|source}} array accepts URLs, {{ic|noextract}} is '''just''' the file name portion:<br />
<br />
<nowiki>source=("http://foo.org/bar/foobar.tar.xz")</nowiki><br />
noextract=('foobar.tar.xz')<br />
<br />
To extract ''nothing'', you can do something like this:<br />
<br />
* If {{ic|source}} contains only plain URLs without custom file names, strip the source array before the last slash:<br />
: {{bc|1=noextract=("${source[@]##*/}")}}<br />
* If {{ic|source}} contains only entries with custom file names, strip the source array after the {{ic|::}} separator (taken from [https://projects.archlinux.org/svntogit/packages.git/tree/trunk/PKGBUILD?h=packages/firefox-i18n#n123 firefox-i18n's PKGBUILD]):<br />
: {{bc|1=noextract=("${source[@]%%::*}")}}<br />
<br />
=== validpgpkeys ===<br />
An array of PGP fingerprints. If used, ''makepkg'' will only accept signatures from the keys listed here and will ignore the trust values from the keyring. If the source file was signed with a subkey, ''makepkg'' will still use the primary key for comparison.<br />
<br />
Only full fingerprints are accepted. They must be uppercase and must not contain whitespace characters.<br />
<br />
{{note|You can use {{ic|gpg --list-keys --fingerprint <KEYID>}} to find out the fingerprint of the appropriate key.}}<br />
<br />
Please read [[makepkg#Signature checking]] for more information.<br />
<br />
== Integrity ==<br />
<br />
These variables are arrays whose items are checksum strings that will be used to verify the integrity of the respective files in the [[#source|source]] array. You can also insert {{ic|SKIP}} for a particular file, and its checksum will not be tested.<br />
<br />
The checksum type and values should always be those provided by upstream, such as in release announcements. When multiple types are available, the strongest checksum is to be preferred: {{ic|sha256}} over {{ic|sha1}}, and {{ic|sha1}} over {{ic|md5}}. This best ensures the integrity of the downloaded files, from upstream's announcement to package building.<br />
<br />
{{Note|Additionally, when upstream makes [[w:Digital signature|digital signatures]] available, the signature files should be added to the [[#source|source]] array and the PGP key fingerprint to the [[#validpgpkeys|validpgpkeys]] array. This allows authentication of the files at build time.}}<br />
<br />
The values for these variables can be auto-generated by [[makepkg]]'s {{ic|-g}}/{{ic|--geninteg}} option, then commonly appended with {{ic|makepkg -g >> PKGBUILD}}. The {{ic|updpkgsums}} command from {{Pkg|pacman-contrib}} is able to update the variables wherever they are in the PKGBUILD. Both tools will use the variable that is already set in the PKGBUILD, or fall back to {{ic|md5sums}} if none is set.<br />
<br />
The file integrity checks to use can be set up with the {{ic|INTEGRITY_CHECK}} option in {{ic|/etc/makepkg.conf}}. See {{man|5|makepkg.conf}}.<br />
<br />
{{Note|Additional architecture-specific arrays can be added by appending an underscore and the architecture name, e.g. {{ic|1=sha256sums_x86_64=()}}.}}<br />
<br />
=== md5sums ===<br />
<br />
An array of 128-bit [[Wikipedia:MD5|MD5]] checksums of the files listed in the {{ic|source}} array.<br />
<br />
=== sha1sums ===<br />
<br />
An array of 160-bit [[Wikipedia:SHA-1|SHA-1]] checksums of the files listed in the {{ic|source}} array.<br />
<br />
=== sha256sums ===<br />
<br />
An array of [[Wikipedia:SHA-2|SHA-2]] checksums with digest size of 256 bits.<br />
<br />
=== sha224sums, sha384sums, sha512sums ===<br />
<br />
An array of SHA-2 checksums with digest sizes 224, 384, and 512 bits, respectively. These are less common alternatives to {{ic|sha256sums}}.<br />
<br />
== See also ==<br />
*{{man|5|PKGBUILD}} manual page<br />
*[https://projects.archlinux.org/pacman.git/plain/proto/PKGBUILD.proto Example PKGBUILD file]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Makepkg&diff=524298Makepkg2018-06-01T12:28:57Z<p>Progandy: /* Generate new checksums */ updpkgsums is part of pacman.contrib</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package development]]<br />
[[Category:About Arch]]<br />
[[ar:Makepkg]]<br />
[[el:Makepkg]]<br />
[[es:Makepkg]]<br />
[[fa:Makepkg]]<br />
[[fr:makepkg]]<br />
[[it:Makepkg]]<br />
[[ja:Makepkg]]<br />
[[nl:Makepkg]]<br />
[[pt:Makepkg]]<br />
[[ru:Makepkg]]<br />
[[sr:Makepkg]]<br />
[[zh-hans:Makepkg]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Arch User Repository}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
[https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg] is a script to automate the building of packages. The requirements for using the script are a build-capable Unix platform and a [[PKGBUILD]].<br />
<br />
''makepkg'' is provided by the {{Pkg|pacman}} package.<br />
<br />
== Configuration ==<br />
<br />
See {{man|5|makepkg.conf}} for details on configuration options for ''makepkg''.<br />
<br />
The system configuration is available in {{ic|/etc/makepkg.conf}}, but user-specific changes can be made in {{ic|$XDG_CONFIG_HOME/pacman/makepkg.conf}} or {{ic|~/.makepkg.conf}}. It is recommended to review the configuration prior to building packages.<br />
<br />
=== Packager information ===<br />
<br />
Each package is tagged with metadata identifying amongst others also the ''packager''. By default, user-compiled packages are marked with {{ic|Unknown Packager}}. If multiple users will be compiling packages on a system, or you are otherwise distributing your packages to other users, it is convenient to provide real contact. This can be done by setting the {{ic|PACKAGER}} variable in {{ic|makepkg.conf}}.<br />
<br />
To check this on an installed package:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
...<br />
Packager : John Doe <john@doe.com><br />
...<br />
</nowiki>}}<br />
<br />
To automatically produce signed packages, also set the {{ic|GPGKEY}} variable in {{ic|makepkg.conf}}.<br />
<br />
=== Package output ===<br />
<br />
By default, ''makepkg'' creates the package tarballs in the working directory and downloads source data directly to the {{ic|src/}} directory. Custom paths can be configured, for example to keep all built packages in {{ic|~/build/packages/}} and all sources in {{ic|~/build/sources/}}.<br />
<br />
Configure the following {{ic|makepkg.conf}} variables if needed:<br />
<br />
* {{ic|PKGDEST}} &mdash; directory for storing resulting packages<br />
* {{ic|SRCDEST}} &mdash; directory for storing [[PKGBUILD#source|source]] data (symbolic links will be placed to {{ic|src/}} if it points elsewhere)<br />
* {{ic|SRCPKGDEST}} &mdash; directory for storing resulting source packages (built with {{ic|makepkg -S}})<br />
<br />
{{Tip|The {{ic|PKGDEST}} directory can be cleaned up with e.g. {{ic|paccache -c ~/build/packages/}} as described in [[pacman#Cleaning the package cache]].}}<br />
<br />
=== Signature checking ===<br />
<br />
{{Note|The signature checking implemented in ''makepkg'' does not use pacman's keyring, instead relying on the user's keyring.[http://allanmcrae.com/2015/01/two-pgp-keyrings-for-package-management-in-arch-linux/]}}<br />
<br />
If a signature file in the form of ''.sig'' or ''.asc'' is part of the [[PKGBUILD]] source array, ''makepkg'' automatically attempts to [[GnuPG#Verify a signature|verify]] it. In case the user's keyring does not contain the needed public key for signature verification, ''makepkg'' will abort the installation with a message that the PGP key could not be verified. <br />
<br />
If a needed public key for a package is missing, the [[PKGBUILD]] will most likely contain a [[PKGBUILD#validpgpkeys|validpgpkeys]] entry with the required key IDs. You can [[GnuPG#Import_a_public_key|import]] it manually, or you can find it [[GnuPG#Use_a_keyserver|on a keyserver]] and import it from there.<br />
<br />
== Usage ==<br />
Before continuing, [[install]] the {{Grp|base-devel}} group. Packages belonging to this group are '''not''' required to be listed as build-time dependencies (''makedepends'') in [[PKGBUILD]] files. In addition, the {{Grp|base}} group is assumed to be installed on '''all''' Arch systems.<br />
<br />
{{Note|<br />
* Make sure [[sudo]] is configured properly for commands passed to [[pacman]].<br />
* Running ''makepkg'' itself as root is [https://lists.archlinux.org/pipermail/pacman-dev/2014-March/018911.html disallowed].[https://projects.archlinux.org/pacman.git/tree/NEWS] Besides how a {{ic|PKGBUILD}} may contain arbitrary commands, building as root is generally considered unsafe.[https://bbs.archlinux.org/viewtopic.php?id&#61;67561] Users who have no access to a regular user account should run makepkg as the [http://allanmcrae.com/2015/01/replacing-makepkg-asroot/ nobody user].<br />
}}<br />
<br />
To build a package, one must first create a [[PKGBUILD]], or build script, as described in [[Creating packages]]. Existing scripts are available from the [[Arch Build System]] ''(ABS)'' tree or the [[AUR]]. Once in possession of a {{ic|PKGBUILD}}, change to the directory where it is saved and run the following command to build the package:<br />
<br />
$ makepkg<br />
<br />
If required dependencies are missing, ''makepkg'' will issue a warning before failing. To build the package and install needed dependencies, add the flag {{ic|-s}}/{{ic|--syncdeps}}:<br />
<br />
$ makepkg --syncdeps<br />
<br />
Adding the {{ic|-r}}/{{ic|--rmdeps}} flag causes ''makepkg'' to remove the make dependencies later, which are no longer needed. If constantly building packages, consider using [[Pacman/Tips and tricks#Removing unused packages (orphans)]] once in a while instead.<br />
<br />
{{Note|<br />
* These dependencies must be available in the configured repositories; see [[pacman#Repositories and mirrors]] for details. Alternatively, one can manually install dependencies prior to building ({{ic|pacman -S --asdeps ''dep1'' ''dep2''}}).<br />
* Only global values are used when installing dependencies, i.e any override done in a split package's packaging function will not be used. [https://patchwork.archlinux.org/patch/2271/]}}<br />
<br />
Once all dependencies are satisfied and the package builds successfully, a package file ({{ic|''pkgname''-''pkgver''.pkg.tar.xz}}) will be created in the working directory. To install, use {{ic|-i}}/{{ic|--install}} (same as {{ic|pacman -U ''pkgname''-''pkgver''.pkg.tar.xz}}):<br />
<br />
$ makepkg --install<br />
<br />
To clean up leftover files and folders, such as files extracted to the {{ic|$srcdir}}, add the option {{ic|-c}}/{{ic|--clean}}. This is useful for multiple builds of the same package or updating the package version, while using the same build folder. It prevents obsolete and remnant files from carrying over to the new builds:<br />
<br />
$ makepkg --clean<br />
<br />
For more, see [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Building optimized binaries ===<br />
<br />
A performance improvement of the packaged software can be achieved by enabling compiler optimizations for the host machine. The downside is that binaries compiled for a specific processor architecture will not run correctly on other machines. On x86_64 machines, there are rarely significant enough real world performance gains that would warrant investing the time to rebuild official packages.<br />
<br />
However, it is very easy to reduce performance by using "nonstandard" compiler flags. Many compiler optimizations are only useful in certain situations and should not be indiscriminately applied to every package. Unless you can verify/benchmark that something is faster, there is a very good chance it is not! The Gentoo [http://www.gentoo.org/doc/en/gcc-optimization.xml Compilation Optimization Guide] and [http://wiki.gentoo.org/wiki/Safe_CFLAGS Safe CFLAGS] wiki article provide more in-depth information about compiler optimization.<br />
<br />
The options passed to a C/C++ compiler (e.g. {{Pkg|gcc}} or {{Pkg|clang}}) are controlled by the {{ic|CFLAGS}}, {{ic|CXXFLAGS}}, and {{ic|CPPFLAGS}} environment variables. For use in the Arch build system, ''makepkg'' exposes these environment variables as configuration options in {{ic|makepkg.conf}}. The default values are configured to produce generic binaries that can be installed on a wide range of machines.<br />
<br />
{{Note|<br />
* Keep in mind that not all build systems use the variables configured in {{ic|makepkg.conf}}. For example, ''cmake'' disregards the preprocessor options environment variable, {{ic|CPPFLAGS}}. Consequently, many [[PKGBUILD]]s contain workarounds with options specific to the build system used by the packaged software.<br />
* The configuration provided with the source code in the {{ic|Makefile}} or a specific argument in the compilation command line takes precedence and can potentially override the one in {{ic|makepkg.conf}}.<br />
}}<br />
<br />
GCC can automatically detect and enable safe architecture-specific optimizations. To use this feature, first remove any {{ic|-march}} and {{ic|-mtune}} flags, then add {{ic|1=-march=native}}. For example:<br />
{{hc|/etc/makepkg.conf|2=<br />
CFLAGS="'''-march=native''' -O2 -pipe -fstack-protector-strong -fno-plt"<br />
CXXFLAGS="${CFLAGS}"}}<br />
To see what flags this enables on your machine, run:<br />
<br />
$ gcc -march=native -v -Q --help=target<br />
<br />
{{Note|1=If you specify different value than {{ic|1=-march=native}}, then {{ic|1=-Q --help=target}} '''will not''' work as expected.[https://bbs.archlinux.org/viewtopic.php?pid=1616694#p1616694] You need to go through a compilation phase to find out which options are really enabled. See [https://wiki.gentoo.org/wiki/Safe_CFLAGS#Find_CPU-specific_options Find CPU-specific options] on Gentoo wiki for instructions.<br />
}}<br />
<br />
=== Improving compile times ===<br />
==== Parallel compilation ====<br />
<br />
The {{Pkg|make}} build system uses the {{ic|MAKEFLAGS}} [[environment variable]] to specify additional options for ''make''. The variable can also be set in the {{ic|makepkg.conf}} file.<br />
<br />
Users with multi-core/multi-processor systems can specify the number of jobs to run simultaneously. This can be accomplished with the use of ''nproc'' to determine the number of available processors, e.g. {{ic|1=MAKEFLAGS="-j$(nproc)"}}. Some [[PKGBUILD]]s specifically override this with {{ic|-j1}}, because of race conditions in certain versions or simply because it is not supported in the first place. Packages that fail to build because of this should be [[Reporting bug guidelines|reported]] on the bug tracker (or in the case of [[AUR]] packages, to the package maintainer) after making sure that the error is indeed being caused by your {{ic|MAKEFLAGS}}.<br />
<br />
See {{man|1|make}} for a complete list of available options.<br />
<br />
==== Building from files in memory ====<br />
<br />
As compiling requires many I/O operations and handling of small files, moving the working directory to a [[tmpfs]] may bring improvements in build times. <br />
<br />
The {{ic|BUILDDIR}} variable can be temporarily exported to ''makepkg'' to set the build directory to an existing tmpfs. For example:<br />
<br />
$ BUILDDIR=/tmp/makepkg makepkg<br />
<br />
Persistent configuration can be done in {{ic|makepkg.conf}} by uncommenting the {{ic|BUILDDIR}} option, which is found at the end of the {{ic|BUILD ENVIRONMENT}} section in the default {{ic|/etc/makepkg.conf}} file. Setting its value to e.g. {{ic|1=BUILDDIR=/tmp/makepkg}} will make use of the Arch's default {{ic|/tmp}} temporary file system.<br />
<br />
{{Note|<br />
* Avoid compiling larger packages in tmpfs to prevent running out of memory.<br />
* The tmpfs folder must be mounted without the {{ic|noexec}} option, otherwise it will prevent built binaries from being executed.<br />
* Keep in mind that packages compiled in tmpfs will not persist across reboot. Consider setting the [[#Package output|PKGDEST]] option appropriately to move the built package automatically to a persistent directory.<br />
}}<br />
<br />
==== Using a compilation cache ====<br />
<br />
The use of [[ccache]] can improve build times by caching the results of compilations for successive use.<br />
<br />
=== Generate new checksums ===<br />
Install {{Pkg|pacman-contrib}} and run the following command in the same directory as the PKGBUILD file to generate new checksums:<br />
$ updpkgsums<br />
<br />
The checksums can also be obtained with e.g {{ic|sha256sum}} and added to the {{ic|sha256sums}} array by hand.<br />
<br />
=== Use other compression algorithms ===<br />
<br />
To speed up both packaging and installation, with the tradeoff of having larger package archives, you can change {{ic|PKGEXT}}. For example, the following makes the package archive uncompressed for only one invocation:<br />
<br />
$ PKGEXT='.pkg.tar' makepkg<br />
<br />
As another example, the following uses the lzop algorithm, with the {{pkg|lzop}} package required:<br />
<br />
$ PKGEXT='.pkg.tar.lzo' makepkg<br />
<br />
To make one of these settings permanent, set {{ic|PKGEXT}} in {{ic|/etc/makepkg.conf}}.<br />
<br />
=== Utilizing multiple cores on compression ===<br />
{{pkg|xz}} supports [[Wikipedia:Symmetric multiprocessing|symmetric multiprocessing (SMP)]] via the {{ic|--threads}} flag to speed up compression. For example, to let makepkg use as many CPU cores as possible to compress packages, edit {{ic|COMPRESSXZ}} array in {{ic|/etc/makepkg.conf}}:<br />
<br />
COMPRESSXZ=(xz -c -z - '''--threads=0''')<br />
<br />
{{pkg|pigz}} is a drop-in, parallel implementation for {{pkg|gzip}} which by default uses all available CPU cores (the {{ic|-p/--processes}} flag can be used to employ less cores):<br />
<br />
COMPRESSGZ=('''pigz''' -c -f -n)<br />
<br />
=== Show packages with specific packager ===<br />
<br />
This shows all packages installed on the system with the packager named ''packagername'':<br />
<br />
$ expac "%n %p" | grep "''packagername''" | column -t<br />
<br />
This shows all packages installed on the system with the packager set in the {{ic|/etc/makepkg}} variable {{ic|PACKAGER}}. This shows only packages that are in a repository defined in {{ic|/etc/pacman.conf}}.<br />
<br />
$ . /etc/makepkg.conf; grep -xvFf <(pacman -Qqm) <(expac "%n\t%p" | grep "$PACKAGER$" | cut -f1)<br />
<br />
=== Build 32-bit packages on a 64-bit system ===<br />
{{merge|Building 32-bit packages on a 64-bit system}}<br />
{{out of date|The [[Install bundled 32-bit system in 64-bit system]] article has been archived}}<br />
{{Warning|Errors have been reported when using this method to build the {{Pkg|linux}} package. The [[Install bundled 32-bit system in 64-bit system|chroot method]] is preferred and has been verified to work for building the kernel packages.}}<br />
<br />
First, enable the [[multilib]] repository and [[install]] {{Grp|multilib-devel}}.<br />
<br />
Then create a 32-bit configuration file<br />
<br />
{{hc|~/.makepkg.i686.conf|<nowiki><br />
CARCH="i686"<br />
CHOST="i686-unknown-linux-gnu"<br />
CFLAGS="-m32 -march=i686 -mtune=generic -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
LDFLAGS="-m32 -Wl,-O1,--sort-common,--as-needed,-z,relro"</nowiki>}}<br />
<br />
and invoke makepkg as such<br />
$ linux32 makepkg --config ~/.makepkg.i686.conf<br />
<br />
== Troubleshooting ==<br />
<br />
=== Makepkg sometimes fails to sign a package without asking for signature passphrase ===<br />
<br />
With [https://www.gnupg.org/faq/whats-new-in-2.1.html gnupg 2.1], gpg-agent is now started 'on-the-fly' by gpg. The problem arises in the package stage of {{ic|makepkg --sign}}. To allow for the correct privileges, {{pkg|fakeroot}} runs the {{ic|package()}} function thereby starting gpg-agent within the same fakeroot environment. On exit, the fakeroot cleanups semaphores causing the 'write' end of the pipe to close for that instance of gpg-agent which will result in a broken pipe error. If the same gpg-agent is running when {{ic|makepkg --sign}} is next executed, then gpg-agent returns exit code 2; so the following output occurs:<br />
<br />
==> Signing package...<br />
==> WARNING: Failed to sign package file.<br />
<br />
This bug is currently being tracked: {{Bug|49946}}. A temporary workaround for this issue is to run {{ic|killall gpg-agent && makepkg --sign}} instead. This issue is resolved within {{aur|pacman-git}}, specifically at commit hash {{ic|c6b04c04653ba9933fe978829148312e412a9ea7}}<br />
<br />
=== CFLAGS/CXXFLAGS/LDFLAGS in makepkg.conf do not work for CMake based packages ===<br />
<br />
In order to let CMake use the variables defined in the ''makepkg'' configuration file, pass the variables to ''cmake'' in the {{ic|build()}} function. For example:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
build() {<br />
...<br />
cmake \<br />
-DCMAKE_C_FLAGS:STRING="${CFLAGS}" \<br />
-DCMAKE_CXX_FLAGS:STRING="${CXXFLAGS}" \<br />
-DCMAKE_EXE_LINKER_FLAGS:STRING="${LDFLAGS}" \<br />
-DCMAKE_SHARED_LINKER_FLAGS:STRING="${LDFLAGS}" \<br />
...<br />
}<br />
<br />
</nowiki>}}<br />
<br />
=== CFLAGS/CXXFLAGS in makepkg.conf do not work for QMAKE based packages ===<br />
Qmake automatically sets the variable {{ic|CFLAGS}} and {{ic|CXXFLAGS}} according to what it thinks should be the right configuration. In order to let qmake use the variables defined in the makepkg configuration file, you must edit the PKGBUILD and pass the variables [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cflags QMAKE_CFLAGS] and [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cxxflags QMAKE_CXXFLAGS] to qmake. For example:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
build() {<br />
cd "$srcdir/$_pkgname-$pkgver-src"<br />
qmake-qt4 "$srcdir/$_pkgname-$pkgver-src/$_pkgname.pro" \<br />
PREFIX=/usr \<br />
QMAKE_CFLAGS="${CFLAGS}"\<br />
QMAKE_CXXFLAGS="${CXXFLAGS}"<br />
<br />
make<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, for a system wide configuration, you can create your own {{ic|qmake.conf}} and set the [http://doc.qt.io/qt-5/qmake-environment-reference.html#qmakespec QMAKESPEC] environment variable.<br />
<br />
=== Specifying install directory for QMAKE based packages ===<br />
The makefile generated by qmake uses the environment variable INSTALL_ROOT to specify where the program should be installed. Thus this package function should work:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
package() {<br />
cd "$srcdir/${pkgname%-git}"<br />
make INSTALL_ROOT="$pkgdir" install<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Note, that qmake also has to be configured appropriately. For example put this in your .pro file:<br />
<br />
{{hc|YourProject.pro|<nowiki><br />
...<br />
<br />
target.path = /usr/local/bin<br />
INSTALLS += target<br />
<br />
...<br />
</nowiki>}}<br />
<br />
=== WARNING: Package contains reference to $srcdir ===<br />
<br />
Somehow, the literal strings {{ic|$srcdir}} or {{ic|$pkgdir}} ended up in one of the installed files in your package.<br />
<br />
To identify which files, run the following from the ''makepkg'' build directory:<br />
$ grep -R "$(pwd)/src" pkg/<br />
<br />
[http://www.mail-archive.com/arch-general@archlinux.org/msg15561.html Link] to discussion thread.<br />
<br />
== See also ==<br />
<br />
* [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8) Manual Page]<br />
* [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5) Manual Page]<br />
* [https://gist.github.com/Earnestly/bebad057f40a662b5cc3 A Brief Tour of the Makepkg Process]<br />
* [https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg source code]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Patching_packages&diff=524297Patching packages2018-06-01T12:19:41Z<p>Progandy: /* Applying patches */ updpkgsums is now in pacman-contrib</p>
<hr />
<div>[[Category:Package management]]<br />
[[ja:パッケージにパッチを適用]]<br />
{{Related articles start}}<br />
{{Related|ABS}}<br />
{{Related articles end}}<br />
<br />
This article covers how to create and how to apply patches to packages in the [[Arch Build System]] (ABS).<br />
<br />
== Creating patches ==<br />
<br />
A patch describes a set of line changes for one or multiple files. Patches are typically used to automate the changing of source code.<br />
<br />
{{Note|If you only need to change one or two lines, you might want to use {{ic|sed}} instead.}}<br />
<br />
The {{ic|diff}} tool compares files line by line if you save its output you have got a patch, e.g. {{ic|diff -ura foo bar > patch}}. If you pass directories {{ic|diff}} will compare the files they contain.<br />
<br />
# Delete the {{ic|src}} directory if you have already built the package.<br />
# Run {{ic|makepkg -o}} which will download and extract the source files, specified in {{ic|PKGBUILD}}, but not build them.<br />
# Create two copies of the extracted directory in the {{ic|src}} directory, one as a pristine copy and one for your altered version. We will call them {{ic|package.orig}} and {{ic|package.new}}.<br />
# Make your changes in the {{ic|package.new}} directory.<br />
# Run {{ic|diff -ura package.orig package.new --color}} and check if the patch looks good.<br />
# Run {{ic|diff -ura package.orig package.new > package.patch}} to create the patch.<br />
# Change into the {{ic|package.orig}} directory and apply the patch using {{ic|patch -p1 < ../package.patch}}. Verify that the patch is working by building and installing the modified package with {{ic|makepkg -ei}}.<br />
<br />
{{Note|You can also create patches with [[Git]] using {{ic|git diff}} or {{ic|git format-patch}} [https://stackoverflow.com/questions/6658313/generate-a-git-patch-for-a-specific-commit].}}<br />
<br />
== Applying patches ==<br />
<br />
This section outlines how to apply patches you created or downloaded from the Internet from within a {{ic|PKGBUILD}}'s {{ic|prepare()}} function. Follow these steps:<br />
<br />
# Add an entry to the {{ic|source}} array of the {{ic|PKGBUILD}} for the patch file, separated from the original source url by a space. If the file is available online, you can provide the full URL and it will automatically be downloaded and placed in the {{ic|src}} directory. If it is a patch you created yourself, or is otherwise not available, you should place the patch file in the same directory as the {{ic|PKGBUILD}} file, and just add the name of the file to the source array so that it is copied into the {{ic|src}} directory. If you redistribute the {{ic|PKGBUILD}}, you should, of course, include the patch with the {{ic|PKGBUILD}}.<br />
# Then use {{ic|updpkgsums}} (from {{Pkg|pacman-contrib}}) to update the {{ic|md5sums}} array. Or manually add an entry to the {{ic|md5sums}} array; you can generate sum of your patch using {{ic|md5sum}} tool.<br />
# Create the {{ic|prepare()}} function in the {{ic|PKGBUILD}} if one is not already present.<br />
# The first step is to change into the directory that needs to be patched (in the {{ic|prepare()}} function, not on your terminal! You want to automate the process of applying the patch). You can do this with something like {{ic|cd $srcdir/$pkgname-$pkgver}} or something similar. {{ic|$pkgname-$pkgver}} is often the name of a directory created by untarring a downloaded source file, but not in all cases.<br />
# Now you simply need to apply the patch from within this directory. This is very simply done by adding <br />
patch -p1 -i ''pkgname''.patch <br />
to your {{ic|prepare()}} function, changing {{ic|''pkgname''.patch}} to the name of the file containing the diff (the file that was automatically copied into your {{ic|src}} directory because it was in the {{ic|source}} array of the {{ic|PKGBUILD}} file).<br />
<br />
An example prepare-function:<br />
prepare() {<br />
cd $pkgname-$pkgver<br />
patch -Np1 -i "${srcdir}/eject.patch"<br />
}<br />
<br />
Run {{ic|makepkg}} (from the terminal now). If all goes well, the patch will be automatically applied, and your new package will contain whatever changes were included in the patch. If not, you may have to experiment with the {{ic|-p}} option of patch. read {{man|1|patch}} for more information.<br />
Basically it works as follows. If the diff file was created to apply patches to files in {{ic|myversion/}}, the diff files will be applied to {{ic|myversion/file}}. You are running it from within the {{ic|yourversion/}} directory (because you cd would into that directory in the {{ic|PKGBUILD}}), so when patch applies the file, you want it to apply it to the file {{ic|file}}, taking off the {{ic|myversion/}} part. {{ic|-p1}} does this, by removing one directory from the path. However, if the developer patched in {{ic|myfiles/myversion}}, you need to remove two directories, so you use {{ic|-p2}}.<br />
<br />
If you do not apply a -p option, it will take off all directory structure. This is ok if all the files are in the base directory, but if the patch was created on {{ic|myversion/}} and one of the edited files was {{ic|myversion/src/file}}, and you run the patch without a {{ic|-p}} option from within {{ic|yourversion}}, it will try to patch a file named {{ic|yourversion/file}}.<br />
<br />
Most developers create patches from the parent directory of the directory that is being patched, so {{ic|-p1}} will usually be right.<br />
<br />
== Using quilt ==<br />
<br />
A simpler way to create patches is using {{Pkg|quilt}} which has better job to manage many patches, such as applying patches, refreshing patches, and reverting patched files to original state. {{Pkg|quilt}} is used on [[debian:UsingQuilt|Debian]] to manage their patches. See [http://www.shakthimaan.com/downloads/glv/quilt-tutorial/quilt-doc.pdf Using Quilt] for basic information about basic quilt usage to generate, apply patches, and reverting patched files.<br />
<br />
== See also ==<br />
<br />
* http://www.kegel.com/academy/opensource.html — Useful information on patching files</div>Progandyhttps://wiki.archlinux.org/index.php?title=Namcap&diff=524296Namcap2018-06-01T12:17:26Z<p>Progandy: /* PKGBUILDs */ updpkgsums is part of pacman-contrib</p>
<hr />
<div>[[Category:Package management]]<br />
[[Category:Package development]]<br />
[[it:Namcap]]<br />
[[ja:Namcap]]<br />
[[pt:Namcap]]<br />
Namcap is a tool to check binary packages and source PKGBUILDs for common packaging mistakes, which can also be automatically enabled. It was created by [https://www.archlinux.org/people/developer-fellows/#jason Jason Chu].<br />
<br />
'''Changes''': The [https://git.archlinux.org/namcap.git/tree/NEWS NEWS] file in the git repository contains the changes from the previous version concisely.<br />
<br />
'''Development Branch''': https://git.archlinux.org/namcap.git<br />
<br />
To '''report a bug''' or a '''feature request''' for namcap, file a bug in the ''Packages:Extra'' section of the Arch Linux [https://bugs.archlinux.org bugtracker] and the set the importance accordingly. If you are reporting a bug, please give concrete examples of packages where the problem occurs and remember to insert the version number.<br />
<br />
If you have a patch (fixing a bug or a new namcap module), then you can send it to the [mailto:arch-projects@archlinux.org arch-projects] mailing list. Namcap development is managed with git, so git-formatted patches are preferred.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|namcap}} package.<br />
<br />
== How to use it ==<br />
<br />
To run namcap on a file, where ''filename'' is {{ic|PKGBUILD}} or the name of a binary {{ic|pkg.tar.xz}}:<br />
<br />
$ namcap ''filename''<br />
<br />
If you want to see extra informational messages, then invoke namcap with the {{ic|-i}} flag:<br />
<br />
$ namcap -i ''filename''<br />
<br />
For more info on usage, see the man page {{man|1|namcap}}.<br />
<br />
== Understanding the output ==<br />
<br />
Namcap uses a system of '''tags''' to classify the output. Currently, tags are of three types, ''errors'' (denoted by E), ''warnings'' (denoted by W) and ''informational'' (denoted by I). An error is important and should be fixed immediately; mostly they relate to insufficient security, missing licenses or permission problems.<br />
<br />
Normally namcap prints a human-readable explanation (sometimes with suggestions on how to fix the problem). If you want output which can be easily parsed by a program, then pass the -m (''machine-readable'') flag to namcap (this feature is currently in the development branch).<br />
<br />
== Tags ==<br />
{{Out of date|New tags are missing and others need attention|Talk:Namcap#Tags are out of date}}<br />
<br />
=== Symbolic Links ===<br />
<br />
* '''symlink-found''' (''informational'') Reports any '''symbolic links''' present in the package.<br />
* '''hardlink-found''' (''informational'') Reports any '''hard links''' present in the package.<br />
* '''dangling-symlink''' (''<span style="color:#e00000">error</span>'') Reports occurrences of symbolic links which point to a file which is not present in the package.<br />
* '''dangling-hardlink''' (''<span style="color:#e00000">error</span>'') Reports occurrences of hard links which point to a file which is not present in the package.<br />
<br />
=== Dependencies ===<br />
<br />
* '''link-level-dependence''' (''informational'') Informs about a library to which a package is dynamically linked.<br />
* '''dependency-is-testing-release''' (''warning'') The package dependency listed is in the [testing] repository. While packages are being built for the official Arch Linux repositories (core, extra and community), then they '''should not be built''' against packages from [testing]. For [core] and [extra] packages, packages built against [testing] should be put in the [testing] repository.<br />
* '''dependency-covered-by-link-dependence''' (''informational'') Dependency covered by dependencies from link dependence. Thus this is a redundant dependency.<br />
* '''dependency-detected-not-included''' (''<span style="color:#e00000">error</span>'') The file referred to has a dependency which is not listed in the depends array. Ignore this error if the named dependency is listed in the optdepends array.<br />
* '''dependency-already-satisfied''' (''warning'') The dependency is already satisfied (as the dependency of some package already listed as a dependency for example) and thus is redundant. You can use the {{ic|pactree}} tool from {{Pkg|pacman}} to view the dependency tree of your package.<br />
* '''dependency-not-needed''' (''warning'') This dependency is not required by any file present in the program (as far as namcap could deduce). This does not work properly yet for scripts (like python or perl packages) though; there you will have to figure out the dependencies on your own.<br />
* '''depends-by-namcap-sight''' (''informational'') A list of dependencies according to namcap.<br />
<br />
=== Licenses ===<br />
<br />
* '''missing-license''' (''<span style="color:#e00000">error</span>'') This package is missing a license. Licenses should be put in the {{ic|1=license=()}} array of the PKGBUILD. See the [[Arch packaging standards]] for more information. It is '''very important''' to fix this error as soon as possible, since not including a license is a copyright violation in many cases.<br />
* '''missing-custom-license-dir''' (''<span style="color:#e00000">error</span>'') The license specified is ''custom'' but no license directory was found under ''/usr/share/licenses/'' as specified in the packaging guidelines.<br />
* '''missing-custom-license-file''' (''<span style="color:#e00000">error</span>'') The license specified is ''custom'' but no license file was found in ''/usr/share/licenses/$pkgname''.<br />
* '''not-a-common-license''' (''<span style="color:#e00000">error</span>'') The license specified is '''not''' ''custom'' but it is not present in the common {{Pkg|licenses}} package shipped in the Arch Linux distribution.<br />
<br />
=== Files ===<br />
<br />
This section describes the tags which relate to incorrect permissions of files or files not being installed in accordance with the FHS guidelines.<br />
<br />
* '''script-link-detected''' (''informational'') The following file is a script.<br />
* '''file-in-non-standard-dir''' (''warning'') The following file is in a non-standard directory as defined by the [http://proton.pathname.com/fhs/pub/fhs-2.3.html FHS guidelines]. The allowed directories are: ''bin/'', ''etc/'', ''usr/bin/'', ''usr/sbin/'', ''usr/lib'', ''usr/include/'', ''usr/share/'', ''opt/'', ''lib/'', ''sbin/'', ''srv/'', ''var/lib/'', ''var/opt/'', ''var/spool/'', ''var/lock/'', ''var/state/'', ''var/run/'', ''var/log/''.<br />
* '''elffile-not-in-allowed-dirs''' (''<span style="color:#e00000">error</span>'') ELF files should only be in these directories: ''/lib'', ''/bin'', ''/sbin'', ''/usr/bin'', ''/usr/sbin'', ''/lib'', ''/usr/lib'', ''/opt/$pkgname/''.<br />
* '''empty-directory''' (''warning'') The following directory in the package is empty.<br />
* '''non-fhs-man-page''' (''<span style="color:#e00000">error</span>'') The package installs manual pages into a location other than ''/usr/share/man'' which is the directory for manual pages according to the [http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREMANMANUALPAGES FHS guidelines].<br />
* '''potential-non-fhs-man-page''' (''warning'') This file seems to be a manual page which is not installed in ''/usr/share/man'' but namcap is not too sure about it.<br />
* '''non-fhs-info-page''' (''<span style="color:#e00000">error</span>'') The package installs info pages into a location other than ''/usr/share/info'' which is where architecture independent data should be installed according to the [http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPENDENTDATA FHS guidelines]<br />
* '''potential-non-fhs-info-page''' (''warning'') This file seems to be a info page which is not installed in ''/usr/share/info'' but namcap is not too sure about it.<br />
* '''incorrect-permissions''' (''<span style="color:#e00000">error</span>'') This file has incorrect ownership. The ownership of files in binary packages should be {{ic|root/root}}.<br />
* '''file-not-world-readable''' (''warning'') The file is not readable by everyone; usually this should not be the case.<br />
* '''file-world-writable''' (''warning'') Anyone can write to this file; again not a typical case.<br />
* '''directory-not-world-executable''' (''warning'') The directory does not have the world executable bit set. This disallows access to the directory for programs running under user privileges.<br />
* '''incorrect-library-permissions''' (''warning'') The static library file (.a) does not have permission 644 (readable and writable by root, readable by anyone else).<br />
* '''libtool-file-present''' (''warning'') This file is a libtool (.la) file and should not be normally present. One can use the {{ic|!libtool}} option in the ''options'' array of the PKGBUILD to remove these files automatically.<br />
* '''perllocal-pod-present''' (''<span style="color:#e00000">error</span>'') The file perllocal.pod should not be present in a perl package; see the [[Perl package guidelines]] for more information.<br />
* '''scrollkeeper-dir-exists''' (''<span style="color:#e00000">error</span>'') A scrollkeeper directory was found in the package. scrollkeeper should not be run till post_{install,upgrade,remove}.<br />
* '''info-dir-file-present''' (''<span style="color:#e00000">error</span>'') The info directory file ''/usr/share/info/dir'' was found in the package. This file should not be present.<br />
* '''gnome-mime-file''' (''<span style="color:#e00000">error</span>'') The file is an autogenerated GNOME mime file and should not be present in the package.<br />
<br />
=== Miscellaneous ===<br />
<br />
* '''insecure-rpath''' (''<span style="color:#e00000">error</span>'') An RPATH (for an executable) is outside ''/usr/lib''. An RPATH to an insecure location is a potential security issue. See {{Bug|14049}} for discussion.<br />
<br />
=== PKGBUILDs ===<br />
<br />
These are the tags related to the PKGBUILDs. Some of these might also apply for binary packages.<br />
<br />
* '''variable-not-array''' (''warning'') The variable should be a bash array instead of a string. These are the variables which should be written as arrays: ''arch'', ''license'', ''depends'', ''makedepends'', ''optdepends'', ''provides'', ''conflicts'', ''replaces'', ''backup'', ''source'', ''noextract'', ''md5sums''<br />
* '''backups-preceding-slashes''' (''<span style="color:#e00000">error</span>'') The file mentioned in the backup array begins with a slash ('/').<br />
* '''package-name-in-uppercase''' (''<span style="color:#e00000">error</span>'') There should not be any upper case letters in package names.<br />
* '''specific-host-type-used''' (''warning'') Instead of using a specific host type (like i686 or x86_64) use the generic $CARCH variable.<br />
* '''extra-var-begins-without-underscore''' (''warning'') The variable is not one of the standard variables defined in the PKGBUILD manual, yet it does not begin with an underscore.<br />
* '''file-referred-in-startdir''' (''<span style="color:#e00000">error</span>'') A file was referenced in ''$startdir'' outside of ''$startdir/pkg'' and ''$startdir/src''.<br />
* '''missing-md5sums''' (''<span style="color:#e00000">error</span>'') MD5sums corresponding to the source files are missing. These can be added to the PKGBUILD using {{ic|updpkgsums}} (from {{Pkg|pacman-contrib}}).<br />
* '''not-enough-md5sums''' (''<span style="color:#e00000">error</span>'') There are more source files than MD5sums provided in the PKGBUILD.<br />
* '''too-many-md5sums''' (''<span style="color:#e00000">error</span>'') There are more MD5sums than source files in the PKGBUILD.<br />
* '''improper-md5sum''' (''<span style="color:#e00000">error</span>'') An improper MD5sum was found. MD5sums are of 32 characters in length.<br />
* '''specific-sourceforge-mirror''' (''warning'') The PKGBUILD uses a specific sourceforge mirror. http://downloads.sourceforge.net should be used instead.<br />
* '''using-dl-sourceforge''' (''warning'') The deprecated http://dl.sourceforge.net domain is being used in the source array. http://downloads.sourceforge.net should be used instead.<br />
* '''missing-contributor''' (''warning'') The contributor tag is missing.<br />
* '''missing-maintainer''' (''warning'') The maintainer tag is missing.<br />
* '''missing-url''' (''<span style="color:#e00000">error</span>'') The package does not have an upstream homepage set. Use the {{ic|url}} variable for this.<br />
* '''pkgname-in-description''' (''warning'') Description should not contain the package name.<br />
* '''recommend-use-pkgdir''' (''informational'') ''$startdir/pkg'' is deprecated, use ''$pkgdir'' instead.<br />
* '''recommend-use-srcdir''' (''informational'') ''$startdir/src'' is deprecated, use ''$srcdir'' instead.<br />
<br />
=== Unreleased ===<br />
<br />
There are currently no new tags in the development version.<br />
<br />
== Making a namcap module ==<br />
<br />
This section documents the innards of namcap and specifies how to create a new namcap module.<br />
<br />
The main namcap program namcap.py takes as parameters the filename of a package or a PKGBUILD and makes a pkginfo object, which it passes to a list of rules defined in {{ic|__tarball__}} and {{ic|__pkgbuild__}}.<br />
<br />
* ''__tarball__'' defines the rules which process binary packages.<br />
* ''__pkgbuild__'' defines the rules which process PKGBUILDs<br />
<br />
Once your module is finalized, remember to add it to the appropriate array (''__tarball__'' or ''__pkgbuild__'') defined in ''Namcap/__init__.py''<br />
<br />
A sample namcap module is like this:<br />
{{hc|namcap/url.py|<nowiki><br />
import pacman<br />
<br />
class package:<br />
def short_name(self):<br />
return "url"<br />
def long_name(self):<br />
return "Verifies url is included in a PKGBUILD"<br />
def prereq(self):<br />
return ""<br />
def analyze(self, pkginfo, tar):<br />
ret = [[],[],[]]<br />
if not hasattr(pkginfo, 'url'):<br />
ret[0].append(("missing-url", ()))<br />
return ret<br />
def type(self):<br />
return "pkgbuild"<br />
</nowiki>}}<br />
<br />
Mostly, the code is self-explanatory. The following are the list of the methods that each namcap module must have:<br />
<br />
* '''short_name'''(self) Returns a string containing a short name of the module. Usually, this is the same as the basename of the module file.<br />
* '''long_name'''(self) Returns a string containing a concise description of the module. This description is used when listing all the rules using {{ic|namcap -r list}}.<br />
* '''prereq'''(self) Return a string containing the prerequisites needed for the module to operate properly. Usually "" for modules processing PKGBUILDs and "tar" for modules processing package files. "extract" should be specified if the package contents should be extracted to a temporary directory before further processing.<br />
* '''analyze'''(self, pkginfo, tar) Should return a list comprising in turn of three lists: of error tags, warning tags and information tags respectively. Each member of these tag lists should be a tuple consisting of two components: '''the short, hyphenated form''' of the tag with the appropriate format specifiers (%s, etc.) The first word of this string must be the tag name. The human readable form of the tag should be put in the tags file. The format of the tags file is described below; and '''the parameters''' which should replace the format specifier tokens in the final output.<br />
* '''type'''(self) "pkgbuild" for a module processing PKGBUILDs, "tarball" for a module processing a binary package file.<br />
<br />
The tags file consists of lines specifying the human readable form of the hyphenated tags used in the namcap code. A line beginning with a '#' is treated as a comment. Otherwise the format of the file is:<br />
<br />
machine-parseable-tag %s :: This is machine parseable tag %s<br />
<br />
Note that a double colon (::) is used to separate the hyphenated tag from the human readable description.<br />
<br />
== Namcap reports ==<br />
<br />
'''namcap-reports''' is an automatically generated report obtained after running namcap against the core, extra and community trees.<br />
<br />
How it works:<br />
* namcap is run against the entire [[ABS]] tree to make {{ic|namcap.log}}.<br />
* The packages in core, extra and community are put in files named core, extra and community respectively (using {{ic|pacman -Slq}}).<br />
* {{ic|namcap-report.py}} takes the code and prepares the report and RSS feeds, which is then copied to the webserver.</div>Progandyhttps://wiki.archlinux.org/index.php?title=Power_management&diff=512965Power management2018-03-07T21:11:11Z<p>Progandy: /* Power management with systemd */ add HandleLidSwitchExternalPower (systemd 238)</p>
<hr />
<div>[[Category:Power management]]<br />
[[es:Power management]]<br />
[[it:Shutdown Pressing Power Button]]<br />
[[ja:電源管理]]<br />
[[zh-hans:Power management]]<br />
{{Related articles start}}<br />
{{Related|Power management/Suspend and hibernate}}<br />
{{Related|Display Power Management Signaling}}<br />
{{Related|CPU frequency scaling}}<br />
{{Related|Hybrid graphics}}<br />
{{Related|Kernel modules}}<br />
{{Related|sysctl}}<br />
{{Related|udev}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Power management|Power management]] is a feature that turns off the power or switches system's components to a low-power state when inactive.<br />
<br />
In Arch Linux, power management consists of two main parts:<br />
<br />
# Configuration of the Linux kernel, which interacts with the hardware.<br />
#* [[Kernel parameters]]<br />
#* [[Kernel modules]]<br />
#* [[udev]] rules<br />
# Configuration of userspace tools, which interact with the kernel and react to its events. Many userspace tools also allow to modify kernel configuration in a "user-friendly" way. See [[#Userspace tools]] for the options.<br />
<br />
== Userspace tools ==<br />
<br />
Using these tools can replace setting a lot of settings by hand. Only run '''one''' of these tools to avoid possible conflicts as they all work more or less similarly. Have a look at the [[:Category:Power management|power management category]] to get an overview on what power management options exist in Arch Linux.<br />
<br />
These are the more popular scripts and tools designed to help power saving:<br />
<br />
* {{App|[[acpid]]| A daemon for delivering ACPI power management events with netlink support.|http://sourceforge.net/projects/acpid2/|{{Pkg|acpid}}}}<br />
* {{App|[[Laptop Mode Tools]]|Utility to configure laptop power saving settings, considered by many to be the de facto utility for power saving though may take a bit of configuration.|https://github.com/rickysarraf/laptop-mode-tools|{{AUR|laptop-mode-tools}}}}<br />
* {{App|[[powertop]]|A tool to diagnose issues with power consumption and power management to help set power saving settings.|https://01.org/powertop/|{{Pkg|powertop}}}}<br />
* [[systemd]]<br />
* {{App|[[TLP]]|Advanced power management for Linux.|http://linrunner.de/tlp|{{Pkg|tlp}}}}<br />
<br />
== Power management with systemd ==<br />
<br />
=== ACPI events ===<br />
<br />
''systemd'' handles some power-related [[Wikipedia:Advanced_Configuration_and_Power_Interface|ACPI]] events, whose actions can be configured in {{ic|/etc/systemd/logind.conf}} or {{ic|/etc/systemd/logind.conf.d/*.conf}} — see {{man|5|logind.conf}}. On systems with no dedicated power manager, this may replace the [[acpid]] daemon which is usually used to react to these ACPI events.<br />
<br />
The specified action for each event can be one of {{ic|ignore}}, {{ic|poweroff}}, {{ic|reboot}}, {{ic|halt}}, {{ic|suspend}}, {{ic|hibernate}}, {{ic|hybrid-sleep}}, {{ic|lock}} or {{ic|kexec}}. In case of hibernation and suspension, they must be properly [[Power management/Suspend and hibernate|set up]]. If an event is not configured, ''systemd'' will use a default action.<br />
<br />
{| class="wikitable sortable" border=1<br />
!Event handler<br />
!Description<br />
!Default action<br />
|-<br />
|{{ic|HandlePowerKey}}<br />
|Triggered when the power key/button is pressed.<br />
|{{ic|poweroff}}<br />
|-<br />
|{{ic|HandleSuspendKey}}<br />
|Triggered when the suspend key/button is pressed.<br />
|{{ic|suspend}}<br />
|-<br />
|{{ic|HandleHibernateKey}}<br />
|Triggered when the hibernate key/button is pressed.<br />
|{{ic|hibernate}}<br />
|-<br />
|{{ic|HandleLidSwitch}}<br />
|Triggered when the lid is closed, except in the cases below.<br />
|{{ic|suspend}}<br />
|-<br />
|{{ic|HandleLidSwitchDocked}}<br />
|Triggered when the lid is closed if the system is inserted in a docking station, or more than one display is connected.<br />
|{{ic|ignore}}<br />
|-<br />
|{{ic|HandleLidSwitchExternalPower}}<br />
|Triggered when the lid is closed if the system is connected to external power.<br />
|action set for {{ic|HandleLidSwitch}}<br />
|}<br />
<br />
To apply any changes, [[restart]] the {{ic|systemd-logind}} daemon (be warned that this will terminate all login sessions that might still be open).<br />
<br />
{{Note|''systemd'' cannot handle AC and Battery ACPI events, so if you use [[Laptop Mode Tools]] or other similar tools [[acpid]] is still required.}}<br />
<br />
==== Power managers ====<br />
<br />
Some [[desktop environment]]s include power managers which [http://www.freedesktop.org/wiki/Software/systemd/inhibit/ inhibit] (temporarily turn off) some or all of the ''systemd'' ACPI settings. If such a power manager is running, then the actions for ACPI events can be configured in the power manager alone. Changes to {{ic|/etc/systemd/logind.conf}} or {{ic|/etc/systemd/logind.conf.d/*.conf}} need be made only if you wish to configure behaviour for a particular event that is not inhibited by the power manager. <br />
<br />
Note that if the power manager does not inhibit ''systemd'' for the appropriate events you can end up with a situation where ''systemd'' suspends your system and then when the system is woken up the other power manager suspends it again. As of December 2016, the power managers of [[KDE]], [[GNOME]], [[Xfce]] and [[MATE]] issue the necessary ''inhibited'' commands. If the ''inhibited'' commands are not being issued, such as when using [[acpid]] or others to handle ACPI events, set the {{ic|Handle}} options to {{ic|ignore}}. See also {{man|1|systemd-inhibit}}.<br />
<br />
==== xss-lock ====<br />
<br />
{{pkg|xss-lock}} subscribes to the systemd-events {{ic|suspend}}, {{ic|hibernate}}, {{ic|lock-session}}, and {{ic|unlock-session}} with appropriate actions (run locker and wait for user to unlock or kill locker). ''xss-lock'' also reacts to [[DPMS]] events and runs or kills the locker in response.<br />
<br />
Start xss-lock in your [[autostart]], for example<br />
<br />
xss-lock -- i3lock -n -i ''background_image.png'' &<br />
<br />
=== Suspend and hibernate ===<br />
<br />
''systemd'' provides commands for suspend to RAM, hibernate and a hybrid suspend using the kernel's native suspend/resume functionality. There are also mechanisms to add hooks to customize pre- and post-suspend actions.<br />
<br />
{{Note|''systemd'' can also use other suspend backends (such as [[Uswsusp]]), in addition to the default ''kernel'' backend, in order to put the computer to sleep or hibernate. See [[Uswsusp#With systemd]] for an example.}}<br />
<br />
{{ic|systemctl suspend}} should work out of the box, for {{ic|systemctl hibernate}} to work on your system you need to follow the instructions at [[Suspend and hibernate#Hibernation]].<br />
<br />
==== Hybrid sleep ====<br />
<br />
{{ic|systemctl hybrid-sleep}} both hibernates and suspends at the same time. This combines some of the benefits and drawbacks of suspension and hibernation. This is useful in case a computer were to suddenly lose power (AC disconnection or battery depletion) since upon powerup it will resume from hibernation. If there is no power loss, then it will resume from suspension, which is much faster than resuming from hibernation. However, since "hybrid-sleep" has to dump memory to swap in order for hibernation to work, it is slower to enter sleep than a plain {{ic|systemctl suspend}}. An alternative is a [[#Delayed_hibernation_service_file|delayed hibernation service file]].<br />
<br />
==== Always do hybrid-sleep instead of suspend or hibernation ====<br />
<br />
It is possible to configure systemd to always do a ''hybrid-sleep'' even on a ''suspend'' or ''hibernation'' request.<br />
<br />
The default ''suspend'' and ''hibernation'' action can be configured in the {{ic|/etc/systemd/sleep.conf}} file. To set both actions to ''hybrid-sleep'':<br />
<br />
{{hc|/etc/systemd/sleep.conf|2=<br />
[Sleep]<br />
# suspend=hybrid-sleep<br />
SuspendMode=suspend<br />
SuspendState=disk<br />
# hibernate=hybrid-sleep<br />
HibernateMode=suspend<br />
HibernateState=disk<br />
}}<br />
<br />
See the {{man|5|sleep.conf.d}} manual page for details.<br />
<br />
=== Sleep hooks ===<br />
<br />
==== Suspend/resume service files ====<br />
<br />
Service files can be hooked into ''suspend.target'', ''hibernate.target'' and ''sleep.target'' to execute actions before or after suspend/hibernate. Separate files should be created for user actions and root/system actions. [[Enable]] the {{ic|suspend@''user''}} and {{ic|resume@''user''}} services to have them started at boot. Examples:<br />
<br />
{{hc|/etc/systemd/system/suspend@.service|2=<nowiki><br />
[Unit]<br />
Description=User suspend actions<br />
Before=sleep.target<br />
<br />
[Service]<br />
User=%I<br />
Type=forking<br />
Environment=DISPLAY=:0<br />
ExecStartPre= -/usr/bin/pkill -u %u unison ; /usr/local/bin/music.sh stop ; /usr/bin/mysql -e 'slave stop'<br />
ExecStart=/usr/bin/sflock<br />
ExecStartPost=/usr/bin/sleep 1<br />
<br />
[Install]<br />
WantedBy=sleep.target</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/resume@.service|2=<nowiki><br />
[Unit]<br />
Description=User resume actions<br />
After=suspend.target<br />
<br />
[Service]<br />
User=%I<br />
Type=simple<br />
ExecStartPre=/usr/local/bin/ssh-connect.sh<br />
ExecStart=/usr/bin/mysql -e 'slave start'<br />
<br />
[Install]<br />
WantedBy=suspend.target</nowiki>}}<br />
<br />
{{Note|As screen lockers may return before the screen is "locked", the screen may flash on resuming from suspend. Adding a small delay via {{ic|1=ExecStartPost=/usr/bin/sleep 1}} helps prevent this.}}<br />
<br />
For root/system actions ([[enable]] the {{ic|root-resume}} and {{ic|root-suspend}} services to have them started at boot):<br />
<br />
{{hc|/etc/systemd/system/root-resume.service|2=<nowiki><br />
[Unit]<br />
Description=Local system resume actions<br />
After=suspend.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=/usr/bin/systemctl restart mnt-media.automount<br />
<br />
[Install]<br />
WantedBy=suspend.target</nowiki>}}<br />
<br />
{{hc|/etc/systemd/system/root-suspend.service|2=<nowiki><br />
[Unit]<br />
Description=Local system suspend actions<br />
Before=sleep.target<br />
<br />
[Service]<br />
Type=simple<br />
ExecStart=-/usr/bin/pkill sshfs<br />
<br />
[Install]<br />
WantedBy=sleep.target</nowiki>}}<br />
<br />
A couple of handy hints about these service files (more in {{man|5|systemd.service}}):<br />
* If {{ic|1=<nowiki>Type=oneshot</nowiki>}} then you can use multiple {{ic|1=<nowiki>ExecStart=</nowiki>}} lines. Otherwise only one {{ic|ExecStart}} line is allowed. You can add more commands with either {{ic|ExecStartPre}} or by separating commands with a semicolon (see the first example above; note the spaces before and after the semicolon, as they are ''required'').<br />
* A command prefixed with {{ic|-}} will cause a non-zero exit status to be ignored and treated as a successful command. <br />
* The best place to find errors when troubleshooting these service files is of course with [[journalctl]].<br />
<br />
==== Combined Suspend/resume service file ====<br />
<br />
With the combined suspend/resume service file, a single hook does all the work for different phases (sleep/resume) and for different targets (suspend/hibernate/hybrid-sleep).<br />
<br />
Example and explanation:<br />
<br />
{{hc|/etc/systemd/system/wicd-sleep.service|2=<nowiki><br />
[Unit]<br />
Description=Wicd sleep hook<br />
Before=sleep.target<br />
StopWhenUnneeded=yes<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
ExecStart=-/usr/share/wicd/daemon/suspend.py<br />
ExecStop=-/usr/share/wicd/daemon/autoconnect.py<br />
<br />
[Install]<br />
WantedBy=sleep.target</nowiki>}}<br />
<br />
* {{ic|1=<nowiki>RemainAfterExit=yes</nowiki>}}: After started, the service is considered active until it is explicitly stopped.<br />
* {{ic|1=<nowiki>StopWhenUnneeded=yes</nowiki>}}: When active, the service will be stopped if no other active service requires it. In this specific example, it will be stopped after ''sleep.target'' is stopped.<br />
* Because ''sleep.target'' is pulled in by ''suspend.target'', ''hibernate.target'' and ''hybrid-sleep.target'' and because ''sleep.target'' itself is a ''StopWhenUnneeded'' service, the hook is guaranteed to start/stop properly for different tasks.<br />
<br />
==== Delayed hibernation service file ====<br />
<br />
An alternative approach is delayed hibernation. This makes use of sleep hooks to suspend as usual but sets a timer to wake up later to perform hibernation. Here, entering sleep is faster than {{ic|systemctl hybrid-sleep}} since no hibernation is performed initially. However, unlike "hybrid-sleep", at this point there is no protection against power loss via hibernation while in suspension. This caveat makes this approach more suitable for laptops than desktops. Since hibernation is delayed, the laptop battery is only used during suspension and to trigger the eventual hibernation. This uses less power over the long-term than a "hybrid-sleep" which will remain suspended until the battery is drained. Note that if your laptop has a spinning hard disk, when it wakes up from suspend in order to hibernate, you may not want to be moving or carrying the laptop for these few seconds. Delayed hibernation may be desirable both to reduce power use as well as for security reasons (e.g. when using full disk encryption). An example script is located [http://superuser.com/questions/298672/linuxhow-to-hibernate-after-a-period-of-sleep here]. See also [https://bbs.archlinux.org/viewtopic.php?pid=1420279#p1420279 this post] for an updated systemd sleep hook. <br />
<br />
A slightly updated version of the service is:<br />
{{hc|/etc/systemd/system/suspend-to-hibernate.service|<nowiki><br />
[Unit]<br />
Description=Delayed hibernation trigger<br />
Documentation=https://bbs.archlinux.org/viewtopic.php?pid=1420279#p1420279<br />
Documentation=https://wiki.archlinux.org/index.php/Power_management<br />
Conflicts=hibernate.target hybrid-sleep.target<br />
Before=sleep.target<br />
StopWhenUnneeded=true<br />
<br />
[Service]<br />
Type=oneshot<br />
RemainAfterExit=yes<br />
Environment="WAKEALARM=/sys/class/rtc/rtc0/wakealarm"<br />
Environment="SLEEPLENGTH=+2hour"<br />
ExecStart=-/usr/bin/sh -c 'echo -n "alarm set for "; date +%%s -d$SLEEPLENGTH | tee $WAKEALARM'<br />
ExecStop=-/usr/bin/sh -c '\<br />
alarm=$(cat $WAKEALARM); \<br />
now=$(date +%%s); \<br />
if [ -z "$alarm" ] || [ "$now" -ge "$alarm" ]; then \<br />
echo "hibernate triggered"; \<br />
systemctl hibernate; \<br />
else \<br />
echo "normal wakeup"; \<br />
fi; \<br />
echo 0 > $WAKEALARM; \<br />
'<br />
<br />
[Install]<br />
WantedBy=sleep.target<br />
</nowiki><br />
}}<br />
<br />
The {{ic|Before}} and {{ic|Conflicts}} options ensure it only is run for suspension and not hibernation--otherwise the service will run twice if delayed hibernation is triggered. The {{ic|WantedBy}} and {{ic|StopWhenUnneeded}} options are so it is started before sleep and stops upon resume. (Note that the {{ic|suspend.target}} and {{ic|hibernate.target}} targets do not stop when unneeded, but {{ic|sleep.target}} does). [[Enable]] the service.<br />
<br />
==== Hooks in /usr/lib/systemd/system-sleep ====<br />
<br />
''systemd'' runs all executables in {{ic|/usr/lib/systemd/system-sleep/}}, passing two arguments to each of them:<br />
<br />
* Argument 1: either {{ic|pre}} or {{ic|post}}, depending on whether the machine is going to sleep or waking up<br />
* Argument 2: {{ic|suspend}}, {{ic|hibernate}} or {{ic|hybrid-sleep}}, depending on which is being invoked<br />
<br />
''systemd'' will run these scripts concurrently and not one after another.<br />
<br />
The output of any custom script will be logged by ''systemd-suspend.service'', ''systemd-hibernate.service'' or ''systemd-hybrid-sleep.service''. You can see its output in ''systemd''<nowiki>'</nowiki>s [[systemd#Journal|journal]]:<br />
# journalctl -b -u systemd-suspend<br />
<br />
{{Note|You can also use ''sleep.target'', ''suspend.target'', ''hibernate.target'' or ''hybrid-sleep.target'' to hook units into the sleep state logic instead of using custom scripts.}}<br />
<br />
An example of a custom sleep script:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/example.sh|<br />
#!/bin/sh<br />
case $1/$2 in<br />
pre/*)<br />
echo "Going to $2..."<br />
;;<br />
post/*)<br />
echo "Waking up from $2..."<br />
;;<br />
esac}}<br />
<br />
Do not forget to make your script executable:<br />
# chmod a+x /usr/lib/systemd/system-sleep/example.sh<br />
<br />
See {{man|7|systemd.special}} and {{man|8|systemd-sleep}} for more details.<br />
<br />
=== Troubleshooting ===<br />
<br />
==== Delayed lid switch action ====<br />
<br />
When performing lid switches in short succession, ''logind'' will delay the suspend action for up to 90s to detect possible docks. [http://lists.freedesktop.org/archives/systemd-devel/2015-January/027131.html] This delay was made configurable with systemd v220:[https://github.com/systemd/systemd/commit/9d10cbee89ca7f82d29b9cb27bef11e23e3803ba]<br />
{{hc|/etc/systemd/logind.conf|<nowiki><br />
...<br />
HoldoffTimeoutSec=30s<br />
...<br />
</nowiki>}}<br />
<br />
==== Suspend from corresponding laptop Fn key not working ====<br />
<br />
If, regardless of the setting in logind.conf, the sleep button does not work (pressing it does not even produce a message in syslog), then logind is probably not watching the keyboard device. [http://lists.freedesktop.org/archives/systemd-devel/2015-February/028325.html] Do:<br />
# journalctl | grep "Watching system buttons"<br />
You might see something like this:<br />
May 25 21:28:19 vmarch.lan systemd-logind[210]: Watching system buttons on /dev/input/event2 (Power Button)<br />
May 25 21:28:19 vmarch.lan systemd-logind[210]: Watching system buttons on /dev/input/event3 (Sleep Button)<br />
May 25 21:28:19 vmarch.lan systemd-logind[210]: Watching system buttons on /dev/input/event4 (Video Bus)<br />
Notice no keyboard device. Now obtain ATTRS{name} for the parent keyboard device [http://systemd-devel.freedesktop.narkive.com/Rbi3rjNN/patch-1-2-logind-add-support-for-tps65217-power-button] :<br />
# udevadm info -a /dev/input/by-path/*-kbd<br />
...<br />
KERNEL=="event0"<br />
...<br />
ATTRS{name}=="AT Translated Set 2 keyboard"<br />
Now write a custom udev rule to add the "power-switch" tag:<br />
{{hc|/etc/udev/rules.d/70-power-switch-my.rules|<nowiki><br />
ACTION=="remove", GOTO="power_switch_my_end"<br />
SUBSYSTEM=="input", KERNEL=="event*", ATTRS{name}=="AT Translated Set 2 keyboard", TAG+="power-switch"<br />
LABEL="power_switch_my_end"<br />
</nowiki>}}<br />
Restart services and reload rules:<br />
# systemctl restart systemd-udevd<br />
# udevadm trigger<br />
# systemctl restart systemd-logind<br />
Now you should see "Watching system buttons on /dev/input/event0" in syslog<br />
<br />
== Power saving ==<br />
<br />
{{Note|See [[Laptop#Power management]] for power management specific to laptops, such as battery monitoring.}}<br />
<br />
This section is a reference for creating custom scripts and power saving settings such as by udev rules. Make sure that the settings are not managed by some [[#Userspace tools|other utility]] to avoid conflicts.<br />
<br />
Almost all of the features listed here are worth using whether or not the computer is on AC or battery power. Most have negligible performance impact and are just not enabled by default because of commonly broken hardware/drivers. Reducing power usage means reducing heat, which can even lead to higher performance on a modern Intel or AMD CPU, thanks to [[Wikipedia:Intel Turbo Boost|dynamic overclocking]].<br />
<br />
=== Audio ===<br />
<br />
By default, audio power saving is turned off by most drivers. It can be enabled by setting the {{ic|power_save}} parameter; a time (in seconds) to go into idle mode. To idle the audio card after one second, create the following file for Intel soundcards.<br />
<br />
{{hc|/etc/modprobe.d/audio_powersave.conf|2=options snd_hda_intel power_save=1}}<br />
<br />
Alternatively, use the following for ac97:<br />
<br />
options snd_ac97_codec power_save=1<br />
<br />
{{Note|<br />
* To retrieve the manufacturer and the corresponding kernel driver which is used for your sound card, run {{ic|lspci -k}}.<br />
* Toggling the audio card's power state can cause a popping sound or noticeable latency on some broken hardware.<br />
}}<br />
<br />
It is also possible to further reduce the audio power requirements by disabling the HDMI audio output, which can done by [[blacklisting]] the appropriate kernel modules (e.g. {{ic|snd_hda_codec_hdmi}} in case of Intel hardware).<br />
<br />
=== Backlight ===<br />
<br />
See [[Backlight]].<br />
<br />
=== Bluetooth ===<br />
<br />
{{expansion|reason=The device should likely be disabled with hciconfig first.}}<br />
<br />
To disable bluetooth completely, [[blacklist]] the {{ic|btusb}} and {{ic|bluetooth}} modules.<br />
<br />
To turn off bluetooth only temporarily, use ''rfkill'':<br />
<br />
# rfkill block bluetooth<br />
<br />
Or with udev rule:<br />
<br />
{{hc|/etc/udev/rules.d/50-bluetooth.rules|<nowiki><br />
# disable bluetooth<br />
SUBSYSTEM=="rfkill", ATTR{type}=="bluetooth", ATTR{state}="0"<br />
</nowiki>}}<br />
<br />
=== Web camera ===<br />
<br />
If you will not use integrated web camera then [[blacklist]] the {{ic|uvcvideo}} module.<br />
<br />
=== Kernel parameters ===<br />
<br />
This section uses configs in {{ic|/etc/sysctl.d/}}, which is ''"a drop-in directory for kernel sysctl parameters."'' See [http://0pointer.de/blog/projects/the-new-configuration-files The New Configuration Files] and more specifically {{man|5|sysctl.d}} for more information.<br />
<br />
==== Disabling NMI watchdog ====<br />
{{Expansion|This or {{ic|nowatchdog}} as can be seen in [[Improving performance#Watchdogs]]}}<br />
<br />
The [[Wikipedia:Non-maskable interrupt|NMI]] watchdog is a debugging feature to catch hardware hangs that cause a kernel panic. On some systems it can generate a lot of interrupts, causing a noticeable increase in power usage:<br />
<br />
{{hc|/etc/sysctl.d/disable_watchdog.conf|2=kernel.nmi_watchdog = 0}}<br />
<br />
or add {{ic|1=nmi_watchdog=0}} to the [[kernel line]] to disable it completely from early boot.<br />
<br />
==== Writeback Time ====<br />
<br />
Increasing the virtual memory dirty writeback time helps to aggregate disk I/O together, thus reducing spanned disk writes, and increasing power saving. To set the value to 60 seconds (default is 5 seconds):<br />
<br />
{{hc|/etc/sysctl.d/dirty.conf|2=vm.dirty_writeback_centisecs = 6000}}<br />
<br />
To do the same for journal commits on supported filesystems (e.g. ext4, btrfs...), use {{ic|1=commit=60}} as a option in [[fstab]].<br />
<br />
Note that this value is modified as a side effect of the Laptop Mode setting below.<br />
See also [[sysctl#Virtual memory]] for other parameters affecting I/O performance and power saving.<br />
<br />
==== Laptop Mode ====<br />
<br />
See the [https://www.kernel.org/doc/Documentation/laptops/laptop-mode.txt kernel documentation] on the laptop mode 'knob.' ''"A sensible value for the knob is 5 seconds."''<br />
<br />
{{hc|/etc/sysctl.d/laptop.conf|2=vm.laptop_mode = 5}}<br />
<br />
{{Note|This setting is mainly relevant to spinning-disk drives.}}<br />
<br />
=== Network interfaces ===<br />
<br />
[[Wake-on-LAN]] can be a useful feature, but if you are not making use of it then it is simply draining extra power waiting for a magic packet while in suspend. You can adapt a [[Wake-on-LAN#udev|udev rule]] to disable the feature for all Ethernet interfaces.<br />
<br />
To enable powersaving with {{Pkg|iw}} on all wireless interfaces:<br />
<br />
{{hc|/etc/udev/rules.d/70-wifi-powersave.rules|2=ACTION=="add", SUBSYSTEM=="net", KERNEL=="wlan*", RUN+="/usr/bin/iw dev %k set power_save on"}}<br />
<br />
In this example, {{ic|%k}} is a specifier for the kernel name of the matched device. For example, if it finds that the rule is applicable to {{ic|wlan0}}, the {{ic|%k}} specifier will be replaced with {{ic|wlan0}}. To apply the rules to only a particular interface, just replace the pattern {{ic|eth*}} and specifier {{ic|%k}} with the desired interface name. For more information, see [http://www.reactivated.net/writing_udev_rules.html Writing udev rules].<br />
<br />
{{Note|In this case, the name of the configuration file is important. Due to the introduction of [[Network configuration#Change device name|persistent device names]] via {{ic|80-net-setup-link.rules}} in systemd, it is important that the network powersave rules are named lexicographically before {{ic|80-net-setup-link.rules}} so that they are applied before the devices are named e.g. {{ic|enp2s0}}.<br />
<br />
However, be advised that commands ran with {{ic|RUN}} are executed '''after''' all rules have been processed -- in which case the naming of the rules file is irrelevant and the persistent device names should be used (the persistent device name can be referenced by replacing {{ic|%k}} with {{ic|$name}}).}}<br />
<br />
==== Intel wireless cards (iwlwifi) ====<br />
<br />
Additional power saving functions of Intel wireless cards with {{ic|iwlwifi}} driver can be enabled by passing the correct parameters to the kernel module. Making it persistent can be achieved by adding the line below to {{ic|/etc/modprobe.d/iwlwifi.conf}} file:<br />
<br />
options iwlwifi power_save=1 d0i3_disable=0 uapsd_disable=0<br />
options iwldvm force_cam=0<br />
<br />
Keep in mind that these power saving options are experimental and can cause an unstable system.<br />
<br />
=== Bus power management ===<br />
<br />
==== Active State Power Management ====<br />
<br />
If the computer is believed not to support [[Wikipedia:Active State Power Management|ASPM]] it will be disabled on boot:<br />
<br />
# lspci -vv | grep ASPM.*abled\;<br />
<br />
ASPM is handled by the BIOS, if ASPM is disabled it will be because [http://wireless.kernel.org/en/users/Documentation/ASPM ref]:<br />
<br />
# The BIOS disabled it for some reason (for conflicts?).<br />
# PCIE requires ASPM but L0s are optional (so L0s might be disabled and only L1 enabled).<br />
# The BIOS might not have been programmed for it.<br />
# The BIOS is buggy.<br />
<br />
If believing the computer has support for ASPM it can be forced on for the kernel to handle with the {{ic|1=pcie_aspm=force}} [[kernel parameter]].<br />
<br />
{{Warning|<br />
* Forcing on ASPM can cause a freeze/panic, so make sure you have a way to undo the option if it does not work.<br />
* On systems that do not support it forcing on ASPM can even increase power consumption.<br />
* This forces ASPM in kernel while it can still remain disabled in hardware and not work. To check whether this is the case the {{ic|dmesg &#124; grep ASPM}} command can be used and if that is the case, hardware-specific Wiki article should be consulted.<br />
}}<br />
<br />
To adjust to {{ic|powersave}} do (the following command will not work unless enabled):<br />
<br />
echo powersave | tee /sys/module/pcie_aspm/parameters/policy<br />
<br />
By default it looks like this:<br />
<br />
{{hc|$ cat /sys/module/pcie_aspm/parameters/policy|[default] performance powersave}}<br />
<br />
==== PCI Runtime Power Management ====<br />
<br />
{{hc|/etc/udev/rules.d/pci_pm.rules|2=ACTION=="add", SUBSYSTEM=="pci", ATTR{power/control}="auto"}}<br />
<br />
==== USB autosuspend ====<br />
<br />
The Linux kernel can automatically suspend USB devices when they are not in use. This can sometimes save quite a bit of power, however some USB devices are not compatible with USB power saving and start to misbehave (common for USB mice/keyboards). [[udev]] rules based on whitelist or blacklist filtering can help to mitigate the problem.<br />
<br />
The most simple and likely useless example is enabling autosuspend for all USB devices:<br />
<br />
{{hc|/etc/udev/rules.d/50-usb_power_save.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", TEST=="power/control", ATTR{power/control}="auto"<br />
</nowiki>}}<br />
<br />
To allow autosuspend only for devices that are known to work, use simple matching against vendor and product IDs (use ''lsusb'' to get these values):<br />
<br />
{{hc|/etc/udev/rules.d/50-usb_power_save.rules|<nowiki><br />
# whitelist for usb autosuspend<br />
ACTION=="add", SUBSYSTEM=="usb", TEST=="power/control", ATTR{idVendor}=="05c6", ATTR{idProduct}=="9205", ATTR{power/control}="auto"<br />
</nowiki>}}<br />
<br />
Alternatively, to blacklist devices that are not working with USB autosuspend and enable it for all other devices:<br />
<br />
{{hc|/etc/udev/rules.d/50-usb_power_save.rules|<nowiki><br />
# blacklist for usb autosuspend<br />
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="05c6", ATTR{idProduct}=="9205", GOTO="power_usb_rules_end"<br />
<br />
ACTION=="add", SUBSYSTEM=="usb", TEST=="power/control", ATTR{power/control}="auto"<br />
LABEL="power_usb_rules_end"<br />
</nowiki>}}<br />
<br />
The default autosuspend idle delay time is controlled by the {{ic|autosuspend}} parameter of the {{ic|usbcore}} [[kernel module]]. To set the delay to 5 seconds instead of the default 2 seconds:<br />
<br />
{{hc|/etc/modprobe.d/usb-autosuspend.conf|<nowiki><br />
options usbcore autosuspend=5<br />
</nowiki>}}<br />
<br />
Similarly to {{ic|power/control}}, the delay time can be fine-tuned per device by setting the {{ic|power/autosuspend}} attribute.<br />
<br />
See the [https://www.kernel.org/doc/Documentation/usb/power-management.txt Linux kernel documentation] for more information on USB power management.<br />
<br />
==== SATA Active Link Power Management ====<br />
{{Warning|SATA Active Link Power Management can lead to data loss on some devices. Do not enable this setting unless you have frequent backups.}}<br />
Since Linux 4.15 there is a [https://hansdegoede.livejournal.com/18412.html| new setting] called {{ic|med_power_with_dipm}} that matches the behaviour of Windows IRST driver settings and should not cause data loss with recent SSD/HDD drives. The power saving can be significant, ranging [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ebb82e3c79d2a956366d0848304a53648bd6350b| from 1.0 to 1.5 Watts (when idle)]. It will become a default setting for Intel based laptops in Linux 4.16 [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ebb82e3c79d2a956366d0848304a53648bd6350b].<br />
<br />
The current setting can be read from {{ic|/sys/class/scsi_host/host*/link_power_management_policy}} as follows:<br />
# cat /sys/class/scsi_host/host*/link_power_management_policy<br />
<br />
{| class="wikitable"<br />
|+ Available ALPM settings<br />
! Setting<br />
! Description<br />
! Power saving<br />
|-<br />
| max_performance<br />
| current default<br />
| None<br />
|-<br />
| medium_power<br />
| -<br />
| ~1.0 Watts<br />
|-<br />
| med_power_with_dipm<br />
| recommended setting<br />
| ~1.5 Watts<br />
|-<br />
| min_power<br />
| '''WARNING: possible data loss'''<br />
| ~1.5 Watts<br />
|}<br />
<br />
{{hc|/etc/udev/rules.d/hd_power_save.rules|2=ACTION=="add", SUBSYSTEM=="scsi_host", KERNEL=="host*", ATTR{link_power_management_policy}="med_power_with_dipm"}}<br />
{{Note|This adds latency when accessing a drive that has been idle, so it is one of the few settings that may be worth toggling based on whether you are on AC power.}}<br />
<br />
=== Hard disk drive ===<br />
<br />
See [[hdparm#Power management configuration]] for drive parameters that can be set.<br />
<br />
Power saving is not effective when too many programs are frequently writing to the disk. Tracking all programs, and how and when they write to disk is the way to limit disk usage. Use {{Pkg|iotop}} to see which programs use the disk frequently. See [[Improving performance#Storage devices]] for other tips.<br />
<br />
Also little things like setting the [[Fstab#atime options|noatime]] option can help. If enough RAM is available, consider disabling or limiting [[swappiness]] as it has the possibility to limit a good number of disk writes.<br />
<br />
=== CD-ROM or DVD drive === <br />
<br />
See [[Udisks#Devices do not remain unmounted (udisks)]].<br />
<br />
== Tools and scripts ==<br />
<br />
{{Style|Merged from [[Power saving]], needs reorganization to fit into this page.}}<br />
<br />
=== Using a script and an udev rule ===<br />
<br />
Since systemd users can suspend and hibernate through {{ic|systemctl suspend}} or {{ic|systemctl hibernate}} and handle acpi events with {{ic|/etc/systemd/logind.conf}}, it might be interesting to remove ''pm-utils'' and [[acpid]]. There is just one thing systemd cannot do (as of systemd-204): power management depending on whether the system is running on AC or battery. To fill this gap, you can create a single [[udev]] rule that runs a script when the AC adapter is plugged and unplugged:<br />
<br />
{{hc|/etc/udev/rules.d/powersave.rules|2=<nowiki><br />
SUBSYSTEM=="power_supply", ATTR{online}=="0", RUN+="/path/to/your/script true"<br />
SUBSYSTEM=="power_supply", ATTR{online}=="1", RUN+="/path/to/your/script false"<br />
</nowiki>}}<br />
<br />
{{Note|You can use the same script that ''pm-powersave'' uses. You just have to make it executable and place it somewhere else (for example {{ic|/usr/local/bin/}}).}}<br />
<br />
Examples of powersave scripts:<br />
<br />
* [https://github.com/supplantr/ftw ftw], package: {{AUR|ftw-git}}<br />
* [https://github.com/Unia/powersave powersave]<br />
* [https://github.com/quequotion/pantheon-bzr-qq/blob/master/EXTRAS/indicator-powersave/throttle throttle], from {{AUR|indicator-powersave}}<br />
<br />
The above udev rule should work as expected, but if your power settings are not updated after a suspend or hibernate cycle, you should add a script in {{ic|/usr/lib/systemd/system-sleep/}} with the following contents:<br />
<br />
{{hc|/usr/lib/systemd/system-sleep/00powersave|<nowiki><br />
#!/bin/sh<br />
<br />
case $1 in<br />
pre) /path/to/your/script false ;;<br />
post) <br />
if cat /sys/class/power_supply/AC0/online | grep 0 > /dev/null 2>&1<br />
then<br />
/path/to/your/script true <br />
else<br />
/path/to/your/script false<br />
fi<br />
;;<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Do not forget to make it executable!<br />
<br />
{{Note|Be aware that AC0 may be different for your laptop, change it if that is the case.}}<br />
<br />
=== Print power settings ===<br />
<br />
This script prints power settings and a variety of other properties for USB and PCI devices. Note that root permissions are needed to see all settings.<br />
<br />
{{bc|<nowiki><br />
#!/bin/bash<br />
<br />
for i in $(find /sys/devices -name "bMaxPower")<br />
do<br />
busdir=${i%/*}<br />
busnum=$(<$busdir/busnum)<br />
devnum=$(<$busdir/devnum)<br />
title=$(lsusb -s $busnum:$devnum)<br />
<br />
printf "\n\n+++ %s\n -%s\n" "$title" "$busdir"<br />
<br />
for ff in $(find $busdir/power -type f ! -empty 2>/dev/null)<br />
do<br />
v=$(cat $ff 2>/dev/null|tr -d "\n")<br />
[[ ${#v} -gt 0 ]] && echo -e " ${ff##*/}=$v";<br />
v=;<br />
done | sort -g;<br />
done;<br />
<br />
printf "\n\n\n+++ %s\n" "Kernel Modules"<br />
for mod in $(lspci -k | sed -n '/in use:/s,^.*: ,,p' | sort -u)<br />
do<br />
echo "+ $mod";<br />
systool -v -m $mod 2> /dev/null | sed -n "/Parameters:/,/^$/p";<br />
done<br />
</nowiki>}}<br />
<br />
== See also ==<br />
<br />
* [http://www.thinkwiki.org/wiki/How_to_reduce_power_consumption ThinkWiki:How to reduce power consumption]<br />
* [http://ivanvojtko.blogspot.sk/2016/04/how-to-get-longer-battery-life-on-linux.html How to get longer battery life on Linux]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Linux_Containers&diff=505085Linux Containers2017-12-30T11:24:25Z<p>Progandy: /* Cannot start unprivileged LXC due to newuidmap execution failure */ REMOVED, current shadow v4.5 is fixed according to FS#52560</p>
<hr />
<div>[[Category:Security]]<br />
[[Category:Virtualization]]<br />
[[ja:Linux Containers]]<br />
[[pt:Linux Containers]]<br />
{{Related articles start}}<br />
{{Related|AirVPN}}<br />
{{Related|ABS}}<br />
{{Related|Cgroups}}<br />
{{Related|Docker}}<br />
{{Related|LXD}}<br />
{{Related|OpenVPN}}<br />
{{Related|OpenVPN (client) in Linux containers}}<br />
{{Related|OpenVPN (server) in Linux containers}}<br />
{{Related|PeerGuardian Linux}}<br />
{{Related|systemd-nspawn}}<br />
{{Related articles end}}<br />
<br />
Linux Containers (LXC) is an operating-system-level virtualization method for running multiple isolated Linux systems (containers) on a single control host (LXC host). It does not provide a virtual machine, but rather provides a virtual environment that has its own CPU, memory, block I/O, network, etc. space and the resource control mechanism. This is provided by [[Wikipedia:Linux namespaces|namespaces]] and [[cgroups]] features in Linux kernel on LXC host. It is similar to a chroot, but offers much more isolation.<br />
<br />
Alternatives for using containers are [[systemd-nspawn]], [[docker]] or {{Pkg|rkt}}.<br />
<br />
== Privileged containers or unprivileged containers ==<br />
LXCs can be setup to run in either ''privileged'' or ''unprivileged'' configurations.<br />
<br />
In general, running an ''unprivileged'' container is [https://www.stgraber.org/2014/01/17/lxc-1-0-unprivileged-containers considered safer] than running a ''privileged'' container since ''unprivileged'' containers have an increased degree of isolation by virtue of their design. Key to this is the mapping of the root UID in the container to a non-root UID on the host which makes it more difficult for a hack within the container to lead to consequences on host system. In other words, if an attacker manages to escape the container, he or she should find themselves with no rights on the host.<br />
<br />
The Arch packages currently provide out-of-the-box support for ''privileged'' containers. ''Unprivileged'' containers are only available for the system administrator without additional kernel configuration. This is due to the current Arch {{pkg|linux}} kernel shipping with user namespaces disabled for normal users. This article contains information for users to run either type of container, but additional setup is required to use ''unprivileged'' containers.<br />
<br />
=== An example to illustrate unprivileged containers ===<br />
<br />
To illustrate the power of UID mapping, consider the output below from a running, ''unprivileged'' container. Therein, we see the containerized processes owned by the containerized root user in the output of {{ic|ps}}:<br />
<br />
[root@unprivileged_container /]# ps -ef | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
root 1 0 0 17:49 ? 00:00:00 /sbin/init<br />
root 14 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
dbus 25 1 0 17:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
systemd+ 26 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-networkd<br />
<br />
On the host however, those containerized root processes are running as the mapped user (ID>100000) on the host, not as the root user on the host:<br />
[root@host /]# lxc-info -Ssip --name sandbox<br />
State: RUNNING<br />
PID: 26204<br />
CPU use: 10.51 seconds<br />
BlkIO use: 244.00 KiB<br />
Memory use: 13.09 MiB<br />
KMem use: 7.21 MiB<br />
<br />
[root@host /]# ps -ef | grep 26204 | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
100000 26204 26200 0 12:49 ? 00:00:00 /sbin/init<br />
100000 26256 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
100081 26282 26204 0 12:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
100000 26284 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-logind<br />
<br />
== Setup ==<br />
=== Required software ===<br />
Installing {{Pkg|lxc}} and {{Pkg|arch-install-scripts}} will allow the host system to run privileged lxcs.<br />
<br />
==== Enable support to run unprivileged contains (optional) ====<br />
Users wishing to run ''unprivileged'' containers need to complete several additional setup steps.<br />
<br />
Firstly, a kernel is required that has support for '''User Namespaces'''. However, due to more general security concerns, the default Arch kernel does ship with User Namespaces enabled only for the ''root'' user. You have multiple options to use a kernel with {{ic|CONFIG_USER_NS}} and thereby create ''unprivileged'' containers:<br />
<br />
* Use {{Pkg|linux}} (v4.14.5 or later) or {{Pkg|linux-hardened}} and start your unprivileged containers only as ''root''<br />
* Use {{Pkg|linux}} (v4.14.5 or later) or {{Pkg|linux-hardened}} and enable the ''sysctl'' setting {{ic|kernel.unprivileged_userns_clone}} to allow normal users to run unprivileged containers. This can be done for the current session with {{ic|<nowiki>sysctl kernel.unprivileged_userns_clone=1</nowiki>}} and can be made permanent with {{man|5|sysctl.d}}<br />
* Install the {{AUR|linux-userns}} or {{AUR|linux-lts-userns}} packages from the [[AUR]]. Both are compiled with {{ic|CONFIG_USER_NS}}, the latter being the Long-Term Support version. <br />
* Compile and install your own custom kernel with {{ic|CONFIG_USER_NS}} enabled. See [[Kernels/Arch Build System]] for more information on compiling a custom kernel.<br />
<br />
<br />
Secondly, modify {{ic|/etc/lxc/default.conf}} to contain the following lines:<br />
lxc.idmap = u 0 100000 65536<br />
lxc.idmap = g 0 100000 65536<br />
<br />
Finally, create both {{ic|/etc/subuid}} and {{ic|/etc/subgid}} to contain the mapping to the containerized uid/gid pairs for each user who shall be able to run the containers. The example below is simply for the root user (and systemd system unit):<br />
<br />
{{hc|/etc/subuid|<nowiki><br />
root:100000:65536<br />
</nowiki>}}<br />
<br />
{{hc|/etc/subgid|<nowiki><br />
root:100000:65536<br />
</nowiki>}}<br />
<br />
=== Host network configuration ===<br />
LXCs support different virtual network types and devices (see [https://linuxcontainers.org/lxc/manpages//man5/lxc.container.conf.5.html lxc.container.conf(5)]). A bridge device on the host is required for most types of virtual networking.<br />
<br />
LXC comes with its own NAT Bridge (lxcbr0).<br />
{{Note|A NAT bridge is a standalone bridge with a private network that is not bridged to the host eth0 or a physical network. It exists as a private subnet in the host.}}<br />
{{Tip|This is quite useful when WIFI is the only option. There have been various attempts of creating Bridges on WIFI without much success.}}<br />
<br />
To use LXC's NAT Bridge you need to create its configuration file:<br />
<br />
{{hc|/etc/default/lxc-net|<br />
2=# Leave USE_LXC_BRIDGE as "true" if you want to use lxcbr0 for your<br />
# containers. Set to "false" if you'll use virbr0 or another existing<br />
# bridge, or mavlan to your host's NIC.<br />
USE_LXC_BRIDGE="true"<br />
<br />
# If you change the LXC_BRIDGE to something other than lxcbr0, then<br />
# you will also need to update your /etc/lxc/default.conf as well as the<br />
# configuration (/var/lib/lxc/<container>/config) for any containers<br />
# already created using the default config to reflect the new bridge<br />
# name.<br />
# If you have the dnsmasq daemon installed, you'll also have to update<br />
# /etc/dnsmasq.d/lxc and restart the system wide dnsmasq daemon.<br />
LXC_BRIDGE="lxcbr0"<br />
LXC_ADDR="10.0.3.1"<br />
LXC_NETMASK="255.255.255.0"<br />
LXC_NETWORK="10.0.3.0/24"<br />
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"<br />
LXC_DHCP_MAX="253"<br />
# Uncomment the next line if you'd like to use a conf-file for the lxcbr0<br />
# dnsmasq. For instance, you can use 'dhcp-host=mail1,10.0.3.100' to have<br />
# container 'mail1' always get ip address 10.0.3.100.<br />
#LXC_DHCP_CONFILE=/etc/lxc/dnsmasq.conf<br />
<br />
# Uncomment the next line if you want lxcbr0's dnsmasq to resolve the .lxc<br />
# domain. You can then add "server=/lxc/10.0.3.1' (or your actual $LXC_ADDR)<br />
# to your system dnsmasq configuration file (normally /etc/dnsmasq.conf,<br />
# or /etc/NetworkManager/dnsmasq.d/lxc.conf on systems that use NetworkManager).<br />
# Once these changes are made, restart the lxc-net and network-manager services.<br />
# 'container1.lxc' will then resolve on your host.<br />
#LXC_DOMAIN="lxc"<br />
}}<br />
<br />
{{Tip| Make sure the bridges ip-range does not interfere with your local network.}}<br />
<br />
Then we need to modify the LXC container template so our containers use our bridge:<br />
<br />
{{hc|/etc/lxc/default.conf|<br />
2=lxc.net.0.type = veth<br />
lxc.net.0.link = lxcbr0<br />
lxc.net.0.flags = up<br />
lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx<br />
}}<br />
<br />
You also need to install [[Dnsmasq]] which is a dependency for lxcbr0.<br />
<br />
pacman -S dnsmasq<br />
<br />
Then we can start the bridge:<br />
<br />
systemctl start lxc-net<br />
<br />
If you want the bridge to start at boot-time<br />
<br />
systemctl enable lxc-net<br />
<br />
<br />
For further information including Host bridges users are referred to the [[Network bridge]] article.<br />
<br />
=== Container creation ===<br />
For ''privileged'' containers, simply select a template from {{ic|/usr/share/lxc/templates}} that matches the target distro to containerize. Users wishing to containerize non-Arch distros will need additional packages on the host depending on the target distro:<br />
* Debian-based: {{Pkg|debootstrap}}<br />
* Fedora-based: {{AUR|yum}}<br />
<br />
Run {{ic|lxc-create}} to create the container, which installs the root filesystem of the LXC to {{ic|/var/lib/lxc/CONTAINER_NAME/rootfs}} by default. Example creating an Arch Linux LXC named "playtime":<br />
# lxc-create -n playtime -t /usr/share/lxc/templates/lxc-archlinux<br />
<br />
Users wishing to run ''unprivileged'' containers should use the -t download directive and select from the images that are displayed. For example:<br />
# lxc-create -n playtime -t download<br />
<br />
Alternatively, create a ''privileged'' container, and see: [[#Converting a privileged container to an unprivileged container]].<br />
<br />
{{Tip|Users may optionally install {{Pkg|haveged}} and [[start]] {{ic|haveged.service}} to avoid a perceived hang during the setup process while waiting for system entropy to be seeded. Without it, the generation of private/GPG keys can add a lengthy wait to the process.}}<br />
<br />
{{Tip|Users of [[Btrfs]] can append {{ic|-B btrfs}} to create a Btrfs subvolume for storing containerized rootfs. This comes in handy if cloning containers with the help of {{ic|lxc-clone}} command. [[ZFS]] users may use {{ic|-B zfs}}, correspondingly.}}<br />
<br />
=== Container configuration ===<br />
The examples below can be used with ''privileged'' and ''unprivileged'' containers alike. Note that for unprivileged containers, additional lines will be present by default which are not shown in the examples, including the {{ic|1=lxc.idmap = u 0 100000 65536}} and the {{ic|1=lxc.idmap = g 0 100000 65536}} values optionally defined in the [[#Enable support to run unprivileged contains (optional)]] section.<br />
<br />
==== Basic config with networking ====<br />
{{Note|With the release of lxc-1:2.1.0-1, many of the configuration options have changed. Existing containers need to be updated; users are directed to the table of these changes in the [https://discuss.linuxcontainers.org/t/lxc-2-1-has-been-released/487 v2.1 release notes].}}<br />
<br />
System resources to be virtualized/isolated when a process is using the container are defined in {{ic|/var/lib/lxc/CONTAINER_NAME/config}}. By default, the creation process will make a minimum setup without networking support. Below is an example config with networking:<br />
<br />
{{hc|/var/lib/lxc/playtime/config|<nowiki><br />
# Template used to create this container: /usr/share/lxc/templates/lxc-archlinux<br />
# Parameters passed to the template:<br />
# For additional config options, please look at lxc.container.conf(5)<br />
<br />
## default values<br />
lxc.rootfs.path = /var/lib/lxc/playtime/rootfs<br />
lxc.uts.name = playtime<br />
lxc.arch = x86_64<br />
lxc.include = /usr/share/lxc/config/archlinux.common.conf<br />
<br />
## network<br />
lxc.net.0.type = veth<br />
lxc.net.0.link = br0<br />
lxc.net.0.flags = up<br />
lxc.net.0.name = eth0<br />
lxc.net.0.hwaddr = ee:ec:fa:e9:56:7d<br />
# uncomment the next two lines if static IP addresses are needed<br />
# leaving these commented will imply DHCP networking<br />
#<br />
#lxc.net.0.ipv4.address = 192.168.0.3/24<br />
#lxc.net.0.ipv4.gateway = 192.168.0.1<br />
</nowiki>}}<br />
<br />
{{Note|The lxc.network.hwaddr entry is optional and if skipped, a random MAC address will be created automatically. It can be advantageous to define a MAC address for the container to allow the DHCP server to always assign the same IP to the container's NIC (beyond the scope of this article but worth mentioning).}}<br />
<br />
==== Mounts within the container ====<br />
For ''privileged'' containers, one can select directories on the host to bind mount to the container. This can be advantageous for example if the same architecture is being containerize and one wants to share pacman packages between the host and container. Another example could be shared directories. The syntax is simple:<br />
<br />
lxc.mount.entry = /var/cache/pacman/pkg var/cache/pacman/pkg none bind 0 0<br />
<br />
{{Note|This will not work without filesystem permission modifications on the host if using ''unprivileged'' containers.}}<br />
==== Xorg program considerations (optional) ====<br />
In order to run programs on the host's display, some bind mounts need to be defined so that the containerized programs can access the host's resources. Add the following section to {{ic|/var/lib/lxc/playtime/config}}:<br />
## for xorg<br />
lxc.mount.entry = /dev/dri dev/dri none bind,optional,create=dir<br />
lxc.mount.entry = /dev/snd dev/snd none bind,optional,create=dir<br />
lxc.mount.entry = /tmp/.X11-unix tmp/.X11-unix none bind,optional,create=dir,ro<br />
lxc.mount.entry = /dev/video0 dev/video0 none bind,optional,create=file<br />
<br />
If you still get a permission denied error in your LXC guest, then you may need to call {{ic|xhost +}} in your host to allow the guest to connect to the host's display server. Take note of the security concerns of opening up your display server by doing this.<br />
<br />
{{Note|This will not work if using ''unprivileged'' containers.}}<br />
<br />
==== OpenVPN considerations ====<br />
<br />
Users wishing to run [[OpenVPN]] within the container are direct to either [[OpenVPN (client) in Linux containers]] and/or [[OpenVPN (server) in Linux containers]].<br />
<br />
== Managing containers ==<br />
=== Basic usage ===<br />
To list all installed LXC containers:<br />
# lxc-ls -f<br />
<br />
Systemd can be used to [[start]] and to [[stop]] LXCs via {{ic|lxc@CONTAINER_NAME.service}}. [[Enable]] {{ic|lxc@CONTAINER_NAME.service}} to have it start when the host system boots.<br />
<br />
Users can also start/stop LXCs without systemd.<br />
Start a container:<br />
# lxc-start -n CONTAINER_NAME<br />
<br />
Stop a container:<br />
# lxc-stop -n CONTAINER_NAME<br />
<br />
To login into a container:<br />
# lxc-console -n CONTAINER_NAME<br />
<br />
If when login you get pts/0 and lxc/tty1 use:<br />
# lxc-console -n CONTAINER_NAME -t 0<br />
<br />
Once logged, treat the container like any other linux system, set the root password, create users, install packages, etc.<br />
<br />
To attach to a container:<br />
# lxc-attach -n CONTAINER_NAME<br />
<br />
It works nearly the same as lxc-console, but you are automatically accessing root prompt inside the container, bypassing login.<br />
<br />
=== Advanced usage ===<br />
<br />
==== LXC clones ====<br />
Users with a need to run multiple containers can simplify administrative overhead (user management, system updates, etc.) by using snapshots. The strategy is to setup and keep up-to-date a single base container, then, as needed, clone (snapshot) it. The power in this strategy is that the disk space and system overhead are truly minimized since the snapshots use an overlayfs mount to only write out to disk, only the differences in data. The base system is read-only but changes to it in the snapshots are allowed via the overlayfs.<br />
<br />
For example, setup a container as outlined above. We will call it "base" for the purposes of this guide. Now create 2 snapshots of "base" which we will call "snap1" and "snap2" with these commands:<br />
# lxc-copy -n base -N snap1 -B overlayfs -s<br />
# lxc-copy -n base -N snap2 -B overlayfs -s<br />
<br />
{{Note|If a static IP was defined for the "base" lxc, that will need to manually changed in the config for "snap1" and for "snap2" before starting them. If the process is to be automated, a script using sed can do this automatically although this is beyond the scope of this wiki section.}}<br />
<br />
The snapshots can be started/stopped like any other container. Users can optionally destroy the snapshots and all new data therein with the following command. Note that the underlying "base" lxc is untouched:<br />
# lxc-destroy -n snap1 -f<br />
<br />
Systemd units and wrapper scripts to manage snapshots for [[pi-hole]] and [[OpenVPN]] are available to automate the process in {{AUR|lxc-snapshots}}.<br />
<br />
=== Converting a privileged container to an unprivileged container ===<br />
Once the system has been configured to use unprivileged containers (see, [[#Enable support to run unprivileged contains (optional)]]), {{AUR|nsexec-bzr}} contains a utility called {{ic|uidmapshift}} which is able to convert an existing ''privileged'' container to an ''unprivileged'' container to avoid a total rebuild of the image.<br />
<br />
{{Warning|<br />
* It is recommended to backup the existing image before using this utility!<br />
* This utility will not shift UIDs and GIDs in [[ACL]], you will need to shift them on your own.<br />
}}<br />
<br />
Invoke the utility to convert over like so:<br />
# uidmapshift -b /var/lib/lxc/foo 0 100000 65536<br />
<br />
Additional options are available simply by calling {{ic|uidmapshift}} without any arguments.<br />
<br />
== Running Xorg programs ==<br />
Either attach to or [[SSH]] into the target container and prefix the call to the program with the DISPLAY ID of the host's X session. For most simple setups, the display is always 0.<br />
<br />
An example of running Firefox from the container in the host's display:<br />
$ DISPLAY=:0 firefox<br />
<br />
Alternatively, to avoid directly attaching to or connecting to the container, the following can be used on the host to automate the process:<br />
# lxc-attach -n playtime --clear-env -- sudo -u YOURUSER env DISPLAY=:0 firefox<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root login fails ===<br />
<br />
If you get the following error when you try to login using lxc-console:<br />
<br />
login: root<br />
Login incorrect<br />
<br />
And the container's {{ic|journalctl}} shows:<br />
<br />
pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !<br />
<br />
Add {{ic|pts/0}} to the list of terminal names in {{ic|/etc/securetty}} on the '''container''' filesystem, see [http://unix.stackexchange.com/questions/41840/effect-of-entries-in-etc-securetty/41939#41939]. You can also opt to delete {{ic|/etc/securetty}} on the '''container''' to allow always root to login, see [https://github.com/systemd/systemd/issues/852].<br />
<br />
Alternatively, create a new user in lxc-attach and use it for logging in to the system, then switch to root.<br />
<br />
# lxc-attach -n playtime<br />
[root@playtime]# useradd -m -Gwheel newuser<br />
[root@playtime]# passwd newuser<br />
[root@playtime]# passwd root<br />
[root@playtime]# exit<br />
# lxc-console -n playtime<br />
[newuser@playtime]$ su<br />
<br />
===No network-connection with veth in container config===<br />
<br />
If you cannot access your LAN or WAN with a networking interface configured as '''veth''' and setup through {{ic|/etc/lxc/''containername''/config}}.<br />
If the virtual interface gets the ip assigned and should be connected to the network correctly.<br />
ip addr show veth0 <br />
inet 192.168.1.111/24<br />
You may disable all the relevant static ip formulas and try setting the ip through the booted container-os like you would normaly do.<br />
<br />
Example {{ic|''container''/config}}<br />
<br />
...<br />
lxc.net.0.type = veth<br />
lxc.net.0.name = veth0<br />
lxc.net.0.flags = up<br />
lxc.net.0.link = {{ic|bridge}}<br />
...<br />
<br />
And then assign your IP through your preferred method '''inside''' the container, see also [[Network configuration#Configure the IP address]]{{Broken section link}}.<br />
<br />
== See also ==<br />
<br />
* [https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/ LXC 1.0 Blog Post Series]<br />
* [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/ LXC@developerWorks]<br />
* [http://docs.docker.io/en/latest/installation/archlinux/ Docker Installation on ArchLinux]<br />
* [http://l3net.wordpress.com/tag/lxc/ LXC articles on l3net]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Linux_Containers&diff=503254Linux Containers2017-12-19T13:56:57Z<p>Progandy: Document userns support in the core/linux package and adapt unprivileged container setup from LXD</p>
<hr />
<div>[[Category:Security]]<br />
[[Category:Virtualization]]<br />
[[ja:Linux Containers]]<br />
[[pt:Linux Containers]]<br />
{{Related articles start}}<br />
{{Related|AirVPN}}<br />
{{Related|ABS}}<br />
{{Related|Cgroups}}<br />
{{Related|Docker}}<br />
{{Related|LXD}}<br />
{{Related|OpenVPN}}<br />
{{Related|OpenVPN (client) in Linux containers}}<br />
{{Related|OpenVPN (server) in Linux containers}}<br />
{{Related|PeerGuardian Linux}}<br />
{{Related|systemd-nspawn}}<br />
{{Related articles end}}<br />
<br />
Linux Containers (LXC) is an operating-system-level virtualization method for running multiple isolated Linux systems (containers) on a single control host (LXC host). It does not provide a virtual machine, but rather provides a virtual environment that has its own CPU, memory, block I/O, network, etc. space and the resource control mechanism. This is provided by [[Wikipedia:Linux namespaces|namespaces]] and [[cgroups]] features in Linux kernel on LXC host. It is similar to a chroot, but offers much more isolation.<br />
<br />
Alternatives for using containers are [[systemd-nspawn]], [[docker]] or {{Pkg|rkt}}.<br />
<br />
== Privileged containers or unprivileged containers ==<br />
LXCs can be setup to run in either ''privileged'' or ''unprivileged'' configurations.<br />
<br />
In general, running an ''unprivileged'' container is [https://www.stgraber.org/2014/01/17/lxc-1-0-unprivileged-containers considered safer] than running a ''privileged'' container since ''unprivileged'' containers have an increased degree of isolation by virtue of their design. Key to this is the mapping of the root UID in the container to a non-root UID on the host which makes it more difficult for a hack within the container to lead to consequences on host system. In other words, if an attacker manages to escape the container, he or she should find themselves with no rights on the host.<br />
<br />
The Arch packages currently provide out-of-the-box support for ''privileged'' containers. ''Unprivileged'' containers are only available for the system administrator without additional kernel configuration. This is due to the current Arch {{pkg|linux}} kernel shipping with user namespaces disabled for normal users. This article contains information for users to run either type of container, but additional setup is required to use ''unprivileged'' containers.<br />
<br />
=== An example to illustrate unprivileged containers ===<br />
<br />
To illustrate the power of UID mapping, consider the output below from a running, ''unprivileged'' container. Therein, we see the containerized processes owned by the containerized root user in the output of {{ic|ps}}:<br />
<br />
[root@unprivileged_container /]# ps -ef | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
root 1 0 0 17:49 ? 00:00:00 /sbin/init<br />
root 14 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
dbus 25 1 0 17:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
systemd+ 26 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-networkd<br />
<br />
On the host however, those containerized root processes are running as the mapped user (ID>100000) on the host, not as the root user on the host:<br />
[root@host /]# lxc-info -Ssip --name sandbox<br />
State: RUNNING<br />
PID: 26204<br />
CPU use: 10.51 seconds<br />
BlkIO use: 244.00 KiB<br />
Memory use: 13.09 MiB<br />
KMem use: 7.21 MiB<br />
<br />
[root@host /]# ps -ef | grep 26204 | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
100000 26204 26200 0 12:49 ? 00:00:00 /sbin/init<br />
100000 26256 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
100081 26282 26204 0 12:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
100000 26284 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-logind<br />
<br />
== Setup ==<br />
=== Required software ===<br />
Installing {{Pkg|lxc}} and {{Pkg|arch-install-scripts}} will allow the host system to run privileged lxcs.<br />
<br />
==== Enable support to run unprivileged contains (optional) ====<br />
Users wishing to run ''unprivileged'' containers need to complete several additional setup steps.<br />
<br />
Firstly, a kernel is required that has support for '''User Namespaces'''. However, due to more general security concerns, the default Arch kernel does ship with User Namespaces enabled only for the ''root'' user. You have multiple options to use a kernel with {{ic|CONFIG_USER_NS}} and thereby create ''unprivileged'' containers:<br />
<br />
* Use {{Pkg|linux}} (v4.14.5 or later) and start your unprivileged containers only as ''root''<br />
* Use {{Pkg|linux}} (v4.14.5 or later) and enable the ''sysctl'' setting {{ic|kernel.unprivileged_userns_clone}} to allow normal users to run unprivileged containers. This can be done for the current session with {{ic|<nowiki>sysctl kernel.unprivileged_userns_clone=1</nowiki>}} and can be made permanent with {{man|5|sysctl.d}}<br />
* Install the {{Pkg|linux-hardened}} kernel package along-side the default {{Pkg|linux}} kernel. When you wish to run unprivileged LXD containers, boot with {{Pkg|linux-hardened}} by selecting it in the bootloader. {{Pkg|linux-hardened}} is compiled with {{ic|CONFIG_USER_NS}}. Otherwise, run with {{Pkg|linux}} as normal.<br />
* Install the {{AUR|linux-userns}} or {{AUR|linux-lts-userns}} packages from the [[AUR]]. Both are compiled with {{ic|CONFIG_USER_NS}}, the latter being the Long-Term Support version. <br />
* Compile and install your own custom kernel with {{ic|CONFIG_USER_NS}} enabled. See, [[Kernels/Arch_Build_System]] for more on compiling a custom kernel.<br />
<br />
<br />
Secondly, modify {{ic|/etc/lxc/default.conf}} to contain the following lines:<br />
lxc.idmap = u 0 100000 65536<br />
lxc.idmap = g 0 100000 65536<br />
<br />
Finally, create both {{ic|/etc/subuid}} and {{ic|/etc/subgid}} to contain the mapping to the containerized uid/gid pairs for each user who shall be able to run the containers. The example below is simply for the root user (and systemd system unit):<br />
<br />
{{hc|/etc/subuid|<nowiki><br />
root:100000:65536<br />
</nowiki>}}<br />
<br />
{{hc|/etc/subgid|<nowiki><br />
root:100000:65536<br />
</nowiki>}}<br />
<br />
=== Host network configuration ===<br />
LXCs support different virtual network types and devices (see [https://linuxcontainers.org/lxc/manpages//man5/lxc.container.conf.5.html lxc.container.conf(5)]). A bridge device on the host is required for most types of virtual networking.<br />
<br />
LXC comes with its own NAT Bridge (lxcbr0).<br />
{{Note|A NAT bridge is a standalone bridge with a private network that is not bridged to the host eth0 or a physical network. It exists as a private subnet in the host.}}<br />
{{Tip|This is quite useful when WIFI is the only option. There have been various attempts of creating Bridges on WIFI without much success.}}<br />
<br />
To use LXC's NAT Bridge you need to create its configuration file:<br />
<br />
{{hc|/etc/default/lxc-net|<br />
2=# Leave USE_LXC_BRIDGE as "true" if you want to use lxcbr0 for your<br />
# containers. Set to "false" if you'll use virbr0 or another existing<br />
# bridge, or mavlan to your host's NIC.<br />
USE_LXC_BRIDGE="true"<br />
<br />
# If you change the LXC_BRIDGE to something other than lxcbr0, then<br />
# you will also need to update your /etc/lxc/default.conf as well as the<br />
# configuration (/var/lib/lxc/<container>/config) for any containers<br />
# already created using the default config to reflect the new bridge<br />
# name.<br />
# If you have the dnsmasq daemon installed, you'll also have to update<br />
# /etc/dnsmasq.d/lxc and restart the system wide dnsmasq daemon.<br />
LXC_BRIDGE="lxcbr0"<br />
LXC_ADDR="10.0.3.1"<br />
LXC_NETMASK="255.255.255.0"<br />
LXC_NETWORK="10.0.3.0/24"<br />
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"<br />
LXC_DHCP_MAX="253"<br />
# Uncomment the next line if you'd like to use a conf-file for the lxcbr0<br />
# dnsmasq. For instance, you can use 'dhcp-host=mail1,10.0.3.100' to have<br />
# container 'mail1' always get ip address 10.0.3.100.<br />
#LXC_DHCP_CONFILE=/etc/lxc/dnsmasq.conf<br />
<br />
# Uncomment the next line if you want lxcbr0's dnsmasq to resolve the .lxc<br />
# domain. You can then add "server=/lxc/10.0.3.1' (or your actual $LXC_ADDR)<br />
# to your system dnsmasq configuration file (normally /etc/dnsmasq.conf,<br />
# or /etc/NetworkManager/dnsmasq.d/lxc.conf on systems that use NetworkManager).<br />
# Once these changes are made, restart the lxc-net and network-manager services.<br />
# 'container1.lxc' will then resolve on your host.<br />
#LXC_DOMAIN="lxc"<br />
}}<br />
<br />
{{Tip| Make sure the bridges ip-range does not interfere with your local network.}}<br />
<br />
Then we need to modify the LXC container template so our containers use our bridge:<br />
<br />
{{hc|/etc/lxc/default.conf|<br />
2=lxc.net.0.type = veth<br />
lxc.net.0.link = lxcbr0<br />
lxc.net.0.flags = up<br />
lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx<br />
}}<br />
<br />
You also need to install [[Dnsmasq]] which is a dependency for lxcbr0.<br />
<br />
pacman -S dnsmasq<br />
<br />
Then we can start the bridge:<br />
<br />
systemctl start lxc-net<br />
<br />
If you want the bridge to start at boot-time<br />
<br />
systemctl enable lxc-net<br />
<br />
<br />
For further information including Host bridges users are referred to the [[Network bridge]] article.<br />
<br />
=== Container creation ===<br />
For ''privileged'' containers, simply select a template from {{ic|/usr/share/lxc/templates}} that matches the target distro to containerize. Users wishing to containerize non-Arch distros will need additional packages on the host depending on the target distro:<br />
* Debian-based: {{Pkg|debootstrap}}<br />
* Fedora-based: {{AUR|yum}}<br />
<br />
Run {{ic|lxc-create}} to create the container, which installs the root filesystem of the LXC to {{ic|/var/lib/lxc/CONTAINER_NAME/rootfs}} by default. Example creating an Arch Linux LXC named "playtime":<br />
# lxc-create -n playtime -t /usr/share/lxc/templates/lxc-archlinux<br />
<br />
Users wishing to run ''unprivileged'' containers should use the -t download directive and select from the images that are displayed. For example:<br />
# lxc-create -n playtime -t download<br />
<br />
Alternatively, create a ''privileged'' container, and see: [[#Converting a privileged container to an unprivileged container]].<br />
<br />
{{Tip|Users may optionally install {{Pkg|haveged}} and [[start]] {{ic|haveged.service}} to avoid a perceived hang during the setup process while waiting for system entropy to be seeded. Without it, the generation of private/GPG keys can add a lengthy wait to the process.}}<br />
<br />
{{Tip|Users of [[Btrfs]] can append {{ic|-B btrfs}} to create a Btrfs subvolume for storing containerized rootfs. This comes in handy if cloning containers with the help of {{ic|lxc-clone}} command. [[ZFS]] users may use {{ic|-B zfs}}, correspondingly.}}<br />
<br />
=== Container configuration ===<br />
The examples below can be used with ''privileged'' and ''unprivileged'' containers alike. Note that for unprivileged containers, additional lines will be present by default which are not shown in the examples, including the {{ic|1=lxc.idmap = u 0 100000 65536}} and the {{ic|1=lxc.idmap = g 0 100000 65536}} values optionally defined in the [[#Enable support to run unprivileged contains (optional)]] section.<br />
<br />
==== Basic config with networking ====<br />
{{Note|With the release of lxc-1:2.1.0-1, many of the configuration options have changed. Existing containers need to be updated; users are directed to the table of these changes in the [https://discuss.linuxcontainers.org/t/lxc-2-1-has-been-released/487 v2.1 release notes].}}<br />
<br />
System resources to be virtualized/isolated when a process is using the container are defined in {{ic|/var/lib/lxc/CONTAINER_NAME/config}}. By default, the creation process will make a minimum setup without networking support. Below is an example config with networking:<br />
<br />
{{hc|/var/lib/lxc/playtime/config|<nowiki><br />
# Template used to create this container: /usr/share/lxc/templates/lxc-archlinux<br />
# Parameters passed to the template:<br />
# For additional config options, please look at lxc.container.conf(5)<br />
<br />
## default values<br />
lxc.rootfs.path = /var/lib/lxc/playtime/rootfs<br />
lxc.uts.name = playtime<br />
lxc.arch = x86_64<br />
lxc.include = /usr/share/lxc/config/archlinux.common.conf<br />
<br />
## network<br />
lxc.net.0.type = veth<br />
lxc.net.0.link = br0<br />
lxc.net.0.flags = up<br />
lxc.net.0.name = eth0<br />
lxc.net.0.hwaddr = ee:ec:fa:e9:56:7d<br />
# uncomment the next two lines if static IP addresses are needed<br />
# leaving these commented will imply DHCP networking<br />
#<br />
#lxc.net.0.ipv4.address = 192.168.0.3/24<br />
#lxc.net.0.ipv4.gateway = 192.168.0.1<br />
</nowiki>}}<br />
<br />
{{Note|The lxc.network.hwaddr entry is optional and if skipped, a random MAC address will be created automatically. It can be advantageous to define a MAC address for the container to allow the DHCP server to always assign the same IP to the container's NIC (beyond the scope of this article but worth mentioning).}}<br />
<br />
==== Mounts within the container ====<br />
For ''privileged'' containers, one can select directories on the host to bind mount to the container. This can be advantageous for example if the same architecture is being containerize and one wants to share pacman packages between the host and container. Another example could be shared directories. The syntax is simple:<br />
<br />
lxc.mount.entry = /var/cache/pacman/pkg var/cache/pacman/pkg none bind 0 0<br />
<br />
{{Note|This will not work without filesystem permission modifications on the host if using ''unprivileged'' containers.}}<br />
==== Xorg program considerations (optional) ====<br />
In order to run programs on the host's display, some bind mounts need to be defined so that the containerized programs can access the host's resources. Add the following section to {{ic|/var/lib/lxc/playtime/config}}:<br />
## for xorg<br />
lxc.mount.entry = /dev/dri dev/dri none bind,optional,create=dir<br />
lxc.mount.entry = /dev/snd dev/snd none bind,optional,create=dir<br />
lxc.mount.entry = /tmp/.X11-unix tmp/.X11-unix none bind,optional,create=dir,ro<br />
lxc.mount.entry = /dev/video0 dev/video0 none bind,optional,create=file<br />
<br />
If you still get a permission denied error in your LXC guest, then you may need to call {{ic|xhost +}} in your host to allow the guest to connect to the host's display server. Take note of the security concerns of opening up your display server by doing this.<br />
<br />
{{Note|This will not work if using ''unprivileged'' containers.}}<br />
<br />
==== OpenVPN considerations ====<br />
<br />
Users wishing to run [[OpenVPN]] within the container are direct to either [[OpenVPN (client) in Linux containers]] and/or [[OpenVPN (server) in Linux containers]].<br />
<br />
== Managing containers ==<br />
=== Basic usage ===<br />
To list all installed LXC containers:<br />
# lxc-ls -f<br />
<br />
Systemd can be used to [[start]] and to [[stop]] LXCs via {{ic|lxc@CONTAINER_NAME.service}}. [[Enable]] {{ic|lxc@CONTAINER_NAME.service}} to have it start when the host system boots.<br />
<br />
Users can also start/stop LXCs without systemd.<br />
Start a container:<br />
# lxc-start -n CONTAINER_NAME<br />
<br />
Stop a container:<br />
# lxc-stop -n CONTAINER_NAME<br />
<br />
To login into a container:<br />
# lxc-console -n CONTAINER_NAME<br />
<br />
If when login you get pts/0 and lxc/tty1 use:<br />
# lxc-console -n CONTAINER_NAME -t 0<br />
<br />
Once logged, treat the container like any other linux system, set the root password, create users, install packages, etc.<br />
<br />
To attach to a container:<br />
# lxc-attach -n CONTAINER_NAME<br />
<br />
It works nearly the same as lxc-console, but you are automatically accessing root prompt inside the container, bypassing login.<br />
<br />
=== Advanced usage ===<br />
<br />
==== LXC clones ====<br />
Users with a need to run multiple containers can simplify administrative overhead (user management, system updates, etc.) by using snapshots. The strategy is to setup and keep up-to-date a single base container, then, as needed, clone (snapshot) it. The power in this strategy is that the disk space and system overhead are truly minimized since the snapshots use an overlayfs mount to only write out to disk, only the differences in data. The base system is read-only but changes to it in the snapshots are allowed via the overlayfs.<br />
<br />
For example, setup a container as outlined above. We will call it "base" for the purposes of this guide. Now create 2 snapshots of "base" which we will call "snap1" and "snap2" with these commands:<br />
# lxc-copy -n base -N snap1 -B overlayfs -s<br />
# lxc-copy -n base -N snap2 -B overlayfs -s<br />
<br />
{{Note|If a static IP was defined for the "base" lxc, that will need to manually changed in the config for "snap1" and for "snap2" before starting them. If the process is to be automated, a script using sed can do this automatically although this is beyond the scope of this wiki section.}}<br />
<br />
The snapshots can be started/stopped like any other container. Users can optionally destroy the snapshots and all new data therein with the following command. Note that the underlying "base" lxc is untouched:<br />
# lxc-destroy -n snap1 -f<br />
<br />
Systemd units and wrapper scripts to manage snapshots for [[pi-hole]] and [[OpenVPN]] are available to automate the process in {{AUR|lxc-snapshots}}.<br />
<br />
=== Converting a privileged container to an unprivileged container ===<br />
Once the system has been configured to use unprivileged containers (see, [[#Enable support to run unprivileged contains (optional)]]), {{AUR|nsexec-bzr}} contains a utility called {{ic|uidmapshift}} which is able to convert an existing ''privileged'' container to an ''unprivileged'' container to avoid a total rebuild of the image.<br />
<br />
{{Warning|<br />
* It is recommended to backup the existing image before using this utility!<br />
* This utility will not shift UIDs and GIDs in [[ACL]], you will need to shift them on your own.<br />
}}<br />
<br />
Invoke the utility to convert over like so:<br />
# uidmapshift -b /var/lib/lxc/foo 0 100000 65536<br />
<br />
Additional options are available simply by calling {{ic|uidmapshift}} without any arguments.<br />
<br />
== Running Xorg programs ==<br />
Either attach to or [[SSH]] into the target container and prefix the call to the program with the DISPLAY ID of the host's X session. For most simple setups, the display is always 0.<br />
<br />
An example of running Firefox from the container in the host's display:<br />
$ DISPLAY=:0 firefox<br />
<br />
Alternatively, to avoid directly attaching to or connecting to the container, the following can be used on the host to automate the process:<br />
# lxc-attach -n playtime --clear-env -- sudo -u YOURUSER env DISPLAY=:0 firefox<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root login fails ===<br />
<br />
If you get the following error when you try to login using lxc-console:<br />
<br />
login: root<br />
Login incorrect<br />
<br />
And the container's {{ic|journalctl}} shows:<br />
<br />
pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !<br />
<br />
Add {{ic|pts/0}} to the list of terminal names in {{ic|/etc/securetty}} on the '''container''' filesystem, see [http://unix.stackexchange.com/questions/41840/effect-of-entries-in-etc-securetty/41939#41939]. You can also opt to delete {{ic|/etc/securetty}} on the '''container''' to allow always root to login, see [https://github.com/systemd/systemd/issues/852].<br />
<br />
Alternatively, create a new user in lxc-attach and use it for logging in to the system, then switch to root.<br />
<br />
# lxc-attach -n playtime<br />
[root@playtime]# useradd -m -Gwheel newuser<br />
[root@playtime]# passwd newuser<br />
[root@playtime]# passwd root<br />
[root@playtime]# exit<br />
# lxc-console -n playtime<br />
[newuser@playtime]$ su<br />
<br />
===No network-connection with veth in container config===<br />
<br />
If you cannot access your LAN or WAN with a networking interface configured as '''veth''' and setup through {{ic|/etc/lxc/''containername''/config}}.<br />
If the virtual interface gets the ip assigned and should be connected to the network correctly.<br />
ip addr show veth0 <br />
inet 192.168.1.111/24<br />
You may disable all the relevant static ip formulas and try setting the ip through the booted container-os like you would normaly do.<br />
<br />
Example {{ic|''container''/config}}<br />
<br />
...<br />
lxc.net.0.type = veth<br />
lxc.net.0.name = veth0<br />
lxc.net.0.flags = up<br />
lxc.net.0.link = {{ic|bridge}}<br />
...<br />
<br />
And then assign your IP through your preferred method '''inside''' the container, see also [[Network configuration#Configure the IP address]]{{Broken section link}}.<br />
<br />
===Cannot start unprivileged LXC due to newuidmap execution failure===<br />
<br />
{{Accuracy|See {{Bug|52560}}: it is unclear what the "current version" is, if there is any upstream bug report and where the patch is.}}<br />
<br />
Unprivileged LXC cannot start with the current {{Pkg|shadow}} package, because the ''newuidmap'' and ''newgidmap'' binaries do not have the ''setuid'' bit.<br />
<br />
$ chmod u+s /usr/bin/newuidmap<br />
$ chmod u+s /usr/bin/newgidmap<br />
<br />
This is a bug in upstream but still not cherry-picked in official repository<br />
<br />
== See also ==<br />
<br />
* [https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/ LXC 1.0 Blog Post Series]<br />
* [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/ LXC@developerWorks]<br />
* [http://docs.docker.io/en/latest/installation/archlinux/ Docker Installation on ArchLinux]<br />
* [http://l3net.wordpress.com/tag/lxc/ LXC articles on l3net]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Linux_Containers&diff=503087Linux Containers2017-12-18T15:03:20Z<p>Progandy: Out of date, there are kernels with userns support in the repositories.</p>
<hr />
<div>[[Category:Security]]<br />
[[Category:Virtualization]]<br />
[[ja:Linux Containers]]<br />
[[pt:Linux Containers]]<br />
{{Related articles start}}<br />
{{Related|AirVPN}}<br />
{{Related|ABS}}<br />
{{Related|Cgroups}}<br />
{{Related|Docker}}<br />
{{Related|LXD}}<br />
{{Related|OpenVPN}}<br />
{{Related|OpenVPN (client) in Linux containers}}<br />
{{Related|OpenVPN (server) in Linux containers}}<br />
{{Related|PeerGuardian Linux}}<br />
{{Related|systemd-nspawn}}<br />
{{Related articles end}}<br />
<br />
{{Out of date|Unprivileged containers are now possible without a custom kernel. User namespaces are available in {{Pkg|linux-hardened}} and can be enabled in {{Pkg|linux}} since version 4.14.5 with the sysctl setting {{ic|kernel.unprivileged_userns_clone}} as well. }}<br />
<br />
Linux Containers (LXC) is an operating-system-level virtualization method for running multiple isolated Linux systems (containers) on a single control host (LXC host). It does not provide a virtual machine, but rather provides a virtual environment that has its own CPU, memory, block I/O, network, etc. space and the resource control mechanism. This is provided by [[Wikipedia:Linux namespaces|namespaces]] and [[cgroups]] features in Linux kernel on LXC host. It is similar to a chroot, but offers much more isolation.<br />
<br />
Alternatives for using containers are [[systemd-nspawn]], [[docker]] or {{Pkg|rkt}}.<br />
<br />
== Privileged containers or unprivileged containers ==<br />
LXCs can be setup to run in either ''privileged'' or ''unprivileged'' configurations.<br />
<br />
In general, running an ''unprivileged'' container is [https://www.stgraber.org/2014/01/17/lxc-1-0-unprivileged-containers considered safer] than running a ''privileged'' container since ''unprivileged'' containers have an increased degree of isolation by virtue of their design. Key to this is the mapping of the root UID in the container to a non-root UID on the host which makes it more difficult for a hack within the container to lead to consequences on host system. In other words, if an attacker manages to escape the container, he or she should find themselves with no rights on the host.<br />
<br />
The Arch packages currently provide out-of-the-box support for ''privileged'' containers only. This is due to the current Arch {{pkg|linux}} kernel '''not''' shipping with user namespaces configured. This article contains information for users to run either type of container, but additional setup is required to use ''unprivileged'' containers at this time.<br />
<br />
{{Note|A request has been filed to include user namespace support in the kernel: {{Bug|36969}}. However, the request has been closed because of the numerous security issues caused by user namespaces, which are frequently discovered.}}<br />
<br />
=== An example to illustrate unprivileged containers ===<br />
<br />
To illustrate the power of UID mapping, consider the output below from a running, ''unprivileged'' container. Therein, we see the containerized processes owned by the containerized root user in the output of {{ic|ps}}:<br />
<br />
[root@unprivileged_container /]# ps -ef | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
root 1 0 0 17:49 ? 00:00:00 /sbin/init<br />
root 14 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
dbus 25 1 0 17:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
systemd+ 26 1 0 17:49 ? 00:00:00 /usr/lib/systemd/systemd-networkd<br />
<br />
On the host however, those containerized root processes are running as the mapped user (ID>100000) on the host, not as the root user on the host:<br />
[root@host /]# lxc-info -Ssip --name sandbox<br />
State: RUNNING<br />
PID: 26204<br />
CPU use: 10.51 seconds<br />
BlkIO use: 244.00 KiB<br />
Memory use: 13.09 MiB<br />
KMem use: 7.21 MiB<br />
<br />
[root@host /]# ps -ef | grep 26204 | head -n 5<br />
UID PID PPID C STIME TTY TIME CMD<br />
100000 26204 26200 0 12:49 ? 00:00:00 /sbin/init<br />
100000 26256 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-journald<br />
100081 26282 26204 0 12:49 ? 00:00:00 /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation<br />
100000 26284 26204 0 12:49 ? 00:00:00 /usr/lib/systemd/systemd-logind<br />
<br />
== Setup ==<br />
=== Required software ===<br />
Installing {{Pkg|lxc}} and {{Pkg|arch-install-scripts}} will allow the host system to run privileged lxcs.<br />
<br />
==== Enable support to run unprivileged contains (optional) ====<br />
Users wishing to run ''unprivileged'' containers need to complete several additional setup steps.<br />
<br />
Firstly, a custom kernel is required that has support for User namespaces. This option is available under '''General setup>Namespaces support>User namespace''' from an nconfig, or by simply modifying the kernel [[PKGBUILD]] with the following line inserted prior to the "make prepare" line:<br />
sed -i -e 's/# CONFIG_USER_NS is not set/CONFIG_USER_NS=y/' ./.config<br />
<br />
See, [[ABS]] for more on compiling a custom kernel.<br />
<br />
Secondly, modify {{ic|/etc/lxc/default.conf}} to contain the following lines:<br />
lxc.idmap = u 0 100000 65536<br />
lxc.idmap = g 0 100000 65536<br />
<br />
Finally, create both {{ic|/etc/subuid}} and {{ic|/etc/subgid}} to contain the mapping to the containerized uid/gid pairs for each user who shall be able to run the containers. The example below is simply for the root user (and systemd system unit):<br />
<br />
{{hc|/etc/subuid|<nowiki><br />
root:100000:65536<br />
</nowiki>}}<br />
<br />
{{hc|/etc/subgid|<nowiki><br />
root:100000:65536<br />
</nowiki>}}<br />
<br />
=== Host network configuration ===<br />
LXCs support different virtual network types and devices (see [https://linuxcontainers.org/lxc/manpages//man5/lxc.container.conf.5.html lxc.container.conf(5)]). A bridge device on the host is required for most types of virtual networking.<br />
<br />
LXC comes with its own NAT Bridge (lxcbr0).<br />
{{Note|A NAT bridge is a standalone bridge with a private network that is not bridged to the host eth0 or a physical network. It exists as a private subnet in the host.}}<br />
{{Tip|This is quite useful when WIFI is the only option. There have been various attempts of creating Bridges on WIFI without much success.}}<br />
<br />
To use LXC's NAT Bridge you need to create its configuration file:<br />
<br />
{{hc|/etc/default/lxc-net|<br />
2=# Leave USE_LXC_BRIDGE as "true" if you want to use lxcbr0 for your<br />
# containers. Set to "false" if you'll use virbr0 or another existing<br />
# bridge, or mavlan to your host's NIC.<br />
USE_LXC_BRIDGE="true"<br />
<br />
# If you change the LXC_BRIDGE to something other than lxcbr0, then<br />
# you will also need to update your /etc/lxc/default.conf as well as the<br />
# configuration (/var/lib/lxc/<container>/config) for any containers<br />
# already created using the default config to reflect the new bridge<br />
# name.<br />
# If you have the dnsmasq daemon installed, you'll also have to update<br />
# /etc/dnsmasq.d/lxc and restart the system wide dnsmasq daemon.<br />
LXC_BRIDGE="lxcbr0"<br />
LXC_ADDR="10.0.3.1"<br />
LXC_NETMASK="255.255.255.0"<br />
LXC_NETWORK="10.0.3.0/24"<br />
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"<br />
LXC_DHCP_MAX="253"<br />
# Uncomment the next line if you'd like to use a conf-file for the lxcbr0<br />
# dnsmasq. For instance, you can use 'dhcp-host=mail1,10.0.3.100' to have<br />
# container 'mail1' always get ip address 10.0.3.100.<br />
#LXC_DHCP_CONFILE=/etc/lxc/dnsmasq.conf<br />
<br />
# Uncomment the next line if you want lxcbr0's dnsmasq to resolve the .lxc<br />
# domain. You can then add "server=/lxc/10.0.3.1' (or your actual $LXC_ADDR)<br />
# to your system dnsmasq configuration file (normally /etc/dnsmasq.conf,<br />
# or /etc/NetworkManager/dnsmasq.d/lxc.conf on systems that use NetworkManager).<br />
# Once these changes are made, restart the lxc-net and network-manager services.<br />
# 'container1.lxc' will then resolve on your host.<br />
#LXC_DOMAIN="lxc"<br />
}}<br />
<br />
{{Tip| Make sure the bridges ip-range does not interfere with your local network.}}<br />
<br />
Then we need to modify the LXC container template so our containers use our bridge:<br />
<br />
{{hc|/etc/lxc/default.conf|<br />
2=lxc.net.0.type = veth<br />
lxc.net.0.link = lxcbr0<br />
lxc.net.0.flags = up<br />
lxc.net.0.hwaddr = 00:16:3e:xx:xx:xx<br />
}}<br />
<br />
You also need to install [[Dnsmasq]] which is a dependency for lxcbr0.<br />
<br />
pacman -S dnsmasq<br />
<br />
Then we can start the bridge:<br />
<br />
systemctl start lxc-net<br />
<br />
If you want the bridge to start at boot-time<br />
<br />
systemctl enable lxc-net<br />
<br />
<br />
For further information including Host bridges users are referred to the [[Network bridge]] article.<br />
<br />
=== Container creation ===<br />
For ''privileged'' containers, simply select a template from {{ic|/usr/share/lxc/templates}} that matches the target distro to containerize. Users wishing to containerize non-Arch distros will need additional packages on the host depending on the target distro:<br />
* Debian-based: {{Pkg|debootstrap}}<br />
* Fedora-based: {{AUR|yum}}<br />
<br />
Run {{ic|lxc-create}} to create the container, which installs the root filesystem of the LXC to {{ic|/var/lib/lxc/CONTAINER_NAME/rootfs}} by default. Example creating an Arch Linux LXC named "playtime":<br />
# lxc-create -n playtime -t /usr/share/lxc/templates/lxc-archlinux<br />
<br />
Users wishing to run ''unprivileged'' containers should use the -t download directive and select from the images that are displayed. For example:<br />
# lxc-create -n playtime -t download<br />
<br />
Alternatively, create a ''privileged'' container, and see: [[#Converting a privileged container to an unprivileged container]].<br />
<br />
{{Tip|Users may optionally install {{Pkg|haveged}} and [[start]] {{ic|haveged.service}} to avoid a perceived hang during the setup process while waiting for system entropy to be seeded. Without it, the generation of private/GPG keys can add a lengthy wait to the process.}}<br />
<br />
{{Tip|Users of [[Btrfs]] can append {{ic|-B btrfs}} to create a Btrfs subvolume for storing containerized rootfs. This comes in handy if cloning containers with the help of {{ic|lxc-clone}} command. [[ZFS]] users may use {{ic|-B zfs}}, correspondingly.}}<br />
<br />
=== Container configuration ===<br />
The examples below can be used with ''privileged'' and ''unprivileged'' containers alike. Note that for unprivileged containers, additional lines will be present by default which are not shown in the examples, including the {{ic|1=lxc.idmap = u 0 100000 65536}} and the {{ic|1=lxc.idmap = g 0 100000 65536}} values optionally defined in the [[#Enable support to run unprivileged contains (optional)]] section.<br />
<br />
==== Basic config with networking ====<br />
{{Note|With the release of lxc-1:2.1.0-1, many of the configuration options have changed. Existing containers need to be updated; users are directed to the table of these changes in the [https://discuss.linuxcontainers.org/t/lxc-2-1-has-been-released/487 v2.1 release notes].}}<br />
<br />
System resources to be virtualized/isolated when a process is using the container are defined in {{ic|/var/lib/lxc/CONTAINER_NAME/config}}. By default, the creation process will make a minimum setup without networking support. Below is an example config with networking:<br />
<br />
{{hc|/var/lib/lxc/playtime/config|<nowiki><br />
# Template used to create this container: /usr/share/lxc/templates/lxc-archlinux<br />
# Parameters passed to the template:<br />
# For additional config options, please look at lxc.container.conf(5)<br />
<br />
## default values<br />
lxc.rootfs.path = /var/lib/lxc/playtime/rootfs<br />
lxc.uts.name = playtime<br />
lxc.arch = x86_64<br />
lxc.include = /usr/share/lxc/config/archlinux.common.conf<br />
<br />
## network<br />
lxc.net.0.type = veth<br />
lxc.net.0.link = br0<br />
lxc.net.0.flags = up<br />
lxc.net.0.name = eth0<br />
lxc.net.0.hwaddr = ee:ec:fa:e9:56:7d<br />
# uncomment the next two lines if static IP addresses are needed<br />
# leaving these commented will imply DHCP networking<br />
#<br />
#lxc.net.0.ipv4.address = 192.168.0.3/24<br />
#lxc.net.0.ipv4.gateway = 192.168.0.1<br />
</nowiki>}}<br />
<br />
{{Note|The lxc.network.hwaddr entry is optional and if skipped, a random MAC address will be created automatically. It can be advantageous to define a MAC address for the container to allow the DHCP server to always assign the same IP to the container's NIC (beyond the scope of this article but worth mentioning).}}<br />
<br />
==== Mounts within the container ====<br />
For ''privileged'' containers, one can select directories on the host to bind mount to the container. This can be advantageous for example if the same architecture is being containerize and one wants to share pacman packages between the host and container. Another example could be shared directories. The syntax is simple:<br />
<br />
lxc.mount.entry = /var/cache/pacman/pkg var/cache/pacman/pkg none bind 0 0<br />
<br />
{{Note|This will not work without filesystem permission modifications on the host if using ''unprivileged'' containers.}}<br />
==== Xorg program considerations (optional) ====<br />
In order to run programs on the host's display, some bind mounts need to be defined so that the containerized programs can access the host's resources. Add the following section to {{ic|/var/lib/lxc/playtime/config}}:<br />
## for xorg<br />
lxc.mount.entry = /dev/dri dev/dri none bind,optional,create=dir<br />
lxc.mount.entry = /dev/snd dev/snd none bind,optional,create=dir<br />
lxc.mount.entry = /tmp/.X11-unix tmp/.X11-unix none bind,optional,create=dir,ro<br />
lxc.mount.entry = /dev/video0 dev/video0 none bind,optional,create=file<br />
<br />
If you still get a permission denied error in your LXC guest, then you may need to call {{ic|xhost +}} in your host to allow the guest to connect to the host's display server. Take note of the security concerns of opening up your display server by doing this.<br />
<br />
{{Note|This will not work if using ''unprivileged'' containers.}}<br />
<br />
==== OpenVPN considerations ====<br />
<br />
Users wishing to run [[OpenVPN]] within the container are direct to either [[OpenVPN (client) in Linux containers]] and/or [[OpenVPN (server) in Linux containers]].<br />
<br />
== Managing containers ==<br />
=== Basic usage ===<br />
To list all installed LXC containers:<br />
# lxc-ls -f<br />
<br />
Systemd can be used to [[start]] and to [[stop]] LXCs via {{ic|lxc@CONTAINER_NAME.service}}. [[Enable]] {{ic|lxc@CONTAINER_NAME.service}} to have it start when the host system boots.<br />
<br />
Users can also start/stop LXCs without systemd.<br />
Start a container:<br />
# lxc-start -n CONTAINER_NAME<br />
<br />
Stop a container:<br />
# lxc-stop -n CONTAINER_NAME<br />
<br />
To login into a container:<br />
# lxc-console -n CONTAINER_NAME<br />
<br />
If when login you get pts/0 and lxc/tty1 use:<br />
# lxc-console -n CONTAINER_NAME -t 0<br />
<br />
Once logged, treat the container like any other linux system, set the root password, create users, install packages, etc.<br />
<br />
To attach to a container:<br />
# lxc-attach -n CONTAINER_NAME<br />
<br />
It works nearly the same as lxc-console, but you are automatically accessing root prompt inside the container, bypassing login.<br />
<br />
=== Advanced usage ===<br />
<br />
==== LXC clones ====<br />
Users with a need to run multiple containers can simplify administrative overhead (user management, system updates, etc.) by using snapshots. The strategy is to setup and keep up-to-date a single base container, then, as needed, clone (snapshot) it. The power in this strategy is that the disk space and system overhead are truly minimized since the snapshots use an overlayfs mount to only write out to disk, only the differences in data. The base system is read-only but changes to it in the snapshots are allowed via the overlayfs.<br />
<br />
For example, setup a container as outlined above. We will call it "base" for the purposes of this guide. Now create 2 snapshots of "base" which we will call "snap1" and "snap2" with these commands:<br />
# lxc-copy -n base -N snap1 -B overlayfs -s<br />
# lxc-copy -n base -N snap2 -B overlayfs -s<br />
<br />
{{Note|If a static IP was defined for the "base" lxc, that will need to manually changed in the config for "snap1" and for "snap2" before starting them. If the process is to be automated, a script using sed can do this automatically although this is beyond the scope of this wiki section.}}<br />
<br />
The snapshots can be started/stopped like any other container. Users can optionally destroy the snapshots and all new data therein with the following command. Note that the underlying "base" lxc is untouched:<br />
# lxc-destroy -n snap1 -f<br />
<br />
Systemd units and wrapper scripts to manage snapshots for [[pi-hole]] and [[OpenVPN]] are available to automate the process in {{AUR|lxc-snapshots}}.<br />
<br />
=== Converting a privileged container to an unprivileged container ===<br />
Once the system has been configured to use unprivileged containers (see, [[#Enable support to run unprivileged contains (optional)]]), {{AUR|nsexec-bzr}} contains a utility called {{ic|uidmapshift}} which is able to convert an existing ''privileged'' container to an ''unprivileged'' container to avoid a total rebuild of the image.<br />
<br />
{{Warning|<br />
* It is recommended to backup the existing image before using this utility!<br />
* This utility will not shift UIDs and GIDs in [[ACL]], you will need to shift them on your own.<br />
}}<br />
<br />
Invoke the utility to convert over like so:<br />
# uidmapshift -b /var/lib/lxc/foo 0 100000 65536<br />
<br />
Additional options are available simply by calling {{ic|uidmapshift}} without any arguments.<br />
<br />
== Running Xorg programs ==<br />
Either attach to or [[SSH]] into the target container and prefix the call to the program with the DISPLAY ID of the host's X session. For most simple setups, the display is always 0.<br />
<br />
An example of running Firefox from the container in the host's display:<br />
$ DISPLAY=:0 firefox<br />
<br />
Alternatively, to avoid directly attaching to or connecting to the container, the following can be used on the host to automate the process:<br />
# lxc-attach -n playtime --clear-env -- sudo -u YOURUSER env DISPLAY=:0 firefox<br />
<br />
== Troubleshooting ==<br />
<br />
=== Root login fails ===<br />
<br />
If you get the following error when you try to login using lxc-console:<br />
<br />
login: root<br />
Login incorrect<br />
<br />
And the container's {{ic|journalctl}} shows:<br />
<br />
pam_securetty(login:auth): access denied: tty 'pts/0' is not secure !<br />
<br />
Add {{ic|pts/0}} to the list of terminal names in {{ic|/etc/securetty}} on the '''container''' filesystem, see [http://unix.stackexchange.com/questions/41840/effect-of-entries-in-etc-securetty/41939#41939]. You can also opt to delete {{ic|/etc/securetty}} on the '''container''' to allow always root to login, see [https://github.com/systemd/systemd/issues/852].<br />
<br />
Alternatively, create a new user in lxc-attach and use it for logging in to the system, then switch to root.<br />
<br />
# lxc-attach -n playtime<br />
[root@playtime]# useradd -m -Gwheel newuser<br />
[root@playtime]# passwd newuser<br />
[root@playtime]# passwd root<br />
[root@playtime]# exit<br />
# lxc-console -n playtime<br />
[newuser@playtime]$ su<br />
<br />
===No network-connection with veth in container config===<br />
<br />
If you cannot access your LAN or WAN with a networking interface configured as '''veth''' and setup through {{ic|/etc/lxc/''containername''/config}}.<br />
If the virtual interface gets the ip assigned and should be connected to the network correctly.<br />
ip addr show veth0 <br />
inet 192.168.1.111/24<br />
You may disable all the relevant static ip formulas and try setting the ip through the booted container-os like you would normaly do.<br />
<br />
Example {{ic|''container''/config}}<br />
<br />
...<br />
lxc.net.0.type = veth<br />
lxc.net.0.name = veth0<br />
lxc.net.0.flags = up<br />
lxc.net.0.link = {{ic|bridge}}<br />
...<br />
<br />
And then assign your IP through your preferred method '''inside''' the container, see also [[Network configuration#Configure the IP address]]{{Broken section link}}.<br />
<br />
===Cannot start unprivileged LXC due to newuidmap execution failure===<br />
<br />
{{Accuracy|See {{Bug|52560}}: it is unclear what the "current version" is, if there is any upstream bug report and where the patch is.}}<br />
<br />
Unprivileged LXC cannot start with the current {{Pkg|shadow}} package, because the ''newuidmap'' and ''newgidmap'' binaries do not have the ''setuid'' bit.<br />
<br />
$ chmod u+s /usr/bin/newuidmap<br />
$ chmod u+s /usr/bin/newgidmap<br />
<br />
This is a bug in upstream but still not cherry-picked in official repository<br />
<br />
== See also ==<br />
<br />
* [https://www.stgraber.org/2013/12/20/lxc-1-0-blog-post-series/ LXC 1.0 Blog Post Series]<br />
* [http://www.ibm.com/developerworks/linux/library/l-lxc-containers/ LXC@developerWorks]<br />
* [http://docs.docker.io/en/latest/installation/archlinux/ Docker Installation on ArchLinux]<br />
* [http://l3net.wordpress.com/tag/lxc/ LXC articles on l3net]</div>Progandyhttps://wiki.archlinux.org/index.php?title=Wayland&diff=501678Wayland2017-12-11T15:14:00Z<p>Progandy: /* Buffer API support */ EGLStreams support in sway will be removed in v1.0</p>
<hr />
<div>[[Category:X server]]<br />
[[es:Wayland]]<br />
[[fr:Wayland]]<br />
[[ja:Wayland]]<br />
[[ru:Wayland]]<br />
[[zh-hans:Wayland]]<br />
{{Related articles start}}<br />
{{Related|KMS}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
<br />
[http://wayland.freedesktop.org/ Wayland] is a protocol for a [[wikipedia:Compositing window manager|compositor]] to talk to its clients, as well as a library implementing this protocol. All major Linux desktop systems like Gnome, KDE do support Wayland, and there is also a reference implementation for a compositor called "Weston". [https://wayland.freedesktop.org/xserver.html XWayland] implements a compatibility layer to seamlessly run legacy X11 applications on Wayland.<br />
<br />
== Requirements ==<br />
<br />
Wayland only works on systems using [[KMS]]. As Wayland is only a library, it is useless on its own: to replace the X Server you need a compositor such as [[#Weston]].<br />
<br />
=== Buffer API support ===<br />
<br />
For the GPU driver and Wayland compositor to be compatible they must support the same buffer API. There are two main APIs: [[Wikipedia:Generic Buffer Management|GBM]] and [http://www.phoronix.com/scan.php?page=news_item&px=XDC2016-Device-Memory-API EGLStreams].<br />
<br />
{| class="wikitable"<br />
|-<br />
! Buffer API !! GPU driver support !! Wayland compositor support<br />
|-<br />
| GBM || All except [[NVIDIA]] || All<br />
|-<br />
| EGLStreams || [[NVIDIA]] || [[GNOME]], [[Grefsen]], [[Sway]] ([https://sircmpwn.github.io/2017/10/26/Fuck-you-nvidia.html will be removed])<br />
|-<br />
|}<br />
<br />
== Weston ==<br />
<br />
Weston is the reference implementation of a Wayland compositor. <br />
<br />
=== Installation ===<br />
<br />
Install the {{Pkg|weston}} package.<br />
<br />
=== Usage ===<br />
<br />
{| class="wikitable" style="float: right; width: 40%; margin-left: 1em"<br />
|+ '''''Keyboard Shortcuts''' (super = windows key - can be changed, see weston.ini)'' {{Ic|Ctrl-b}}<br />
!Cmd<br />
!Action<br />
|-<br />
|{{ic|Ctrl+Alt+Backspace}}<br />
|Quit Weston<br />
|-<br />
|{{ic|Super+Scroll}} (or {{ic|PageUp}}/{{ic|PageDown}})<br />
|Zoom in/out of desktop<br />
|-<br />
|{{ic|Super+Tab}}<br />
|Switch windows<br />
|-<br />
|{{ic|Super+LMB}}<br />
|Move Window<br />
|-<br />
|{{ic|Super+MMB}}<br />
|Rotate Window !<br />
|-<br />
|{{ic|Super+RMB}}<br />
|Resize Window <br />
|-<br />
|{{ic|Super+Alt+Scroll}}<br />
|Change window opacity<br />
|-<br />
|{{ic|Super+K}}<br />
|Force Kill Active Window<br />
|-<br />
|{{ic|Super+KeyUp/KeyDown}}<br />
|Switch Prev/Next Workspace<br />
|-<br />
|{{ic|Super+Shift+KeyUp/KeyDown}}<br />
|Grab Current Window and Switch Workspace<br />
|-<br />
|{{ic|Super+F'''''n'''''}}<br />
|Switch to Workspace '''''n'''''<br />
|-<br />
|{{ic|Super+S}}<br />
|Take a screenshot<br />
|-<br />
|{{ic|Super+R}}<br />
|Record a screencast.<br />
|}<br />
<br />
Now that Wayland and its requirements are installed you should be ready to test it out. <br />
<br />
It is possible to run Weston inside a running X session:<br />
$ weston<br />
<br />
Alternatively, to try to launch Weston natively, switch to a terminal and run:<br />
$ weston-launch<br />
<br />
Then at a TTY within Weston, you can run the demos. To launch a terminal emulator:<br />
$ weston-terminal<br />
<br />
To move flowers around the screen:<br />
$ weston-flower <br />
<br />
To display images:<br />
$ weston-image image1.jpg image2.jpg...<br />
<br />
=== Configuration ===<br />
Example configuration file for keyboard layout, module selection and UI modifications. See {{man|5|weston.ini}} for full details. The Weston outputs differ slightly from {{ic|xorg.conf}}'s Monitors:<br />
<br />
$ ls /sys/class/drm<br />
card0<br />
card0-VGA-1<br />
card1<br />
card1-DVI-I-1<br />
card1-HDMI-A-1<br />
card1-VGA-2<br />
<br />
{{ic|card0}} is the unused built-in video adapter. The add-on adapter {{ic|card1}} is cabled to one HDMI and one DVI monitor, so the output names are {{ic|HDMI-A-1}} and {{ic|DVI-I-1}}.<br />
<br />
{{hc|~/.config/weston.ini|<nowiki><br />
[core]<br />
# xwayland support<br />
xwayland=true<br />
<br />
[libinput]<br />
enable_tap=true<br />
<br />
[shell]<br />
background-image=/usr/share/backgrounds/gnome/Aqua.jpg<br />
background-color=0xff002244<br />
panel-color=0x90ff0000<br />
locking=true<br />
animation=zoom<br />
close-animation=fade<br />
focus-animation=dim-layer<br />
#binding-modifier=ctrl<br />
#num-workspaces=6<br />
### for cursor themes install xcursor-themes pkg from Extra. ###<br />
#cursor-theme=whiteglass<br />
#cursor-size=24<br />
<br />
### tablet options ###<br />
#lockscreen-icon=/usr/share/icons/gnome/256x256/actions/lock.png<br />
#lockscreen=/usr/share/backgrounds/gnome/Garden.jpg<br />
#homescreen=/usr/share/backgrounds/gnome/Blinds.jpg<br />
#animation=fade<br />
<br />
### for Laptop displays ###<br />
#[output]<br />
#name=LVDS1<br />
#mode=1680x1050<br />
#transform=90<br />
<br />
#[output]<br />
#name=VGA1<br />
# The following sets the mode with a modeline, you can get modelines for your preffered resolutions using the cvt utility<br />
#mode=173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync<br />
#transform=flipped<br />
<br />
#[output]<br />
#name=X1<br />
#mode=1024x768<br />
#transform=flipped-270<br />
<br />
[input-method]<br />
#path=/usr/lib/weston/weston-keyboard<br />
<br />
[keyboard]<br />
keymap_rules=evdev<br />
#keymap_layout=gb,de<br />
#keymap_options=caps:ctrl_modifier,shift:both_capslock_cancel<br />
### keymap_options from /usr/share/X11/xkb/rules/base.lst ###<br />
numlock-on=true<br />
<br />
[terminal]<br />
#font=DroidSansMono<br />
#font-size=14<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/weston-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/gnome-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/hicolor/24x24/apps/firefox.png<br />
path=/usr/bin/firefox<br />
<br />
[launcher]<br />
icon=/usr/share/weston/icon_flower.png<br />
path=/usr/bin/weston-flower<br />
<br />
[screensaver]<br />
# Uncomment path to disable screensaver<br />
path=/usr/libexec/weston-screensaver<br />
duration=600<br />
</nowiki><br />
}}<br />
<br />
Minimal {{ic|weston.ini}} :<br />
{{hc|~/.config/weston.ini|<nowiki><br />
[core]<br />
xwayland=true<br />
<br />
[keyboard]<br />
keymap_layout=gb<br />
<br />
[output]<br />
name=LVDS1<br />
mode=1680x1050<br />
transform=90<br />
<br />
[launcher]<br />
icon=/usr/share/icons/gnome/24x24/apps/utilities-terminal.png<br />
path=/usr/bin/weston-terminal<br />
<br />
[launcher]<br />
icon=/usr/share/icons/hicolor/24x24/apps/firefox.png<br />
path=/usr/bin/firefox<br />
<br />
</nowiki><br />
}}<br />
<br />
==== XWayland ====<br />
[[Install]] the {{Pkg|xorg-server-xwayland}} package.<br />
<br />
When you want to run an X application from within Weston, it spins up Xwayland to service the request. The following configuration is shown above:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[core]<br />
modules=xwayland.so</nowiki><br />
}}<br />
{{Note| if X is not already configured you may need to configure a keymap: [[Keyboard configuration in Xorg]]}}<br />
<br />
==== Screencast recording ====<br />
Weston has build-in screencast recording which can be started and stopped by pressing the {{ic|Super+r}} key combination. Screencasts are saved to the file {{ic|capture.wcap}} in the current working directory of Weston. <br />
<br />
The WCAP format is a lossless video format specific to Weston, which only records the difference in frames. To be able to play the recorded screencast, the WCAP file will need to be converted to a format which a media player can understand. First, convert the capture to the YUV pixel format:<br />
<br />
$ wcap-decode capture.wcap --yuv4mpeg2 > capture.y4m<br />
<br />
The YUV file can then be transcoded to other formats using [[FFmpeg]].<br />
<br />
==== High DPI displays ====<br />
<br />
For [[wikipedia:Retina_Display|Retina]] or [[HiDPI]] displays, use:<br />
<br />
{{hc|~/.config/weston.ini|<br />
<nowiki>[output]<br />
name=...<br />
scale=2</nowiki><br />
}}<br />
<br />
==== Shell font ====<br />
<br />
Weston uses the default sans-serif font for window title bars, clocks, etc. See [[Font configuration#Replace or set default fonts]] for instructions on how to change this font.<br />
<br />
== GUI libraries ==<br />
<br />
See details on the [http://wayland.freedesktop.org/toolkits.html official website].<br />
<br />
=== GTK+ 3 ===<br />
<br />
The {{Pkg|gtk3}} package has the Wayland backend enabled. GTK+ will default to the X11 backend, but this can be overridden by modifying an environment variable: {{ic|GDK_BACKEND&#61;wayland}}.<br />
<br />
=== Qt 5 ===<br />
To enable Wayland support in Qt 5, install the {{Pkg|qt5-wayland}} package.<br />
<br />
To run a Qt 5 app with the Wayland plugin, use {{ic|1=-platform wayland}} or set the {{ic|1=QT_QPA_PLATFORM=wayland-egl}} [[environment variable]].<br />
<br />
=== Clutter ===<br />
<br />
The Clutter toolkit has a Wayland backend that allows it to run as a Wayland client. The backend is enabled in the {{Pkg|clutter}} package.<br />
<br />
To run a Clutter app on Wayland, set {{ic|CLUTTER_BACKEND&#61;wayland}}.<br />
<br />
=== SDL2 ===<br />
<br />
To run a SDL2 application on Wayland, set {{ic|SDL_VIDEODRIVER&#61;wayland}}.<br />
<br />
=== GLFW ===<br />
<br />
To use GLFW with the Wayland backend, install the {{Pkg|glfw-wayland}} package (instead of {{Pkg|glfw-x11}}).<br />
<br />
=== EFL ===<br />
<br />
EFL has complete Wayland support. <br />
To run a EFL application on Wayland, see Wayland [http://wayland.freedesktop.org/efl.html project page].<br />
<br />
== Window managers and desktop shells ==<br />
<br />
{| class="wikitable sortable"<br />
! Name<br />
! Type<br />
! Description<br />
|-<br />
| GNOME<br />
| Stacking<br />
| See [[GNOME#Starting GNOME]].<br />
|-<br />
| sway<br />
| Tiling<br />
| [[Sway]] is an i3-compatible window manager for Wayland. [https://github.com/SirCmpwn/sway GitHub]<br />
|-<br />
| Enlightenment<br />
| Stacking<br />
| [https://www.enlightenment.org/about-wayland More Info]<br />
|-<br />
| KDE Plasma<br />
| Stacking<br />
| See [[KDE#Starting Plasma]]<br />
|-<br />
| Orbment<br />
| Tiling<br />
| [https://github.com/Cloudef/orbment orbment] (previously loliwm) is a tiling WM for Wayland.<br />
|-<br />
| Velox<br />
| Tiling<br />
| [[Velox]] is a simple window manager based on swc. It is inspired by [[dwm]] and [[xmonad]].<br />
|-<br />
| Orbital<br />
| Stacking<br />
| [https://github.com/giucam/orbital Orbital] is a Wayland compositor and shell, using Qt5 and Weston. The goal of the project is to build a simple yet flexible and good looking Wayland desktop. It is not a full fledged DE but rather the analogue of a WM in the X11 world, such as [[Awesome]] or [[Fluxbox]].<br />
|-<br />
| Liri Shell<br />
| Stacking<br />
| [https://github.com/lirios/shell Liri Shell] is the desktop shell for [[Liri]], built using QtQuick and QtCompositor as a compositor for Wayland.<br />
|-<br />
| Maynard<br />
| ''(Unclear)''<br />
| [https://github.com/raspberrypi/maynard Maynard] is a desktop shell client for Weston based on GTK. It was based on weston-gtk-shell, a project by Tiago Vignatti.<br />
|-<br />
| Motorcar<br />
| ''(Unclear)''<br />
| [https://github.com/evil0sheep/motorcar Motorcar] is a Wayland compositor to explore 3D windowing using virtual reality.<br />
|-<br />
| Way Cooler<br />
| Tiling<br />
| {{AUR|way-cooler}} is a customizable (Lua config files) Wayland compositor written in Rust. Inspired by i3 and awesome.<br />
|-<br />
| Maze Compositor<br />
| Floating 3D<br />
| [https://github.com/capisce/mazecompositor Maze Compositor] is a 3D Qt based Wayland compositor<br />
|-<br />
| Grefsen<br />
| Floating<br />
| [https://github.com/ec1oud/grefsen Grefsen] is a Qt/Wayland compositor providing a minimal desktop environment.<br />
|}<br />
<br />
Some of installed wayland desktop clients might store information in {{ic|/usr/share/wayland-sessions/*.desktop}} files about how to start them in wayland.<br />
<br />
==Troubleshooting==<br />
<br />
<br />
=== Running graphical applications as root ===<br />
<br />
Trying to run a graphical application as root via [[su]], [[sudo]] or [[polkit|pkexec]] in a Wayland session (''e.g.'' [[GParted]] or [[Gedit]]), be it in a terminal emulator or from a graphical component, will fail with an error similar to this:<br />
<br />
{{bc|$ sudo gedit<br />
No protocol specified<br />
Unable to init server: Could not connect: Connection refused<br />
<br />
(gedit:2349): Gtk-WARNING **: cannot open display: :0<br />
}}<br />
<br />
Before Wayland, running GUI applications with elevated privileges could be properly implemented by creating a [[Polkit]] policy, or more dangerously done by running the command in a terminal by prepending the command with {{ic|sudo}}; but under (X)Wayland this does not work anymore as the default has been made to only allow the user who started the X server to connect clients to it (see the [https://bugzilla.redhat.com/show_bug.cgi?id=1266771 bug report] and [https://cgit.freedesktop.org/xorg/xserver/commit/?id=c4534a3 the] [https://cgit.freedesktop.org/xorg/xserver/commit/?id=4b4b908 upstream] [https://cgit.freedesktop.org/xorg/xserver/commit/?id=76636ac commits] it refers to).<br />
<br />
The most straightforward workaround is to use [[xhost]] to temporarily allow the root user to access the local user's X session. To do so, execute the following command as the current (unprivileged) user[https://bugzilla.redhat.com/show_bug.cgi?id=1274451#c64]:<br />
xhost si:localuser:root<br />
<br />
To remove this access after the application has been closed:<br />
xhost -si:localuser:root<br />
<br />
{{Note|1=This [https://bugzilla.gnome.org//show_bug.cgi?id=772875 GNOME bug report] suggests two other workarounds, with one specific to editing text files.}}<br />
<br />
{{Style|Many of these subsections should go into a "Known issues" section (i.e., there is no solution currently). Additionally prepending a date is not needed.}}<br />
<br />
=== LLVM assertion failure ===<br />
If you get an LLVM assertion failure, you need to rebuild {{Pkg|mesa}} without Gallium LLVM until this problem is fixed. <br />
<br />
This may imply disabling some drivers which require LLVM.<br />
You may also try exporting the following, if having problems with hardware drivers: <br />
<br />
$ export EGL_DRIVER=/usr/lib/egl/egl_gallium.so<br />
<br />
=== Slow motion, graphical glitches, and crashes ===<br />
Gnome-shell users may experience display issues when they switch to Wayland from X. One of the root cause might be the {{ic|1=CLUTTER_PAINT=disable-clipped-redraws:disable-culling}} set by yourself for Xorg-based gnome-shell. Just try to remove it from {{ic|/etc/environment}} or other rc files to see if everything goes back to normal.<br />
<br />
=== nemo ===<br />
(20161229) prevent that the desktop is created <ref>[https://github.com/linuxmint/nemo/issues/1343 nemo issue 1343]</ref><br />
gsettings set org.nemo.desktop show-desktop-icons false<br />
<br />
=== X11 on tty1, wayland on tty2 ===<br />
(20161209) windows of gnome applications end up on tty2 no matter where started ([https://bugzilla.gnome.org/show_bug.cgi?id=774775 gnome issue 774775)]<br />
<br />
=== gnome wayland on tty1, weston on tty2 ===<br />
(20170106) apps started on gnome with WAYLAND_DISPLAY set to westen make it not respond any more ([https://bugs.freedesktop.org/show_bug.cgi?id=99489 wayland issue 99489])<br />
<br />
=== weston-terminal ===<br />
(20161229) core dump when started on gnome<br />
<br />
=== liteide ===<br />
(20161229) [https://github.com/visualfc/liteide/issues/734 core dump]] on gnome and weston.<br />
<br />
=== screen recording ===<br />
Currently only {{AUR|green-recorder}} supports screen recording on Wayland (requires a GNOME session).<br />
<br />
=== remote display ===<br />
(20161229) there was a merge of FreeRDP into weston in 2013, enabled via compile time switch. The arch linux weston package currently has it not enabled.<br />
<br />
=== Input grabbing in games, remote desktop and VM windows ===<br />
<br />
In contrast to Xorg, Wayland does not allow exclusive input device grabbing, also known as active or explicit grab (e.g. [https://tronche.com/gui/x/xlib/input/XGrabKeyboard.html keyboard], [https://tronche.com/gui/x/xlib/input/XGrabPointer.html mouse]), instead, it depends on the Wayland compositor to pass keyboard shortcuts and confine the pointer device to the application window.<br />
<br />
This change in input grabbing breaks current applications' behavior, meaning:<br />
* Hotkey combinations and modifiers will be caught by the compositor and won't be sent to remote desktop and virtual machine windows.<br />
* The mouse pointer will not be restricted to the application's window which might cause a parallax effect where the location of the mouse pointer inside the window of the virtual machine or remote desktop is displaced from the host's mouse pointer.<br />
<br />
Wayland solves this by adding protocol extensions for Wayland and XWayland. Support for these extensions is needed to be added to Wayland compositors, XWayland and in the case of native Wayland clients to widget toolkits (e.g GTK, QT) and probably also to the applications themselves. ATM there is no Wayland compositor which support all of these extensions.<br />
<br />
The related extensions are:<br />
* [https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/xwayland-keyboard-grab/xwayland-keyboard-grab-unstable-v1.xml XWayland keyboard grabbing protocol], added in [https://lists.freedesktop.org/archives/wayland-devel/2017-July/034459.html wayland-protocols 1.9], XWayland support [https://lists.x.org/archives/xorg-devel/2017-August/054231.html already been added] to xorg-server 1.20 development tree.<br />
* [https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/keyboard-shortcuts-inhibit/keyboard-shortcuts-inhibit-unstable-v1.xml Compositor shortcuts inhibit protocol] (native Wayland only), added in [https://lists.freedesktop.org/archives/wayland-devel/2017-July/034459.html wayland-protocols 1.9]<br />
* [https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/relative-pointer/relative-pointer-unstable-v1.xml Relative pointer protocol], added in [https://lists.freedesktop.org/archives/wayland-devel/2016-February/027029.html wayland-protocols 1.1], XWayland support [https://lists.x.org/archives/xorg-devel/2016-September/050975.html already been added] in [https://lists.x.org/archives/xorg-announce/2016-October/002734.html xorg-server 1.19]<br />
* [https://cgit.freedesktop.org/wayland/wayland-protocols/tree/unstable/pointer-constraints/pointer-constraints-unstable-v1.xml Pointer constraints protocol], added in [https://lists.freedesktop.org/archives/wayland-devel/2016-February/027029.html wayland-protocols 1.1], XWayland support [https://lists.x.org/archives/xorg-devel/2016-September/050975.html already been added] in [https://lists.x.org/archives/xorg-announce/2016-October/002734.html xorg-server 1.19]<br />
<br />
== See also ==<br />
* [https://fedoraproject.org/wiki/How_to_debug_Wayland_problems Article about Wayland debugging on Fedora Wiki]<br />
* [[Cursor themes]]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=107499 Arch Linux forum discussion]<br />
* [http://wayland.freedesktop.org/docs/html/ Wayland documentation online]</div>Progandyhttps://wiki.archlinux.org/index.php?title=User:Progandy&diff=483027User:Progandy2017-07-27T18:41:06Z<p>Progandy: pacman hook: display optdepends</p>
<hr />
<div><br />
== Pacman Hook: Display new optional dependencies after upgrades and installations ==<br />
<br />
<br />
https://gist.github.com/progandy/0a672083a373d69e819a508578c327b5</div>Progandy