ArchWiki - User contributions [en]

Category talk:Digital signature

2026-05-17T19:20:34Z

Indigo: /* How to group this category? */ re

== How to group this category? ==

Given we have [[:Category:OpenPGP]] for the [[OpenPGP]] article/group of implementations, and [[:Category:Transport Layer Security]] with the analogue [[Transport Layer Security]] for everything [[OpenSSL]]/TLS related, what's the aim for this category (ping @[[User:Davezerave|Davezerave]])?

-- [[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:35, 29 February 2024 (UTC)

:The new category is meant to collect all pages that concern themselves with creating digital signatures.
:Examples are articles doing so in all OpenPGP implementations (e.g. [[GnuPG]], and sequoia-pgp, the SOP interfaces in [[Stateless OpenPGP]]) and also for creating data signatures using [[OpenSSL]] (e.g. for release artifacts) or other systems (e.g. signify). [[User:Davezerave|Davezerave]] ([[User talk:Davezerave|talk]]) 20:07, 2 March 2024 (UTC)

::Ok. I was asking to figure how we avoid duplication. For example, manually adding [[GnuPG]] to both categories (openpgp and digital signature) would be subject duplication. I read your ''all'' [[:Category:OpenPGP]] implementations as all its assigned articles, hence I've changed its parent category with [[Special:diff/802129]]. While we lose a separate entry for OpenPGP in [[:Category:Cryptography]], it has the advantage that the subcategory is separated in its [[:Category:Digital signature]] overview and (mainly) we don't have to assign some/most openpgp articles to both groups, and the selected additions like [[OpenSSL]] are clearly separated. Does this reflect the plan? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 12:37, 3 March 2024 (UTC)
:::Hmm, no not really.
:::OpenPGP is used both for digital signatures *and* encryption (but there are other mechanisms to do his for either of these two topics!). The OpenPGP category is more suitable as a subcategory of Cryptography than a subcategory of only Digital Signature.
:::Both Digital Signature and Encryption are suitable subcategories for Cryptography and as mentioned above, both of those topics can be assigned to other articles (not related to OpenPGP). [[User:Davezerave|Davezerave]] ([[User talk:Davezerave|talk]]) 18:12, 11 March 2024 (UTC)

::::Yes, both Digital Signature and Encryption can be assigned independent of OpenPGP, that's not impeded. And, yes, both are subjects to be grouped under Cryptography academically, but I think its too academic for our purpose; most software implements specific protocols, those define the primary use case (category) and why applications depend on them. So, OpenPGP, TLS, OpenSSH, TLS, etc.
::::What would be a search/use case that is better served by double-assigning Digital Signature and OpenPGP categories separately to these articles?
::::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:42, 12 March 2024 (UTC)
::::There was a new article grouped under this Digital Signature category only ([[Autofirma_(Español)]]), and I'd have trouble to group it otherwise. Also, in the meantime the wiki CSS switched categories to display at the bottom of the articles. That's much less intrusive if we double-assign articles.
::::So, let's keep it like you intended. I keep this item open until I had a go at assigning it to existing articles.
::::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:20, 17 May 2026 (UTC)

Autofirma (Español)

2026-05-17T19:09:11Z

Indigo: /* Véase también */ fix dead link

[[Category:Digital signature (Español)]]
[[Category:Software (Español)]]

[https://firmaelectronica.gob.es/Home/Ciudadanos/Apps-Firma.html Autofirma] es una aplicación de firma electrónica desarrollada por el Ministerio de Asuntos Económicos y Transformación Digital de España. Permite firmar documentos localmente y a través del navegador en páginas de la administración pública.

== Instalación ==

[[Instalación (Español)|Instale]] el paquete {{AUR|autofirma}}, disponible en los [[AUR (Español)|Repositorios de Usuarios de Arch (AUR)]].

Este paquete incluye las dependencias necesarias, como el entorno de ejecución de Java (JRE), que es fundamental para su funcionamiento.

== Configuración ==

=== Navegadores web ===
Para que Autofirma funcione correctamente con navegadores como [[Firefox (Español)|Firefox]] o [[Chromium (Español)|Chromium]], es posible que necesite reiniciar el navegador tras la instalación para que se reconozca el protocolo `afirma://`.

== Uso ==

Puede ejecutar Autofirma desde su menú de aplicaciones o mediante el comando:

$ autofirma

Al acceder a una sede electrónica que requiera firma, el navegador lanzará automáticamente la aplicación para procesar el certificado digital.

== Solución de problemas ==

=== Problemas con el almacén de certificados ===
Si Autofirma no detecta sus certificados instalados en el navegador, asegúrese de que el paquete `nss` esté actualizado y que los certificados estén correctamente importados en el almacén de su navegador principal.

== Véase también ==
* [https://firmaelectronica.gob.es/ciudadanos Sitio oficial de Autofirma]
* [[Certificados digitales (Español)|Certificados digitales en Arch Linux]]

Talk:Self-encrypting drives

2026-05-17T18:50:38Z

Indigo: /* WD PC SN740 NVMe SSD setup doesn't work with sedutil */ remove closed item

== Suspend doesn't work properly ==

Suspend locks the drive (Dell E6410 + Samsung EVO 850) and drive is not accessible after wake up. One solution is to disable Suspend - see https://wiki.archlinux.org/index.php/Polkit#Disable_suspend_and_hibernate

Is possible to unlock drive after wake up?
-> A fork to sedutil-cli is available that allows providing the password *BEFORE* sleeping such that the system can resume: https://aur.archlinux.org/packages/sedutil-sleep-git/
[[User:Germafab|Germafab]] ([[User talk:Germafab|talk]]) 12:39, 10 May 2020 (UTC)

== UEFI boot problems on Asus H97M-E ==

Unfortunately, OPAL breaks Linux UEFI boot on my Asus motherboard. I use a dualboot configuration. As I understand it, during the initial boot, when the firmware sees an "empty" SSD it removes all UEFI boot entries. When it gets rebooted after entering the encryption password in the PBA, the firmware notices the EFI boot partition and automatically inserts a single new boot entry (of course, only the Windows one). I have only tested it on Asus H97M-E, but I wouldn't be surprised to see this behaviour at least on other Asus motherboards.

Maybe the possibility of firmware bugs of this kind should be mentioned in the "disadvantages" section?

[[User:Catnip|Catnip]] ([[User talk:Catnip|talk]]) 14:40, 9 March 2020 (UTC)

:: I see something similar as a consequence of the issue explained in "Troubleshooting: PBA Cold Reboot Locks Drives Again": after unlocking the drive, if I manage to break the cold reboot (by hitting F2 at the right moment) and do a warm reboot instead, I see the unlocked drive in UEFI, but its boot entry doesn't work. My workaround is choosing "Boot From File" in UEFI and select the proper grubx64.efi. Then normal boot is possible. But this has to be done for each boot. -- [[User:XX|XX]] ([[User talk:XX|talk]]) 11:18, 3 October 2023 (UTC)

:I've added [https://wiki.archlinux.org/index.php?title=Self-encrypting_drives&diff=803377&oldid=803376]. Ideally, we could add example references of such firmware behaviour (bug report, BBS topic). Please add one, if you come across it (must not be yours, but conclusive for a firmware). --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:22, 15 March 2024 (UTC)

== Article should be clearer early on about the negatives ==

It's unfortunate that there's barely any information on SED/OPAL online. Given that resume from sleep doesn't work, I suspect many notebook users will not want to go this route at all. While it's commendable that the article attempts to show the (hacky) ways of getting OPAL to work, I think there should an early notification about the flaky nature of current solutions, so users can make an informed choice.

Having a cautionary message above every section is not the answer. I'd rather the article be rewritten from scratch based on the current state of information. [[User:Adrian5|Adrian5]] ([[User talk:Adrian5|talk]]) 22:00, 25 February 2021 (UTC)

:: According to my experience resume from sleep works. Resume from suspend may not work. -- [[User:XX|XX]] ([[User talk:XX|talk]]) 11:18, 3 October 2023 (UTC)

== cryptsetup support for OPAL ==

Heads-up: If all goes well, the upcoming {{Pkg|cryptsetup}} 2.7.0 gains OPAL support. While it won't be suitable for pre-boot authentification (whole drive encryption), it will make the hardware features much easier to deploy for individual devices. See the [https://mirrors.edge.kernel.org/pub/linux/utils/cryptsetup/v2.7/v2.7.0-ReleaseNotes release candidate Notes].
As a first thought how to integrate the new support, the [[Self-encrypting drives#Encrypting a non-root drive]] could be applicable for an initial example once the release lands.? -- [[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 23:10, 12 December 2023 (UTC)

:I am so looking forward to this, it was [https://gitlab.com/cryptsetup/cryptsetup/-/merge_requests/461 merged] 5 months ago. Pottering on how this would fix OPAL and SecureBoot - https://github.com/systemd/systemd/issues/16089#issuecomment-1681980103 [[User:Strykar|What is bash?]] ([[User talk:Strykar|talk]]) 05:04, 25 December 2023 (UTC)

::I did a first test with with a sata ssd. This now triggers a pre-boot pw on uefi and when I plug it into a legacy bios (no tcg support, hence no pre-boot pw), it opens opal with the luks device or also a luks header for opal-only (yay). Performance does not seem to differ with opal-only or opal+luks, could be the drive maxes sata in both cases. What did not work yet was (1) luksFormat on the legacy bios, and a nvme on uefi, (2) a FIDO2 cryptenroll on the opal-only device. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 16:20, 14 January 2024 (UTC)
::With cryptsetup 2.7.0-1 now in the repo, a luksFormat on legacy bios and a FIDO2 cryptenroll on the opal-only device was now possible. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:08, 28 January 2024 (UTC)
:::Is it possible for you to add some examples to the wiki? [[User:Strykar|What is bash?]] ([[User talk:Strykar|talk]]) 21:02, 2 February 2024 (UTC)
::::Yes, I've collected example output for [[Special:diff/799562]] and will add first paras soon. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 16:27, 4 February 2024 (UTC)
::::I've added initial examples. Welcome to add to it. I have not tried crypttab/resume yet and will add that if no-one is faster. If it works as expected, it should be enough to crosslink dm-crypt/suspend sections. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:26, 4 February 2024 (UTC)
:::::Does anyone know if there are any compatibility issues with [[dm-crypt/Drive preparation#Stacked block devices|stacked block devices]]? My gut says that it should not be possible to place LUKS on top of LVM or mdadm RAID, but {{ic|cryptsetup luksFormat --hw-opal-only}} didn't complain about creating LUKS on top of a LVM logical volume (a single LV in a single VG in a single PV) when I tested it. Unfortunately I don't have multiple spare OPAL drives to test RAID configurations. --[[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 10:11, 10 July 2024 (UTC)
::::::In theory it should work as well, but your gut sensing issues is spot on ([https://github.com/util-linux/util-linux/commit/93ba7961779789217a1f814ce3110ff8c040c8c3], [https://gitlab.com/cryptsetup/cryptsetup/-/issues/873#note_1843634341]). I can't try it currently, but also think it's too early to rely on it productively. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 00:55, 14 August 2024 (UTC)

Talk:ECryptfs

2026-05-17T18:49:53Z

Indigo: /* eCryptfs is deprecated and unmaintained – add prominent warning? */ remove closed item

=== Automounting ===
Just a short remark which took me several hours to figure out:

I tried to follow 3.2 manual setup without ecryptfs-utils and it worked very well until I tried to get my encrypted directory mounted on login.

It is now working and two crucial steps seemed to be:
1. besides pam_mount.so use also pam_ecryptfs.so
2. put an empty file "auto-mount" into /home/USER/.ecryptfs

Especially figuring out 2. has taken a lot of time. It would be good if the article would mention this fact.
If someone who really knows ecryptfs can verify that I have done the right things, then one should add remarks about this to the page.

Kind regards
[[User:DaAlx|DaAlx]] ([[User talk:DaAlx|talk]]) 21:20, 25 March 2015 (UTC)

:Hi, can you please put a link here which section you followed? Did you use the ecryptfs-simple package (section 3.2)? Section 3.1 mentions the points you make ([[ECryptfs#Auto-mounting]]). Sections 3.2 and 3.3 dont. I assume you refer to 3.3 [[ECryptfs#Without_ecryptfs-utils]], please confirm. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 06:56, 26 March 2015 (UTC)

::Hi, oh sorry for the imprecise section reference (must have been too tired) So I started my setup with 3.3.2 and followed up to 3.3.2.2. [[Ecryptfs#Auto-mounting_2]] -- [[User:DaAlx|DaAlx]] ([[User talk:DaAlx|talk]]) 08:22, 26 March 2015 (UTC)

:::Thanks. I now re-tried the section 3.3.2 again. My results for the described pam_mount are different though, i.e. I did not need your points (1) and (2) above at all. It mounts like it should, but tor some reason the directory is user-mounted twice and does not unmount on logout.
:::Not sure what to make of that, maybe someone else has an idea. How do you login (console, gdm, kdm, slim,...)? Did you use the ecryptfs-utils default directory name (~/.Private,~/Private) or another one? Have you modified {{ic|/etc/pam.d/system-auth}} for other reasons before? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:06, 26 March 2015 (UTC)
:::Edit: Now I figured why I had different results and was able to confirm yours. The reason was that I had an old /etc/modules-load.d autoload for ecryptfs and fuse (needed for other reasons) which I forgot about. Removing that I arrive at your results. The problems described above remain though. I have adjusted the section with [https://wiki.archlinux.org/index.php?title=ECryptfs&diff=367315&oldid=366857], does it reflect your experience now correctly? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:06, 26 March 2015 (UTC)

:::: Hi! Yes, your changes exactly make the right points. Thank you very much. By the way, in the pam mount article there is a remark that auto-umount does not work currently. I also noted the double mounting thing on login --[[User:DaAlx|DaAlx]] ([[User talk:DaAlx|talk]]) 22:20, 26 March 2015 (UTC)

::::: Ok, good. Yes, the auto-umount does not work consistently with just pam_ecryptfs.so as well:[https://wiki.archlinux.org/index.php?title=ECryptfs&diff=365591&oldid=362767] The double-mounting I only noticed with configured pam_mount. Let's keep this item open a bit, maybe someone has an idea about the cause. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 23:19, 26 March 2015 (UTC)

:::::: With reference to this talk I received a suggestion of a different approach via email. It employs pam_exec instead of pam_mount and it is suggested not to have the unmounting problem. See the short <s>write up</s> - see below comment. Note it is used on systemd-based debian Jessie and I have not looked into porting/testing it to Arch yet. If someone does, please give some input on your results. Thanks. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 16:36, 14 February 2017 (UTC)

::::::: Hi I am the person responsible for the link [[User:Indigo|Indigo]] posted I have made a second guide which corrects a very bad issue of your password ending up in the journal log, PLEASE MAKE SURE to update the code mentioned in my guide, [https://paste.debian.net/plainh/f2480500 new guide] and make sure to WIPE YOUR JOURNAL if you did use the previous guide. Sorry for the bad error. I will when I am not tethering for Internet spin up an Arch VM and test this on Arch but thus far I have only tested it on Debian. Improvements and reviews of the guide and its code are more than welcome! [[User:KonomiKitten|KonomiKitten]] ([[User talk:KonomiKitten|talk]]) 09:38, 10 March 2017 (UTC)

:::::::: In any case thanks for reporting it! --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 15:06, 10 March 2017 (UTC)
:::::::: I forgot to mention you can of course just rewrap with the new passphrase after you ran ''passwd''; more effective than wiping the journal. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:41, 17 March 2017 (UTC)

::::::: Hey [[User:Indigo|Indigo]], concerning auto-umount of ecryptfs, I've been adapting the solution proposed in [https://wiki.archlinux.org/index.php/Talk:Pam_mount the Pam_mount talk], and it works fine with console, lightdm and gdm logins (meaning the encrypted dir gets cleanly unmounted on logout, provided there are no process left using this dir), at least if one uses Ubuntu tools to encrypt the dir. It involves a different setup of /etc/pam.d (moving pam_ecryptfs.so calls to a separate conf file, so as to stop being interfered by {{ic|systemd --user}}). I am willing to expose it in lieu of the actual warning on auto-umounting ; just thought I could to tell you first. [[User:Lafleur|la Fleur]] ([[User talk:Lafleur|talk]]) 00:06, 13 October 2018 (UTC)

::::::::Hey, thanks for the heads up. Sounds like great news, though I faintly remember the ecryptfs was always arguing that systemd does not warrant respecitve processes accessing the dir being stopped on user logout. Anyhow, please go ahead and share - it sure is something like a show-stopper for Arch usage of the package in some system environments. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 22:27, 14 November 2018 (UTC)

::::::::: Well; I did it at last. Now it seems pretty clear to me, as I tested the setup on 2 machines of daily use. One way or the other, the {{ic|systemd-logind}} process can't quit on user logout if it did reach {{ic|session pam_ecryptfs.so}} in {{ic|system-auth}}. [[User:Lafleur|la Fleur]] ([[User talk:Lafleur|talk]]) 22:13, 14 September 2020 (UTC)

== Changes to /etc/pam.d/system-auth for auto-mounting ==

Section 2.1.3.2 explains the changes to {{ic|/etc/pam.d/system-auth}} that are required for auto-mounting. As the contents of this file have [https://github.com/archlinux/svntogit-packages/commit/2d5af94ae55a5c98837ce9631f331ad2aad32bb3#diff-8d0411b338c83cd8cd8ad9d9db127101 changed], the guide needs to be updated.
The following works for me, however, I do not use systemd-homed. So, this needs to be verified / corrected:

Open {{ic|/etc/pam.d/system-auth}} and ''after'' the line containing {{ic|auth [default=die] pam_faillock.so authfail}} add:
auth required pam_ecryptfs.so unwrap
Next, ''above'' the line containing {{ic|-password [success=1 default=ignore] pam_systemd_home.so}} insert:
password optional pam_ecryptfs.so
And finally, ''after'' the line {{ic|session required pam_unix.so}} add:
session optional pam_ecryptfs.so unwrap

[[User:Bananana|Bananana]] ([[User talk:Bananana|talk]]) 13:09, 19 August 2020 (UTC)

[[User:Msoulier|Msoulier]] ([[User talk:Msoulier|talk]]) 13:13, 10 March 2022 (UTC) So I tried the changes in auto-mount, and the corrections here, and in both cases my login fails. I nearly locked myself out of my laptop. Thankfully I kept a login in a virtual terminal so that I could undo the changes. The ecryptfs-migrate-user script seems to have already set up auto-mounting without modifying pam, as it worked on my first login. Are the pam changes needed?

: You were right ! It was corrected (maybe you did) [[User:Lafleur|la Fleur]] ([[User talk:Lafleur|talk]]) 22:32, 14 September 2020 (UTC)

=== Updating pam.d files used ===

Why do we modify {{ic|system-auth}} ? [https://wiki.archlinux.org/index.php/Pam_mount pam_mount] actually modifies {{ic|system-login}} for {{ic|session}} and {{ic|auth}} instructions, and {{ic|password}} for {{ic|password}} instructions. It seems indeed adapted to process home-mounting sequences on login procedure. And I can really understand that {{ic|su}} fails for the reason that it can't access home directory if nobody has logged in. [[User:Lafleur|la Fleur]] ([[User talk:Lafleur|talk]]) 22:13, 14 September 2020 (UTC)

Talk:File recovery

2026-05-17T18:49:17Z

Indigo: /* dumpe2fs / superblocks */ remove closed item

Talk:SSH keys

2026-05-17T18:46:15Z

Indigo: /* pam_tally */ remove closed item

== SSH public key passphrase ==

I think that we should add `ssh -p -k ~/.ssh/id_ed25519.pub` to page, I saw a nice example from https://blog.0xbadc0de.be/archives/300. [[User:Pickfire|Pickfire]] ([[User talk:Pickfire|talk]]) 10:09, 13 April 2016 (UTC)

== Starting ssh-agent as a wrapper ==

In this section, there is a note which says that you "can" add eval$(ssh-agent) to your .xinitrc.

When using ssh-agent as a wrapper to startx, I have noticed that if I have both -- the alias as well as the eval statement in .xinitrc, it spawns 2 ssh-agent processes. I believe this is a leftover note from earlier when we didn't have the section titled "ssh-agent".

Can someone confirm and I will remove that note from the "ssh-agent as a wrapper section", because the way it stands today seems to indicate that you need to do both -- the alias to startx as well as add the eval statement to xinitrc in order for it to work when that is not the case.

[[User:Inxsible|Inxsible]] ([[User talk:Inxsible|talk]]) 00:46, 4 January 2017 (UTC)

:I'm pretty sure the note was intended [https://wiki.archlinux.org/index.php?title=SSH_keys&diff=461444&oldid=460060 like this]. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:12, 4 January 2017 (UTC)

== Cleaner systemd-based ssh-agent setup ==

{{hc|~/.config/environment.d/ssh-agent.conf|<nowiki>
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/ssh-agent.socket"
</nowiki>}}

{{hc|~/.config/systemd/user/ssh-agent.service|<nowiki>
[Service]
ExecStart=/usr/bin/ssh-agent -D -a "${SSH_AUTH_SOCK}"

[Install]
WantedBy=default.target
</nowiki>}}

{{hc|~/.zshrc or ~/.bash_profile or ~/.profile or the equivalent|<nowiki>
eval $(systemctl --user show-environment | grep SSH_AUTH_SOCK)
export SSH_AUTH_SOCK
</nowiki>}}

Touching three files, instead of two, but the path is defined only in one place. Something similar could be achieved with {{ic|EnvironmentFile}}. Thoughts?

[[User:Jeremejevs|Jeremejevs]] ([[User talk:Jeremejevs|talk]]) 17:22, 23 November 2017 (UTC)

:It's arguably not cleaner because you need eval, systemctl and grep to extract the path for the shell. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:29, 23 November 2017 (UTC)

== SSH Keys generated without -o flag are not safe ==

SSH Keys with default parameters are not safe [https://latacora.singles/2018/08/03/the-default-openssh.html], Hacker News discussion[https://news.ycombinator.com/item?id=17682946]. The wiki already suggests that we use -o for increased brute force protection, the suggested command for generating keys should include this. Would there be any compatibility issues with any mainstream system by always generating keys with this flag?

[[User:Orekix|Orekix]] ([[User talk:Orekix|talk]]) 02:47, 4 August 2018 (UTC)

:Good call. I'm rearranging the section. It was much too detailed on the technical aspects. All we really want to know is which key type to use and why. There could be compatibility issues with older (pre 2014) implementations of OpenSSH. Hopefully no server you're running has an OS older than 2014. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 14:07, 4 August 2018 (UTC)

:: Unfortunately, this flag " -o" is not documented in ssh-keygen's manual page (man or info). If its usage is recommended in the wiki, I think we would need some more links, references, etc., about what it does, why it's not in the manual while being implemented and how you're supposed to find out its existence. [[User:Tétrapyle|Tétrapyle]] ([[User talk:Tétrapyle|talk]]) 09:22, 30 October 2018 (UTC)

:: ''Update''. Thanks to information kindly [https://bbs.archlinux.org/viewtopic.php?pid=1814785#p1814785 reported] by user /dev/zero, this flag is documented in [https://www.freebsd.org/cgi/man.cgi?query=ssh-keygen&sektion=1&manpath=OpenBSD BSD's ssh-keygen manpage]. The Gnu/Linux manpage is probably outdated. [[User:Tétrapyle|Tétrapyle]] ([[User talk:Tétrapyle|talk]])

::: As far as I know, OpenSSH 7.8 and above set the OpenSSH format for private keys by default: "ssh-keygen(1): write OpenSSH format private keys by default instead of using OpenSSL's PEM format. The OpenSSH format, supported in OpenSSH releases since 2014 and described in the PROTOCOL.key file in the source distribution, offers substantially better protection against offline password guessing and supports key comments in private keys. If necessary, it is possible to write old PEM-style keys by adding '-m PEM' to ssh-keygen's arguments when generating or updating a key." So, there is no need to set the "-o" flag anymore if you use OpenSSH > 7.7. --[[User:Ish|Ish]] ([[User talk:Ish|talk]]) 05:39, 8 January 2019 (UTC)

== Intro draft ==

{{Comment|Draft to make the intro and ''Background'' section account for the server perspective. Section levels are only adjusted for the talk page. Copy editing may be done directly, comments should be added in the ''Comments'' subsection. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 05:58, 2 January 2019 (UTC)}}

[[SSH]] uses [[Wikipedia:Public-key cryptography|public-key cryptography]] to authenticate servers, optionally it can also be used to authenticate clients.

This article assumes you already have a basic understanding of the [[Secure Shell]] protocol and have [[install]]ed [[OpenSSH]].

=== Key-based client authentication ===

SSH keys can serve as a means of identifying yourself to an SSH server using [[Wikipedia:Challenge-response authentication|challenge-response authentication]]. The major advantage of key-based authentication is that in contrast to password authentication it is not prone to [[Wikipedia:Brute-force attack|brute-force attacks]] and you do not expose valid credentials, if the server has been compromised.[https://tools.ietf.org/html/rfc4251#section-9.4.4]

Furthermore SSH key authentication can be more convenient than the more traditional password authentication. When used with a program known as an SSH agent, SSH keys can allow you to connect to a server, or multiple servers, without having to remember or enter your password for each system.

Key-based authentication is not without its drawbacks and may not be appropriate for all environments, but in many circumstances it can offer some strong advantages. A general understanding of how SSH keys work will help you decide how and when to use them to meet your needs.

==== Background ====

If an SSH server has your [[Wikipedia:Public key|public key]] on file and sees you requesting a connection, it uses your public key to construct and send you a challenge. This challenge is an encrypted message and it must be met with the appropriate response before the server will grant you access. What makes this coded message particularly secure is that it can only be understood by the private key holder. While the public key can be used to encrypt the message, it cannot be used to decrypt that very same message. Only you, the holder of the private key, will be able to correctly understand the challenge and produce the proper response.

This [[Wikipedia:Challenge-response authentication|challenge-response]] phase happens behind the scenes and is invisible to the user. As long as you hold the private key, which is typically stored in the {{ic|~/.ssh/}} directory, your SSH client should be able to reply with the appropriate response to the server.

A private key is a guarded secret and as such it is advisable to store it on disk in an encrypted form. When the encrypted private key is required, a passphrase must first be entered in order to decrypt it. While this might superficially appear as though you are providing a login password to the SSH server, the passphrase is only used to decrypt the private key on the local system. The passphrase is not transmitted over the network.

=== Comments ===

So there is a new section title, the "public-key cryptography" was moved into a different sentence and the first paragraph of the current Background section is gone:

:SSH keys are always generated in pairs with one known as the private key and the other as the public key. The private key is known only to you and it should be safely guarded. By contrast, the public key can be shared freely with any SSH server to which you wish to connect.

-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:04, 10 February 2019 (UTC)

== SSH Agent File Naming ==

The current suggested ssh-agent file name is "~/.ssh-agent-thing". I think "~/.ssh-agent.rc" would be more apt, as it bears a certain resemblance to other RC files. Moreover, this will leave the file in the user's home directory as it's never cleaned up. This could be mitigated by writing it to "/tmp/ssh-agent.rc", although I'm not sure what side effects this could have (e.g. on a multi-user system), hence proposing it here before changing the sample script on the page.

[[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 18:07, 14 August 2019 (UTC)

:"It's never cleaned up" isn't a major problem as the script will start a new agent on every boot anyway. But you could put the file at {{ic|$XDG_RUNTIME_DIR/ssh-agent.env}} to get auto-cleanup and avoid multi-user issues.
:
:...Or you could just tell ssh-agent to put the socket itself at a fixed location such as {{ic|$XDG_RUNTIME_DIR/ssh-agent.sock}}, avoiding the extra indirection. That's how the systemd --user example works.
:
:[[User:Grawity|grawity]] ([[User talk:Grawity|talk]]) 19:37, 14 August 2019 (UTC)

::I wasn't able to get it working by using {{ic|-a}} to set the socket location and then evaluate that (I got {{ic|/run/user/1000/ssh-agent.sock: No such device or address}}, so I assume that the socket can't be used in the way that I thought it could?). Regardless, {{ic|XDG_RUNTIME_DIR}} is exactly what I was looking for. Cheers.
::
::[[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 20:25, 14 August 2019 (UTC)

Is there a reason why we don't suggest using the default socket {{ic|$TMPDIR/ssh-XXXXXXXXXX/agent.<ppid>}} mentioned in the ssh-agent manpage? That way there is no need for most of this configuration.
[[User:JoeCool|JoeCool]] ([[User talk:JoeCool|talk]])

== ssh-agent invocation in .bashrc? ==

In the section for ssh-agent it's recommended: "add the following to your ~/.bashrc". I suggest changing that to .bash_profile, because of the following error.

Programs like scp or rsync use ssh, and that calls .bashrc. The command "eval `ssh-agent`" outputs agent pid, which makes these programs fail.

Since .bash_profile is for a login shell, it won't cause this problem (it doesn't).

[[User:Ynikitenko|Ynikitenko]] ([[User talk:Ynikitenko|talk]]) 11:54, 26 February 2020 (UTC)

:{{ic|.bashrc}} is sourced only for interactive shells, scp and rsync don't invoke an interactive shell on the remote host. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:55, 26 May 2020 (UTC)

== ssh-agent systemd ==

I tried setting

SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/ssh-agent.socket"

in ~/.zshrc but it didn't work. Supplied the solution of:

In the file

~/.pam_environment

put

SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/ssh-agent.socket"

which works, so I think this is the better solution.

{{Unsigned|18:23, 16 April 2021 (UTC)|Fenton.travers}}

:You are not supposed to put the {{ic|DEFAULT}} after the first space in the variable for your shell. This is the syntax for {{ic|~/.pam_environment}}.
:-- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 18:33, 16 April 2021 (UTC)

== certificates ==

There's no mention of certificates. Did I fail at searching? Or should we add it here?

[[User:Gcb|Gcb]] ([[User talk:Gcb|talk]]) 01:18, 18 August 2021 (UTC)

:This page covers the public key authentication, not certificate authentication. Feel free to draft a new page about SSH certificates in your user page. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 05:52, 19 August 2021 (UTC)

== AddKeysToAgent Option ==

The option to automatically add keys to the agent on first use is already mentioned in a tip at the ssh-agent section, however I would argue that its better to have this mentioned in the subsection for better visibility. When I tried to find a way to implement what this option does, I did not find this option in the wiki despite reading most of it. The subsection should make it easier to find. It may also be a good idea to mention this option in the chapters for external helper applications such as keychain, since many use cases for these programs are covered by OpenSSH natively after the new option was introduced. — [[User:Valoq|Valoq]] ([[User talk:Valoq|talk]]) 14:46, 16 October 2022 (UTC)

:The tip is more accurate, shows all the options instead of just "yes", and I think the formatting in a green box stands out sufficiently. There will always be somebody who will not find even the section. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 16 October 2022 (UTC)

== Server perspective is ignored ==

There is an expansion notice at the beginning with the reason:

"The intro and ''Background'' section ignore the server perspective."

I couldn't understand what that means. Mentioned sections state the relation between SSH keys and an SSH server. Or aren't those statements enough? [[User:Ismailarilik|Ismailarilik]] ([[User talk:Ismailarilik|talk]]) 07:51, 7 March 2025 (UTC)

:The page describes how a user can create their client key for identifying themselves to an SSH server, but each SSH server must also have a key that clients can use to verify that they connect to the right server. I think if you search for "SSH host key", you will find some text on this topic. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:24, 8 March 2025 (UTC)

== Section 5.2 agent refused operation ==

It appears that the problem described in this paragraph:

There is currently an open [https://bugzilla.mindrot.org/show_bug.cgi?id=3572 bug] that triggers with the "agent refused operation" error when using authenticator keys like ED25519-sk and ECDSA-SK that were created with the option <code>-O verify-required</code>. To avoid this issue, use the <code>-o IdentityAgent=none -o IdentitiesOnly=yes</code> option for the <code>ssh</code> command or add it to your <code>ssh_config</code> file for the relevant hosts:

has been fixed in OpenSSH 10.0. At least it works for me now without any intervention. [[User:Eta-carinae|Eta-carinae]] ([[User talk:Eta-carinae|talk]]) 21:06, 17 April 2025 (UTC)

== AddKeysToAgent requires default key names ==

I noticed that the {{ic|AddKeysToAgent}} option doesn't work if the public and private keys aren't named one of the default options presented when generating them.

More specifically: running {{ic|ssh -vT git@github.com}}, for example, gives:

{{bc|[...]
debug1: Next authentication method: publickey
debug1: get_agent_identities: bound agent to hostkey
debug1: get_agent_identities: ssh_fetch_identitylist: agent contains no identities
debug1: Will attempt key: /home/user/.ssh/id_rsa
debug1: Will attempt key: /home/user/.ssh/id_ecdsa
debug1: Will attempt key: /home/user/.ssh/id_ecdsa_sk
debug1: Will attempt key: /home/user/.ssh/id_ed25519
debug1: Will attempt key: /home/user/.ssh/id_ed25519_sk
debug1: Will attempt key: /home/user/.ssh/id_xmss
debug1: Trying private key: /home/user/.ssh/id_rsa
debug1: Trying private key: /home/user/.ssh/id_ecdsa
debug1: Trying private key: /home/user/.ssh/id_ecdsa_sk
debug1: Trying private key: /home/user/.ssh/id_ed25519
debug1: Trying private key: /home/user/.ssh/id_ed25519_sk
debug1: Trying private key: /home/user/.ssh/id_xmss
debug1: No more authentication methods to try.
git@github.com: Permission denied (publickey).
}}

Assuming that this is correct (I am making this discussion page partly because I'm not 100% sure it isn't), I think a note or warning has to be added next to the existing note on {{ic|AddKeysToAgent}}, in the section on generating keys, or in both to clarify this. Personally, I feel a note/warning next to the {{ic|AddKeysToAgent}} note would be best; if a user generated their keys with a non-default name they can just do {{ic|mv oldname default}} without needing to regenerate them. [[User:Elizabeth|Elizabeth]] ([[User talk:Elizabeth|talk]]) 21:31, 14 May 2025 (UTC)

:If you "add a key to the agent", it doesn't mean that you can move the original key anywhere in the file system. Identities are specified by path (see {{man|5|ssh_config|IdentityFile}}) and when the file does not exist, you get the error above. This has nothing to do with {{ic|AddKeysToAgent}}. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:09, 25 May 2025 (UTC)
::Noted, ill explore why what I did worked to fix this for me on my own then, and thanks for the help. [[User:Elizabeth|Elizabeth]] ([[User talk:Elizabeth|talk]]) 18:08, 27 May 2025 (UTC)

== Info on SSH Agent is obsolete ==

Many things about using an SSH agent are now obsolete, and will just confuse users. I suggest:

1. Removing the section on using ssh-agent as a wrapper program.

2. Removing the OpenPGP card ssh-agent section, and moving it to the OpenPGP page (just like it is done for GnuPH Agent).

3. Removing, or shortening Keychain section. I've used keychain for a long time myself; but now with the systemd activated socket (which can last multiple login sessions), and GPG handling it's own agent automatically, there's no reason to use keychain anymore. Move it to it's own page, and link to it from here.

4. The x11-ssh-askpass section belongs in the Keychain section, and not it's own subsection of ssh agents. (IMO it belongs in a separate page about keychain, which can be linked to from here.)

--[[User:Gi1242|Gi1242]] ([[User talk:Gi1242|talk]]) 13:58, 10 August 2025 (UTC)

:Honestly, after introducing ssh-agent, instead of the BashFu to ensure only one copy is running I would suggest:
:{{bc|<nowiki>
:if [[ -z $SSH_CONNECTION && -z $SSH_AUTH_SOCK ]]; then
: export SSH_AUTH_SOCK=$XDG_RUNTIME_DIR/ssh-agent.socket
:fi</nowiki>}}
:If the ssh agent is needed in systemd user scripts, then also do {{ic|<nowiki>systemctl --user set-environment SSH_AUTH_SOCK=$SSH_AUTH_SOCK</nowiki>}} [[User:Gi1242|Gi1242]] ([[User talk:Gi1242|talk]]) 14:14, 10 August 2025 (UTC)

Yt-dlp

2026-05-16T13:36:38Z

Indigo: /* Format selection */ add example for bestvideo, analog to bestaudio below

{{Lowercase title}}
[[Category:Download utilities]]
[[Category:Streaming]]
[[de:yt-dlp]]
[[es:Yt-dlp]]
[[ja:Youtube-dl]]
[[pl:Youtube-dl]]
[[uk:Youtube-dl]]
[[zh-hans:yt-dlp]]
{{Related articles start}}
{{Related|mpv}}
{{Related|FFmpeg}}
{{Related articles end}}

'''yt-dlp''' is a command-line program that lets you easily download videos and audio from more than a thousand websites. See the [https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md list of supported sites].

{{Note|yt-dlp is a fork of [https://ytdl-org.github.io/youtube-dl/ youtube-dl] that was created after the parent project became stagnant. The upstream youtube-dl can still be [[install]]ed as {{AUR|youtube-dl}}; commands on this page should still work, but check the [https://github.com/yt-dlp/yt-dlp#differences-in-default-behavior list of differences].}}

== Installation ==

[[Install]] the {{Pkg|yt-dlp}} package. See the optional dependencies, a notable one to install is [[FFmpeg]] for muxing on some sites.

There are also various [https://www.reddit.com/r/youtubedl/wiki/info-guis graphical frontends] to yt-dlp, such as {{AUR|tartube}} and {{AUR|yt-dlg-git}}.

You can also install {{AUR|yt-dlp-drop-in}} which provides a dummy {{ic|/usr/bin/youtube-dl}} executable (that just redirects to ''yt-dlp'') for outdated programs that still look for a ''youtube-dl'' executable.

== Configuration ==

The system-wide configuration file is {{ic|/etc/yt-dlp.conf}} and the user-specific configuration file is {{ic|~/.config/yt-dlp/config}}. The syntax is simply one command-line option per line. Example configuration:

--ignore-errors
# --no-playlist

# Save in ~/Videos
-o ~/Videos/%(title)s.%(ext)s

# Prefer 1080p or lower resolutions
-f bestvideo[height<=?1080]+bestaudio/best

See [https://github.com/yt-dlp/yt-dlp/blob/master/README.md#configuration] for more information.

A custom configuration file can also be specified with:

$ yt-dlp ''URL'' --config-locations ''PATH''

== Usage ==

See {{man|1|yt-dlp}} for the manual.

$ yt-dlp [OPTIONS] ''URL''

{{tip|In some cases (like YouTube) {{ic|''URL''}} can be substituted with the video ID.}}

=== Format selection ===

When multiple formats of a video are available, ''youtube-dl'' will download the best ones by default.

To get a list of the available formats:

$ yt-dlp -F ''URL''

To select a specific one to download:

$ yt-dlp -f ''format'' ''URL''

To automatically select the best video format, but exclude specific formats - for example, when the system does not support H.265:

$ yt-dlp -f "bestvideo[vcodec!=h265]+bestaudio" ''URL''

=== Extract audio ===

Use {{ic|-x}} for audio-only downloads (requires [[FFmpeg]]):

$ yt-dlp -x -f bestaudio ''URL''

Depending on the available source streams, this will often correct the audio-only container. If an audio-only stream is not available, exclude {{ic|-f bestaudio}} from the example above. This will download the video and copy its audio as post process. By default this will remove the downloaded video, include {{ic|-k}} to keep it.

To also include album art (requires {{Pkg|atomicparsley}}):

$ yt-dlp -x -f bestaudio[ext=m4a] --add-metadata --embed-thumbnail ''URL''

=== Subtitles ===

To see which languages are available:

$ yt-dlp --list-subs ''URL''

To download a video with selected subtitles (comma separated):

$ yt-dlp --write-sub --sub-lang ''LANG'' ''URL''

For auto-generated subtitles:

$ yt-dlp --write-auto-sub --sub-lang ''LANG'' ''URL''

Add {{ic|--skip-download}} to get only subtitles.

=== Cookies ===

To import cookies add the {{ic|--cookies-from-browser <browser>}}

Example of importing cookies from chromium

$ yt-dlp --cookies-from-browser chromium ''URL''

== Tips and tricks ==

=== Faster downloads ===

Some websites throttle transfer speeds. You can often get around this by choosing non DASH streams or by using [[aria2]], an external downloader which supports multi-connection downloads. For example:

$ yt-dlp --downloader aria2c --downloader-args '-c -j 3 -x 3 -s 3 -k 1M' ''URL''

=== Playlist ===

Using youtube-dl for a playlist usually boils down to the following options:

$ yt-dlp --ignore-errors --continue --no-overwrites --download-archive progress.txt ''usual options'' ''URL''

This set of options allow for the download to effectively continue even after interruption. If you are archiving, add the usual {{ic|--write-xxx}} and {{ic|--embed-xxx}} options you may have.

=== Trim (partial download) ===

Parts of videos can be downloaded by using the output of {{ic|yt-dlp -g -f ''format'' ''URL''}} as ''ffmpeg'' input with the {{ic|-ss}} (for input), {{ic|-t}} and {{ic|-c copy}} [https://ffmpeg.org/ffmpeg.html#Main-options options].

=== URL from clipboard ===

A shell [[alias]], a [[desktop launcher]] or a keyboard shortcut can be set to download a video (or audio) of a selected (or copied) URL by outputting it from the [[Wikipedia:X_Window_selection|X selection]]. See [[Clipboard#Tools]].

== See also ==

* [https://github.com/yt-dlp/yt-dlp GitHub repository] for documentation.

MEncoder

2026-05-16T13:09:23Z

Indigo: /* Basics */ adjust external link title

[[Category:Multimedia]]
[[ja:MEncoder]]
{{Related articles start}}
{{Related|DVD Ripping}}
{{Related|MPlayer}}
{{Related|Video2dvdiso}}
{{Related articles end}}
An overview of [[Wikipedia:MEncoder|MEncoder]], the video encoding/decoding tool provided by [[MPlayer]] as part of the {{Pkg|mencoder}} package.

== Basics ==

The basic syntax for a conversion is:

$ mencoder ''original_video''.mpg -o ''new_video''.avi -ovc ''output_video_codec'' -oac ''output_audio_codec''

This is basically how one converts a video. However, there are '''many''' more options available.

For input formats, MEncoder can use any format that MPlayer can play, so to verify whether it will work with your video, just try playing it in MPlayer.

To list ''o''utput ''v''ideo ''c''odecs, run:

$ mencoder -ovc help

Similarly, to list ''o''utput ''a''udio ''c''odecs, run:

$ mencoder -oac help

This information can also be found in the [https://mplayerhq.hu/DOCS/HTML/en/menc-feat-selecting-codec.html project online documentation] where it is better explained, although non-specific.

== Example ==

This approach allows one to make a .mkv file with an [[Wikipedia:H.264/MPEG-4 AVC|H.264]]-encoded video and any number of Vorbis-encoded audio tracks.

We will use ''mencoder'' for ripping and encoding and ''mkvmerge'' (part of {{Pkg|mkvtoolnix-cli}}) for making the ''.mkv'' file itself.

=== Ripping and encoding the video ===

The H.264 encoder is usually used in two passes: the first reads information about the movie, the second uses that information to encode. We will not extract any audio for now.

Commands follow; remember to replace the variables with the proper values:

First pass: we are just collecting information, so the normal output is thrown away:

{{bc|1=
$ mencoder -dvd-device "$ISO" dvd://"$TITLE" -chapter "$CHAPTER" -o /dev/null -nosound -ovc x264 \
-x264encopts direct=auto:pass=1:turbo:bitrate=900:bframes=1:\
me=umh:partitions=all:trellis=1:qp_step=4:qcomp=0.7:direct_pred=auto:keyint=300 \
-vf scale=-1:-10,harddup
}}

Second pass: here we compress the video track using the information from the first step:

{{bc|1=
$ mencoder -dvd-device "$ISO" dvd://"$TITLE" -chapter "$CHAPTER" -nosound -ovc x264 \
-x264encopts direct=auto:pass=2:bitrate=900:frameref=5:bframes=1:\
me=umh:partitions=all:trellis=1:qp_step=4:qcomp=0.7:direct_pred=auto:keyint=300 \
-vf scale=-1:-10,harddup -o video.avi
}}

This will create a {{ic|video.avi}} file containing the video. You can play with the {{ic|-x264encopts}} options and the {{ic|-vf}} filters to improve the quality or reduce the file size. For example, a movie with a black border should be cropped with {{ic|1=-vf crop=$X:$Y,scale=-1:-10,harddup}} with the proper values instead of {{ic|$X}} and {{ic|$Y}} (see {{man|1|mencoder|3=cropdetect_=limit:round_:reset__|fragment=cropdetect_=limit:round_:reset__}}). You may want to scale down the movie with {{ic|1=-vf scale=$WIDTH:-10,harddup}} the width of the movie will become {{ic|$WIDTH}} (keep {{ic|$WIDTH}} a multiple of 16: 640, 480, or 320 are usually fine), the height will be correctly calculated in order to keep the aspect ratio.

You can also use any other of the filters MEncoder has to offer, like {{ic|pullup,softskip}} or you can change the frame rate using {{ic|-ofps}}. (If you do so, remember to use the same frame rate everywhere including in the commands to rip audio.)

It is important that you use {{ic|harddup}} as the last filter: it will force MEncoder to write every frame (even duplicate ones) in the output. Also, it is necessary to use {{ic|1=scale=$WIDTH,-10}}} with {{ic|$WIDTH}} as {{ic|-1}} to keep the original width or a new, usually smaller, width: it is necessary since the H.264 codec uses square pixels and DVDs instead use rectangular pixels.

=== Ripping and encoding the audio ===

You can extract audio tracks as needed. Here we compress with the Vorbis algorithm, but you may want to check the MEncoder manual in order to see alternatives.

The command follows (replace the variables with desired values) where we rip and compress the audio:

$ mencoder -dvd-device "$ISO" dvd://"$TITLE" -alang "$AUDIOLANG" -chapter "$CHAPTER" -ovc frameno \
-oac lavc -lavcopts acodec=vorbis:abitrate=224 -channels 2 -srate 48000 -o "$AUDIOLANG".avi

You should repeat the command for every audio track you want, so we will have .avi files with the audio track.

You may also want to use {{ic|-channels 6}} to exact all the channels of a 5.1 DVD or changing the bit rate. As with the video, you can use audio filters via {{ic|-af}} but it is not necessary.

=== Making the final .mkv file ===

Putting it all together in a single file is simple. Add other audio tracks if needed:

$ mkvmerge -D audio.avi -A video.avi -o mymovie.mkv

The ''.mkv'' file will contain everything, so you can store your movie keeping all the audio track you want. Even if you are not interested in keeping multiple sound tracks, the H.264/Vorbis format pair should ensure great quality.

=== Encoding for Nokia 5800 XM and Nokia N97 ===

In '''2 pass'''es with small bitrates (640kbps video vbitrate and 96kbps audio abitrate) yields pretty watchable video mp4 for Nokia 5800 xm and Nokia N97 phones' default video player.

==== mkv to mp4 (nokia 97, 5800 compatible) ====

# convert the mkv to mpg ; many mkv files do not directly get converted to mp4: {{bc|1=$ mencoder ''original_file''.mkv -ovc lavc -lavcopts vcodec=mpeg1video -aid 0 -oac pcm -o delete_me.mpg}}
# convert the mpg file to mp4: {{bc|1=<nowiki>$ mencoder -of lavf -lavfopts format=mp4 -oac lavc -ovc lavc \
-lavcopts aglobal=1:vglobal=1:acodec=libfaac:vcodec=mpeg4:abitrate=128:vbitrate=640:keyint=250:mbd=1:vqmax=10:lmax=10:turbo \
-af lavcresample=44100 -vf harddup,scale=640:-3 "delete_me.mpg" -o "converted_file.mp4"
</nowiki>}}
#delete the temporary huge sized mpg file: {{bc|$ rm "delete_me.mpg"}}

Here {{ic|-aid 0}} is the first audio track in the original mkv.

==== avi to mp4 (nokia 97, 5800 compatible) using multipass (2 passes) ====

# First pass: {{bc|1=<nowiki>$ mencoder -of lavf -lavfopts format=mp4 -oac lavc -ovc lavc \
-lavcopts aglobal=1:vglobal=1:acodec=libfaac:vcodec=mpeg4:abitrate=96:vbitrate=640:keyint=250:mbd=1:vqmax=10:lmax=10:vpass=1:turbo \
-af lavcresample=44100 -vf harddup,scale=640:-3 "video.avi" -o "video.mp4"
</nowiki>}}
# Second pass: {{bc|1=<nowiki>$ mencoder -of lavf -lavfopts format=mp4 -oac lavc -ovc lavc \
-lavcopts aglobal=1:vglobal=1:acodec=libfaac:vcodec=mpeg4:abitrate=96:vbitrate=640:keyint=250:mbd=1:vqmax=10:lmax=10:vpass=2 \
-af lavcresample=44100 -vf harddup,scale=640:-3 "video.avi" -o "video.mp4"
</nowiki>}}

Play around with abitrate, vbitrate, and scale values to get video quality and size of your liking.

{{ic|1=scale=640:-3}} will try to keep the video width to 640 and resize the video height accordingly. Do use the "original" aspect in Nokia's mp4 player ''Option > aspect'' for 16:9 and 4:3 aspect ratio videos.

=== Encoding a multi audio / multi language MKV video to an MP4 with different audio streams ===

To encode multi-audio file to mp4 we need to use the {{ic|-aid ''audio_stream_number''}} like {{ic|-map 0:1}} in ''ffmpeg''.

# To extract video+audio stream1 (e.g. english) of mkv file: {{bc|$ mencoder -oac copy -ovc copy '''-aid 0''' sample.mkv -o sample.mp4}}
# To extract video+audio stream2 (e.g. Hindi, French, etc.) of mkv file: {{bc|$ mencoder -oac copy -ovc copy '''-aid 1''' sample.mkv -o sample.mp4}}

=== Adding SubRip subtitles to a file ===

The following output video codec ({{ic|-ovc}}) options are suggested as very high-quality settings and should suffice for most transcoding, including the addition of subtitles to a stream.

==== Two-pass x264 (very high-quality) ====

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc x264 \
-x264encopts pass=1:preset=veryslow:fast_pskip=0:tune=film:frameref=15:bitrate=3000:threads=auto \
-sub original_video.srt -subfont-text-scale 3 -o /dev/null
}}

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc x264 \
-x264encopts pass=2:preset=veryslow:fast_pskip=0:tune=film:frameref=15:bitrate=3000:threads=auto \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

* {{ic|1=fast_pskip=0}} is a maximum quality {{ic|placebo}} preset option.
* {{ic|frameref}} is the only other major option undefined by {{ic|preset}} settings.
* {{ic|bitrate}} values can be modified to suit desired file size and quality needs.
* {{ic|tune}} should be set to match the type and content of the media being encoded.

==== Single-pass x264 (very high-quality) ====

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc x264 \
-x264encopts preset=veryslow:tune=film:crf=15:frameref=15:fast_pskip=0:threads=auto \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

* The following example uses the option {{ic|-of lavf}} to mux the output into a [[Wikipedia:Matroska|Matroska]] container which is autodetected from the output file extension ''.mkv'': {{bc|1=<nowiki>
mencoder original_video.avi -oac copy -of lavf -ovc x264 \
-x264encopts preset=veryslow:tune=film:crf=15:frameref=15:fast_pskip=0:global_header:threads=auto \
-sub original_video.srt -subfont-text-scale 3 -o output_video.mkv
</nowiki>}}
* {{ic|global_header}} writes global video headers to extradata, or in front of keyframes and is typically required for .mp4 and .mkv containers.

==== Two-pass xvid (very high-quality) ====

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc xvid \
-xvidencopts pass=1:chroma_opt:vhq=4:max_bframes=1:quant_type=mpeg:threads=6 \
-sub original_video.srt -subfont-text-scale 3 -o /dev/null
}}

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc xvid \
-xvidencopts pass=2:chroma_opt:vhq=4:max_bframes=1:quant_type=mpeg:bitrate=3000:threads=6 \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

* {{ic|1=threads=n}} where n = physical, or CPU cores.
* Recent versions of mencoder enable {{ic|1=bvhq=1}} as a default setting.
* Xvid does not accept {{ic|bitrate}} settings on the first of multiple-pass encodings.
* {{ic|subfont-text-scale 2-3}} helps with proper sizing with 16:9 format screens.
* {{ic|1=max_bframes=0}} can be set so long as the bitrate is high enough.

==== Three-pass lavc (very high-quality mpeg4) ====

{{bc|1=
$ mencoder original_video.avi -oac copy -ffourcc DX50 -ovc lavc \
-lavcopts vpass=1:mbd=2:mv0:trell:v4mv:cbp:predia=6:dia=6:precmp=6:cmp=6:subcmp=6:preme=2:qns=2:vbitrate=3000 \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

{{bc|1=
$ mencoder original_video.avi -oac copy -ffourcc DX50 -ovc lavc \
-lavcopts vpass=3:mbd=2:mv0:trell:v4mv:cbp:predia=6:dia=6:precmp=6:cmp=6:subcmp=6:preme=2:qns=2:vbitrate=3000 \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

{{bc|1=
$ mencoder original_video.avi -oac copy -ffourcc DX50 -ovc lavc \
-lavcopts vpass=3:mbd=2:mv0:trell:v4mv:cbp:predia=6:dia=6:precmp=6:cmp=6:subcmp=6:preme=2:qns=2:vbitrate=3000 \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

* Introducing {{ic|1=threads=n}} (with n above 1) for {{ic|-vcodec mpeg4}} may skew the effects of [[Wikipedia:Motion_estimation|motion estimation]] and lead to [https://ffmpeg.org/faq.html#SEC16 reduced video quality] and compression efficiency.
* {{ic|1=predia=6:dia=6:precmp=6:cmp=6:subcmp=6}} to {{ic|1=predia=3:dia=3:precmp=3:cmp=3:subcmp=3}} can reduce encoding times without incurring much loss in quality.
* {{ic|vmax_b_frames}} not included as referenced in the official mencoder documentation as the current default setting is to not to use [[Wikipedia:Video_compression_picture_types|B-frames]] at all.
* {{ic|vb_strategy}} not included as referenced in the official mencoder documentation for the same reason as above. Else {{ic|1=vb_strategy=2}}.

==== Single-pass lavc (very high-quality mpeg-2) ====

{{bc|1=
$ mencoder -mc 0 -noskip -oac lavc -ovc lavc -of mpeg -mpegopts format=dvd:tsaf -vf scale=720:576,harddup -srate 48000 -af lavcresample=48000 \
-lavcopts vcodec=mpeg2video:vrc_buf_size=1835:vrc_maxrate=9800:vbitrate=5000:keyint=15:vstrict=0:acodec=mp2:abitrate=192:aspect=16/9 \
-sub-bg-alpha 100 -subpos 95 -subfont-text-scale 2.5 -subcp cp1250 -sub subFile.srt -o outFile.mpg inFile.mkv
}}

* {{ic|-mc 0 -noskip}} to ensure A/V sync
* {{ic|aspect}} - setting video aspect manually
* subtitle background, subtitle encoding and subtitle scaling

There are as always many options that can be set, this combination ensures that picture looks almost the same as original with slightly smaller file size (great for converting FULL HD videos so that they are playable on older devices).

=== Adding VOBsub subtitles to a file ===

==== Two-pass x264 (very high-quality) ====

* Direct {{ic|-vobsub}} to the {{ic|subtitle_file}} using the full pathname of the file without extensions (''.idx'' or ''.sub'').
* Select the second subtitle ID language ({{ic|-vobsubid 2}}) contained within the VOBsub files (''.idx'' or ''.sub'').

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc x264 \
-x264encopts pass=1:preset=veryslow:fast_pskip=0:tune=film:frameref=15:bitrate=3000:threads=auto \
-vobsub subtitle_file -vobsubid 2 -o /dev/null
}}

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc x264 \
-x264encopts pass=2:preset=veryslow:fast_pskip=0:tune=film:frameref=15:bitrate=3000:threads=auto \
-vobsub subtitle_file -vobsubid 2 -o output_video.avi
}}

==== Testing subtitle muxing results ====

Avoid passing resource intensive encoding options in order to verify desired results sooner rather than later.

===== Single-pass x264 (low quality) =====

{{bc|1=
$ mencoder original_video.avi -oac copy -ovc x264 \
-x264encopts preset=ultrafast:threads=auto \
-sub original_video.srt -subfont-text-scale 3 -o output_video.avi
}}

=== mp2 vs. mp3lame vs. aac ===

* {{Pkg|toolame}} is recommended over [https://www.ffmpeg.org/ FFmpeg] lavc (libavcodec) for mp2 encoding.
* [https://lame.sourceforge.net/ mp3lame] is recommended over [https://faac.sourceforge.net/ FAAC] (not fully developed) encoding at all bitrates.

=== Encoding AVI videos in Windows and Mac readable formats ===

Use these commands:

$ opt="vbitrate=2160000:mbd=2:keyint=132:vqblur=1.0:cmp=2:subcmp=2:dia=2:mv0:last_pred=3"
$ mencoder -ovc lavc -lavcopts vcodec=msmpeg4v2:vpass=1:$opt -oac mp3lame -o /dev/null input.avi
$ mencoder -ovc lavc -lavcopts vcodec=msmpeg4v2:vpass=2:$opt -oac mp3lame -o output.avi input.avi

{{ic|input.avi}} is the AVI you made using Linux utilities, and "output.avi" is the AVI you want to make which will be readable by Windows and Mac users.

== GUI frontends ==

The official MPlayer homepage has a comprehensive list of available front-ends [http://www.mplayerhq.hu/design7/projects.html#mencoder_frontends here].

* {{App|OGMRip|An application and a set of libraries for ripping and encoding DVD into AVI, OGM, MP4, or Matroska files using a wide variety of codecs. It relies on mplayer, mencoder, ogmtools, mkvtoolnix, mp4box, oggenc, lame, and faac to perform its tasks.|https://ogmrip.sourceforge.net/|{{AUR|ogmrip}}}}
* {{App|Hybrid|A multi platform (Linux/macOS/Windows) Qt based frontend for a bunch of other tools which can convert nearly every input to x264/Xvid/VP8 + ac3/ogg/mp3/aac/flac inside an avi/mp4/m2ts/mkv/webm container, a BluRay or an AVCHD structure.|https://www.selur.de/|{{AUR|hybrid-encoder}}}}
* {{App|Hyper Video Converter|A frontend for various cli videoencoder tools I have made because I wanted something, that lets me quickly convert videos from konqueror without typing 3-line-commands in the console.|https://hypervideoconve.sourceforge.net/|{{AUR|hypervc-qt4}}}}
* {{App|jmencode|A simple java front-end for the free and very useful MPlayer software, for the purpose of encoding video. Initially the focus is on converting DVD into MPEG-4.|https://jmencode.sourceforge.net/|{{AUR|jmencode}}}}

Mobile phone

2026-05-16T12:47:19Z

Indigo: remove stray masking from redirect

#REDIRECT [[Category:Mobile devices]]

HTML

2026-05-16T12:44:58Z

Indigo: remove stray category from redirect

#REDIRECT [[Category:Web]]

Init

2026-05-15T11:14:02Z

Indigo: /* Rootless X */ add talk to template

{{Lowercase title}}
[[Category:Init]]
[[es:Init]]
[[hu:Init]]
[[ja:Init]]
[[pt:Init]]
[[zh-hans:Init]]
{{Related articles start}}
{{Related|Arch boot process}}
{{Related|ConsoleKit}}
{{Related|Init package guidelines}}
{{Related articles end}}

{{Warning|Arch Linux only has official support for [[systemd]]. [https://lists.archlinux.org/archives/list/arch-general@lists.archlinux.org/message/RSVHZP56KEQ4C6PRTROIMJRM45MTOFK7/] When using a different init system, please mention so in support requests.}}

[[Wikipedia:Init|Init]] is the first process started during system boot. It is a daemon process that continues running until the system is shut down. Init is the direct or indirect ancestor of all other processes, and automatically adopts all orphaned processes. It is started by the kernel using a hard-coded filename; if the kernel is unable to start it, [[Kernel panic|panic]] will result. Init is typically assigned [[Wikipedia:process identifier|process identifier]] 1.

The init ''scripts'' (or ''rc'') are launched by the init process to guarantee basic functionality on system start and shutdown. This includes (un)mounting of [[file system]]s and launching of [[daemons]]. A ''service manager'' takes this one step further by providing active control over launched processes, or [[Wikipedia:Process Supervision|process supervision]]. An example is to monitor for crashes and restart processes accordingly.

These components combine to the init ''system''. Some inits include the service manager in the init process, or have init scripts in close relation to them. These inits are below referred to as ''integrated'', though entries in different categories may explicitly depend on each other.

== Inits (integrated) ==

* {{App|anopa|Init system built around the s6 supervision suite.|https://jjacky.com/anopa/|{{AUR|anopa}}}}
* {{App|GNU Shepherd|Init system written in [https://www.gnu.org/software/guile/ Guile].|https://www.gnu.org/software/shepherd/|{{AUR|shepherd}}}}
* {{App|[[OpenRC]]|Dependency-based init system.|https://www.gentoo.org/proj/en/base/openrc/|{{AUR|openrc}} {{AUR|openrc-arch-services-git}}}}
* {{App|[[systemd]]|Dependency-based init system with aggressive parallelization, process supervision using cgroups, and the ability to depend on a given mount point or dbus service.|https://systemd.io/|{{Pkg|systemd}}}}

== Inits ==

* {{App|[[BusyBox]]|Utilities for rescue and embedded systems.|https://busybox.net/|{{Pkg|busybox}}}}
* {{App|sinit|Simple init initially based on Rich Felker’s minimal init.|https://core.suckless.org/sinit|{{AUR|sinit}}}}

== Init scripts ==

* {{App|kisslinux-init|Init framework of KISS Linux.|https://github.com/kisslinux/init|{{AUR|kisslinux-init}}}}

== Service managers ==

* {{App|[[Monit]]|Monit is a process supervision tool for Unix and Linux. With monit, system status can be viewed directly from the command line, or via the native HTTP(S) web server.|https://mmonit.com/monit/|{{Pkg|monit}}}}
* {{App|perp|Persistent process (service) supervisor and management framework for UNIX.|http://b0llix.net/perp/|{{AUR|perp}}}}
* {{App|[[runit]]|UNIX init scheme with service supervision, a replacement for SysVinit, and other init schemes.|https://smarden.org/runit/|{{Pkg|busybox}}}}
* {{App|s6|Small suite of programs for UNIX, designed to allow service supervision in the line of daemontools and runit.|https://skarnet.org/software/s6/|{{AUR|s6}}}}
* {{App|Supervisor|A system that allows its users to monitor and control processes on UNIX-like operating systems.|https://supervisord.org/|{{Pkg|supervisor}}}}

== Configuration ==

=== Migrate running services ===

To run daemons under the new init, save a list of running daemons:

$ systemctl list-units --state=running "*.service" > daemons.list

and configure the [[#Init scripts]] accordingly. See also [https://unix.stackexchange.com/questions/175380/how-to-list-all-running-daemons].

{{Note|{{man|8|systemd-tmpfiles}}, [[kernel modules]] and [[sysctl]] may also need configuration.}}

=== logind ===

[https://www.freedesktop.org/wiki/Software/systemd/logind/ logind] requires ''systemd'' to be the init process. [https://systemd.io/PORTABILITY_AND_STABILITY/] As such, [[General troubleshooting#Session permissions|local sessions]] and other functionality is not available.

=== Device permissions ===

Add users to respective [[user group]]s for device access and reboot. Current group membership should first be checked with {{ic|id ''user''}}.

# usermod -a -G video,audio,power,disk,storage,optical,lp,scanner,input ''user''

See also [[Users and groups#Pre-systemd groups]]. To create group rules for use with [[Polkit]], see [[Polkit#Bypass password prompt]].

=== Rootless X ===

{{Accuracy|People on [https://github.com/void-linux/void-docs/issues/547 Void Linux] can get X runnning rootless even without logind, we should probably promote this instead of suggesting to run X as root.|section=rootless X void workaround}}

As {{ic|Xorg.wrap}} does not check if logind is active [https://bugs.freedesktop.org/show_bug.cgi?id=86975#c5], root rights for Xorg need be [[Xorg#Xorg as Root|enabled manually]].

=== Power management ===

See {{AUR|pm-utils}} and [[acpid]] to replace [[Systemd#Power management|Power management with systemd]].

=== Scheduled tasks ===

Arch uses [[systemd/Timers|timer]] files instead of [[cron]] by default.

=== Dbus ===

{{Expansion|1=Explanative section removed with [[Special:Diff/458617|458617]]}}

User instances of ''dbus-daemon'' are launched by [[systemd/User]] [https://archlinux.org/news/d-bus-now-launches-user-buses/]. When requiring IPC between desktop applications, restore {{ic|30-dbus.sh}}:

{{hc|1=/etc/X11/xinit/xinitrc.d/30-dbus.sh|2=
#!/bin/bash

# launches a session dbus instance
if [ -z "${DBUS_SESSION_BUS_ADDRESS-}" ] && type dbus-launch >/dev/null; then
eval $(dbus-launch --sh-syntax --exit-with-session)
fi
}}

== Tips and tricks ==

=== systemd-nspawn ===

[[systemd-nspawn]] is a tool for systemd systems. Since Linux 2.6.19, it is possible, however, to run systemd on a non-systemd system by using PID namespace. For it, the kernel needs to be configured with {{ic|CONFIG_PID_NS}} and {{ic|CONFIG_NAMESPACES}}).

The PID namespace creates a new hierarchy of processes starting with PID 1. In addition to this, systemd requires a chrooted root filesystem to be mounted. Hence, you have to at least make a bind mount, because otherwise some services will fail with

"Failed at step NAMESPACE spawning" due to "Invalid operation"

as systemd tries to remount the root with {{ic|private}} option.

To setup a chroot with a new PID namespace, you can use jchroot.[https://vincent.bernat.im/en/blog/2011-jchroot-isolation.html] [https://github.com/vincentbernat/jchroot].
Make sure not to mount {{ic|/proc}} inside the new root before chrooting, otherwise systemd will detect the chroot environment. You can mount it later once systemd is running.

=== Replacing udev ===

{{Warning|Replacing udev is not required as ''systemd-udev'' is functional without ''systemd'' as PID 1. Some replacements can also not coexist with {{Pkg|systemd}}—ensure an alternative init is booted '''prior''' to their installation.}}

* {{App|mdev|Device manager for usage in embedded systems.|https://git.busybox.net/busybox/plain/docs/mdev.txt|{{Pkg|busybox}}}}
* {{App|smdev|smdev is a simple program to manage device nodes. It is mostly compatible with mdev but does not have all of its features.|https://git.suckless.org/smdev/|{{AUR|smdev}}}}

== See also ==

* [[Debian:Debate/initsystem]]
* [https://skarnet.org/software/s6/s6-svscan-1.html How to run s6-svscan as process 1]
* [https://bbs.archlinux.org/viewtopic.php?id=162606&p=1 Replace systemd with busybox + minirc]
* [https://busybox.net/~vda/init_vs_runsv.html Init vs. runsv]
* [https://felipec.wordpress.com/2013/11/04/init/ Demystifying the init system]
* [https://web.archive.org/web/20201108092524/https://blog.darknedgy.net/technology/2015/09/05/0/ A history of modern init systems (1992-2015)]
* [[Gentoo:Comparison of init systems]]
* [https://github.com/InitWare/InitWare/wiki/Contributors'-Study-Guide InitWare: Contributors' Study Guide]
* [https://jdebp.uk/Softwares/nosh/ The nosh package]

Talk:Init

2026-05-15T11:13:21Z

Indigo: /* rootless X void workaround */ new section

== rootless X void workaround ==

To my understanding the Void discussion offers two solutions: (1) adding users to the input group (unsafe as they note) and (2) relying on elogind, a forked systemd-logind (for X during packaging and thereafter). Did I miss a solution? What should be promoted? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 11:13, 15 May 2026 (UTC)

Init

2026-05-15T10:50:59Z

Indigo: /* Scheduled tasks */ remove sentence with 404 link (not found in aur either); cron would be better suited for it anyway, and repo has both cronie and fcron options

{{Lowercase title}}
[[Category:Init]]
[[es:Init]]
[[hu:Init]]
[[ja:Init]]
[[pt:Init]]
[[zh-hans:Init]]
{{Related articles start}}
{{Related|Arch boot process}}
{{Related|ConsoleKit}}
{{Related|Init package guidelines}}
{{Related articles end}}

{{Warning|Arch Linux only has official support for [[systemd]]. [https://lists.archlinux.org/archives/list/arch-general@lists.archlinux.org/message/RSVHZP56KEQ4C6PRTROIMJRM45MTOFK7/] When using a different init system, please mention so in support requests.}}

[[Wikipedia:Init|Init]] is the first process started during system boot. It is a daemon process that continues running until the system is shut down. Init is the direct or indirect ancestor of all other processes, and automatically adopts all orphaned processes. It is started by the kernel using a hard-coded filename; if the kernel is unable to start it, [[Kernel panic|panic]] will result. Init is typically assigned [[Wikipedia:process identifier|process identifier]] 1.

The init ''scripts'' (or ''rc'') are launched by the init process to guarantee basic functionality on system start and shutdown. This includes (un)mounting of [[file system]]s and launching of [[daemons]]. A ''service manager'' takes this one step further by providing active control over launched processes, or [[Wikipedia:Process Supervision|process supervision]]. An example is to monitor for crashes and restart processes accordingly.

These components combine to the init ''system''. Some inits include the service manager in the init process, or have init scripts in close relation to them. These inits are below referred to as ''integrated'', though entries in different categories may explicitly depend on each other.

== Inits (integrated) ==

* {{App|anopa|Init system built around the s6 supervision suite.|https://jjacky.com/anopa/|{{AUR|anopa}}}}
* {{App|GNU Shepherd|Init system written in [https://www.gnu.org/software/guile/ Guile].|https://www.gnu.org/software/shepherd/|{{AUR|shepherd}}}}
* {{App|[[OpenRC]]|Dependency-based init system.|https://www.gentoo.org/proj/en/base/openrc/|{{AUR|openrc}} {{AUR|openrc-arch-services-git}}}}
* {{App|[[systemd]]|Dependency-based init system with aggressive parallelization, process supervision using cgroups, and the ability to depend on a given mount point or dbus service.|https://systemd.io/|{{Pkg|systemd}}}}

== Inits ==

* {{App|[[BusyBox]]|Utilities for rescue and embedded systems.|https://busybox.net/|{{Pkg|busybox}}}}
* {{App|sinit|Simple init initially based on Rich Felker’s minimal init.|https://core.suckless.org/sinit|{{AUR|sinit}}}}

== Init scripts ==

* {{App|kisslinux-init|Init framework of KISS Linux.|https://github.com/kisslinux/init|{{AUR|kisslinux-init}}}}

== Service managers ==

* {{App|[[Monit]]|Monit is a process supervision tool for Unix and Linux. With monit, system status can be viewed directly from the command line, or via the native HTTP(S) web server.|https://mmonit.com/monit/|{{Pkg|monit}}}}
* {{App|perp|Persistent process (service) supervisor and management framework for UNIX.|http://b0llix.net/perp/|{{AUR|perp}}}}
* {{App|[[runit]]|UNIX init scheme with service supervision, a replacement for SysVinit, and other init schemes.|https://smarden.org/runit/|{{Pkg|busybox}}}}
* {{App|s6|Small suite of programs for UNIX, designed to allow service supervision in the line of daemontools and runit.|https://skarnet.org/software/s6/|{{AUR|s6}}}}
* {{App|Supervisor|A system that allows its users to monitor and control processes on UNIX-like operating systems.|https://supervisord.org/|{{Pkg|supervisor}}}}

== Configuration ==

=== Migrate running services ===

To run daemons under the new init, save a list of running daemons:

$ systemctl list-units --state=running "*.service" > daemons.list

and configure the [[#Init scripts]] accordingly. See also [https://unix.stackexchange.com/questions/175380/how-to-list-all-running-daemons].

{{Note|{{man|8|systemd-tmpfiles}}, [[kernel modules]] and [[sysctl]] may also need configuration.}}

=== logind ===

[https://www.freedesktop.org/wiki/Software/systemd/logind/ logind] requires ''systemd'' to be the init process. [https://systemd.io/PORTABILITY_AND_STABILITY/] As such, [[General troubleshooting#Session permissions|local sessions]] and other functionality is not available.

=== Device permissions ===

Add users to respective [[user group]]s for device access and reboot. Current group membership should first be checked with {{ic|id ''user''}}.

# usermod -a -G video,audio,power,disk,storage,optical,lp,scanner,input ''user''

See also [[Users and groups#Pre-systemd groups]]. To create group rules for use with [[Polkit]], see [[Polkit#Bypass password prompt]].

=== Rootless X ===

{{Accuracy|People on [https://github.com/void-linux/void-docs/issues/547 Void Linux] can get X runnning rootless even without logind, we should probably promote this instead of suggesting to run X as root.}}

As {{ic|Xorg.wrap}} does not check if logind is active [https://bugs.freedesktop.org/show_bug.cgi?id=86975#c5], root rights for Xorg need be [[Xorg#Xorg as Root|enabled manually]].

=== Power management ===

See {{AUR|pm-utils}} and [[acpid]] to replace [[Systemd#Power management|Power management with systemd]].

=== Scheduled tasks ===

Arch uses [[systemd/Timers|timer]] files instead of [[cron]] by default.

=== Dbus ===

{{Expansion|1=Explanative section removed with [[Special:Diff/458617|458617]]}}

User instances of ''dbus-daemon'' are launched by [[systemd/User]] [https://archlinux.org/news/d-bus-now-launches-user-buses/]. When requiring IPC between desktop applications, restore {{ic|30-dbus.sh}}:

{{hc|1=/etc/X11/xinit/xinitrc.d/30-dbus.sh|2=
#!/bin/bash

# launches a session dbus instance
if [ -z "${DBUS_SESSION_BUS_ADDRESS-}" ] && type dbus-launch >/dev/null; then
eval $(dbus-launch --sh-syntax --exit-with-session)
fi
}}

== Tips and tricks ==

=== systemd-nspawn ===

[[systemd-nspawn]] is a tool for systemd systems. Since Linux 2.6.19, it is possible, however, to run systemd on a non-systemd system by using PID namespace. For it, the kernel needs to be configured with {{ic|CONFIG_PID_NS}} and {{ic|CONFIG_NAMESPACES}}).

The PID namespace creates a new hierarchy of processes starting with PID 1. In addition to this, systemd requires a chrooted root filesystem to be mounted. Hence, you have to at least make a bind mount, because otherwise some services will fail with

"Failed at step NAMESPACE spawning" due to "Invalid operation"

as systemd tries to remount the root with {{ic|private}} option.

To setup a chroot with a new PID namespace, you can use jchroot.[https://vincent.bernat.im/en/blog/2011-jchroot-isolation.html] [https://github.com/vincentbernat/jchroot].
Make sure not to mount {{ic|/proc}} inside the new root before chrooting, otherwise systemd will detect the chroot environment. You can mount it later once systemd is running.

=== Replacing udev ===

{{Warning|Replacing udev is not required as ''systemd-udev'' is functional without ''systemd'' as PID 1. Some replacements can also not coexist with {{Pkg|systemd}}—ensure an alternative init is booted '''prior''' to their installation.}}

* {{App|mdev|Device manager for usage in embedded systems.|https://git.busybox.net/busybox/plain/docs/mdev.txt|{{Pkg|busybox}}}}
* {{App|smdev|smdev is a simple program to manage device nodes. It is mostly compatible with mdev but does not have all of its features.|https://git.suckless.org/smdev/|{{AUR|smdev}}}}

== See also ==

* [[Debian:Debate/initsystem]]
* [https://skarnet.org/software/s6/s6-svscan-1.html How to run s6-svscan as process 1]
* [https://bbs.archlinux.org/viewtopic.php?id=162606&p=1 Replace systemd with busybox + minirc]
* [https://busybox.net/~vda/init_vs_runsv.html Init vs. runsv]
* [https://felipec.wordpress.com/2013/11/04/init/ Demystifying the init system]
* [https://web.archive.org/web/20201108092524/https://blog.darknedgy.net/technology/2015/09/05/0/ A history of modern init systems (1992-2015)]
* [[Gentoo:Comparison of init systems]]
* [https://github.com/InitWare/InitWare/wiki/Contributors'-Study-Guide InitWare: Contributors' Study Guide]
* [https://jdebp.uk/Softwares/nosh/ The nosh package]

River Classic

2026-05-14T09:23:37Z

Indigo: /* Configuration */ apply Help:Style/Formatting and punctuation#Executable/application names

{{Lowercase title}}
[[Category:Wayland compositors]]
[[ja:River Classic]]
{{Related articles start}}
{{Related|river}}
{{Related|Wayland#Compositors}}
{{Related articles end}}
[https://codeberg.org/river/river-classic river classic] is a wlroots-based Wayland dynamic tiling compositor, inspired by, but not based on dwm, xmonad and bspwm. Configuration is by an external executable file. It is the old branch of the now non-monolithic compositor [[river]].

Its declared design goals are:

* Simple and predictable behavior, river should be easy to use and have a low cognitive load.
* Window management based on a stack of views and tags.
* Dynamic layouts generated by external, user-written executables. A default rivertile layout generator is provided.
* Scriptable configuration and control through a custom Wayland protocol and separate riverctl binary implementing it.

== Installation ==

River Classic is [[install]]ed with the {{pkg|river-classic}} package.

== Starting ==

A single executable file is used as a configuration file. No initialisation file is set up for the user by default, so no keybindings or default applications are available until an init file is created. Note that this includes the exit keybinding, so set up in tty or another desktop environment before running river.

An example config init file is available in {{ic|/usr/share/river/example/}}.
Copy this as {{ic|~/.config/river/init}} and ensure it is [[executable]].

=== Manually ===

Enter {{ic|river}} (exits to tty with user still logged in) or {{ic|exec river}} (more securely exits to tty with user logged out)

=== From TTY ===

River can be autostarted in a similar manner to ''startx'', by setting up the environment variable checks in {{ic|.bash_profile}} or the equivalent file for other shells. See [[Xinit#Autostart X at login]], replacing {{ic|$DISPLAY}} with {{ic|$WAYLAND_DISPLAY}}, and running {{ic|exec river}}.

=== Display manager ===

River does not officially support display managers but many will work with no or minimal effort. A session entry is installed by default in {{ic|/usr/share/wayland-sessions/}}.

== Configuration ==

The configuration file can be a shell script or executable program, comprising a list of ''riverctl'' individual commands which define key bindings, input settings and window rules. It is executed once at start-up but can be re-run like any other shell script (consider the effects of duplicating any autostarted spawned actions).
Each setting can also be run individually by simply running the relevant ''riverctl'' line in a terminal. This allows temporary override of the init settings, dynamic updates and testing new settings.

For example, to map the shortcut {{ic|Super+PrtSc}} to take a screenshot with the application {{Pkg|grim}} and display a temporary [[desktop notification]]:

riverctl map normal Super Print spawn "grim && notify-send -t 2000 'Screenshot taken'"

The ''spawn'' command can launch any application or script but expects a single word argument. Quote any longer expressions.

=== Keyboard layout ===

riverctl keyboard-layout gb

Multiple layouts can be entered as a comma-separated list, e.g. {{ic|gb,fr}}.

Variables and other shell constructs can be used: {{ic|1=mod='Mod4'}}, {{ic|set term foot}}, etc, as per your shell.

=== Touchpad examples ===

Certain touchpad behaviour and focus preferences are available.

riverctl input pointer-2-7-SynPS/2_Synaptics_TouchPad tap enabled
riverctl focus-follows-cursor normal

Exact keyboard, mouse and touchpad models for use in these settings can be identified using:

$ riverctl list-inputs

=== Window rules ===

It is sometimes desirable to set certain windows to be non-tiling by default. Floating windows can be defined by class or title:

riverctl rule-add -app-id 'galculator' float
riverctl rule-add -app-id 'thunar' float # make all Thunar windows floating
riverctl rule-add -app-id 'thunar' -title '* - Thunar' no-float # except main window

== Usage ==

=== Autostart ===

Use {{ic|riverctl spawn}} without a keybinding to launch any executable at startup, for example:

riverctl spawn "i3-battery-popup -n -m 'Battery Low!'"

== Tips and tricks ==

=== Scratchpads ===

River does not define any scratchpads by default, but these can be set up on any tag beyond the default 0-9. First, define the tag number, then the key mapping to move an application to the scratchpad tag and toggle its appearance, and, finally, prevent new windows being assigned to the scratchpad.

scratch_tag=$((1 << 20 ))

riverctl map normal Super P toggle-focused-tags ${scratch_tag} # toggle the scratchpad
riverctl map normal Super+Shift P set-view-tags ${scratch_tag} # send windows to the scratchpad

# Set spawn tagmask to ensure new windows do not have the scratchpad tag unless explicitly set.
all_but_scratch_tag=$(( ((1 << 32) - 1) ^ $scratch_tag ))
riverctl spawn-tagmask ${all_but_scratch_tag}

=== Modes ===

River supports modes for key mapping, which allows for reuse of mappings, and combinations of fewer keys. There are two default modes of 'normal' and 'locked' (defining allowed key mappings when the screen is locked).
Custom modes can be added. Eg. if floating windows are rarely used, the key mapping to manipulate those windows can be defined in a 'float' mode. Entry and exit key mappings for the mode are set as the first and last mappings, with other mapping between these.

riverctl declare-mode float
riverctl map normal Super R enter-mode float # Super+R to enter float mode

### Floating window mappings but note that these also apply to tiled windows.
#
# Super {Arrows} to move views
riverctl map float Super Left move left 100
riverctl map float Super Down move down 100
riverctl map float Super Up move up 100
riverctl map float Super Right move right 100

# Alt+{arrows} to snap views to screen edges
riverctl map float Alt Left snap left
riverctl map float Alt Down snap down
riverctl map float Alt Up snap up
riverctl map float Alt Right snap right

# Shift+{arrows} to resize views
riverctl map float Shift Left resize horizontal -100
riverctl map float Shift Down resize vertical 100
riverctl map float Shift Up resize vertical -100
riverctl map float Shift Right resize horizontal 100

riverctl map float None Escape enter-mode normal # Escape to exit float mode and return to normal mode

Note that floating window modifiers also work on tiled windows, making them floating and giving potentially unpredictable layouts.

=== External tools ===

In common with many other Wayland minimalist tiling clients, other tools are not included. Example external bars, screenshot tools, launchers, etc. are listed in the [https://codeberg.org/river/wiki-classic River wiki], including several with River-specific functionality.

== Troubleshooting ==

=== Screencasting ===

If Screencasting is not working with river, check if the needed [[environment variables]] are properly set for systemd:
$ systemctl --user show-environment

You should find something like:
WAYLAND_DISPLAY=wayland-1
XDG_CURRENT_DESKTOP=river

If any of these variables are not set, you may add this to your {{ic|.config/river/init}}:
systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=river
systemctl --user restart xdg-desktop-portal

If you need further troubleshooting, try to:
* Make sure [[XDG Desktop Portal]] services are running:
$ systemctl --user status xdg-desktop-portal.service
$ systemctl --user status xdg-desktop-portal-wlr.service

* Stop the {{ic|xdg-desktop-portal.service}} and run it manually to see if it works:
$ systemctl --user stop xdg-desktop-portal
$ XDG_CURRENT_DESKTOP=river /usr/lib/xdg-desktop-portal

* Test it using [https://mozilla.github.io/webrtc-landing/gum_test.html Mozilla WebRTC test]

{{Note|
Contrary to what you may find in older posts in the internet, it is not necessary to install {{Pkg|pipewire-media-session}}, since {{Pkg|wireplumber}} is working just fine now.
}}

== See also ==

* [https://codeberg.org/river/river-classic/ River Codeberg repository]
* [https://codeberg.org/river/wiki-classic/ River wiki]
* [https://leon_plickat.srht.site/writing/river-setup-guide/article.html Developer set-up blog post]

River Classic

2026-05-14T09:20:32Z

Indigo: /* Touchpad examples */ apply Help:Style#Code formatting

{{Lowercase title}}
[[Category:Wayland compositors]]
[[ja:River Classic]]
{{Related articles start}}
{{Related|river}}
{{Related|Wayland#Compositors}}
{{Related articles end}}
[https://codeberg.org/river/river-classic river classic] is a wlroots-based Wayland dynamic tiling compositor, inspired by, but not based on dwm, xmonad and bspwm. Configuration is by an external executable file. It is the old branch of the now non-monolithic compositor [[river]].

Its declared design goals are:

* Simple and predictable behavior, river should be easy to use and have a low cognitive load.
* Window management based on a stack of views and tags.
* Dynamic layouts generated by external, user-written executables. A default rivertile layout generator is provided.
* Scriptable configuration and control through a custom Wayland protocol and separate riverctl binary implementing it.

== Installation ==

River Classic is [[install]]ed with the {{pkg|river-classic}} package.

== Starting ==

A single executable file is used as a configuration file. No initialisation file is set up for the user by default, so no keybindings or default applications are available until an init file is created. Note that this includes the exit keybinding, so set up in tty or another desktop environment before running river.

An example config init file is available in {{ic|/usr/share/river/example/}}.
Copy this as {{ic|~/.config/river/init}} and ensure it is [[executable]].

=== Manually ===

Enter {{ic|river}} (exits to tty with user still logged in) or {{ic|exec river}} (more securely exits to tty with user logged out)

=== From TTY ===

River can be autostarted in a similar manner to ''startx'', by setting up the environment variable checks in {{ic|.bash_profile}} or the equivalent file for other shells. See [[Xinit#Autostart X at login]], replacing {{ic|$DISPLAY}} with {{ic|$WAYLAND_DISPLAY}}, and running {{ic|exec river}}.

=== Display manager ===

River does not officially support display managers but many will work with no or minimal effort. A session entry is installed by default in {{ic|/usr/share/wayland-sessions/}}.

== Configuration ==

The configuration file can be a shell script or executable program, comprising a list of ''riverctl'' individual commands which define key bindings, input settings and window rules. It is executed once at start-up but can be re-run like any other shell script (consider the effects of duplicating any autostarted spawned actions).
Each setting can also be run individually by simply running the relevant riverctl line in a terminal. This allows temporary override of the init settings, dynamic updates and testing new settings.

For example, to map the shortcut {{ic|Super+PrtSc}} to take a screenshot with the application {{Pkg|grim}} and display a temporary [[desktop notification]]:

riverctl map normal Super Print spawn "grim && notify-send -t 2000 'Screenshot taken'"

The ''spawn'' command can launch any application or script but expects a single word argument. Quote any longer expressions.

=== Keyboard layout ===

riverctl keyboard-layout gb

Multiple layouts can be entered as a comma-separated list, e.g. {{ic|gb,fr}}.

Variables and other shell constructs can be used: {{ic|1=mod='Mod4'}}, {{ic|set term foot}}, etc, as per your shell.

=== Touchpad examples ===

Certain touchpad behaviour and focus preferences are available.

riverctl input pointer-2-7-SynPS/2_Synaptics_TouchPad tap enabled
riverctl focus-follows-cursor normal

Exact keyboard, mouse and touchpad models for use in these settings can be identified using:

$ riverctl list-inputs

=== Window rules ===

It is sometimes desirable to set certain windows to be non-tiling by default. Floating windows can be defined by class or title:

riverctl rule-add -app-id 'galculator' float
riverctl rule-add -app-id 'thunar' float # make all Thunar windows floating
riverctl rule-add -app-id 'thunar' -title '* - Thunar' no-float # except main window

== Usage ==

=== Autostart ===

Use {{ic|riverctl spawn}} without a keybinding to launch any executable at startup, for example:

riverctl spawn "i3-battery-popup -n -m 'Battery Low!'"

== Tips and tricks ==

=== Scratchpads ===

River does not define any scratchpads by default, but these can be set up on any tag beyond the default 0-9. First, define the tag number, then the key mapping to move an application to the scratchpad tag and toggle its appearance, and, finally, prevent new windows being assigned to the scratchpad.

scratch_tag=$((1 << 20 ))

riverctl map normal Super P toggle-focused-tags ${scratch_tag} # toggle the scratchpad
riverctl map normal Super+Shift P set-view-tags ${scratch_tag} # send windows to the scratchpad

# Set spawn tagmask to ensure new windows do not have the scratchpad tag unless explicitly set.
all_but_scratch_tag=$(( ((1 << 32) - 1) ^ $scratch_tag ))
riverctl spawn-tagmask ${all_but_scratch_tag}

=== Modes ===

River supports modes for key mapping, which allows for reuse of mappings, and combinations of fewer keys. There are two default modes of 'normal' and 'locked' (defining allowed key mappings when the screen is locked).
Custom modes can be added. Eg. if floating windows are rarely used, the key mapping to manipulate those windows can be defined in a 'float' mode. Entry and exit key mappings for the mode are set as the first and last mappings, with other mapping between these.

riverctl declare-mode float
riverctl map normal Super R enter-mode float # Super+R to enter float mode

### Floating window mappings but note that these also apply to tiled windows.
#
# Super {Arrows} to move views
riverctl map float Super Left move left 100
riverctl map float Super Down move down 100
riverctl map float Super Up move up 100
riverctl map float Super Right move right 100

# Alt+{arrows} to snap views to screen edges
riverctl map float Alt Left snap left
riverctl map float Alt Down snap down
riverctl map float Alt Up snap up
riverctl map float Alt Right snap right

# Shift+{arrows} to resize views
riverctl map float Shift Left resize horizontal -100
riverctl map float Shift Down resize vertical 100
riverctl map float Shift Up resize vertical -100
riverctl map float Shift Right resize horizontal 100

riverctl map float None Escape enter-mode normal # Escape to exit float mode and return to normal mode

Note that floating window modifiers also work on tiled windows, making them floating and giving potentially unpredictable layouts.

=== External tools ===

In common with many other Wayland minimalist tiling clients, other tools are not included. Example external bars, screenshot tools, launchers, etc. are listed in the [https://codeberg.org/river/wiki-classic River wiki], including several with River-specific functionality.

== Troubleshooting ==

=== Screencasting ===

If Screencasting is not working with river, check if the needed [[environment variables]] are properly set for systemd:
$ systemctl --user show-environment

You should find something like:
WAYLAND_DISPLAY=wayland-1
XDG_CURRENT_DESKTOP=river

If any of these variables are not set, you may add this to your {{ic|.config/river/init}}:
systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=river
systemctl --user restart xdg-desktop-portal

If you need further troubleshooting, try to:
* Make sure [[XDG Desktop Portal]] services are running:
$ systemctl --user status xdg-desktop-portal.service
$ systemctl --user status xdg-desktop-portal-wlr.service

* Stop the {{ic|xdg-desktop-portal.service}} and run it manually to see if it works:
$ systemctl --user stop xdg-desktop-portal
$ XDG_CURRENT_DESKTOP=river /usr/lib/xdg-desktop-portal

* Test it using [https://mozilla.github.io/webrtc-landing/gum_test.html Mozilla WebRTC test]

{{Note|
Contrary to what you may find in older posts in the internet, it is not necessary to install {{Pkg|pipewire-media-session}}, since {{Pkg|wireplumber}} is working just fine now.
}}

== See also ==

* [https://codeberg.org/river/river-classic/ River Codeberg repository]
* [https://codeberg.org/river/wiki-classic/ River wiki]
* [https://leon_plickat.srht.site/writing/river-setup-guide/article.html Developer set-up blog post]

River Classic

2026-05-14T09:14:43Z

Indigo: grammar fix

{{Lowercase title}}
[[Category:Wayland compositors]]
[[ja:River Classic]]
{{Related articles start}}
{{Related|river}}
{{Related|Wayland#Compositors}}
{{Related articles end}}
[https://codeberg.org/river/river-classic river classic] is a wlroots-based Wayland dynamic tiling compositor, inspired by, but not based on dwm, xmonad and bspwm. Configuration is by an external executable file. It is the old branch of the now non-monolithic compositor [[river]].

Its declared design goals are:

* Simple and predictable behavior, river should be easy to use and have a low cognitive load.
* Window management based on a stack of views and tags.
* Dynamic layouts generated by external, user-written executables. A default rivertile layout generator is provided.
* Scriptable configuration and control through a custom Wayland protocol and separate riverctl binary implementing it.

== Installation ==

River Classic is [[install]]ed with the {{pkg|river-classic}} package.

== Starting ==

A single executable file is used as a configuration file. No initialisation file is set up for the user by default, so no keybindings or default applications are available until an init file is created. Note that this includes the exit keybinding, so set up in tty or another desktop environment before running river.

An example config init file is available in {{ic|/usr/share/river/example/}}.
Copy this as {{ic|~/.config/river/init}} and ensure it is [[executable]].

=== Manually ===

Enter {{ic|river}} (exits to tty with user still logged in) or {{ic|exec river}} (more securely exits to tty with user logged out)

=== From TTY ===

River can be autostarted in a similar manner to ''startx'', by setting up the environment variable checks in {{ic|.bash_profile}} or the equivalent file for other shells. See [[Xinit#Autostart X at login]], replacing {{ic|$DISPLAY}} with {{ic|$WAYLAND_DISPLAY}}, and running {{ic|exec river}}.

=== Display manager ===

River does not officially support display managers but many will work with no or minimal effort. A session entry is installed by default in {{ic|/usr/share/wayland-sessions/}}.

== Configuration ==

The configuration file can be a shell script or executable program, comprising a list of ''riverctl'' individual commands which define key bindings, input settings and window rules. It is executed once at start-up but can be re-run like any other shell script (consider the effects of duplicating any autostarted spawned actions).
Each setting can also be run individually by simply running the relevant riverctl line in a terminal. This allows temporary override of the init settings, dynamic updates and testing new settings.

For example, to map the shortcut {{ic|Super+PrtSc}} to take a screenshot with the application {{Pkg|grim}} and display a temporary [[desktop notification]]:

riverctl map normal Super Print spawn "grim && notify-send -t 2000 'Screenshot taken'"

The ''spawn'' command can launch any application or script but expects a single word argument. Quote any longer expressions.

=== Keyboard layout ===

riverctl keyboard-layout gb

Multiple layouts can be entered as a comma-separated list, e.g. {{ic|gb,fr}}.

Variables and other shell constructs can be used: {{ic|1=mod='Mod4'}}, {{ic|set term foot}}, etc, as per your shell.

=== Touchpad examples ===

Certain touchpad behaviour and focus preferences are available.

riverctl input pointer-2-7-SynPS/2_Synaptics_TouchPad tap enabled
riverctl focus-follows-cursor normal

Exact keyboard, mouse and touchpad models for use in these settings can be identified using:

riverctl list-inputs

=== Window rules ===

It is sometimes desirable to set certain windows to be non-tiling by default. Floating windows can be defined by class or title:

riverctl rule-add -app-id 'galculator' float
riverctl rule-add -app-id 'thunar' float # make all Thunar windows floating
riverctl rule-add -app-id 'thunar' -title '* - Thunar' no-float # except main window

== Usage ==

=== Autostart ===

Use {{ic|riverctl spawn}} without a keybinding to launch any executable at startup, for example:

riverctl spawn "i3-battery-popup -n -m 'Battery Low!'"

== Tips and tricks ==

=== Scratchpads ===

River does not define any scratchpads by default, but these can be set up on any tag beyond the default 0-9. First, define the tag number, then the key mapping to move an application to the scratchpad tag and toggle its appearance, and, finally, prevent new windows being assigned to the scratchpad.

scratch_tag=$((1 << 20 ))

riverctl map normal Super P toggle-focused-tags ${scratch_tag} # toggle the scratchpad
riverctl map normal Super+Shift P set-view-tags ${scratch_tag} # send windows to the scratchpad

# Set spawn tagmask to ensure new windows do not have the scratchpad tag unless explicitly set.
all_but_scratch_tag=$(( ((1 << 32) - 1) ^ $scratch_tag ))
riverctl spawn-tagmask ${all_but_scratch_tag}

=== Modes ===

River supports modes for key mapping, which allows for reuse of mappings, and combinations of fewer keys. There are two default modes of 'normal' and 'locked' (defining allowed key mappings when the screen is locked).
Custom modes can be added. Eg. if floating windows are rarely used, the key mapping to manipulate those windows can be defined in a 'float' mode. Entry and exit key mappings for the mode are set as the first and last mappings, with other mapping between these.

riverctl declare-mode float
riverctl map normal Super R enter-mode float # Super+R to enter float mode

### Floating window mappings but note that these also apply to tiled windows.
#
# Super {Arrows} to move views
riverctl map float Super Left move left 100
riverctl map float Super Down move down 100
riverctl map float Super Up move up 100
riverctl map float Super Right move right 100

# Alt+{arrows} to snap views to screen edges
riverctl map float Alt Left snap left
riverctl map float Alt Down snap down
riverctl map float Alt Up snap up
riverctl map float Alt Right snap right

# Shift+{arrows} to resize views
riverctl map float Shift Left resize horizontal -100
riverctl map float Shift Down resize vertical 100
riverctl map float Shift Up resize vertical -100
riverctl map float Shift Right resize horizontal 100

riverctl map float None Escape enter-mode normal # Escape to exit float mode and return to normal mode

Note that floating window modifiers also work on tiled windows, making them floating and giving potentially unpredictable layouts.

=== External tools ===

In common with many other Wayland minimalist tiling clients, other tools are not included. Example external bars, screenshot tools, launchers, etc. are listed in the [https://codeberg.org/river/wiki-classic River wiki], including several with River-specific functionality.

== Troubleshooting ==

=== Screencasting ===

If Screencasting is not working with river, check if the needed [[environment variables]] are properly set for systemd:
$ systemctl --user show-environment

You should find something like:
WAYLAND_DISPLAY=wayland-1
XDG_CURRENT_DESKTOP=river

If any of these variables are not set, you may add this to your {{ic|.config/river/init}}:
systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=river
systemctl --user restart xdg-desktop-portal

If you need further troubleshooting, try to:
* Make sure [[XDG Desktop Portal]] services are running:
$ systemctl --user status xdg-desktop-portal.service
$ systemctl --user status xdg-desktop-portal-wlr.service

* Stop the {{ic|xdg-desktop-portal.service}} and run it manually to see if it works:
$ systemctl --user stop xdg-desktop-portal
$ XDG_CURRENT_DESKTOP=river /usr/lib/xdg-desktop-portal

* Test it using [https://mozilla.github.io/webrtc-landing/gum_test.html Mozilla WebRTC test]

{{Note|
Contrary to what you may find in older posts in the internet, it is not necessary to install {{Pkg|pipewire-media-session}}, since {{Pkg|wireplumber}} is working just fine now.
}}

== See also ==

* [https://codeberg.org/river/river-classic/ River Codeberg repository]
* [https://codeberg.org/river/wiki-classic/ River wiki]
* [https://leon_plickat.srht.site/writing/river-setup-guide/article.html Developer set-up blog post]

River Classic

2026-05-14T09:13:34Z

Indigo: add related articles to link back to river

{{Lowercase title}}
[[Category:Wayland compositors]]
[[ja:River Classic]]
{{Related articles start}}
{{Related|River}}
{{Related|Wayland#Compositors}}
{{Related articles end}}
[https://codeberg.org/river/river-classic river classic] is a wlroots-based Wayland dynamic tiling compositor, inspired by, but not based on dwm, xmonad and bspwm. Configuration is by an external executable file. It is the old branch of the now non-monolithic compositor [[river]]

Its declared design goals are:

* Simple and predictable behavior, river should be easy to use and have a low cognitive load.
* Window management based on a stack of views and tags.
* Dynamic layouts generated by external, user-written executables. A default rivertile layout generator is provided.
* Scriptable configuration and control through a custom Wayland protocol and separate riverctl binary implementing it.

== Installation ==

River Classic is [[install]]ed with the {{pkg|river-classic}} package.

== Starting ==

A single executable file is used as a configuration file. No initialisation file is set up for the user by default, so no keybindings or default applications are available until an init file is created. Note that this includes the exit keybinding, so set up in tty or another desktop environment before running river.

An example config init file is available in {{ic|/usr/share/river/example/}}.
Copy this as {{ic|~/.config/river/init}} and ensure it is [[executable]].

=== Manually ===

Enter {{ic|river}} (exits to tty with user still logged in) or {{ic|exec river}} (more securely exits to tty with user logged out)

=== From TTY ===

River can be autostarted in a similar manner to ''startx'', by setting up the environment variable checks in {{ic|.bash_profile}} or the equivalent file for other shells. See [[Xinit#Autostart X at login]], replacing {{ic|$DISPLAY}} with {{ic|$WAYLAND_DISPLAY}}, and running {{ic|exec river}}.

=== Display manager ===

River does not officially support display managers but many will work with no or minimal effort. A session entry is installed by default in {{ic|/usr/share/wayland-sessions/}}.

== Configuration ==

The configuration file can be a shell script or executable program, comprising a list of ''riverctl'' individual commands which define key bindings, input settings and window rules. It is executed once at start-up but can be re-run like any other shell script (consider the effects of duplicating any autostarted spawned actions).
Each setting can also be run individually by simply running the relevant riverctl line in a terminal. This allows temporary override of the init settings, dynamic updates and testing new settings.

For example, to map the shortcut {{ic|Super+PrtSc}} to take a screenshot with the application {{Pkg|grim}} and display a temporary [[desktop notification]]:

riverctl map normal Super Print spawn "grim && notify-send -t 2000 'Screenshot taken'"

The ''spawn'' command can launch any application or script but expects a single word argument. Quote any longer expressions.

=== Keyboard layout ===

riverctl keyboard-layout gb

Multiple layouts can be entered as a comma-separated list, e.g. {{ic|gb,fr}}.

Variables and other shell constructs can be used: {{ic|1=mod='Mod4'}}, {{ic|set term foot}}, etc, as per your shell.

=== Touchpad examples ===

Certain touchpad behaviour and focus preferences are available.

riverctl input pointer-2-7-SynPS/2_Synaptics_TouchPad tap enabled
riverctl focus-follows-cursor normal

Exact keyboard, mouse and touchpad models for use in these settings can be identified using:

riverctl list-inputs

=== Window rules ===

It is sometimes desirable to set certain windows to be non-tiling by default. Floating windows can be defined by class or title:

riverctl rule-add -app-id 'galculator' float
riverctl rule-add -app-id 'thunar' float # make all Thunar windows floating
riverctl rule-add -app-id 'thunar' -title '* - Thunar' no-float # except main window

== Usage ==

=== Autostart ===

Use {{ic|riverctl spawn}} without a keybinding to launch any executable at startup, for example:

riverctl spawn "i3-battery-popup -n -m 'Battery Low!'"

== Tips and tricks ==

=== Scratchpads ===

River does not define any scratchpads by default, but these can be set up on any tag beyond the default 0-9. First, define the tag number, then the key mapping to move an application to the scratchpad tag and toggle its appearance, and, finally, prevent new windows being assigned to the scratchpad.

scratch_tag=$((1 << 20 ))

riverctl map normal Super P toggle-focused-tags ${scratch_tag} # toggle the scratchpad
riverctl map normal Super+Shift P set-view-tags ${scratch_tag} # send windows to the scratchpad

# Set spawn tagmask to ensure new windows do not have the scratchpad tag unless explicitly set.
all_but_scratch_tag=$(( ((1 << 32) - 1) ^ $scratch_tag ))
riverctl spawn-tagmask ${all_but_scratch_tag}

=== Modes ===

River supports modes for key mapping, which allows for reuse of mappings, and combinations of fewer keys. There are two default modes of 'normal' and 'locked' (defining allowed key mappings when the screen is locked).
Custom modes can be added. Eg. if floating windows are rarely used, the key mapping to manipulate those windows can be defined in a 'float' mode. Entry and exit key mappings for the mode are set as the first and last mappings, with other mapping between these.

riverctl declare-mode float
riverctl map normal Super R enter-mode float # Super+R to enter float mode

### Floating window mappings but note that these also apply to tiled windows.
#
# Super {Arrows} to move views
riverctl map float Super Left move left 100
riverctl map float Super Down move down 100
riverctl map float Super Up move up 100
riverctl map float Super Right move right 100

# Alt+{arrows} to snap views to screen edges
riverctl map float Alt Left snap left
riverctl map float Alt Down snap down
riverctl map float Alt Up snap up
riverctl map float Alt Right snap right

# Shift+{arrows} to resize views
riverctl map float Shift Left resize horizontal -100
riverctl map float Shift Down resize vertical 100
riverctl map float Shift Up resize vertical -100
riverctl map float Shift Right resize horizontal 100

riverctl map float None Escape enter-mode normal # Escape to exit float mode and return to normal mode

Note that floating window modifiers also work on tiled windows, making them floating and giving potentially unpredictable layouts.

=== External tools ===

In common with many other Wayland minimalist tiling clients, other tools are not included. Example external bars, screenshot tools, launchers, etc. are listed in the [https://codeberg.org/river/wiki-classic River wiki], including several with River-specific functionality.

== Troubleshooting ==

=== Screencasting ===

If Screencasting is not working with river, check if the needed [[environment variables]] are properly set for systemd:
$ systemctl --user show-environment

You should find something like:
WAYLAND_DISPLAY=wayland-1
XDG_CURRENT_DESKTOP=river

If any of these variables are not set, you may add this to your {{ic|.config/river/init}}:
systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=river
systemctl --user restart xdg-desktop-portal

If you need further troubleshooting, try to:
* Make sure [[XDG Desktop Portal]] services are running:
$ systemctl --user status xdg-desktop-portal.service
$ systemctl --user status xdg-desktop-portal-wlr.service

* Stop the {{ic|xdg-desktop-portal.service}} and run it manually to see if it works:
$ systemctl --user stop xdg-desktop-portal
$ XDG_CURRENT_DESKTOP=river /usr/lib/xdg-desktop-portal

* Test it using [https://mozilla.github.io/webrtc-landing/gum_test.html Mozilla WebRTC test]

{{Note|
Contrary to what you may find in older posts in the internet, it is not necessary to install {{Pkg|pipewire-media-session}}, since {{Pkg|wireplumber}} is working just fine now.
}}

== See also ==

* [https://codeberg.org/river/river-classic/ River Codeberg repository]
* [https://codeberg.org/river/wiki-classic/ River wiki]
* [https://leon_plickat.srht.site/writing/river-setup-guide/article.html Developer set-up blog post]

River

2026-05-14T09:12:26Z

Indigo: move note below article preface including grammar fixes.

[[Category:Wayland compositors]]
{{Related articles start}}
{{Related|River Classic}}
{{Related|Wayland#Compositors}}
{{Related articles end}}
According to [https://isaacfreund.com/software/river River's homepage]:
:River is a non-monolithic Wayland compositor. Unlike other Wayland compositors, river does not combine the compositor and window manager into one program. Instead, users can choose any window manager implementing the river-window-management-v1 protocol.

The stated goals for River is to make getting into Wayland development easier and to allow its "window managers" to be more experimental as they do not need to write a whole compositor. This also allows for things not normally possible with Wayland Compositors such as reloading configurations without closing all windows.

{{note|This page is about the non-monolithic version of River, if you are looking for the dynamic tiling version, look at [[River Classic]].}}

== Installation ==

River is [[install]]ed with the {{pkg|river}} package.

A separate window manager will need to be installed as well. See also [https://codeberg.org/river/wiki/src/branch/main/pages/wm-list.md River's wiki] for a more comprehensive list of window managers.

=== Stacking ===
*{{App|Canoe|Stacking window manager with classic look and feel written in Rust.|https://github.com/roblillack/canoe|{{AUR|canoe}}}}

=== Tiling ===
* {{App|Kwm|Window manager inspired by [[dwm]] with its built in bar.|https://github.com/kewuaa/kwm|{{AUR|kwm}}}}
=== Other ===
* {{App|Rill|A minimalist scrolling window manager with simple animation.|https://codeberg.org/lzj15/rill|{{AUR|rill}}}}

== Starting ==

River can be started by a [[display manager]] or with the command below.

river

River can be started with select window manager with the "c" argument.

river -c foo

== Configuration ==

River is configured through a executable shell file, by default it is located in {{ic|$XDG_CONFIG_HOME/river/init}}. By default this is {{ic|~/.config/river/init}}.

River can use a different configuration if it is called with the "c" argument.

river -c customConfPath
=== Selecting a default window manager ===
A window manager can be made the default by appending it to River's configuration file.

=== Autostart ===
Since the configuration is executed by the [https://en.wikipedia.org/wiki/Bourne_shell bourne shell]. Commands placed inside the configuration will be executed on start up, certain window managers also allow for autostarting in their configurations.

=== Input configuration ===
Input configuration can be done in multiple ways. Some window managers support input configuration.

There are separate input managers such as [https://codeberg.org/Sivecano/channel Channel] and {{AUR|kwim}} that can be used.

If only the keyboard layout needs to be changed. Change the [[environment variable]]{{ic|XKB_DEFAULT_LAYOUT}} to the needed layout; example "gb" for UK keyboards.

== Troubleshooting ==

=== Configuration file does nothing ===

This may be caused by the configuration file lacking execution permissions. See [[File permissions and attributes]].

=== Screencast via WebRTC does not work ===

See [[River Classic#Troubleshooting]].

== See also ==

* [https://isaacfreund.com/docs/wayland/ River protocols specifications]
* [https://codeberg.org/river/tinyrwm Example window manager]
*[https://codeberg.org/river/wiki River wiki]
*[https://codeberg.org/river/river Official Codeberg repository]

Niri

2026-05-14T08:38:54Z

Indigo: /* Starting */ apply Help:Style#Command line text

[[Category:Wayland compositors]]
[[ja:Niri]]
[[zh-hans:Niri]]
[https://github.com/niri-wm/niri Niri] is a scrollable tiling [[Wayland]] compositor. Unlike [[Sway]] or [[Hyprland]], Niri arranges the windows in an infinite horizontal desktop, where you can scroll to the left or to the right (although more advanced layouts are possible). It is similar to [[GNOME]]'s PaperWM and [[KDE]]'s [https://aur.archlinux.org/packages/kwin-karousel Karousel].

== Installation ==

Niri can be [[install]]ed with the {{pkg|niri}} package. Additionally, to have a better experience, you may want to install:

* {{pkg|fuzzel}}: default application launcher in Niri
* {{pkg|mako}}: notifications
* [[waybar]]: a Wayland bar
* {{pkg|xdg-desktop-portal-gtk}}, {{pkg|xdg-desktop-portal-gnome}}: to be able to do screen sharing
* [[alacritty]]: default terminal in Niri
* {{pkg|swaybg}}: background image
* {{pkg|swayidle}}, {{pkg|swaylock}}: to lock the screen on idle status
* {{pkg|xwayland-satellite}}: to run X11 apps
* {{pkg|udiskie}}: to manage and auto-mount USB drives
* {{pkg|dms-shell-niri}} or {{AUR|noctalia-shell}}: complete desktop shell

== Starting ==

Niri comes with a [[desktop entry]] that can be sourced by [[display manager]]s; selecting it will run {{ic|niri-session}} which handles exporting [[environment variables]] to [[systemd]].

Additionally you can start Niri from a [[getty]] by executing:

$ niri-session -l

This can be paired with [[Getty#Automatic login to virtual console|auto login]] to have a seamless [[boot]] experience.

== Configuration ==

Niri reads the configuration from {{ic|~/.config/niri/config.kdl}}. It is a KDL file, divided by sections. The default configuration, created on the first run, documents the default options with comments. However, options introduced with updates will not be documented in the user's configuration; you may check [https://niri-wm.github.io/niri/Configuration:-Introduction.html Niri's official documentation] instead.

{{Note|When using LXQt, the configuration needs to be stored in a different location; see [[LXQt#Wayland Session]].}}

Niri automatically applies the configuration when it is saved. The live reload of invalid configuration will not crash Niri; instead, the last working state is preserved, and the user is notified of the configuration error. {{ic|niri validate}} can be invoked to validate the configuration outside of a Niri session.

=== Keymap ===

To configure the keymap, edit the {{ic|input/keyboard/xkb}} section.

For example, if you want to have a "US Int Alt Gr" layout with {{ic|CapsLock}} acting as {{ic|Ctrl}} key:

{{hc|~/.config/niri/config.kdl|
input {
keyboard {
xkb {
layout "us"
variant "altgr-intl"
options "ctrl:nocaps"
}
}
...
}
}}

=== Outputs ===

First run {{ic|niri msg outputs}} to get an overview of the outputs recognized by Niri. Then you can apply configs to each monitor. For example to set the HDMI monitor to 2560x1440 60Hz with a 1.2 scaling, and turning off the laptop monitor, set the following:

{{hc|~/.config/niri/config.kdl|
output "HDMI-A-1" {
mode "2560x1440@60.000"
scale 1.2
}

output "eDP-1" {
off
}
}}

{{Note|Alternatively, you can use [[kanshi]] to set up dynamic layouts, for example, if you want to turn off an internal laptop screen when docked to a monitor.}}

=== Bindings ===

The binds section allows to set up the different key combinations that have effect on Niri. Many bindings are already set in the default configuration generated on first launch. These are all remappable.

Please note that Niri does ''not'' load any default bindings. If a binding is not specified in the configuration, it will not be active. "Defaults" are simply bindings that are present in the automatically generated configuration. Therefore, take care when removing the bindings. It is recommended to instead comment out unused bindings.

Bindings are defined using the modifiers keys appended with a {{ic|+}} sign and the action between brackets. The special action 'spawn' will launch a program. For example, you will find the following bindings that spawn [[alacritty]] and {{pkg|fuzzel}} on {{ic|Mod+T}} and {{ic|Mod+D}} respectively. {{ic|Mod}} is usually the {{ic|Super}} key if running standalone, but it is {{ic|Alt}} if it is running inside of another compositor.

{{hc|~/.config/niri/config.kdl|
binds {
...
Mod+T { spawn "alacritty"; }
Mod+D { spawn "fuzzel"; }
...
}
}}

Note that all space-separated arguments to processes started by {{ic|spawn}} must be enclosed in quotes:

{{hc|~/.config/niri/config.kdl|
binds {
...
Mod+Ctrl+semicolon {
spawn "swaylock" "-c" "121212" "-e" "-f" "-F"
}
...
}
}}

==== WASD-like navigation ====

It is possible to configure Niri workspaces and bindings so that jumping through windows follows a navigation similar to WASD as in games.

{{hc|~/.config/niri/config.kdl|
binds {
...
Mod+A { focus-column-left; }
Mod+S { focus-window-or-workspace-down; }
Mod+W { focus-window-or-workspace-up; }
Mod+D { focus-column-right; }
...
}
}}

Be aware that this config will probably need other bindings to be remapped as well. Also, some people may prefer to have the WASD navigation on the right-hand side, or have a more Vim-like navigation.

=== Autostart ===

Niri allows some programs to be started alongside with Niri.
For example, some of the programs mentioned beforehand like {{Pkg|mako}}, {{Pkg|waybar}} and {{Pkg|swayidle}}/{{Pkg|swaylock}} can be configured:

{{hc|~/.config/niri/config.kdl|
spawn-at-startup "mako"
spawn-at-startup "waybar"
spawn-at-startup "swayidle" "-w" "timeout" "601" "niri msg action power-off-monitors" "timeout" "600" "swaylock -f" "before-sleep" "swaylock -f"
}}

Note that these processes are tied to the Niri session, and they will be killed when Niri exits '''or''' is suspended. To make a process persist, you may set it to a background task by providing the {{ic|"&"}} argument.

=== XWayland ===

Niri does not provide XWayland support for running X11 applications. Instead, it recommends using an external tool: {{Pkg|xwayland-satellite}} is listed in the optional dependencies. After installation, no configuration is required.

{{Note|1=Since niri 25.08, {{Pkg|xwayland-satellite}} is integrated out of the box. Ensure xwayland-satellite >= 0.7 is installed and available in $PATH. No manual configuration is required.}}

=== Multi GPU Configuration ===

In laptop (or PC) setups with both integrated graphics and a dedicated GPU, Niri may default to using the dedicated GPU for both the compositor and starting other applications, causing unnecessary battery drain.

{{Note|For NVIDIA cards, see [[PRIME]] for how to set your GPU to properly enter a low power state, and how to launch applications with that GPU.}}

To set what GPU Niri should use, first check which render devices are available on your system:
{{hc|
$ ls -l /dev/dri/by-path/*-render|
lrwxrwxrwx 1 root root 13 Jan 10 13:02 /dev/dri/by-path/pci-0000:c1:00.0-render -> ../renderD129
lrwxrwxrwx 1 root root 13 Jan 10 13:02 /dev/dri/by-path/pci-0000:c2:00.0-render -> ../renderD128
}}

Then, use the PCI address to identify the correct device you want to use for Niri in {{ic|/dev/dri}}:
{{hc|
$ lspci -s c1:00.0|
c1:00.0 VGA compatible controller: NVIDIA Corporation GB206M [GeForce RTX 5070 Max-Q / Mobile] (rev a1)
}}
If the first PCI address is the wrong card, try the next one.

Finally add to Niri's configuration and specify the correct render device based on the PCI address you identified:
{{hc|
~/.config/niri/config.kdl|
debug {
render-drm-device "/dev/dri/renderD128"
}
}}

Reboot your computer. You can now check if one of the rendering devices is correctly in a low power state using:
{{hc|
$ cat /sys/class/drm/card*/device/power_state|
D3cold
D0
}}

== See also ==

* [https://niri-wm.github.io/niri/ Niri's own wiki]

Proxy server

2026-05-13T13:15:33Z

Indigo: /* HTTPS MITM proxies */ reorder as subsection

[[Category:Proxy servers]]
[[Category:Network configuration]]
[[ja:プロキシ設定]]
[[zh-hans:Proxy server]]
{{Related articles start}}
{{Related|HTTP tunneling}}
{{Related articles end}}

According to [[Wikipedia:Proxy server|Wikipedia]]:
:In computer networks, a proxy server is a server (a computer system or an application) that acts as an intermediary for requests from clients seeking resources from other servers.

Proxying can be applied in common Internet protocols such as HTTP or [[Wikipedia:SOCKS|SOCKS]].

== Environment variables ==

{{Expansion|To export the environment everywhere (more or less), they could be set in {{ic|/etc/environment}}, {{ic|/etc/environment.d/*.conf}} and {{ic|~/.config/environment.d/*.conf}}.}}

Some programs, such as [[wget]] and (used by [[pacman]]) [[CURL]], use environment variables of the form {{ic|''protocol''_proxy}} to determine the proxy for a given protocol (e.g. HTTP, FTP, ...).

Below is an example on how to set these variables in a shell:

{{bc|1=
export http_proxy=http://10.203.0.1:5187/
export https_proxy=$http_proxy
export ftp_proxy=$http_proxy
export rsync_proxy=$http_proxy
export no_proxy="localhost,127.0.0.1,localaddress,.localdomain.com"
}}

Some programs look for the all caps version of the environment variables.

If the proxy environment variables are to be made available to all users and all applications, the above mentioned export commands may be added to a script, say {{ic|proxy.sh}} inside {{ic|/etc/profile.d/}}. The script has to be then made [[executable]]. This method is helpful while using a desktop environment like [[Xfce]] which does not provide an option for proxy configuration. For example, [[Chromium]] browser will make use of the variables set using this method while running XFCE.

Alternatively, there is a tool named {{AUR|proxyman-git}} which claims to configure system-wide proxy settings easily. It also handles proxy configurations of other software like [[git]], [[npm]], [[Dropbox]], etc.

Alternatively you can automate the toggling of the variables by adding a function to your {{ic|.bashrc}}:

{{bc|<nowiki>
function proxy_on() {
export no_proxy="localhost,127.0.0.1,localaddress,.localdomain.com"

if (( $# > 0 )); then
valid=$(echo $@ | sed -n 's/$[0-9]\{1,3\}.\?$\{4\}:$[0-9]\+$/&/p')
if [[ $valid != $@ ]]; then
>&2 echo "Invalid address"
return 1
fi
local proxy=$1
export http_proxy="$proxy" \
https_proxy=$proxy \
ftp_proxy=$proxy \
rsync_proxy=$proxy
echo "Proxy environment variable set."
return 0
fi

echo -n "username: "; read username
if [[ $username != "" ]]; then
echo -n "password: "
read -es password
local pre="$username:$password@"
fi

echo -n "server: "; read server
echo -n "port: "; read port
local proxy=$pre$server:$port
export http_proxy="$proxy" \
https_proxy=$proxy \
ftp_proxy=$proxy \
rsync_proxy=$proxy \
HTTP_PROXY=$proxy \
HTTPS_PROXY=$proxy \
FTP_PROXY=$proxy \
RSYNC_PROXY=$proxy
}

function proxy_off(){
unset http_proxy https_proxy ftp_proxy rsync_proxy \
HTTP_PROXY HTTPS_PROXY FTP_PROXY RSYNC_PROXY
echo -e "Proxy environment variable removed."
}
</nowiki>}}

Omit username or password if they are not needed.

As an alternative, you may want to use the following script.
Change the strings {{ic|YourUserName}}, {{ic|ProxyServerAddress:Port}}, {{ic|LocalAddress}} and {{ic|LocalDomain}} to match your own data, then edit your {{ic|~/.bashrc}} to include the edited functions. Any new bash window will have the new functions. In existing bash windows, type {{ic|source ~/.bashrc}}.
You may prefer to put function definitions in a separate file like {{ic|functions}} then add {{ic|source functions}} to {{ic|.bashrc}} instead of putting everything in {{ic|.bashrc}}. You may also want to change the name "myProxy" into something short and easy to write.

{{bc|<nowiki>
#!/bin/bash

assignProxy(){
PROXY_ENV="http_proxy ftp_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY"
for envar in $PROXY_ENV
do
export $envar=$1
done
for envar in "no_proxy NO_PROXY"
do
export $envar=$2
done
}

clrProxy(){
PROXY_ENV="http_proxy ftp_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY"
for envar in $PROXY_ENV
do
unset $envar
done
}

myProxy(){
user=YourUserName
read -p "Password: " -s pass && echo -e " "
proxy_value="http://$user:$pass@ProxyServerAddress:Port"
no_proxy_value="localhost,127.0.0.1,LocalAddress,LocalDomain.com"
assignProxy $proxy_value $no_proxy_value
}
</nowiki>}}

=== Keep proxy through sudo ===

If the proxy [[environment variables]] are set for the user only they will get lost when running commands with [[sudo]] (or when programs use sudo internally).

A way to prevent that is to add the following line to a [[sudo]] configuration file:

{{hc|/etc/sudoers.d/05_proxy|2=
Defaults env_keep += "*_proxy *_PROXY"
}}

=== Automation with network managers ===

* [[NetworkManager]] cannot change the environment variables.
* [[netctl]] could set-up these environment variables but they would not be seen by other applications as they are not child of netctl.

== About libproxy ==

{{Pkg|libproxy}} is an abstraction library which should be used by all applications that want to access a network resource. It still is in development but could lead to a unified and automated handling of proxies in GNU/Linux if widely adopted.

The role of libproxy is to read the proxy settings from different sources and make them available to applications which use the library. The interesting part with libproxy is that it offers an implementation of the [[Wikipedia:Web_Proxy_Autodiscovery_Protocol|Web Proxy Autodiscovery Protocol]] and an implementation of [[Wikipedia:Proxy_auto-config|Proxy Auto-Config]] that goes with it.

The {{ic|/usr/bin/proxy}} binary takes URL(s) as argument(s) and returns the proxy/proxies that could be used to fetch this/these network resource(s).

{{Note|1=the version 0.4.11 does not support {{ic|1=http_proxy='wpad:'}} because {{ic|1={ pkg-config 'mozjs185 >= 1.8.5'; } }} fails .}}

== Web proxy options ==

* [[Squid]] is a very popular caching/optimizing proxy.
* [[Privoxy]] is an anonymizing and ad-blocking proxy.
* {{Pkg|tinyproxy}} is a small, efficient HTTP/SSL proxy daemon.
* For a simple proxy, [[ssh]] with port forwarding can be used.

=== Simple Proxy with SSH ===

Connect to a server (HOST) on which you have an account (USER) as follows

$ ssh -D ''PORT'' ''USER''@''HOST''

For PORT, choose some number which is not an IANA registered port. This specifies that traffic on the local ''PORT'' will be forwarded to the remote ''HOST''. ssh will act as a [[Wikipedia:SOCKS|SOCKS]] server. Software supporting SOCKS proxy servers can simply be configured to connect to ''PORT'' on localhost. See [[OpenSSH#Forwarding other ports]].

=== HTTPS MITM proxies ===

When debugging HTTPS connections it is sometimes useful to intercept them outside of the browser. In order for the TLS MITM to work you need to trust a [[certificate authority]] of the proxy either in your browser or system-wide.

* {{App|Charles|Graphical trialware written in Java.|https://www.charlesproxy.com/|{{AUR|charles}}}}
* {{App|Fiddler|Proprietary and graphical, running on Mono.|https://www.telerik.com/fiddler|{{AUR|fiddler-appimage}}}}
* {{App|microsocks|Plain simple SOCKS5 proxy server, written in C.|https://github.com/rofl0r/microsocks|{{Pkg|microsocks}}}}
* {{App|mitmproxy|Command-line and web interface, written in Python, also has API.|https://mitmproxy.org/|{{Pkg|mitmproxy}}}}
* {{App|sslsplit|Works with any TLS connections but cannot act as a HTTP proxy in a browser, written in C.|https://www.roe.ch/SSLsplit|{{Pkg|sslsplit}}}}

== Using a SOCKS proxy ==

There are two cases:

* the application you want to use handles [[Wikipedia:SOCKS#SOCKS5|SOCKS5]] proxies (for example [[Firefox]]), then you just have to configure it to use the proxy.
* the application you want to use does not handle SOCKS proxies, then you can try to use {{Pkg|proxychains-ng}}, {{AUR|proxy-ns}}, or [[tor#Torsocks|torsocks]].

In Firefox, you can use the SOCKS proxy in the menu ''Preferences > Network > Settings''. Choose ''Manual Proxy Configuration'', and set the SOCKS Host (and only this one, make sure the other fields, such as HTTP Proxy or SSL Proxy are left empty). For example, if a SOCKS5 proxy is running on localhost port 8080, put {{ic|127.0.0.1}} in the SOCKS Host field, {{ic|8080}} in the Port field, and validate.

If using ''proxychains-ng'', the configuration takes place in {{ic|/etc/proxychains.conf}}. You may have to uncomment the last line (set by default to use [[Tor]]), and replace it with the parameters of the SOCKS proxy. For example, if you are using the same SOCKS5 proxy as above, you will have to replace the last line by:

socks5 127.0.0.1 8080

Then, ''proxychains-ng'' can be launched with

$ proxychains ''program''

Where {{ic|''program''}} can be any program already installed on your system (e.g. xterm, gnome-terminal, etc).

If using ''proxy-ns'', the configuration takes place in {{ic|/etc/proxy-ns/config.json}}. You may have to change the ''socks5_address''. An example configuration using SOCKS5 proxy as above looks like this:

{{hc|/etc/proxy-ns/config.json|2=
{
"tun_name": "tun0",
"tun_ip": "10.0.0.1/24",
"socks5_address": "127.0.0.1:8080",
"fake_dns": true,
"fake_network": "240.0.0.0/4",
"dns_server": "9.9.9.9"
}
}}

Then, ''proxy-ns'' can be launched with:

$ proxy-ns ''program''

The usage is the same as ''proxychains''.

If using ''tsocks'', the configuration takes place in {{ic|/etc/tsocks.conf}}. See {{man|5|tsocks.conf}} for the options. An example minimum configuration looks like this:

{{hc|/etc/tsocks.conf|2=
server = 127.0.0.1
server_port = 8080
server_type = 5
default_user = ""
default_pass = ""}}

=== curl and pacman ===

You may set the {{ic|all_proxy}} environment variable to let curl and pacman (which uses curl) use your socks5 proxy:

$ export all_proxy="socks5://your.proxy:1080"

== Proxy settings on GNOME ==

Some programs like [[Chromium]] and [[Firefox]] can use the settings stored by GNOME. These settings can be modified through the gnome-control-center front end and also through ''gsettings''.

gsettings set org.gnome.system.proxy mode 'manual'
gsettings set org.gnome.system.proxy.http host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.http port 8080
gsettings set org.gnome.system.proxy.ftp host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.ftp port 8080
gsettings set org.gnome.system.proxy.https host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.https port 8080
gsettings set org.gnome.system.proxy.socks host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.socks port 8080
gsettings set org.gnome.system.proxy ignore-hosts "['localhost', '127.0.0.0/8', '10.0.0.0/8', '192.168.0.0/16', '172.16.0.0/12' , '*.localdomain.com' ]"

As GNOME is often used with NetworkManager, see also [[NetworkManager#Proxy settings]]. It does not appear that NetworkManager supports fetching the configuration from the GNOME settings above without a GNOME desktop.



== Microsoft NTLM proxy ==

In a Windows network, NT LAN Manager (NTLM) is a suite of Microsoft security protocols which provides authentication, integrity, and confidentiality to users.

A local proxy stands between your applications and the NTLM proxy, adding NTLM authentication on-the-fly.

(NTLM PROXY IP:PORT + CREDENTIALS + OTHER INFO) -----> '''(127.0.0.1:PORT)'''

Two options are available from [[AUR]]:
* {{AUR|alpaca-proxy}}
* {{AUR|cntlm}}

=== Alpaca ===

{{AUR|alpaca-proxy}} from [[AUR]] is a local HTTP proxy for command-line tools. It supports proxy auto-configuration (PAC) files and NTLM authentication.

==== Usage ====

Alpaca can be launched interactively, which requires entering a password:

$ alpaca -d MYDOMAIN -u me
Password (for MYDOMAIN\me):

To launch alpaca non-interactively, a NTLM hash needs to be generated and exported as a variable:

$ ./alpaca -d MYDOMAIN -u me -H
Password (for MYDOMAIN\me):
NTLM_CREDENTIALS="me@DOMAIN:00000000000000000000000000000000"; export NTLM_CREDENTIALS

Alpaca will by default listen on {{ic|localhost:''3128''}}, this can be overridden using the {{ic|-l}} and {{ic|-p}} options.

Furthermore a proxy PAC url should be provided as a parameter of the {{ic|-C}} option.

==== Running as a service ====

{{AUR|alpaca-proxy}} includes the {{ic|alpaca.service}} [[systemd/User|systemd user service]], which can be used to start alpaca automatically in a non-interactive way.

It requires the following environment variables to be set in {{ic|~/.config/alpaca.environment}}:

LISTEN_ADDRESS=localhost
LISTEN_PORT=3128
NTLM_CREDENTIALS="me@DOMAIN:00000000000000000000000000000000"
PAC_URL="<nowiki>http://some.url/to/some-file.pac</nowiki>"

=== Cntlm ===

{{AUR|cntlm}} from the [[AUR]] can be configured with several "parent" proxies and Cntlm will try one after another until one works. All authenticated connections are cached and reused to achieve high efficiency.

==== Configuration ====

Change settings in {{ic|/etc/cntlm.conf}} as needed, except for the password. Then run:

$ cntlm -H

This will generate encrypted password hashes according to your proxy hostname, username and password.

{{Warning|{{Pkg|ettercap}} can easily sniff your password over LAN when using plain-text passwords instead of encrypted hashes.}}

Edit {{ic|/etc/cntlm.conf}} again and include all three generated hashes, then [[enable]] {{ic|cntlm.service}}.

To test settings, run:

$ cntlm -v

==== Usage ====

Use {{ic|127.0.0.1:''port''}} or {{ic|localhost:''port''}} as a proxy adress. {{ic|''port''}} matches the {{ic|Listen}} parameter in {{ic|/etc/cntlm.conf}}, which by default is {{ic|3128}}.

Proxy server

2026-05-13T13:14:43Z

Indigo: move /* HTTPS MITM proxies */ as subsection into /* Web proxy options */ (unchanged); the tools extend the regular http proxies for special test purposes, MITM is too specific as first section for this general article

[[Category:Proxy servers]]
[[Category:Network configuration]]
[[ja:プロキシ設定]]
[[zh-hans:Proxy server]]
{{Related articles start}}
{{Related|HTTP tunneling}}
{{Related articles end}}

According to [[Wikipedia:Proxy server|Wikipedia]]:
:In computer networks, a proxy server is a server (a computer system or an application) that acts as an intermediary for requests from clients seeking resources from other servers.

Proxying can be applied in common Internet protocols such as HTTP or [[Wikipedia:SOCKS|SOCKS]].

== Environment variables ==

{{Expansion|To export the environment everywhere (more or less), they could be set in {{ic|/etc/environment}}, {{ic|/etc/environment.d/*.conf}} and {{ic|~/.config/environment.d/*.conf}}.}}

Some programs, such as [[wget]] and (used by [[pacman]]) [[CURL]], use environment variables of the form {{ic|''protocol''_proxy}} to determine the proxy for a given protocol (e.g. HTTP, FTP, ...).

Below is an example on how to set these variables in a shell:

{{bc|1=
export http_proxy=http://10.203.0.1:5187/
export https_proxy=$http_proxy
export ftp_proxy=$http_proxy
export rsync_proxy=$http_proxy
export no_proxy="localhost,127.0.0.1,localaddress,.localdomain.com"
}}

Some programs look for the all caps version of the environment variables.

If the proxy environment variables are to be made available to all users and all applications, the above mentioned export commands may be added to a script, say {{ic|proxy.sh}} inside {{ic|/etc/profile.d/}}. The script has to be then made [[executable]]. This method is helpful while using a desktop environment like [[Xfce]] which does not provide an option for proxy configuration. For example, [[Chromium]] browser will make use of the variables set using this method while running XFCE.

Alternatively, there is a tool named {{AUR|proxyman-git}} which claims to configure system-wide proxy settings easily. It also handles proxy configurations of other software like [[git]], [[npm]], [[Dropbox]], etc.

Alternatively you can automate the toggling of the variables by adding a function to your {{ic|.bashrc}}:

{{bc|<nowiki>
function proxy_on() {
export no_proxy="localhost,127.0.0.1,localaddress,.localdomain.com"

if (( $# > 0 )); then
valid=$(echo $@ | sed -n 's/$[0-9]\{1,3\}.\?$\{4\}:$[0-9]\+$/&/p')
if [[ $valid != $@ ]]; then
>&2 echo "Invalid address"
return 1
fi
local proxy=$1
export http_proxy="$proxy" \
https_proxy=$proxy \
ftp_proxy=$proxy \
rsync_proxy=$proxy
echo "Proxy environment variable set."
return 0
fi

echo -n "username: "; read username
if [[ $username != "" ]]; then
echo -n "password: "
read -es password
local pre="$username:$password@"
fi

echo -n "server: "; read server
echo -n "port: "; read port
local proxy=$pre$server:$port
export http_proxy="$proxy" \
https_proxy=$proxy \
ftp_proxy=$proxy \
rsync_proxy=$proxy \
HTTP_PROXY=$proxy \
HTTPS_PROXY=$proxy \
FTP_PROXY=$proxy \
RSYNC_PROXY=$proxy
}

function proxy_off(){
unset http_proxy https_proxy ftp_proxy rsync_proxy \
HTTP_PROXY HTTPS_PROXY FTP_PROXY RSYNC_PROXY
echo -e "Proxy environment variable removed."
}
</nowiki>}}

Omit username or password if they are not needed.

As an alternative, you may want to use the following script.
Change the strings {{ic|YourUserName}}, {{ic|ProxyServerAddress:Port}}, {{ic|LocalAddress}} and {{ic|LocalDomain}} to match your own data, then edit your {{ic|~/.bashrc}} to include the edited functions. Any new bash window will have the new functions. In existing bash windows, type {{ic|source ~/.bashrc}}.
You may prefer to put function definitions in a separate file like {{ic|functions}} then add {{ic|source functions}} to {{ic|.bashrc}} instead of putting everything in {{ic|.bashrc}}. You may also want to change the name "myProxy" into something short and easy to write.

{{bc|<nowiki>
#!/bin/bash

assignProxy(){
PROXY_ENV="http_proxy ftp_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY"
for envar in $PROXY_ENV
do
export $envar=$1
done
for envar in "no_proxy NO_PROXY"
do
export $envar=$2
done
}

clrProxy(){
PROXY_ENV="http_proxy ftp_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY"
for envar in $PROXY_ENV
do
unset $envar
done
}

myProxy(){
user=YourUserName
read -p "Password: " -s pass && echo -e " "
proxy_value="http://$user:$pass@ProxyServerAddress:Port"
no_proxy_value="localhost,127.0.0.1,LocalAddress,LocalDomain.com"
assignProxy $proxy_value $no_proxy_value
}
</nowiki>}}

=== Keep proxy through sudo ===

If the proxy [[environment variables]] are set for the user only they will get lost when running commands with [[sudo]] (or when programs use sudo internally).

A way to prevent that is to add the following line to a [[sudo]] configuration file:

{{hc|/etc/sudoers.d/05_proxy|2=
Defaults env_keep += "*_proxy *_PROXY"
}}

=== Automation with network managers ===

* [[NetworkManager]] cannot change the environment variables.
* [[netctl]] could set-up these environment variables but they would not be seen by other applications as they are not child of netctl.

== About libproxy ==

{{Pkg|libproxy}} is an abstraction library which should be used by all applications that want to access a network resource. It still is in development but could lead to a unified and automated handling of proxies in GNU/Linux if widely adopted.

The role of libproxy is to read the proxy settings from different sources and make them available to applications which use the library. The interesting part with libproxy is that it offers an implementation of the [[Wikipedia:Web_Proxy_Autodiscovery_Protocol|Web Proxy Autodiscovery Protocol]] and an implementation of [[Wikipedia:Proxy_auto-config|Proxy Auto-Config]] that goes with it.

The {{ic|/usr/bin/proxy}} binary takes URL(s) as argument(s) and returns the proxy/proxies that could be used to fetch this/these network resource(s).

{{Note|1=the version 0.4.11 does not support {{ic|1=http_proxy='wpad:'}} because {{ic|1={ pkg-config 'mozjs185 >= 1.8.5'; } }} fails .}}

== Web proxy options ==

* [[Squid]] is a very popular caching/optimizing proxy.
* [[Privoxy]] is an anonymizing and ad-blocking proxy.
* {{Pkg|tinyproxy}} is a small, efficient HTTP/SSL proxy daemon.
* For a simple proxy, [[ssh]] with port forwarding can be used.

=== Simple Proxy with SSH ===

Connect to a server (HOST) on which you have an account (USER) as follows

$ ssh -D ''PORT'' ''USER''@''HOST''

For PORT, choose some number which is not an IANA registered port. This specifies that traffic on the local ''PORT'' will be forwarded to the remote ''HOST''. ssh will act as a [[Wikipedia:SOCKS|SOCKS]] server. Software supporting SOCKS proxy servers can simply be configured to connect to ''PORT'' on localhost. See [[OpenSSH#Forwarding other ports]].

== HTTPS MITM proxies ==

When debugging HTTPS connections it is sometimes useful to intercept them outside of the browser. In order for the TLS MITM to work you need to trust a [[certificate authority]] of the proxy either in your browser or system-wide.

* {{App|Charles|Graphical trialware written in Java.|https://www.charlesproxy.com/|{{AUR|charles}}}}
* {{App|Fiddler|Proprietary and graphical, running on Mono.|https://www.telerik.com/fiddler|{{AUR|fiddler-appimage}}}}
* {{App|microsocks|Plain simple SOCKS5 proxy server, written in C.|https://github.com/rofl0r/microsocks|{{Pkg|microsocks}}}}
* {{App|mitmproxy|Command-line and web interface, written in Python, also has API.|https://mitmproxy.org/|{{Pkg|mitmproxy}}}}
* {{App|sslsplit|Works with any TLS connections but cannot act as a HTTP proxy in a browser, written in C.|https://www.roe.ch/SSLsplit|{{Pkg|sslsplit}}}}

== Using a SOCKS proxy ==

There are two cases:

* the application you want to use handles [[Wikipedia:SOCKS#SOCKS5|SOCKS5]] proxies (for example [[Firefox]]), then you just have to configure it to use the proxy.
* the application you want to use does not handle SOCKS proxies, then you can try to use {{Pkg|proxychains-ng}}, {{AUR|proxy-ns}}, or [[tor#Torsocks|torsocks]].

In Firefox, you can use the SOCKS proxy in the menu ''Preferences > Network > Settings''. Choose ''Manual Proxy Configuration'', and set the SOCKS Host (and only this one, make sure the other fields, such as HTTP Proxy or SSL Proxy are left empty). For example, if a SOCKS5 proxy is running on localhost port 8080, put {{ic|127.0.0.1}} in the SOCKS Host field, {{ic|8080}} in the Port field, and validate.

If using ''proxychains-ng'', the configuration takes place in {{ic|/etc/proxychains.conf}}. You may have to uncomment the last line (set by default to use [[Tor]]), and replace it with the parameters of the SOCKS proxy. For example, if you are using the same SOCKS5 proxy as above, you will have to replace the last line by:

socks5 127.0.0.1 8080

Then, ''proxychains-ng'' can be launched with

$ proxychains ''program''

Where {{ic|''program''}} can be any program already installed on your system (e.g. xterm, gnome-terminal, etc).

If using ''proxy-ns'', the configuration takes place in {{ic|/etc/proxy-ns/config.json}}. You may have to change the ''socks5_address''. An example configuration using SOCKS5 proxy as above looks like this:

{{hc|/etc/proxy-ns/config.json|2=
{
"tun_name": "tun0",
"tun_ip": "10.0.0.1/24",
"socks5_address": "127.0.0.1:8080",
"fake_dns": true,
"fake_network": "240.0.0.0/4",
"dns_server": "9.9.9.9"
}
}}

Then, ''proxy-ns'' can be launched with:

$ proxy-ns ''program''

The usage is the same as ''proxychains''.

If using ''tsocks'', the configuration takes place in {{ic|/etc/tsocks.conf}}. See {{man|5|tsocks.conf}} for the options. An example minimum configuration looks like this:

{{hc|/etc/tsocks.conf|2=
server = 127.0.0.1
server_port = 8080
server_type = 5
default_user = ""
default_pass = ""}}

=== curl and pacman ===

You may set the {{ic|all_proxy}} environment variable to let curl and pacman (which uses curl) use your socks5 proxy:

$ export all_proxy="socks5://your.proxy:1080"

== Proxy settings on GNOME ==

Some programs like [[Chromium]] and [[Firefox]] can use the settings stored by GNOME. These settings can be modified through the gnome-control-center front end and also through ''gsettings''.

gsettings set org.gnome.system.proxy mode 'manual'
gsettings set org.gnome.system.proxy.http host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.http port 8080
gsettings set org.gnome.system.proxy.ftp host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.ftp port 8080
gsettings set org.gnome.system.proxy.https host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.https port 8080
gsettings set org.gnome.system.proxy.socks host 'proxy.localdomain.com'
gsettings set org.gnome.system.proxy.socks port 8080
gsettings set org.gnome.system.proxy ignore-hosts "['localhost', '127.0.0.0/8', '10.0.0.0/8', '192.168.0.0/16', '172.16.0.0/12' , '*.localdomain.com' ]"

As GNOME is often used with NetworkManager, see also [[NetworkManager#Proxy settings]]. It does not appear that NetworkManager supports fetching the configuration from the GNOME settings above without a GNOME desktop.



== Microsoft NTLM proxy ==

In a Windows network, NT LAN Manager (NTLM) is a suite of Microsoft security protocols which provides authentication, integrity, and confidentiality to users.

A local proxy stands between your applications and the NTLM proxy, adding NTLM authentication on-the-fly.

(NTLM PROXY IP:PORT + CREDENTIALS + OTHER INFO) -----> '''(127.0.0.1:PORT)'''

Two options are available from [[AUR]]:
* {{AUR|alpaca-proxy}}
* {{AUR|cntlm}}

=== Alpaca ===

{{AUR|alpaca-proxy}} from [[AUR]] is a local HTTP proxy for command-line tools. It supports proxy auto-configuration (PAC) files and NTLM authentication.

==== Usage ====

Alpaca can be launched interactively, which requires entering a password:

$ alpaca -d MYDOMAIN -u me
Password (for MYDOMAIN\me):

To launch alpaca non-interactively, a NTLM hash needs to be generated and exported as a variable:

$ ./alpaca -d MYDOMAIN -u me -H
Password (for MYDOMAIN\me):
NTLM_CREDENTIALS="me@DOMAIN:00000000000000000000000000000000"; export NTLM_CREDENTIALS

Alpaca will by default listen on {{ic|localhost:''3128''}}, this can be overridden using the {{ic|-l}} and {{ic|-p}} options.

Furthermore a proxy PAC url should be provided as a parameter of the {{ic|-C}} option.

==== Running as a service ====

{{AUR|alpaca-proxy}} includes the {{ic|alpaca.service}} [[systemd/User|systemd user service]], which can be used to start alpaca automatically in a non-interactive way.

It requires the following environment variables to be set in {{ic|~/.config/alpaca.environment}}:

LISTEN_ADDRESS=localhost
LISTEN_PORT=3128
NTLM_CREDENTIALS="me@DOMAIN:00000000000000000000000000000000"
PAC_URL="<nowiki>http://some.url/to/some-file.pac</nowiki>"

=== Cntlm ===

{{AUR|cntlm}} from the [[AUR]] can be configured with several "parent" proxies and Cntlm will try one after another until one works. All authenticated connections are cached and reused to achieve high efficiency.

==== Configuration ====

Change settings in {{ic|/etc/cntlm.conf}} as needed, except for the password. Then run:

$ cntlm -H

This will generate encrypted password hashes according to your proxy hostname, username and password.

{{Warning|{{Pkg|ettercap}} can easily sniff your password over LAN when using plain-text passwords instead of encrypted hashes.}}

Edit {{ic|/etc/cntlm.conf}} again and include all three generated hashes, then [[enable]] {{ic|cntlm.service}}.

To test settings, run:

$ cntlm -v

==== Usage ====

Use {{ic|127.0.0.1:''port''}} or {{ic|localhost:''port''}} as a proxy adress. {{ic|''port''}} matches the {{ic|Listen}} parameter in {{ic|/etc/cntlm.conf}}, which by default is {{ic|3128}}.

Talk:Data-at-rest encryption

2026-05-13T12:49:06Z

Indigo: /* add File encryption tools / secure archiving ? */ re

== Add filesystem encryption ==
It is possible to use encryption offered by filesystems, instead of using something like [[dm-crypt]] and [[eCryptfs]].
In most cases they are even better because they offer more flexibility, performance and without the need of something like [[FUSE]] (but that's not part of this scope).

Should we extend the table listing encryption solutions or simple link to the filesystem page instead?

[[User:Francoism|Francoism]] ([[User talk:Francoism|talk]]) 11:53, 19 November 2018 (UTC)

:Agree. The comparison table mentioned [[fscrypt]]; as far as I know, [[bcachefs]] also natively support encryption. I’m not sure about the advantages, though; there are [https://www.reddit.com/r/zfs/comments/wdrfxp/testing_and_comparing_io_performance_with_and/ some tests] claiming that LUKS is actually faster overall (a little slower write, much faster read). [[User:Franklin Yu|Franklin Yu]] ([[User talk:Franklin Yu|talk]]) 07:59, 4 May 2024 (UTC)

::While bcachefs is an exciting candidate, I'd still give it time before it's added. It's doc points to open todos and testing/fixing enc is still very active (and mainly focussed on chacha, not AES-GCM), to name two reasons. As of today my choice would be ext4 ([[#Add EXT4 transparent folder encryption]]) to add. A re-grouping of methods (block devices, then filesystems before FUSE) may be useful. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:48, 11 December 2024 (UTC)
::I've re-grouped the table with [https://wiki.archlinux.org/index.php?title=Data-at-rest_encryption&diff=824310&oldid=822756]. My next move would be to follow-up [[#Remove deprecated encryptions]] sometime. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:48, 1 January 2025 (UTC)

==Unicode graphs/patterns==
''[Original title was Ascii graphs/patterns]''

Hi,
A small issue unrelated topic : how are ascii graphs/patterns made?
:One method I know is: http://www.asciiflow.com/#Draw
:--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:45, 3 September 2013 (UTC)
::Note that those graphs are not made with simple ASCII characters, but Unicode (I've fixed the title of the discussion).
::Anyway, this is a very interesting question indeed, I too would like to know if there are any editors that can make it easy to draw such diagrams.
::This would also solve [[Talk:Installing Arch Linux with EVMS#Image replacement contest]].
::Finally, an editor like that should be mentioned in [[Help:Style#Non-pertinent content]].
::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 05:47, 4 September 2013 (UTC)
:I created these diagrams manually using [[Wikipedia:Kate_%28text_editor%29|Kate]], which is a normal text editor ''(but it has an advanced feature called "Block Selection Mode" that helps a lot with this kind of stuff)''. I also kept a window of [[Wikipedia:gucharmap|gucharmap]] open on one side of the screen, which allowed me to easily find and pick suitable Unicode characters.
:--[[User:Sas|Sas]] ([[User talk:Sas|talk]]) 19:21, 19 November 2013 (UTC)

==Move out of User page==
This page is quite good IMO. So it can be moved to a normal page. It can receive updates there and other pepole can contribute. -- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 06:20, 11 June 2012 (UTC)
:+1 -- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 09:18, 12 June 2012 (UTC)
: No respons from author. This will block [System_Encryption_with_LUKS] restructure so I do the job to move on.-- [[User:Fengchao|Fengchao]] ([[User talk:Fengchao|talk]]) 02:22, 15 June 2012 (UTC)
:: Hi, and sorry for abandoning this article half-way through and then forgetting about it.
:: As for writing the general introduction/explanation text (part of which consists of merging the corresponding sections from the [[System_Encryption_with_LUKS]] article into this one), I had already started working on that locally back when I created this article, but I have that file on a different computer than I am on now. If you give me until tomorrow (Monday) evening (European time), I'll bring what I have into a readable state and upload it to this page, and then everybody can help modifying/extending it.
:: The reason why I created the article as a user page and didn't move it into the main namespace right away, is that I originally planned to first discuss some feature requests with the wiki maintainers which would make the page more maintainable (without sacrificing user-friendliness). Namely, support for automatically numbered footnotes, and moving the comparison table formatting into a wiki-wide "comparison-table" CSS class (or maybe, separate "comparison-table-vertical" and "comparison-table-horizontal" classes). Right now, the comparison table's wiki markup is so messy and difficult to work with that I would feel guilty asking other people to help add info to it. --[[User:Sas|Sas]] ([[User talk:Sas|talk]]) 17:35, 17 June 2012 (UTC)
::: I added the main text sections now. It would be great if a native speaker with good language skills could do some copyediting for the individual subsections to formulate them more concisely and make them nicer to read. --[[User:Sas|Sas]] ([[User talk:Sas|talk]]) 20:42, 18 June 2012 (UTC)
::::Hi Sas, thank you for getting back working on this article!!
::::About the numbered footnotes, that would require the installation of an extension (involving web developers) and if we can keep it simpler instead it'd be better, since this would be the only article using that feature.
::::About the comparison-table class, can you report an existing example (in another wiki I guess) of what you mean exactly?
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 20:57, 19 June 2012 (UTC)

== Was Serpent judged most secure? ==

According to the fact sheet available from the relevant link (https://web.archive.org/web/20020211162045/http://csrc.nist.gov:80/encryption/aes/round2/aesfact.html), Serpent was not the finalist selected for the relevant standard. According to that fact sheet, the judgement was not that the other finalists (including Serpent) were insecure, but claiming it was judged the most secure seems unmotivated. Have I missed something? What's the source for this? The linked papers are by the researchers who proposed Serpent, aren't they? That's not the judgement of impartial evaluators. --[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 05:03, 4 November 2017 (UTC)

== About hardware-based full disk encryption ==

There's a line stating

"The best remedy might be hardware-based full disk encryption and Trusted Computing."

As it became known over the last few years, disk-based encryption is often either weak, broken or vulnerable to other attaks, like altering the firmware.

So the Arch Wiki recommends a propritary solution, which (from the vendors point of view) must be as cheap and fast as possible.

Should the statement be altered or a warning added?

[[User:Baerbeisser|Baerbeisser]] ([[User talk:Baerbeisser|talk]]) 15:23, 27 July 2019 (UTC)

:About hardware-based FDE, there's already [[Self-Encrypting Drives#Disadvantages]], I think we can expand that if needed.
:About [[Wikipedia:Trusted Computing]], I think the Wikipedia article is a bit biased actually, "trusted computing" may be a term originally suggested by the [[Wikipedia:Trusted Computing Group|Trusted Computing Group]], but to me it has a more generic meaning, and the TCG technology is only an ''implementation'' of the idea (although basically the only one in practice), see e.g. [https://searchsecurity.techtarget.com/definition/trusted-computing], [https://www.eff.org/wp/trusted-computing-promise-and-risk] or even [https://lwn.net/Articles/747564/]. Since we don't link to a specific TC vendor site, and we already say "The best remedy '''might be''' ..." (not '''is'''), I think the Wikipedia article already does a decent job at following up by introducing the possible flaws of the technology, but perhaps we could link to a more neutral external page, or [[Wikipedia:trusted system]]s?
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 07:14, 28 July 2019 (UTC)

== Remove deprecated encryptions ==

Like TrueCrypt and encfs which are deprecated and halted.
The TrueCrypt page is archived...
--[[User:Tiziodcaio|Tiziodcaio]] ([[User talk:Tiziodcaio|talk]]) 23:54, 17 July 2022 (UTC)

:Yes, others have thankfully replaced Truecrypt with [[VeraCrypt]] already, as well as added filesystem alternatives for [[Encfs]] to the tables.
:Perhaps, the table columns for enfcs can be removed in one edit. This would make it easier to re-add, in case it's version 2[https://github.com/vgough/encfs?tab=readme-ov-file#status] does land. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:44, 1 March 2024 (UTC)

:encfs moved to unmaintained status meanwhile. So, it's a candidate to remove in my opinion. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:38, 11 December 2024 (UTC)
:Meanwhile encfs started porting to rust (incl a migration tool[https://github.com/vgough/encfs?tab{{=}}readme-ov-file#status---feb-2026]) and ecryptfs gets no [https://bugs.launchpad.net/ecryptfs/+bugs?orderby=importance&start=0 recent bug report] attention and [[Special:diff/860145| deprecation notice]]. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 17:14, 29 April 2026 (UTC)

== rclone ==

rclone may also be a good option (with rclone crypt + rclone mount).
[[User:Coolwanglu|Coolwanglu]] ([[User talk:Coolwanglu|talk]]) 22:12, 3 October 2022 (UTC)

== Move the page to "Encryption" ==

I think the page should be more generally oriented, maybe naming it with a more general name and moving all the thing truly related with Data-at-rest encryption to a subpage near to File system encryption on other page

--[[User:Tiziodcaio|Tiziodcaio]] ([[User talk:Tiziodcaio|talk]]) 16:49, 21 February 2023 (UTC)

:The [[:Category:Encryption]] contains different topics and this article heads its subcat [[:Category:Data-at-rest encryption]]. It is a generally used term, see [[wikipedia:Data at rest]]. "File system encryption" is more ambigious in my view (see zfs encryption as an example). --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 21:56, 22 February 2023 (UTC)

== add File encryption tools / secure archiving ? ==

Regarding ''Undo revision'' https://wiki.archlinux.org/index.php?diff=872878

Do we have another place for listing some tools, that can encrypt one or few files ? A new wiki page would be oversized. [[User:Ua4000|Ua4000]] ([[User talk:Ua4000|talk]]) 16:52, 12 May 2026 (UTC)

:The gist of your contribution is already crosslinked in [[Security#Data-at-rest encryption]]. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 12:49, 13 May 2026 (UTC)

Help talk:Style/Formatting and punctuation

2026-05-12T17:24:53Z

Indigo: /* systemd-* daemons */ add new item

__TOC__

== Reference links before or after punctuation marks? ==

I was about to revert [https://wiki.archlinux.org/index.php?title=PKGBUILD&diff=next&oldid=354351], but I have not found any rule about it in our guidelines, so I'm proposing to add one.

Basically, reference links are not part of the sentence, so they should be put ''after'' punctuation marks like period or comma. There should be no space between the punctuation mark and the reference link. This style is widely used on [[wikipedia:Wikipedia:Manual_of_Style#Punctuation_and_footnotes|Wikipedia]] and apparently also [http://graphicdesign.stackexchange.com/a/15343 Chicago Manual Of Style].

-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 30 December 2014 (UTC)

:Fine with me, although I just recall using reference links in a sentence the other day, which I (obviously) found appropriate usage as well.[https://wiki.archlinux.org/index.php?title=Network_configuration&diff=352654&oldid=352629] Further, if we are going to introduce "reference link" as a term, it should be noted as a case in [[Help:Style#Hypertext_metaphor]] as well (close to the indirect links bullet). --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:35, 30 December 2014 (UTC)

::Well quoting the linked manual of style:
:::''The superior numerals used for note reference numbers in the text should follow any punctuation marks except the dash, which they precede. The numbers should also be placed outside closing parentheses.''
::So as I understand it, it can be "part of the sentence", just after the respective punctuation (though you wouldn't put a {{ic|1=,}} between the references.) -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 19:56, 30 December 2014 (UTC)

:::Good point, sometimes links are part of the sentence, for example in "...as can be found in [42]." or "...for example [43], [44] and [45]." it does not make sense to place the link after the period. On Wikipedia though, where the reference links are formatted as superscript, you would not find it being part of a sentence anywhere. If we keep formatting reference links as normal-size text, I believe the editors should be free to choose if the reference link will be part of a sentence or not.
:::I would define a reference link as a link without an anchor text (which implies that reference link must be of the syntax {{ic|[''full_url'']}}) and the rule would apply only to reference links that are not part of the sentence. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:08, 30 December 2014 (UTC)

::::In [https://wiki.archlinux.org/index.php?title=PKGBUILD&diff=next&oldid=354351]'s case, I'd prefer the link to be after the period too, and I agree with the observations that have been brought here.
::::Just a quickly-thought idea, we could specify that the rule "would apply only to reference links that are not" ''grammatically'' "part of the sentence".
::::-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:10, 31 December 2014 (UTC)

:::::I like that idea a lot. In my view it would, however, rule out the frequently used "...for example [43], [44] and [45]." cases, because the link count substitution ([43],...) does not make any of them a grammatic part of the sentence. My personal rule of thumb is that the reader should not be required to hover over the link in order to see where it leads out to. Arguably the "for example" does hint enough in this example what the links will lead to. For the wiki here that should be enough; we're using external links in a different manner than wikipedia and the cases they are used in an academic (aka "Chicago") style is very seldom.
:::::I now think we should skip this and leave it up to the editors how they want to present the references. Just make sure we don't end up with bogus sentences like "If [46] is [[Start|started]] with default configuration [47], the journal will show [48]." --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 11:10, 16 January 2015 (UTC)

::::::Draft for [[Help:Style/Formatting and punctuation#Links]]:
::::::* A numbered external link that does not have a grammatical function should appear at the end of the sentence that it supports, immediately ''after'' a punctuation mark that terminates the sentence, unless such mark is a dash or a parenthesis, in which case the link shall be inserted immediately ''before'' it.
::::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:23, 3 June 2017 (UTC)

:::::::Well, after a couple of years, I've actually got used to the option #3 below, which is about the most common style in academic papers. See also [https://tex.stackexchange.com/questions/34414/should-you-put-citations-before-or-after-interpunction this question] and the two answers, and [https://english.stackexchange.com/questions/1751/where-does-the-period-go-in-an-mla-in-text-citation this question] with the same result even for non-numeric references. I should also correct my original reference to the [http://graphicdesign.stackexchange.com/a/15343 Chicago Manual Of Style], which in that snippet talks only about superscripts, which is entirely different beast. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 11:28, 3 June 2017 (UTC)

::::::::I think I've almost always used option #2 here instead, but I don't really mind as long as we agree on a common style. Your proposal would also simplify the wording:
::::::::* A numbered external link that does not have a grammatical function should appear at the end of the sentence that it supports, separated from the last word by one space, and immediately ''before'' a punctuation mark that terminates the sentence. For example:
:::::::::* Lorem ipsum [https://www.archlinux.org], dolor sit (amet consectetur [https://www.archlinux.org]) adipiscing elit [https://www.archlinux.org].
:::::::::Multiple references, still without grammatical function, should be joined without spaces, for example:
:::::::::* Lorem ipsum [https://www.archlinux.org][https://www.archlinux.org], dolor sit (amet consectetur [https://www.archlinux.org][https://www.archlinux.org]) adipiscing elit [https://www.archlinux.org][https://www.archlinux.org].
:::::::::Note that numbered links are automatically enclosed in brackets, so there is no need to further enclose them in parentheses, for example ([https://www.archlinux.org]).
:::::::::Numbered links that have a grammatical function should be treated like regular words, following the same punctuation conventions, for example:
:::::::::* Lorem ipsum, as reported in [https://www.archlinux.org]'s last paragraph, dolor sit amet consectetur adipiscing elit, see also [https://www.archlinux.org], [https://www.archlinux.org] and [https://www.archlinux.org].
::::::::— [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 06:21, 4 June 2017 (UTC)

:::::::::I changed my mind and now support your previous proposal for option #2. I dislike option #3 because placing periods after bold text and a symbol makes them hard to spot. --[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 06:39, 7 October 2018 (UTC)

=== Positioning of numbered external links ===

''[Moved from [[Help talk:Style#Positioning of numbered external links]] — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:02, 3 June 2017 (UTC)]''

# Lorem ipsum dolor sit amet, consectetur adipiscing elit. [http://example.com/]
# Lorem ipsum dolor sit amet, consectetur adipiscing elit.[http://example.com/]
# Lorem ipsum dolor sit amet, consectetur adipiscing elit [http://example.com/].

I have seen all of these. I prefer #1. #2 looks clinched and #3 looks weird.

–[[User:Larivact|Larivact]] ([[User talk:Larivact|talk]]) 05:18, 2 June 2017 (UTC)

== Orphan break line tag? ==

Hi, all!
I'm new to contributing in ArchWiki but I'm not quite familiar with wikitext... I'll try not to make many or serious errors!
Is the "<nowiki> </nowiki>" tag inside the first item of the first list of the article orphan, or do I miss something...?

P.S. I see now my message has a different formating from the rest of the messages in the page... Hows that...?
{{Unsigned|10:46, 1 December 2016 (UTC)|Fragos.george}}

:The usage of {{ic|<nowiki> </nowiki>}} in [[Help:Style/Formatting and punctuation#General rules]] is explained in the last line in [[Help:Style#HTML tags]], basically it's used to add a line break without breaking the list.
:As for your ''different formatting'', see [[Help:Editing#Code]]. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 11:09, 1 December 2016 (UTC)

::Just in case by "orphan" OP meant that the tag is not closed, is an empty tag in HTML, and it takes no end tag. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 11:50, 1 December 2016 (UTC)

:::Why not make it valid XHTML and use {{ic|<nowiki> </nowiki>}}? -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 11:55, 1 December 2016 (UTC)

::::Are you proposing to add a generic style rule (e.g. "always self-close void html tags"), or would you only change the tags in this article? In the former case [[Help:Style#HTML tags]] is the right place, I think I'd be in favor, but then I wouldn't start a campaign to mass-edit the tags in the articles... In the latter case, without a style rule I think it would not make a real difference, since the two syntaxes are well supported by the vast majority of modern browsers anyway. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:36, 2 December 2016 (UTC)

:::::I added the [https://wiki.archlinux.org/index.php?title=Help:Style&curid=11478&diff=458313&oldid=456514 new style rule] with an explicit {{ic|<nowiki> </nowiki>}} example. While mass editing tags would not be the most productive thing to do, maybe [[ArchWiki:Bots|bots]] could update them when making other changes to articles? -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 10:08, 3 December 2016 (UTC)

::::::Well yes, bots could do it indeed. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:03, 3 December 2016 (UTC)

::::{{ic|<nowiki> </nowiki>}} is valid HTML5. We serve HTML5 at Arch Wiki, so the XHTML argument is invalid. {{ic|<nowiki> </nowiki>}} is accepted as well in HTML5, but is not better in any way than {{ic|<nowiki> </nowiki>}}, so it makes no sense to let a bot change all of these. See http://stackoverflow.com/questions/1946426/html-5-is-it-br-br-or-br for more information. (edit: to clarify: I think the rule should not be there and we should remove it) [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 14:01, 3 December 2016 (UTC)

:::::Just like with any other style rule, the purpose of this one would not be to improve the functionality or compatibility with browsers or standards, but more simply to resolve possible editing disputes by stating what is the preferred way to write html tags, and also to have a more consistent source text in general. Usually I do tend to prefer self-closed tags (when I pay attention to that detail, which wasn't clearly the case when I wrote this article :P ), however if more users think that this rule is too strict, when compared to the other ones, we can always just fall back on [[Help:Style#Coding style]]. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 16:03, 3 December 2016 (UTC)

::::::I too think the self-closed style looks better, but I think it is too unimportant to make a rule about. It makes no difference in how the reader experiences the page, both options are technically valid, and the rule only creates extra work for the editors. It also makes the [[Help:Style]] page needlessly longer. The longer it is, the less people will read, honour and memorise it. I really don't see why we should enforce one or the other. [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 16:33, 3 December 2016 (UTC)

:::::::I agree this is too specific to make an explicit rule over. After all, we're not trying to compete with [[w:Wikipedia:Manual of style]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 17:52, 3 December 2016 (UTC)

::::::::How about replacing the usage of {{ic|<nowiki> </nowiki>}} with a template ([[Template:\n]]) which would insert it instead. We could get rid of the special rule for br (and also the one I added) and the page would be shorter than before I edited it. [[Help:Editing#Line breaks]] and maybe others would need adjusting, but it should not make them longer. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 09:44, 4 December 2016 (UTC)

::::::::I rolled back the changes to [[Help:Style]]. Any thoughts about the [[Template:\n]] idea? -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 15:12, 5 December 2016 (UTC)

:::::::::I see, however we're still 2 for and 2 against the new style rule :)
:::::::::Regarding [[Template:\n]], I'm against instead because it feels too complicated, and it would look a bit incoherent to me if a style rule about void tags syntax was rejected because unimportant, but then we passed one to enforce replacing tags altogether. — [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 10:16, 6 December 2016 (UTC)

::::::::::I'm still for the new style rule, it just seemed ''wrong'' to have it sitting there while someone so strongly objects to it. If the '''for''' side wins we can undo the rollback.
::::::::::About [[Template:\n]], I thought that having a template would be preferable to using plain HTML. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 10:31, 6 December 2016 (UTC)

:::::::::::Wikipedia has [[w:Template:break|Template:break]] for this purpose, but it's not just a stupid wrapper around since their Lua module allowed the implementation of the "count" parameter. They also have many similar [[w:Category:Wikipedia_XHTML_tag-replacing_templates|templates to replace XHTML tags]], but most of them are not simple wrappers. Some are convenient shortcuts, some involve Lua programming, and some are there just for consistency. If we want to go the same way (except for Lua obviously), I'd say the "consistency templates" like a wrapper should be created last and not induce the creation of the more complex templates. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:00, 6 December 2016 (UTC)

::::::::::::So, which of the other templates do we ''need''? -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 15:44, 10 December 2016 (UTC)

== Formatting for pseudo-URLs ==

There are many cases which use wording like "Navigate to ''some URL''", where "''some URL''" is usually something like http://yoursite.com/foo/bar, http://yourdomain/foo/bar, http://example.com/foo/bar, http://domain.tld/foo/bar, http://domain:8080/foo/bar or http://localhost/foo/bar. Note that the "/foo/bar" part does not necessarily have to be intended as a pseudo-variable, it is usually a fixed string like "/mediawiki/" or "/phpMyAdmin" which represent the web-application's default location.

How should these links be formatted? I wouldn't like them to be clickable, but links to localhost might be an exception. Then, should they be plain text or something else, and should the pseudo-variable formatting apply to the whole URL or just the variable parts of the URL?

-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:32, 28 February 2020 (UTC)

:They could also be seen as [[Help:Style/Formatting and punctuation#File names and paths]] (maybe we can rename it to "Resource names and paths"), so monospace, which would at the same time solve the problem of allowing to highlight their variable parts with italics.
:I'd also be ok with excepting localhost links, but then [[Help:Style/Formatting and punctuation#Links]] should apply.
:-- [[User:Kynikos|Kynikos]] ([[User talk:Kynikos|talk]]) 15:25, 16 March 2020 (UTC)

:I encountered [https://wiki.archlinux.org/index.php?title=MantisBT&curid=23530&diff=652506&oldid=603264 this one] yesterday. I turned it into a path for now because it was detected as a dead link.
:Perhaps something like the following will work?
::Open [[List of applications/Internet#Web browsers|https://domain.tld/some/path in a web browser]]
:I do not like this too much because this is potentially misleading, but you get the idea. Maybe a new section in [[Help:Reading]] is appropriate for this? Also it requires typing out the full URL which is tedious but acceptable.
:Another idea would be to use https://example.com but I also do not like this because it depends on external resources and this is unnecessary.
:A new template for this might be a good idea, but this potentially requires maintenance and a lot of effort.
:-- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 05:20, 16 February 2021 (UTC)

::I'd avoid formatting the pseudo-URLs as clickable links to something else, because it makes it harder to select the pseudo-URL text (or its part) without actually clicking the link. So I think using monospace with italics, e.g. "Open {{ic|https://''domain.tld''/some/path}} in a [[web browser]].", would be best. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:49, 8 May 2021 (UTC)

:::I agree. But one thing that still needs to be clarified is what example (pseudo) domain/host to use. There are some possible solutions:
:::* ''domain.tld'' - my favorite so far
:::* ''host''
:::* ''address'' - sometimes there is no DNS involved
:::Alternatively one could also use a template perhaps? This is effort and potentially unnecessarily complex. Like this:
::::Open {{ic|https://[[Help:Reading|domain.tld]]:8000/some/path}} and do something.
:::-- [[User:NetSysFire|NetSysFire]] ([[User talk:NetSysFire|talk]]) 09:19, 14 May 2021 (UTC)

::::I like ''domain.tld'' too because of the included dot. It can be easily extended to e.g. ''sub.domain.tld'' if some page talks about subdomains. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:56, 1 August 2021 (UTC)

== Merge Help:Style#Formatting here? ==

This page is all about formatting, so why don't we merge [[Help:Style#Formatting]] here to keep all formatting rules in one place? — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 19:08, 9 September 2023 (UTC)

:+1 for that. I always confuse with them. -- [[User:Andrei Korshikov|Andrei Korshikov]] ([[User talk:Andrei Korshikov|talk]]) 16:45, 17 December 2024 (UTC)

== systemd-* daemons ==

I was looking over [[systemd-resolved]] and found italicising ''systemd-resolved'' confusing, particularly when used in close vicinity of an actual command-line utility like ''resolveconf'', like in [[Systemd-resolved#Automatically]]. Then scoured over style examples and did not find any. I do remember it being discussed long ago, but did not look into history. It gets no better by systemd providing some utilities like ''systemd-run'', ''systemd-resolve / resolvectl '', etc.

Is this exception of italicising the ''systemd-*'' daemons/libraries/tools covered somewhere? I now think it would be better not to italicise them, unless useable on the command-line, except perhaps for highlighting as a first-mention.
--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 17:24, 12 May 2026 (UTC)

Talk:PAM

2026-05-12T16:26:33Z

Indigo: /* Accuracy of PAM#Examples */ re

== Accuracy of PAM#Examples ==
The accuracy of [[PAM#Examples]] was discussed at [https://bbs.archlinux.org/viewtopic.php?id=245892 the forums]. I suggest to
# Mention that nullok inverts pam_unix.so default behavoiur of not allowing blank passwords.
# Remove the claim that
::: - the latter being what pam_permit.so is used for.
::And state that as is, the pam_permit.so line has no effect with this configuration due to the way pam treats an optional module.
02:05, 23 April 2019 (UTC)

Edit: I tried to review this thread at 13 April 2024. My first difficulty was to see the content of the article back then. Was it as in [[Special:Diff/571854/cur]]? 13 April 2024 (UTC)

[[User:Regid|Regid]] ([[User talk:Regid|talk]])
:Technically it's used as a fallback in case no other modules has contributed to the return code. According to manual {{ic|pam_unix(8)}}, {{ic|pam_unix}} can return {{ic|PAM_IGNORE}} which leaves {{ic|pam_permit}} the only one in this stack, hence {{ic|pam_permit}}'s return code is used as the final result. This is a common practice to avoid being locked from the system accidentally.
:[[User:FrederickZh|FrederickZh]] ([[User talk:FrederickZh|talk]]) 20:07, 5 January 2021 (UTC)

::Good point to discuss. The purpose of [[PAM#Examples]] was, as it says with reference to the warning, to illustrate how an single erroneous change (of switching required and optional) can havoc the stack. For that it referenced it default pambase, which was later updated in 08/2021.[https://github.com/archlinux/svntogit-packages/commit/2d5af94ae55a5c98837ce9631f331ad2aad32bb3] Explaining how and when nullok takes effect and when pam_permit applies, was not necessary to show the point (and both would have required deeper dive, yes). Since, the stack and login.defs have changed more; the example does not work anymore. A simple example following current system-auth (to follow the section) would be best, because we don't want users locking themselves out when they try it. Ideas how to update it?
::--[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:15, 26 May 2022 (UTC)

::Revisiting, I added [https://wiki.archlinux.org/index.php?title=PAM&diff=803367&oldid=790245 the reference]. Perhaps another example would be to fiddle with pam_faillock.so to intentionally break that, but it would need a little more verbose.? --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 20:30, 15 March 2024 (UTC)

::@Regid: Regarding your review of 13 April, the diff you link is complicated to overview, but the first example at [[PAM#Examples]] has the status you reviewed in your original comment + my above link addendum. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 22:50, 28 October 2024 (UTC)

::No new ideas from my side for a suitable example. I've now come to the conclusion, it's sufficient to remove the first example of [[PAM#Examples]] and use the existing second as one example, maybe plus another crosslink to [[Security]] for relevant PAM configuration. That is unless someone else has an idea prior. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 19:22, 11 May 2026 (UTC)
::I forgot to mention, I added [https://wiki.archlinux.org/index.php?title=Security&diff=873616&oldid=873614] yesterday to cover {{ic|nullok}} handling. The points mentioned at the beginning of this item may well go in there, if any of you want to cover it. I consider it a better destination, because it's where adjusting PAM pw processing is covered. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 16:26, 12 May 2026 (UTC)

Chromium

2026-05-12T16:02:47Z

Indigo: /* Re-enable Manifest V2 (MV2) extension compatibility */ shorten version (it's the first v148 shipped, hence no ambiguity) in line with other version quoting in the article

[[Category:Web browser]]
[[Category:Google]]
[[de:Chromium]]
[[ja:Chromium]]
[[zh-hans:Chromium]]
{{Related articles start}}
{{Related|Browser extensions}}
{{Related|Firefox}}
{{Related|Vivaldi}}
{{Related articles end}}

[[Wikipedia:Chromium (web browser)|Chromium]] is an open-source graphical web browser based on the [[Wikipedia:Blink (web engine)|Blink]] rendering engine. It is the basis for the proprietary Google Chrome browser.

See [https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md this page] for an explanation of the differences between Chromium and Google Chrome.

{{Tip|
On {{Pkg|chromium}}, Chrome Sync can be temporarily restored by [https://gist.github.com/foutrelis/14e339596b89813aa9c37fd1b4e5d9d5 using Chrome's OAuth2 credentials] or [https://www.chromium.org/developers/how-tos/api-keys getting your own], but pay attention to the disclaimers and do not consider this to be a long-term solution.

Consider switching to [https://www.xbrowsersync.org/ xBrowserSync] for bookmark synchronization as a long-term solution.
}}

See [[List of applications/Internet#Blink-based]] for other browsers based on Chromium.

== Installation ==

[[Install]] the {{Pkg|chromium}} package, which tracks the {{AUR|google-chrome}} releases.

{{Note|From the [https://www.chromium.org/Home/chromium-privacy Chromium privacy page]: "Features that communicate with Google made available through the compilation of code in Chromium are subject to the [https://www.google.com/policies/privacy/ Google Privacy Policy]." For those who want to avoid all integration with Google services, there are some [[List of applications/Internet#Privacy-focused Chromium spin-offs|privacy-focused spin-offs]].}}

== Configuration ==

{{Merge|#Tips and tricks|Most of the content in this section should be split between [[#Tips and tricks]] and maybe [[#Troubleshooting]] for the applicable sections.}}

=== Default applications ===

To set Chromium as the default browser and to change which applications Chromium launches when opening downloaded files, see [[default applications]].

=== Certificates ===

Chromium uses [[Network Security Services]] for certificate management. Certificates can be managed in {{ic|chrome://certificate-manager}}.

The "Local certificates" tab manages server certificates. Certificates added in the "Custom" section are per-profile, and stored in the {{ic|ServerCertificate}} SQLite database in the profile directory. Certificates in the "Linux" section are read from the NSS Shared DB at {{ic|~/.pki/nssdb}}, and cannot be modified in this UI. To add to NSS Shared DB, use another tool such as ''certutil''. See [[#SSL certificates]] for usage examples.

The "Your certificates" tab manages client certificates. Certificates added here are stored in the NSS Shared DB.

=== Making flags persistent ===

{{Note|The {{ic|chromium-flags.conf}} file and the accompanying custom launcher script are specific to the various Chromium packages. For Google Chrome, use {{ic|chrome-flags.conf}} (or {{ic|chrome-''channel''-flags.conf}} for the Dev and Beta channels) instead.}}

You can put your flags in a {{ic|chromium-flags.conf}} file under {{ic|$HOME/.config/}} (or under {{ic|$XDG_CONFIG_HOME}} if you have configured that environment variable) or {{ic|/etc/}} for global.

No special syntax is used; flags are defined as if they were written in a terminal.

* The arguments are split on whitespace and shell quoting rules apply, but no further parsing is performed.
* In case of improper quoting anywhere in the file, a fatal error is raised.
* Flags can be placed in separate lines for readability, but this is not required.
* Lines starting with a hash symbol (#) are skipped. (This is only supported by the Chromium launcher script and will not work when using Google Chrome.)

Below is an example {{ic|chromium-flags.conf}} file that defines the flags {{ic|--start-maximized --incognito}}:

{{hc|~/.config/chromium-flags.conf|
# This line will be ignored.
--start-maximized
--incognito
}}

=== Force GPU acceleration ===

Since at least Chromium 110, GPU acceleration is enabled by default for most systems. You may have to [[append]] the following flags to [[/Tips and tricks#Making flags persistent|persistent configuration]] if your system configuration is matched by the [https://chromium.googlesource.com/chromium/src/gpu/+/master/config/software_rendering_list.json block list]:

{{Warning|Disabling the rendering blocklist may cause unstable behavior, including crashes of the host. See the bug reports in {{ic|chrome://gpu}} for details.}}

{{hc|~/.config/chromium-flags.conf|
--ignore-gpu-blocklist
--enable-zero-copy
}}

=== Hardware video acceleration ===

{{Note|1=<nowiki/>
* There is no official support from Chromium or Arch Linux for this feature [https://chromium.googlesource.com/chromium/src/+/master/docs/gpu/vaapi.md#vaapi-on-linux]. However, {{Pkg|chromium}} from official repositories is compiled with VA-API support and you may ask for help in [https://bbs.archlinux.org/viewtopic.php?id=244031 the dedicated forum thread].
* Since Chromium version 122, an extra [[VA-API]] package is no longer needed. VA-API works when using the native Wayland backend with the {{Pkg|chromium}} package from official repositories.
* Chromium 116 dropped support for Intel iGPUs using {{Pkg|libva-intel-driver}}. To have working h264 acceleration, {{AUR|libva-intel-driver-irql}} is required.
* When trying to find the correct combination of flags in {{ic|chromium-flags.conf}}, note that this file should contain at most one line starting with {{ic|--enable-features}} and {{ic|--disable-features}}. Multiple features must be concatenated with commas.
}}

If you have confirmed working VA-API support by checking the output of {{ic|1=vainfo}} (see [[Hardware video acceleration#Verifying VA-API]]), since Chromium 143 hardware acceleration via VA-API should work out of box. On older Chromium versions you might first try the following flag alone:

{{hc|~/.config/chromium-flags.conf|
--enable-features{{=}}AcceleratedVideoDecodeLinuxGL
}}

{{Note|
* When using EGL/Wayland and Chromium versions prior to 143, using {{ic|--enable-features{{=}}AcceleratedVideoDecodeLinuxGL,AcceleratedVideoDecodeLinuxZeroCopyGL}} instead of the above flag may improve performance.
* Chromium versions prior to 131 should use {{ic|--enable-features{{=}}VaapiVideoDecodeLinuxGL}} instead.
}}

Otherwise, continue reading.

To enable accelerated '''en'''coding in Chromium:
* Append the {{ic|AcceleratedVideoEncoder}} feature, e.g. {{ic|1=--enable-features{{=}}AcceleratedVideoDecodeLinuxGL,AcceleratedVideoEncoder}}. See [https://github.com/chromium/chromium/blob/main/docs/gpu/vaapi.md#vaapi-on-linux] and [https://issues.chromium.org/issues/40225939#comment54] for details.

To enable VA-API support:

* Install the correct VA-API driver for your video card and verify VA-API has been enabled and working correctly, see [[Hardware video acceleration]]. For proprietary NVIDIA support, you must install {{Pkg|libva-nvidia-driver}} and append the {{ic|VaapiOnNvidiaGPUs}} feature in addition to the features above.
* Set the option {{ic|1=--enable-features=VaapiVideoDecoder}}. This is enough when using ANGLE GL renderer and {{Pkg|libva-intel-driver}}.
* When using ANGLE, Chromium forces the older i965 driver and fails when {{Pkg|intel-media-driver}} is used. As a workaround, [[Hardware video acceleration#Configuring VA-API|configure VA-API manually]]. See [https://github.com/intel/media-driver/issues/818] for details.
* To use the system GL renderer on Xorg or Wayland, use {{ic|1=--use-gl=egl}}. Setting this option might no longer be needed when using Chrome 112 and may break GPU acceleration when using AMD GPUs.
* If VA-API still does not work, try the {{ic|1=--enable-features=VaapiIgnoreDriverChecks}} or{{ic|1=--disable-features=UseChromeOSDirectVideoDecoder}} flag
* If VA-API still does not work on X11 and old GPUs, set the {{ic|1=LIBVA_DRI3_DISABLE=1}} [[environment variable]] [https://www.phoronix.com/news/VA-API-libva-2.18].

==== Vulkan ====

When using Vulkan, the following flags are required and might also be sufficient on Chromium 126 and Mesa 24.1:
{{hc|~/.config/chromium-flags.conf|
--enable-features{{=}}VaapiVideoDecoder,VaapiIgnoreDriverChecks,Vulkan,DefaultANGLEVulkan,VulkanFromANGLE
}}
without any of the additional flags mentioned above.

==== Tips and tricks ====

{{Out of date|
* Chromium uses VaapiVideoDecoder for AV1 on Wayland + RADV
* Chromium uses VaapiVideoDecoder for videos of any size on Wayland + RADV
}}

To check if it is working play a video which is using a codec supported by your VA-API driver (''vainfo'' tells you which codecs are supported, but Chromium will only support VP9 and h264):

* Open the DevTools by pressing {{ic|Ctrl+Shift+I}} or on the ''Inspect'' button of the context (right-click) menu
* Add the Media inspection tab: ''Hamburger menu > More tools > Media''
* In the newly opened Media tab, look at the hardware decoder state of the video decoder

Test on a large enough video. Starting with version 86, Chromium on desktop [https://issues.chromium.org/issues/40503293 will only accelerate videos larger than 720p].

To reduce CPU usage while watching YouTube where VP8/VP9 hardware decoding is not available use the [https://chrome.google.com/webstore/detail/h264ify/aleakchihdccplidncghkekgioiakgal h264ify], [https://chrome.google.com/webstore/detail/enhanced-h264ify/omkfmpieigblcllmkgbflkikinpkodlk enhanced-h264ify] or [https://chrome.google.com/webstore/detail/not-yet-av1/dcmllfkiihingappljlkffafnlhdpbai Not yet, AV1][https://bbs.archlinux.org/viewtopic.php?pid=2039884#p2039884] extension.

On some systems (especially on Xwayland) you might need to [[#Force GPU acceleration]]. Only {{ic|--ignore-gpu-blocklist}} is enough for our purposes.

{{Expansion|Provide a link to some bug report.}}

You might need to disable the Skia renderer, as it is currently not compatible with video decode acceleration: {{ic|1=--disable-features=UseSkiaRenderer}}

=== KDE integration ===

For integration into [[Plasma]], you can:

* install {{Pkg|plasma-browser-integration}} on your system, and [https://chromewebstore.google.com/detail/plasma-integration/cimiefiiaegbelhefglklhhakcgmhkai Plasma Integration] in your browser (see [https://community.kde.org/Plasma/Browser_Integration KDE Plasma Browser Integration] for more details)
* install {{Pkg|kdialog}} to allow Chromium to use native KDE open/save dialogs
* [[KDE_Wallet#KDE_Wallet_for_Chromium_and_VSCode|configure Chromium to use KWallet]]

=== PDF viewer plugin ===

Chromium and Google Chrome are bundled with the ''Chromium PDF Viewer'' plugin. If you do not want to use this plugin, check ''Download PDFs'' in {{ic|chrome://settings/content/pdfDocuments}}.

=== Running on Xwayland ===

If you are using NVIDIA's proprietary driver, running Chromium on Xwayland may cause the GPU process to occasionally crash. To prevent the GPU process from crashing, add the following flags:

--use-angle=vulkan --use-cmd-decoder=passthrough

{{Note|This does not prevent all Xwayland-related crashes.}}

=== Native Wayland support ===

Chromium 140 supports [[Wayland]] by default.
For old versions, you can use

--ozone-platform-hint=auto

or

--ozone-platform=wayland

See [[#Making flags persistent]] for a permanent configuration. The flag is also available via [[#chrome:// URLs|browser flags menu]].

This will select wayland Ozone backend when in wayland session, so you can use a single desktop entry if you switch between X11 and Wayland often.

{{Note|When changing the "ozone-platform-hint" in browser flags menu, the browser will provide you a relaunch button. Do not use it, because the browser will still be relaunched in a platform it was before changing the flag. You need to close the browser, then open it.}}

Additionally, if you are having [https://issues.chromium.org/issues/40259478 trouble with input methods] you may also want to force newer GTK:

--gtk-version=4

If a {{ic|AltGr}}/{{ic|Compose}} key stops working, adding this workaround might fix it:

--disable-gtk-ime

If you are using Fcitx5 and not work properly when using the above flags, try using the {{ic|--enable-wayland-ime}} flag instead of {{ic|--gtk-version{{=}}4}}. [https://fcitx-im.org/wiki/Using_Fcitx_5_on_Wayland#Chromium_.2F_Electron]

--enable-wayland-ime --wayland-text-input-version=3

{{Note|Enabling the {{ic|--enable-wayland-ime}} flag works if the {{ic|text_input_v1}} protocol is implemented by default. Known compositors that implement this protocol are: Weston, KWin, Hyprland.}}

==== Touchpad gestures for navigation ====

To enable two finger swipe to go back and forward through your history, use the following flags:

--ozone-platform-hint=auto --enable-features=TouchpadOverscrollHistoryNavigation

==== Force device scale factor ====

{{Merge|HiDPI#Chromium / Google Chrome|Same topic.}}

To force a scale factor on native Wayland, use the following flags [https://chromium.googlesource.com/chromium/src/+/756e64489c84c22998470beddb1facab5e78e1fa]:

--force-device-scale-factor=1.33 --gtk-version=4 --enable-features=WaylandPerSurfaceScale,WaylandUiScale

== Tips and tricks ==

The following tips and tricks should work for both Chromium and Chrome unless explicitly stated.

=== Browsing experience ===

==== chrome:// URLs ====

A number of tweaks can be accessed via Chrome URLs. See '''chrome://chrome-urls''' for a complete list.

* '''chrome://flags''' - access experimental features such as WebGL and rendering webpages with GPU, etc.
* '''chrome://extensions''' - view, enable and disable the currently used Chromium extensions.
* '''chrome://gpu''' - status of different GPU options.
* '''chrome://sandbox''' - indicate sandbox status.
* '''chrome://version''' - display version and switches used to invoke the active {{ic|/usr/bin/chromium}}.

An automatically updated, complete listing of Chromium switches (command line parameters) is available at https://peter.sh/experiments/chromium-command-line-switches/.

==== Chromium task manager ====

Shift+ESC can be used to bring up the browser task manager wherein memory, CPU, and network usage can be viewed.

==== Chromium overrides/overwrites Preferences file ====

If you enabled syncing with a Google Account, then Chromium will override any direct edits to the Preferences file found under {{ic|~/.config/chromium/Default/Preferences}}. To work around this, start Chromium with the {{ic|--disable-sync-preferences}} switch:
$ chromium --disable-sync-preferences

If Chromium is started in the background when you login in to your desktop environment, make sure the command your desktop environment uses is:
$ chromium --disable-sync-preferences --no-startup-window

==== Search engines ====

Make sites like [https://wiki.archlinux.org wiki.archlinux.org] and [https://en.wikipedia.org wikipedia.org] easily searchable by first executing a search on those pages, then going to ''Settings > Search'' and click the ''Manage search engines..'' button. From there, "Edit" the Wikipedia entry and change its keyword to '''w''' (or some other shortcut you prefer). Now searching Wikipedia for "Arch Linux" from the address bar is done simply by entering "'''w arch linux'''".

{{Note| Google search is used automatically when typing something into the URL bar. A hard-coded keyword trigger is also available using the '''?''' prefix.}}

==== Tmpfs ====

===== Cache in tmpfs =====

{{Note|Chromium stores its cache separate from its browser profile directory.}}

To limit Chromium from writing its cache to a physical disk, one can define an alternative location via the {{ic|--disk-cache-dir}} flag:

$ chromium --disk-cache-dir="$XDG_RUNTIME_DIR/chromium-cache"

Cache should be considered temporary and will '''not''' be saved after a reboot or hard lock. Another option is to setup the space in {{ic|/etc/fstab}}:

{{hc|/etc/fstab|2=
tmpfs /home/''username''/.cache/chromium tmpfs noatime,nodev,nosuid,size=''400M'' 0 0
}}

Alternatively create a symbolic link to {{ic|/tmp}}. Make sure to delete Chromium's cache folder before you run the command:

$ ln -s /tmp /home/''username''/.cache/chromium

===== Profile in tmpfs =====

Relocate the browser profile to a [[tmpfs]] filesystem, including {{ic|/tmp}}, or {{ic|/dev/shm}} for improvements in application response as the entire profile is now stored in RAM.

Use an active profile management tool such as {{Pkg|profile-sync-daemon}} for maximal reliability and ease of use. It symlinks or bind mounts and syncs the browser profile directories to RAM. For more, see [[Profile-sync-daemon]].

==== Launch a new browser instance ====

When you launch the browser, it first checks if another instance using the same data directory is already running. If there is one, the new window is associated with the old instance. If you want to launch an independent instance of the browser, you must specify separate directory using the {{ic|--user-data-dir}} parameter:

$ chromium --user-data-dir=''/path/to/some/directory''

{{Note|The default location of the user data is {{ic|~/.config/chromium/}}.}}

==== Directly open *.torrent files and magnet links with a torrent client ====

By default, Chromium downloads {{ic|*.torrent}} files directly and you need to click the notification from the bottom-left corner of the screen in order for the file to be opened with your default torrent client. This can be avoided with the following method:

* Download a {{ic|*.torrent}} file.
* Right-click the notification displayed at the bottom-left corner of the screen.
* Check the "''Always Open Files of This Type''" checkbox.

See [[xdg-open]] to change the default assocation.

==== Touch Scrolling on touchscreen devices ====

You may need to specify which touch device to use. Find your touchscreen device with {{ic| xinput list}} then launch Chromium with the {{ic|1=--touch-devices='''x'''}} parameter, where "'''x'''" is the id of your device. {{Note|If the device is designated as a slave pointer, using this may not work, use the master pointer's ID instead.}}

==== Reduce memory usage ====

By default, Chromium uses a separate OS process for each ''instance'' of a visited web site. [https://www.chromium.org/developers/design-documents/process-models#Supported_Models] However, you can specify command-line switches when starting Chromium to modify this behaviour.

For example, to share one process for all instances of a website:

$ chromium --process-per-site

To use a single process model:

$ chromium --single-process

{{Warning|The single-process model is discouraged because it is unsafe and may contain bugs not present in other models.[https://www.chromium.org/developers/design-documents/process-models#TOC-Single-process]}}

In addition, you can suspend or store inactive Tabs with extensions such as [https://chrome.google.com/webstore/detail/tab-suspender/fiabciakcmgepblmdkmemdbbkilneeeh?hl=en Tab Suspender] and [https://chrome.google.com/webstore/detail/onetab/chphlpgkkbolifaimnlloiipkdnihall?hl=en OneTab].

==== User Agent ====

The User Agent can be arbitrarily modified at the start of Chromium's base instance via its {{Ic|<nowiki>--user-agent="[string]"</nowiki>}} parameter.

==== Forcing specific GPU ====

In multi-GPU systems, Chromium automatically detects which GPU should be used for rendering (discrete or integrated). This works 99% of the time, except when it does not - if an unavailable GPU is picked (for example, discrete graphics on VFIO GPU passthrough-enabled systems), {{ic|chrome://gpu}} will complain about not being able to initialize the GPU process.

On this page below '''Driver Information''' there will be multiple GPUs shown (GPU0, GPU1, ...). There is no user-friendly way to switch between them. However we can read their PCI addresses then compel Chromium to select the GPU at a specific PCI address via command-line argument:

{{hc|$ ls -l /dev/dri/by-path/|
pci-0000:'''01:00.0'''-render -> ../../renderD128
pci-0000:'''03:00.0'''-render -> ../../renderD129
}}

Then we can identify which is which:

{{hc|lspci -k {{!}} grep "'''01:00.0'''\{{!}}'''03:00.0'''"|
'''01:00.0''' VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Ellesmere [Radeon RX 470/480/570/570X/580/580X/590]
'''03:00.0''' VGA compatible controller: NVIDIA Corporation GA106 [GeForce RTX 3060 Lite Hash Rate] (rev a1)
}}

Then to launch Chromium:
$ chromium --render-node-override=/dev/dri/by-path/pci-0000:'''01:00.0'''-render
or
$ chromium --render-node-override=/dev/dri/by-path/pci-0000:'''03:00.0'''-render

Unfortunately the simpler {{ic|/dev/dri/renderD128}} or {{ic|/dev/dri/renderD129}} specifiers are unstable and subject to change based on driver/kernel module load order.

==== Import bookmarks from Firefox ====

To ease the transition, you can import bookmarks from [[Firefox]] into Chromium.

Navigate Chromium to {{ic|chrome://settings/importData}}

If Firefox is already installed on your computer, you can directly import bookmarks as well as many other things from Firefox.

Make sure '''Mozilla Firefox''' is selected. Optionally, you can uncheck some unwanted items here. Click the '''Import''' and then '''Done'''. You are done with it.

{{note|If you have not created any bookmarks in Chromium yet, the bookmarks will show up in your bookmarks bar. If you already have bookmarks, the bookmarks will be in a new folder labeled "Imported From Firefox"}}

If you import bookmarks from another PC, you have to export bookmarks from Firefox first.

{{ic|Ctrl+Shift+o}} ''Import and Backup > Export Bookmarks To HTML'' in Firefox.

The procedure is pretty much the same. You need to go to {{ic|chrome://settings/importData}}. However, this time, in the '''From''' drop-down menu, select '''Bookmarks HTML File''' and click the '''Choose File''' button and upload the desired bookmark file.

==== Enabling autoscroll with middle mouse button ====

The autoscroll is still an experimental feature [https://niek.github.io/chrome-features/]. It is intended to be disabled by default if Chromium or Chromium-based browsers are not a development build and is running on a Linux environment. [https://issues.chromium.org/issues/40811836]

To enable this feature, launch your browser with the {{ic|1=--enable-features=MiddleClickAutoscroll}} flag. In case you want to make the option persistent, see [[#Making flags persistent]].

{{Note|
* While setting {{ic|--enable-blink-features}} works in the same way as only typing {{ic|--enable-features}}, the browser instead may display a warning to state this is an unsupported flag, which "stability and security will suffer".
* As an alternative you can add an extension like [https://chromewebstore.google.com/detail/wheely-wheel-scroll-for-l/kkmfljfnlmppiaoijkfaejgkhccokpdn WHEELY] with similar behavior from Chrome Web Store.
}}

{{Tip|Another option is to [[install]] {{AUR|chromium-extension-autoscroll}}, but this is not recommended since it is an outdated package and not official. Use it with caution.}}

==== U2F authentication ====

Install {{Pkg|libfido2}} library. This provides the udev rules required to enable access to the [[U2F]] key as a user.
U2F keys are by default only accessible by root, and without these rules Chromium will give an error.

==== Theming ====

You can make Chromium use your current GTK theme for browser menus and controls. Simply press ''Use GTK'' in {{ic|chrome://settings/appearance}}.

==== Dark mode ====

Since Chromium 114, [[XDG Desktop Portal]] is used to automatically determine the user's preferred appearance ([https://issues.chromium.org/issues/40642550 issue]), thereby dissociating dark mode enablement from the user's GTK theme. This preference will be applied to ''prefers-color-scheme'' in CSS, JavaScript, Settings and Dev-Tools.

The way to change the preferred appearance depends on your XDG Desktop Portal backend. For instance, many desktop environments have a switch in their appearance settings. Or when using e.g. {{Pkg|xdg-desktop-portal-gtk}}, set the preferred mode to {{ic|prefer-light}}, {{ic|prefer-dark}} or {{ic|default}} with:

$ dconf write /org/gnome/desktop/interface/color-scheme \'prefer-dark\'

You can query the current preferred appearance using {{ic|dbus-send}} in {{Pkg|dbus}} ([https://flatpak.github.io/xdg-desktop-portal/#gdbus-org.freedesktop.portal.Settings documentation]):

$ dbus-send --session --print-reply=literal --dest=org.freedesktop.portal.Desktop /org/freedesktop/portal/desktop org.freedesktop.portal.Settings.Read string:org.freedesktop.appearance string:color-scheme | tr -s ' ' | cut -d ' ' -f 5

* '''0''': No preference
* '''1''': Prefer dark appearance
* '''2''': Prefer light appearance

===== Pre Chromium 114 =====

To enable dark mode and enable the dark theme (normally used for incognito mode) [[append]] the following flag to [[#Making flags persistent|persistent configuration]]:

{{hc|1=~/.config/chromium-flags.conf|2=
--force-dark-mode
--enable-features=WebUIDarkMode
}}

==== Enable Side Panel ====

The Side Panel can be enabled through {{ic|chrome://flags}}. You can enable or disable '''Side panel''', and change options such as '''Side panel border''' and '''Side panel drag and drop'''.

=== Profile maintenance ===

Chromium uses [[SQLite]] databases to manage history and the like. Sqlite databases become fragmented over time and empty spaces appear all around. But, since there are no managing processes checking and optimizing the database, these factors eventually result in a performance hit. A good way to improve startup and some other bookmarks- and history-related tasks is to defragment and trim unused space from these databases.

{{Pkg|profile-cleaner}} and {{AUR|browser-vacuum}} do just this.

=== Security ===

==== Disable JIT ====

At the cost of reduced performance, you can disable just-in-time compilation of JavaScript to native code, which is responsible for [https://microsoftedge.github.io/edgevr/posts/Super-Duper-Secure-Mode/ roughly half of the security vulnerabilities in the JS engine], using the flag {{ic|1=--js-flags=--jitless}}.

==== WebRTC ====

WebRTC is a communication protocol that relies on JavaScript that can leak one's actual IP address and hardware hash from behind a VPN. While some software may prevent the leaking scripts from running, it is probably a good idea to block this protocol directly as well, just to be safe. As of October 2016, there is no way to disable WebRTC on Chromium on desktop, there are extensions available to disable local IP address leak, one is this [https://chrome.google.com/webstore/detail/webrtc-network-limiter/npeicpdbkakmehahjeeohfdhnlpdklia extension].

One can test WebRTC via https://browserleaks.com/webrtc.

{{Warning|Even though IP leak can be prevented, Chromium still sends your unique hash, and there is no way to prevent this. More information is available at https://browserleaks.com/webrtc#howto-disable-webrtc.}}

==== SSL certificates ====

See [[#Certificates]] for general information.

===== Adding CAcert certificates for self-signed certificates =====

Grab the CAcerts and create an {{ic|nssdb}}, if one does not already exist. To do this, first install the {{Pkg|nss}} package, then complete these steps:

$ mkdir -p $HOME/.pki/nssdb
$ cd $HOME/.pki/nssdb
$ certutil -N -d sql:.

$ curl -k -o "cacert-root.crt" "http://www.cacert.org/certs/root.crt"
$ curl -k -o "cacert-class3.crt" "http://www.cacert.org/certs/class3.crt"
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org" -i cacert-root.crt
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "CAcert.org Class 3" -i cacert-class3.crt

{{Note|Users will need to create a password for the database, if it does not exist.}}

Now users may manually import a self-signed certificate.

===== Example 1: Using a shell script to isolate the certificate from TomatoUSB =====

Below is a simple script that will extract and add a certificate to the user's {{ic|nssdb}}:

#!/bin/sh
#
# usage: import-cert.sh remote.host.name [port]
#
REMHOST=$1
REMPORT=${2:-443}
exec 6>&1
exec > $REMHOST
echo | openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "$REMHOST" -i $REMHOST
exec 1>&6 6>&-

Syntax is advertised in the commented lines.

References:
*https://web.archive.org/web/20180718193807/https://blog.avirtualhome.com/adding-ssl-certificates-to-google-chrome-linux-ubuntu
*https://chromium.googlesource.com/chromium/src/+/master/docs/linux/cert_management.md

===== Example 2: Using Firefox to isolate the certificate from TomatoUSB =====

The {{Pkg|firefox}} browser can be used to save the certificate to a file for manual import into the database.

Using firefox:
#Browse to the target URL.
#Upon seeing the "This Connection is Untrusted" warning screen, click: ''I understand the Risks > Add Exception...''
#Click: ''View > Details > Export'' and save the certificate to a temporary location ({{ic|/tmp/easy.pem}} in this example).

Now import the certificate for use in Chromium:
$ certutil -d sql:$HOME/.pki/nssdb -A -t TC -n "easy" -i /tmp/easy.pem

{{Note|Adjust the name to match that of the certificate. In the example above, "easy" is the name of the certificate.}}

Reference:
*https://sahissam.blogspot.com/2012/06/new-ssl-certificates-for-tomatousb-and.html

==== Canvas Fingerprinting ====

Canvas fingerprinting is a technique that allows websites to identify users by detecting differences when rendering to an HTML5 canvas. This information can be made inaccessible by using the {{ic|--disable-reading-from-canvas}} flag.

To confirm this is working run [https://panopticlick.eff.org this test] and make sure "hash of canvas fingerprint" is reported as undetermined in the full results.

{{Note|1=<nowiki/>
* Some extensions require reading from canvas and may be broken by setting {{ic|--disable-reading-from-canvas}}.
* The YouTube player or Google Maps do not work properly without canvas reading (see [https://github.com/qutebrowser/qutebrowser/issues/5345 Qutebrowser issue 5345], [https://bbs.archlinux.org/viewtopic.php?id=255958 BBS#255958], [https://bbs.archlinux.org/viewtopic.php?id=276425 BBS#276425]).
}}

==== Privacy extensions ====

See [[Browser extensions#Privacy]].

{{Tip|Installing too many extensions might take up much space in the toolbar. Those extensions which you would not interact with anyway can be hidden by right-clicking on the extension and choosing ''Hide in Chromium menu''.}}

==== Do Not Track ====

To enable [[wikipedia:Do Not Track|Do Not Track]], visit {{ic|chrome://settings}}, scroll down to ''Advanced'' and under ''Privacy and security'', check ''Send a "Do Not Track" request with your browsing traffic''.

==== Force a password store ====

Chromium uses a password store to store your passwords and the ''Chromium Safe Storage'' key, which is used to encrypt cookie values. [https://codereview.chromium.org/24734007]

By default Chromium auto-detects which password store to use, which can lead to you apparently losing your passwords and cookies when switching to another desktop environment or window manager.

You can force Chromium to use a specific password store by launching it with the {{ic|--password-store}} flag with one of following the values [https://chromium.googlesource.com/chromium/src/+/master/docs/linux/password_storage.md]:

* {{ic|gnome-libsecret}}, uses [[Gnome Keyring]] via [https://gitlab.gnome.org/GNOME/libsecret libsecret].
* {{ic|kwallet5}}, uses [[KDE Wallet]] 5
* {{ic|kwallet6}}, uses [[KDE Wallet]] 6
* {{ic|basic}}, saves the passwords and the cookies' encryption key as plain text in the file {{ic|Login Data}}
* {{ic|detect}}, the default auto-detect behavior

For example, to force Chromium to use Gnome Keyring in another desktop or WM use {{ic|1=--password-store=gnome-libsecret}}, see [[#Making flags persistent]] for making it permanent.

When using a password store of another desktop environment you probably also want to unlock it automatically. See [[GNOME/Keyring#Using the keyring]] and [[KDE Wallet#Unlock KDE Wallet automatically on login]].

==== Enable hybrid post-quantum key exchange ====

Chromium supports the hybrid post-quantum key exchange [https://www.ietf.org/archive/id/draft-tls-westerbaan-xyber768d00-02.html X25519Kyber768] for TLS 1.3 since version 155 [https://blog.chromium.org/2023/08/protecting-chrome-traffic-with-hybrid.html]. This feature is disabled by default, but can be enabled using the {{Ic|chrome://flags/#enable-tls13-kyber}} flag.

=== Open any website as a native application ===

You can open any website in a tabless window intended for [https://developer.chrome.com/blog/getting-started-pwa/ Progressive Web Apps]:

$ chromium --app=''https://archlinux.org/''

You need to use a correct full URL. This could be combined with {{ic|--user-data-dir}} to split configs. Local html file is also used at native application with {{ic|1=--allow-file-access-from-files --app=file://*}}.

=== Force offline ===

You can force offline state by {{ic|1=--proxy-server=dummy}} for security when you use local html file from Chromium.

=== Faster downloading ===

Chromium has {{ic|--enable-parallel-downloading}} flag for parallel downloading without extensions.

=== Re-enable Manifest V2 (MV2) extension compatibility ===

{{Warning|
Manifest V2 extensions are deprecated for '''security reasons''' and Google recommends against using them.

See [https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3 What is Manifest V3] and [https://developer.chrome.com/docs/extensions/develop/migrate/mv2-deprecation-timeline Manifest V2 support timeline] for more information.}}

As of {{Pkg|chromium}} version 148, manifest V2 support can be re-enabled to use popular extensions such as the original (non-Lite) [https://chromewebstore.google.com/detail/ublock-origin/cjpalhdlnbpafiamejdnhcphjbkeiagm uBlock Origin] extension.

To do so, launch Chromium with the following flags:

$ chromium --enable-features=AllowLegacyMV2Extensions --disable-features=ExtensionsManifestV3Only,ExtensionManifestV2Unsupported,ExtensionManifestV2Disabled

See also [[#Making flags persistent]].

{{Note|The enterprise policy [https://chromeenterprise.google/intl/en_us/policies/#ExtensionManifestV2Availability ExtensionManifestV2Availability] was deprecated in Chromium version 139 and is no longer available.}}

== Troubleshooting ==

=== Fonts ===

{{Note|Chromium does not fully integrate with fontconfig/GTK/Pango/X/etc. due to its sandbox. For more information, see the [https://dev.chromium.org/developers/linux-technical-faq Linux Technical FAQ].}}

==== Tab font size is too large ====

Chromium will use the GTK settings as described in [[GTK#Configuration]]. When configured, Chromium will use the {{ic|gtk-font-name}} setting for tabs (which may mismatch window font size). To override these settings, use {{ic|1=--force-device-scale-factor=1.0}}.

Since Chrome Refresh 2023 became default, GNOME users with Cantarell font may notice some characters (like lowercase g) cut off in the tab title. See the [https://issues.chromium.org/issues/40934082 issue on chromium.org].

Until the issue resolved, a workaround is to replace Cantarell with another font using a configuration based on [[Font configuration#Set default or fallback fonts]], e.g.

{{hc|~/.config/fontconfig/conf.d/10-chromium-font.conf|<nowiki>
<match target="pattern">
<test name="prgname" compare="eq">
<string>chromium</string>
</test>
<test qual="any" name="family">
<string>Cantarell</string>
</test>
<edit name="family" mode="assign" binding="strong">
<string>Ubuntu</string>
</edit>
</match>
</nowiki>}}

This configuration will apply only if process name {{ic|chromium}} matches. You can use {{ic|chrome}} for Google Chrome.

=== WebGL ===

There is the possibility that your graphics card has been blacklisted by Chromium. See [[#Force GPU acceleration]].

If you are using Chromium with [[Bumblebee]], WebGL might crash due to GPU sandboxing. In this case, you can disable GPU sandboxing with {{ic|optirun chromium --disable-gpu-sandbox}}.

Visit {{ic|chrome://gpu/}} for debugging information about WebGL support.

Chromium can save incorrect data about your GPU in your user profile (e.g. if you use switch between an Nvidia card using Optimus and Intel, it will show the Nvidia card in {{ic|chrome://gpu}} even when you are not using it or primusrun/optirun). Running using a different user directory, e.g, {{ic|1=chromium --user-data-dir=$(mktemp -d)}} may solve this issue. For a persistent solution you can reset the GPU information by deleting {{ic|~/.config/chromium/Local\ State}}.

=== Incorrect HiDPI rendering ===

Chromium will automatically scale for a [[HiDPI]] display, however, this may cause an incorrectly rendered GUI.

The flag {{ic|1=--force-device-scale-factor=1}} may be used to overrule the automatic scaling factor.

=== Incorrect window size and mouse position on Wayland fractional scaling ===

When [[#Native Wayland support|native Wayland support]] is enabled, Chromium will automatically scale based on the configured scale of each monitor.

There is a longstanding bug in chromium, which affects electron apps as well, with scaling under wayland when the desktop scale is less than 100% on some compositors (e.g. KDE). Windows will shrink themselves on every interaction and mouse positioning is scaled by the desktop scale percentage. The flag {{ic|1=--disable-features=WaylandPerSurfaceScale}} can be used to disable this behavior.

The flag {{ic|1=--disable-features=WaylandPerSurfaceScale}} was removed in Chromium v146, but the flag {{ic|1=--disable-features=WaylandFractionalScaleV1}} disables the broken behavior.

=== Password prompt on every start with GNOME Keyring ===

See [[GNOME/Keyring#Passwords are not remembered]].

=== Everything is syncing except for password ===

If synchronization is not working for password only (you can check it on {{ic|chrome://sync-internals/}}) delete profile login data:

$ rm ~/.config/chromium/Default/Login\ Data*

See [https://support.google.com/chrome/thread/9947763?hl=en&msgid=23687608 Google Chrome Help forum] for details.

=== Losing cookies and passwords when switching between desktop environments ===

If you see the message {{ic|Failed to decrypt token for service AccountId-*}} in the terminal when you start Chromium, it might try to use the wrong password storage backend. This might happen when you switch between Desktop Environments.

See [[#Force a password store]].

=== Hang on startup when Google Sync enabled ===

Try launching Chrome with {{ic|1=--password-store=basic}} or another appropriate password store.

See [[#Force a password store]].

=== Chromium asks to be set as the default browser every time it starts ===

If you are using KDE and have once set Firefox as the default browser (by clicking the button inside Firefox), you might find Chromium asks to be set as the default browser every time it starts, even if you click the "set as default" button.

Chromium checks for this status by running {{ic|xdg-settings check default-web-browser chromium.desktop}}. If the output is "no", it is not considering itself to be the default browser. The script {{ic|xdg-settings}} checks for the following MIME associations and expect all of them to be {{ic|chromium.desktop}}:

{{bc|
x-scheme-handler/http
x-scheme-handler/https
text/html}}

To fix it, go to ''System settings > Applications > Default applications > Web browser'' and choose Chromium. Then, set the MIME association for {{ic|text/html}}:

$ xdg-mime default chromium.desktop text/html

Finally, [[XDG MIME Applications#New MIME types|update the MIME database]]:

$ update-mime-database ~/.local/share/mime

=== "This browser or app may not be secure" error logging in to Google ===

As of 2020.04.20 if you run chromium with {{ic|1=--remote-debugging-port=9222}} flag for web development, you cannot log in to your Google account. Temporarily disable this flag to login and then you can enable it back.

=== Chromium rendering at 60 FPS despite using a display with a higher refresh rate ===

See [https://issues.chromium.org/issues/40761642 the general issue] which may contain some additional workarounds and [https://issues.chromium.org/issues/40725152 a sister issue about mixed refresh rates].

==== Mixed refresh rates ====

{{Tip|This issue is possibly not present on the Wayland backend, needs testing.}}

When using displays with mixed refresh rates(for example 60Hz and 144Hz), Chromium might render for the lower Hz display.

There is a suitable workaround for this issue, [[append]] the following flags to [[#Making flags persistent|persistent configuration]]:

{{hc|1=~/.config/chromium-flags.conf|2=
--use-gl=egl
--ignore-gpu-blocklist
--enable-gpu-rasterization
}}

This should make Chromium run at 144 FPS when used on a 144Hz display, assuming your compositor is also refreshing at 144 FPS.
Keep in mind it might be a little choppy due to {{Bug|67035}}, but it is way better than being stuck at 60 FPS.

==== Running on the Wayland backend ====

There seem to be Wayland compositor-specific problems that trigger this issue.
Notably, Plasma 5 seems to only ever render on 60Hz no matter the setup, but Plasma 6(rc1, at the time of writing) makes Chromium work flawlessly on high refresh rates.

A workaround may be to switch to the XWayland backend if all else fails.

=== Chromium slow scroll speed ===

Mouse whell scrolling in chromium and electron based applications may be too slow for daily usage. Here are some solutions.

[[Libinput#Mouse wheel scrolling speed scaling]] injects {{ic|libinput_event_pointer_get_axis_value}} function in libinput and provides an interface to change scale factor. This is not an application level injection, so an addition script for application specific scale factor tuning is needed. Note that scroll on chromium's small height developer tools may be too fast when scale factor is big enough.

[[IMWheel]] increases scroll distance by replaying X wheel button event for multiple times. However, chromium assumes the real scroll and the replayed ones as two events. There is a small but noticeable delay between them, so one mouse wheel scroll leads to twice page jumps. Also, touchpad scroll needs additional care.

[https://chrome.google.com/webstore/detail/linux-scroll-speed-fix/mlboohjioameadaedfjcpemcaangkkbp Linux Scroll Speed Fix] and [https://chrome.google.com/webstore/detail/smoothscroll/nbokbjkabcmbfdlbddjidfmibcpneigj SmoothScroll] are two chromium extensions with support for scroll distance modification. Upon wheel scroll in a web page, the closest scrollable ancestor of current focused node will be found, then a scroll method with given pixel distance will be called on it, even if it has been scrolled to bottom. So once you scroll into a text editor or any scrollable element, you can never scroll out of it, except moving mouse. Also, extension based methods can not be used outside chromium.

=== Videos load but do not play ===

{{Out of date|The linked section states that Chromium is not affected.}}

This may be a PulseAudio issue. See the suggested fix in [[PulseAudio/Troubleshooting#Browsers (firefox) load videos but do no play]].

=== Passwords are not saved due to a corrupted database ===

The stored password database can become corrupted and in need of getting rebuilt. Doing so will destroy all data therein/lose stored passwords.

Launch chromium from a terminal and look for output like:
[472531:472565:1207/055404.688559:ERROR:login_database.cc(1048)] Password decryption failed, encryption_result is 2

Exit chromium and then delete these three database files: {{ic|~/.config/chromium/Default/Login Data*}}

Launching chromium again should re-create them.

=== Cursor is not correct on KDE Wayland ===

See [[KDE#Plasma cursor sometimes shown incorrectly]].

=== Chromium window is transparent under Wayland ===

Due to a [https://issues.chromium.org/issues/329678163 bug], chromium 124 must be started with the explicit command line flag {{ic|1=--ozone-platform=wayland}}.

=== Wayland hardware acceleration buffer handle is null errors ===

Due to a [https://issues.chromium.org/issues/331796411 bug], you may see the below in your log when launching from terminal, especially with hardware acceleration enabled on Wayland:

{{bc|[333310:333425:0919/121130.103852:ERROR:gpu_channel.cc(502)] Buffer Handle is null.
[333341:18:0919/121130.104000:ERROR:shared_image_interface_proxy.cc(134)] Buffer handle is null. Not creating a mailbox from it.
[333310:333425:0919/121130.137149:ERROR:gbm_pixmap_wayland.cc(82)] Cannot create bo with format{{=}} YUV_420_BIPLANAR and usage{{=}}SCANOUT_CPU_READ_WRITE
}}

Workaround for now is adding this flag:
{{hc|1=~/.config/chromium-flags.conf|2=
--disable-gpu-memory-buffer-video-frames
}}

=== No audio available without sound server ===

Chromium does not support [[Advanced Linux Sound Architecture#Addressing hardware directly]].
Set output devices {{ic|pcm.dmixer}} and {{ic|pcm.dsnooper}} as seen in the page and use {{ic|1=-alsa-output-device=pcm.dmixer -alsa-input-device=pcm.dsnooper}} flags.

=== Gnome "Global Shortcuts" menu appears on startup ===

Due to extensions which define global shortcuts (such as obsidian web clipper), the gnome "Global Shortcuts" appears at startup. This is described in https://github.com/brave/brave-browser/issues/44886 and can be fixed by adding this flag:

{{hc|1=~/.config/chromium-flags.conf|2=
--disable-features=GlobalShortcutsPortal
}}

=== Compose key does not work: Typing special characters with keyboard not possible ===

Due to a bug the "Compose" key does not work in recent versions of chromium. This becomes apparent when user tries to type in special characters such as `@` or umlauts anywhere in the browser. The special key combinations utilizing the compose key (for example `ALT GR`) work in all applications except chromium. This issue is most likely related to gtk and cannot be resolved by switching between Wayland and X11. It is described at https://issues.chromium.org/issues/327158031 and can be fixed by adding this flag:

{{hc|1=~/.config/chromium-flags.conf|2=
--disable-gtk-ime
}}

=== Chromium does not fully maximize on Wayland===
You have to enable ''Use system title bar and borders'' via the ''chrome://settings/appearance'' menu.

=== Chromium has no sound but sound output device is present ===

For WirePlumber users, [[WirePlumber#Delete corrupt settings|resetting WirePlumber state]] may help.

=== File picker does not open when trying to save or download ===
This is a problem with [[XDG Desktop Portal]], restarting the user unit may help.

=== Forcing a specific GPU has no effect on Wayland ===
Sometimes, [[#Forcing specific GPU]] may not work on [[Wayland]], with an error message like so:
{{hc|head=$ chromium --render-node-override="/dev/dri/by-path/pci-0000:01:00.0-render"|output=[46318:46318:0310/131714.847139:ERROR:ui/events/platform/wayland/wayland_event_watcher.cc:47] libwayland: [destroyed object]: error 7: importing the supplied dmabufs failed

# The output below may or may not appear
[0310/133129.221806:ERROR:third_party/crashpad/crashpad/snapshot/elf/elf_dynamic_array_reader.h:64] tag not found
[0310/133129.222571:ERROR:third_party/crashpad/crashpad/util/process/process_memory_range.cc:75] read out of range}}

As of March 10th 2026, the only workaround that works is disabling the unwanted GPU in the firmware (which is not ideal, and even impossible on some systems). It might be possible to achieve the same result by [[Kernel_module#Blacklisting|blacklisting the appropriate kernel modules]], but users might still find this approach undesirable.

Another possibility would be to go back to [[Xorg]] or use [[Xwayland]] [https://issues.chromium.org/issues/40766635#comment19].

More information can be read in [https://forum.vivaldi.net/topic/99688/vivaldi-crashes-at-startup-when-using-wayland], [https://bbs.archlinux.org/viewtopic.php?pid=2269237#p2269237] and [https://issues.chromium.org/issues/40766635].

== See also ==

* [https://www.chromium.org/Home/ Chromium homepage]
* [https://chromereleases.googleblog.com/ Google Chrome release notes]
* [https://chrome.google.com/webstore/ Chrome web store]
* [[Tmpfs]] - Tmpfs Filesystem in {{ic|/etc/fstab}}
* [https://docs.kernel.org/filesystems/tmpfs.html Official tmpfs kernel Documentation]
* [https://github.com/RKNF404/chromium-hardening-guide RKNF404's chromium-hardening-guide on GitHub]

Atrium

2026-05-12T15:47:55Z

Indigo: /* Starting */ reword to distinguish systemd unit and the display manager at hand

{{Lowercase title}}
[[Category:Display managers]]
{{Related articles start}}
{{Related|Display manager}}
{{Related|Wayland}}
{{Related articles end}}

'''atrium''' is a Wayland [[display manager]] with first-class [[Wikipedia:Multiseat configuration|multiseat]] support. In a multiseat setup, multiple users share a single machine, each with their own monitor, keyboard, and mouse and an independent login session. atrium handles each seat automatically: it discovers seats, presents a login screen, authenticates users via [[PAM]], and launches their Wayland compositor.

{{Note|atrium supports Wayland sessions only. X11 sessions are not supported.}}

== Installation ==

[[Install]] {{AUR|atrium}}.

== Configuration ==

{{Note|The default configuration works for most single-seat and standard multiseat setups. This step can be skipped unless something does not work or you need to customise compositor selection.}}

atrium reads two configuration files at startup:

* {{ic|/etc/atrium.conf}} — daemon settings (compositor command, session policy, timeouts)
* {{ic|/etc/atrium-greeter.conf}} — greeter settings (font size, screen blanking timeout, passwordless users)

Both files are installed with commented-out defaults. Refer to the inline comments for available options.

atrium discovers available sessions from {{ic|/usr/share/wayland-sessions/}}. Any installed Wayland compositor that provides a {{ic|.desktop}} file there will appear on the login screen automatically.

== Starting ==

To start atrium, [[enable]] {{ic|atrium.service}} and restart.

{{Note|
* Before enabling the [[systemd]] service, [[disable]] any other display manager.
* [[Starting]] it immediately will terminate any active graphical session.
}}

== Multiseat ==

atrium has built-in multiseat support. Each seat requires its own GPU; atrium discovers seats via logind and launches an independent greeter on each one. Devices must be assigned to seats with {{ic|loginctl attach}}, but no additional configuration is needed.

See [https://github.com/kavau/atrium/blob/main/doc/multiseat-setup.md Multiseat Setup Guide] for a step-by-step device assignment guide.

== Known limitations ==

* '''Limited hotplug''' — GPU or seat removal/addition at runtime is not yet fully handled. Restart atrium to recover (this ends active sessions).
* '''No SIGKILL escalation''' — compositors that ignore SIGTERM are waited on indefinitely.

== See also ==

* [https://github.com/kavau/atrium GitHub repository]
* [https://github.com/kavau/atrium/releases Releases and release notes]
* [https://www.reddit.com/r/linux_multiseat/ r/linux_multiseat] — general Linux multiseat discussion

Talk:PAM

2026-05-11T19:23:01Z

Indigo: /* Accuracy of PAM#Examples */ re

Security

2026-05-11T19:16:16Z

Indigo: /* Disallow empty password */ typo

[[Category:Security]]
[[Category:File systems]]
[[Category:Networking]]
[[de:Sicherheit]]
[[es:Security]]
[[hu:Security]]
[[ja:セキュリティ]]
[[pt:Security]]
[[ru:Security]]
[[zh-hans:Security]]
{{Related articles start}}
{{Related|Arch Security Team}}
{{Related|General recommendations}}
{{Related|Identity management}}
{{Related|Capabilities}}
{{Related|List of Applications/Security}}
{{Related|Arch package guidelines/Security}}
{{Related articles end}}
This article contains recommendations and best practices for [[Wikipedia:Hardening (computing)|hardening]] an Arch Linux system.

== Concepts ==

* It ''is'' possible to tighten security to the point where the system is unusable. Security and convenience must be balanced. The trick is to create a secure ''and'' useful system.
* The biggest threat is, and will always be, the user.
* The [[Wikipedia:Principle of least privilege|principle of least privilege]]: Each part of a system should only be able to access what is strictly required, and nothing more.
* Defense in depth: Security works better in independent layers. When one layer is breached, another should stop the attack.
* Be a little paranoid. And be suspicious. If anything sounds too good to be true, it probably is!
* You can never make a system 100% secure unless you unplug the machine from all networks, turn it off, lock it in a safe, smother it in concrete and never use it.
* Prepare for failure. Create a plan ahead of time to follow when your security is broken.

== Passwords ==

Passwords are key to a secure system. They secure your [[Users and groups|user accounts]], [[Data-at-rest encryption|encrypted filesystems]], and [[SSH keys|SSH]]/[[GPG]] keys. They are the main way a computer chooses to trust the person using it, so a big part of security is just about picking secure passwords and protecting them.

=== Choosing secure passwords ===

Passwords must be complex enough to not be easily guessed from e.g. personal information, or [[Wikipedia:Password cracking|cracked]] using methods like brute-force attacks. The tenets of strong passwords are based on ''length'' and ''randomness''. In cryptography the quality of a password is often referred to as its [[Wikipedia:Password strength#Entropy as a measure of password strength|entropy]].

Insecure passwords include those containing or those using as a base before substitution/variation:

* Personally identifiable information (e.g., your dog's name, date of birth, area code, favorite video game)
* Simple character substitutions on words (e.g., {{ic|k1araj0hns0n}}), as modern dictionary attacks can easily work with these
* Root "words" or common strings followed or preceded by added numbers, symbols, or characters (e.g., {{ic|DG091101%}})
* Common phrases or short strings of common dictionary words (e.g. {{ic|photocopyhauntbranchexpose}}) including with character substitution (e.g. {{ic|Ph0toc0pyh4uN7br@nch3xp*se}}) (See Diceware below for when a combination of dictionary words can be secure)
* Any of the [[Wikipedia:List of the most common passwords|most common passwords]]

The best choice for a password is something long (the longer, the better) and generated from a random source. It is important to use a long password. [https://www.theregister.com/2019/02/14/password_length Weak hash algorithms allow an 8-character password hash to be compromised in just a few hours.]

Tools like {{Pkg|pwgen}} or {{AUR|apg}} can generate random passwords. However, these passwords can be difficult to memorize. One memorization technique (for ones often typed) is to generate a long password and memorize a minimally secure number of characters, temporarily writing down the full generated string. Over time, increase the number of characters typed - until the password is ingrained in muscle memory and need not be remembered. This technique is more difficult, but can provide confidence that a password will not turn up in wordlists or "intelligent" brute force attacks that combine words and substitute characters.

Apart from password management, {{Pkg|keepassxc}} offers password/passphrase generation. It is possible to customize the generation in a GUI. Dictionary based passphrases are also supported.

One technique for memorizing a password is to use a mnemonic phrase, where each word in the phrase reminds you of the next character in the password.
Take for instance “the girl is walking down the rainy street” could be translated to {{ic|t6!WdtR5}} or, less simply, {{ic|t&6!RrlW@dtR,57}}.
This approach could make it easier to remember a password, but note that the various letters have very different probabilities of being found at the start of words ([[Wikipedia:Letter frequency#Relative frequencies of the first letters of a word in the English language|Wikipedia:Letter frequency]]).

Another effective technique can be to write randomly generated passwords down and store them in a ''safe'' place, such as in a wallet, purse, or document safe. Most people do a generally good job of protecting their physical valuables from attack, and it is easier for most people to understand physical security best practices compared to digital security practices.

It is also very effective to combine the mnemonic and random technique by saving long randomly generated passwords with a [[password manager]], which will be in turn accessed with a memorable "master password"/primary password that must be used only for that purpose. The master password must be memorized and never saved. This requires the password manager to be installed on a system to easily access the password (which could be seen as an inconvenience or a security feature, depending on the situation). Some password managers also have smartphone apps which can be used to display passwords for manual entry on systems without that password manager installed (if that is a common use case, you could still use easily typeable but secure passwords for each service instead of completely random ones, see below). Note that a password manager introduces a single point of failure if you ever forget the master password.
Some password managers compute the contained passwords based on the master password and the service name where you want to log in instead of encrypting them, making it possible to use it on a new system without syncing any data.

It can be effective to use a memorable long series of unrelated words as a password. The theory is that if a sufficiently long phrase is used, the gained entropy from the password's length can counter the lost entropy from the use of dictionary words. This [https://xkcd.com/936/ xkcd comic] demonstrates the entropy tradeoff of this method, taking into account the limited set of possible words for each word in the passphrase. If the set of words you choose from is large (multiple thousand words) and you choose 5-7 or even more random words from it, this method provides great entropy, even assuming the attacker knows the set of possible words chosen from and the number of words chosen. The number of possible passphrases after settling on a set of words and number of words is: (number of words in the set of words to select from) to the power of (the number of words chosen for the passphrase). See e.g. [https://www.rempe.us/diceware/ Diceware] for more.

See [https://www.iusmentis.com/security/passphrasefaq/ The passphrase FAQ] or [[Wikipedia:Password strength]] for some additional background.

=== Maintaining passwords ===

Once you pick a strong password, be sure to keep it safe. Watch out for [[Wikipedia:Keylogger|keyloggers]] (software and hardware), screen loggers, [[Wikipedia:Social engineering (security)|social engineering]], [[Wikipedia:Shoulder surfing (computer security)|shoulder surfing]], and avoid reusing passwords so insecure servers cannot leak more information than necessary. [[List of applications/Security#Password managers|Password managers]] can help manage large numbers of complex passwords: if you are copy-pasting the stored passwords from the manager to the applications that need them, make sure to clear the copy buffer every time, and ensure they are not saved in any kind of log (e.g. do not paste them in plain terminal commands, which would store them in files like {{ic|.bash_history}}). Note that password managers that are implemented as browser extensions may be vulnerable to [https://www.spookjs.com side channel attacks]. These can be mitigated by using password managers that run as separate applications.

As a rule, do not pick insecure passwords just because secure ones are harder to remember. Passwords are a balancing act. It is better to have an encrypted database of secure passwords, guarded behind a key and one strong master password, than it is to have many similar weak passwords. Writing passwords down is perhaps equally effective [https://www.schneier.com/blog/archives/2005/06/write_down_your.html], avoiding potential vulnerabilities in software solutions while requiring physical security.

Another aspect of the strength of the passphrase is that it must not be easily recoverable from other places.

If you use the same passphrase for disk encryption as you use for your login password (useful e.g. to auto-mount the encrypted partition or folder on login), make sure that {{ic|/etc/shadow}} ends up on an encrypted partition or/and uses a strong key derivation function (i.e. yescrypt/argon2 or sha512 with PBKDF2, but not md5 or low iterations in PBKDF2) for the stored password hash (see [[SHA password hashes]] for more information).

{{Tip|In 2023 Arch Linux switched the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default hashing] algorithm to yescrypt. If you have not customized the default, executing a password change with {{ic|passwd}} is necessary (and sufficient) to apply the new default.}}

If you are backing up your password database, make sure that each copy is not stored behind any other passphrase which in turn is stored in it, e.g. an encrypted drive or an authenticated remote storage service, or you will not be able to access it in case of need; a useful trick is to protect the drives or accounts where the database is backed up using a simple cryptographic hash of the master password. Maintain a list of all the backup locations: if one day you fear that the master passphrase has been compromised you will have to change it immediately on all the database backups and the locations protected with keys derived from the master password.

Version-controlling the database in a secure way can be very complicated: if you choose to do it, you must have a way to update the master password of all the database versions. It may not always be immediately clear when the master password is leaked: to reduce the risk of somebody else discovering your password before you realize that it leaked, you may choose to change it on a periodical basis. If you fear that you have lost control over a copy of the database, you will need to change all the passwords contained in it within the time that it may take to brute-force the master password, according to its entropy.

=== Password hashes ===

A hash is a one-way function, i.e. it is designed to make it impossible to deduct the input without computing the hash function with it (example: MD5, SHA).

A password-hash function is designed to make deducting a user-input (password) impossible without computing the hash function with it (example: bcrypt). A [[Wikipedia:Key derivation function|key derivation function]] (KDF; examples: yescrypt, scrypt, PBKDF2) is a cryptographic algorithm designed to derive secret keys (e.g. an AES key, a password hash) from an input (a master key, a password). Hence, a KDF can serve multiple applications, including those of a password-hash function.

By default, Arch stores the hashed user passwords in the root-only-readable {{ic|/etc/shadow}} file, separated from the other user parameters stored in the world-readable {{ic|/etc/passwd}} file, see [[Users and groups#User database]]. See also [[#Restricting root]].

Passwords are set with the '''passwd''' command, which [[Wikipedia:Key stretching|stretches]] them with the system's crypt function and then saves them in {{ic|/etc/shadow}}. The passwords are also [[Wikipedia:Salt (cryptography)|salted]] in order to defend them against [[Wikipedia:Rainbow table|rainbow table]] attacks. See also [https://www.slashroot.in/how-are-passwords-stored-linux-understanding-hashing-shadow-utils How are passwords stored in Linux (Understanding hashing with shadow utils)].

Since password hashes follow a defined format, the method and parameter can be configured for subsequent new invocations of the ''passwd'' command. Hence, the individual hashes stored in the {{ic|/etc/shadow}} file can be a heterogeneous mix of the hash functions supported by the system.

See {{man|5|crypt}} for more information on the format, hashing methods and parameters.

The {{ic|/etc/login.defs}} file configures the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default password hashing] method {{ic|ENCRYPT_METHOD YESCRYPT}} and its parameter {{ic|YESCRYPT_COST_FACTOR}}.

For example, an increment of the default {{ic|YESCRYPT_COST_FACTOR}} parameter will lead to a logarithmic increase of the compute time required to deduce the hash from a password. This applies, likewise, to a third-party trying to obtain the password secret, and the system to authenticate a user log-in.

In contrast, the compute time for the SHA-512 hash function is configured by a parameter with a linear influence. See [[SHA password hashes]] for information on the previous Arch default. Note the yescrypt algorithm internally uses SHA-256, HMAC and PBKDF2 to compute its password-hash. The main reason is to combine positive attributes of these widely used and tested functions for an enhanced resistance to attacks. For example, the usability of SHA for various purposes has resulted in hardware support for the function, i.e. the performance to compute a pure SHA hash has accelerated considerably, making its application as a password-hash function more and more derelict.

=== Disallow empty passwords ===

{{Expansion|The [https://github.com/V4bel/dirtyfrag dirtyfrag] kernel vulnerabilities mwnipulated {{ic|/etc/shadow}} and relied on the regularly used {{ic|pam_unis}} option {{ic|nullok}} in {{ic|/etc/pam.d/system-auth}}. Removing this default, thereby disallowing empty passwords, can be an option to increase security. Instructions should be accompanied by commands how to check for user accounts with unset passwords first.}}

=== Enforcing strong passwords with pam_pwquality ===

PAM stands for the Pluggable Authentication Modules. ''pam_pwquality'' provides protection against [[Wikipedia:Dictionary attack|Dictionary attacks]] and helps configure a password policy that can be enforced throughout the system. It is based on ''pam_cracklib'', so it is backwards compatible with its options.

[[Install]] the {{Pkg|libpwquality}} package.

{{Warning|The ''root'' account is not affected by this policy by default.}}

{{Note|
* You can use the ''root'' account to set a password for a user that bypasses the desired/configured policy. This is useful when setting temporary passwords.
* Current security guidelines around passwords, e.g. from NIST, but also from others, do not recommend enforcing special characters, since they often only lead to predictable alterations.
}}

If for example you want to enforce this policy:

* prompt 2 times for password in case of an error (retry option)
* 10 characters minimum length (minlen option)
* at least 6 characters should be different from old password when entering a new one (difok option)
* at least 1 digit (dcredit option)
* at least 1 uppercase (ucredit option)
* at least 1 lowercase (lcredit option)
* at least 1 other character (ocredit option)
* cannot contain the words "myservice" and "mydomain"
* enforce the policy for root

Edit the {{ic|/etc/pam.d/passwd}} file to read as:

{{bc|1=
#%PAM-1.0
password required pam_pwquality.so retry=2 minlen=10 difok=6 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=-1 [badwords=myservice mydomain] enforce_for_root
password required pam_unix.so use_authtok yescrypt shadow
}}

The {{ic|password required pam_unix.so use_authtok}} instructs the ''pam_unix'' module to not prompt for a password but rather to use the one provided by ''pam_pwquality''.

You can refer to the {{man|8|pam_pwquality}} and {{man|8|pam_unix}} man pages for more information.

== CPU ==

=== Microcode ===

See [[microcode]] for information on how to install important security updates for your CPU's microcode.

=== Hardware vulnerabilities ===

Some CPUs contain hardware vulnerabilities. See the [https://docs.kernel.org/admin-guide/hw-vuln/ kernel documentation on hardware vulnerabilities] for a list of these vulnerabilities, as well as mitigation selection guides to help customize the kernel to mitigate these vulnerabilities for specific usage scenarios.

To check if you are affected by a known vulnerability, run the following:

$ grep -r . /sys/devices/system/cpu/vulnerabilities/

In most cases, updating the kernel and microcode will mitigate vulnerabilities.

==== Simultaneous multithreading (hyper-threading) ====

[[Wikipedia:Simultaneous multithreading|Simultaneous multithreading]] (SMT), also called hyper-threading on Intel CPUs, is a hardware feature that may be a source of [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html L1 Terminal Fault] and [https://docs.kernel.org/admin-guide/hw-vuln/mds.html Microarchitectural Data Sampling] vulnerabilities. The Linux kernel and microcode updates contain mitigations for known vulnerabilities, but [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html#virtualization-with-untrusted-guests disabling SMT may still be required on certain CPUs if untrusted virtualization guests are present].

{{Note|Disabling SMT is something mostly hypervisors benefit from.[https://security.stackexchange.com/questions/219753/sacrificing-30-of-my-cpu-performance-by-disabling-hyper-threading-to-fully-mi/219759#219759] On an ordinary system it has very little to no security benefits.}}

SMT can often be disabled in your system's firmware. Consult your motherboard or system documentation for more information. You can also disable SMT in the kernel by adding the following [[kernel parameter]]:

mitigations=auto,nosmt

== Memory ==

=== Hardened malloc ===

{{AUR|hardened_malloc}} is a hardened replacement for [[Wikipedia:GNU C Library|glibc]]'s malloc(). The project was originally developed for integration into Android's [[Wikipedia:Bionic (software)|Bionic]] and [[Wikipedia:musl|musl]] by Daniel Micay, of [[Wikipedia:GrapheneOS|GrapheneOS]], but he has also built in support for standard Linux distributions on the x86_64 architecture.

== Storage ==

=== Data-at-rest encryption ===

[[Data-at-rest encryption]], preferably full-disk encryption with a [[#Passwords|strong passphrase]], is the only way to guard data against physical recovery. This provides data confidentiality when the computer is turned off or the disks in question are unmounted.

Once the computer is powered on and the drive is mounted, however, its data becomes just as vulnerable as an unencrypted drive. It is therefore best practice to unmount data partitions as soon as they are no longer needed.

You may also [[Trusted Platform Module#LUKS encryption|encrypt a drive with the key stored in a TPM]], although it has had [https://tpm.fail vulnerabilites in the past] and the key can be extracted by a [https://pulsesecurity.co.nz/articles/TPM-sniffing bus sniffing attack].

Certain programs, like [[dm-crypt]], allow the user to encrypt a loop file as a virtual volume. This is a reasonable alternative to full-disk encryption when only certain parts of the system need to be secure.

While the block-device or filesystem-based encryption types compared in the [[data-at-rest encryption]] article are useful at protecting data on physical media, most can not be used to protect data on a remote system that you can not control (such as [[Data-at-rest encryption#Cloud-storage optimized|cloud storage]]). In some cases, individual file encryption will be useful.

These are some methods to encrypt files:

* Some [[Archiving and compression|archiving and compressing]] tools also provide basic encryption. Some examples are [[7-Zip]] ({{ic|-p}} flag), {{Pkg|zip}} ({{ic|-e}} flag). The encryption should only be relied on particular care, because the tools may use custom algorithms for cross-platform compatibility.[https://math.ucr.edu/~mike/zipattacks.pdf]
* [[GnuPG]] can be used to [[GnuPG#Encrypt and decrypt|encrypt files]].
* {{Pkg|age}} is a simple and easy to use file encryption tool. It also supports multiple recipients and encryption using SSH keys, which is useful for secure file sharing.

=== File systems ===

The kernel now prevents security issues related to hardlinks and symlinks if the {{ic|fs.protected_hardlinks}} and {{ic|fs.protected_symlinks}} sysctl switches are enabled, so there is no longer a major security benefit from separating out world-writable directories.

File systems containing world-writable directories can still be kept separate as a coarse way of limiting the damage from disk space exhaustion. However, filling {{ic|/var}} or {{ic|/tmp}} is enough to take down services. More flexible mechanisms for dealing with this concern exist (like [[Disk quota|quotas]]), and some [[file systems]] include related features themselves (Btrfs has quotas on subvolumes).

==== Mount options ====

Following the principle of least privilege, file systems should be mounted with the most restrictive mount options possible (without losing functionality).

Relevant mount options are:

* {{ic|nodev}}: Do not interpret character or block special devices on the file system.
* {{ic|nosuid}}: Do not allow set-user-identifier or set-group-identifier bits to take effect.
* {{ic|noexec}}: Do not allow direct execution of any binaries on the mounted file system.
** Setting {{ic|noexec}} on {{ic|/home}} disallows executable scripts and breaks [[Wine]], [[Steam]], PyCharm, [[.NET]], etc.
*** Wine does not need the {{ic|exec}} flag for opening Windows binaries. It is only needed when Wine itself is installed in {{ic|/home}}.
*** To keep [[Steam]] working you can mount {{ic|/home/user/.local/share/Steam}} as {{ic|exec}} in [[fstab]] by adding the following: {{bc|/home/user/.local/share/Steam /home/user/.local/share/Steam none defaults,bind,user,exec,nofail 0 0}}
** Some packages (building {{Pkg|nvidia-open-dkms}} for example) may require {{ic|exec}} on {{ic|/var}}.

File systems used for data should always be mounted with {{ic|nodev}}, {{ic|nosuid}} and {{ic|noexec}}.

Potential file system mounts to consider:

* {{ic|/var}}
* {{ic|/home}}
* {{ic|/dev/shm}}
* {{ic|/tmp}}
* {{ic|/boot}}

{{Tip|When using [[systemd#GPT partition automounting|GPT partition automounting]], the ESP and XBOOTLDR partitions are [https://github.com/systemd/systemd-stable/commit/49804cfb71d3a79f433096e4cfb5616980171336 always hardened] with {{ic|noexec,nosuid,nodev}}.}}

==== Snapshots ====

When utilizing file system snapshots, e.g. with [[Btrfs]], [[LVM]], or [[ZFS]], it is essential to be aware that snapshots may retain sensitive information that users expect to be deleted. This is especially true when automatic snapshotting tools like [[Snapper]] are configured, as they can capture snapshots at regular intervals or in response to system events. Here are some examples of how sensitive information in {{ic|/home/}} can persist within snapshots:

* ''Deleted files and directories'': Even though files or directories are deleted from the file system, they may still exist within older snapshots. This is expected most of the time, but consider whether files and directories such as {{ic|.local/share/Trash/}}, {{ic|.history}}, etc. should be retained.
* ''Temporary files and cache'': Temporary files and cached data generated by applications may be included in snapshots. For example, files kept in encrypted directories might generate thumbnails ({{ic|.cache/thumbnails}}) or work copies when opened, which might in turn be included in snapshots. The same applies e.g. to browsing history ({{ic|.mozilla/}}, {{ic|.config/chromium/}}, etc.), which could have been included in a snapshot before being purged.

If this is supported, consider excluding such directories from snapshots altogether. For example, if using [[Btrfs]], you can create subvolumes for example {{ic|.cache/}}, {{ic|.config/}}, {{ic|.local/}}, {{ic|.var/}} or any other directory according to your use-case.

{{Note|Moving {{ic|.local/share/Trash}} to a separate subvolume might break the trash feature in some cases, e.g. with [[GNOME/Files]].}}

=== File access permissions ===

{{Accuracy|{{ic|chmod go-r}} does not "take away all permissions", it only removes the read permission.}}

The default [[file permissions]] allow read access to almost everything and changing the permissions can hide valuable information from an attacker who gains access to a non-root account such as the {{ic|http}} or {{ic|nobody}} users. You can use [[chmod]] to take away all permissions from the group and others:

# chmod go-r ''path_to_hide''

{{Warning|Do not apply this broadly. Try this for one config at a time, ensuring that it is worth hiding, and that it will not break program functionality. You may need to remove the {{ic|g}} from the command (or re-add the permission with {{ic|chmod g+r ''path''}} if already ran) if the group is relied on.}}

Some paths to consider are:

* {{ic|/boot}}: The [[Partitioning#/boot|boot directory]], which may include traditional [[vmlinuz]] and [[initramfs]] images, or a [[Unified kernel image]]. Note that safe permissions are used by default when using [[systemd#GPT partition automounting]].
* {{ic|/etc/nftables.conf}}: The [[nftables]] configuration, applicable to {{Pkg|nftables}} and {{Pkg|iptables}}.
* {{ic|/etc/iptables}}: The legacy [[iptables]] configuration, applicable to {{Pkg|iptables-legacy}}.

The default [[umask]] {{ic|0022}} can be changed to improve security for newly created files. The [https://apps.nsa.gov/iaarchive/library/ia-guidance/security-configuration/operating-systems/guide-to-the-secure-configuration-of-red-hat-enterprise.cfm NSA RHEL5 Security Guide] suggests a umask of {{ic|0077}} for maximum security, which makes new files not readable by users other than the owner. To change this, see [[Umask#Set the mask value]]. If you use [[sudo]], consider configuring it to use the [[Sudo#Permissive umask|default root umask]].

=== SUID and SGID files ===

It is important to be aware of any files with the [[Wikipedia:Setuid|Setuid]] or Setgid bit. Examples of relevant files with the SUID bit set:

* [[PAM|unix_chkpwd]]
* chage, expiry, gpasswd, groupmems, [[passwd]], sg ({{Pkg|shadow}})
* [[FUSE|fusermount3]], fusermount2
* [[polkit|pkexec]]
* [[OpenSSH|ssh-keysign]]
* chfn, chsh, mount, newgrp, umount, wall, write ({{Pkg|util-linux}})
* [[sudo]], {{Pkg|sudo-rs}}, [[doas]], [[su]], su-rs, [[Kerberos|ksu]]
* [[firejail]]
* [[Dbus|dbus-daemon-launch-helper]]
* [[Chromium|chromium-sandbox]]
* [[Xorg|Xorg.wrap]]

The prominent risks of such executable files include privilege escalation vulnerabilities, see e.g [[Wikipedia:Setuid#Security impact]].[https://www.cvedetails.com/vulnerability-list/vendor_id-16224/product_id-36412/Calibre-ebook-Calibre.html][https://www.cvedetails.com/product/32625/Sudo-Project-Sudo.html?vendor_id=15714][https://www.cvedetails.com/vulnerability-list/vendor_id-16191/Firejail-Project.html]

Files with the SUID bit set and not owned by root, or files with the SGID bit set ''typically'' have less potential impact but can theoretically still do decent damage if vulnerable. It is usually possible to avoid using SUID or SGID by assigning [[Capabilities]] instead.

{{Tip|It is vital to be vigilant in keeping packages which provide SUID/SGID executables up to date in order to prevent having a vulnerable system.}}

To search for files with either the SUID or SGID bit:

$ find / -perm "/u=s,g=s" -type f 2>/dev/null

=== Backups ===

{{Merge|System backup|There is a dedicated page for system backups.}}

Regularly create backups of important data. Regularly test the integrity of the backups. Regularly test that the backups can be restored.

Make sure that at least one copy of the data is stored offline, i.e. not connected to the system under threat in any way. [[Wikipedia:Ransomware|Ransomware]] and other destructive attacks may also attack any connected backup systems.

=== SATA SSD frozen mode ===

See [[Solid state drive#Setting the SATA SSD state to frozen mode after waking up from sleep]].

== User setup ==

=== Do not use the root account for daily use ===

Following the principle of least privilege, do not use the root user for daily use. Create a non-privileged user account for each person using the system. See [[List of applications/Security#Privilege elevation]] for ways of temporarily gaining privileged access.

=== Enforce a delay after a failed login attempt ===

Add the following line to {{ic|/etc/pam.d/system-login}} to add a delay of at least 4 seconds between failed login attempts:

{{hc|/etc/pam.d/system-login|2=
auth optional pam_faildelay.so delay=4000000
}}

{{Note|This line needs to be the first line in the file.}}

{{ic|4000000}} is the time in microseconds to delay.

Other PAM modules besides {{ic|pam_faildelay}} can also suggest such a delay; if multiple modules do so, PAM will use the longest one.

In particular, both {{ic|pam_unix}} and {{ic|pam_faillock}} set a minimum delay of 2 seconds by default.
In order to completely remove this delay, you need to add the {{ic|nodelay}} parameter to any {{ic|auth}} lines of these modules, for example
{{hc|/etc/pam.d/system-auth|2=
auth [success{{=}}1 default{{=}}bad] pam_unix.so try_first_pass nullok nodelay
}}

=== Lock out user after three failed login attempts ===

Since {{Pkg|pambase}} 20200721.1-2, {{ic|pam_faillock.so}} is enabled by default to lock out users for 10 minutes after 3 failed login attempts in a 15 minute period (see {{Bug|67644}}). The lockout only applies to password authentication (e.g. login and ''sudo''), public key authentication over SSH is still accepted. To prevent complete denial-of-service, this lockout is disabled for the root user by default.

To unlock a user, do:

$ faillock --user ''username'' --reset

By default, the lock mechanism is a file per-user located at {{ic|/run/faillock/}}. Deleting or emptying the file unlocks that user—the directory is owned by root, but the file is owned by the user, so the {{ic|faillock}} command only empties the file, therefore does not require root.

The module {{ic|pam_faillock.so}} can be configured with the file {{ic|1=/etc/security/faillock.conf}}. The lockout parameters:

* {{ic|unlock_time}} — the lockout time (in seconds, default 10 minutes).
* {{ic|fail_interval}} — the time in which failed logins can cause a lockout (in seconds, default 15 minutes).
* {{ic|deny}} — the number of failed logins before lockout (default 3).

{{Tip|The primary purpose for the lockout is to slow down brute-force attacks so that they become infeasible. Hence, if lockouts due to mistyping of passwords become too frequent, relaxing the number of attempts may be preferred to reducing the lockout time.}}

{{Note|{{ic|1=deny = 0}} will disable the lockout mechanism entirely.}}

By default, all user locks are lost after reboot. If your attacker can reboot the machine, it is more secure if locks persist. To make locks persist, change the {{ic|dir}} parameter in {{ic|1=/etc/security/faillock.conf}} to {{ic|/var/lib/faillock}}.

No restart is required for changes to take effect. See {{man|5|faillock.conf}} for further configuration options, such as enabling lockout for the root account, disabling for centralized login (e.g. LDAP), etc.

{{Note|If you make locks persistant, following the changes introduced in polkit 127: you may have to relax the sandbox of its helper agent in order to keep it functional. The best way is to create a drop-in for its systemd unit via {{ic|systemctl edit polkit-agent-helper\@.service}} and add:

[Service]
ReadWritePaths{{=}}/var/lib/faillock
}}

=== Limit amount of processes ===

On systems with many, or untrusted users, it is important to limit the number of processes each can run at once, therefore preventing [[Wikipedia:Fork bomb|fork bombs]] and other denial of service attacks. The {{ic|/etc/security/limits.conf}} configuration determines how many processes each user, or group can have open, and is empty (except for useful comments) by default. Adding the following lines to this file will limit all users to 100 active processes, unless they use the {{ic|prlimit}} command to explicitly raise their maximum to 200 for that session. These values can be changed according to the appropriate number of processes a user should have running, or the hardware of the box you are administrating.

* soft nproc 100
* hard nproc 200

The current number of threads for each user can be found with {{ic|ps --no-headers -Leo user {{!}} sort {{!}} uniq --count}}. This may help with determining appropriate values for the users' limits; see also [[limits.conf]].

=== Use Wayland ===

Prefer using [[Wayland]] over [[Xorg]]. Xorg's design predates modern security practices and is [https://security.stackexchange.com/questions/4641/why-are-people-saying-that-the-x-window-system-is-not-secure/4646#4646 considered insecure] by many. For example, Xorg applications may record keystrokes while inactive.

If you must run Xorg, it is recommended to [[Xorg#Rootless Xorg|avoid running it as root]]. Within Wayland, the Xwayland compatibility layer will automatically use rootless Xorg.

== Restricting root ==

The root user is, by definition, the most powerful user on a system. It is also difficult to [[audit]] the root user account. It is therefore important to restrict usage of the root user account as much as possible. There are a number of ways to keep the power of the root user while limiting its ability to cause harm.

=== Use sudo instead of su ===

Using [[sudo]] for privileged access is preferable to [[su]] for a number of reasons:

* It keeps a log of which normal privilege user has run each privileged command.
* The root user password need not be given out to each user who requires root access.
* {{ic|sudo}} prevents users from accidentally running commands as ''root'' that do not need root access, because a full root terminal is not created. This aligns with the [[Wikipedia:Principle of least privilege|principle of least privilege]].
* Individual programs may be enabled per user, instead of offering complete root access just to run one command.

See [[Sudo#Configuration]].

==== Editing files using sudo ====

See [[Sudo#Editing files]]. Alternatively, you can use editors like {{ic|rvim}} or {{ic|rnano}} which have restricted capabilities in order to be safe to run as root.

=== Restricting root login ===

Once [[sudo]] is properly configured, full root access can be heavily restricted or denied without losing much usability. To disable root, but still allowing to use [[sudo]], you can use {{man|1|passwd}} with {{ic|passwd --lock root}}.

==== Allow only certain users ====

The [[PAM]] {{ic|pam_wheel.so}} lets you allow only users in the group {{ic|wheel}} to login using [[su]]. See [[su#su and wheel]].

==== Denying SSH login ====

Even if you do not wish to deny root login for local users, it is always good practice to [[OpenSSH#Deny|deny root login via SSH]]. The purpose of this is to add an additional layer of security before a user can completely compromise your system remotely.

==== Specify acceptable login combinations with access.conf ====

{{Warning|If you are using GNOME 49 or later, you should make sure the group ''gdm'' can log in locally. This can be done with a {{ic|+:(gdm):LOCAL}} rule. [https://gitlab.gnome.org/GNOME/gdm/-/issues/1021]}}

When someone attempts to log in with [[PAM]], {{ic|/etc/security/access.conf}} is checked for the first combination that matches their login properties. Their attempt then fails or succeeds based on the rule for that combination.

+:root:LOCAL
-:root:ALL

Rules can be set for specific groups and users. In this example, the user archie is allowed to login locally, as are all users in the wheel and adm groups. All other logins are rejected:

+:archie:LOCAL
+:(wheel):LOCAL
+:(adm):LOCAL
-:ALL:ALL

Read more at {{man|5|access.conf}}

== Mandatory access control ==

[[Wikipedia:Mandatory Access Control|Mandatory access control]] (MAC) is a type of security policy that differs significantly from the [[Wikipedia:Discretionary Access Control|discretionary access control]] (DAC) used by default in Arch and most Linux distributions. MAC essentially means that every action a program could perform that affects the system in any way is checked against a security ruleset. This ruleset, in contrast to DAC methods, cannot be modified by users. Using virtually any mandatory access control system will significantly improve the security of your computer, although there are differences in how it can be implemented.

=== Pathname MAC ===

Pathname-based access control is a simple form of access control that offers permissions based on the path of a given file. The downside to this style of access control is that permissions are not carried with files if they are moved around the system. On the positive side, pathname-based MAC can be implemented on a much wider range of filesystems, unlike labels-based alternatives.

* [[AppArmor]] is a [[Wikipedia:Canonical (company)|Canonical]]-maintained MAC implementation seen as an "easier" alternative to SELinux.
* [[TOMOYO]] is another simple, easy-to-use system offering mandatory access control. It is designed to be both simple in usage and in implementation, requiring very few dependencies.

=== Labels MAC ===

Labels-based access control means the extended attributes of a file are used to govern its security permissions. While this system is arguably more flexible in its security offerings than pathname-based MAC, it only works on filesystems that support these extended attributes.

* [[SELinux]], based on an [[Wikipedia:NSA|NSA]] project to improve Linux security, implements MAC completely separate from system users and roles. It offers an extremely robust multi-level MAC policy implementation that can easily maintain control of a system that grows and changes past its original configuration.

=== Access Control Lists ===

[[Access Control Lists]] (ACLs) are an alternative to attaching rules directly to the filesystem in some way. ACLs implement access control by checking program actions against a list of permitted behavior.

== Kernel hardening ==

=== Kernel self-protection / exploit mitigation ===

The {{pkg|linux-hardened}} package uses a [https://github.com/anthraxx/linux-hardened basic kernel hardening patch set] and more security-focused compile-time configuration options than the {{pkg|linux}} package. A custom build can be made to choose a different compromise between security and performance than the security-leaning defaults.

However, it should be noted that several packages (such as {{pkg|throttled}}) will not work when using this kernel.

If you use an out-of-tree driver such as [[NVIDIA]], you may need to switch to its [[DKMS]] package.

==== Userspace ASLR comparison ====

The {{pkg|linux-hardened}} package provides an improved implementation of Address Space Layout Randomization for userspace processes. The {{pkg|paxtest}} command can be used to obtain an estimate of the provided entropy:

===== 64-bit processes =====

{{hc|linux-hardened 5.4.21.a-1-hardened|
Anonymous mapping randomization test : 32 quality bits (guessed)
Heap randomization test (ET_EXEC) : 40 quality bits (guessed)
Heap randomization test (PIE) : 40 quality bits (guessed)
Main executable randomization (ET_EXEC) : 32 quality bits (guessed)
Main executable randomization (PIE) : 32 quality bits (guessed)
Shared library randomization test : 32 quality bits (guessed)
VDSO randomization test : 32 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 40 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 40 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 44 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 44 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 34 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 34 quality bits (guessed)
Randomization under memory exhaustion @~0: 32 bits (guessed)
Randomization under memory exhaustion @0 : 32 bits (guessed)
}}

{{hc|linux 5.5.5-arch1-1|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 20 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 29 bits (guessed)
Randomization under memory exhaustion @0 : 29 bits (guessed)
}}

{{hc|linux-lts 4.19.101-1-lts|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 19 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 28 bits (guessed)
Randomization under memory exhaustion @0 : 28 bits (guessed)
}}

===== 32-bit processes (on an x86_64 kernel) =====

{{hc|linux-hardened|
Anonymous mapping randomization test : 16 quality bits (guessed)
Heap randomization test (ET_EXEC) : 22 quality bits (guessed)
Heap randomization test (PIE) : 27 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 18 quality bits (guessed)
Shared library randomization test : 16 quality bits (guessed)
VDSO randomization test : 16 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 24 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 24 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 28 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 28 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 18 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 16 quality bits (guessed)
Randomization under memory exhaustion @~0: 18 bits (guessed)
Randomization under memory exhaustion @0 : 18 bits (guessed)
}}

{{hc|linux|
Anonymous mapping randomization test : 8 quality bits (guessed)
Heap randomization test (ET_EXEC) : 13 quality bits (guessed)
Heap randomization test (PIE) : 13 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 8 quality bits (guessed)
Shared library randomization test : 8 quality bits (guessed)
VDSO randomization test : 8 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 19 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 19 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 11 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 11 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 8 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 13 quality bits (guessed)
Randomization under memory exhaustion @~0: No randomization
Randomization under memory exhaustion @0 : No randomization
}}

=== Restricting access to kernel pointers in the proc filesystem ===

Setting {{ic|kernel.kptr_restrict}} to 1 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} from regular users without {{ic|CAP_SYSLOG}}, making it more difficult for kernel exploits to resolve addresses/symbols dynamically. This will not help that much on a pre-compiled Arch Linux kernel, since a determined attacker could just download the kernel package and get the symbols manually from there, but if you are compiling your own kernel, this can help mitigating local root exploits. This will break some {{Pkg|perf}} commands when used by non-root users (but many {{Pkg|perf}} features require root access anyway). See {{Bug|34323}} for more information.

Setting {{ic|kernel.kptr_restrict}} to 2 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} regardless of privileges.

{{hc|/etc/sysctl.d/51-kptr-restrict.conf|2=
kernel.kptr_restrict = 1
}}

{{Note|{{pkg|linux-hardened}} sets {{ic|1=kptr_restrict=2}} by default rather than {{ic|0}}.}}

=== BPF hardening ===

BPF is a system used to load and execute bytecode within the kernel dynamically during runtime. It is used in a number of Linux kernel subsystems such as networking (e.g. XDP, tc), tracing (e.g. kprobes, uprobes, tracepoints) and security (e.g. seccomp). It is also useful for advanced network security, performance profiling and dynamic tracing.

BPF was originally an acronym of [[Wikipedia:Berkeley Packet Filter|Berkeley Packet Filter]] since the original classic BPF was used for packet capture tools for BSD. This eventually evolved into Extended BPF (eBPF), which was shortly afterwards renamed to just BPF (not an acronym). BPF should not be confused with packet filtering tools like iptables or netfilter, although BPF can be used to implement packet filtering tools.

BPF code may be either interpreted or compiled using a [[Wikipedia:Just-in-time compilation|Just-In-Time (JIT) compiler]]. The Arch kernel is built with {{ic|CONFIG_BPF_JIT_ALWAYS_ON}} which disables the BPF interpreter and forces all BPF to use JIT compilation. This makes it harder for an attacker to use BPF to escalate attacks that exploit SPECTRE-style vulnerabilities. See [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=290af86629b25ffd1ed6232c4e9107da031705cb the kernel patch which introduced CONFIG_BPF_JIT_ALWAYS_ON] for more details.

The kernel includes a hardening feature for JIT-compiled BPF which can mitigate some types of JIT spraying attacks at the cost of performance and the ability to trace and debug many BPF programs. It may be enabled by setting {{ic|net.core.bpf_jit_harden}} to {{ic|1}} (to enable hardening of unprivileged code) or {{ic|2}} (to enable hardening of all code).

See the {{ic|net.core.bpf_*}} settings in the [https://docs.kernel.org/admin-guide/sysctl/net.html kernel documentation] for more details.

{{Tip|
* {{Pkg|linux-hardened}} sets {{ic|1=net.core.bpf_jit_harden=2}} by default rather than {{ic|0}}.
* By default, BPF programs can be run even by unprivileged users. To change that behaviour set {{ic|1=kernel.unprivileged_bpf_disabled=1}}[https://access.redhat.com/security/cve/cve-2021-33624].
}}

=== ptrace scope ===

The {{man|2|ptrace}} syscall provides a means by which one process (the "tracer") may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. {{ic|ptrace}} is commonly used by debugging tools including ''gdb'', ''strace'', ''perf'', ''reptyr'' and other debuggers. However, it also provides a means by which a malicious process can read data from and take control of other processes.

Arch enables the [https://docs.kernel.org/admin-guide/LSM/Yama.html Yama LSM] by default, which provides a {{ic|kernel.yama.ptrace_scope}} [[kernel parameter]]. This parameter is set to {{ic|1}} (restricted) by default which prevents tracers from performing a {{ic|ptrace}} call on traces outside of a restricted scope unless the tracer is privileged or has the {{ic|CAP_SYS_PTRACE}} [[Capabilities|capability]]. This is a significant improvement in security compared to the classic permissions. Without this module, there is no separation between processes running as the same user (in the absence of additional security layers such as {{man|7|pid_namespaces}}).

{{Note|By default, you can still use tools which require {{ic|ptrace}} by running them as privileged processes, e.g. using [[sudo]].}}

If you do not need to use debugging tools, consider setting {{ic|kernel.yama.ptrace_scope}} to {{ic|2}} (admin-only) or {{ic|3}} (no {{ic|ptrace}} possible) to harden the system.

{{Note|Some anti-cheat and DRM implementations rely on {{ic|ptrace}} to work, including Easy Anti-Cheat and Ubisoft Connect under Wine. Setting this parameter to {{ic|2}} or higher might prevent games using these solutions from launching.}}

=== hidepid ===

{{Expansion|1=[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0fb5ce62c5920b6e0a8a061f2fe80e0403281e10 Linux 5.8 implemented private instances] and new values for {{ic|1=hidepid=}}.}}

{{Accuracy|Enabling {{ic|hidepid}} globally is not a supported way of operation by [[systemd]], nor does it have any practical improvements security-wise when systemd is running as service manager. [https://github.com/systemd/systemd/issues/29893#issuecomment-1798030108]}}

{{Warning|
* This may cause issues for certain applications like an application running in a sandbox and [[Xorg]] (see workaround).
* This causes issues with [[D-Bus]], [[Polkit]], [[PulseAudio]] and [[bluetooth]] when using {{Pkg|systemd}} > 237.64-1.
}}

The kernel has the ability to hide other users' processes, normally accessible via {{ic|/proc}}, from unprivileged users by mounting the {{ic|proc}} filesystem with the {{ic|1=hidepid=}} and {{ic|1=gid=}} options documented in https://docs.kernel.org/filesystems/proc.html.

This greatly complicates an intruder's task of gathering information about running processes, whether some daemon runs with elevated privileges, whether other user runs some sensitive program, whether other users run any program at all, makes it impossible to learn whether any user runs a specific program (given the program does not reveal itself by its behaviour), and, as an additional bonus, poorly written programs passing sensitive information via program arguments are now protected against local eavesdroppers.

The {{ic|proc}} [[Users and groups#System groups|group]], provided by the {{Pkg|filesystem}} package, acts as a whitelist of users authorized to learn other users' process information. If users or services need access to {{ic|/proc/<pid>}} directories beyond their own, [[Users and groups#Group management|add them to the group]].

For example, to hide process information from other users except those in the {{ic|proc}} group:

{{hc|/etc/fstab|2=
proc /proc proc nosuid,nodev,noexec,hidepid=2,gid=proc 0 0
}}

For user sessions to work correctly, an exception needs to be added for ''systemd-logind'':

{{hc|/etc/systemd/system/systemd-logind.service.d/hidepid.conf|2=
[Service]
SupplementaryGroups=proc
}}

=== Restricting module loading ===

The default Arch kernel has {{ic|CONFIG_MODULE_SIG_ALL}} enabled, which signs all kernel modules built as part of the {{Pkg|linux}} package. This allows the kernel to only load modules signed with a valid key, i.e. out-of-tree modules compiled locally or provided by packages such as {{Pkg|virtualbox-host-modules-arch}} cannot be loaded. You can use {{ic|1=modinfo}} to verify currently loaded modules have signatures; verifying the signatures by hand is slightly more involved [https://unix.stackexchange.com/a/496800].

Kernel module loading can be restricted by setting the {{ic|1=module.sig_enforce=1}} [[kernel parameter]]. More information can be found in the [https://docs.kernel.org/admin-guide/module-signing.html kernel documentation].

Further, unneeded individual modules can be [[blacklist]]ed, see [https://github.com/secureblue/secureblue/blob/live/files/system/usr/lib/modprobe.d/secureblue.conf secureblue] for examples.

=== Disable kexec ===

Kexec allows replacing the current running kernel.

{{hc|/etc/sysctl.d/51-kexec-restrict.conf|2=
kernel.kexec_load_disabled = 1
}}

{{Tip|kexec is disabled by default in {{pkg|linux-hardened}}.}}

=== Kernel lockdown mode ===

Linux supports an optional [https://mjg59.dreamwidth.org/55105.html lockdown feature], intended to strengthen the boundary between UID 0 (root) and the kernel. When enabled some applications may cease to work which rely on low-level access to either hardware or the kernel.

To use lockdown, its LSM must be initialized and a lockdown mode must be set.

All [[Kernel#Officially supported kernels|officially supported kernels]] initialize the LSM, but none of them enforce any lockdown mode.

{{Tip|Initialized LSMs can be verified by running {{ic|cat /sys/kernel/security/lsm}}.}}

Lockdown has two modes of operation:

* {{ic|integrity}}: kernel features that allow userland to modify the running kernel are disabled (e.g. kexec, bpf).
* {{ic|confidentiality}}: kernel features that allow userland to extract confidential information from the kernel are also disabled.

It is recommended to use {{ic|integrity}}, unless your specific threat model dictates otherwise.

To enable kernel lockdown at runtime, run:

# echo ''mode'' > /sys/kernel/security/lockdown

To enable kernel lockdown on boot, use the [[kernel parameter]] {{ic|1=lockdown=''mode''}}.

{{Note|
* Kernel lockdown cannot be disabled at runtime.
* Kernel lockdown disables [[hibernation]].
* Versions <6.17 of the {{man|7|kernel_lockdown}} man page incorrectly state that "lockdown will be automatically enabled if the system boots in EFI Secure Boot mode". This is not the behaviour of the upstream kernel, nor Arch's packaged [[kernel]]s.
}}

See also {{man|7|kernel_lockdown}}.

=== Linux Kernel Runtime Guard (LKRG) ===

[https://www.openwall.com/lkrg/ LKRG] ({{AUR|lkrg-dkms}}) is a kernel module which performs integrity checking of the kernel and detection of exploit attempts.

=== Disable emergency shell ===

{{Accuracy|Masking {{ic|emergency.target}} and {{ic|emergency.service}} will have no effect on those units being added to the initramfs and run in early userspace. Even with them in the initramfs, mkinitcpio's systemd hook locks the root account[https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/292cdf8a2f7dd7c6c7d91d2b59617391935c837c][https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/8835b2f5dfbe8663f1a2fd08edbd35f90bf08691] for "security reasons" (see {{Bug|70408}}). The solution for the issue in the linked article, if even needed, would be to prevent {{ic|rescue.target}}, {{ic|rescue.service}}, {{ic|emergency.target}} and {{ic|emergency.service}} from being added to the initramfs image.}}

The emergency shell is used to interactively troubleshoot the machine during the boot process. However, it is also a gadget that an attacker can use to access secure resources such as the TPM. See [https://pulsesecurity.co.nz/advisories/tpm-luks-bypass this article] for a practical example. The difficulty of attacks can be increased by disabling the emergency shell, at the tradeoff of removing a tool to troubleshoot early boot failures.

To disable the emergency shell, See [[systemd#Disable emergency mode on remote machine]].

== Sandboxing applications ==

See also [[Wikipedia:Sandbox (computer security)]].

To improve the security of systemd service units, see [[systemd/Sandboxing]].

{{Warning|Unprivileged user namespace usage is enabled by default in all [[Kernel#Officially supported kernels|officially supported kernels]] except for {{Pkg|linux-hardened}}. Unprivileged user namespaces greatly increase the attack surface for local privilege escalation; see [https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction AppArmor's Wiki] and {{Bug|36969}}.}}

To mitigate this, either:

* use the {{Pkg|linux-hardened}} kernel which has the safe default, or
* set the {{ic|kernel.unprivileged_userns_clone}} [[sysctl]] to {{ic|0}}.

Note that this can break applications such as {{pkg|nsjail}}. [[Chromium]] based applications need SUID bit for {{ic|chrome-sandbox}} to work with this setting.

=== Firejail ===

[[Firejail]] is an easy to use tool for sandboxing applications and servers alike. It was originally created for browsers and internet facing applications, but supports a large number of applications by now. To establish a sandboxed environment with a variety of features, it is installed as a suid binary and builds a sandboxed runtime environment for the target application based on black and white lists.

=== bubblewrap ===

[[bubblewrap]] is a sandbox application developed for unprivileged container tools like [[Flatpak]] with a significantly smaller resource footprint and complexity than Firejail. While it lacks certain features such as file path whitelisting, bubblewrap does offer bind mounts as well as the creation of user/IPC/PID/network/cgroup namespaces and can support both simple and complex sandboxes. For the {{Pkg|linux-hardened}} kernel you will need to to use {{Pkg|bubblewrap-suid}}.

[[Bubblejail]] sandbox is based on [[bubblewrap]] and provides a resource oriented permission model with a graphical interface to tweak permissions.

=== Portable ===

[https://github.com/Kraftland/portable Portable] is a sandboxing framework which utilizes [[bubblewrap]] and many other tools to lockdown running applications. It is designed to be simple for packagers and efficient for users, yet cuts off security holes and monitors background processes by default.

See [https://github.com/Kraftland/portable-arch portable-arch] for a repository of applications sandboxed by portable.

If a sandboxed application does not utilize the Portal file chooser, portable can pass files to the sandbox (by passing {{ic|--actions share-files}}).

Portable is fully functional on GNOME, while other desktops may lack small amounts of features like advanced background monitoring and ScreenShot portal.

=== chroots ===

Manual [[chroot]] jails can also be constructed to build sandboxed process environments. It is much more limited than other sandboxing technologies; the extent of its sandboxing is file path isolation.

=== Linux containers ===

[[Linux Containers]] are another good option when you need more separation than the other options (short of [[#Full virtualization options|full system virtualization]]) provide. LXC is run on top of the existing kernel in a pseudo-chroot with their own virtual hardware.

=== gVisor ===

The [https://gvisor.dev/ gVisor] project, led by Google, is providing a sandboxing application with a focus on containers following the [https://opencontainers.org/ OCI initiative], such as [[Docker]] and [[Kubernetes]]. It isolates containers and individual applications from the host by intercepting a majority of system calls to the kernel and presenting itself as guest kernel.

A key difference to other intercepting sandboxing projects is that gVisor re-implements system calls in the Go programming language, as described in its [https://gvisor.dev/docs/architecture_guide/intro/ design overview]. Details for the list of [https://gvisor.dev/docs/user_guide/compatibility/linux/amd64/ re-implemented syscalls support] can be seen in [https://github.com/google/gvisor/blob/master/pkg/sentry/syscalls/linux/linux64.go git]. For usage examples, limitations and special features see the project [https://gvisor.dev/docs/ documentation].

The application is available as {{Aur|gvisor-git}} and {{Aur|gvisor-bin}}.

=== Full virtualization options ===

Using full virtualization options such as [[VirtualBox]], [[KVM]], [[Xen]] or [https://www.qubes-os.org/ Qubes OS] (based on Xen) can also improve isolation and security in the event you plan on running risky applications or browsing dangerous websites.

== Network and firewalls ==

=== Firewalls ===

While the stock Arch kernel is capable of using [[Wikipedia:Netfilter|Netfilter]]'s [[iptables]] and [[nftables]], the services are not [[enable]]d by default. It is highly recommended to set up some form of firewall to protect the services running on the system. Many resources (including ArchWiki) do not state explicitly which services are worth protecting, so enabling a firewall is a good precaution.

* See [[iptables]] and [[nftables]] for general information.
* See [[Simple stateful firewall]] for a guide on setting up an iptables firewall.
* See [[:Category:Firewalls]] for other ways of setting up netfilter.
* See [[Ipset]] for blocking lists of ip addresses, such as those from Bluetack.
* {{Pkg|opensnitch}} is a configurable inbound and outbound firewall with support for configurable rules by application, port, host, etc.

A quick way to setup a basic firewall is to use the tool {{ic|ufw}} (Uncomplicated Fire Wall). Then set {{ic|ufw default deny incoming}} and {{ic|ufw default allow outgoing}} and enabling it with {{ic|ufw enable}} and {{ic|systemctl enable ufw}}.

==== Open ports ====

{{Style|"Open ports" is not a good title since it disregards interfaces and addresses that the application may be bound to. From the firewalls' point of view, ports may be "open" even if no application listens on them at the moment.}}

Some services listen for inbound traffic on open network ports. It is important to only bind these services to the addresses and interfaces that are strictly necessary. It may be possible for a remote attacker to [https://samy.pl/slipstream/ exploit flawed network protocols to access exposed services]. This can even happen with [https://nvd.nist.gov/vuln/detail/CVE-2019-13450 processes bound to localhost].

In general, if a service only needs to be accessible to the local system, bind to a Unix domain socket ({{man|7|unix}}) or a loopback address such as {{ic|localhost}} instead of a non-loopback address like {{ic|0.0.0.0/0}}.

If a service needs to be accessible to other systems via the network, control the access with strict [[firewall]] rules and configure authentication, authorization and encryption whenever possible.

You can list all current open ports with {{ic|ss -l}}. To show all '''l'''istening '''p'''rocesses and their '''n'''umeric '''t'''cp and '''u'''dp port numbers:

# ss -lpntu

See {{man|8|ss}} for more options.

=== Kernel parameters ===

Kernel parameters which affect networking can be set using [[Sysctl]]. For how to do this, see [[Sysctl#TCP/IP stack hardening]].

=== SSH ===

To mitigate [[Wikipedia:Brute-force attack|brute-force attacks]] it is recommended to enforce key-based authentication. For OpenSSH see [[OpenSSH#Protection]] for more recommendations. Alternatively [[Fail2ban]] or [[Sshguard]] offer lesser forms of protection by monitoring logs and writing [[firewall]] rules but open up the potential for a denial of service, since an attacker can [[Wikipedia:Spoofing attack#Spoofing and TCP/IP|spoof]] packets as if they came from the administrator after identifying their address. Spoofing IP has lines of defense, such as by [[sysctl#Reverse path filtering|reverse path filtering]] and [[sysctl#Disable ICMP redirects|disabling ICMP redirects]].

You may want to harden authentication even more by using two-factor authentication. [[Google Authenticator]] provides a two-step authentication procedure using one-time passcodes (OTP).

Denying root login is also a good practice, both for tracing intrusions and adding an additional layer of security before root access. For OpenSSH, see [[OpenSSH#Deny]].

Mozilla publishes an [https://infosec.mozilla.org/guidelines/openssh.html OpenSSH configuration guide] which configures more verbose audit logging and restricts ciphers.

=== DNS ===

The default domain name resolution (DNS) configuration is highly compatible but has security weaknesses. See [[Domain name resolution#Privacy and security|DNS privacy and security]] for more information.

=== Proxies ===

Proxies are commonly used as an extra layer between applications and the network, sanitizing data from untrusted sources. The attack surface of a small proxy running with lower privileges is significantly smaller than a complex application running with the end user privileges.

For example the DNS resolver is implemented in {{Pkg|glibc}}, that is linked with the application (that may be running as root), so a bug in the DNS resolver might lead to a remote code execution. This can be prevented by installing a DNS caching server, such as [[dnsmasq]], which acts as a proxy. [https://googleonlinesecurity.blogspot.it/2016/02/cve-2015-7547-glibc-getaddrinfo-stack.html]

=== Managing TLS certificates ===

See [[TLS#Trust management]].

== Physical security ==

Physical access to a computer is root access given enough time and resources. However, a high ''practical'' level of security can be obtained by putting up enough barriers.

An attacker can gain full control of your computer on the next boot by simply attaching a malicious IEEE 1394 (FireWire), Thunderbolt or PCI Express device as they are given full memory access by default.[https://web.archive.org/web/20210312083421/http://breaknenter.org/2014/09/inception-metasploit-integration/] For Thunderbolt, you can restrict the direct memory access completely or to known devices, see [[Thunderbolt#User device authorization|user device authorization]]. For Firewire and PCI Express, there is little you can do from preventing this, or modification of the hardware itself - such as flashing malicious firmware onto a drive. However, the vast majority of attackers will not be this knowledgeable and determined.

[[#Data-at-rest encryption|Data-at-rest encryption]] will prevent access to your data if the computer is stolen, but malicious firmware can be installed to obtain this data upon your next log in by a resourceful attacker.

=== Locking down BIOS ===

Adding a password to the BIOS prevents someone from booting into removable media, which is basically the same as having root access to your computer. You should make sure your drive is first in the boot order and disable the other drives from being bootable if you can.

=== Boot loaders ===

It is highly important to protect your [[boot loader]]. An unprotected boot loader can bypass any login restrictions, e.g. by setting the {{ic|1=init=/bin/sh}} [[kernel parameter]] to boot directly to a shell.

==== Syslinux ====

[[Syslinux]] supports [[Syslinux#Security|password-protecting your boot loader]]. It allows you to set either a per-menu-item password or a global boot loader password.

==== GRUB ====

[[GRUB]] supports boot loader passwords as well. See [[GRUB/Tips and tricks#Password protection of GRUB menu]] for details. It also has support for [[GRUB#Encrypted /boot|encrypted /boot]], which only leaves some parts of the boot loader code unencrypted. GRUB's configuration, [[kernel]] and [[initramfs]] are encrypted.

==== systemd-boot ====

[[systemd-boot]] disables editing of kernel parameters when [[#Secure Boot|Secure Boot]] is enabled. Alternatively, you can set [[systemd-boot#Kernel parameters editor with password protection|kernel parameters for password protection]] in systemd-boot for a more traditional password-based option.

=== Secure Boot ===

[[Secure Boot]] is a feature of [[UEFI]] that allows authentication of the files your computer boots. This helps preventing some [[Wikipedia:Evil maid attack|evil maid attacks]] such as replacing files inside the boot partition. Normally computers come with keys that are enrolled by vendors (OEM). However these can be removed and allow the computer to enter ''Setup Mode'' which allows the user to enroll and manage their own keys.

The secure boot page guides you through how to set secure boot up by [[Unified Extensible Firmware Interface/Secure Boot#Using your own keys|using your own keys]].

=== Trusted Platform Module (TPM) ===

[[Trusted Platform Module|TPMs]] are hardware microprocessors which have cryptographic keys embedded. This forms the fundamental root of trust of most modern computers and allows end-to-end verification of the boot chain. They can be used as internal smartcards, attest the firmware running on the computer and allow users to insert secrets into a tamper-proof and brute-force resistant store.

=== Boot partition on removable flash drive ===

One popular idea is to place the boot partition on a flash drive in order to render the system unbootable without it. Proponents of this idea often use [[#Data-at-rest encryption|full-disk encryption]] alongside, and some also use [[Dm-crypt/Specialties#Encrypted system using a detached LUKS header|detached encryption headers]] placed on the boot partition.

This method can also be merged with [[Dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB|encrypting /boot]].

=== Automatic logout ===

If you are using [[Bash]] or [[Zsh]], you can set {{ic|TMOUT}} for an automatic logout from shells after a timeout.

For example, the following will automatically log out from virtual consoles (but not terminal emulators in X11):

{{hc|/etc/profile.d/shell-timeout.sh|<nowiki>
TMOUT="$(( 60*10 ))";
[ -z "$DISPLAY" ] && export TMOUT;
case $( /usr/bin/tty ) in
/dev/tty[0-9]*) export TMOUT;;
esac
</nowiki>}}

If you really want EVERY Bash/Zsh prompt (even within X) to timeout, use:

$ export TMOUT="$(( 60*10 ))";

Note that this will not work if there is some command running in the shell (eg.: an SSH session or other shell without {{ic|TMOUT}} support). But if you are using VC mostly for restarting frozen GDM/Xorg as root, then this is very useful.

=== Protect against rogue USB devices ===

The kernel has [https://docs.kernel.org/usb/authorization.html settings to deactivate] USB ports to protect your computer against rogue USB devices (a.k.a. [[Wikipedia:BadUSB|BadUSB]], [https://github.com/samyk/poisontap PoisonTap] or [https://lanturtle.com/ LanTurtle]). They can be set at runtime and automated via [[sysctl]].

For more control install [[USBGuard]], which is a software framework implementing basic whitelisting and blacklisting capabilities based on device attributes.

=== Volatile data collection ===

A computer that is powered on may be vulnerable to [https://web.archive.org/web/20210420075636/https://fedvte.usalearning.gov/courses/CSI/course/videos/pdf/CSI_D01_S05_T01_STEP.pdf volatile data collection]. It is a best practice to turn a computer completely off at times it is not necessary for it to be on, or if the computer's physical security is temporarily compromised (e.g. when passing through a security checkpoint).

== Packages ==

=== Authentication ===

[https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html#overview Attacks on package managers] are possible without proper use of package signing, and can affect even package managers with [https://www2.cs.arizona.edu/stork/packagemanagersecurity/faq.html proper signature systems]. Arch uses package signing by default and relies on a web of trust from 5 trusted master keys. See [[Pacman-key]] for details.

=== Upgrades ===

It is important to regularly [[System maintenance#Upgrading the system|upgrade the system]].

=== Follow vulnerability alerts ===

Subscribe to the Common Vulnerabilities and Exposure (CVE) Security Alert updates, made available by National Vulnerability Database, and found on the [https://nvd.nist.gov/download.cfm NVD Download webpage].

The tool {{Pkg|arch-audit}} can be used to check for vulnerabilities affecting the running system. A graphical system tray, {{Pkg|arch-audit-gtk}}, can also be used. See also [[Arch Security Team]].

You should also consider subscribing to the release notifications for software you use, especially if you install software through means other than the main repositories or AUR. Some software have mailing lists you can subscribe to for security notifications. Source code hosting sites often offer RSS feeds for new releases.

=== Rebuilding packages ===

Packages can be rebuilt and stripped of undesired functions and features as a means to reduce attack surface. For example, {{Pkg|bzip2}} can be rebuilt without {{ic|bzip2recover}} in an attempt to circumvent [https://security.archlinux.org/CVE-2016-3189 CVE-2016-3189]. Custom hardening flags can also be applied either manually or via a wrapper.

{{Merge|Arch package guidelines/Security|Security related build flags have their own article.}}

{{Accuracy|Copy-pasted from a 3 years old blog post. The compiler flags are specific to [[GCC]], some are hardly security related.}}

{| class="wikitable"
! Flag !! Purpose
|-
| -D_FORTIFY_SOURCE=2 || Run-time buffer overflow detection
|-
| -D_GLIBCXX_ASSERTIONS || Run-time bounds checking for C++ strings and containers
|-
| -fasynchronous-unwind-tables || Increased reliability of backtraces
|-
| -fexceptions || Enable table-based thread cancellation
|-
| -fpie -Wl,-pie || Full ASLR for executables
|-
| -fpic -shared || No text relocations for shared libraries
|-
| -fplugin=annobin || Generate data for hardening quality control
|-
| -fstack-clash-protection || Increased reliability of stack overflow detection
|-
| -fstack-protector, -fstack-protector-all or -fstack-protector-strong || Stack smashing protector
|-
| -grecord-gcc-switches || Store compiler flags in debugging information
|-
| -mcet -fcf-protection || Control flow integrity protection
|-
| -Werror=format-security || Reject potentially unsafe format string arguments
|-
| -Werror=implicit-function-declaration || Reject missing function prototypes
|-
| -Wl,-z,defs || Detect and reject underlinking
|-
| -Wl,-z,now || Disable lazy binding
|-
| -Wl,-z,relro || Read-only segments after relocation
|}

* [https://developers.redhat.com/blog/2018/03/21/compiler-and-linker-flags-gcc/ Flags and info source]

== See also ==

* [https://security.archlinux.org/ Arch Linux Security Tracker]
* [https://wiki.centos.org/HowTos/OS_Protection CentOS Wiki: OS Protection]
* [https://web.archive.org/web/20210712001756/https://developer.ibm.com/technologies/linux/articles/l-harden-desktop/ Hardening the Linux desktop]
* [https://web.archive.org/web/20190701140035/https://www.ibm.com/developerworks/linux/tutorials/l-harden-server/index.html Hardening the Linux server]
* [https://github.com/lfit/itpol/blob/master/linux-workstation-security.md Linux Foundation: Linux workstation security checklist]
* [https://www.privacyguides.org/ privacyguides.org Privacy Resources]
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/ Red Hat Enterprise Linux 7 Security Guide]
* [https://www.debian.org/doc/manuals/securing-debian-manual/index.en.html Securing Debian Manual]
* [https://web.archive.org/web/20140220055801/http://crunchbang.org:80/forums/viewtopic.php?id=24722 The paranoid #! Security Guide]

Security

2026-05-11T19:15:33Z

Indigo: /* Enforcing strong passwords with pam_pwquality */ add subsection with expansion template regarding pam_unix nullok usage

[[Category:Security]]
[[Category:File systems]]
[[Category:Networking]]
[[de:Sicherheit]]
[[es:Security]]
[[hu:Security]]
[[ja:セキュリティ]]
[[pt:Security]]
[[ru:Security]]
[[zh-hans:Security]]
{{Related articles start}}
{{Related|Arch Security Team}}
{{Related|General recommendations}}
{{Related|Identity management}}
{{Related|Capabilities}}
{{Related|List of Applications/Security}}
{{Related|Arch package guidelines/Security}}
{{Related articles end}}
This article contains recommendations and best practices for [[Wikipedia:Hardening (computing)|hardening]] an Arch Linux system.

== Concepts ==

* It ''is'' possible to tighten security to the point where the system is unusable. Security and convenience must be balanced. The trick is to create a secure ''and'' useful system.
* The biggest threat is, and will always be, the user.
* The [[Wikipedia:Principle of least privilege|principle of least privilege]]: Each part of a system should only be able to access what is strictly required, and nothing more.
* Defense in depth: Security works better in independent layers. When one layer is breached, another should stop the attack.
* Be a little paranoid. And be suspicious. If anything sounds too good to be true, it probably is!
* You can never make a system 100% secure unless you unplug the machine from all networks, turn it off, lock it in a safe, smother it in concrete and never use it.
* Prepare for failure. Create a plan ahead of time to follow when your security is broken.

== Passwords ==

Passwords are key to a secure system. They secure your [[Users and groups|user accounts]], [[Data-at-rest encryption|encrypted filesystems]], and [[SSH keys|SSH]]/[[GPG]] keys. They are the main way a computer chooses to trust the person using it, so a big part of security is just about picking secure passwords and protecting them.

=== Choosing secure passwords ===

Passwords must be complex enough to not be easily guessed from e.g. personal information, or [[Wikipedia:Password cracking|cracked]] using methods like brute-force attacks. The tenets of strong passwords are based on ''length'' and ''randomness''. In cryptography the quality of a password is often referred to as its [[Wikipedia:Password strength#Entropy as a measure of password strength|entropy]].

Insecure passwords include those containing or those using as a base before substitution/variation:

* Personally identifiable information (e.g., your dog's name, date of birth, area code, favorite video game)
* Simple character substitutions on words (e.g., {{ic|k1araj0hns0n}}), as modern dictionary attacks can easily work with these
* Root "words" or common strings followed or preceded by added numbers, symbols, or characters (e.g., {{ic|DG091101%}})
* Common phrases or short strings of common dictionary words (e.g. {{ic|photocopyhauntbranchexpose}}) including with character substitution (e.g. {{ic|Ph0toc0pyh4uN7br@nch3xp*se}}) (See Diceware below for when a combination of dictionary words can be secure)
* Any of the [[Wikipedia:List of the most common passwords|most common passwords]]

The best choice for a password is something long (the longer, the better) and generated from a random source. It is important to use a long password. [https://www.theregister.com/2019/02/14/password_length Weak hash algorithms allow an 8-character password hash to be compromised in just a few hours.]

Tools like {{Pkg|pwgen}} or {{AUR|apg}} can generate random passwords. However, these passwords can be difficult to memorize. One memorization technique (for ones often typed) is to generate a long password and memorize a minimally secure number of characters, temporarily writing down the full generated string. Over time, increase the number of characters typed - until the password is ingrained in muscle memory and need not be remembered. This technique is more difficult, but can provide confidence that a password will not turn up in wordlists or "intelligent" brute force attacks that combine words and substitute characters.

Apart from password management, {{Pkg|keepassxc}} offers password/passphrase generation. It is possible to customize the generation in a GUI. Dictionary based passphrases are also supported.

One technique for memorizing a password is to use a mnemonic phrase, where each word in the phrase reminds you of the next character in the password.
Take for instance “the girl is walking down the rainy street” could be translated to {{ic|t6!WdtR5}} or, less simply, {{ic|t&6!RrlW@dtR,57}}.
This approach could make it easier to remember a password, but note that the various letters have very different probabilities of being found at the start of words ([[Wikipedia:Letter frequency#Relative frequencies of the first letters of a word in the English language|Wikipedia:Letter frequency]]).

Another effective technique can be to write randomly generated passwords down and store them in a ''safe'' place, such as in a wallet, purse, or document safe. Most people do a generally good job of protecting their physical valuables from attack, and it is easier for most people to understand physical security best practices compared to digital security practices.

It is also very effective to combine the mnemonic and random technique by saving long randomly generated passwords with a [[password manager]], which will be in turn accessed with a memorable "master password"/primary password that must be used only for that purpose. The master password must be memorized and never saved. This requires the password manager to be installed on a system to easily access the password (which could be seen as an inconvenience or a security feature, depending on the situation). Some password managers also have smartphone apps which can be used to display passwords for manual entry on systems without that password manager installed (if that is a common use case, you could still use easily typeable but secure passwords for each service instead of completely random ones, see below). Note that a password manager introduces a single point of failure if you ever forget the master password.
Some password managers compute the contained passwords based on the master password and the service name where you want to log in instead of encrypting them, making it possible to use it on a new system without syncing any data.

It can be effective to use a memorable long series of unrelated words as a password. The theory is that if a sufficiently long phrase is used, the gained entropy from the password's length can counter the lost entropy from the use of dictionary words. This [https://xkcd.com/936/ xkcd comic] demonstrates the entropy tradeoff of this method, taking into account the limited set of possible words for each word in the passphrase. If the set of words you choose from is large (multiple thousand words) and you choose 5-7 or even more random words from it, this method provides great entropy, even assuming the attacker knows the set of possible words chosen from and the number of words chosen. The number of possible passphrases after settling on a set of words and number of words is: (number of words in the set of words to select from) to the power of (the number of words chosen for the passphrase). See e.g. [https://www.rempe.us/diceware/ Diceware] for more.

See [https://www.iusmentis.com/security/passphrasefaq/ The passphrase FAQ] or [[Wikipedia:Password strength]] for some additional background.

=== Maintaining passwords ===

Once you pick a strong password, be sure to keep it safe. Watch out for [[Wikipedia:Keylogger|keyloggers]] (software and hardware), screen loggers, [[Wikipedia:Social engineering (security)|social engineering]], [[Wikipedia:Shoulder surfing (computer security)|shoulder surfing]], and avoid reusing passwords so insecure servers cannot leak more information than necessary. [[List of applications/Security#Password managers|Password managers]] can help manage large numbers of complex passwords: if you are copy-pasting the stored passwords from the manager to the applications that need them, make sure to clear the copy buffer every time, and ensure they are not saved in any kind of log (e.g. do not paste them in plain terminal commands, which would store them in files like {{ic|.bash_history}}). Note that password managers that are implemented as browser extensions may be vulnerable to [https://www.spookjs.com side channel attacks]. These can be mitigated by using password managers that run as separate applications.

As a rule, do not pick insecure passwords just because secure ones are harder to remember. Passwords are a balancing act. It is better to have an encrypted database of secure passwords, guarded behind a key and one strong master password, than it is to have many similar weak passwords. Writing passwords down is perhaps equally effective [https://www.schneier.com/blog/archives/2005/06/write_down_your.html], avoiding potential vulnerabilities in software solutions while requiring physical security.

Another aspect of the strength of the passphrase is that it must not be easily recoverable from other places.

If you use the same passphrase for disk encryption as you use for your login password (useful e.g. to auto-mount the encrypted partition or folder on login), make sure that {{ic|/etc/shadow}} ends up on an encrypted partition or/and uses a strong key derivation function (i.e. yescrypt/argon2 or sha512 with PBKDF2, but not md5 or low iterations in PBKDF2) for the stored password hash (see [[SHA password hashes]] for more information).

{{Tip|In 2023 Arch Linux switched the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default hashing] algorithm to yescrypt. If you have not customized the default, executing a password change with {{ic|passwd}} is necessary (and sufficient) to apply the new default.}}

If you are backing up your password database, make sure that each copy is not stored behind any other passphrase which in turn is stored in it, e.g. an encrypted drive or an authenticated remote storage service, or you will not be able to access it in case of need; a useful trick is to protect the drives or accounts where the database is backed up using a simple cryptographic hash of the master password. Maintain a list of all the backup locations: if one day you fear that the master passphrase has been compromised you will have to change it immediately on all the database backups and the locations protected with keys derived from the master password.

Version-controlling the database in a secure way can be very complicated: if you choose to do it, you must have a way to update the master password of all the database versions. It may not always be immediately clear when the master password is leaked: to reduce the risk of somebody else discovering your password before you realize that it leaked, you may choose to change it on a periodical basis. If you fear that you have lost control over a copy of the database, you will need to change all the passwords contained in it within the time that it may take to brute-force the master password, according to its entropy.

=== Password hashes ===

A hash is a one-way function, i.e. it is designed to make it impossible to deduct the input without computing the hash function with it (example: MD5, SHA).

A password-hash function is designed to make deducting a user-input (password) impossible without computing the hash function with it (example: bcrypt). A [[Wikipedia:Key derivation function|key derivation function]] (KDF; examples: yescrypt, scrypt, PBKDF2) is a cryptographic algorithm designed to derive secret keys (e.g. an AES key, a password hash) from an input (a master key, a password). Hence, a KDF can serve multiple applications, including those of a password-hash function.

By default, Arch stores the hashed user passwords in the root-only-readable {{ic|/etc/shadow}} file, separated from the other user parameters stored in the world-readable {{ic|/etc/passwd}} file, see [[Users and groups#User database]]. See also [[#Restricting root]].

Passwords are set with the '''passwd''' command, which [[Wikipedia:Key stretching|stretches]] them with the system's crypt function and then saves them in {{ic|/etc/shadow}}. The passwords are also [[Wikipedia:Salt (cryptography)|salted]] in order to defend them against [[Wikipedia:Rainbow table|rainbow table]] attacks. See also [https://www.slashroot.in/how-are-passwords-stored-linux-understanding-hashing-shadow-utils How are passwords stored in Linux (Understanding hashing with shadow utils)].

Since password hashes follow a defined format, the method and parameter can be configured for subsequent new invocations of the ''passwd'' command. Hence, the individual hashes stored in the {{ic|/etc/shadow}} file can be a heterogeneous mix of the hash functions supported by the system.

See {{man|5|crypt}} for more information on the format, hashing methods and parameters.

The {{ic|/etc/login.defs}} file configures the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default password hashing] method {{ic|ENCRYPT_METHOD YESCRYPT}} and its parameter {{ic|YESCRYPT_COST_FACTOR}}.

For example, an increment of the default {{ic|YESCRYPT_COST_FACTOR}} parameter will lead to a logarithmic increase of the compute time required to deduce the hash from a password. This applies, likewise, to a third-party trying to obtain the password secret, and the system to authenticate a user log-in.

In contrast, the compute time for the SHA-512 hash function is configured by a parameter with a linear influence. See [[SHA password hashes]] for information on the previous Arch default. Note the yescrypt algorithm internally uses SHA-256, HMAC and PBKDF2 to compute its password-hash. The main reason is to combine positive attributes of these widely used and tested functions for an enhanced resistance to attacks. For example, the usability of SHA for various purposes has resulted in hardware support for the function, i.e. the performance to compute a pure SHA hash has accelerated considerably, making its application as a password-hash function more and more derelict.

=== Disallow empty password ===

{{Expansion|The [https://github.com/V4bel/dirtyfrag dirtyfrag] kernel vulnerabilities mwnipulated {{ic|/etc/shadow}} and relied on the regularly used {{ic|pam_unis}} option {{ic|nullok}} in {{ic|/etc/pam.d/system-auth}}. Removing this default, thereby disallowing empty passwords, can be an option to increase security. Instructions should be accompanied by commands how to check for user accounts with unset passwords first.}}

=== Enforcing strong passwords with pam_pwquality ===

PAM stands for the Pluggable Authentication Modules. ''pam_pwquality'' provides protection against [[Wikipedia:Dictionary attack|Dictionary attacks]] and helps configure a password policy that can be enforced throughout the system. It is based on ''pam_cracklib'', so it is backwards compatible with its options.

[[Install]] the {{Pkg|libpwquality}} package.

{{Warning|The ''root'' account is not affected by this policy by default.}}

{{Note|
* You can use the ''root'' account to set a password for a user that bypasses the desired/configured policy. This is useful when setting temporary passwords.
* Current security guidelines around passwords, e.g. from NIST, but also from others, do not recommend enforcing special characters, since they often only lead to predictable alterations.
}}

If for example you want to enforce this policy:

* prompt 2 times for password in case of an error (retry option)
* 10 characters minimum length (minlen option)
* at least 6 characters should be different from old password when entering a new one (difok option)
* at least 1 digit (dcredit option)
* at least 1 uppercase (ucredit option)
* at least 1 lowercase (lcredit option)
* at least 1 other character (ocredit option)
* cannot contain the words "myservice" and "mydomain"
* enforce the policy for root

Edit the {{ic|/etc/pam.d/passwd}} file to read as:

{{bc|1=
#%PAM-1.0
password required pam_pwquality.so retry=2 minlen=10 difok=6 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=-1 [badwords=myservice mydomain] enforce_for_root
password required pam_unix.so use_authtok yescrypt shadow
}}

The {{ic|password required pam_unix.so use_authtok}} instructs the ''pam_unix'' module to not prompt for a password but rather to use the one provided by ''pam_pwquality''.

You can refer to the {{man|8|pam_pwquality}} and {{man|8|pam_unix}} man pages for more information.

== CPU ==

=== Microcode ===

See [[microcode]] for information on how to install important security updates for your CPU's microcode.

=== Hardware vulnerabilities ===

Some CPUs contain hardware vulnerabilities. See the [https://docs.kernel.org/admin-guide/hw-vuln/ kernel documentation on hardware vulnerabilities] for a list of these vulnerabilities, as well as mitigation selection guides to help customize the kernel to mitigate these vulnerabilities for specific usage scenarios.

To check if you are affected by a known vulnerability, run the following:

$ grep -r . /sys/devices/system/cpu/vulnerabilities/

In most cases, updating the kernel and microcode will mitigate vulnerabilities.

==== Simultaneous multithreading (hyper-threading) ====

[[Wikipedia:Simultaneous multithreading|Simultaneous multithreading]] (SMT), also called hyper-threading on Intel CPUs, is a hardware feature that may be a source of [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html L1 Terminal Fault] and [https://docs.kernel.org/admin-guide/hw-vuln/mds.html Microarchitectural Data Sampling] vulnerabilities. The Linux kernel and microcode updates contain mitigations for known vulnerabilities, but [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html#virtualization-with-untrusted-guests disabling SMT may still be required on certain CPUs if untrusted virtualization guests are present].

{{Note|Disabling SMT is something mostly hypervisors benefit from.[https://security.stackexchange.com/questions/219753/sacrificing-30-of-my-cpu-performance-by-disabling-hyper-threading-to-fully-mi/219759#219759] On an ordinary system it has very little to no security benefits.}}

SMT can often be disabled in your system's firmware. Consult your motherboard or system documentation for more information. You can also disable SMT in the kernel by adding the following [[kernel parameter]]:

mitigations=auto,nosmt

== Memory ==

=== Hardened malloc ===

{{AUR|hardened_malloc}} is a hardened replacement for [[Wikipedia:GNU C Library|glibc]]'s malloc(). The project was originally developed for integration into Android's [[Wikipedia:Bionic (software)|Bionic]] and [[Wikipedia:musl|musl]] by Daniel Micay, of [[Wikipedia:GrapheneOS|GrapheneOS]], but he has also built in support for standard Linux distributions on the x86_64 architecture.

== Storage ==

=== Data-at-rest encryption ===

[[Data-at-rest encryption]], preferably full-disk encryption with a [[#Passwords|strong passphrase]], is the only way to guard data against physical recovery. This provides data confidentiality when the computer is turned off or the disks in question are unmounted.

Once the computer is powered on and the drive is mounted, however, its data becomes just as vulnerable as an unencrypted drive. It is therefore best practice to unmount data partitions as soon as they are no longer needed.

You may also [[Trusted Platform Module#LUKS encryption|encrypt a drive with the key stored in a TPM]], although it has had [https://tpm.fail vulnerabilites in the past] and the key can be extracted by a [https://pulsesecurity.co.nz/articles/TPM-sniffing bus sniffing attack].

Certain programs, like [[dm-crypt]], allow the user to encrypt a loop file as a virtual volume. This is a reasonable alternative to full-disk encryption when only certain parts of the system need to be secure.

While the block-device or filesystem-based encryption types compared in the [[data-at-rest encryption]] article are useful at protecting data on physical media, most can not be used to protect data on a remote system that you can not control (such as [[Data-at-rest encryption#Cloud-storage optimized|cloud storage]]). In some cases, individual file encryption will be useful.

These are some methods to encrypt files:

* Some [[Archiving and compression|archiving and compressing]] tools also provide basic encryption. Some examples are [[7-Zip]] ({{ic|-p}} flag), {{Pkg|zip}} ({{ic|-e}} flag). The encryption should only be relied on particular care, because the tools may use custom algorithms for cross-platform compatibility.[https://math.ucr.edu/~mike/zipattacks.pdf]
* [[GnuPG]] can be used to [[GnuPG#Encrypt and decrypt|encrypt files]].
* {{Pkg|age}} is a simple and easy to use file encryption tool. It also supports multiple recipients and encryption using SSH keys, which is useful for secure file sharing.

=== File systems ===

The kernel now prevents security issues related to hardlinks and symlinks if the {{ic|fs.protected_hardlinks}} and {{ic|fs.protected_symlinks}} sysctl switches are enabled, so there is no longer a major security benefit from separating out world-writable directories.

File systems containing world-writable directories can still be kept separate as a coarse way of limiting the damage from disk space exhaustion. However, filling {{ic|/var}} or {{ic|/tmp}} is enough to take down services. More flexible mechanisms for dealing with this concern exist (like [[Disk quota|quotas]]), and some [[file systems]] include related features themselves (Btrfs has quotas on subvolumes).

==== Mount options ====

Following the principle of least privilege, file systems should be mounted with the most restrictive mount options possible (without losing functionality).

Relevant mount options are:

* {{ic|nodev}}: Do not interpret character or block special devices on the file system.
* {{ic|nosuid}}: Do not allow set-user-identifier or set-group-identifier bits to take effect.
* {{ic|noexec}}: Do not allow direct execution of any binaries on the mounted file system.
** Setting {{ic|noexec}} on {{ic|/home}} disallows executable scripts and breaks [[Wine]], [[Steam]], PyCharm, [[.NET]], etc.
*** Wine does not need the {{ic|exec}} flag for opening Windows binaries. It is only needed when Wine itself is installed in {{ic|/home}}.
*** To keep [[Steam]] working you can mount {{ic|/home/user/.local/share/Steam}} as {{ic|exec}} in [[fstab]] by adding the following: {{bc|/home/user/.local/share/Steam /home/user/.local/share/Steam none defaults,bind,user,exec,nofail 0 0}}
** Some packages (building {{Pkg|nvidia-open-dkms}} for example) may require {{ic|exec}} on {{ic|/var}}.

File systems used for data should always be mounted with {{ic|nodev}}, {{ic|nosuid}} and {{ic|noexec}}.

Potential file system mounts to consider:

* {{ic|/var}}
* {{ic|/home}}
* {{ic|/dev/shm}}
* {{ic|/tmp}}
* {{ic|/boot}}

{{Tip|When using [[systemd#GPT partition automounting|GPT partition automounting]], the ESP and XBOOTLDR partitions are [https://github.com/systemd/systemd-stable/commit/49804cfb71d3a79f433096e4cfb5616980171336 always hardened] with {{ic|noexec,nosuid,nodev}}.}}

==== Snapshots ====

When utilizing file system snapshots, e.g. with [[Btrfs]], [[LVM]], or [[ZFS]], it is essential to be aware that snapshots may retain sensitive information that users expect to be deleted. This is especially true when automatic snapshotting tools like [[Snapper]] are configured, as they can capture snapshots at regular intervals or in response to system events. Here are some examples of how sensitive information in {{ic|/home/}} can persist within snapshots:

* ''Deleted files and directories'': Even though files or directories are deleted from the file system, they may still exist within older snapshots. This is expected most of the time, but consider whether files and directories such as {{ic|.local/share/Trash/}}, {{ic|.history}}, etc. should be retained.
* ''Temporary files and cache'': Temporary files and cached data generated by applications may be included in snapshots. For example, files kept in encrypted directories might generate thumbnails ({{ic|.cache/thumbnails}}) or work copies when opened, which might in turn be included in snapshots. The same applies e.g. to browsing history ({{ic|.mozilla/}}, {{ic|.config/chromium/}}, etc.), which could have been included in a snapshot before being purged.

If this is supported, consider excluding such directories from snapshots altogether. For example, if using [[Btrfs]], you can create subvolumes for example {{ic|.cache/}}, {{ic|.config/}}, {{ic|.local/}}, {{ic|.var/}} or any other directory according to your use-case.

{{Note|Moving {{ic|.local/share/Trash}} to a separate subvolume might break the trash feature in some cases, e.g. with [[GNOME/Files]].}}

=== File access permissions ===

{{Accuracy|{{ic|chmod go-r}} does not "take away all permissions", it only removes the read permission.}}

The default [[file permissions]] allow read access to almost everything and changing the permissions can hide valuable information from an attacker who gains access to a non-root account such as the {{ic|http}} or {{ic|nobody}} users. You can use [[chmod]] to take away all permissions from the group and others:

# chmod go-r ''path_to_hide''

{{Warning|Do not apply this broadly. Try this for one config at a time, ensuring that it is worth hiding, and that it will not break program functionality. You may need to remove the {{ic|g}} from the command (or re-add the permission with {{ic|chmod g+r ''path''}} if already ran) if the group is relied on.}}

Some paths to consider are:

* {{ic|/boot}}: The [[Partitioning#/boot|boot directory]], which may include traditional [[vmlinuz]] and [[initramfs]] images, or a [[Unified kernel image]]. Note that safe permissions are used by default when using [[systemd#GPT partition automounting]].
* {{ic|/etc/nftables.conf}}: The [[nftables]] configuration, applicable to {{Pkg|nftables}} and {{Pkg|iptables}}.
* {{ic|/etc/iptables}}: The legacy [[iptables]] configuration, applicable to {{Pkg|iptables-legacy}}.

The default [[umask]] {{ic|0022}} can be changed to improve security for newly created files. The [https://apps.nsa.gov/iaarchive/library/ia-guidance/security-configuration/operating-systems/guide-to-the-secure-configuration-of-red-hat-enterprise.cfm NSA RHEL5 Security Guide] suggests a umask of {{ic|0077}} for maximum security, which makes new files not readable by users other than the owner. To change this, see [[Umask#Set the mask value]]. If you use [[sudo]], consider configuring it to use the [[Sudo#Permissive umask|default root umask]].

=== SUID and SGID files ===

It is important to be aware of any files with the [[Wikipedia:Setuid|Setuid]] or Setgid bit. Examples of relevant files with the SUID bit set:

* [[PAM|unix_chkpwd]]
* chage, expiry, gpasswd, groupmems, [[passwd]], sg ({{Pkg|shadow}})
* [[FUSE|fusermount3]], fusermount2
* [[polkit|pkexec]]
* [[OpenSSH|ssh-keysign]]
* chfn, chsh, mount, newgrp, umount, wall, write ({{Pkg|util-linux}})
* [[sudo]], {{Pkg|sudo-rs}}, [[doas]], [[su]], su-rs, [[Kerberos|ksu]]
* [[firejail]]
* [[Dbus|dbus-daemon-launch-helper]]
* [[Chromium|chromium-sandbox]]
* [[Xorg|Xorg.wrap]]

The prominent risks of such executable files include privilege escalation vulnerabilities, see e.g [[Wikipedia:Setuid#Security impact]].[https://www.cvedetails.com/vulnerability-list/vendor_id-16224/product_id-36412/Calibre-ebook-Calibre.html][https://www.cvedetails.com/product/32625/Sudo-Project-Sudo.html?vendor_id=15714][https://www.cvedetails.com/vulnerability-list/vendor_id-16191/Firejail-Project.html]

Files with the SUID bit set and not owned by root, or files with the SGID bit set ''typically'' have less potential impact but can theoretically still do decent damage if vulnerable. It is usually possible to avoid using SUID or SGID by assigning [[Capabilities]] instead.

{{Tip|It is vital to be vigilant in keeping packages which provide SUID/SGID executables up to date in order to prevent having a vulnerable system.}}

To search for files with either the SUID or SGID bit:

$ find / -perm "/u=s,g=s" -type f 2>/dev/null

=== Backups ===

{{Merge|System backup|There is a dedicated page for system backups.}}

Regularly create backups of important data. Regularly test the integrity of the backups. Regularly test that the backups can be restored.

Make sure that at least one copy of the data is stored offline, i.e. not connected to the system under threat in any way. [[Wikipedia:Ransomware|Ransomware]] and other destructive attacks may also attack any connected backup systems.

=== SATA SSD frozen mode ===

See [[Solid state drive#Setting the SATA SSD state to frozen mode after waking up from sleep]].

== User setup ==

=== Do not use the root account for daily use ===

Following the principle of least privilege, do not use the root user for daily use. Create a non-privileged user account for each person using the system. See [[List of applications/Security#Privilege elevation]] for ways of temporarily gaining privileged access.

=== Enforce a delay after a failed login attempt ===

Add the following line to {{ic|/etc/pam.d/system-login}} to add a delay of at least 4 seconds between failed login attempts:

{{hc|/etc/pam.d/system-login|2=
auth optional pam_faildelay.so delay=4000000
}}

{{Note|This line needs to be the first line in the file.}}

{{ic|4000000}} is the time in microseconds to delay.

Other PAM modules besides {{ic|pam_faildelay}} can also suggest such a delay; if multiple modules do so, PAM will use the longest one.

In particular, both {{ic|pam_unix}} and {{ic|pam_faillock}} set a minimum delay of 2 seconds by default.
In order to completely remove this delay, you need to add the {{ic|nodelay}} parameter to any {{ic|auth}} lines of these modules, for example
{{hc|/etc/pam.d/system-auth|2=
auth [success{{=}}1 default{{=}}bad] pam_unix.so try_first_pass nullok nodelay
}}

=== Lock out user after three failed login attempts ===

Since {{Pkg|pambase}} 20200721.1-2, {{ic|pam_faillock.so}} is enabled by default to lock out users for 10 minutes after 3 failed login attempts in a 15 minute period (see {{Bug|67644}}). The lockout only applies to password authentication (e.g. login and ''sudo''), public key authentication over SSH is still accepted. To prevent complete denial-of-service, this lockout is disabled for the root user by default.

To unlock a user, do:

$ faillock --user ''username'' --reset

By default, the lock mechanism is a file per-user located at {{ic|/run/faillock/}}. Deleting or emptying the file unlocks that user—the directory is owned by root, but the file is owned by the user, so the {{ic|faillock}} command only empties the file, therefore does not require root.

The module {{ic|pam_faillock.so}} can be configured with the file {{ic|1=/etc/security/faillock.conf}}. The lockout parameters:

* {{ic|unlock_time}} — the lockout time (in seconds, default 10 minutes).
* {{ic|fail_interval}} — the time in which failed logins can cause a lockout (in seconds, default 15 minutes).
* {{ic|deny}} — the number of failed logins before lockout (default 3).

{{Tip|The primary purpose for the lockout is to slow down brute-force attacks so that they become infeasible. Hence, if lockouts due to mistyping of passwords become too frequent, relaxing the number of attempts may be preferred to reducing the lockout time.}}

{{Note|{{ic|1=deny = 0}} will disable the lockout mechanism entirely.}}

By default, all user locks are lost after reboot. If your attacker can reboot the machine, it is more secure if locks persist. To make locks persist, change the {{ic|dir}} parameter in {{ic|1=/etc/security/faillock.conf}} to {{ic|/var/lib/faillock}}.

No restart is required for changes to take effect. See {{man|5|faillock.conf}} for further configuration options, such as enabling lockout for the root account, disabling for centralized login (e.g. LDAP), etc.

{{Note|If you make locks persistant, following the changes introduced in polkit 127: you may have to relax the sandbox of its helper agent in order to keep it functional. The best way is to create a drop-in for its systemd unit via {{ic|systemctl edit polkit-agent-helper\@.service}} and add:

[Service]
ReadWritePaths{{=}}/var/lib/faillock
}}

=== Limit amount of processes ===

On systems with many, or untrusted users, it is important to limit the number of processes each can run at once, therefore preventing [[Wikipedia:Fork bomb|fork bombs]] and other denial of service attacks. The {{ic|/etc/security/limits.conf}} configuration determines how many processes each user, or group can have open, and is empty (except for useful comments) by default. Adding the following lines to this file will limit all users to 100 active processes, unless they use the {{ic|prlimit}} command to explicitly raise their maximum to 200 for that session. These values can be changed according to the appropriate number of processes a user should have running, or the hardware of the box you are administrating.

* soft nproc 100
* hard nproc 200

The current number of threads for each user can be found with {{ic|ps --no-headers -Leo user {{!}} sort {{!}} uniq --count}}. This may help with determining appropriate values for the users' limits; see also [[limits.conf]].

=== Use Wayland ===

Prefer using [[Wayland]] over [[Xorg]]. Xorg's design predates modern security practices and is [https://security.stackexchange.com/questions/4641/why-are-people-saying-that-the-x-window-system-is-not-secure/4646#4646 considered insecure] by many. For example, Xorg applications may record keystrokes while inactive.

If you must run Xorg, it is recommended to [[Xorg#Rootless Xorg|avoid running it as root]]. Within Wayland, the Xwayland compatibility layer will automatically use rootless Xorg.

== Restricting root ==

The root user is, by definition, the most powerful user on a system. It is also difficult to [[audit]] the root user account. It is therefore important to restrict usage of the root user account as much as possible. There are a number of ways to keep the power of the root user while limiting its ability to cause harm.

=== Use sudo instead of su ===

Using [[sudo]] for privileged access is preferable to [[su]] for a number of reasons:

* It keeps a log of which normal privilege user has run each privileged command.
* The root user password need not be given out to each user who requires root access.
* {{ic|sudo}} prevents users from accidentally running commands as ''root'' that do not need root access, because a full root terminal is not created. This aligns with the [[Wikipedia:Principle of least privilege|principle of least privilege]].
* Individual programs may be enabled per user, instead of offering complete root access just to run one command.

See [[Sudo#Configuration]].

==== Editing files using sudo ====

See [[Sudo#Editing files]]. Alternatively, you can use editors like {{ic|rvim}} or {{ic|rnano}} which have restricted capabilities in order to be safe to run as root.

=== Restricting root login ===

Once [[sudo]] is properly configured, full root access can be heavily restricted or denied without losing much usability. To disable root, but still allowing to use [[sudo]], you can use {{man|1|passwd}} with {{ic|passwd --lock root}}.

==== Allow only certain users ====

The [[PAM]] {{ic|pam_wheel.so}} lets you allow only users in the group {{ic|wheel}} to login using [[su]]. See [[su#su and wheel]].

==== Denying SSH login ====

Even if you do not wish to deny root login for local users, it is always good practice to [[OpenSSH#Deny|deny root login via SSH]]. The purpose of this is to add an additional layer of security before a user can completely compromise your system remotely.

==== Specify acceptable login combinations with access.conf ====

{{Warning|If you are using GNOME 49 or later, you should make sure the group ''gdm'' can log in locally. This can be done with a {{ic|+:(gdm):LOCAL}} rule. [https://gitlab.gnome.org/GNOME/gdm/-/issues/1021]}}

When someone attempts to log in with [[PAM]], {{ic|/etc/security/access.conf}} is checked for the first combination that matches their login properties. Their attempt then fails or succeeds based on the rule for that combination.

+:root:LOCAL
-:root:ALL

Rules can be set for specific groups and users. In this example, the user archie is allowed to login locally, as are all users in the wheel and adm groups. All other logins are rejected:

+:archie:LOCAL
+:(wheel):LOCAL
+:(adm):LOCAL
-:ALL:ALL

Read more at {{man|5|access.conf}}

== Mandatory access control ==

[[Wikipedia:Mandatory Access Control|Mandatory access control]] (MAC) is a type of security policy that differs significantly from the [[Wikipedia:Discretionary Access Control|discretionary access control]] (DAC) used by default in Arch and most Linux distributions. MAC essentially means that every action a program could perform that affects the system in any way is checked against a security ruleset. This ruleset, in contrast to DAC methods, cannot be modified by users. Using virtually any mandatory access control system will significantly improve the security of your computer, although there are differences in how it can be implemented.

=== Pathname MAC ===

Pathname-based access control is a simple form of access control that offers permissions based on the path of a given file. The downside to this style of access control is that permissions are not carried with files if they are moved around the system. On the positive side, pathname-based MAC can be implemented on a much wider range of filesystems, unlike labels-based alternatives.

* [[AppArmor]] is a [[Wikipedia:Canonical (company)|Canonical]]-maintained MAC implementation seen as an "easier" alternative to SELinux.
* [[TOMOYO]] is another simple, easy-to-use system offering mandatory access control. It is designed to be both simple in usage and in implementation, requiring very few dependencies.

=== Labels MAC ===

Labels-based access control means the extended attributes of a file are used to govern its security permissions. While this system is arguably more flexible in its security offerings than pathname-based MAC, it only works on filesystems that support these extended attributes.

* [[SELinux]], based on an [[Wikipedia:NSA|NSA]] project to improve Linux security, implements MAC completely separate from system users and roles. It offers an extremely robust multi-level MAC policy implementation that can easily maintain control of a system that grows and changes past its original configuration.

=== Access Control Lists ===

[[Access Control Lists]] (ACLs) are an alternative to attaching rules directly to the filesystem in some way. ACLs implement access control by checking program actions against a list of permitted behavior.

== Kernel hardening ==

=== Kernel self-protection / exploit mitigation ===

The {{pkg|linux-hardened}} package uses a [https://github.com/anthraxx/linux-hardened basic kernel hardening patch set] and more security-focused compile-time configuration options than the {{pkg|linux}} package. A custom build can be made to choose a different compromise between security and performance than the security-leaning defaults.

However, it should be noted that several packages (such as {{pkg|throttled}}) will not work when using this kernel.

If you use an out-of-tree driver such as [[NVIDIA]], you may need to switch to its [[DKMS]] package.

==== Userspace ASLR comparison ====

The {{pkg|linux-hardened}} package provides an improved implementation of Address Space Layout Randomization for userspace processes. The {{pkg|paxtest}} command can be used to obtain an estimate of the provided entropy:

===== 64-bit processes =====

{{hc|linux-hardened 5.4.21.a-1-hardened|
Anonymous mapping randomization test : 32 quality bits (guessed)
Heap randomization test (ET_EXEC) : 40 quality bits (guessed)
Heap randomization test (PIE) : 40 quality bits (guessed)
Main executable randomization (ET_EXEC) : 32 quality bits (guessed)
Main executable randomization (PIE) : 32 quality bits (guessed)
Shared library randomization test : 32 quality bits (guessed)
VDSO randomization test : 32 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 40 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 40 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 44 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 44 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 34 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 34 quality bits (guessed)
Randomization under memory exhaustion @~0: 32 bits (guessed)
Randomization under memory exhaustion @0 : 32 bits (guessed)
}}

{{hc|linux 5.5.5-arch1-1|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 20 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 29 bits (guessed)
Randomization under memory exhaustion @0 : 29 bits (guessed)
}}

{{hc|linux-lts 4.19.101-1-lts|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 19 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 28 bits (guessed)
Randomization under memory exhaustion @0 : 28 bits (guessed)
}}

===== 32-bit processes (on an x86_64 kernel) =====

{{hc|linux-hardened|
Anonymous mapping randomization test : 16 quality bits (guessed)
Heap randomization test (ET_EXEC) : 22 quality bits (guessed)
Heap randomization test (PIE) : 27 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 18 quality bits (guessed)
Shared library randomization test : 16 quality bits (guessed)
VDSO randomization test : 16 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 24 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 24 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 28 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 28 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 18 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 16 quality bits (guessed)
Randomization under memory exhaustion @~0: 18 bits (guessed)
Randomization under memory exhaustion @0 : 18 bits (guessed)
}}

{{hc|linux|
Anonymous mapping randomization test : 8 quality bits (guessed)
Heap randomization test (ET_EXEC) : 13 quality bits (guessed)
Heap randomization test (PIE) : 13 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 8 quality bits (guessed)
Shared library randomization test : 8 quality bits (guessed)
VDSO randomization test : 8 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 19 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 19 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 11 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 11 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 8 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 13 quality bits (guessed)
Randomization under memory exhaustion @~0: No randomization
Randomization under memory exhaustion @0 : No randomization
}}

=== Restricting access to kernel pointers in the proc filesystem ===

Setting {{ic|kernel.kptr_restrict}} to 1 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} from regular users without {{ic|CAP_SYSLOG}}, making it more difficult for kernel exploits to resolve addresses/symbols dynamically. This will not help that much on a pre-compiled Arch Linux kernel, since a determined attacker could just download the kernel package and get the symbols manually from there, but if you are compiling your own kernel, this can help mitigating local root exploits. This will break some {{Pkg|perf}} commands when used by non-root users (but many {{Pkg|perf}} features require root access anyway). See {{Bug|34323}} for more information.

Setting {{ic|kernel.kptr_restrict}} to 2 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} regardless of privileges.

{{hc|/etc/sysctl.d/51-kptr-restrict.conf|2=
kernel.kptr_restrict = 1
}}

{{Note|{{pkg|linux-hardened}} sets {{ic|1=kptr_restrict=2}} by default rather than {{ic|0}}.}}

=== BPF hardening ===

BPF is a system used to load and execute bytecode within the kernel dynamically during runtime. It is used in a number of Linux kernel subsystems such as networking (e.g. XDP, tc), tracing (e.g. kprobes, uprobes, tracepoints) and security (e.g. seccomp). It is also useful for advanced network security, performance profiling and dynamic tracing.

BPF was originally an acronym of [[Wikipedia:Berkeley Packet Filter|Berkeley Packet Filter]] since the original classic BPF was used for packet capture tools for BSD. This eventually evolved into Extended BPF (eBPF), which was shortly afterwards renamed to just BPF (not an acronym). BPF should not be confused with packet filtering tools like iptables or netfilter, although BPF can be used to implement packet filtering tools.

BPF code may be either interpreted or compiled using a [[Wikipedia:Just-in-time compilation|Just-In-Time (JIT) compiler]]. The Arch kernel is built with {{ic|CONFIG_BPF_JIT_ALWAYS_ON}} which disables the BPF interpreter and forces all BPF to use JIT compilation. This makes it harder for an attacker to use BPF to escalate attacks that exploit SPECTRE-style vulnerabilities. See [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=290af86629b25ffd1ed6232c4e9107da031705cb the kernel patch which introduced CONFIG_BPF_JIT_ALWAYS_ON] for more details.

The kernel includes a hardening feature for JIT-compiled BPF which can mitigate some types of JIT spraying attacks at the cost of performance and the ability to trace and debug many BPF programs. It may be enabled by setting {{ic|net.core.bpf_jit_harden}} to {{ic|1}} (to enable hardening of unprivileged code) or {{ic|2}} (to enable hardening of all code).

See the {{ic|net.core.bpf_*}} settings in the [https://docs.kernel.org/admin-guide/sysctl/net.html kernel documentation] for more details.

{{Tip|
* {{Pkg|linux-hardened}} sets {{ic|1=net.core.bpf_jit_harden=2}} by default rather than {{ic|0}}.
* By default, BPF programs can be run even by unprivileged users. To change that behaviour set {{ic|1=kernel.unprivileged_bpf_disabled=1}}[https://access.redhat.com/security/cve/cve-2021-33624].
}}

=== ptrace scope ===

The {{man|2|ptrace}} syscall provides a means by which one process (the "tracer") may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. {{ic|ptrace}} is commonly used by debugging tools including ''gdb'', ''strace'', ''perf'', ''reptyr'' and other debuggers. However, it also provides a means by which a malicious process can read data from and take control of other processes.

Arch enables the [https://docs.kernel.org/admin-guide/LSM/Yama.html Yama LSM] by default, which provides a {{ic|kernel.yama.ptrace_scope}} [[kernel parameter]]. This parameter is set to {{ic|1}} (restricted) by default which prevents tracers from performing a {{ic|ptrace}} call on traces outside of a restricted scope unless the tracer is privileged or has the {{ic|CAP_SYS_PTRACE}} [[Capabilities|capability]]. This is a significant improvement in security compared to the classic permissions. Without this module, there is no separation between processes running as the same user (in the absence of additional security layers such as {{man|7|pid_namespaces}}).

{{Note|By default, you can still use tools which require {{ic|ptrace}} by running them as privileged processes, e.g. using [[sudo]].}}

If you do not need to use debugging tools, consider setting {{ic|kernel.yama.ptrace_scope}} to {{ic|2}} (admin-only) or {{ic|3}} (no {{ic|ptrace}} possible) to harden the system.

{{Note|Some anti-cheat and DRM implementations rely on {{ic|ptrace}} to work, including Easy Anti-Cheat and Ubisoft Connect under Wine. Setting this parameter to {{ic|2}} or higher might prevent games using these solutions from launching.}}

=== hidepid ===

{{Expansion|1=[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0fb5ce62c5920b6e0a8a061f2fe80e0403281e10 Linux 5.8 implemented private instances] and new values for {{ic|1=hidepid=}}.}}

{{Accuracy|Enabling {{ic|hidepid}} globally is not a supported way of operation by [[systemd]], nor does it have any practical improvements security-wise when systemd is running as service manager. [https://github.com/systemd/systemd/issues/29893#issuecomment-1798030108]}}

{{Warning|
* This may cause issues for certain applications like an application running in a sandbox and [[Xorg]] (see workaround).
* This causes issues with [[D-Bus]], [[Polkit]], [[PulseAudio]] and [[bluetooth]] when using {{Pkg|systemd}} > 237.64-1.
}}

The kernel has the ability to hide other users' processes, normally accessible via {{ic|/proc}}, from unprivileged users by mounting the {{ic|proc}} filesystem with the {{ic|1=hidepid=}} and {{ic|1=gid=}} options documented in https://docs.kernel.org/filesystems/proc.html.

This greatly complicates an intruder's task of gathering information about running processes, whether some daemon runs with elevated privileges, whether other user runs some sensitive program, whether other users run any program at all, makes it impossible to learn whether any user runs a specific program (given the program does not reveal itself by its behaviour), and, as an additional bonus, poorly written programs passing sensitive information via program arguments are now protected against local eavesdroppers.

The {{ic|proc}} [[Users and groups#System groups|group]], provided by the {{Pkg|filesystem}} package, acts as a whitelist of users authorized to learn other users' process information. If users or services need access to {{ic|/proc/<pid>}} directories beyond their own, [[Users and groups#Group management|add them to the group]].

For example, to hide process information from other users except those in the {{ic|proc}} group:

{{hc|/etc/fstab|2=
proc /proc proc nosuid,nodev,noexec,hidepid=2,gid=proc 0 0
}}

For user sessions to work correctly, an exception needs to be added for ''systemd-logind'':

{{hc|/etc/systemd/system/systemd-logind.service.d/hidepid.conf|2=
[Service]
SupplementaryGroups=proc
}}

=== Restricting module loading ===

The default Arch kernel has {{ic|CONFIG_MODULE_SIG_ALL}} enabled, which signs all kernel modules built as part of the {{Pkg|linux}} package. This allows the kernel to only load modules signed with a valid key, i.e. out-of-tree modules compiled locally or provided by packages such as {{Pkg|virtualbox-host-modules-arch}} cannot be loaded. You can use {{ic|1=modinfo}} to verify currently loaded modules have signatures; verifying the signatures by hand is slightly more involved [https://unix.stackexchange.com/a/496800].

Kernel module loading can be restricted by setting the {{ic|1=module.sig_enforce=1}} [[kernel parameter]]. More information can be found in the [https://docs.kernel.org/admin-guide/module-signing.html kernel documentation].

Further, unneeded individual modules can be [[blacklist]]ed, see [https://github.com/secureblue/secureblue/blob/live/files/system/usr/lib/modprobe.d/secureblue.conf secureblue] for examples.

=== Disable kexec ===

Kexec allows replacing the current running kernel.

{{hc|/etc/sysctl.d/51-kexec-restrict.conf|2=
kernel.kexec_load_disabled = 1
}}

{{Tip|kexec is disabled by default in {{pkg|linux-hardened}}.}}

=== Kernel lockdown mode ===

Linux supports an optional [https://mjg59.dreamwidth.org/55105.html lockdown feature], intended to strengthen the boundary between UID 0 (root) and the kernel. When enabled some applications may cease to work which rely on low-level access to either hardware or the kernel.

To use lockdown, its LSM must be initialized and a lockdown mode must be set.

All [[Kernel#Officially supported kernels|officially supported kernels]] initialize the LSM, but none of them enforce any lockdown mode.

{{Tip|Initialized LSMs can be verified by running {{ic|cat /sys/kernel/security/lsm}}.}}

Lockdown has two modes of operation:

* {{ic|integrity}}: kernel features that allow userland to modify the running kernel are disabled (e.g. kexec, bpf).
* {{ic|confidentiality}}: kernel features that allow userland to extract confidential information from the kernel are also disabled.

It is recommended to use {{ic|integrity}}, unless your specific threat model dictates otherwise.

To enable kernel lockdown at runtime, run:

# echo ''mode'' > /sys/kernel/security/lockdown

To enable kernel lockdown on boot, use the [[kernel parameter]] {{ic|1=lockdown=''mode''}}.

{{Note|
* Kernel lockdown cannot be disabled at runtime.
* Kernel lockdown disables [[hibernation]].
* Versions <6.17 of the {{man|7|kernel_lockdown}} man page incorrectly state that "lockdown will be automatically enabled if the system boots in EFI Secure Boot mode". This is not the behaviour of the upstream kernel, nor Arch's packaged [[kernel]]s.
}}

See also {{man|7|kernel_lockdown}}.

=== Linux Kernel Runtime Guard (LKRG) ===

[https://www.openwall.com/lkrg/ LKRG] ({{AUR|lkrg-dkms}}) is a kernel module which performs integrity checking of the kernel and detection of exploit attempts.

=== Disable emergency shell ===

{{Accuracy|Masking {{ic|emergency.target}} and {{ic|emergency.service}} will have no effect on those units being added to the initramfs and run in early userspace. Even with them in the initramfs, mkinitcpio's systemd hook locks the root account[https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/292cdf8a2f7dd7c6c7d91d2b59617391935c837c][https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/8835b2f5dfbe8663f1a2fd08edbd35f90bf08691] for "security reasons" (see {{Bug|70408}}). The solution for the issue in the linked article, if even needed, would be to prevent {{ic|rescue.target}}, {{ic|rescue.service}}, {{ic|emergency.target}} and {{ic|emergency.service}} from being added to the initramfs image.}}

The emergency shell is used to interactively troubleshoot the machine during the boot process. However, it is also a gadget that an attacker can use to access secure resources such as the TPM. See [https://pulsesecurity.co.nz/advisories/tpm-luks-bypass this article] for a practical example. The difficulty of attacks can be increased by disabling the emergency shell, at the tradeoff of removing a tool to troubleshoot early boot failures.

To disable the emergency shell, See [[systemd#Disable emergency mode on remote machine]].

== Sandboxing applications ==

See also [[Wikipedia:Sandbox (computer security)]].

To improve the security of systemd service units, see [[systemd/Sandboxing]].

{{Warning|Unprivileged user namespace usage is enabled by default in all [[Kernel#Officially supported kernels|officially supported kernels]] except for {{Pkg|linux-hardened}}. Unprivileged user namespaces greatly increase the attack surface for local privilege escalation; see [https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction AppArmor's Wiki] and {{Bug|36969}}.}}

To mitigate this, either:

* use the {{Pkg|linux-hardened}} kernel which has the safe default, or
* set the {{ic|kernel.unprivileged_userns_clone}} [[sysctl]] to {{ic|0}}.

Note that this can break applications such as {{pkg|nsjail}}. [[Chromium]] based applications need SUID bit for {{ic|chrome-sandbox}} to work with this setting.

=== Firejail ===

[[Firejail]] is an easy to use tool for sandboxing applications and servers alike. It was originally created for browsers and internet facing applications, but supports a large number of applications by now. To establish a sandboxed environment with a variety of features, it is installed as a suid binary and builds a sandboxed runtime environment for the target application based on black and white lists.

=== bubblewrap ===

[[bubblewrap]] is a sandbox application developed for unprivileged container tools like [[Flatpak]] with a significantly smaller resource footprint and complexity than Firejail. While it lacks certain features such as file path whitelisting, bubblewrap does offer bind mounts as well as the creation of user/IPC/PID/network/cgroup namespaces and can support both simple and complex sandboxes. For the {{Pkg|linux-hardened}} kernel you will need to to use {{Pkg|bubblewrap-suid}}.

[[Bubblejail]] sandbox is based on [[bubblewrap]] and provides a resource oriented permission model with a graphical interface to tweak permissions.

=== Portable ===

[https://github.com/Kraftland/portable Portable] is a sandboxing framework which utilizes [[bubblewrap]] and many other tools to lockdown running applications. It is designed to be simple for packagers and efficient for users, yet cuts off security holes and monitors background processes by default.

See [https://github.com/Kraftland/portable-arch portable-arch] for a repository of applications sandboxed by portable.

If a sandboxed application does not utilize the Portal file chooser, portable can pass files to the sandbox (by passing {{ic|--actions share-files}}).

Portable is fully functional on GNOME, while other desktops may lack small amounts of features like advanced background monitoring and ScreenShot portal.

=== chroots ===

Manual [[chroot]] jails can also be constructed to build sandboxed process environments. It is much more limited than other sandboxing technologies; the extent of its sandboxing is file path isolation.

=== Linux containers ===

[[Linux Containers]] are another good option when you need more separation than the other options (short of [[#Full virtualization options|full system virtualization]]) provide. LXC is run on top of the existing kernel in a pseudo-chroot with their own virtual hardware.

=== gVisor ===

The [https://gvisor.dev/ gVisor] project, led by Google, is providing a sandboxing application with a focus on containers following the [https://opencontainers.org/ OCI initiative], such as [[Docker]] and [[Kubernetes]]. It isolates containers and individual applications from the host by intercepting a majority of system calls to the kernel and presenting itself as guest kernel.

A key difference to other intercepting sandboxing projects is that gVisor re-implements system calls in the Go programming language, as described in its [https://gvisor.dev/docs/architecture_guide/intro/ design overview]. Details for the list of [https://gvisor.dev/docs/user_guide/compatibility/linux/amd64/ re-implemented syscalls support] can be seen in [https://github.com/google/gvisor/blob/master/pkg/sentry/syscalls/linux/linux64.go git]. For usage examples, limitations and special features see the project [https://gvisor.dev/docs/ documentation].

The application is available as {{Aur|gvisor-git}} and {{Aur|gvisor-bin}}.

=== Full virtualization options ===

Using full virtualization options such as [[VirtualBox]], [[KVM]], [[Xen]] or [https://www.qubes-os.org/ Qubes OS] (based on Xen) can also improve isolation and security in the event you plan on running risky applications or browsing dangerous websites.

== Network and firewalls ==

=== Firewalls ===

While the stock Arch kernel is capable of using [[Wikipedia:Netfilter|Netfilter]]'s [[iptables]] and [[nftables]], the services are not [[enable]]d by default. It is highly recommended to set up some form of firewall to protect the services running on the system. Many resources (including ArchWiki) do not state explicitly which services are worth protecting, so enabling a firewall is a good precaution.

* See [[iptables]] and [[nftables]] for general information.
* See [[Simple stateful firewall]] for a guide on setting up an iptables firewall.
* See [[:Category:Firewalls]] for other ways of setting up netfilter.
* See [[Ipset]] for blocking lists of ip addresses, such as those from Bluetack.
* {{Pkg|opensnitch}} is a configurable inbound and outbound firewall with support for configurable rules by application, port, host, etc.

A quick way to setup a basic firewall is to use the tool {{ic|ufw}} (Uncomplicated Fire Wall). Then set {{ic|ufw default deny incoming}} and {{ic|ufw default allow outgoing}} and enabling it with {{ic|ufw enable}} and {{ic|systemctl enable ufw}}.

==== Open ports ====

{{Style|"Open ports" is not a good title since it disregards interfaces and addresses that the application may be bound to. From the firewalls' point of view, ports may be "open" even if no application listens on them at the moment.}}

Some services listen for inbound traffic on open network ports. It is important to only bind these services to the addresses and interfaces that are strictly necessary. It may be possible for a remote attacker to [https://samy.pl/slipstream/ exploit flawed network protocols to access exposed services]. This can even happen with [https://nvd.nist.gov/vuln/detail/CVE-2019-13450 processes bound to localhost].

In general, if a service only needs to be accessible to the local system, bind to a Unix domain socket ({{man|7|unix}}) or a loopback address such as {{ic|localhost}} instead of a non-loopback address like {{ic|0.0.0.0/0}}.

If a service needs to be accessible to other systems via the network, control the access with strict [[firewall]] rules and configure authentication, authorization and encryption whenever possible.

You can list all current open ports with {{ic|ss -l}}. To show all '''l'''istening '''p'''rocesses and their '''n'''umeric '''t'''cp and '''u'''dp port numbers:

# ss -lpntu

See {{man|8|ss}} for more options.

=== Kernel parameters ===

Kernel parameters which affect networking can be set using [[Sysctl]]. For how to do this, see [[Sysctl#TCP/IP stack hardening]].

=== SSH ===

To mitigate [[Wikipedia:Brute-force attack|brute-force attacks]] it is recommended to enforce key-based authentication. For OpenSSH see [[OpenSSH#Protection]] for more recommendations. Alternatively [[Fail2ban]] or [[Sshguard]] offer lesser forms of protection by monitoring logs and writing [[firewall]] rules but open up the potential for a denial of service, since an attacker can [[Wikipedia:Spoofing attack#Spoofing and TCP/IP|spoof]] packets as if they came from the administrator after identifying their address. Spoofing IP has lines of defense, such as by [[sysctl#Reverse path filtering|reverse path filtering]] and [[sysctl#Disable ICMP redirects|disabling ICMP redirects]].

You may want to harden authentication even more by using two-factor authentication. [[Google Authenticator]] provides a two-step authentication procedure using one-time passcodes (OTP).

Denying root login is also a good practice, both for tracing intrusions and adding an additional layer of security before root access. For OpenSSH, see [[OpenSSH#Deny]].

Mozilla publishes an [https://infosec.mozilla.org/guidelines/openssh.html OpenSSH configuration guide] which configures more verbose audit logging and restricts ciphers.

=== DNS ===

The default domain name resolution (DNS) configuration is highly compatible but has security weaknesses. See [[Domain name resolution#Privacy and security|DNS privacy and security]] for more information.

=== Proxies ===

Proxies are commonly used as an extra layer between applications and the network, sanitizing data from untrusted sources. The attack surface of a small proxy running with lower privileges is significantly smaller than a complex application running with the end user privileges.

For example the DNS resolver is implemented in {{Pkg|glibc}}, that is linked with the application (that may be running as root), so a bug in the DNS resolver might lead to a remote code execution. This can be prevented by installing a DNS caching server, such as [[dnsmasq]], which acts as a proxy. [https://googleonlinesecurity.blogspot.it/2016/02/cve-2015-7547-glibc-getaddrinfo-stack.html]

=== Managing TLS certificates ===

See [[TLS#Trust management]].

== Physical security ==

Physical access to a computer is root access given enough time and resources. However, a high ''practical'' level of security can be obtained by putting up enough barriers.

An attacker can gain full control of your computer on the next boot by simply attaching a malicious IEEE 1394 (FireWire), Thunderbolt or PCI Express device as they are given full memory access by default.[https://web.archive.org/web/20210312083421/http://breaknenter.org/2014/09/inception-metasploit-integration/] For Thunderbolt, you can restrict the direct memory access completely or to known devices, see [[Thunderbolt#User device authorization|user device authorization]]. For Firewire and PCI Express, there is little you can do from preventing this, or modification of the hardware itself - such as flashing malicious firmware onto a drive. However, the vast majority of attackers will not be this knowledgeable and determined.

[[#Data-at-rest encryption|Data-at-rest encryption]] will prevent access to your data if the computer is stolen, but malicious firmware can be installed to obtain this data upon your next log in by a resourceful attacker.

=== Locking down BIOS ===

Adding a password to the BIOS prevents someone from booting into removable media, which is basically the same as having root access to your computer. You should make sure your drive is first in the boot order and disable the other drives from being bootable if you can.

=== Boot loaders ===

It is highly important to protect your [[boot loader]]. An unprotected boot loader can bypass any login restrictions, e.g. by setting the {{ic|1=init=/bin/sh}} [[kernel parameter]] to boot directly to a shell.

==== Syslinux ====

[[Syslinux]] supports [[Syslinux#Security|password-protecting your boot loader]]. It allows you to set either a per-menu-item password or a global boot loader password.

==== GRUB ====

[[GRUB]] supports boot loader passwords as well. See [[GRUB/Tips and tricks#Password protection of GRUB menu]] for details. It also has support for [[GRUB#Encrypted /boot|encrypted /boot]], which only leaves some parts of the boot loader code unencrypted. GRUB's configuration, [[kernel]] and [[initramfs]] are encrypted.

==== systemd-boot ====

[[systemd-boot]] disables editing of kernel parameters when [[#Secure Boot|Secure Boot]] is enabled. Alternatively, you can set [[systemd-boot#Kernel parameters editor with password protection|kernel parameters for password protection]] in systemd-boot for a more traditional password-based option.

=== Secure Boot ===

[[Secure Boot]] is a feature of [[UEFI]] that allows authentication of the files your computer boots. This helps preventing some [[Wikipedia:Evil maid attack|evil maid attacks]] such as replacing files inside the boot partition. Normally computers come with keys that are enrolled by vendors (OEM). However these can be removed and allow the computer to enter ''Setup Mode'' which allows the user to enroll and manage their own keys.

The secure boot page guides you through how to set secure boot up by [[Unified Extensible Firmware Interface/Secure Boot#Using your own keys|using your own keys]].

=== Trusted Platform Module (TPM) ===

[[Trusted Platform Module|TPMs]] are hardware microprocessors which have cryptographic keys embedded. This forms the fundamental root of trust of most modern computers and allows end-to-end verification of the boot chain. They can be used as internal smartcards, attest the firmware running on the computer and allow users to insert secrets into a tamper-proof and brute-force resistant store.

=== Boot partition on removable flash drive ===

One popular idea is to place the boot partition on a flash drive in order to render the system unbootable without it. Proponents of this idea often use [[#Data-at-rest encryption|full-disk encryption]] alongside, and some also use [[Dm-crypt/Specialties#Encrypted system using a detached LUKS header|detached encryption headers]] placed on the boot partition.

This method can also be merged with [[Dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB|encrypting /boot]].

=== Automatic logout ===

If you are using [[Bash]] or [[Zsh]], you can set {{ic|TMOUT}} for an automatic logout from shells after a timeout.

For example, the following will automatically log out from virtual consoles (but not terminal emulators in X11):

{{hc|/etc/profile.d/shell-timeout.sh|<nowiki>
TMOUT="$(( 60*10 ))";
[ -z "$DISPLAY" ] && export TMOUT;
case $( /usr/bin/tty ) in
/dev/tty[0-9]*) export TMOUT;;
esac
</nowiki>}}

If you really want EVERY Bash/Zsh prompt (even within X) to timeout, use:

$ export TMOUT="$(( 60*10 ))";

Note that this will not work if there is some command running in the shell (eg.: an SSH session or other shell without {{ic|TMOUT}} support). But if you are using VC mostly for restarting frozen GDM/Xorg as root, then this is very useful.

=== Protect against rogue USB devices ===

The kernel has [https://docs.kernel.org/usb/authorization.html settings to deactivate] USB ports to protect your computer against rogue USB devices (a.k.a. [[Wikipedia:BadUSB|BadUSB]], [https://github.com/samyk/poisontap PoisonTap] or [https://lanturtle.com/ LanTurtle]). They can be set at runtime and automated via [[sysctl]].

For more control install [[USBGuard]], which is a software framework implementing basic whitelisting and blacklisting capabilities based on device attributes.

=== Volatile data collection ===

A computer that is powered on may be vulnerable to [https://web.archive.org/web/20210420075636/https://fedvte.usalearning.gov/courses/CSI/course/videos/pdf/CSI_D01_S05_T01_STEP.pdf volatile data collection]. It is a best practice to turn a computer completely off at times it is not necessary for it to be on, or if the computer's physical security is temporarily compromised (e.g. when passing through a security checkpoint).

== Packages ==

=== Authentication ===

[https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html#overview Attacks on package managers] are possible without proper use of package signing, and can affect even package managers with [https://www2.cs.arizona.edu/stork/packagemanagersecurity/faq.html proper signature systems]. Arch uses package signing by default and relies on a web of trust from 5 trusted master keys. See [[Pacman-key]] for details.

=== Upgrades ===

It is important to regularly [[System maintenance#Upgrading the system|upgrade the system]].

=== Follow vulnerability alerts ===

Subscribe to the Common Vulnerabilities and Exposure (CVE) Security Alert updates, made available by National Vulnerability Database, and found on the [https://nvd.nist.gov/download.cfm NVD Download webpage].

The tool {{Pkg|arch-audit}} can be used to check for vulnerabilities affecting the running system. A graphical system tray, {{Pkg|arch-audit-gtk}}, can also be used. See also [[Arch Security Team]].

You should also consider subscribing to the release notifications for software you use, especially if you install software through means other than the main repositories or AUR. Some software have mailing lists you can subscribe to for security notifications. Source code hosting sites often offer RSS feeds for new releases.

=== Rebuilding packages ===

Packages can be rebuilt and stripped of undesired functions and features as a means to reduce attack surface. For example, {{Pkg|bzip2}} can be rebuilt without {{ic|bzip2recover}} in an attempt to circumvent [https://security.archlinux.org/CVE-2016-3189 CVE-2016-3189]. Custom hardening flags can also be applied either manually or via a wrapper.

{{Merge|Arch package guidelines/Security|Security related build flags have their own article.}}

{{Accuracy|Copy-pasted from a 3 years old blog post. The compiler flags are specific to [[GCC]], some are hardly security related.}}

{| class="wikitable"
! Flag !! Purpose
|-
| -D_FORTIFY_SOURCE=2 || Run-time buffer overflow detection
|-
| -D_GLIBCXX_ASSERTIONS || Run-time bounds checking for C++ strings and containers
|-
| -fasynchronous-unwind-tables || Increased reliability of backtraces
|-
| -fexceptions || Enable table-based thread cancellation
|-
| -fpie -Wl,-pie || Full ASLR for executables
|-
| -fpic -shared || No text relocations for shared libraries
|-
| -fplugin=annobin || Generate data for hardening quality control
|-
| -fstack-clash-protection || Increased reliability of stack overflow detection
|-
| -fstack-protector, -fstack-protector-all or -fstack-protector-strong || Stack smashing protector
|-
| -grecord-gcc-switches || Store compiler flags in debugging information
|-
| -mcet -fcf-protection || Control flow integrity protection
|-
| -Werror=format-security || Reject potentially unsafe format string arguments
|-
| -Werror=implicit-function-declaration || Reject missing function prototypes
|-
| -Wl,-z,defs || Detect and reject underlinking
|-
| -Wl,-z,now || Disable lazy binding
|-
| -Wl,-z,relro || Read-only segments after relocation
|}

* [https://developers.redhat.com/blog/2018/03/21/compiler-and-linker-flags-gcc/ Flags and info source]

== See also ==

* [https://security.archlinux.org/ Arch Linux Security Tracker]
* [https://wiki.centos.org/HowTos/OS_Protection CentOS Wiki: OS Protection]
* [https://web.archive.org/web/20210712001756/https://developer.ibm.com/technologies/linux/articles/l-harden-desktop/ Hardening the Linux desktop]
* [https://web.archive.org/web/20190701140035/https://www.ibm.com/developerworks/linux/tutorials/l-harden-server/index.html Hardening the Linux server]
* [https://github.com/lfit/itpol/blob/master/linux-workstation-security.md Linux Foundation: Linux workstation security checklist]
* [https://www.privacyguides.org/ privacyguides.org Privacy Resources]
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/ Red Hat Enterprise Linux 7 Security Guide]
* [https://www.debian.org/doc/manuals/securing-debian-manual/index.en.html Securing Debian Manual]
* [https://web.archive.org/web/20140220055801/http://crunchbang.org:80/forums/viewtopic.php?id=24722 The paranoid #! Security Guide]

Security

2026-05-11T18:59:26Z

Indigo: /* Enforce a delay after a failed login attempt */ expand e.g.

[[Category:Security]]
[[Category:File systems]]
[[Category:Networking]]
[[de:Sicherheit]]
[[es:Security]]
[[hu:Security]]
[[ja:セキュリティ]]
[[pt:Security]]
[[ru:Security]]
[[zh-hans:Security]]
{{Related articles start}}
{{Related|Arch Security Team}}
{{Related|General recommendations}}
{{Related|Identity management}}
{{Related|Capabilities}}
{{Related|List of Applications/Security}}
{{Related|Arch package guidelines/Security}}
{{Related articles end}}
This article contains recommendations and best practices for [[Wikipedia:Hardening (computing)|hardening]] an Arch Linux system.

== Concepts ==

* It ''is'' possible to tighten security to the point where the system is unusable. Security and convenience must be balanced. The trick is to create a secure ''and'' useful system.
* The biggest threat is, and will always be, the user.
* The [[Wikipedia:Principle of least privilege|principle of least privilege]]: Each part of a system should only be able to access what is strictly required, and nothing more.
* Defense in depth: Security works better in independent layers. When one layer is breached, another should stop the attack.
* Be a little paranoid. And be suspicious. If anything sounds too good to be true, it probably is!
* You can never make a system 100% secure unless you unplug the machine from all networks, turn it off, lock it in a safe, smother it in concrete and never use it.
* Prepare for failure. Create a plan ahead of time to follow when your security is broken.

== Passwords ==

Passwords are key to a secure system. They secure your [[Users and groups|user accounts]], [[Data-at-rest encryption|encrypted filesystems]], and [[SSH keys|SSH]]/[[GPG]] keys. They are the main way a computer chooses to trust the person using it, so a big part of security is just about picking secure passwords and protecting them.

=== Choosing secure passwords ===

Passwords must be complex enough to not be easily guessed from e.g. personal information, or [[Wikipedia:Password cracking|cracked]] using methods like brute-force attacks. The tenets of strong passwords are based on ''length'' and ''randomness''. In cryptography the quality of a password is often referred to as its [[Wikipedia:Password strength#Entropy as a measure of password strength|entropy]].

Insecure passwords include those containing or those using as a base before substitution/variation:

* Personally identifiable information (e.g., your dog's name, date of birth, area code, favorite video game)
* Simple character substitutions on words (e.g., {{ic|k1araj0hns0n}}), as modern dictionary attacks can easily work with these
* Root "words" or common strings followed or preceded by added numbers, symbols, or characters (e.g., {{ic|DG091101%}})
* Common phrases or short strings of common dictionary words (e.g. {{ic|photocopyhauntbranchexpose}}) including with character substitution (e.g. {{ic|Ph0toc0pyh4uN7br@nch3xp*se}}) (See Diceware below for when a combination of dictionary words can be secure)
* Any of the [[Wikipedia:List of the most common passwords|most common passwords]]

The best choice for a password is something long (the longer, the better) and generated from a random source. It is important to use a long password. [https://www.theregister.com/2019/02/14/password_length Weak hash algorithms allow an 8-character password hash to be compromised in just a few hours.]

Tools like {{Pkg|pwgen}} or {{AUR|apg}} can generate random passwords. However, these passwords can be difficult to memorize. One memorization technique (for ones often typed) is to generate a long password and memorize a minimally secure number of characters, temporarily writing down the full generated string. Over time, increase the number of characters typed - until the password is ingrained in muscle memory and need not be remembered. This technique is more difficult, but can provide confidence that a password will not turn up in wordlists or "intelligent" brute force attacks that combine words and substitute characters.

Apart from password management, {{Pkg|keepassxc}} offers password/passphrase generation. It is possible to customize the generation in a GUI. Dictionary based passphrases are also supported.

One technique for memorizing a password is to use a mnemonic phrase, where each word in the phrase reminds you of the next character in the password.
Take for instance “the girl is walking down the rainy street” could be translated to {{ic|t6!WdtR5}} or, less simply, {{ic|t&6!RrlW@dtR,57}}.
This approach could make it easier to remember a password, but note that the various letters have very different probabilities of being found at the start of words ([[Wikipedia:Letter frequency#Relative frequencies of the first letters of a word in the English language|Wikipedia:Letter frequency]]).

Another effective technique can be to write randomly generated passwords down and store them in a ''safe'' place, such as in a wallet, purse, or document safe. Most people do a generally good job of protecting their physical valuables from attack, and it is easier for most people to understand physical security best practices compared to digital security practices.

It is also very effective to combine the mnemonic and random technique by saving long randomly generated passwords with a [[password manager]], which will be in turn accessed with a memorable "master password"/primary password that must be used only for that purpose. The master password must be memorized and never saved. This requires the password manager to be installed on a system to easily access the password (which could be seen as an inconvenience or a security feature, depending on the situation). Some password managers also have smartphone apps which can be used to display passwords for manual entry on systems without that password manager installed (if that is a common use case, you could still use easily typeable but secure passwords for each service instead of completely random ones, see below). Note that a password manager introduces a single point of failure if you ever forget the master password.
Some password managers compute the contained passwords based on the master password and the service name where you want to log in instead of encrypting them, making it possible to use it on a new system without syncing any data.

It can be effective to use a memorable long series of unrelated words as a password. The theory is that if a sufficiently long phrase is used, the gained entropy from the password's length can counter the lost entropy from the use of dictionary words. This [https://xkcd.com/936/ xkcd comic] demonstrates the entropy tradeoff of this method, taking into account the limited set of possible words for each word in the passphrase. If the set of words you choose from is large (multiple thousand words) and you choose 5-7 or even more random words from it, this method provides great entropy, even assuming the attacker knows the set of possible words chosen from and the number of words chosen. The number of possible passphrases after settling on a set of words and number of words is: (number of words in the set of words to select from) to the power of (the number of words chosen for the passphrase). See e.g. [https://www.rempe.us/diceware/ Diceware] for more.

See [https://www.iusmentis.com/security/passphrasefaq/ The passphrase FAQ] or [[Wikipedia:Password strength]] for some additional background.

=== Maintaining passwords ===

Once you pick a strong password, be sure to keep it safe. Watch out for [[Wikipedia:Keylogger|keyloggers]] (software and hardware), screen loggers, [[Wikipedia:Social engineering (security)|social engineering]], [[Wikipedia:Shoulder surfing (computer security)|shoulder surfing]], and avoid reusing passwords so insecure servers cannot leak more information than necessary. [[List of applications/Security#Password managers|Password managers]] can help manage large numbers of complex passwords: if you are copy-pasting the stored passwords from the manager to the applications that need them, make sure to clear the copy buffer every time, and ensure they are not saved in any kind of log (e.g. do not paste them in plain terminal commands, which would store them in files like {{ic|.bash_history}}). Note that password managers that are implemented as browser extensions may be vulnerable to [https://www.spookjs.com side channel attacks]. These can be mitigated by using password managers that run as separate applications.

As a rule, do not pick insecure passwords just because secure ones are harder to remember. Passwords are a balancing act. It is better to have an encrypted database of secure passwords, guarded behind a key and one strong master password, than it is to have many similar weak passwords. Writing passwords down is perhaps equally effective [https://www.schneier.com/blog/archives/2005/06/write_down_your.html], avoiding potential vulnerabilities in software solutions while requiring physical security.

Another aspect of the strength of the passphrase is that it must not be easily recoverable from other places.

If you use the same passphrase for disk encryption as you use for your login password (useful e.g. to auto-mount the encrypted partition or folder on login), make sure that {{ic|/etc/shadow}} ends up on an encrypted partition or/and uses a strong key derivation function (i.e. yescrypt/argon2 or sha512 with PBKDF2, but not md5 or low iterations in PBKDF2) for the stored password hash (see [[SHA password hashes]] for more information).

{{Tip|In 2023 Arch Linux switched the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default hashing] algorithm to yescrypt. If you have not customized the default, executing a password change with {{ic|passwd}} is necessary (and sufficient) to apply the new default.}}

If you are backing up your password database, make sure that each copy is not stored behind any other passphrase which in turn is stored in it, e.g. an encrypted drive or an authenticated remote storage service, or you will not be able to access it in case of need; a useful trick is to protect the drives or accounts where the database is backed up using a simple cryptographic hash of the master password. Maintain a list of all the backup locations: if one day you fear that the master passphrase has been compromised you will have to change it immediately on all the database backups and the locations protected with keys derived from the master password.

Version-controlling the database in a secure way can be very complicated: if you choose to do it, you must have a way to update the master password of all the database versions. It may not always be immediately clear when the master password is leaked: to reduce the risk of somebody else discovering your password before you realize that it leaked, you may choose to change it on a periodical basis. If you fear that you have lost control over a copy of the database, you will need to change all the passwords contained in it within the time that it may take to brute-force the master password, according to its entropy.

=== Password hashes ===

A hash is a one-way function, i.e. it is designed to make it impossible to deduct the input without computing the hash function with it (example: MD5, SHA).

A password-hash function is designed to make deducting a user-input (password) impossible without computing the hash function with it (example: bcrypt). A [[Wikipedia:Key derivation function|key derivation function]] (KDF; examples: yescrypt, scrypt, PBKDF2) is a cryptographic algorithm designed to derive secret keys (e.g. an AES key, a password hash) from an input (a master key, a password). Hence, a KDF can serve multiple applications, including those of a password-hash function.

By default, Arch stores the hashed user passwords in the root-only-readable {{ic|/etc/shadow}} file, separated from the other user parameters stored in the world-readable {{ic|/etc/passwd}} file, see [[Users and groups#User database]]. See also [[#Restricting root]].

Passwords are set with the '''passwd''' command, which [[Wikipedia:Key stretching|stretches]] them with the system's crypt function and then saves them in {{ic|/etc/shadow}}. The passwords are also [[Wikipedia:Salt (cryptography)|salted]] in order to defend them against [[Wikipedia:Rainbow table|rainbow table]] attacks. See also [https://www.slashroot.in/how-are-passwords-stored-linux-understanding-hashing-shadow-utils How are passwords stored in Linux (Understanding hashing with shadow utils)].

Since password hashes follow a defined format, the method and parameter can be configured for subsequent new invocations of the ''passwd'' command. Hence, the individual hashes stored in the {{ic|/etc/shadow}} file can be a heterogeneous mix of the hash functions supported by the system.

See {{man|5|crypt}} for more information on the format, hashing methods and parameters.

The {{ic|/etc/login.defs}} file configures the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default password hashing] method {{ic|ENCRYPT_METHOD YESCRYPT}} and its parameter {{ic|YESCRYPT_COST_FACTOR}}.

For example, an increment of the default {{ic|YESCRYPT_COST_FACTOR}} parameter will lead to a logarithmic increase of the compute time required to deduce the hash from a password. This applies, likewise, to a third-party trying to obtain the password secret, and the system to authenticate a user log-in.

In contrast, the compute time for the SHA-512 hash function is configured by a parameter with a linear influence. See [[SHA password hashes]] for information on the previous Arch default. Note the yescrypt algorithm internally uses SHA-256, HMAC and PBKDF2 to compute its password-hash. The main reason is to combine positive attributes of these widely used and tested functions for an enhanced resistance to attacks. For example, the usability of SHA for various purposes has resulted in hardware support for the function, i.e. the performance to compute a pure SHA hash has accelerated considerably, making its application as a password-hash function more and more derelict.

=== Enforcing strong passwords with pam_pwquality ===

PAM stands for the Pluggable Authentication Modules. ''pam_pwquality'' provides protection against [[Wikipedia:Dictionary attack|Dictionary attacks]] and helps configure a password policy that can be enforced throughout the system. It is based on ''pam_cracklib'', so it is backwards compatible with its options.

[[Install]] the {{Pkg|libpwquality}} package.

{{Warning|The ''root'' account is not affected by this policy by default.}}

{{Note|
* You can use the ''root'' account to set a password for a user that bypasses the desired/configured policy. This is useful when setting temporary passwords.
* Current security guidelines around passwords, e.g. from NIST, but also from others, do not recommend enforcing special characters, since they often only lead to predictable alterations.
}}

If for example you want to enforce this policy:

* prompt 2 times for password in case of an error (retry option)
* 10 characters minimum length (minlen option)
* at least 6 characters should be different from old password when entering a new one (difok option)
* at least 1 digit (dcredit option)
* at least 1 uppercase (ucredit option)
* at least 1 lowercase (lcredit option)
* at least 1 other character (ocredit option)
* cannot contain the words "myservice" and "mydomain"
* enforce the policy for root

Edit the {{ic|/etc/pam.d/passwd}} file to read as:

{{bc|1=
#%PAM-1.0
password required pam_pwquality.so retry=2 minlen=10 difok=6 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=-1 [badwords=myservice mydomain] enforce_for_root
password required pam_unix.so use_authtok yescrypt shadow
}}

The {{ic|password required pam_unix.so use_authtok}} instructs the ''pam_unix'' module to not prompt for a password but rather to use the one provided by ''pam_pwquality''.

You can refer to the {{man|8|pam_pwquality}} and {{man|8|pam_unix}} man pages for more information.

== CPU ==

=== Microcode ===

See [[microcode]] for information on how to install important security updates for your CPU's microcode.

=== Hardware vulnerabilities ===

Some CPUs contain hardware vulnerabilities. See the [https://docs.kernel.org/admin-guide/hw-vuln/ kernel documentation on hardware vulnerabilities] for a list of these vulnerabilities, as well as mitigation selection guides to help customize the kernel to mitigate these vulnerabilities for specific usage scenarios.

To check if you are affected by a known vulnerability, run the following:

$ grep -r . /sys/devices/system/cpu/vulnerabilities/

In most cases, updating the kernel and microcode will mitigate vulnerabilities.

==== Simultaneous multithreading (hyper-threading) ====

[[Wikipedia:Simultaneous multithreading|Simultaneous multithreading]] (SMT), also called hyper-threading on Intel CPUs, is a hardware feature that may be a source of [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html L1 Terminal Fault] and [https://docs.kernel.org/admin-guide/hw-vuln/mds.html Microarchitectural Data Sampling] vulnerabilities. The Linux kernel and microcode updates contain mitigations for known vulnerabilities, but [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html#virtualization-with-untrusted-guests disabling SMT may still be required on certain CPUs if untrusted virtualization guests are present].

{{Note|Disabling SMT is something mostly hypervisors benefit from.[https://security.stackexchange.com/questions/219753/sacrificing-30-of-my-cpu-performance-by-disabling-hyper-threading-to-fully-mi/219759#219759] On an ordinary system it has very little to no security benefits.}}

SMT can often be disabled in your system's firmware. Consult your motherboard or system documentation for more information. You can also disable SMT in the kernel by adding the following [[kernel parameter]]:

mitigations=auto,nosmt

== Memory ==

=== Hardened malloc ===

{{AUR|hardened_malloc}} is a hardened replacement for [[Wikipedia:GNU C Library|glibc]]'s malloc(). The project was originally developed for integration into Android's [[Wikipedia:Bionic (software)|Bionic]] and [[Wikipedia:musl|musl]] by Daniel Micay, of [[Wikipedia:GrapheneOS|GrapheneOS]], but he has also built in support for standard Linux distributions on the x86_64 architecture.

== Storage ==

=== Data-at-rest encryption ===

[[Data-at-rest encryption]], preferably full-disk encryption with a [[#Passwords|strong passphrase]], is the only way to guard data against physical recovery. This provides data confidentiality when the computer is turned off or the disks in question are unmounted.

Once the computer is powered on and the drive is mounted, however, its data becomes just as vulnerable as an unencrypted drive. It is therefore best practice to unmount data partitions as soon as they are no longer needed.

You may also [[Trusted Platform Module#LUKS encryption|encrypt a drive with the key stored in a TPM]], although it has had [https://tpm.fail vulnerabilites in the past] and the key can be extracted by a [https://pulsesecurity.co.nz/articles/TPM-sniffing bus sniffing attack].

Certain programs, like [[dm-crypt]], allow the user to encrypt a loop file as a virtual volume. This is a reasonable alternative to full-disk encryption when only certain parts of the system need to be secure.

While the block-device or filesystem-based encryption types compared in the [[data-at-rest encryption]] article are useful at protecting data on physical media, most can not be used to protect data on a remote system that you can not control (such as [[Data-at-rest encryption#Cloud-storage optimized|cloud storage]]). In some cases, individual file encryption will be useful.

These are some methods to encrypt files:

* Some [[Archiving and compression|archiving and compressing]] tools also provide basic encryption. Some examples are [[7-Zip]] ({{ic|-p}} flag), {{Pkg|zip}} ({{ic|-e}} flag). The encryption should only be relied on particular care, because the tools may use custom algorithms for cross-platform compatibility.[https://math.ucr.edu/~mike/zipattacks.pdf]
* [[GnuPG]] can be used to [[GnuPG#Encrypt and decrypt|encrypt files]].
* {{Pkg|age}} is a simple and easy to use file encryption tool. It also supports multiple recipients and encryption using SSH keys, which is useful for secure file sharing.

=== File systems ===

The kernel now prevents security issues related to hardlinks and symlinks if the {{ic|fs.protected_hardlinks}} and {{ic|fs.protected_symlinks}} sysctl switches are enabled, so there is no longer a major security benefit from separating out world-writable directories.

File systems containing world-writable directories can still be kept separate as a coarse way of limiting the damage from disk space exhaustion. However, filling {{ic|/var}} or {{ic|/tmp}} is enough to take down services. More flexible mechanisms for dealing with this concern exist (like [[Disk quota|quotas]]), and some [[file systems]] include related features themselves (Btrfs has quotas on subvolumes).

==== Mount options ====

Following the principle of least privilege, file systems should be mounted with the most restrictive mount options possible (without losing functionality).

Relevant mount options are:

* {{ic|nodev}}: Do not interpret character or block special devices on the file system.
* {{ic|nosuid}}: Do not allow set-user-identifier or set-group-identifier bits to take effect.
* {{ic|noexec}}: Do not allow direct execution of any binaries on the mounted file system.
** Setting {{ic|noexec}} on {{ic|/home}} disallows executable scripts and breaks [[Wine]], [[Steam]], PyCharm, [[.NET]], etc.
*** Wine does not need the {{ic|exec}} flag for opening Windows binaries. It is only needed when Wine itself is installed in {{ic|/home}}.
*** To keep [[Steam]] working you can mount {{ic|/home/user/.local/share/Steam}} as {{ic|exec}} in [[fstab]] by adding the following: {{bc|/home/user/.local/share/Steam /home/user/.local/share/Steam none defaults,bind,user,exec,nofail 0 0}}
** Some packages (building {{Pkg|nvidia-open-dkms}} for example) may require {{ic|exec}} on {{ic|/var}}.

File systems used for data should always be mounted with {{ic|nodev}}, {{ic|nosuid}} and {{ic|noexec}}.

Potential file system mounts to consider:

* {{ic|/var}}
* {{ic|/home}}
* {{ic|/dev/shm}}
* {{ic|/tmp}}
* {{ic|/boot}}

{{Tip|When using [[systemd#GPT partition automounting|GPT partition automounting]], the ESP and XBOOTLDR partitions are [https://github.com/systemd/systemd-stable/commit/49804cfb71d3a79f433096e4cfb5616980171336 always hardened] with {{ic|noexec,nosuid,nodev}}.}}

==== Snapshots ====

When utilizing file system snapshots, e.g. with [[Btrfs]], [[LVM]], or [[ZFS]], it is essential to be aware that snapshots may retain sensitive information that users expect to be deleted. This is especially true when automatic snapshotting tools like [[Snapper]] are configured, as they can capture snapshots at regular intervals or in response to system events. Here are some examples of how sensitive information in {{ic|/home/}} can persist within snapshots:

* ''Deleted files and directories'': Even though files or directories are deleted from the file system, they may still exist within older snapshots. This is expected most of the time, but consider whether files and directories such as {{ic|.local/share/Trash/}}, {{ic|.history}}, etc. should be retained.
* ''Temporary files and cache'': Temporary files and cached data generated by applications may be included in snapshots. For example, files kept in encrypted directories might generate thumbnails ({{ic|.cache/thumbnails}}) or work copies when opened, which might in turn be included in snapshots. The same applies e.g. to browsing history ({{ic|.mozilla/}}, {{ic|.config/chromium/}}, etc.), which could have been included in a snapshot before being purged.

If this is supported, consider excluding such directories from snapshots altogether. For example, if using [[Btrfs]], you can create subvolumes for example {{ic|.cache/}}, {{ic|.config/}}, {{ic|.local/}}, {{ic|.var/}} or any other directory according to your use-case.

{{Note|Moving {{ic|.local/share/Trash}} to a separate subvolume might break the trash feature in some cases, e.g. with [[GNOME/Files]].}}

=== File access permissions ===

{{Accuracy|{{ic|chmod go-r}} does not "take away all permissions", it only removes the read permission.}}

The default [[file permissions]] allow read access to almost everything and changing the permissions can hide valuable information from an attacker who gains access to a non-root account such as the {{ic|http}} or {{ic|nobody}} users. You can use [[chmod]] to take away all permissions from the group and others:

# chmod go-r ''path_to_hide''

{{Warning|Do not apply this broadly. Try this for one config at a time, ensuring that it is worth hiding, and that it will not break program functionality. You may need to remove the {{ic|g}} from the command (or re-add the permission with {{ic|chmod g+r ''path''}} if already ran) if the group is relied on.}}

Some paths to consider are:

* {{ic|/boot}}: The [[Partitioning#/boot|boot directory]], which may include traditional [[vmlinuz]] and [[initramfs]] images, or a [[Unified kernel image]]. Note that safe permissions are used by default when using [[systemd#GPT partition automounting]].
* {{ic|/etc/nftables.conf}}: The [[nftables]] configuration, applicable to {{Pkg|nftables}} and {{Pkg|iptables}}.
* {{ic|/etc/iptables}}: The legacy [[iptables]] configuration, applicable to {{Pkg|iptables-legacy}}.

The default [[umask]] {{ic|0022}} can be changed to improve security for newly created files. The [https://apps.nsa.gov/iaarchive/library/ia-guidance/security-configuration/operating-systems/guide-to-the-secure-configuration-of-red-hat-enterprise.cfm NSA RHEL5 Security Guide] suggests a umask of {{ic|0077}} for maximum security, which makes new files not readable by users other than the owner. To change this, see [[Umask#Set the mask value]]. If you use [[sudo]], consider configuring it to use the [[Sudo#Permissive umask|default root umask]].

=== SUID and SGID files ===

It is important to be aware of any files with the [[Wikipedia:Setuid|Setuid]] or Setgid bit. Examples of relevant files with the SUID bit set:

* [[PAM|unix_chkpwd]]
* chage, expiry, gpasswd, groupmems, [[passwd]], sg ({{Pkg|shadow}})
* [[FUSE|fusermount3]], fusermount2
* [[polkit|pkexec]]
* [[OpenSSH|ssh-keysign]]
* chfn, chsh, mount, newgrp, umount, wall, write ({{Pkg|util-linux}})
* [[sudo]], {{Pkg|sudo-rs}}, [[doas]], [[su]], su-rs, [[Kerberos|ksu]]
* [[firejail]]
* [[Dbus|dbus-daemon-launch-helper]]
* [[Chromium|chromium-sandbox]]
* [[Xorg|Xorg.wrap]]

The prominent risks of such executable files include privilege escalation vulnerabilities, see e.g [[Wikipedia:Setuid#Security impact]].[https://www.cvedetails.com/vulnerability-list/vendor_id-16224/product_id-36412/Calibre-ebook-Calibre.html][https://www.cvedetails.com/product/32625/Sudo-Project-Sudo.html?vendor_id=15714][https://www.cvedetails.com/vulnerability-list/vendor_id-16191/Firejail-Project.html]

Files with the SUID bit set and not owned by root, or files with the SGID bit set ''typically'' have less potential impact but can theoretically still do decent damage if vulnerable. It is usually possible to avoid using SUID or SGID by assigning [[Capabilities]] instead.

{{Tip|It is vital to be vigilant in keeping packages which provide SUID/SGID executables up to date in order to prevent having a vulnerable system.}}

To search for files with either the SUID or SGID bit:

$ find / -perm "/u=s,g=s" -type f 2>/dev/null

=== Backups ===

{{Merge|System backup|There is a dedicated page for system backups.}}

Regularly create backups of important data. Regularly test the integrity of the backups. Regularly test that the backups can be restored.

Make sure that at least one copy of the data is stored offline, i.e. not connected to the system under threat in any way. [[Wikipedia:Ransomware|Ransomware]] and other destructive attacks may also attack any connected backup systems.

=== SATA SSD frozen mode ===

See [[Solid state drive#Setting the SATA SSD state to frozen mode after waking up from sleep]].

== User setup ==

=== Do not use the root account for daily use ===

Following the principle of least privilege, do not use the root user for daily use. Create a non-privileged user account for each person using the system. See [[List of applications/Security#Privilege elevation]] for ways of temporarily gaining privileged access.

=== Enforce a delay after a failed login attempt ===

Add the following line to {{ic|/etc/pam.d/system-login}} to add a delay of at least 4 seconds between failed login attempts:

{{hc|/etc/pam.d/system-login|2=
auth optional pam_faildelay.so delay=4000000
}}

{{Note|This line needs to be the first line in the file.}}

{{ic|4000000}} is the time in microseconds to delay.

Other PAM modules besides {{ic|pam_faildelay}} can also suggest such a delay; if multiple modules do so, PAM will use the longest one.

In particular, both {{ic|pam_unix}} and {{ic|pam_faillock}} set a minimum delay of 2 seconds by default.
In order to completely remove this delay, you need to add the {{ic|nodelay}} parameter to any {{ic|auth}} lines of these modules, for example
{{hc|/etc/pam.d/system-auth|2=
auth [success{{=}}1 default{{=}}bad] pam_unix.so try_first_pass nullok nodelay
}}

=== Lock out user after three failed login attempts ===

Since {{Pkg|pambase}} 20200721.1-2, {{ic|pam_faillock.so}} is enabled by default to lock out users for 10 minutes after 3 failed login attempts in a 15 minute period (see {{Bug|67644}}). The lockout only applies to password authentication (e.g. login and ''sudo''), public key authentication over SSH is still accepted. To prevent complete denial-of-service, this lockout is disabled for the root user by default.

To unlock a user, do:

$ faillock --user ''username'' --reset

By default, the lock mechanism is a file per-user located at {{ic|/run/faillock/}}. Deleting or emptying the file unlocks that user—the directory is owned by root, but the file is owned by the user, so the {{ic|faillock}} command only empties the file, therefore does not require root.

The module {{ic|pam_faillock.so}} can be configured with the file {{ic|1=/etc/security/faillock.conf}}. The lockout parameters:

* {{ic|unlock_time}} — the lockout time (in seconds, default 10 minutes).
* {{ic|fail_interval}} — the time in which failed logins can cause a lockout (in seconds, default 15 minutes).
* {{ic|deny}} — the number of failed logins before lockout (default 3).

{{Tip|The primary purpose for the lockout is to slow down brute-force attacks so that they become infeasible. Hence, if lockouts due to mistyping of passwords become too frequent, relaxing the number of attempts may be preferred to reducing the lockout time.}}

{{Note|{{ic|1=deny = 0}} will disable the lockout mechanism entirely.}}

By default, all user locks are lost after reboot. If your attacker can reboot the machine, it is more secure if locks persist. To make locks persist, change the {{ic|dir}} parameter in {{ic|1=/etc/security/faillock.conf}} to {{ic|/var/lib/faillock}}.

No restart is required for changes to take effect. See {{man|5|faillock.conf}} for further configuration options, such as enabling lockout for the root account, disabling for centralized login (e.g. LDAP), etc.

{{Note|If you make locks persistant, following the changes introduced in polkit 127: you may have to relax the sandbox of its helper agent in order to keep it functional. The best way is to create a drop-in for its systemd unit via {{ic|systemctl edit polkit-agent-helper\@.service}} and add:

[Service]
ReadWritePaths{{=}}/var/lib/faillock
}}

=== Limit amount of processes ===

On systems with many, or untrusted users, it is important to limit the number of processes each can run at once, therefore preventing [[Wikipedia:Fork bomb|fork bombs]] and other denial of service attacks. The {{ic|/etc/security/limits.conf}} configuration determines how many processes each user, or group can have open, and is empty (except for useful comments) by default. Adding the following lines to this file will limit all users to 100 active processes, unless they use the {{ic|prlimit}} command to explicitly raise their maximum to 200 for that session. These values can be changed according to the appropriate number of processes a user should have running, or the hardware of the box you are administrating.

* soft nproc 100
* hard nproc 200

The current number of threads for each user can be found with {{ic|ps --no-headers -Leo user {{!}} sort {{!}} uniq --count}}. This may help with determining appropriate values for the users' limits; see also [[limits.conf]].

=== Use Wayland ===

Prefer using [[Wayland]] over [[Xorg]]. Xorg's design predates modern security practices and is [https://security.stackexchange.com/questions/4641/why-are-people-saying-that-the-x-window-system-is-not-secure/4646#4646 considered insecure] by many. For example, Xorg applications may record keystrokes while inactive.

If you must run Xorg, it is recommended to [[Xorg#Rootless Xorg|avoid running it as root]]. Within Wayland, the Xwayland compatibility layer will automatically use rootless Xorg.

== Restricting root ==

The root user is, by definition, the most powerful user on a system. It is also difficult to [[audit]] the root user account. It is therefore important to restrict usage of the root user account as much as possible. There are a number of ways to keep the power of the root user while limiting its ability to cause harm.

=== Use sudo instead of su ===

Using [[sudo]] for privileged access is preferable to [[su]] for a number of reasons:

* It keeps a log of which normal privilege user has run each privileged command.
* The root user password need not be given out to each user who requires root access.
* {{ic|sudo}} prevents users from accidentally running commands as ''root'' that do not need root access, because a full root terminal is not created. This aligns with the [[Wikipedia:Principle of least privilege|principle of least privilege]].
* Individual programs may be enabled per user, instead of offering complete root access just to run one command.

See [[Sudo#Configuration]].

==== Editing files using sudo ====

See [[Sudo#Editing files]]. Alternatively, you can use editors like {{ic|rvim}} or {{ic|rnano}} which have restricted capabilities in order to be safe to run as root.

=== Restricting root login ===

Once [[sudo]] is properly configured, full root access can be heavily restricted or denied without losing much usability. To disable root, but still allowing to use [[sudo]], you can use {{man|1|passwd}} with {{ic|passwd --lock root}}.

==== Allow only certain users ====

The [[PAM]] {{ic|pam_wheel.so}} lets you allow only users in the group {{ic|wheel}} to login using [[su]]. See [[su#su and wheel]].

==== Denying SSH login ====

Even if you do not wish to deny root login for local users, it is always good practice to [[OpenSSH#Deny|deny root login via SSH]]. The purpose of this is to add an additional layer of security before a user can completely compromise your system remotely.

==== Specify acceptable login combinations with access.conf ====

{{Warning|If you are using GNOME 49 or later, you should make sure the group ''gdm'' can log in locally. This can be done with a {{ic|+:(gdm):LOCAL}} rule. [https://gitlab.gnome.org/GNOME/gdm/-/issues/1021]}}

When someone attempts to log in with [[PAM]], {{ic|/etc/security/access.conf}} is checked for the first combination that matches their login properties. Their attempt then fails or succeeds based on the rule for that combination.

+:root:LOCAL
-:root:ALL

Rules can be set for specific groups and users. In this example, the user archie is allowed to login locally, as are all users in the wheel and adm groups. All other logins are rejected:

+:archie:LOCAL
+:(wheel):LOCAL
+:(adm):LOCAL
-:ALL:ALL

Read more at {{man|5|access.conf}}

== Mandatory access control ==

[[Wikipedia:Mandatory Access Control|Mandatory access control]] (MAC) is a type of security policy that differs significantly from the [[Wikipedia:Discretionary Access Control|discretionary access control]] (DAC) used by default in Arch and most Linux distributions. MAC essentially means that every action a program could perform that affects the system in any way is checked against a security ruleset. This ruleset, in contrast to DAC methods, cannot be modified by users. Using virtually any mandatory access control system will significantly improve the security of your computer, although there are differences in how it can be implemented.

=== Pathname MAC ===

Pathname-based access control is a simple form of access control that offers permissions based on the path of a given file. The downside to this style of access control is that permissions are not carried with files if they are moved around the system. On the positive side, pathname-based MAC can be implemented on a much wider range of filesystems, unlike labels-based alternatives.

* [[AppArmor]] is a [[Wikipedia:Canonical (company)|Canonical]]-maintained MAC implementation seen as an "easier" alternative to SELinux.
* [[TOMOYO]] is another simple, easy-to-use system offering mandatory access control. It is designed to be both simple in usage and in implementation, requiring very few dependencies.

=== Labels MAC ===

Labels-based access control means the extended attributes of a file are used to govern its security permissions. While this system is arguably more flexible in its security offerings than pathname-based MAC, it only works on filesystems that support these extended attributes.

* [[SELinux]], based on an [[Wikipedia:NSA|NSA]] project to improve Linux security, implements MAC completely separate from system users and roles. It offers an extremely robust multi-level MAC policy implementation that can easily maintain control of a system that grows and changes past its original configuration.

=== Access Control Lists ===

[[Access Control Lists]] (ACLs) are an alternative to attaching rules directly to the filesystem in some way. ACLs implement access control by checking program actions against a list of permitted behavior.

== Kernel hardening ==

=== Kernel self-protection / exploit mitigation ===

The {{pkg|linux-hardened}} package uses a [https://github.com/anthraxx/linux-hardened basic kernel hardening patch set] and more security-focused compile-time configuration options than the {{pkg|linux}} package. A custom build can be made to choose a different compromise between security and performance than the security-leaning defaults.

However, it should be noted that several packages (such as {{pkg|throttled}}) will not work when using this kernel.

If you use an out-of-tree driver such as [[NVIDIA]], you may need to switch to its [[DKMS]] package.

==== Userspace ASLR comparison ====

The {{pkg|linux-hardened}} package provides an improved implementation of Address Space Layout Randomization for userspace processes. The {{pkg|paxtest}} command can be used to obtain an estimate of the provided entropy:

===== 64-bit processes =====

{{hc|linux-hardened 5.4.21.a-1-hardened|
Anonymous mapping randomization test : 32 quality bits (guessed)
Heap randomization test (ET_EXEC) : 40 quality bits (guessed)
Heap randomization test (PIE) : 40 quality bits (guessed)
Main executable randomization (ET_EXEC) : 32 quality bits (guessed)
Main executable randomization (PIE) : 32 quality bits (guessed)
Shared library randomization test : 32 quality bits (guessed)
VDSO randomization test : 32 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 40 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 40 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 44 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 44 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 34 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 34 quality bits (guessed)
Randomization under memory exhaustion @~0: 32 bits (guessed)
Randomization under memory exhaustion @0 : 32 bits (guessed)
}}

{{hc|linux 5.5.5-arch1-1|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 20 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 29 bits (guessed)
Randomization under memory exhaustion @0 : 29 bits (guessed)
}}

{{hc|linux-lts 4.19.101-1-lts|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 19 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 28 bits (guessed)
Randomization under memory exhaustion @0 : 28 bits (guessed)
}}

===== 32-bit processes (on an x86_64 kernel) =====

{{hc|linux-hardened|
Anonymous mapping randomization test : 16 quality bits (guessed)
Heap randomization test (ET_EXEC) : 22 quality bits (guessed)
Heap randomization test (PIE) : 27 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 18 quality bits (guessed)
Shared library randomization test : 16 quality bits (guessed)
VDSO randomization test : 16 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 24 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 24 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 28 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 28 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 18 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 16 quality bits (guessed)
Randomization under memory exhaustion @~0: 18 bits (guessed)
Randomization under memory exhaustion @0 : 18 bits (guessed)
}}

{{hc|linux|
Anonymous mapping randomization test : 8 quality bits (guessed)
Heap randomization test (ET_EXEC) : 13 quality bits (guessed)
Heap randomization test (PIE) : 13 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 8 quality bits (guessed)
Shared library randomization test : 8 quality bits (guessed)
VDSO randomization test : 8 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 19 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 19 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 11 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 11 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 8 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 13 quality bits (guessed)
Randomization under memory exhaustion @~0: No randomization
Randomization under memory exhaustion @0 : No randomization
}}

=== Restricting access to kernel pointers in the proc filesystem ===

Setting {{ic|kernel.kptr_restrict}} to 1 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} from regular users without {{ic|CAP_SYSLOG}}, making it more difficult for kernel exploits to resolve addresses/symbols dynamically. This will not help that much on a pre-compiled Arch Linux kernel, since a determined attacker could just download the kernel package and get the symbols manually from there, but if you are compiling your own kernel, this can help mitigating local root exploits. This will break some {{Pkg|perf}} commands when used by non-root users (but many {{Pkg|perf}} features require root access anyway). See {{Bug|34323}} for more information.

Setting {{ic|kernel.kptr_restrict}} to 2 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} regardless of privileges.

{{hc|/etc/sysctl.d/51-kptr-restrict.conf|2=
kernel.kptr_restrict = 1
}}

{{Note|{{pkg|linux-hardened}} sets {{ic|1=kptr_restrict=2}} by default rather than {{ic|0}}.}}

=== BPF hardening ===

BPF is a system used to load and execute bytecode within the kernel dynamically during runtime. It is used in a number of Linux kernel subsystems such as networking (e.g. XDP, tc), tracing (e.g. kprobes, uprobes, tracepoints) and security (e.g. seccomp). It is also useful for advanced network security, performance profiling and dynamic tracing.

BPF was originally an acronym of [[Wikipedia:Berkeley Packet Filter|Berkeley Packet Filter]] since the original classic BPF was used for packet capture tools for BSD. This eventually evolved into Extended BPF (eBPF), which was shortly afterwards renamed to just BPF (not an acronym). BPF should not be confused with packet filtering tools like iptables or netfilter, although BPF can be used to implement packet filtering tools.

BPF code may be either interpreted or compiled using a [[Wikipedia:Just-in-time compilation|Just-In-Time (JIT) compiler]]. The Arch kernel is built with {{ic|CONFIG_BPF_JIT_ALWAYS_ON}} which disables the BPF interpreter and forces all BPF to use JIT compilation. This makes it harder for an attacker to use BPF to escalate attacks that exploit SPECTRE-style vulnerabilities. See [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=290af86629b25ffd1ed6232c4e9107da031705cb the kernel patch which introduced CONFIG_BPF_JIT_ALWAYS_ON] for more details.

The kernel includes a hardening feature for JIT-compiled BPF which can mitigate some types of JIT spraying attacks at the cost of performance and the ability to trace and debug many BPF programs. It may be enabled by setting {{ic|net.core.bpf_jit_harden}} to {{ic|1}} (to enable hardening of unprivileged code) or {{ic|2}} (to enable hardening of all code).

See the {{ic|net.core.bpf_*}} settings in the [https://docs.kernel.org/admin-guide/sysctl/net.html kernel documentation] for more details.

{{Tip|
* {{Pkg|linux-hardened}} sets {{ic|1=net.core.bpf_jit_harden=2}} by default rather than {{ic|0}}.
* By default, BPF programs can be run even by unprivileged users. To change that behaviour set {{ic|1=kernel.unprivileged_bpf_disabled=1}}[https://access.redhat.com/security/cve/cve-2021-33624].
}}

=== ptrace scope ===

The {{man|2|ptrace}} syscall provides a means by which one process (the "tracer") may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. {{ic|ptrace}} is commonly used by debugging tools including ''gdb'', ''strace'', ''perf'', ''reptyr'' and other debuggers. However, it also provides a means by which a malicious process can read data from and take control of other processes.

Arch enables the [https://docs.kernel.org/admin-guide/LSM/Yama.html Yama LSM] by default, which provides a {{ic|kernel.yama.ptrace_scope}} [[kernel parameter]]. This parameter is set to {{ic|1}} (restricted) by default which prevents tracers from performing a {{ic|ptrace}} call on traces outside of a restricted scope unless the tracer is privileged or has the {{ic|CAP_SYS_PTRACE}} [[Capabilities|capability]]. This is a significant improvement in security compared to the classic permissions. Without this module, there is no separation between processes running as the same user (in the absence of additional security layers such as {{man|7|pid_namespaces}}).

{{Note|By default, you can still use tools which require {{ic|ptrace}} by running them as privileged processes, e.g. using [[sudo]].}}

If you do not need to use debugging tools, consider setting {{ic|kernel.yama.ptrace_scope}} to {{ic|2}} (admin-only) or {{ic|3}} (no {{ic|ptrace}} possible) to harden the system.

{{Note|Some anti-cheat and DRM implementations rely on {{ic|ptrace}} to work, including Easy Anti-Cheat and Ubisoft Connect under Wine. Setting this parameter to {{ic|2}} or higher might prevent games using these solutions from launching.}}

=== hidepid ===

{{Expansion|1=[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0fb5ce62c5920b6e0a8a061f2fe80e0403281e10 Linux 5.8 implemented private instances] and new values for {{ic|1=hidepid=}}.}}

{{Accuracy|Enabling {{ic|hidepid}} globally is not a supported way of operation by [[systemd]], nor does it have any practical improvements security-wise when systemd is running as service manager. [https://github.com/systemd/systemd/issues/29893#issuecomment-1798030108]}}

{{Warning|
* This may cause issues for certain applications like an application running in a sandbox and [[Xorg]] (see workaround).
* This causes issues with [[D-Bus]], [[Polkit]], [[PulseAudio]] and [[bluetooth]] when using {{Pkg|systemd}} > 237.64-1.
}}

The kernel has the ability to hide other users' processes, normally accessible via {{ic|/proc}}, from unprivileged users by mounting the {{ic|proc}} filesystem with the {{ic|1=hidepid=}} and {{ic|1=gid=}} options documented in https://docs.kernel.org/filesystems/proc.html.

This greatly complicates an intruder's task of gathering information about running processes, whether some daemon runs with elevated privileges, whether other user runs some sensitive program, whether other users run any program at all, makes it impossible to learn whether any user runs a specific program (given the program does not reveal itself by its behaviour), and, as an additional bonus, poorly written programs passing sensitive information via program arguments are now protected against local eavesdroppers.

The {{ic|proc}} [[Users and groups#System groups|group]], provided by the {{Pkg|filesystem}} package, acts as a whitelist of users authorized to learn other users' process information. If users or services need access to {{ic|/proc/<pid>}} directories beyond their own, [[Users and groups#Group management|add them to the group]].

For example, to hide process information from other users except those in the {{ic|proc}} group:

{{hc|/etc/fstab|2=
proc /proc proc nosuid,nodev,noexec,hidepid=2,gid=proc 0 0
}}

For user sessions to work correctly, an exception needs to be added for ''systemd-logind'':

{{hc|/etc/systemd/system/systemd-logind.service.d/hidepid.conf|2=
[Service]
SupplementaryGroups=proc
}}

=== Restricting module loading ===

The default Arch kernel has {{ic|CONFIG_MODULE_SIG_ALL}} enabled, which signs all kernel modules built as part of the {{Pkg|linux}} package. This allows the kernel to only load modules signed with a valid key, i.e. out-of-tree modules compiled locally or provided by packages such as {{Pkg|virtualbox-host-modules-arch}} cannot be loaded. You can use {{ic|1=modinfo}} to verify currently loaded modules have signatures; verifying the signatures by hand is slightly more involved [https://unix.stackexchange.com/a/496800].

Kernel module loading can be restricted by setting the {{ic|1=module.sig_enforce=1}} [[kernel parameter]]. More information can be found in the [https://docs.kernel.org/admin-guide/module-signing.html kernel documentation].

Further, unneeded individual modules can be [[blacklist]]ed, see [https://github.com/secureblue/secureblue/blob/live/files/system/usr/lib/modprobe.d/secureblue.conf secureblue] for examples.

=== Disable kexec ===

Kexec allows replacing the current running kernel.

{{hc|/etc/sysctl.d/51-kexec-restrict.conf|2=
kernel.kexec_load_disabled = 1
}}

{{Tip|kexec is disabled by default in {{pkg|linux-hardened}}.}}

=== Kernel lockdown mode ===

Linux supports an optional [https://mjg59.dreamwidth.org/55105.html lockdown feature], intended to strengthen the boundary between UID 0 (root) and the kernel. When enabled some applications may cease to work which rely on low-level access to either hardware or the kernel.

To use lockdown, its LSM must be initialized and a lockdown mode must be set.

All [[Kernel#Officially supported kernels|officially supported kernels]] initialize the LSM, but none of them enforce any lockdown mode.

{{Tip|Initialized LSMs can be verified by running {{ic|cat /sys/kernel/security/lsm}}.}}

Lockdown has two modes of operation:

* {{ic|integrity}}: kernel features that allow userland to modify the running kernel are disabled (e.g. kexec, bpf).
* {{ic|confidentiality}}: kernel features that allow userland to extract confidential information from the kernel are also disabled.

It is recommended to use {{ic|integrity}}, unless your specific threat model dictates otherwise.

To enable kernel lockdown at runtime, run:

# echo ''mode'' > /sys/kernel/security/lockdown

To enable kernel lockdown on boot, use the [[kernel parameter]] {{ic|1=lockdown=''mode''}}.

{{Note|
* Kernel lockdown cannot be disabled at runtime.
* Kernel lockdown disables [[hibernation]].
* Versions <6.17 of the {{man|7|kernel_lockdown}} man page incorrectly state that "lockdown will be automatically enabled if the system boots in EFI Secure Boot mode". This is not the behaviour of the upstream kernel, nor Arch's packaged [[kernel]]s.
}}

See also {{man|7|kernel_lockdown}}.

=== Linux Kernel Runtime Guard (LKRG) ===

[https://www.openwall.com/lkrg/ LKRG] ({{AUR|lkrg-dkms}}) is a kernel module which performs integrity checking of the kernel and detection of exploit attempts.

=== Disable emergency shell ===

{{Accuracy|Masking {{ic|emergency.target}} and {{ic|emergency.service}} will have no effect on those units being added to the initramfs and run in early userspace. Even with them in the initramfs, mkinitcpio's systemd hook locks the root account[https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/292cdf8a2f7dd7c6c7d91d2b59617391935c837c][https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/8835b2f5dfbe8663f1a2fd08edbd35f90bf08691] for "security reasons" (see {{Bug|70408}}). The solution for the issue in the linked article, if even needed, would be to prevent {{ic|rescue.target}}, {{ic|rescue.service}}, {{ic|emergency.target}} and {{ic|emergency.service}} from being added to the initramfs image.}}

The emergency shell is used to interactively troubleshoot the machine during the boot process. However, it is also a gadget that an attacker can use to access secure resources such as the TPM. See [https://pulsesecurity.co.nz/advisories/tpm-luks-bypass this article] for a practical example. The difficulty of attacks can be increased by disabling the emergency shell, at the tradeoff of removing a tool to troubleshoot early boot failures.

To disable the emergency shell, See [[systemd#Disable emergency mode on remote machine]].

== Sandboxing applications ==

See also [[Wikipedia:Sandbox (computer security)]].

To improve the security of systemd service units, see [[systemd/Sandboxing]].

{{Warning|Unprivileged user namespace usage is enabled by default in all [[Kernel#Officially supported kernels|officially supported kernels]] except for {{Pkg|linux-hardened}}. Unprivileged user namespaces greatly increase the attack surface for local privilege escalation; see [https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction AppArmor's Wiki] and {{Bug|36969}}.}}

To mitigate this, either:

* use the {{Pkg|linux-hardened}} kernel which has the safe default, or
* set the {{ic|kernel.unprivileged_userns_clone}} [[sysctl]] to {{ic|0}}.

Note that this can break applications such as {{pkg|nsjail}}. [[Chromium]] based applications need SUID bit for {{ic|chrome-sandbox}} to work with this setting.

=== Firejail ===

[[Firejail]] is an easy to use tool for sandboxing applications and servers alike. It was originally created for browsers and internet facing applications, but supports a large number of applications by now. To establish a sandboxed environment with a variety of features, it is installed as a suid binary and builds a sandboxed runtime environment for the target application based on black and white lists.

=== bubblewrap ===

[[bubblewrap]] is a sandbox application developed for unprivileged container tools like [[Flatpak]] with a significantly smaller resource footprint and complexity than Firejail. While it lacks certain features such as file path whitelisting, bubblewrap does offer bind mounts as well as the creation of user/IPC/PID/network/cgroup namespaces and can support both simple and complex sandboxes. For the {{Pkg|linux-hardened}} kernel you will need to to use {{Pkg|bubblewrap-suid}}.

[[Bubblejail]] sandbox is based on [[bubblewrap]] and provides a resource oriented permission model with a graphical interface to tweak permissions.

=== Portable ===

[https://github.com/Kraftland/portable Portable] is a sandboxing framework which utilizes [[bubblewrap]] and many other tools to lockdown running applications. It is designed to be simple for packagers and efficient for users, yet cuts off security holes and monitors background processes by default.

See [https://github.com/Kraftland/portable-arch portable-arch] for a repository of applications sandboxed by portable.

If a sandboxed application does not utilize the Portal file chooser, portable can pass files to the sandbox (by passing {{ic|--actions share-files}}).

Portable is fully functional on GNOME, while other desktops may lack small amounts of features like advanced background monitoring and ScreenShot portal.

=== chroots ===

Manual [[chroot]] jails can also be constructed to build sandboxed process environments. It is much more limited than other sandboxing technologies; the extent of its sandboxing is file path isolation.

=== Linux containers ===

[[Linux Containers]] are another good option when you need more separation than the other options (short of [[#Full virtualization options|full system virtualization]]) provide. LXC is run on top of the existing kernel in a pseudo-chroot with their own virtual hardware.

=== gVisor ===

The [https://gvisor.dev/ gVisor] project, led by Google, is providing a sandboxing application with a focus on containers following the [https://opencontainers.org/ OCI initiative], such as [[Docker]] and [[Kubernetes]]. It isolates containers and individual applications from the host by intercepting a majority of system calls to the kernel and presenting itself as guest kernel.

A key difference to other intercepting sandboxing projects is that gVisor re-implements system calls in the Go programming language, as described in its [https://gvisor.dev/docs/architecture_guide/intro/ design overview]. Details for the list of [https://gvisor.dev/docs/user_guide/compatibility/linux/amd64/ re-implemented syscalls support] can be seen in [https://github.com/google/gvisor/blob/master/pkg/sentry/syscalls/linux/linux64.go git]. For usage examples, limitations and special features see the project [https://gvisor.dev/docs/ documentation].

The application is available as {{Aur|gvisor-git}} and {{Aur|gvisor-bin}}.

=== Full virtualization options ===

Using full virtualization options such as [[VirtualBox]], [[KVM]], [[Xen]] or [https://www.qubes-os.org/ Qubes OS] (based on Xen) can also improve isolation and security in the event you plan on running risky applications or browsing dangerous websites.

== Network and firewalls ==

=== Firewalls ===

While the stock Arch kernel is capable of using [[Wikipedia:Netfilter|Netfilter]]'s [[iptables]] and [[nftables]], the services are not [[enable]]d by default. It is highly recommended to set up some form of firewall to protect the services running on the system. Many resources (including ArchWiki) do not state explicitly which services are worth protecting, so enabling a firewall is a good precaution.

* See [[iptables]] and [[nftables]] for general information.
* See [[Simple stateful firewall]] for a guide on setting up an iptables firewall.
* See [[:Category:Firewalls]] for other ways of setting up netfilter.
* See [[Ipset]] for blocking lists of ip addresses, such as those from Bluetack.
* {{Pkg|opensnitch}} is a configurable inbound and outbound firewall with support for configurable rules by application, port, host, etc.

A quick way to setup a basic firewall is to use the tool {{ic|ufw}} (Uncomplicated Fire Wall). Then set {{ic|ufw default deny incoming}} and {{ic|ufw default allow outgoing}} and enabling it with {{ic|ufw enable}} and {{ic|systemctl enable ufw}}.

==== Open ports ====

{{Style|"Open ports" is not a good title since it disregards interfaces and addresses that the application may be bound to. From the firewalls' point of view, ports may be "open" even if no application listens on them at the moment.}}

Some services listen for inbound traffic on open network ports. It is important to only bind these services to the addresses and interfaces that are strictly necessary. It may be possible for a remote attacker to [https://samy.pl/slipstream/ exploit flawed network protocols to access exposed services]. This can even happen with [https://nvd.nist.gov/vuln/detail/CVE-2019-13450 processes bound to localhost].

In general, if a service only needs to be accessible to the local system, bind to a Unix domain socket ({{man|7|unix}}) or a loopback address such as {{ic|localhost}} instead of a non-loopback address like {{ic|0.0.0.0/0}}.

If a service needs to be accessible to other systems via the network, control the access with strict [[firewall]] rules and configure authentication, authorization and encryption whenever possible.

You can list all current open ports with {{ic|ss -l}}. To show all '''l'''istening '''p'''rocesses and their '''n'''umeric '''t'''cp and '''u'''dp port numbers:

# ss -lpntu

See {{man|8|ss}} for more options.

=== Kernel parameters ===

Kernel parameters which affect networking can be set using [[Sysctl]]. For how to do this, see [[Sysctl#TCP/IP stack hardening]].

=== SSH ===

To mitigate [[Wikipedia:Brute-force attack|brute-force attacks]] it is recommended to enforce key-based authentication. For OpenSSH see [[OpenSSH#Protection]] for more recommendations. Alternatively [[Fail2ban]] or [[Sshguard]] offer lesser forms of protection by monitoring logs and writing [[firewall]] rules but open up the potential for a denial of service, since an attacker can [[Wikipedia:Spoofing attack#Spoofing and TCP/IP|spoof]] packets as if they came from the administrator after identifying their address. Spoofing IP has lines of defense, such as by [[sysctl#Reverse path filtering|reverse path filtering]] and [[sysctl#Disable ICMP redirects|disabling ICMP redirects]].

You may want to harden authentication even more by using two-factor authentication. [[Google Authenticator]] provides a two-step authentication procedure using one-time passcodes (OTP).

Denying root login is also a good practice, both for tracing intrusions and adding an additional layer of security before root access. For OpenSSH, see [[OpenSSH#Deny]].

Mozilla publishes an [https://infosec.mozilla.org/guidelines/openssh.html OpenSSH configuration guide] which configures more verbose audit logging and restricts ciphers.

=== DNS ===

The default domain name resolution (DNS) configuration is highly compatible but has security weaknesses. See [[Domain name resolution#Privacy and security|DNS privacy and security]] for more information.

=== Proxies ===

Proxies are commonly used as an extra layer between applications and the network, sanitizing data from untrusted sources. The attack surface of a small proxy running with lower privileges is significantly smaller than a complex application running with the end user privileges.

For example the DNS resolver is implemented in {{Pkg|glibc}}, that is linked with the application (that may be running as root), so a bug in the DNS resolver might lead to a remote code execution. This can be prevented by installing a DNS caching server, such as [[dnsmasq]], which acts as a proxy. [https://googleonlinesecurity.blogspot.it/2016/02/cve-2015-7547-glibc-getaddrinfo-stack.html]

=== Managing TLS certificates ===

See [[TLS#Trust management]].

== Physical security ==

Physical access to a computer is root access given enough time and resources. However, a high ''practical'' level of security can be obtained by putting up enough barriers.

An attacker can gain full control of your computer on the next boot by simply attaching a malicious IEEE 1394 (FireWire), Thunderbolt or PCI Express device as they are given full memory access by default.[https://web.archive.org/web/20210312083421/http://breaknenter.org/2014/09/inception-metasploit-integration/] For Thunderbolt, you can restrict the direct memory access completely or to known devices, see [[Thunderbolt#User device authorization|user device authorization]]. For Firewire and PCI Express, there is little you can do from preventing this, or modification of the hardware itself - such as flashing malicious firmware onto a drive. However, the vast majority of attackers will not be this knowledgeable and determined.

[[#Data-at-rest encryption|Data-at-rest encryption]] will prevent access to your data if the computer is stolen, but malicious firmware can be installed to obtain this data upon your next log in by a resourceful attacker.

=== Locking down BIOS ===

Adding a password to the BIOS prevents someone from booting into removable media, which is basically the same as having root access to your computer. You should make sure your drive is first in the boot order and disable the other drives from being bootable if you can.

=== Boot loaders ===

It is highly important to protect your [[boot loader]]. An unprotected boot loader can bypass any login restrictions, e.g. by setting the {{ic|1=init=/bin/sh}} [[kernel parameter]] to boot directly to a shell.

==== Syslinux ====

[[Syslinux]] supports [[Syslinux#Security|password-protecting your boot loader]]. It allows you to set either a per-menu-item password or a global boot loader password.

==== GRUB ====

[[GRUB]] supports boot loader passwords as well. See [[GRUB/Tips and tricks#Password protection of GRUB menu]] for details. It also has support for [[GRUB#Encrypted /boot|encrypted /boot]], which only leaves some parts of the boot loader code unencrypted. GRUB's configuration, [[kernel]] and [[initramfs]] are encrypted.

==== systemd-boot ====

[[systemd-boot]] disables editing of kernel parameters when [[#Secure Boot|Secure Boot]] is enabled. Alternatively, you can set [[systemd-boot#Kernel parameters editor with password protection|kernel parameters for password protection]] in systemd-boot for a more traditional password-based option.

=== Secure Boot ===

[[Secure Boot]] is a feature of [[UEFI]] that allows authentication of the files your computer boots. This helps preventing some [[Wikipedia:Evil maid attack|evil maid attacks]] such as replacing files inside the boot partition. Normally computers come with keys that are enrolled by vendors (OEM). However these can be removed and allow the computer to enter ''Setup Mode'' which allows the user to enroll and manage their own keys.

The secure boot page guides you through how to set secure boot up by [[Unified Extensible Firmware Interface/Secure Boot#Using your own keys|using your own keys]].

=== Trusted Platform Module (TPM) ===

[[Trusted Platform Module|TPMs]] are hardware microprocessors which have cryptographic keys embedded. This forms the fundamental root of trust of most modern computers and allows end-to-end verification of the boot chain. They can be used as internal smartcards, attest the firmware running on the computer and allow users to insert secrets into a tamper-proof and brute-force resistant store.

=== Boot partition on removable flash drive ===

One popular idea is to place the boot partition on a flash drive in order to render the system unbootable without it. Proponents of this idea often use [[#Data-at-rest encryption|full-disk encryption]] alongside, and some also use [[Dm-crypt/Specialties#Encrypted system using a detached LUKS header|detached encryption headers]] placed on the boot partition.

This method can also be merged with [[Dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB|encrypting /boot]].

=== Automatic logout ===

If you are using [[Bash]] or [[Zsh]], you can set {{ic|TMOUT}} for an automatic logout from shells after a timeout.

For example, the following will automatically log out from virtual consoles (but not terminal emulators in X11):

{{hc|/etc/profile.d/shell-timeout.sh|<nowiki>
TMOUT="$(( 60*10 ))";
[ -z "$DISPLAY" ] && export TMOUT;
case $( /usr/bin/tty ) in
/dev/tty[0-9]*) export TMOUT;;
esac
</nowiki>}}

If you really want EVERY Bash/Zsh prompt (even within X) to timeout, use:

$ export TMOUT="$(( 60*10 ))";

Note that this will not work if there is some command running in the shell (eg.: an SSH session or other shell without {{ic|TMOUT}} support). But if you are using VC mostly for restarting frozen GDM/Xorg as root, then this is very useful.

=== Protect against rogue USB devices ===

The kernel has [https://docs.kernel.org/usb/authorization.html settings to deactivate] USB ports to protect your computer against rogue USB devices (a.k.a. [[Wikipedia:BadUSB|BadUSB]], [https://github.com/samyk/poisontap PoisonTap] or [https://lanturtle.com/ LanTurtle]). They can be set at runtime and automated via [[sysctl]].

For more control install [[USBGuard]], which is a software framework implementing basic whitelisting and blacklisting capabilities based on device attributes.

=== Volatile data collection ===

A computer that is powered on may be vulnerable to [https://web.archive.org/web/20210420075636/https://fedvte.usalearning.gov/courses/CSI/course/videos/pdf/CSI_D01_S05_T01_STEP.pdf volatile data collection]. It is a best practice to turn a computer completely off at times it is not necessary for it to be on, or if the computer's physical security is temporarily compromised (e.g. when passing through a security checkpoint).

== Packages ==

=== Authentication ===

[https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html#overview Attacks on package managers] are possible without proper use of package signing, and can affect even package managers with [https://www2.cs.arizona.edu/stork/packagemanagersecurity/faq.html proper signature systems]. Arch uses package signing by default and relies on a web of trust from 5 trusted master keys. See [[Pacman-key]] for details.

=== Upgrades ===

It is important to regularly [[System maintenance#Upgrading the system|upgrade the system]].

=== Follow vulnerability alerts ===

Subscribe to the Common Vulnerabilities and Exposure (CVE) Security Alert updates, made available by National Vulnerability Database, and found on the [https://nvd.nist.gov/download.cfm NVD Download webpage].

The tool {{Pkg|arch-audit}} can be used to check for vulnerabilities affecting the running system. A graphical system tray, {{Pkg|arch-audit-gtk}}, can also be used. See also [[Arch Security Team]].

You should also consider subscribing to the release notifications for software you use, especially if you install software through means other than the main repositories or AUR. Some software have mailing lists you can subscribe to for security notifications. Source code hosting sites often offer RSS feeds for new releases.

=== Rebuilding packages ===

Packages can be rebuilt and stripped of undesired functions and features as a means to reduce attack surface. For example, {{Pkg|bzip2}} can be rebuilt without {{ic|bzip2recover}} in an attempt to circumvent [https://security.archlinux.org/CVE-2016-3189 CVE-2016-3189]. Custom hardening flags can also be applied either manually or via a wrapper.

{{Merge|Arch package guidelines/Security|Security related build flags have their own article.}}

{{Accuracy|Copy-pasted from a 3 years old blog post. The compiler flags are specific to [[GCC]], some are hardly security related.}}

{| class="wikitable"
! Flag !! Purpose
|-
| -D_FORTIFY_SOURCE=2 || Run-time buffer overflow detection
|-
| -D_GLIBCXX_ASSERTIONS || Run-time bounds checking for C++ strings and containers
|-
| -fasynchronous-unwind-tables || Increased reliability of backtraces
|-
| -fexceptions || Enable table-based thread cancellation
|-
| -fpie -Wl,-pie || Full ASLR for executables
|-
| -fpic -shared || No text relocations for shared libraries
|-
| -fplugin=annobin || Generate data for hardening quality control
|-
| -fstack-clash-protection || Increased reliability of stack overflow detection
|-
| -fstack-protector, -fstack-protector-all or -fstack-protector-strong || Stack smashing protector
|-
| -grecord-gcc-switches || Store compiler flags in debugging information
|-
| -mcet -fcf-protection || Control flow integrity protection
|-
| -Werror=format-security || Reject potentially unsafe format string arguments
|-
| -Werror=implicit-function-declaration || Reject missing function prototypes
|-
| -Wl,-z,defs || Detect and reject underlinking
|-
| -Wl,-z,now || Disable lazy binding
|-
| -Wl,-z,relro || Read-only segments after relocation
|}

* [https://developers.redhat.com/blog/2018/03/21/compiler-and-linker-flags-gcc/ Flags and info source]

== See also ==

* [https://security.archlinux.org/ Arch Linux Security Tracker]
* [https://wiki.centos.org/HowTos/OS_Protection CentOS Wiki: OS Protection]
* [https://web.archive.org/web/20210712001756/https://developer.ibm.com/technologies/linux/articles/l-harden-desktop/ Hardening the Linux desktop]
* [https://web.archive.org/web/20190701140035/https://www.ibm.com/developerworks/linux/tutorials/l-harden-server/index.html Hardening the Linux server]
* [https://github.com/lfit/itpol/blob/master/linux-workstation-security.md Linux Foundation: Linux workstation security checklist]
* [https://www.privacyguides.org/ privacyguides.org Privacy Resources]
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/ Red Hat Enterprise Linux 7 Security Guide]
* [https://www.debian.org/doc/manuals/securing-debian-manual/index.en.html Securing Debian Manual]
* [https://web.archive.org/web/20140220055801/http://crunchbang.org:80/forums/viewtopic.php?id=24722 The paranoid #! Security Guide]

Security

2026-05-11T18:57:53Z

Indigo: /* Enforce a delay after a failed login attempt */ remove note template for readability; the previous short note is important to accomplish the configuration, the rest regular supplementary info

[[Category:Security]]
[[Category:File systems]]
[[Category:Networking]]
[[de:Sicherheit]]
[[es:Security]]
[[hu:Security]]
[[ja:セキュリティ]]
[[pt:Security]]
[[ru:Security]]
[[zh-hans:Security]]
{{Related articles start}}
{{Related|Arch Security Team}}
{{Related|General recommendations}}
{{Related|Identity management}}
{{Related|Capabilities}}
{{Related|List of Applications/Security}}
{{Related|Arch package guidelines/Security}}
{{Related articles end}}
This article contains recommendations and best practices for [[Wikipedia:Hardening (computing)|hardening]] an Arch Linux system.

== Concepts ==

* It ''is'' possible to tighten security to the point where the system is unusable. Security and convenience must be balanced. The trick is to create a secure ''and'' useful system.
* The biggest threat is, and will always be, the user.
* The [[Wikipedia:Principle of least privilege|principle of least privilege]]: Each part of a system should only be able to access what is strictly required, and nothing more.
* Defense in depth: Security works better in independent layers. When one layer is breached, another should stop the attack.
* Be a little paranoid. And be suspicious. If anything sounds too good to be true, it probably is!
* You can never make a system 100% secure unless you unplug the machine from all networks, turn it off, lock it in a safe, smother it in concrete and never use it.
* Prepare for failure. Create a plan ahead of time to follow when your security is broken.

== Passwords ==

Passwords are key to a secure system. They secure your [[Users and groups|user accounts]], [[Data-at-rest encryption|encrypted filesystems]], and [[SSH keys|SSH]]/[[GPG]] keys. They are the main way a computer chooses to trust the person using it, so a big part of security is just about picking secure passwords and protecting them.

=== Choosing secure passwords ===

Passwords must be complex enough to not be easily guessed from e.g. personal information, or [[Wikipedia:Password cracking|cracked]] using methods like brute-force attacks. The tenets of strong passwords are based on ''length'' and ''randomness''. In cryptography the quality of a password is often referred to as its [[Wikipedia:Password strength#Entropy as a measure of password strength|entropy]].

Insecure passwords include those containing or those using as a base before substitution/variation:

* Personally identifiable information (e.g., your dog's name, date of birth, area code, favorite video game)
* Simple character substitutions on words (e.g., {{ic|k1araj0hns0n}}), as modern dictionary attacks can easily work with these
* Root "words" or common strings followed or preceded by added numbers, symbols, or characters (e.g., {{ic|DG091101%}})
* Common phrases or short strings of common dictionary words (e.g. {{ic|photocopyhauntbranchexpose}}) including with character substitution (e.g. {{ic|Ph0toc0pyh4uN7br@nch3xp*se}}) (See Diceware below for when a combination of dictionary words can be secure)
* Any of the [[Wikipedia:List of the most common passwords|most common passwords]]

The best choice for a password is something long (the longer, the better) and generated from a random source. It is important to use a long password. [https://www.theregister.com/2019/02/14/password_length Weak hash algorithms allow an 8-character password hash to be compromised in just a few hours.]

Tools like {{Pkg|pwgen}} or {{AUR|apg}} can generate random passwords. However, these passwords can be difficult to memorize. One memorization technique (for ones often typed) is to generate a long password and memorize a minimally secure number of characters, temporarily writing down the full generated string. Over time, increase the number of characters typed - until the password is ingrained in muscle memory and need not be remembered. This technique is more difficult, but can provide confidence that a password will not turn up in wordlists or "intelligent" brute force attacks that combine words and substitute characters.

Apart from password management, {{Pkg|keepassxc}} offers password/passphrase generation. It is possible to customize the generation in a GUI. Dictionary based passphrases are also supported.

One technique for memorizing a password is to use a mnemonic phrase, where each word in the phrase reminds you of the next character in the password.
Take for instance “the girl is walking down the rainy street” could be translated to {{ic|t6!WdtR5}} or, less simply, {{ic|t&6!RrlW@dtR,57}}.
This approach could make it easier to remember a password, but note that the various letters have very different probabilities of being found at the start of words ([[Wikipedia:Letter frequency#Relative frequencies of the first letters of a word in the English language|Wikipedia:Letter frequency]]).

Another effective technique can be to write randomly generated passwords down and store them in a ''safe'' place, such as in a wallet, purse, or document safe. Most people do a generally good job of protecting their physical valuables from attack, and it is easier for most people to understand physical security best practices compared to digital security practices.

It is also very effective to combine the mnemonic and random technique by saving long randomly generated passwords with a [[password manager]], which will be in turn accessed with a memorable "master password"/primary password that must be used only for that purpose. The master password must be memorized and never saved. This requires the password manager to be installed on a system to easily access the password (which could be seen as an inconvenience or a security feature, depending on the situation). Some password managers also have smartphone apps which can be used to display passwords for manual entry on systems without that password manager installed (if that is a common use case, you could still use easily typeable but secure passwords for each service instead of completely random ones, see below). Note that a password manager introduces a single point of failure if you ever forget the master password.
Some password managers compute the contained passwords based on the master password and the service name where you want to log in instead of encrypting them, making it possible to use it on a new system without syncing any data.

It can be effective to use a memorable long series of unrelated words as a password. The theory is that if a sufficiently long phrase is used, the gained entropy from the password's length can counter the lost entropy from the use of dictionary words. This [https://xkcd.com/936/ xkcd comic] demonstrates the entropy tradeoff of this method, taking into account the limited set of possible words for each word in the passphrase. If the set of words you choose from is large (multiple thousand words) and you choose 5-7 or even more random words from it, this method provides great entropy, even assuming the attacker knows the set of possible words chosen from and the number of words chosen. The number of possible passphrases after settling on a set of words and number of words is: (number of words in the set of words to select from) to the power of (the number of words chosen for the passphrase). See e.g. [https://www.rempe.us/diceware/ Diceware] for more.

See [https://www.iusmentis.com/security/passphrasefaq/ The passphrase FAQ] or [[Wikipedia:Password strength]] for some additional background.

=== Maintaining passwords ===

Once you pick a strong password, be sure to keep it safe. Watch out for [[Wikipedia:Keylogger|keyloggers]] (software and hardware), screen loggers, [[Wikipedia:Social engineering (security)|social engineering]], [[Wikipedia:Shoulder surfing (computer security)|shoulder surfing]], and avoid reusing passwords so insecure servers cannot leak more information than necessary. [[List of applications/Security#Password managers|Password managers]] can help manage large numbers of complex passwords: if you are copy-pasting the stored passwords from the manager to the applications that need them, make sure to clear the copy buffer every time, and ensure they are not saved in any kind of log (e.g. do not paste them in plain terminal commands, which would store them in files like {{ic|.bash_history}}). Note that password managers that are implemented as browser extensions may be vulnerable to [https://www.spookjs.com side channel attacks]. These can be mitigated by using password managers that run as separate applications.

As a rule, do not pick insecure passwords just because secure ones are harder to remember. Passwords are a balancing act. It is better to have an encrypted database of secure passwords, guarded behind a key and one strong master password, than it is to have many similar weak passwords. Writing passwords down is perhaps equally effective [https://www.schneier.com/blog/archives/2005/06/write_down_your.html], avoiding potential vulnerabilities in software solutions while requiring physical security.

Another aspect of the strength of the passphrase is that it must not be easily recoverable from other places.

If you use the same passphrase for disk encryption as you use for your login password (useful e.g. to auto-mount the encrypted partition or folder on login), make sure that {{ic|/etc/shadow}} ends up on an encrypted partition or/and uses a strong key derivation function (i.e. yescrypt/argon2 or sha512 with PBKDF2, but not md5 or low iterations in PBKDF2) for the stored password hash (see [[SHA password hashes]] for more information).

{{Tip|In 2023 Arch Linux switched the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default hashing] algorithm to yescrypt. If you have not customized the default, executing a password change with {{ic|passwd}} is necessary (and sufficient) to apply the new default.}}

If you are backing up your password database, make sure that each copy is not stored behind any other passphrase which in turn is stored in it, e.g. an encrypted drive or an authenticated remote storage service, or you will not be able to access it in case of need; a useful trick is to protect the drives or accounts where the database is backed up using a simple cryptographic hash of the master password. Maintain a list of all the backup locations: if one day you fear that the master passphrase has been compromised you will have to change it immediately on all the database backups and the locations protected with keys derived from the master password.

Version-controlling the database in a secure way can be very complicated: if you choose to do it, you must have a way to update the master password of all the database versions. It may not always be immediately clear when the master password is leaked: to reduce the risk of somebody else discovering your password before you realize that it leaked, you may choose to change it on a periodical basis. If you fear that you have lost control over a copy of the database, you will need to change all the passwords contained in it within the time that it may take to brute-force the master password, according to its entropy.

=== Password hashes ===

A hash is a one-way function, i.e. it is designed to make it impossible to deduct the input without computing the hash function with it (example: MD5, SHA).

A password-hash function is designed to make deducting a user-input (password) impossible without computing the hash function with it (example: bcrypt). A [[Wikipedia:Key derivation function|key derivation function]] (KDF; examples: yescrypt, scrypt, PBKDF2) is a cryptographic algorithm designed to derive secret keys (e.g. an AES key, a password hash) from an input (a master key, a password). Hence, a KDF can serve multiple applications, including those of a password-hash function.

By default, Arch stores the hashed user passwords in the root-only-readable {{ic|/etc/shadow}} file, separated from the other user parameters stored in the world-readable {{ic|/etc/passwd}} file, see [[Users and groups#User database]]. See also [[#Restricting root]].

Passwords are set with the '''passwd''' command, which [[Wikipedia:Key stretching|stretches]] them with the system's crypt function and then saves them in {{ic|/etc/shadow}}. The passwords are also [[Wikipedia:Salt (cryptography)|salted]] in order to defend them against [[Wikipedia:Rainbow table|rainbow table]] attacks. See also [https://www.slashroot.in/how-are-passwords-stored-linux-understanding-hashing-shadow-utils How are passwords stored in Linux (Understanding hashing with shadow utils)].

Since password hashes follow a defined format, the method and parameter can be configured for subsequent new invocations of the ''passwd'' command. Hence, the individual hashes stored in the {{ic|/etc/shadow}} file can be a heterogeneous mix of the hash functions supported by the system.

See {{man|5|crypt}} for more information on the format, hashing methods and parameters.

The {{ic|/etc/login.defs}} file configures the [https://archlinux.org/news/changes-to-default-password-hashing-algorithm-and-umask-settings/ default password hashing] method {{ic|ENCRYPT_METHOD YESCRYPT}} and its parameter {{ic|YESCRYPT_COST_FACTOR}}.

For example, an increment of the default {{ic|YESCRYPT_COST_FACTOR}} parameter will lead to a logarithmic increase of the compute time required to deduce the hash from a password. This applies, likewise, to a third-party trying to obtain the password secret, and the system to authenticate a user log-in.

In contrast, the compute time for the SHA-512 hash function is configured by a parameter with a linear influence. See [[SHA password hashes]] for information on the previous Arch default. Note the yescrypt algorithm internally uses SHA-256, HMAC and PBKDF2 to compute its password-hash. The main reason is to combine positive attributes of these widely used and tested functions for an enhanced resistance to attacks. For example, the usability of SHA for various purposes has resulted in hardware support for the function, i.e. the performance to compute a pure SHA hash has accelerated considerably, making its application as a password-hash function more and more derelict.

=== Enforcing strong passwords with pam_pwquality ===

PAM stands for the Pluggable Authentication Modules. ''pam_pwquality'' provides protection against [[Wikipedia:Dictionary attack|Dictionary attacks]] and helps configure a password policy that can be enforced throughout the system. It is based on ''pam_cracklib'', so it is backwards compatible with its options.

[[Install]] the {{Pkg|libpwquality}} package.

{{Warning|The ''root'' account is not affected by this policy by default.}}

{{Note|
* You can use the ''root'' account to set a password for a user that bypasses the desired/configured policy. This is useful when setting temporary passwords.
* Current security guidelines around passwords, e.g. from NIST, but also from others, do not recommend enforcing special characters, since they often only lead to predictable alterations.
}}

If for example you want to enforce this policy:

* prompt 2 times for password in case of an error (retry option)
* 10 characters minimum length (minlen option)
* at least 6 characters should be different from old password when entering a new one (difok option)
* at least 1 digit (dcredit option)
* at least 1 uppercase (ucredit option)
* at least 1 lowercase (lcredit option)
* at least 1 other character (ocredit option)
* cannot contain the words "myservice" and "mydomain"
* enforce the policy for root

Edit the {{ic|/etc/pam.d/passwd}} file to read as:

{{bc|1=
#%PAM-1.0
password required pam_pwquality.so retry=2 minlen=10 difok=6 dcredit=-1 ucredit=-1 ocredit=-1 lcredit=-1 [badwords=myservice mydomain] enforce_for_root
password required pam_unix.so use_authtok yescrypt shadow
}}

The {{ic|password required pam_unix.so use_authtok}} instructs the ''pam_unix'' module to not prompt for a password but rather to use the one provided by ''pam_pwquality''.

You can refer to the {{man|8|pam_pwquality}} and {{man|8|pam_unix}} man pages for more information.

== CPU ==

=== Microcode ===

See [[microcode]] for information on how to install important security updates for your CPU's microcode.

=== Hardware vulnerabilities ===

Some CPUs contain hardware vulnerabilities. See the [https://docs.kernel.org/admin-guide/hw-vuln/ kernel documentation on hardware vulnerabilities] for a list of these vulnerabilities, as well as mitigation selection guides to help customize the kernel to mitigate these vulnerabilities for specific usage scenarios.

To check if you are affected by a known vulnerability, run the following:

$ grep -r . /sys/devices/system/cpu/vulnerabilities/

In most cases, updating the kernel and microcode will mitigate vulnerabilities.

==== Simultaneous multithreading (hyper-threading) ====

[[Wikipedia:Simultaneous multithreading|Simultaneous multithreading]] (SMT), also called hyper-threading on Intel CPUs, is a hardware feature that may be a source of [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html L1 Terminal Fault] and [https://docs.kernel.org/admin-guide/hw-vuln/mds.html Microarchitectural Data Sampling] vulnerabilities. The Linux kernel and microcode updates contain mitigations for known vulnerabilities, but [https://docs.kernel.org/admin-guide/hw-vuln/l1tf.html#virtualization-with-untrusted-guests disabling SMT may still be required on certain CPUs if untrusted virtualization guests are present].

{{Note|Disabling SMT is something mostly hypervisors benefit from.[https://security.stackexchange.com/questions/219753/sacrificing-30-of-my-cpu-performance-by-disabling-hyper-threading-to-fully-mi/219759#219759] On an ordinary system it has very little to no security benefits.}}

SMT can often be disabled in your system's firmware. Consult your motherboard or system documentation for more information. You can also disable SMT in the kernel by adding the following [[kernel parameter]]:

mitigations=auto,nosmt

== Memory ==

=== Hardened malloc ===

{{AUR|hardened_malloc}} is a hardened replacement for [[Wikipedia:GNU C Library|glibc]]'s malloc(). The project was originally developed for integration into Android's [[Wikipedia:Bionic (software)|Bionic]] and [[Wikipedia:musl|musl]] by Daniel Micay, of [[Wikipedia:GrapheneOS|GrapheneOS]], but he has also built in support for standard Linux distributions on the x86_64 architecture.

== Storage ==

=== Data-at-rest encryption ===

[[Data-at-rest encryption]], preferably full-disk encryption with a [[#Passwords|strong passphrase]], is the only way to guard data against physical recovery. This provides data confidentiality when the computer is turned off or the disks in question are unmounted.

Once the computer is powered on and the drive is mounted, however, its data becomes just as vulnerable as an unencrypted drive. It is therefore best practice to unmount data partitions as soon as they are no longer needed.

You may also [[Trusted Platform Module#LUKS encryption|encrypt a drive with the key stored in a TPM]], although it has had [https://tpm.fail vulnerabilites in the past] and the key can be extracted by a [https://pulsesecurity.co.nz/articles/TPM-sniffing bus sniffing attack].

Certain programs, like [[dm-crypt]], allow the user to encrypt a loop file as a virtual volume. This is a reasonable alternative to full-disk encryption when only certain parts of the system need to be secure.

While the block-device or filesystem-based encryption types compared in the [[data-at-rest encryption]] article are useful at protecting data on physical media, most can not be used to protect data on a remote system that you can not control (such as [[Data-at-rest encryption#Cloud-storage optimized|cloud storage]]). In some cases, individual file encryption will be useful.

These are some methods to encrypt files:

* Some [[Archiving and compression|archiving and compressing]] tools also provide basic encryption. Some examples are [[7-Zip]] ({{ic|-p}} flag), {{Pkg|zip}} ({{ic|-e}} flag). The encryption should only be relied on particular care, because the tools may use custom algorithms for cross-platform compatibility.[https://math.ucr.edu/~mike/zipattacks.pdf]
* [[GnuPG]] can be used to [[GnuPG#Encrypt and decrypt|encrypt files]].
* {{Pkg|age}} is a simple and easy to use file encryption tool. It also supports multiple recipients and encryption using SSH keys, which is useful for secure file sharing.

=== File systems ===

The kernel now prevents security issues related to hardlinks and symlinks if the {{ic|fs.protected_hardlinks}} and {{ic|fs.protected_symlinks}} sysctl switches are enabled, so there is no longer a major security benefit from separating out world-writable directories.

File systems containing world-writable directories can still be kept separate as a coarse way of limiting the damage from disk space exhaustion. However, filling {{ic|/var}} or {{ic|/tmp}} is enough to take down services. More flexible mechanisms for dealing with this concern exist (like [[Disk quota|quotas]]), and some [[file systems]] include related features themselves (Btrfs has quotas on subvolumes).

==== Mount options ====

Following the principle of least privilege, file systems should be mounted with the most restrictive mount options possible (without losing functionality).

Relevant mount options are:

* {{ic|nodev}}: Do not interpret character or block special devices on the file system.
* {{ic|nosuid}}: Do not allow set-user-identifier or set-group-identifier bits to take effect.
* {{ic|noexec}}: Do not allow direct execution of any binaries on the mounted file system.
** Setting {{ic|noexec}} on {{ic|/home}} disallows executable scripts and breaks [[Wine]], [[Steam]], PyCharm, [[.NET]], etc.
*** Wine does not need the {{ic|exec}} flag for opening Windows binaries. It is only needed when Wine itself is installed in {{ic|/home}}.
*** To keep [[Steam]] working you can mount {{ic|/home/user/.local/share/Steam}} as {{ic|exec}} in [[fstab]] by adding the following: {{bc|/home/user/.local/share/Steam /home/user/.local/share/Steam none defaults,bind,user,exec,nofail 0 0}}
** Some packages (building {{Pkg|nvidia-open-dkms}} for example) may require {{ic|exec}} on {{ic|/var}}.

File systems used for data should always be mounted with {{ic|nodev}}, {{ic|nosuid}} and {{ic|noexec}}.

Potential file system mounts to consider:

* {{ic|/var}}
* {{ic|/home}}
* {{ic|/dev/shm}}
* {{ic|/tmp}}
* {{ic|/boot}}

{{Tip|When using [[systemd#GPT partition automounting|GPT partition automounting]], the ESP and XBOOTLDR partitions are [https://github.com/systemd/systemd-stable/commit/49804cfb71d3a79f433096e4cfb5616980171336 always hardened] with {{ic|noexec,nosuid,nodev}}.}}

==== Snapshots ====

When utilizing file system snapshots, e.g. with [[Btrfs]], [[LVM]], or [[ZFS]], it is essential to be aware that snapshots may retain sensitive information that users expect to be deleted. This is especially true when automatic snapshotting tools like [[Snapper]] are configured, as they can capture snapshots at regular intervals or in response to system events. Here are some examples of how sensitive information in {{ic|/home/}} can persist within snapshots:

* ''Deleted files and directories'': Even though files or directories are deleted from the file system, they may still exist within older snapshots. This is expected most of the time, but consider whether files and directories such as {{ic|.local/share/Trash/}}, {{ic|.history}}, etc. should be retained.
* ''Temporary files and cache'': Temporary files and cached data generated by applications may be included in snapshots. For example, files kept in encrypted directories might generate thumbnails ({{ic|.cache/thumbnails}}) or work copies when opened, which might in turn be included in snapshots. The same applies e.g. to browsing history ({{ic|.mozilla/}}, {{ic|.config/chromium/}}, etc.), which could have been included in a snapshot before being purged.

If this is supported, consider excluding such directories from snapshots altogether. For example, if using [[Btrfs]], you can create subvolumes for example {{ic|.cache/}}, {{ic|.config/}}, {{ic|.local/}}, {{ic|.var/}} or any other directory according to your use-case.

{{Note|Moving {{ic|.local/share/Trash}} to a separate subvolume might break the trash feature in some cases, e.g. with [[GNOME/Files]].}}

=== File access permissions ===

{{Accuracy|{{ic|chmod go-r}} does not "take away all permissions", it only removes the read permission.}}

The default [[file permissions]] allow read access to almost everything and changing the permissions can hide valuable information from an attacker who gains access to a non-root account such as the {{ic|http}} or {{ic|nobody}} users. You can use [[chmod]] to take away all permissions from the group and others:

# chmod go-r ''path_to_hide''

{{Warning|Do not apply this broadly. Try this for one config at a time, ensuring that it is worth hiding, and that it will not break program functionality. You may need to remove the {{ic|g}} from the command (or re-add the permission with {{ic|chmod g+r ''path''}} if already ran) if the group is relied on.}}

Some paths to consider are:

* {{ic|/boot}}: The [[Partitioning#/boot|boot directory]], which may include traditional [[vmlinuz]] and [[initramfs]] images, or a [[Unified kernel image]]. Note that safe permissions are used by default when using [[systemd#GPT partition automounting]].
* {{ic|/etc/nftables.conf}}: The [[nftables]] configuration, applicable to {{Pkg|nftables}} and {{Pkg|iptables}}.
* {{ic|/etc/iptables}}: The legacy [[iptables]] configuration, applicable to {{Pkg|iptables-legacy}}.

The default [[umask]] {{ic|0022}} can be changed to improve security for newly created files. The [https://apps.nsa.gov/iaarchive/library/ia-guidance/security-configuration/operating-systems/guide-to-the-secure-configuration-of-red-hat-enterprise.cfm NSA RHEL5 Security Guide] suggests a umask of {{ic|0077}} for maximum security, which makes new files not readable by users other than the owner. To change this, see [[Umask#Set the mask value]]. If you use [[sudo]], consider configuring it to use the [[Sudo#Permissive umask|default root umask]].

=== SUID and SGID files ===

It is important to be aware of any files with the [[Wikipedia:Setuid|Setuid]] or Setgid bit. Examples of relevant files with the SUID bit set:

* [[PAM|unix_chkpwd]]
* chage, expiry, gpasswd, groupmems, [[passwd]], sg ({{Pkg|shadow}})
* [[FUSE|fusermount3]], fusermount2
* [[polkit|pkexec]]
* [[OpenSSH|ssh-keysign]]
* chfn, chsh, mount, newgrp, umount, wall, write ({{Pkg|util-linux}})
* [[sudo]], {{Pkg|sudo-rs}}, [[doas]], [[su]], su-rs, [[Kerberos|ksu]]
* [[firejail]]
* [[Dbus|dbus-daemon-launch-helper]]
* [[Chromium|chromium-sandbox]]
* [[Xorg|Xorg.wrap]]

The prominent risks of such executable files include privilege escalation vulnerabilities, see e.g [[Wikipedia:Setuid#Security impact]].[https://www.cvedetails.com/vulnerability-list/vendor_id-16224/product_id-36412/Calibre-ebook-Calibre.html][https://www.cvedetails.com/product/32625/Sudo-Project-Sudo.html?vendor_id=15714][https://www.cvedetails.com/vulnerability-list/vendor_id-16191/Firejail-Project.html]

Files with the SUID bit set and not owned by root, or files with the SGID bit set ''typically'' have less potential impact but can theoretically still do decent damage if vulnerable. It is usually possible to avoid using SUID or SGID by assigning [[Capabilities]] instead.

{{Tip|It is vital to be vigilant in keeping packages which provide SUID/SGID executables up to date in order to prevent having a vulnerable system.}}

To search for files with either the SUID or SGID bit:

$ find / -perm "/u=s,g=s" -type f 2>/dev/null

=== Backups ===

{{Merge|System backup|There is a dedicated page for system backups.}}

Regularly create backups of important data. Regularly test the integrity of the backups. Regularly test that the backups can be restored.

Make sure that at least one copy of the data is stored offline, i.e. not connected to the system under threat in any way. [[Wikipedia:Ransomware|Ransomware]] and other destructive attacks may also attack any connected backup systems.

=== SATA SSD frozen mode ===

See [[Solid state drive#Setting the SATA SSD state to frozen mode after waking up from sleep]].

== User setup ==

=== Do not use the root account for daily use ===

Following the principle of least privilege, do not use the root user for daily use. Create a non-privileged user account for each person using the system. See [[List of applications/Security#Privilege elevation]] for ways of temporarily gaining privileged access.

=== Enforce a delay after a failed login attempt ===

Add the following line to {{ic|/etc/pam.d/system-login}} to add a delay of at least 4 seconds between failed login attempts:

{{hc|/etc/pam.d/system-login|2=
auth optional pam_faildelay.so delay=4000000
}}

{{Note|This line needs to be the first line in the file.}}

{{ic|4000000}} is the time in microseconds to delay.

Other PAM modules besides {{ic|pam_faildelay}} can also suggest such a delay; if multiple modules do so, PAM will use the longest one.
In particular, both {{ic|pam_unix}} and {{ic|pam_faillock}} set a minimum delay of 2 seconds by default.
In order to completely remove this delay, you need to add the {{ic|nodelay}} parameter to any {{ic|auth}} lines of these modules, e.g.
{{hc|/etc/pam.d/system-auth|2=
auth [success{{=}}1 default{{=}}bad] pam_unix.so try_first_pass nullok nodelay
}}

=== Lock out user after three failed login attempts ===

Since {{Pkg|pambase}} 20200721.1-2, {{ic|pam_faillock.so}} is enabled by default to lock out users for 10 minutes after 3 failed login attempts in a 15 minute period (see {{Bug|67644}}). The lockout only applies to password authentication (e.g. login and ''sudo''), public key authentication over SSH is still accepted. To prevent complete denial-of-service, this lockout is disabled for the root user by default.

To unlock a user, do:

$ faillock --user ''username'' --reset

By default, the lock mechanism is a file per-user located at {{ic|/run/faillock/}}. Deleting or emptying the file unlocks that user—the directory is owned by root, but the file is owned by the user, so the {{ic|faillock}} command only empties the file, therefore does not require root.

The module {{ic|pam_faillock.so}} can be configured with the file {{ic|1=/etc/security/faillock.conf}}. The lockout parameters:

* {{ic|unlock_time}} — the lockout time (in seconds, default 10 minutes).
* {{ic|fail_interval}} — the time in which failed logins can cause a lockout (in seconds, default 15 minutes).
* {{ic|deny}} — the number of failed logins before lockout (default 3).

{{Tip|The primary purpose for the lockout is to slow down brute-force attacks so that they become infeasible. Hence, if lockouts due to mistyping of passwords become too frequent, relaxing the number of attempts may be preferred to reducing the lockout time.}}

{{Note|{{ic|1=deny = 0}} will disable the lockout mechanism entirely.}}

By default, all user locks are lost after reboot. If your attacker can reboot the machine, it is more secure if locks persist. To make locks persist, change the {{ic|dir}} parameter in {{ic|1=/etc/security/faillock.conf}} to {{ic|/var/lib/faillock}}.

No restart is required for changes to take effect. See {{man|5|faillock.conf}} for further configuration options, such as enabling lockout for the root account, disabling for centralized login (e.g. LDAP), etc.

{{Note|If you make locks persistant, following the changes introduced in polkit 127: you may have to relax the sandbox of its helper agent in order to keep it functional. The best way is to create a drop-in for its systemd unit via {{ic|systemctl edit polkit-agent-helper\@.service}} and add:

[Service]
ReadWritePaths{{=}}/var/lib/faillock
}}

=== Limit amount of processes ===

On systems with many, or untrusted users, it is important to limit the number of processes each can run at once, therefore preventing [[Wikipedia:Fork bomb|fork bombs]] and other denial of service attacks. The {{ic|/etc/security/limits.conf}} configuration determines how many processes each user, or group can have open, and is empty (except for useful comments) by default. Adding the following lines to this file will limit all users to 100 active processes, unless they use the {{ic|prlimit}} command to explicitly raise their maximum to 200 for that session. These values can be changed according to the appropriate number of processes a user should have running, or the hardware of the box you are administrating.

* soft nproc 100
* hard nproc 200

The current number of threads for each user can be found with {{ic|ps --no-headers -Leo user {{!}} sort {{!}} uniq --count}}. This may help with determining appropriate values for the users' limits; see also [[limits.conf]].

=== Use Wayland ===

Prefer using [[Wayland]] over [[Xorg]]. Xorg's design predates modern security practices and is [https://security.stackexchange.com/questions/4641/why-are-people-saying-that-the-x-window-system-is-not-secure/4646#4646 considered insecure] by many. For example, Xorg applications may record keystrokes while inactive.

If you must run Xorg, it is recommended to [[Xorg#Rootless Xorg|avoid running it as root]]. Within Wayland, the Xwayland compatibility layer will automatically use rootless Xorg.

== Restricting root ==

The root user is, by definition, the most powerful user on a system. It is also difficult to [[audit]] the root user account. It is therefore important to restrict usage of the root user account as much as possible. There are a number of ways to keep the power of the root user while limiting its ability to cause harm.

=== Use sudo instead of su ===

Using [[sudo]] for privileged access is preferable to [[su]] for a number of reasons:

* It keeps a log of which normal privilege user has run each privileged command.
* The root user password need not be given out to each user who requires root access.
* {{ic|sudo}} prevents users from accidentally running commands as ''root'' that do not need root access, because a full root terminal is not created. This aligns with the [[Wikipedia:Principle of least privilege|principle of least privilege]].
* Individual programs may be enabled per user, instead of offering complete root access just to run one command.

See [[Sudo#Configuration]].

==== Editing files using sudo ====

See [[Sudo#Editing files]]. Alternatively, you can use editors like {{ic|rvim}} or {{ic|rnano}} which have restricted capabilities in order to be safe to run as root.

=== Restricting root login ===

Once [[sudo]] is properly configured, full root access can be heavily restricted or denied without losing much usability. To disable root, but still allowing to use [[sudo]], you can use {{man|1|passwd}} with {{ic|passwd --lock root}}.

==== Allow only certain users ====

The [[PAM]] {{ic|pam_wheel.so}} lets you allow only users in the group {{ic|wheel}} to login using [[su]]. See [[su#su and wheel]].

==== Denying SSH login ====

Even if you do not wish to deny root login for local users, it is always good practice to [[OpenSSH#Deny|deny root login via SSH]]. The purpose of this is to add an additional layer of security before a user can completely compromise your system remotely.

==== Specify acceptable login combinations with access.conf ====

{{Warning|If you are using GNOME 49 or later, you should make sure the group ''gdm'' can log in locally. This can be done with a {{ic|+:(gdm):LOCAL}} rule. [https://gitlab.gnome.org/GNOME/gdm/-/issues/1021]}}

When someone attempts to log in with [[PAM]], {{ic|/etc/security/access.conf}} is checked for the first combination that matches their login properties. Their attempt then fails or succeeds based on the rule for that combination.

+:root:LOCAL
-:root:ALL

Rules can be set for specific groups and users. In this example, the user archie is allowed to login locally, as are all users in the wheel and adm groups. All other logins are rejected:

+:archie:LOCAL
+:(wheel):LOCAL
+:(adm):LOCAL
-:ALL:ALL

Read more at {{man|5|access.conf}}

== Mandatory access control ==

[[Wikipedia:Mandatory Access Control|Mandatory access control]] (MAC) is a type of security policy that differs significantly from the [[Wikipedia:Discretionary Access Control|discretionary access control]] (DAC) used by default in Arch and most Linux distributions. MAC essentially means that every action a program could perform that affects the system in any way is checked against a security ruleset. This ruleset, in contrast to DAC methods, cannot be modified by users. Using virtually any mandatory access control system will significantly improve the security of your computer, although there are differences in how it can be implemented.

=== Pathname MAC ===

Pathname-based access control is a simple form of access control that offers permissions based on the path of a given file. The downside to this style of access control is that permissions are not carried with files if they are moved around the system. On the positive side, pathname-based MAC can be implemented on a much wider range of filesystems, unlike labels-based alternatives.

* [[AppArmor]] is a [[Wikipedia:Canonical (company)|Canonical]]-maintained MAC implementation seen as an "easier" alternative to SELinux.
* [[TOMOYO]] is another simple, easy-to-use system offering mandatory access control. It is designed to be both simple in usage and in implementation, requiring very few dependencies.

=== Labels MAC ===

Labels-based access control means the extended attributes of a file are used to govern its security permissions. While this system is arguably more flexible in its security offerings than pathname-based MAC, it only works on filesystems that support these extended attributes.

* [[SELinux]], based on an [[Wikipedia:NSA|NSA]] project to improve Linux security, implements MAC completely separate from system users and roles. It offers an extremely robust multi-level MAC policy implementation that can easily maintain control of a system that grows and changes past its original configuration.

=== Access Control Lists ===

[[Access Control Lists]] (ACLs) are an alternative to attaching rules directly to the filesystem in some way. ACLs implement access control by checking program actions against a list of permitted behavior.

== Kernel hardening ==

=== Kernel self-protection / exploit mitigation ===

The {{pkg|linux-hardened}} package uses a [https://github.com/anthraxx/linux-hardened basic kernel hardening patch set] and more security-focused compile-time configuration options than the {{pkg|linux}} package. A custom build can be made to choose a different compromise between security and performance than the security-leaning defaults.

However, it should be noted that several packages (such as {{pkg|throttled}}) will not work when using this kernel.

If you use an out-of-tree driver such as [[NVIDIA]], you may need to switch to its [[DKMS]] package.

==== Userspace ASLR comparison ====

The {{pkg|linux-hardened}} package provides an improved implementation of Address Space Layout Randomization for userspace processes. The {{pkg|paxtest}} command can be used to obtain an estimate of the provided entropy:

===== 64-bit processes =====

{{hc|linux-hardened 5.4.21.a-1-hardened|
Anonymous mapping randomization test : 32 quality bits (guessed)
Heap randomization test (ET_EXEC) : 40 quality bits (guessed)
Heap randomization test (PIE) : 40 quality bits (guessed)
Main executable randomization (ET_EXEC) : 32 quality bits (guessed)
Main executable randomization (PIE) : 32 quality bits (guessed)
Shared library randomization test : 32 quality bits (guessed)
VDSO randomization test : 32 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 40 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 40 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 44 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 44 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 34 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 34 quality bits (guessed)
Randomization under memory exhaustion @~0: 32 bits (guessed)
Randomization under memory exhaustion @0 : 32 bits (guessed)
}}

{{hc|linux 5.5.5-arch1-1|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 20 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 29 bits (guessed)
Randomization under memory exhaustion @0 : 29 bits (guessed)
}}

{{hc|linux-lts 4.19.101-1-lts|
Anonymous mapping randomization test : 28 quality bits (guessed)
Heap randomization test (ET_EXEC) : 28 quality bits (guessed)
Heap randomization test (PIE) : 28 quality bits (guessed)
Main executable randomization (ET_EXEC) : 28 quality bits (guessed)
Main executable randomization (PIE) : 28 quality bits (guessed)
Shared library randomization test : 28 quality bits (guessed)
VDSO randomization test : 19 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 30 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 30 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 22 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 22 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 28 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 28 quality bits (guessed)
Randomization under memory exhaustion @~0: 28 bits (guessed)
Randomization under memory exhaustion @0 : 28 bits (guessed)
}}

===== 32-bit processes (on an x86_64 kernel) =====

{{hc|linux-hardened|
Anonymous mapping randomization test : 16 quality bits (guessed)
Heap randomization test (ET_EXEC) : 22 quality bits (guessed)
Heap randomization test (PIE) : 27 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 18 quality bits (guessed)
Shared library randomization test : 16 quality bits (guessed)
VDSO randomization test : 16 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 24 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 24 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 28 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 28 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 18 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 16 quality bits (guessed)
Randomization under memory exhaustion @~0: 18 bits (guessed)
Randomization under memory exhaustion @0 : 18 bits (guessed)
}}

{{hc|linux|
Anonymous mapping randomization test : 8 quality bits (guessed)
Heap randomization test (ET_EXEC) : 13 quality bits (guessed)
Heap randomization test (PIE) : 13 quality bits (guessed)
Main executable randomization (ET_EXEC) : No randomization
Main executable randomization (PIE) : 8 quality bits (guessed)
Shared library randomization test : 8 quality bits (guessed)
VDSO randomization test : 8 quality bits (guessed)
Stack randomization test (SEGMEXEC) : 19 quality bits (guessed)
Stack randomization test (PAGEEXEC) : 19 quality bits (guessed)
Arg/env randomization test (SEGMEXEC) : 11 quality bits (guessed)
Arg/env randomization test (PAGEEXEC) : 11 quality bits (guessed)
Offset to library randomisation (ET_EXEC): 8 quality bits (guessed)
Offset to library randomisation (ET_DYN) : 13 quality bits (guessed)
Randomization under memory exhaustion @~0: No randomization
Randomization under memory exhaustion @0 : No randomization
}}

=== Restricting access to kernel pointers in the proc filesystem ===

Setting {{ic|kernel.kptr_restrict}} to 1 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} from regular users without {{ic|CAP_SYSLOG}}, making it more difficult for kernel exploits to resolve addresses/symbols dynamically. This will not help that much on a pre-compiled Arch Linux kernel, since a determined attacker could just download the kernel package and get the symbols manually from there, but if you are compiling your own kernel, this can help mitigating local root exploits. This will break some {{Pkg|perf}} commands when used by non-root users (but many {{Pkg|perf}} features require root access anyway). See {{Bug|34323}} for more information.

Setting {{ic|kernel.kptr_restrict}} to 2 will hide kernel symbol addresses in {{ic|/proc/kallsyms}} regardless of privileges.

{{hc|/etc/sysctl.d/51-kptr-restrict.conf|2=
kernel.kptr_restrict = 1
}}

{{Note|{{pkg|linux-hardened}} sets {{ic|1=kptr_restrict=2}} by default rather than {{ic|0}}.}}

=== BPF hardening ===

BPF is a system used to load and execute bytecode within the kernel dynamically during runtime. It is used in a number of Linux kernel subsystems such as networking (e.g. XDP, tc), tracing (e.g. kprobes, uprobes, tracepoints) and security (e.g. seccomp). It is also useful for advanced network security, performance profiling and dynamic tracing.

BPF was originally an acronym of [[Wikipedia:Berkeley Packet Filter|Berkeley Packet Filter]] since the original classic BPF was used for packet capture tools for BSD. This eventually evolved into Extended BPF (eBPF), which was shortly afterwards renamed to just BPF (not an acronym). BPF should not be confused with packet filtering tools like iptables or netfilter, although BPF can be used to implement packet filtering tools.

BPF code may be either interpreted or compiled using a [[Wikipedia:Just-in-time compilation|Just-In-Time (JIT) compiler]]. The Arch kernel is built with {{ic|CONFIG_BPF_JIT_ALWAYS_ON}} which disables the BPF interpreter and forces all BPF to use JIT compilation. This makes it harder for an attacker to use BPF to escalate attacks that exploit SPECTRE-style vulnerabilities. See [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=290af86629b25ffd1ed6232c4e9107da031705cb the kernel patch which introduced CONFIG_BPF_JIT_ALWAYS_ON] for more details.

The kernel includes a hardening feature for JIT-compiled BPF which can mitigate some types of JIT spraying attacks at the cost of performance and the ability to trace and debug many BPF programs. It may be enabled by setting {{ic|net.core.bpf_jit_harden}} to {{ic|1}} (to enable hardening of unprivileged code) or {{ic|2}} (to enable hardening of all code).

See the {{ic|net.core.bpf_*}} settings in the [https://docs.kernel.org/admin-guide/sysctl/net.html kernel documentation] for more details.

{{Tip|
* {{Pkg|linux-hardened}} sets {{ic|1=net.core.bpf_jit_harden=2}} by default rather than {{ic|0}}.
* By default, BPF programs can be run even by unprivileged users. To change that behaviour set {{ic|1=kernel.unprivileged_bpf_disabled=1}}[https://access.redhat.com/security/cve/cve-2021-33624].
}}

=== ptrace scope ===

The {{man|2|ptrace}} syscall provides a means by which one process (the "tracer") may observe and control the execution of another process (the "tracee"), and examine and change the tracee's memory and registers. {{ic|ptrace}} is commonly used by debugging tools including ''gdb'', ''strace'', ''perf'', ''reptyr'' and other debuggers. However, it also provides a means by which a malicious process can read data from and take control of other processes.

Arch enables the [https://docs.kernel.org/admin-guide/LSM/Yama.html Yama LSM] by default, which provides a {{ic|kernel.yama.ptrace_scope}} [[kernel parameter]]. This parameter is set to {{ic|1}} (restricted) by default which prevents tracers from performing a {{ic|ptrace}} call on traces outside of a restricted scope unless the tracer is privileged or has the {{ic|CAP_SYS_PTRACE}} [[Capabilities|capability]]. This is a significant improvement in security compared to the classic permissions. Without this module, there is no separation between processes running as the same user (in the absence of additional security layers such as {{man|7|pid_namespaces}}).

{{Note|By default, you can still use tools which require {{ic|ptrace}} by running them as privileged processes, e.g. using [[sudo]].}}

If you do not need to use debugging tools, consider setting {{ic|kernel.yama.ptrace_scope}} to {{ic|2}} (admin-only) or {{ic|3}} (no {{ic|ptrace}} possible) to harden the system.

{{Note|Some anti-cheat and DRM implementations rely on {{ic|ptrace}} to work, including Easy Anti-Cheat and Ubisoft Connect under Wine. Setting this parameter to {{ic|2}} or higher might prevent games using these solutions from launching.}}

=== hidepid ===

{{Expansion|1=[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=0fb5ce62c5920b6e0a8a061f2fe80e0403281e10 Linux 5.8 implemented private instances] and new values for {{ic|1=hidepid=}}.}}

{{Accuracy|Enabling {{ic|hidepid}} globally is not a supported way of operation by [[systemd]], nor does it have any practical improvements security-wise when systemd is running as service manager. [https://github.com/systemd/systemd/issues/29893#issuecomment-1798030108]}}

{{Warning|
* This may cause issues for certain applications like an application running in a sandbox and [[Xorg]] (see workaround).
* This causes issues with [[D-Bus]], [[Polkit]], [[PulseAudio]] and [[bluetooth]] when using {{Pkg|systemd}} > 237.64-1.
}}

The kernel has the ability to hide other users' processes, normally accessible via {{ic|/proc}}, from unprivileged users by mounting the {{ic|proc}} filesystem with the {{ic|1=hidepid=}} and {{ic|1=gid=}} options documented in https://docs.kernel.org/filesystems/proc.html.

This greatly complicates an intruder's task of gathering information about running processes, whether some daemon runs with elevated privileges, whether other user runs some sensitive program, whether other users run any program at all, makes it impossible to learn whether any user runs a specific program (given the program does not reveal itself by its behaviour), and, as an additional bonus, poorly written programs passing sensitive information via program arguments are now protected against local eavesdroppers.

The {{ic|proc}} [[Users and groups#System groups|group]], provided by the {{Pkg|filesystem}} package, acts as a whitelist of users authorized to learn other users' process information. If users or services need access to {{ic|/proc/<pid>}} directories beyond their own, [[Users and groups#Group management|add them to the group]].

For example, to hide process information from other users except those in the {{ic|proc}} group:

{{hc|/etc/fstab|2=
proc /proc proc nosuid,nodev,noexec,hidepid=2,gid=proc 0 0
}}

For user sessions to work correctly, an exception needs to be added for ''systemd-logind'':

{{hc|/etc/systemd/system/systemd-logind.service.d/hidepid.conf|2=
[Service]
SupplementaryGroups=proc
}}

=== Restricting module loading ===

The default Arch kernel has {{ic|CONFIG_MODULE_SIG_ALL}} enabled, which signs all kernel modules built as part of the {{Pkg|linux}} package. This allows the kernel to only load modules signed with a valid key, i.e. out-of-tree modules compiled locally or provided by packages such as {{Pkg|virtualbox-host-modules-arch}} cannot be loaded. You can use {{ic|1=modinfo}} to verify currently loaded modules have signatures; verifying the signatures by hand is slightly more involved [https://unix.stackexchange.com/a/496800].

Kernel module loading can be restricted by setting the {{ic|1=module.sig_enforce=1}} [[kernel parameter]]. More information can be found in the [https://docs.kernel.org/admin-guide/module-signing.html kernel documentation].

Further, unneeded individual modules can be [[blacklist]]ed, see [https://github.com/secureblue/secureblue/blob/live/files/system/usr/lib/modprobe.d/secureblue.conf secureblue] for examples.

=== Disable kexec ===

Kexec allows replacing the current running kernel.

{{hc|/etc/sysctl.d/51-kexec-restrict.conf|2=
kernel.kexec_load_disabled = 1
}}

{{Tip|kexec is disabled by default in {{pkg|linux-hardened}}.}}

=== Kernel lockdown mode ===

Linux supports an optional [https://mjg59.dreamwidth.org/55105.html lockdown feature], intended to strengthen the boundary between UID 0 (root) and the kernel. When enabled some applications may cease to work which rely on low-level access to either hardware or the kernel.

To use lockdown, its LSM must be initialized and a lockdown mode must be set.

All [[Kernel#Officially supported kernels|officially supported kernels]] initialize the LSM, but none of them enforce any lockdown mode.

{{Tip|Initialized LSMs can be verified by running {{ic|cat /sys/kernel/security/lsm}}.}}

Lockdown has two modes of operation:

* {{ic|integrity}}: kernel features that allow userland to modify the running kernel are disabled (e.g. kexec, bpf).
* {{ic|confidentiality}}: kernel features that allow userland to extract confidential information from the kernel are also disabled.

It is recommended to use {{ic|integrity}}, unless your specific threat model dictates otherwise.

To enable kernel lockdown at runtime, run:

# echo ''mode'' > /sys/kernel/security/lockdown

To enable kernel lockdown on boot, use the [[kernel parameter]] {{ic|1=lockdown=''mode''}}.

{{Note|
* Kernel lockdown cannot be disabled at runtime.
* Kernel lockdown disables [[hibernation]].
* Versions <6.17 of the {{man|7|kernel_lockdown}} man page incorrectly state that "lockdown will be automatically enabled if the system boots in EFI Secure Boot mode". This is not the behaviour of the upstream kernel, nor Arch's packaged [[kernel]]s.
}}

See also {{man|7|kernel_lockdown}}.

=== Linux Kernel Runtime Guard (LKRG) ===

[https://www.openwall.com/lkrg/ LKRG] ({{AUR|lkrg-dkms}}) is a kernel module which performs integrity checking of the kernel and detection of exploit attempts.

=== Disable emergency shell ===

{{Accuracy|Masking {{ic|emergency.target}} and {{ic|emergency.service}} will have no effect on those units being added to the initramfs and run in early userspace. Even with them in the initramfs, mkinitcpio's systemd hook locks the root account[https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/292cdf8a2f7dd7c6c7d91d2b59617391935c837c][https://gitlab.archlinux.org/archlinux/packaging/packages/systemd/-/commit/8835b2f5dfbe8663f1a2fd08edbd35f90bf08691] for "security reasons" (see {{Bug|70408}}). The solution for the issue in the linked article, if even needed, would be to prevent {{ic|rescue.target}}, {{ic|rescue.service}}, {{ic|emergency.target}} and {{ic|emergency.service}} from being added to the initramfs image.}}

The emergency shell is used to interactively troubleshoot the machine during the boot process. However, it is also a gadget that an attacker can use to access secure resources such as the TPM. See [https://pulsesecurity.co.nz/advisories/tpm-luks-bypass this article] for a practical example. The difficulty of attacks can be increased by disabling the emergency shell, at the tradeoff of removing a tool to troubleshoot early boot failures.

To disable the emergency shell, See [[systemd#Disable emergency mode on remote machine]].

== Sandboxing applications ==

See also [[Wikipedia:Sandbox (computer security)]].

To improve the security of systemd service units, see [[systemd/Sandboxing]].

{{Warning|Unprivileged user namespace usage is enabled by default in all [[Kernel#Officially supported kernels|officially supported kernels]] except for {{Pkg|linux-hardened}}. Unprivileged user namespaces greatly increase the attack surface for local privilege escalation; see [https://gitlab.com/apparmor/apparmor/-/wikis/unprivileged_userns_restriction AppArmor's Wiki] and {{Bug|36969}}.}}

To mitigate this, either:

* use the {{Pkg|linux-hardened}} kernel which has the safe default, or
* set the {{ic|kernel.unprivileged_userns_clone}} [[sysctl]] to {{ic|0}}.

Note that this can break applications such as {{pkg|nsjail}}. [[Chromium]] based applications need SUID bit for {{ic|chrome-sandbox}} to work with this setting.

=== Firejail ===

[[Firejail]] is an easy to use tool for sandboxing applications and servers alike. It was originally created for browsers and internet facing applications, but supports a large number of applications by now. To establish a sandboxed environment with a variety of features, it is installed as a suid binary and builds a sandboxed runtime environment for the target application based on black and white lists.

=== bubblewrap ===

[[bubblewrap]] is a sandbox application developed for unprivileged container tools like [[Flatpak]] with a significantly smaller resource footprint and complexity than Firejail. While it lacks certain features such as file path whitelisting, bubblewrap does offer bind mounts as well as the creation of user/IPC/PID/network/cgroup namespaces and can support both simple and complex sandboxes. For the {{Pkg|linux-hardened}} kernel you will need to to use {{Pkg|bubblewrap-suid}}.

[[Bubblejail]] sandbox is based on [[bubblewrap]] and provides a resource oriented permission model with a graphical interface to tweak permissions.

=== Portable ===

[https://github.com/Kraftland/portable Portable] is a sandboxing framework which utilizes [[bubblewrap]] and many other tools to lockdown running applications. It is designed to be simple for packagers and efficient for users, yet cuts off security holes and monitors background processes by default.

See [https://github.com/Kraftland/portable-arch portable-arch] for a repository of applications sandboxed by portable.

If a sandboxed application does not utilize the Portal file chooser, portable can pass files to the sandbox (by passing {{ic|--actions share-files}}).

Portable is fully functional on GNOME, while other desktops may lack small amounts of features like advanced background monitoring and ScreenShot portal.

=== chroots ===

Manual [[chroot]] jails can also be constructed to build sandboxed process environments. It is much more limited than other sandboxing technologies; the extent of its sandboxing is file path isolation.

=== Linux containers ===

[[Linux Containers]] are another good option when you need more separation than the other options (short of [[#Full virtualization options|full system virtualization]]) provide. LXC is run on top of the existing kernel in a pseudo-chroot with their own virtual hardware.

=== gVisor ===

The [https://gvisor.dev/ gVisor] project, led by Google, is providing a sandboxing application with a focus on containers following the [https://opencontainers.org/ OCI initiative], such as [[Docker]] and [[Kubernetes]]. It isolates containers and individual applications from the host by intercepting a majority of system calls to the kernel and presenting itself as guest kernel.

A key difference to other intercepting sandboxing projects is that gVisor re-implements system calls in the Go programming language, as described in its [https://gvisor.dev/docs/architecture_guide/intro/ design overview]. Details for the list of [https://gvisor.dev/docs/user_guide/compatibility/linux/amd64/ re-implemented syscalls support] can be seen in [https://github.com/google/gvisor/blob/master/pkg/sentry/syscalls/linux/linux64.go git]. For usage examples, limitations and special features see the project [https://gvisor.dev/docs/ documentation].

The application is available as {{Aur|gvisor-git}} and {{Aur|gvisor-bin}}.

=== Full virtualization options ===

Using full virtualization options such as [[VirtualBox]], [[KVM]], [[Xen]] or [https://www.qubes-os.org/ Qubes OS] (based on Xen) can also improve isolation and security in the event you plan on running risky applications or browsing dangerous websites.

== Network and firewalls ==

=== Firewalls ===

While the stock Arch kernel is capable of using [[Wikipedia:Netfilter|Netfilter]]'s [[iptables]] and [[nftables]], the services are not [[enable]]d by default. It is highly recommended to set up some form of firewall to protect the services running on the system. Many resources (including ArchWiki) do not state explicitly which services are worth protecting, so enabling a firewall is a good precaution.

* See [[iptables]] and [[nftables]] for general information.
* See [[Simple stateful firewall]] for a guide on setting up an iptables firewall.
* See [[:Category:Firewalls]] for other ways of setting up netfilter.
* See [[Ipset]] for blocking lists of ip addresses, such as those from Bluetack.
* {{Pkg|opensnitch}} is a configurable inbound and outbound firewall with support for configurable rules by application, port, host, etc.

A quick way to setup a basic firewall is to use the tool {{ic|ufw}} (Uncomplicated Fire Wall). Then set {{ic|ufw default deny incoming}} and {{ic|ufw default allow outgoing}} and enabling it with {{ic|ufw enable}} and {{ic|systemctl enable ufw}}.

==== Open ports ====

{{Style|"Open ports" is not a good title since it disregards interfaces and addresses that the application may be bound to. From the firewalls' point of view, ports may be "open" even if no application listens on them at the moment.}}

Some services listen for inbound traffic on open network ports. It is important to only bind these services to the addresses and interfaces that are strictly necessary. It may be possible for a remote attacker to [https://samy.pl/slipstream/ exploit flawed network protocols to access exposed services]. This can even happen with [https://nvd.nist.gov/vuln/detail/CVE-2019-13450 processes bound to localhost].

In general, if a service only needs to be accessible to the local system, bind to a Unix domain socket ({{man|7|unix}}) or a loopback address such as {{ic|localhost}} instead of a non-loopback address like {{ic|0.0.0.0/0}}.

If a service needs to be accessible to other systems via the network, control the access with strict [[firewall]] rules and configure authentication, authorization and encryption whenever possible.

You can list all current open ports with {{ic|ss -l}}. To show all '''l'''istening '''p'''rocesses and their '''n'''umeric '''t'''cp and '''u'''dp port numbers:

# ss -lpntu

See {{man|8|ss}} for more options.

=== Kernel parameters ===

Kernel parameters which affect networking can be set using [[Sysctl]]. For how to do this, see [[Sysctl#TCP/IP stack hardening]].

=== SSH ===

To mitigate [[Wikipedia:Brute-force attack|brute-force attacks]] it is recommended to enforce key-based authentication. For OpenSSH see [[OpenSSH#Protection]] for more recommendations. Alternatively [[Fail2ban]] or [[Sshguard]] offer lesser forms of protection by monitoring logs and writing [[firewall]] rules but open up the potential for a denial of service, since an attacker can [[Wikipedia:Spoofing attack#Spoofing and TCP/IP|spoof]] packets as if they came from the administrator after identifying their address. Spoofing IP has lines of defense, such as by [[sysctl#Reverse path filtering|reverse path filtering]] and [[sysctl#Disable ICMP redirects|disabling ICMP redirects]].

You may want to harden authentication even more by using two-factor authentication. [[Google Authenticator]] provides a two-step authentication procedure using one-time passcodes (OTP).

Denying root login is also a good practice, both for tracing intrusions and adding an additional layer of security before root access. For OpenSSH, see [[OpenSSH#Deny]].

Mozilla publishes an [https://infosec.mozilla.org/guidelines/openssh.html OpenSSH configuration guide] which configures more verbose audit logging and restricts ciphers.

=== DNS ===

The default domain name resolution (DNS) configuration is highly compatible but has security weaknesses. See [[Domain name resolution#Privacy and security|DNS privacy and security]] for more information.

=== Proxies ===

Proxies are commonly used as an extra layer between applications and the network, sanitizing data from untrusted sources. The attack surface of a small proxy running with lower privileges is significantly smaller than a complex application running with the end user privileges.

For example the DNS resolver is implemented in {{Pkg|glibc}}, that is linked with the application (that may be running as root), so a bug in the DNS resolver might lead to a remote code execution. This can be prevented by installing a DNS caching server, such as [[dnsmasq]], which acts as a proxy. [https://googleonlinesecurity.blogspot.it/2016/02/cve-2015-7547-glibc-getaddrinfo-stack.html]

=== Managing TLS certificates ===

See [[TLS#Trust management]].

== Physical security ==

Physical access to a computer is root access given enough time and resources. However, a high ''practical'' level of security can be obtained by putting up enough barriers.

An attacker can gain full control of your computer on the next boot by simply attaching a malicious IEEE 1394 (FireWire), Thunderbolt or PCI Express device as they are given full memory access by default.[https://web.archive.org/web/20210312083421/http://breaknenter.org/2014/09/inception-metasploit-integration/] For Thunderbolt, you can restrict the direct memory access completely or to known devices, see [[Thunderbolt#User device authorization|user device authorization]]. For Firewire and PCI Express, there is little you can do from preventing this, or modification of the hardware itself - such as flashing malicious firmware onto a drive. However, the vast majority of attackers will not be this knowledgeable and determined.

[[#Data-at-rest encryption|Data-at-rest encryption]] will prevent access to your data if the computer is stolen, but malicious firmware can be installed to obtain this data upon your next log in by a resourceful attacker.

=== Locking down BIOS ===

Adding a password to the BIOS prevents someone from booting into removable media, which is basically the same as having root access to your computer. You should make sure your drive is first in the boot order and disable the other drives from being bootable if you can.

=== Boot loaders ===

It is highly important to protect your [[boot loader]]. An unprotected boot loader can bypass any login restrictions, e.g. by setting the {{ic|1=init=/bin/sh}} [[kernel parameter]] to boot directly to a shell.

==== Syslinux ====

[[Syslinux]] supports [[Syslinux#Security|password-protecting your boot loader]]. It allows you to set either a per-menu-item password or a global boot loader password.

==== GRUB ====

[[GRUB]] supports boot loader passwords as well. See [[GRUB/Tips and tricks#Password protection of GRUB menu]] for details. It also has support for [[GRUB#Encrypted /boot|encrypted /boot]], which only leaves some parts of the boot loader code unencrypted. GRUB's configuration, [[kernel]] and [[initramfs]] are encrypted.

==== systemd-boot ====

[[systemd-boot]] disables editing of kernel parameters when [[#Secure Boot|Secure Boot]] is enabled. Alternatively, you can set [[systemd-boot#Kernel parameters editor with password protection|kernel parameters for password protection]] in systemd-boot for a more traditional password-based option.

=== Secure Boot ===

[[Secure Boot]] is a feature of [[UEFI]] that allows authentication of the files your computer boots. This helps preventing some [[Wikipedia:Evil maid attack|evil maid attacks]] such as replacing files inside the boot partition. Normally computers come with keys that are enrolled by vendors (OEM). However these can be removed and allow the computer to enter ''Setup Mode'' which allows the user to enroll and manage their own keys.

The secure boot page guides you through how to set secure boot up by [[Unified Extensible Firmware Interface/Secure Boot#Using your own keys|using your own keys]].

=== Trusted Platform Module (TPM) ===

[[Trusted Platform Module|TPMs]] are hardware microprocessors which have cryptographic keys embedded. This forms the fundamental root of trust of most modern computers and allows end-to-end verification of the boot chain. They can be used as internal smartcards, attest the firmware running on the computer and allow users to insert secrets into a tamper-proof and brute-force resistant store.

=== Boot partition on removable flash drive ===

One popular idea is to place the boot partition on a flash drive in order to render the system unbootable without it. Proponents of this idea often use [[#Data-at-rest encryption|full-disk encryption]] alongside, and some also use [[Dm-crypt/Specialties#Encrypted system using a detached LUKS header|detached encryption headers]] placed on the boot partition.

This method can also be merged with [[Dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB|encrypting /boot]].

=== Automatic logout ===

If you are using [[Bash]] or [[Zsh]], you can set {{ic|TMOUT}} for an automatic logout from shells after a timeout.

For example, the following will automatically log out from virtual consoles (but not terminal emulators in X11):

{{hc|/etc/profile.d/shell-timeout.sh|<nowiki>
TMOUT="$(( 60*10 ))";
[ -z "$DISPLAY" ] && export TMOUT;
case $( /usr/bin/tty ) in
/dev/tty[0-9]*) export TMOUT;;
esac
</nowiki>}}

If you really want EVERY Bash/Zsh prompt (even within X) to timeout, use:

$ export TMOUT="$(( 60*10 ))";

Note that this will not work if there is some command running in the shell (eg.: an SSH session or other shell without {{ic|TMOUT}} support). But if you are using VC mostly for restarting frozen GDM/Xorg as root, then this is very useful.

=== Protect against rogue USB devices ===

The kernel has [https://docs.kernel.org/usb/authorization.html settings to deactivate] USB ports to protect your computer against rogue USB devices (a.k.a. [[Wikipedia:BadUSB|BadUSB]], [https://github.com/samyk/poisontap PoisonTap] or [https://lanturtle.com/ LanTurtle]). They can be set at runtime and automated via [[sysctl]].

For more control install [[USBGuard]], which is a software framework implementing basic whitelisting and blacklisting capabilities based on device attributes.

=== Volatile data collection ===

A computer that is powered on may be vulnerable to [https://web.archive.org/web/20210420075636/https://fedvte.usalearning.gov/courses/CSI/course/videos/pdf/CSI_D01_S05_T01_STEP.pdf volatile data collection]. It is a best practice to turn a computer completely off at times it is not necessary for it to be on, or if the computer's physical security is temporarily compromised (e.g. when passing through a security checkpoint).

== Packages ==

=== Authentication ===

[https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html#overview Attacks on package managers] are possible without proper use of package signing, and can affect even package managers with [https://www2.cs.arizona.edu/stork/packagemanagersecurity/faq.html proper signature systems]. Arch uses package signing by default and relies on a web of trust from 5 trusted master keys. See [[Pacman-key]] for details.

=== Upgrades ===

It is important to regularly [[System maintenance#Upgrading the system|upgrade the system]].

=== Follow vulnerability alerts ===

Subscribe to the Common Vulnerabilities and Exposure (CVE) Security Alert updates, made available by National Vulnerability Database, and found on the [https://nvd.nist.gov/download.cfm NVD Download webpage].

The tool {{Pkg|arch-audit}} can be used to check for vulnerabilities affecting the running system. A graphical system tray, {{Pkg|arch-audit-gtk}}, can also be used. See also [[Arch Security Team]].

You should also consider subscribing to the release notifications for software you use, especially if you install software through means other than the main repositories or AUR. Some software have mailing lists you can subscribe to for security notifications. Source code hosting sites often offer RSS feeds for new releases.

=== Rebuilding packages ===

Packages can be rebuilt and stripped of undesired functions and features as a means to reduce attack surface. For example, {{Pkg|bzip2}} can be rebuilt without {{ic|bzip2recover}} in an attempt to circumvent [https://security.archlinux.org/CVE-2016-3189 CVE-2016-3189]. Custom hardening flags can also be applied either manually or via a wrapper.

{{Merge|Arch package guidelines/Security|Security related build flags have their own article.}}

{{Accuracy|Copy-pasted from a 3 years old blog post. The compiler flags are specific to [[GCC]], some are hardly security related.}}

{| class="wikitable"
! Flag !! Purpose
|-
| -D_FORTIFY_SOURCE=2 || Run-time buffer overflow detection
|-
| -D_GLIBCXX_ASSERTIONS || Run-time bounds checking for C++ strings and containers
|-
| -fasynchronous-unwind-tables || Increased reliability of backtraces
|-
| -fexceptions || Enable table-based thread cancellation
|-
| -fpie -Wl,-pie || Full ASLR for executables
|-
| -fpic -shared || No text relocations for shared libraries
|-
| -fplugin=annobin || Generate data for hardening quality control
|-
| -fstack-clash-protection || Increased reliability of stack overflow detection
|-
| -fstack-protector, -fstack-protector-all or -fstack-protector-strong || Stack smashing protector
|-
| -grecord-gcc-switches || Store compiler flags in debugging information
|-
| -mcet -fcf-protection || Control flow integrity protection
|-
| -Werror=format-security || Reject potentially unsafe format string arguments
|-
| -Werror=implicit-function-declaration || Reject missing function prototypes
|-
| -Wl,-z,defs || Detect and reject underlinking
|-
| -Wl,-z,now || Disable lazy binding
|-
| -Wl,-z,relro || Read-only segments after relocation
|}

* [https://developers.redhat.com/blog/2018/03/21/compiler-and-linker-flags-gcc/ Flags and info source]

== See also ==

* [https://security.archlinux.org/ Arch Linux Security Tracker]
* [https://wiki.centos.org/HowTos/OS_Protection CentOS Wiki: OS Protection]
* [https://web.archive.org/web/20210712001756/https://developer.ibm.com/technologies/linux/articles/l-harden-desktop/ Hardening the Linux desktop]
* [https://web.archive.org/web/20190701140035/https://www.ibm.com/developerworks/linux/tutorials/l-harden-server/index.html Hardening the Linux server]
* [https://github.com/lfit/itpol/blob/master/linux-workstation-security.md Linux Foundation: Linux workstation security checklist]
* [https://www.privacyguides.org/ privacyguides.org Privacy Resources]
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/ Red Hat Enterprise Linux 7 Security Guide]
* [https://www.debian.org/doc/manuals/securing-debian-manual/index.en.html Securing Debian Manual]
* [https://web.archive.org/web/20140220055801/http://crunchbang.org:80/forums/viewtopic.php?id=24722 The paranoid #! Security Guide]

Isync

2026-05-10T15:43:38Z

Indigo: /* Configuring */ move note below configuration sample (paragraph unchanged) and reword note according to manual

{{Lowercase title}}
[[Category:Mail retrieval agents]]
[[Category:OpenPGP]]
[[ja:Isync]]
[https://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.

Synchronization is based on unique message identifiers (UIDs), so no identification conflicts can occur (as opposed to some other mail synchronizers).
Synchronization state is kept in one local text file per mailbox pair; multiple replicas of a mailbox can be maintained.
{{note|isync is the name of the project, mbsync is the name of the executable}}

== Installing ==

[[Install]] the {{Pkg|isync}} package.

== Configuring ==

First, a main configuration file needs to be created, either as {{ic|isyncrc}} in the user's {{ic|XDG_CONFIG_HOME}} directory, or {{ic|.mbsyncrc}} in the user's home directory root. The package supplies an example {{ic|/usr/share/doc/isync/examples/mbsyncrc.sample}} file. Another example for a Google-mail account is as follows:

{{Note|'''Subfolders''' setting for {{ic|MaildirStore}} is required to be set, but unset per default - see [https://isync.sourceforge.net/mbsync.html iSync Config SubFolders].}}

{{Out of date|The access to Gmail with [https://myaccount.google.com/lesssecureapps lesssecureapps] is no longer possible without two-factor authentication. The example needs to be updated for an [https://myaccount.google.com/apppasswords an app password], or another provider. For Gmail, [[#Using XOAUTH2]] is another option.}}

{{hc|~/.mbsyncrc|
IMAPAccount gmail
# Address to connect to
Host imap.gmail.com
User ''username''@gmail.com
Pass ***************
# To store the password in an encrypted file use PassCmd instead of Pass
# PassCmd "gpg2 -q --for-your-eyes-only --no-tty -d ~/.mailpass.gpg"
#
# Use TLS
TLSType IMAPS
# The following line should work. If you get certificate errors, uncomment the two following lines and read the "Troubleshooting" section.
CertificateFile /etc/ssl/certs/ca-certificates.crt
#CertificateFile ~/.cert/imap.gmail.com.pem
#CertificateFile ~/.cert/Equifax_Secure_CA.pem

IMAPStore gmail-remote
Account gmail

MaildirStore gmail-local
SubFolders Verbatim
# The trailing "/" is important
Path ~/.mail/gmail/
Inbox ~/.mail/gmail/Inbox

Channel gmail
Far :gmail-remote:
Near :gmail-local:
# Exclude everything under the internal [Gmail] folder, except the interesting folders
Patterns * ![Gmail]* "[Gmail]/Sent Mail" "[Gmail]/Starred" "[Gmail]/All Mail"
# Or include everything
#Patterns *
# Automatically create missing mailboxes, both locally and on the server
Create Both
# Sync the movement of messages between folders and deletions, add after making sure the sync works
Expunge Both
# Save the synchronization state files in the relevant directory
SyncState *
}}

It is possible to avoid the proprietary {{ic|[Gmail]}} (or {{ic|[Google Mail]}}) folder categorization by using separate channels for each directory, and later merging them to a group:
{{hc|~/.mbsyncrc|
Channel sync-googlemail-default
Far :gmail-remote:
Near :gmail-local:
# Select some mailboxes to sync
Patterns "INBOX" "arch"
Create Both

Channel sync-googlemail-sent
Far :gmail-remote:"[Google Mail]/Gesendet"
Near :gmail-local:sent
Create Near

Channel sync-googlemail-trash
Far :gmail-remote:"[Google Mail]/Papierkorb"
Near :gmail-local:trash
Create Near

# Get all the channels together into a group.
Group googlemail
Channel sync-googlemail-default
Channel sync-googlemail-sent
Channel sync-googlemail-trash
}}

As you can see, name-translations are possible this way as well.

== Usage ==

First make any folders that were specified as Maildirs:

$ mkdir -p ~/.mail/gmail

Then to retrieve the mail for a specific channel run:

$ mbsync gmail

or to retrieve the mail for all channels:

$ mbsync -a

== Tips and tricks ==

=== Using Path and/or Inbox on NTFS partitions ===

Since NTFS partitions will not accept a semicolon in a filename, you need to change your InfoDelimiter and your FieldDelimiter to something else, you can achieve this by globaly (outside any store or channel configuration) changing the later, like below:

{{hc|~/.mbsyncrc|2=
FieldDelimiter -
}}

=== Importing EML emails ===

Importing emails in the [[Wikipedia:Email#Filename_extensions|EML]] format is achieved by copying the {{ic|.eml}} files under the {{ic|cur}} directory of the desired [[Wikipedia:Maildir|Maildir]] directory.
For example, using {{ic|mv message.eml ~/.mail/''myaccount''/Inbox}}.
The new emails should be detected during the subsequent run of {{ic|mbsync}}.

=== Calling mbsync automatically ===

==== With a timer ====

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:

{{hc|~/.config/systemd/user/mbsync.service|2=
[Unit]
Description=Mailbox synchronization service

[Service]
Type=oneshot
ExecStart=/usr/bin/mbsync -Va

[Install]
WantedBy=default.target
}}

The following timer configures {{ic|mbsync}} to be started 2 minutes after boot, and then every 5 minutes:

{{hc|~/.config/systemd/user/mbsync.timer|2=
[Unit]
Description=Mailbox synchronization timer

[Timer]
OnBootSec=2m
OnUnitActiveSec=5m
Unit=mbsync.service

[Install]
WantedBy=timers.target
}}

Once those two files are created, [[reload]] systemd, then [[enable]] and [[start]] {{ic|mbsync.timer}}, adding the {{ic|--user}} flag to {{ic|systemctl}}.

{{Tip|The mbsync service now only runs after login. It is also possible to launch the systemd-user instances after boot if you configure [[Systemd/User#Automatic start-up of systemd user instances]].
}}

===== Integration with notmuch or mu4e =====

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:

{{hc|~/.config/systemd/user/mbsync.service|2=
[Unit]
Description=Mailbox synchronization service

[Service]
Type=oneshot
ExecStart=/usr/bin/mbsync -Va
ExecStartPost=/usr/bin/notmuch new
}}

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}}.

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!

Trigger syncing immediately when making local changes (such as marking messages as read) by watching the {{ic|.notmuch}} directory:

{{hc|~/.config/systemd/user/mbsync.path|2=
[Path]
PathChanged=%h/mail/.notmuch

[Install]
WantedBy=default.target
}}

Systemd defaults ensure that the service will not trigger redundantly.

==== With imapnotify ====

[[Wikipedia:IMAP IDLE|IMAP IDLE]] is a way to get [[Wikipedia:Push Technology|push notifications]] to download new email, rather than polling the server intermittently. This has the advantage of saving bandwidth and delivering your mail as soon as it is available. Isync does not have native IDLE support, but we can use a program like [https://www.npmjs.com/package/imapnotify imapnotify] to call mbsync when you receive new email. For this example we will use the {{Pkg|goimapnotify}} package which is reported to work better with frequent network interruptions.

Install {{Pkg|goimapnotify}} and create a configuration file for each mail server you want to poll. Note that the file name format, including the ''.yaml'', is necessary if you want to use the provided systemd service:
{{hc|~/.config/imapnotify/gmail.yaml|<nowiki>
{
"host": "imap.gmail.com",
"port": 993,
"tls": true,
"tlsOptions": {
"rejectUnauthorized": false
},
"username": "username@gmail.com",
"password": "",
"passwordCmd": "pass gmail | head -n1",
"onNewMail": "mbsync gmail",
"onNewMailPost": "",
"boxes": [ "INBOX" ]
}
</nowiki>}}
(You can view the full configuration options in the project's [https://gitlab.com/shackra/goimapnotify README].)

[[Start/enable]] the {{ic|goimapnotify@gmail.service}} [[user unit]].

Note that IMAP IDLE only triggers when new mail arrives, not when there is undownloaded mail on the server. For example, if you receive 100 emails with your computer powered off, then turn on your computer, imapnotify will still not download new mail until you receive another email. For this reason you may want to run mbsync [[Autostarting|once when you log in]].

=== Using XOAUTH2 ===

First install an XOAUTH2 SASL plugin, like {{AUR|cyrus-sasl-xoauth2-git}}.

For all OAuth2 helpers listed below, choose either one among them, you need to provide a {{ic|client_id}} and optionally a {{ic|client_secret}} of your own or of a suitable FOSS registered application.

In order to get a {{ic|client_id}} and {{ic|client_secret}}, you will need an app registration with the provider. You should create your own app registration if possible, otherwise, for example due to missing rights, you can use existing app registrations, such as [https://hg.mozilla.org/comm-central/file/tip/mailnews/base/src/OAuth2Providers.sys.mjs Thunderbird's] (under {{ic|kIssuers}}) or [https://github.com/harishkrupo/oauth2ms/issues/15 Evolution's], which are publicly available until dynamic client registration is supported.

Another option is to temporarily use an incognito browser window to create a free outlook.com account and use that to create the app registration.

==== oama ====

[https://github.com/pdobsan/oama oama] is a utility which provides IMAP/SMTP clients with renewal capabilities and authorization of OAuth2 credentials. [[install]] {{AUR|oama-bin}} and configure it according to its [https://github.com/pdobsan/oama README].
You can find configuration templates in {{ic|/usr/share/oama}}.

Before you are able to use oama with your credentials you need to authorize OAuth2 access by running the command below:

$ oama authorize ''service'' ''email''

Where ''service'' is your email provider (e.g. ''google'') and ''email'' is your email address.

After the authorization completed add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "oama access ''email''"}} to the {{ic|IMAPAccount}} section in the {{ic|.mbsyncrc}}.

==== oauth2token ====

Install {{AUR|oauth2token}} and follow its [https://pypi.org/project/oauth2token/ README] to configure the account. It will be responsible for getting the current XOAUTH2 token using the account credentials every time mbsync needs to authenticate.

Finally, add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "oauth2get ''provider'' ''account''"}}, substituting {{ic|''provider''}} and {{ic|''account''}} with the values you used for {{ic|oauth2create}}, to the {{ic|IMAPAccount}} section in the {{ic|.mbsyncrc}}.

==== mutt_oauth2.py ====

{{ic|mutt_oauth2.py}} is known to work with Google and Microsoft accounts. Download {{AUR|mutt_oauth2.py}} and follow its [https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py.README README] for background and to configure the account.

In short, you will need to modify the {{ic|ENCRYPTION_PIPE}} and {{ic|DECRYPTION_PIPE}} for your preferred encryption system directly in script's source or specify them on each subsequent renew invocation using flags. During authorization, add the {{ic|client_id}} and {{ic|client_secret}} from an app registration with the provider (see [[#Using XOAUTH2]]). Then to initialize your tokens, you run and answer the questions in:

$ mutt_oauth2.py userid@myschool.edu.tokens --verbose --authorize

Note that gmail only supports the {{ic|localhostauthcode}} authflow while MS only supports the {{ic|authcode}} authflow.

To subsequently receive your access token (the script automatically handles renewing of tokens), you can run:

$ mutt_oauth2.py userid@myschool.edu.tokens

As the {{ic|ENCRYPTION_PIPE}} and {{ic|DECRYPTION_PIPE}} options are not stored within the token file, you have to pass them separately if you do not want to hardcode your gpg key name in script's source:

$ mutt_oauth2.py userid@myschool.edu.tokens --encryption-pipe 'gpg --encrypt --recipient <gpg-key>'

Finally, add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "mutt_oauth2.py userid@myschool.edu.tokens"}}, with the correct paths if necessary, to the {{ic|IMAPAccount}} section in the {{ic|.mbsyncrc}}.

==== oauth2ms ====

{{ic|oauth2ms}} can be used to fetch oauth2 tokens from the Microsoft identity endpoint.
Additionally, it can encode the token in the XOAUTH2 format to be used as authentication in IMAP mail servers.

Install {{ic|oauth2ms}} as [https://github.com/harishkrupo/oauth2ms#installation indicated] and create a config file {{ic|$XDG_CONFIG_HOME/oauth2ms/config.json}} [https://github.com/harishkrupo/oauth2ms#usage containing] the {{ic| client_id}}.

Finally, add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "oauth2ms"}}, or the full path to {{ic|oauth2ms}} if necessary, to the {{ic|IMAPAccount}} section in {{ic|.mbsyncrc}}.

=== Integration with ProtonMail ===

[[Wikipedia:Proton Mail|Proton Mail]] solution for interfacing with conventional email clients is for the user to run a local IMAP/SMTP server that will communicate with ProtonMail servers -- it is known as ProtonMail Bridge and available in the {{Pkg|protonmail-bridge-core}} package.
Note that this software requires a running and working software implementing FreeDesktop.org's [https://specifications.freedesktop.org/secret-service-spec/latest/ Secret Service API] (''e.g.'', [[GNOME Keyring]] or [[Wikipedia:KeePassXC|KeePassXC]]) and [[gpg-agent]].

==== Bridge installation and configuration ====

1. Run the bridge and login using ProtonMail credentials:

$ protonmail-bridge-core --cli
>>> login
>>> info

2. To let IMAP clients accessing the local Bridge IMAP server, get the ProtonMail self-signed certificate:

$ openssl s_client -starttls imap -connect 127.0.0.1:1143 -showcerts

3. Manually copy lines between {{ic|-----BEGIN CERTIFICATE-----}} and {{ic|-----END CERTIFICATE-----}} and put them inside a file, ''e.g.'', {{ic|~/.config/protonmail/bridge-v3/cert.pem}}.

4. After checking that everything is working, stop the Bridge from the command-line and run it as a service:

$ systemctl --user enable --now protonmail-bridge.service

==== Isync configuration for interacting with Bridge ====

Configuring Isync to use ProtonMail Bridge as an IMAP server is possible using the following in your {{ic|~/.mbsyncrc}} configuration.
The following is a working example in a two-way sync between the local machine the ProtonMail account.

{{Note|In the following, only configuration that is special for ProtonMail will be commented.}}
{{Tip|The port can be obtained from the CLI interface of the ProtonMail Bridge binary.}}
{{Tip|In {{ic|Patterns}}, we ignore the {{ic|Labels/*}} directories since this is a directory hierarchy used internally by ProtonMail to store the labels/tags user settings.}}
{{Warning|In {{ic|Patterns}}, we ignore the {{ic|All Mail/*}} directory since this is a virtual view of all emails created by ProtonMail. As such, if not ignored, the IMAP library of Bridge ([https://github.com/ProtonMail/gluon Gluon]) will throw an [https://github.com/ProtonMail/gluon/issues/426 error about an IMAP CLOSE command] that is not allowed during the {{ic|Expunge}} operation of Isync.}}

IMAPStore proton-remote
Port 1143
Host 127.0.0.1
User ''YOUR_EMAIL''
PassCmd ''YOUR_PASSWORD''
TLSType STARTTLS
CertificateFile ''YOUR_CERTIFICATE_PATH''

MaildirStore proton-local
SubFolders Verbatim
Path ''~/PATH/TO/MAILBOX/''
Inbox ''~/PATH/TO/MAILBOX/Inbox''

Channel proton
Far :proton-remote:
Near :proton-local:
Patterns * !Labels* !"All Mail"
Create Both
Expunge Both
SyncState *

== Troubleshooting ==

=== SSL error ===

If you get the following error:

{{bc|
<nowiki>SSL error connecting imap.gmail.com (108.177.125.109:993): self signed certificate</nowiki>
}}

Since google enforce SNI when you use TLS 1.3, ensure to run at least isync v1.3.0
See https://sourceforge.net/p/isync/isync/merge-requests/2/ for more details

If you get certificate related errors like:

{{bc|
<nowiki>SSL error connecting pop.mail.com (193.222.111.111:143): error:00000012:lib(0):func(0):reason(18)</nowiki>
}}

you may need to retrieve the server's certificates manually in order for mbsync to correctly verify it.

==== Step #1: Get the certificates ====

{{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}}

{{bc|
<nowiki>$ mkdir ~/.cert
$ 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</nowiki>
}}

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:

{{bc|
<nowiki>$ mkdir ~/.cert
$ wget https://gist.githubusercontent.com/petRUShka/af96ae25ce8280729b9ea049b929f31d/raw/a79471ce8aee3f6d04049039adf870a53a524f7f/get_certs.sh
$ sh get_certs.sh some.imap.server port ~/.cert/</nowiki>
}}

If you wish to do this manually, you may enter:

{{bc|
<nowiki>$ openssl s_client -connect some.imap.server:port -showcerts</nowiki>
}}

and it will display output something like:

{{bc|
<nowiki>CONNECTED(00000003)
depth=1 C = US, O = Google Inc, CN = Google Internet Authority
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=imap.gmail.com
i:/C=US/O=Google Inc/CN=Google Internet Authority
-----BEGIN CERTIFICATE-----
MIIDgDCCAumgAwIBAgIKO3MmiwAAAABopTANBgkqhkiG9w0BAQUFADBGMQswCQYD
VQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZR29vZ2xlIElu
dGVybmV0IEF1dGhvcml0eTAeFw0xMjA5MTIxMTU1NDlaFw0xMzA2MDcxOTQzMjda
MGgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1N
b3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRcwFQYDVQQDEw5pbWFw
LmdtYWlsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2OmU9DjI+DFQ
ThqIN4vL6EqZbzH0ejLKcc+zhxsq9BU5hXohSJ1sS5FUU2vReDKk8fd+ZR3cWtpf
CTYAUSvdnz1ZFjESSzyUBmGRqByhoc0yqdfb61NosA4CDaO+z7DtAgKyecqnAJad
TPYYf9aLk/UgJuc6GseitjzFYonXi6ECAwEAAaOCAVEwggFNMB0GA1UdJQQWMBQG
CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQUFuLyTg2NcsyaEESytZbLbQan
YIowHwYDVR0jBBgwFoAUv8Aw6/VDET5nup6R+/xq2uNrEiQwWwYDVR0fBFQwUjBQ
oE6gTIZKaHR0cDovL3d3dy5nc3RhdGljLmNvbS9Hb29nbGVJbnRlcm5ldEF1dGhv
cml0eS9Hb29nbGVJbnRlcm5ldEF1dGhvcml0eS5jcmwwZgYIKwYBBQUHAQEEWjBY
MFYGCCsGAQUFBzAChkpodHRwOi8vd3d3LmdzdGF0aWMuY29tL0dvb2dsZUludGVy
bmV0QXV0aG9yaXR5L0dvb2dsZUludGVybmV0QXV0aG9yaXR5LmNydDAMBgNVHRMB
Af8EAjAAMBkGA1UdEQQSMBCCDmltYXAuZ21haWwuY29tMA0GCSqGSIb3DQEBBQUA
A4GBAC1LV7tM6pcyVJLcwdPml4DomtowsjTrqvy5ZFa3SMKANK0iZBgFu74O0THX
8SxP/vn4eAs0yRQxcT1ZuoishLGQl5NoimLaQ4BGQnzFQHDJendfaVKDl21GenJp
is72sIrAeprsVU8PbNsllUamWsIjKr3DH5xQdH54hDtzQojY
-----END CERTIFICATE-----
1 s:/C=US/O=Google Inc/CN=Google Internet Authority
i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority
-----BEGIN CERTIFICATE-----
MIICsDCCAhmgAwIBAgIDC2dxMA0GCSqGSIb3DQEBBQUAME4xCzAJBgNVBAYTAlVT
MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0
aWZpY2F0ZSBBdXRob3JpdHkwHhcNMDkwNjA4MjA0MzI3WhcNMTMwNjA3MTk0MzI3
WjBGMQswCQYDVQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZ
R29vZ2xlIEludGVybmV0IEF1dGhvcml0eTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw
gYkCgYEAye23pIucV+eEPkB9hPSP0XFjU5nneXQUr0SZMyCSjXvlKAy6rWxJfoNf
NFlOCnowzdDXxFdF7dWq1nMmzq0yE7jXDx07393cCDaob1FEm8rWIFJztyaHNWrb
qeXUWaUr/GcZOfqTGBhs3t0lig4zFEfC7wFQeeT9adGnwKziV28CAwEAAaOBozCB
oDAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFL/AMOv1QxE+Z7qekfv8atrjaxIk
MB8GA1UdIwQYMBaAFEjmaPkr0rKV10fYIyAQTzOYkJ/UMBIGA1UdEwEB/wQIMAYB
Af8CAQAwOgYDVR0fBDMwMTAvoC2gK4YpaHR0cDovL2NybC5nZW90cnVzdC5jb20v
Y3Jscy9zZWN1cmVjYS5jcmwwDQYJKoZIhvcNAQEFBQADgYEAuIojxkiWsRF8YHde
BZqrocb6ghwYB8TrgbCoZutJqOkM0ymt9e8kTP3kS8p/XmOrmSfLnzYhLLkQYGfN
0rTw8Ktx5YtaiScRhKqOv5nwnQkhClIZmloJ0pC3+gz4fniisIWvXEyZ2VxVKfml
UUIuOss4jHg7y/j7lYe8vJD5UDI=
-----END CERTIFICATE-----
---
Server certificate
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=imap.gmail.com
issuer=/C=US/O=Google Inc/CN=Google Internet Authority
---
No client certificate CA names sent
---
SSL handshake has read 2108 bytes and written 350 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-RC4-SHA
Server public key is 1024 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : TLSv1.1
Cipher : ECDHE-RSA-RC4-SHA
Session-ID: 77136647F42633D82DEDFBB9EB62AB516547A3697D83BD1884726034613C1C09
Session-ID-ctx:
Master-Key: 635957FBA0762B10694560488905F73BDD2DB674C41970542ED079446F27234E2CA51CF26938B8CA56DF5BBC71E429A7
Key-Arg : None
PSK identity: None
PSK identity hint: None
SRP username: None
TLS session ticket lifetime hint: 100800 (seconds)
TLS session ticket:
0000 - d6 5b a0 a7 10 0e 64 04-72 93 7c 9f 94 fa 07 57 .[....d.r.|....W
0010 - f1 8b 9d 24 8b 9d 1b f3-a8 b1 4d 2c a9 00 e1 82 ...$......M,....
0020 - 00 83 1e 3f e5 f2 b2 2c-d2 a8 87 83 16 02 0d 1e ...?...,........
0030 - bf b6 c1 d6 75 21 04 e6-63 6b ab 5b ed 94 7a 30 ....u!..ck.[..z0
0040 - 1a d0 aa 44 c2 04 9b 10-06 28 b5 7b a0 43 a6 0d ...D.....(.{.C..
0050 - 3b 4a 85 1f 2e 07 0a e1-32 9b bd 5d 65 41 4c e2 ;J......2..]eAL.
0060 - 7c d7 43 ec c4 18 77 53-b5 d4 84 b4 c9 bd 51 d6 |.C...wS......Q.
0070 - 2d 4f 2e 10 a6 ed 38 c5-8e 9d f8 8b 8a 63 3f 7b -O....8......c?{
0080 - ee e6 b8 bf 7a f8 b8 e8-47 92 84 f1 9b 0c 63 30 ....z...G.....c0
0090 - 76 d8 e1 44 v..D

Start Time: 1352632558
Timeout : 300 (sec)
Verify return code: 20 (unable to get local issuer certificate)
---
* OK Gimap ready for requests from 108.78.162.240 o67if11168976yhc.67</nowiki>
}}

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.

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.

{{bc|
<nowiki>$ cp /usr/share/ca-certificates/mozilla/Equifax_Secure_CA.crt ~/.cert/Equifax_Secure_CA.pem</nowiki>
}}

==== Step #2: Setup mbsync ====

Configure mbsync to use that certificate:

{{hc|~/.mbsyncrc|2=
<nowiki>IMAPAccount gmail
Host imap.gmail.com
# ...
CertificateFile ~/.cert/imap.gmail.com.pem</nowiki>
}}

=== BAD Command with Exchange 2003 ===

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:

{{hc|mbsync -V exchange|
<nowiki>>>> 9 SELECT "arch"^M
* 250 EXISTS
* 0 RECENT
* FLAGS (\Seen \Answered \Flagged \Deleted \Draft $MDNSent)
* OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft $MDNSent)] Permanent flags
* OK [UNSEEN 241] Is the first unseen message
* OK [UIDVALIDITY 4352] UIDVALIDITY value
9 OK [READ-WRITE] SELECT completed.
>>> 10 UID FETCH 1:1000000000 (UID FLAGS)^M
* 1 FETCH (UID 1 FLAGS (\Seen \Answered))
* 2 FETCH (UID 2 FLAGS (\Seen \Answered))
...
* 249 FETCH (UID 696 FLAGS ())
* 250 FETCH (UID 697 FLAGS (\Seen))
10 OK FETCH completed.
>>> 11 APPEND "arch" (\Seen) {4878+}^M
(1 in progress) >>> 12 UID FETCH 697 (BODY.PEEK[])^M
(2 in progress) >>> 13 UID STORE 696 +FLAGS.SILENT (\Deleted)^M
12 BAD Command is not valid in this state.</nowiki>
}}

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

PipelineDepth 1

in the IMAPStore config part of the Exchange, this problem did not occur any more.

=== Emails on remote server have the wrong date ===

This fix works when syncing with fastmail, but it likely applies to other services as well.

If you move an email to a new folder using an email client, and mbsync causes the email to appear with the wrong date on the server, add this to your configuration file:

CopyArrivalDate yes

For example, without this setting, moving an old email from Inbox to Archive using mu4e and then
syncing to fastmail with mbsync will cause the email to appear in Archive but with the date of
the sync.

mbsync uses mtime of email message when uploading from maildir to imap server. You can use [https://gist.github.com/artizirk/877ce9d30159323aac037e2a2af74509 fix_maildir_mail_mtime.py] script to set mtime from email header.

== External links ==

*[https://isync.sourceforge.net/ Home page]
*[https://sourceforge.net/projects/isync/ Sourceforge page]
*[https://web.archive.org/web/20230830054154/https://kevin.deldycke.com/2012/08/gmail-backup-mbsync/ backing up gmail with mbsync]
*[https://www.cyberciti.biz/faq/test-ssl-certificates-diagnosis-ssl-certificate/ How To Verify SSL Certificate From A Shell Prompt]

Isync

2026-05-10T15:35:51Z

Indigo: /* Configuring */ remove outdated note bullet about gmail, move out of date template to example with respective info added from the bullet

{{Lowercase title}}
[[Category:Mail retrieval agents]]
[[Category:OpenPGP]]
[[ja:Isync]]
[https://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.

Synchronization is based on unique message identifiers (UIDs), so no identification conflicts can occur (as opposed to some other mail synchronizers).
Synchronization state is kept in one local text file per mailbox pair; multiple replicas of a mailbox can be maintained.
{{note|isync is the name of the project, mbsync is the name of the executable}}

== Installing ==

[[Install]] the {{Pkg|isync}} package.

== Configuring ==

{{Note|
'''Subfolders''' setting in MaildirStore now seems to be required to be set: [https://isync.sourceforge.net/mbsync.html iSync Config SubFolders] '''SubFolders Legacy''' worked as previous unset - Oct 2017
}}

First, a main configuration file needs to be created, either as {{ic|isyncrc}} in the user's {{ic|XDG_CONFIG_HOME}} directory, or {{ic|.mbsyncrc}} in the user's home directory root. The package supplies an example {{ic|/usr/share/doc/isync/examples/mbsyncrc.sample}} file. Another example for a Google-mail account is as follows:

{{Out of date|The access to Gmail with [https://myaccount.google.com/lesssecureapps lesssecureapps] is no longer possible without two-factor authentication. The example needs to be updated for an [https://myaccount.google.com/apppasswords an app password], or another provider. For Gmail, [[#Using XOAUTH2]] is another option.}}

{{hc|~/.mbsyncrc|
IMAPAccount gmail
# Address to connect to
Host imap.gmail.com
User ''username''@gmail.com
Pass ***************
# To store the password in an encrypted file use PassCmd instead of Pass
# PassCmd "gpg2 -q --for-your-eyes-only --no-tty -d ~/.mailpass.gpg"
#
# Use TLS
TLSType IMAPS
# The following line should work. If you get certificate errors, uncomment the two following lines and read the "Troubleshooting" section.
CertificateFile /etc/ssl/certs/ca-certificates.crt
#CertificateFile ~/.cert/imap.gmail.com.pem
#CertificateFile ~/.cert/Equifax_Secure_CA.pem

IMAPStore gmail-remote
Account gmail

MaildirStore gmail-local
SubFolders Verbatim
# The trailing "/" is important
Path ~/.mail/gmail/
Inbox ~/.mail/gmail/Inbox

Channel gmail
Far :gmail-remote:
Near :gmail-local:
# Exclude everything under the internal [Gmail] folder, except the interesting folders
Patterns * ![Gmail]* "[Gmail]/Sent Mail" "[Gmail]/Starred" "[Gmail]/All Mail"
# Or include everything
#Patterns *
# Automatically create missing mailboxes, both locally and on the server
Create Both
# Sync the movement of messages between folders and deletions, add after making sure the sync works
Expunge Both
# Save the synchronization state files in the relevant directory
SyncState *
}}

It is possible to avoid the proprietary {{ic|[Gmail]}} (or {{ic|[Google Mail]}}) folder categorization by using separate channels for each directory, and later merging them to a group:
{{hc|~/.mbsyncrc|
Channel sync-googlemail-default
Far :gmail-remote:
Near :gmail-local:
# Select some mailboxes to sync
Patterns "INBOX" "arch"
Create Both

Channel sync-googlemail-sent
Far :gmail-remote:"[Google Mail]/Gesendet"
Near :gmail-local:sent
Create Near

Channel sync-googlemail-trash
Far :gmail-remote:"[Google Mail]/Papierkorb"
Near :gmail-local:trash
Create Near

# Get all the channels together into a group.
Group googlemail
Channel sync-googlemail-default
Channel sync-googlemail-sent
Channel sync-googlemail-trash
}}

As you can see, name-translations are possible this way as well.

== Usage ==

First make any folders that were specified as Maildirs:

$ mkdir -p ~/.mail/gmail

Then to retrieve the mail for a specific channel run:

$ mbsync gmail

or to retrieve the mail for all channels:

$ mbsync -a

== Tips and tricks ==

=== Using Path and/or Inbox on NTFS partitions ===

Since NTFS partitions will not accept a semicolon in a filename, you need to change your InfoDelimiter and your FieldDelimiter to something else, you can achieve this by globaly (outside any store or channel configuration) changing the later, like below:

{{hc|~/.mbsyncrc|2=
FieldDelimiter -
}}

=== Importing EML emails ===

Importing emails in the [[Wikipedia:Email#Filename_extensions|EML]] format is achieved by copying the {{ic|.eml}} files under the {{ic|cur}} directory of the desired [[Wikipedia:Maildir|Maildir]] directory.
For example, using {{ic|mv message.eml ~/.mail/''myaccount''/Inbox}}.
The new emails should be detected during the subsequent run of {{ic|mbsync}}.

=== Calling mbsync automatically ===

==== With a timer ====

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:

{{hc|~/.config/systemd/user/mbsync.service|2=
[Unit]
Description=Mailbox synchronization service

[Service]
Type=oneshot
ExecStart=/usr/bin/mbsync -Va

[Install]
WantedBy=default.target
}}

The following timer configures {{ic|mbsync}} to be started 2 minutes after boot, and then every 5 minutes:

{{hc|~/.config/systemd/user/mbsync.timer|2=
[Unit]
Description=Mailbox synchronization timer

[Timer]
OnBootSec=2m
OnUnitActiveSec=5m
Unit=mbsync.service

[Install]
WantedBy=timers.target
}}

Once those two files are created, [[reload]] systemd, then [[enable]] and [[start]] {{ic|mbsync.timer}}, adding the {{ic|--user}} flag to {{ic|systemctl}}.

{{Tip|The mbsync service now only runs after login. It is also possible to launch the systemd-user instances after boot if you configure [[Systemd/User#Automatic start-up of systemd user instances]].
}}

===== Integration with notmuch or mu4e =====

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:

{{hc|~/.config/systemd/user/mbsync.service|2=
[Unit]
Description=Mailbox synchronization service

[Service]
Type=oneshot
ExecStart=/usr/bin/mbsync -Va
ExecStartPost=/usr/bin/notmuch new
}}

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}}.

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!

Trigger syncing immediately when making local changes (such as marking messages as read) by watching the {{ic|.notmuch}} directory:

{{hc|~/.config/systemd/user/mbsync.path|2=
[Path]
PathChanged=%h/mail/.notmuch

[Install]
WantedBy=default.target
}}

Systemd defaults ensure that the service will not trigger redundantly.

==== With imapnotify ====

[[Wikipedia:IMAP IDLE|IMAP IDLE]] is a way to get [[Wikipedia:Push Technology|push notifications]] to download new email, rather than polling the server intermittently. This has the advantage of saving bandwidth and delivering your mail as soon as it is available. Isync does not have native IDLE support, but we can use a program like [https://www.npmjs.com/package/imapnotify imapnotify] to call mbsync when you receive new email. For this example we will use the {{Pkg|goimapnotify}} package which is reported to work better with frequent network interruptions.

Install {{Pkg|goimapnotify}} and create a configuration file for each mail server you want to poll. Note that the file name format, including the ''.yaml'', is necessary if you want to use the provided systemd service:
{{hc|~/.config/imapnotify/gmail.yaml|<nowiki>
{
"host": "imap.gmail.com",
"port": 993,
"tls": true,
"tlsOptions": {
"rejectUnauthorized": false
},
"username": "username@gmail.com",
"password": "",
"passwordCmd": "pass gmail | head -n1",
"onNewMail": "mbsync gmail",
"onNewMailPost": "",
"boxes": [ "INBOX" ]
}
</nowiki>}}
(You can view the full configuration options in the project's [https://gitlab.com/shackra/goimapnotify README].)

[[Start/enable]] the {{ic|goimapnotify@gmail.service}} [[user unit]].

Note that IMAP IDLE only triggers when new mail arrives, not when there is undownloaded mail on the server. For example, if you receive 100 emails with your computer powered off, then turn on your computer, imapnotify will still not download new mail until you receive another email. For this reason you may want to run mbsync [[Autostarting|once when you log in]].

=== Using XOAUTH2 ===

First install an XOAUTH2 SASL plugin, like {{AUR|cyrus-sasl-xoauth2-git}}.

For all OAuth2 helpers listed below, choose either one among them, you need to provide a {{ic|client_id}} and optionally a {{ic|client_secret}} of your own or of a suitable FOSS registered application.

In order to get a {{ic|client_id}} and {{ic|client_secret}}, you will need an app registration with the provider. You should create your own app registration if possible, otherwise, for example due to missing rights, you can use existing app registrations, such as [https://hg.mozilla.org/comm-central/file/tip/mailnews/base/src/OAuth2Providers.sys.mjs Thunderbird's] (under {{ic|kIssuers}}) or [https://github.com/harishkrupo/oauth2ms/issues/15 Evolution's], which are publicly available until dynamic client registration is supported.

Another option is to temporarily use an incognito browser window to create a free outlook.com account and use that to create the app registration.

==== oama ====

[https://github.com/pdobsan/oama oama] is a utility which provides IMAP/SMTP clients with renewal capabilities and authorization of OAuth2 credentials. [[install]] {{AUR|oama-bin}} and configure it according to its [https://github.com/pdobsan/oama README].
You can find configuration templates in {{ic|/usr/share/oama}}.

Before you are able to use oama with your credentials you need to authorize OAuth2 access by running the command below:

$ oama authorize ''service'' ''email''

Where ''service'' is your email provider (e.g. ''google'') and ''email'' is your email address.

After the authorization completed add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "oama access ''email''"}} to the {{ic|IMAPAccount}} section in the {{ic|.mbsyncrc}}.

==== oauth2token ====

Install {{AUR|oauth2token}} and follow its [https://pypi.org/project/oauth2token/ README] to configure the account. It will be responsible for getting the current XOAUTH2 token using the account credentials every time mbsync needs to authenticate.

Finally, add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "oauth2get ''provider'' ''account''"}}, substituting {{ic|''provider''}} and {{ic|''account''}} with the values you used for {{ic|oauth2create}}, to the {{ic|IMAPAccount}} section in the {{ic|.mbsyncrc}}.

==== mutt_oauth2.py ====

{{ic|mutt_oauth2.py}} is known to work with Google and Microsoft accounts. Download {{AUR|mutt_oauth2.py}} and follow its [https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py.README README] for background and to configure the account.

In short, you will need to modify the {{ic|ENCRYPTION_PIPE}} and {{ic|DECRYPTION_PIPE}} for your preferred encryption system directly in script's source or specify them on each subsequent renew invocation using flags. During authorization, add the {{ic|client_id}} and {{ic|client_secret}} from an app registration with the provider (see [[#Using XOAUTH2]]). Then to initialize your tokens, you run and answer the questions in:

$ mutt_oauth2.py userid@myschool.edu.tokens --verbose --authorize

Note that gmail only supports the {{ic|localhostauthcode}} authflow while MS only supports the {{ic|authcode}} authflow.

To subsequently receive your access token (the script automatically handles renewing of tokens), you can run:

$ mutt_oauth2.py userid@myschool.edu.tokens

As the {{ic|ENCRYPTION_PIPE}} and {{ic|DECRYPTION_PIPE}} options are not stored within the token file, you have to pass them separately if you do not want to hardcode your gpg key name in script's source:

$ mutt_oauth2.py userid@myschool.edu.tokens --encryption-pipe 'gpg --encrypt --recipient <gpg-key>'

Finally, add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "mutt_oauth2.py userid@myschool.edu.tokens"}}, with the correct paths if necessary, to the {{ic|IMAPAccount}} section in the {{ic|.mbsyncrc}}.

==== oauth2ms ====

{{ic|oauth2ms}} can be used to fetch oauth2 tokens from the Microsoft identity endpoint.
Additionally, it can encode the token in the XOAUTH2 format to be used as authentication in IMAP mail servers.

Install {{ic|oauth2ms}} as [https://github.com/harishkrupo/oauth2ms#installation indicated] and create a config file {{ic|$XDG_CONFIG_HOME/oauth2ms/config.json}} [https://github.com/harishkrupo/oauth2ms#usage containing] the {{ic| client_id}}.

Finally, add {{ic|AuthMechs XOAUTH2}} and {{ic|PassCmd "oauth2ms"}}, or the full path to {{ic|oauth2ms}} if necessary, to the {{ic|IMAPAccount}} section in {{ic|.mbsyncrc}}.

=== Integration with ProtonMail ===

[[Wikipedia:Proton Mail|Proton Mail]] solution for interfacing with conventional email clients is for the user to run a local IMAP/SMTP server that will communicate with ProtonMail servers -- it is known as ProtonMail Bridge and available in the {{Pkg|protonmail-bridge-core}} package.
Note that this software requires a running and working software implementing FreeDesktop.org's [https://specifications.freedesktop.org/secret-service-spec/latest/ Secret Service API] (''e.g.'', [[GNOME Keyring]] or [[Wikipedia:KeePassXC|KeePassXC]]) and [[gpg-agent]].

==== Bridge installation and configuration ====

1. Run the bridge and login using ProtonMail credentials:

$ protonmail-bridge-core --cli
>>> login
>>> info

2. To let IMAP clients accessing the local Bridge IMAP server, get the ProtonMail self-signed certificate:

$ openssl s_client -starttls imap -connect 127.0.0.1:1143 -showcerts

3. Manually copy lines between {{ic|-----BEGIN CERTIFICATE-----}} and {{ic|-----END CERTIFICATE-----}} and put them inside a file, ''e.g.'', {{ic|~/.config/protonmail/bridge-v3/cert.pem}}.

4. After checking that everything is working, stop the Bridge from the command-line and run it as a service:

$ systemctl --user enable --now protonmail-bridge.service

==== Isync configuration for interacting with Bridge ====

Configuring Isync to use ProtonMail Bridge as an IMAP server is possible using the following in your {{ic|~/.mbsyncrc}} configuration.
The following is a working example in a two-way sync between the local machine the ProtonMail account.

{{Note|In the following, only configuration that is special for ProtonMail will be commented.}}
{{Tip|The port can be obtained from the CLI interface of the ProtonMail Bridge binary.}}
{{Tip|In {{ic|Patterns}}, we ignore the {{ic|Labels/*}} directories since this is a directory hierarchy used internally by ProtonMail to store the labels/tags user settings.}}
{{Warning|In {{ic|Patterns}}, we ignore the {{ic|All Mail/*}} directory since this is a virtual view of all emails created by ProtonMail. As such, if not ignored, the IMAP library of Bridge ([https://github.com/ProtonMail/gluon Gluon]) will throw an [https://github.com/ProtonMail/gluon/issues/426 error about an IMAP CLOSE command] that is not allowed during the {{ic|Expunge}} operation of Isync.}}

IMAPStore proton-remote
Port 1143
Host 127.0.0.1
User ''YOUR_EMAIL''
PassCmd ''YOUR_PASSWORD''
TLSType STARTTLS
CertificateFile ''YOUR_CERTIFICATE_PATH''

MaildirStore proton-local
SubFolders Verbatim
Path ''~/PATH/TO/MAILBOX/''
Inbox ''~/PATH/TO/MAILBOX/Inbox''

Channel proton
Far :proton-remote:
Near :proton-local:
Patterns * !Labels* !"All Mail"
Create Both
Expunge Both
SyncState *

== Troubleshooting ==

=== SSL error ===

If you get the following error:

{{bc|
<nowiki>SSL error connecting imap.gmail.com (108.177.125.109:993): self signed certificate</nowiki>
}}

Since google enforce SNI when you use TLS 1.3, ensure to run at least isync v1.3.0
See https://sourceforge.net/p/isync/isync/merge-requests/2/ for more details

If you get certificate related errors like:

{{bc|
<nowiki>SSL error connecting pop.mail.com (193.222.111.111:143): error:00000012:lib(0):func(0):reason(18)</nowiki>
}}

you may need to retrieve the server's certificates manually in order for mbsync to correctly verify it.

==== Step #1: Get the certificates ====

{{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}}

{{bc|
<nowiki>$ mkdir ~/.cert
$ 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</nowiki>
}}

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:

{{bc|
<nowiki>$ mkdir ~/.cert
$ wget https://gist.githubusercontent.com/petRUShka/af96ae25ce8280729b9ea049b929f31d/raw/a79471ce8aee3f6d04049039adf870a53a524f7f/get_certs.sh
$ sh get_certs.sh some.imap.server port ~/.cert/</nowiki>
}}

If you wish to do this manually, you may enter:

{{bc|
<nowiki>$ openssl s_client -connect some.imap.server:port -showcerts</nowiki>
}}

and it will display output something like:

{{bc|
<nowiki>CONNECTED(00000003)
depth=1 C = US, O = Google Inc, CN = Google Internet Authority
verify error:num=20:unable to get local issuer certificate
verify return:0
---
Certificate chain
0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=imap.gmail.com
i:/C=US/O=Google Inc/CN=Google Internet Authority
-----BEGIN CERTIFICATE-----
MIIDgDCCAumgAwIBAgIKO3MmiwAAAABopTANBgkqhkiG9w0BAQUFADBGMQswCQYD
VQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZR29vZ2xlIElu
dGVybmV0IEF1dGhvcml0eTAeFw0xMjA5MTIxMTU1NDlaFw0xMzA2MDcxOTQzMjda
MGgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1N
b3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRcwFQYDVQQDEw5pbWFw
LmdtYWlsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEA2OmU9DjI+DFQ
ThqIN4vL6EqZbzH0ejLKcc+zhxsq9BU5hXohSJ1sS5FUU2vReDKk8fd+ZR3cWtpf
CTYAUSvdnz1ZFjESSzyUBmGRqByhoc0yqdfb61NosA4CDaO+z7DtAgKyecqnAJad
TPYYf9aLk/UgJuc6GseitjzFYonXi6ECAwEAAaOCAVEwggFNMB0GA1UdJQQWMBQG
CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQUFuLyTg2NcsyaEESytZbLbQan
YIowHwYDVR0jBBgwFoAUv8Aw6/VDET5nup6R+/xq2uNrEiQwWwYDVR0fBFQwUjBQ
oE6gTIZKaHR0cDovL3d3dy5nc3RhdGljLmNvbS9Hb29nbGVJbnRlcm5ldEF1dGhv
cml0eS9Hb29nbGVJbnRlcm5ldEF1dGhvcml0eS5jcmwwZgYIKwYBBQUHAQEEWjBY
MFYGCCsGAQUFBzAChkpodHRwOi8vd3d3LmdzdGF0aWMuY29tL0dvb2dsZUludGVy
bmV0QXV0aG9yaXR5L0dvb2dsZUludGVybmV0QXV0aG9yaXR5LmNydDAMBgNVHRMB
Af8EAjAAMBkGA1UdEQQSMBCCDmltYXAuZ21haWwuY29tMA0GCSqGSIb3DQEBBQUA
A4GBAC1LV7tM6pcyVJLcwdPml4DomtowsjTrqvy5ZFa3SMKANK0iZBgFu74O0THX
8SxP/vn4eAs0yRQxcT1ZuoishLGQl5NoimLaQ4BGQnzFQHDJendfaVKDl21GenJp
is72sIrAeprsVU8PbNsllUamWsIjKr3DH5xQdH54hDtzQojY
-----END CERTIFICATE-----
1 s:/C=US/O=Google Inc/CN=Google Internet Authority
i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority
-----BEGIN CERTIFICATE-----
MIICsDCCAhmgAwIBAgIDC2dxMA0GCSqGSIb3DQEBBQUAME4xCzAJBgNVBAYTAlVT
MRAwDgYDVQQKEwdFcXVpZmF4MS0wKwYDVQQLEyRFcXVpZmF4IFNlY3VyZSBDZXJ0
aWZpY2F0ZSBBdXRob3JpdHkwHhcNMDkwNjA4MjA0MzI3WhcNMTMwNjA3MTk0MzI3
WjBGMQswCQYDVQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZ
R29vZ2xlIEludGVybmV0IEF1dGhvcml0eTCBnzANBgkqhkiG9w0BAQEFAAOBjQAw
gYkCgYEAye23pIucV+eEPkB9hPSP0XFjU5nneXQUr0SZMyCSjXvlKAy6rWxJfoNf
NFlOCnowzdDXxFdF7dWq1nMmzq0yE7jXDx07393cCDaob1FEm8rWIFJztyaHNWrb
qeXUWaUr/GcZOfqTGBhs3t0lig4zFEfC7wFQeeT9adGnwKziV28CAwEAAaOBozCB
oDAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFL/AMOv1QxE+Z7qekfv8atrjaxIk
MB8GA1UdIwQYMBaAFEjmaPkr0rKV10fYIyAQTzOYkJ/UMBIGA1UdEwEB/wQIMAYB
Af8CAQAwOgYDVR0fBDMwMTAvoC2gK4YpaHR0cDovL2NybC5nZW90cnVzdC5jb20v
Y3Jscy9zZWN1cmVjYS5jcmwwDQYJKoZIhvcNAQEFBQADgYEAuIojxkiWsRF8YHde
BZqrocb6ghwYB8TrgbCoZutJqOkM0ymt9e8kTP3kS8p/XmOrmSfLnzYhLLkQYGfN
0rTw8Ktx5YtaiScRhKqOv5nwnQkhClIZmloJ0pC3+gz4fniisIWvXEyZ2VxVKfml
UUIuOss4jHg7y/j7lYe8vJD5UDI=
-----END CERTIFICATE-----
---
Server certificate
subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=imap.gmail.com
issuer=/C=US/O=Google Inc/CN=Google Internet Authority
---
No client certificate CA names sent
---
SSL handshake has read 2108 bytes and written 350 bytes
---
New, TLSv1/SSLv3, Cipher is ECDHE-RSA-RC4-SHA
Server public key is 1024 bit
Secure Renegotiation IS supported
Compression: NONE
Expansion: NONE
SSL-Session:
Protocol : TLSv1.1
Cipher : ECDHE-RSA-RC4-SHA
Session-ID: 77136647F42633D82DEDFBB9EB62AB516547A3697D83BD1884726034613C1C09
Session-ID-ctx:
Master-Key: 635957FBA0762B10694560488905F73BDD2DB674C41970542ED079446F27234E2CA51CF26938B8CA56DF5BBC71E429A7
Key-Arg : None
PSK identity: None
PSK identity hint: None
SRP username: None
TLS session ticket lifetime hint: 100800 (seconds)
TLS session ticket:
0000 - d6 5b a0 a7 10 0e 64 04-72 93 7c 9f 94 fa 07 57 .[....d.r.|....W
0010 - f1 8b 9d 24 8b 9d 1b f3-a8 b1 4d 2c a9 00 e1 82 ...$......M,....
0020 - 00 83 1e 3f e5 f2 b2 2c-d2 a8 87 83 16 02 0d 1e ...?...,........
0030 - bf b6 c1 d6 75 21 04 e6-63 6b ab 5b ed 94 7a 30 ....u!..ck.[..z0
0040 - 1a d0 aa 44 c2 04 9b 10-06 28 b5 7b a0 43 a6 0d ...D.....(.{.C..
0050 - 3b 4a 85 1f 2e 07 0a e1-32 9b bd 5d 65 41 4c e2 ;J......2..]eAL.
0060 - 7c d7 43 ec c4 18 77 53-b5 d4 84 b4 c9 bd 51 d6 |.C...wS......Q.
0070 - 2d 4f 2e 10 a6 ed 38 c5-8e 9d f8 8b 8a 63 3f 7b -O....8......c?{
0080 - ee e6 b8 bf 7a f8 b8 e8-47 92 84 f1 9b 0c 63 30 ....z...G.....c0
0090 - 76 d8 e1 44 v..D

Start Time: 1352632558
Timeout : 300 (sec)
Verify return code: 20 (unable to get local issuer certificate)
---
* OK Gimap ready for requests from 108.78.162.240 o67if11168976yhc.67</nowiki>
}}

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.

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.

{{bc|
<nowiki>$ cp /usr/share/ca-certificates/mozilla/Equifax_Secure_CA.crt ~/.cert/Equifax_Secure_CA.pem</nowiki>
}}

==== Step #2: Setup mbsync ====

Configure mbsync to use that certificate:

{{hc|~/.mbsyncrc|2=
<nowiki>IMAPAccount gmail
Host imap.gmail.com
# ...
CertificateFile ~/.cert/imap.gmail.com.pem</nowiki>
}}

=== BAD Command with Exchange 2003 ===

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:

{{hc|mbsync -V exchange|
<nowiki>>>> 9 SELECT "arch"^M
* 250 EXISTS
* 0 RECENT
* FLAGS (\Seen \Answered \Flagged \Deleted \Draft $MDNSent)
* OK [PERMANENTFLAGS (\Seen \Answered \Flagged \Deleted \Draft $MDNSent)] Permanent flags
* OK [UNSEEN 241] Is the first unseen message
* OK [UIDVALIDITY 4352] UIDVALIDITY value
9 OK [READ-WRITE] SELECT completed.
>>> 10 UID FETCH 1:1000000000 (UID FLAGS)^M
* 1 FETCH (UID 1 FLAGS (\Seen \Answered))
* 2 FETCH (UID 2 FLAGS (\Seen \Answered))
...
* 249 FETCH (UID 696 FLAGS ())
* 250 FETCH (UID 697 FLAGS (\Seen))
10 OK FETCH completed.
>>> 11 APPEND "arch" (\Seen) {4878+}^M
(1 in progress) >>> 12 UID FETCH 697 (BODY.PEEK[])^M
(2 in progress) >>> 13 UID STORE 696 +FLAGS.SILENT (\Deleted)^M
12 BAD Command is not valid in this state.</nowiki>
}}

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

PipelineDepth 1

in the IMAPStore config part of the Exchange, this problem did not occur any more.

=== Emails on remote server have the wrong date ===

This fix works when syncing with fastmail, but it likely applies to other services as well.

If you move an email to a new folder using an email client, and mbsync causes the email to appear with the wrong date on the server, add this to your configuration file:

CopyArrivalDate yes

For example, without this setting, moving an old email from Inbox to Archive using mu4e and then
syncing to fastmail with mbsync will cause the email to appear in Archive but with the date of
the sync.

mbsync uses mtime of email message when uploading from maildir to imap server. You can use [https://gist.github.com/artizirk/877ce9d30159323aac037e2a2af74509 fix_maildir_mail_mtime.py] script to set mtime from email header.

== External links ==

*[https://isync.sourceforge.net/ Home page]
*[https://sourceforge.net/projects/isync/ Sourceforge page]
*[https://web.archive.org/web/20230830054154/https://kevin.deldycke.com/2012/08/gmail-backup-mbsync/ backing up gmail with mbsync]
*[https://www.cyberciti.biz/faq/test-ssl-certificates-diagnosis-ssl-certificate/ How To Verify SSL Certificate From A Shell Prompt]

Pass

2026-05-10T14:58:08Z

Indigo: /* Basic usage */ style fix, add crosslink on first mention

{{Lowercase title}}
[[Category:Password managers]]
[[Category:Console applications]]
[[Category:OpenPGP]]
[[ja:Pass]]
[[zh-hans:Pass]]
From [https://www.passwordstore.org/ the official website]:

:Password management should be simple and follow Unix philosophy. With pass, each password lives inside of a gpg encrypted file whose filename is the title of the website or resource that requires the password. These encrypted files may be organized into meaningful folder hierarchies, copied from computer to computer, and, in general, manipulated using standard command line file management utilities.

pass is a simple password manager for the command line. pass is a shell script that makes use of existing tools like [[GnuPG]], {{Pkg|tree}} and [[Git]].

== Installation ==

[[Install]] the {{Pkg|pass}} package.

An optional [[Qt]] GUI is available via the {{Pkg|qtpass}} package.

== Basic usage ==

{{Note|To be able to use ''pass'', set up [[GnuPG]]. The trust level of the key used for pass must be "ultimate".}}

To initialize the password store:

$ pass init ''gpg-id_or_email''

To create a new password, first provide a descriptive hierarchical name. In this example, this is ''archlinux.org/wiki/username'':

$ pass insert archlinux.org/wiki/username

To get a view of the password store do the following. Note the example output which shows the hierarchy we just created:

{{hc|$ pass|
Password Store
└── archlinux.org
└── wiki
└── username
}}

To generate a new random password for the above example, do the following, where {{ic|''n''}} is the desired password length as a number:

$ pass generate archlinux.org/wiki/username ''n''

To retrieve a password, enter the gpg passphrase at the following prompt, again using the example name from above:

$ pass archlinux.org/wiki/username

Users of Xorg with {{Pkg|xclip}} installed can retrieve the password directly onto the clipboard temporarily (e.g., to paste into web forms). In a Wayland session, should use {{Pkg|wl-clipboard}} instead. To do so, do the following (again with the same example hierarchical name from above):

$ pass -c archlinux.org/wiki/username

{{Note|Users preferring the classical middle-click/paste can add the following to their respective ~/.shellrc for this behavior: {{ic|1=export PASSWORD_STORE_X_SELECTION=primary}}}}

pass comes with a [[dmenu]] wrapper to enable easy searching/copying. To use it, install the optional dependency {{Pkg|dmenu}} and run:

$ passmenu

Then selecting an entry will copy its password to the clipboard. See {{man|1|dmenu}} for customization options such as case-insensitivity. You may want to set this to a systemwide keybinding in order to easily access passwords from any application.

== Data organization ==

By default, the credential file created with {{ic|pass insert}} will only contain your password. However, it may not be enough since several applications ask for detail data like username, url, etc.
You can edit an existing file the way you want with command {{ic|pass edit ''password_name''}}.
Below is the preferred organizational scheme provided by [https://www.passwordstore.org/ pass-project page]. When using the option {{ic|-c}} or {{ic|--clip}} with this scheme, only the password will be copied.

{{bc|
YwrZSNH35z164ym9pI
URL: *.amazon.com/*
Username: AmazonianChicken@example.com
Secret Question 1: What is your childhood best friend's most bizarre superhero fantasy? Oh god, Amazon, it's too awful to say...
Phone Support PIN #: 84719
}}

== Migrating to pass ==

There are multiple scripts listed on the [https://www.zx2c4.com/projects/password-store/ pass-project page] to import passwords from other programs

== Extensions ==

Since version 1.7, pass supports extensions developed by the community. These extensions extend the features of pass with the support of new commands.

* {{App|pass-audit|An extension for auditing a password repository.|https://github.com/roddhjav/pass-audit|{{AUR|pass-audit}}}}
* {{App|pass-coffin|A password store extension to hide data inside a signed and encrypted coffin|https://github.com/ayushnix/pass-coffin|{{AUR|pass-coffin}}}}
* {{App|pass-import|A generic importer tool from other password managers.|https://github.com/roddhjav/pass-import|{{AUR|pass-import}}}}
* {{App|pass-otp|Support for one-time-password (OTP) tokens.|https://github.com/tadfisher/pass-otp|{{Pkg|pass-otp}}}}
* {{App|pass-phrase|An extension for generating passphrases.|https://github.com/programadoroccidental/pass-phrase|{{AUR|pass-phrase}}}}
* {{App|pass-tessen|An Xorg/Wayland compatible command line fuzzy selection tool with copy and paste.|https://github.com/ayushnix/pass-tessen|{{AUR|pass-tessen}}}}
* {{App|pass-tomb|Manage the whole tree of your password store encrypted inside a [[tomb]].|https://github.com/roddhjav/pass-tomb|{{AUR|pass-tomb}}}}
* {{App|pass-update|An easy flow for updating passwords.|https://github.com/roddhjav/pass-update|{{AUR|pass-update}}}}
* {{App|passless|A FIDO2 authenticator backend ([[WebAuthn]], CTAP); store and use passkeys with your web browser.|https://github.com/pando85/passless|{{AUR|passless}}}}
* {{App|tessen|A bash script for Wayland extending compatibility to dmenu type applications such as rofi and fuzzel.|https://github.com/ayushnix/tessen|{{AUR|tessen}}}}

== Advanced usage ==

[[Environment variables]] can be used to alter where ''pass'' looks to do store and git operations via:
PASSWORD_STORE_DIR=/path/to/store

For more information on how this can be used to support multiple pass repositories see [https://lists.zx2c4.com/pipermail/password-store/2016-November/002463.html this link].
The following {{ic|pw()}} example alias sends the second line of the named database to the clipboard before sending the first line five seconds thereafter and finally an OTP code five seconds after that. Assuming that a password occupies the first line and a username the second line and an [https://github.com/google/google-authenticator/wiki/Key-Uri-Format OTP URI] exists anywhere in the named database, the net effect is passing ''username > password > otp code'' for consecutive primary pasting into available (e.g. browser) entry fields:

pw() {
export PASSWORD_STORE_CLIP_TIME=8
export PASSWORD_STORE_X_SELECTION=primary
pass -c2 $1; sleep 5; pass -c $1; sleep 5; pass otp -c $1; exit
}

== Multiple pass contexts (e.g. teaming) ==

One can use aliases to set up different pass contexts, which helps when collaborating with different teams. We have gotten this working in bash as follows:

Add aliases to your [[Command-line shell#Configuration files|shell configuration file]]:

alias passred="PASSWORD_STORE_DIR=~/.pass/red pass"
alias passblue="PASSWORD_STORE_DIR=~/.pass/blue pass"

If using bash, add these for bash-completion to your {{ic|~/.bash_completion}} and make sure {{Pkg|bash-completion}} is installed:

source /usr/share/bash-completion/completions/pass
_passred(){
PASSWORD_STORE_DIR=~/.pass/red/ _pass
}
complete -o filenames -o nospace -F _passred passred
_passblue(){
PASSWORD_STORE_DIR=~/.pass/blue/ _pass
}
complete -o filenames -o nospace -F _passblue passblue

Or for zsh (source: {{ic|/usr/share/zsh/site-functions/_pass}})

compdef _pass passred
zstyle ':completion::complete:passred::' prefix "$HOME/.pass/red"
passred() {
PASSWORD_STORE_DIR=$HOME/.pass/red pass $@
}
compdef _pass passblue
zstyle ':completion::complete:passblue::' prefix "$HOME/.pass/blue"
passblue() {
PASSWORD_STORE_DIR=$HOME/.pass/blue pass $@
}

Now you can initialize into {{ic|''~/.pass/red''}} and {{ic|''~/.pass/blue''}} and have two pass contexts with the {{ic|''passred''}} and {{ic|''passblue''}} aliases. You can generalize this further into as many contexts as you like.

== Git integration ==

=== Git helper usage ===

You can use {{ic|pass}} as a credentials helper for {{ic|git}}. [[Install]] the {{Aur|pass-git-helper}}.
Details are described in the [https://github.com/languitar/pass-git-helper github README file].

==== git configuration ====

Configure {{ic|pass-git-helper}} as a git credentials helper by calling:
$ git config --global credential.helper /usr/bin/pass-git-helper

==== Mapping file ====

Create the file {{ic|~/.config/pass-git-helper/git-pass-mapping.ini}}. It is used to map git remote hosts to your {{ic|pass}} database. The format is something like this:

{{bc|code=[github.com]
target=dev/github

[*.fooo-bar.*]
target=dev/fooo-bar
}}

You can use wildcards in the host part, as shown in the example.

==== Password store layout ====

As usual with pass, the helper assumes that the password is contained in the first line of the passwordstore entry.
Additionally, if a second line is present, this line is interpreted as the username.

For this to work, you have to use {{ic|pass insert --multiline}} to create a multi line password store entry.

=== Central Git server for pass in combination with GnuPG (SSH example) ===

You are able to setup a password management system by setting up a central Git server for pass. This allows you to synchronize your central password repository through multiple client environments.

==== Install a bare Git repository for pass on the server ====

On the server run {{ic|git init --bare ~/.password-store}} to create a bare repository you can push to.

==== Import authorized public SSH keys ====

See [[SSH keys#Copying the public key to the remote server]]

==== On the client ====

This section assumes you have configured GnuPG and have a key pair to encrypt passwords.
On your local client ensure you have a local password store on the client, then enable management of local changes through Git, add your remote Git repository, and push your local pass history.

Create a local password store:

$ pass init ''gpg_key_id''

Enable management of local changes through Git:

$ pass git init

Add the remote git repository as 'origin':

$ pass git remote add origin user@server:~/.password-store

Push your local pass history:

$ pass git push -u --all

Now you can use the standard Git commands, prefixed by {{ic|pass}}. For example: {{ic|pass git push}}, or {{ic|pass git pull}}. pass will automatically create commits when you use it to modify your password store.

== Troubleshooting ==

=== Encryption failed: Unusable public key ===

The following error can occur when attempting to insert a new entry:

{{hc|$ pass insert archlinux.org/wiki/username|
Enter password for archlinux.org/wiki/username:
Retype password for archlinux.org/wiki/username:
gpg: XXXXXXXXX: There is no assurance this key belongs to the named user
gpg: [stdin]: encryption failed: Unusable public key
Password encryption aborted.
}}

This occurs if the trust level of the GnuPG key is set to anything other than "ultimate". Edit the key used for {{ic|pass}} to set its trust level to "ultimate":

{{hc|$ gpg --edit-key ''your_key_id''|
> trust
> 5
}}
=== Secret key expired ===

The following error can occur when your GPG key expires (e.g., after a year) and you try to add a new password:

{{bc|
gpg: Note: secret key 0xAAAABBBBCCCCDDEE expired at Thu 09 Jan 2020 01:15:15 PM UTC
gpg: AAAABBBBCCCCDDEE: skipped: Unusable public key
}}

To fix this, either [[GnuPG#Extending expiration date|extend the current GPG key's expiration date]] or switch to a new one (i.e., key rotation).

To switch to a new key and re-encrypt the store:

$ pass init ''new_gpg-id_or_email''

== See also ==

* [https://web.archive.org/web/20230527122558/https://blog.sanctum.geek.nz/gnu-linux-crypto-passwords/ A more comprehensive pass tutorial]
* [https://www.passwordstore.org/ pass home page]
* [https://www.passwordstore.org/#other List of Compatible clients and possibilities for migration to pass]

Electron package guidelines

2026-05-10T14:41:31Z

Indigo: /* Using electron-builder with system electron */ move disjunct accuracy template up over command, add question and link to talk item (I suppose both are discussing the same topic)

[[Category:Arch package guidelines]]
[[ja:Electron パッケージガイドライン]]
[[pt:Electron package guidelines]]
{{Package guidelines}}

This document covers standards and guidelines on writing [[PKGBUILD]]s for [[Electron]].

== Using the system electron ==

Arch Linux provides versioned [https://archlinux.org/packages/?q=electron electron*] packages and an {{Pkg|electron}} metapackage for the latest version. They can be used to run an electron application via a shell script wrapper:

{{bc|#!/bin/sh

exec /usr/bin/electron34 /path/to/''appname''/ "$@"}}

The {{ic|''appname''/}} directory, or alternatively a file bundle called {{ic|''appname''.asar}}, can be found in a prebuilt electron application as the {{ic|resources/app/}} folder (or {{ic|resources/app.asar}}). Everything else is just a copy of the electron runtime and can be removed from the final package.

{{Note|Applications that require {{ic|1=ELECTRON_RUN_AS_NODE=1}}, e.g. [[Visual Studio Code]], cannot use {{ic|/usr/bin/electron*}}. See [https://gitlab.archlinux.org/archlinux/packaging/packages/code code.sh].}}

=== Editing version on package.json ===

It is dangerous to edit version of Electron in {{ic|package.json}} or {{ic|package-lock.json}} using {{ic|sed}}. You can use {{ic|1=npm pkg set devDependencies.electron=$(cat /usr/lib/electron*/version)}} instead.
{{Accuracy|Editing package.json may not needed and unrelated to building modules correctly.}}

=== Building compiled extensions against the system electron ===

Some electron applications have compiled native extensions which link to the electron runtime, and must be built using the correct electron version. Since npm/yarn will always build against a private prebuilt copy of electron, patch the electron dependency from {{ic|package.json}} to reference the same version as the system electron dependency. The build system will download the prebuilt copy it requires, compile the native extensions, and package everything into a final distribution, but this can be pruned during the {{ic|package()}} step as usual.

Alternatively, you can remove the electron dependency from {{ic|package.json}} and set the correct environment variables before running npm:

export npm_config_target=$(tail /usr/lib/electron/version)
export npm_config_arch=x64
export npm_config_target_arch=x64
export npm_config_disturl=https://electronjs.org/headers{{Dead link|2023|10|29|status=404}}
export npm_config_runtime=electron
export npm_config_build_from_source=true
HOME="$srcdir/.electron-gyp" npm install

Set {{ic|HOME}} to a path inside the {{ic|$srcdir}} so the build process does not place any files in your real {{ic|HOME}} directory. Make sure to adjust the path for all further commands that make use of the {{ic|.electron-gyp}} cache.

(more details [https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules#using-npm in Electron docs]).

=== Using electron-builder with system electron ===

Many projects use '''electron-builder''' to build and package the Javascript file and Electron binaries. By default electron-builder downloads the entire electron version that is defined in the package management file (e.g. {{ic|package.json}}). This might not be desired if you want to use the system electron and save the bandwidth since you are going to throw away the electron binaries anyway. The electron-builder provides the configurations {{ic|electronDist}} and {{ic|electronVersion}}, to specify a custom path of Electron and the version the application is packaged for respectively.

Find the electron-builder configuration file (e.g. {{ic|electron-builder.json}}) and add the following settings:

* {{ic|electronDist}} to　{{ic|/usr/lib/electron34}} for {{Pkg|electron34}}
* {{ic|electronVersion}} to the contents of {{ic|/usr/lib/electron34/version}} (without the leading {{ic|v}} if exists)

Packages that apply this: {{AUR|rocketchat-desktop}} {{AUR|ubports-installer-git}}

[https://www.electron.build/configuration#electrondist electron-builder configuration]

{{Accuracy|Current setting still copies Electron from $electronDist. It is expired to add the method to stop it. Does the command work?|section=Using electron-builder with system electron}}

Alternatively you can use the CLI to change/add these settings like this:

./node_modules/.bin/electron-builder --linux --x64 --dir $dist -c.electronDist=$electronDist -c.electronVersion=$electronVer

Note that you have to specify all these options or it will not work.

{{Accuracy|Packaging with Arch's Electron discards fuses bits [https://www.electronjs.org/docs/latest/tutorial/fuses] flipped by electron-builder. Some bits should be emulated by including environment variables to launcher.}}

== Architecture ==

See [[PKGBUILD#arch]].

An Electron package that contains compiled native extensions is architecture-dependent. Otherwise it is most likely architecture-independent.

If the package contains a prebuilt copy of electron, it is always architecture-dependent.

== Directory structure ==

If the package is architecture-dependent, install the {{ic|resources/app/}} directory to {{ic|/usr/lib/''appname''/}}. Otherwise use {{ic|/usr/share/''appname''/}}.

If the package contains a prebuilt copy of electron, copy the final distribution in its entirety to {{ic|/opt/''appname''}}.

== Getting version of Electron ==

Version of Electron could be given by {{ic|npm pkg get devDependencies.electron}} in the directory containing {{ic|package.json}} or {{ic|package-lock.json}}.

Prebuild or [[Nonfree applications package guidelines|Nonfree]] application hides version of electron from {{ic|package.json}}, {{ic|package-lock.json}}, and {{ic|version}} files. In such case, you may get version by replacing {{ic|app}} or {{ic|app.asar}} with {{ic|/usr/lib/electron/resources/default_app.asar}} and running {{ic|''pathto/electron-binary'' --version}}.
{{Note|Avoid doing it at PKGBUILD. This should be last resort to make packages with system-wide electron.}}

Talk:Pacman/Tips and tricks

2026-05-09T15:16:25Z

Indigo: /* pacman cache */ re, close

== Leading slash ==

[[Pacman/Tips_and_tricks#aria2]] doesn't work without leading slash, i.e. {{ic|-d /}} turning file names to {{ic|//var/cache/...}}. The article mentions this, but it doesn't mention why. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 05:28, 16 October 2015 (UTC)

:You would have to go [https://wiki.archlinux.org/index.php?title=Improve_pacman_performance&diff=32104&oldid=30674 way] [https://wiki.archlinux.org/index.php?title=Improve_pacman_performance&diff=next&oldid=115292 back] to track this. It seems to have worked without {{ic|-d /}} even in 2006: [https://wiki.archlinux.org/index.php?title=Faster_Pacman_Downloads&oldid=15627], [https://wiki.archlinux.org/index.php?title=Improve_pacman_performance&oldid=17759]. <s>I guess that simply nobody asked the right question...</s> -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:30, 16 October 2015 (UTC)
:Oops, it does ''not'' work without {{ic|-d /}}. Then the problem must be on aria's side, which expects a file name for the {{ic|-o}} option, which is then catenated with {{ic|-d}} into the full path. Assuming that {{ic|-d}} defaults to the cwd, {{ic|/var/cache/}} would appear twice in the result. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:43, 16 October 2015 (UTC)

== <s>pacman cache</s> ==

I still think we should warn people not to symlink /var or anything under it. It leaves the whole system unusable because if the cache disappears during a pacman transaction, you're left with missing /usr/lib libraries, and nothing works, including pacman itself. This is a serious enough problem that it can take hours to figure out how to recover. If the wiki had mentioned this problem it would have saved me a lot of time and effort, and I'm not the only one who has run in to this. It is not, however, considered a bug. See https://bugs.archlinux.org/task/50298. [[User:JimRees|JimRees]] ([[User talk:JimRees|talk]]) 23:15, 29 April 2017 (UTC)

:This revisions says that: [https://wiki.archlinux.org/index.php?title=Pacman%2FTips_and_tricks&type=revision&diff=475454&oldid=475438]. But to make it more clear: [https://wiki.archlinux.org/index.php?title=Pacman%2FTips_and_tricks&type=revision&diff=475492&oldid=475482] -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 00:13, 30 April 2017 (UTC)

::Actually, I undid my change since I think that first change is more accurate (mentioning {{ic|/var/cache/pacman/pkg}} and ancestors), so I went back to that but explicitly mentioned {{ic|/var}} as an example. -- [[User:Rdeckard|Rdeckard]] ([[User_talk:Rdeckard|talk]]) 01:11, 30 April 2017 (UTC)

: Thanks for the background information. I was not aware of the bug report and now clearly understand why you altered the section the way you did. I hope the [https://wiki.archlinux.org/index.php?title=Pacman/Tips_and_tricks&diff=475548&oldid=475495 recent change] is sufficient for you. Since every misbehaving program might leave a system unbootable if it plays a role in the boot process, it should be unnecessary to add this redundant information. However the problem you described is still severe and I hope you agree that the recent edits made to the article do the topic justice. Thanks for clarifying the topic and adding this to the article and sorry for reverting your edits at first. -- [[User:Edh|Edh]] ([[User talk:Edh|talk]]) 21:07, 30 April 2017 (UTC)

:: The section was moved to [[Package proxy cache]]. Recently the bug was closed. I adjusted above with [https://wiki.archlinux.org/index.php?title=Package_proxy_cache&diff=873435&oldid=871111] and close this item. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 15:15, 9 May 2026 (UTC)

== local repository database extension/compression recomendation ==

If you opt to not compress a pacman database, the files database can become very large, 10x larger than a gzipped one in my case, which cause issues when trying to update the local pacman files db (pacman -Fy) since apparently there is a max (expected) size. Should we include a warning about uncompressed databases?

{{unsigned|00:35, 29 January 2019‎|JoshH100}}

== Use a new nginx.conf for [[Pacman/Tips_and_tricks#Dynamic_reverse_proxy_cache_using_nginx|Dynamic reverse proxy cache using nginx]] ==

I propose to replace the [https://gist.github.com/anonymous/97ec4148f643de925e433bed3dc7ee7d current nginx.conf] with an [https://github.com/nastasie-octavian/nginx_pacman_cache_config/blob/master/nginx.conf improved nginx.conf] and update the section. The new config doesn't make the upstream servers directly available on the network and it allows having mirrors with different relative paths to package files. It also removes directives that are not needed and has some other minor cleanups. I've been using a similar config for a few months now without any problems, so I believe it should be fine. [[User:Noctavian|Noctavian]] ([[User talk:Noctavian|talk]]) 16:05, 28 February 2019 (UTC)

:What do you mean by "The new config doesn't make the upstream servers directly available on the network"? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:54, 28 February 2019 (UTC)

:: In the new config the server blocks for the upstream mirrors are set to listen to 127.0.0.1:800X. Only the computer that is running the nginx cache can send requests to 127.0.0.1. Other computers on the network can't. The current config exposes the upstream mirrors to the network, a nmap scan will show the 8080 port of the cache as open and the ports 8001, 8002, 8003 of the upstream mirrors as open. One can browse to cache.domain.example:8002 and have direct access to whatever package mirror website is used by the cache bypassing the cache config order and locations. The upstream mirrors don't need to be available to the entire network for the cache to work; they only need to be available to the computer that is hosting the nginx cache. I believe ports should not be left open on the network if they don't have to be open. [[User:Noctavian|Noctavian]] ([[User talk:Noctavian|talk]]) 08:37, 1 March 2019 (UTC)

: I have written a draft for the section update on my [[User:Noctavian|user page]]. I made some small changes to the config file since last week, added comments and mirror examples and turned off IPv6 address resolution to prevent some errors that can happen sometimes. Suggestions.are welcome. I haven't seen objections to my proposal, so I'm going to wait a few more days for feedback and then update the section on the main page with my draft and the new nginx.conf file if that's ok. [[User:Noctavian|Noctavian]] ([[User talk:Noctavian|talk]]) 11:43, 8 March 2019 (UTC)

::Feel free to go ahead. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:11, 16 March 2019 (UTC)

== Remove uninstalled packages from the cache with paccache ==

Just figured the following out, noting here since I'm not sure it's worth noting in the page itself: {{ic|paccache}} won't remove uninstalled packages, even with {{ic|-u}}, unless {{ic|-k}} is given a value lower than the number of instances in cache. In particular, oneshot AUR experiments won't be removed without {{ic|-k0}}.
[[User:Gesh|Gesh]] ([[User talk:Gesh|talk]]) 01:23, 1 November 2021 (UTC)

:The {{ic|-u}} flag just adds all installed packages to the blacklist. So to remove uninstalled packages from the cache and nothing else, use {{ic|-uk0}}. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:28, 1 November 2021 (UTC)

== Additional options needed for mounting overlay of remote pacman pkg cache ==

"The factual accuracy of this article or section is disputed. Reason: Why is -o index=off -o metacopy=off needed? Is -o redirect_dir=off needed only for this use-case? If not, it should be explained on the overlay filesystem page too."

My reply: I'm not an expert on use of sshfs for mounting remote filesystems. To me, using sshfs is much simpler than going to all the trouble of setting up the chosen box to serve up {{ic|/var/cache/pacman/pkg}} over, e.g., NFS. I wonder if using fuse.sshfs leads to this problem? That being said, my setup is bog standard, all boxes using ''linux'' kernel from Arch, connected to the same LAN switch with normal IPv4 addressing, e.g., 192.168.1.100, and so on.

Without using any additional options the problem I encounter is an unusual but familiar one, namely:
$ ls /tmp/pacman_pkg/ > /dev/null
ls: reading directory '/tmp/pacman_pkg/': Stale file handle

This is obviously unworkable. The minimal options I am able to succeed with are: {{ic|1=-o redirect_dir=off -o index=off}}. Prior to the 5.17 kernel series, I needed {{ic|1=-o index=off -o metacopy=off}} but in my use something then changed which requires {{ic|1=-o redirect_dir=off}} (and {{ic|1=-o metacopy=off}} now comes along for free). Without these options... "Stale file handle".

I am eliminating additional options from the generic commands even though I expect that anyone who tries to run them as listed will fail due to the file handle reporting as stale. I will add a tip note suggesting these options if problems are encountered. HTH :) [[User:Cmsigler|Cmsigler]] ([[User talk:Cmsigler|talk]]) 16:21, 27 April 2022 (UTC)

:I'm not super familiar with sshfs, but this looks good to me! Thanks for addressing the accuracy template ^^ [[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 06:48, 2 May 2022 (UTC)

== Is PackageKit still not recommended to use in 2022? ==

In [[Pacman/Tips_and_tricks#Graphical]], a warning says that PackageKit opens up system permissions by default and thus is not recommended to use. However, that warning was added back in 2018 and it links bug reports from 2016. I'm wondering if it's still valid in 2022? Also, as far as I know, PackageKit only allowed users from the wheel group to perform updates (kind of similar to what sudo does).

Is this still the case nowadays? If so, are there any other warnings one should know of before using PackageKit? I'm thinking partial upgrades, but I'm not sure. [[User:Cont999|Cont999]] ([[User talk:Cont999|talk]]) 03:54, 3 September 2022 (UTC)

: sudo pacman requires a password, whereas PackageKit doesn't, so they are really not equivalent. I believe PackageKit can also update the system even if the user is not in the wheel group. I haven't looked upstream, but this is how the software is designed to work because it fits the way other distributions configure things. In Fedora, for example, you do not need to authenticate to install updates to the system. Updates can also run without user intervention. These practices are dangerous on Arch. Unattended updates aren't supported and attended ones require you to read the output and the News. So the problems using PackageKit on Arch are not going to be resolved unless changes are made locally, but there's not much motivation to do that as Arch users are expected to be able to use pacman. That is, the bugs on Arch aren't bugs elsewhere, so upstream is unlikely to fix them (and break how stuff works elsewhere); the bugs are more easily avoided on Arch by not using PackageKit. At least, that would be my understanding. --[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 01:11, 13 December 2022 (UTC)

== Why do I have this package? ==

I occasionally wonder why a certain <code>PACKAGE</code> is installed. I used to browse <code>pactree -r PACKAGE</code> to answer this question, but I recently figured that you can just do <code>pacman -Qe `pactree -ruo PACKAGE`</code> to list all explicitly installed packages that directly or indirectly depend on <code>PACKAGE</code>.

I would've added a section to the article but I'm not sure if this is useful for anyone but me. [[User:Rumsbums|Rumsbums]] ([[User talk:Rumsbums|talk]]) 07:58, 21 January 2024 (UTC)

:<blockquote>to list all explicitly installed packages that directly or indirectly depend on <code>PACKAGE</code>.</blockquote>
:The question is, why do you want to know that in the first place? What purpose such information can serve?
:If you have some '''explicit''' package you don't need, just uninstall it. If it is required by something else, pacman won't let you uninstall it anyway. In which case you can simply mark it as non-explicit ({{ic|pacman -D --asdeps PACKAGE}}).
:Also this maybe a bit obvious, but you should '''not''' uninstall {{Pkg|base}} metapackage of course. It is a special case and core of the proper Arch installation.
:[[User:Hanabishi|Hanabishi]] ([[User talk:Hanabishi|talk]]) 08:17, 21 January 2024 (UTC)

::To add to this, you can run {{ic|pacman -Rsc --print ''package''}} to see what would have been removed. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 14:07, 21 January 2024 (UTC)

== A CacheServer which is using the database files ==

In the past, there was a tip about [[Special:Diff/810046|a CacheServer that does use the database files]]. I find it useful, for example when the admin would like to have all his machines refers to exactly the same database files. My edit to get it back [[Special:Diff/818026|was rejected]]. A solution might be to divide [[Pacman/Tips and tricks#Network shared pacman cache]] into two sections. One section will discuss a CacheServer which is using the database files. The other section will discuss a CacheServer which does not use database files. Any opinions? [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 07:59, 10 October 2024 (UTC)

:A {{ic|CacheServer}} in pacman ''does not'' use database files, please don't call your solution like that. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 06:54, 12 October 2024 (UTC)
::In the context of the suggestion for the clients to have a {{ic|CacheServer}} statement in their {{ic|/etc/pacman.conf}}, is the following acceptable?
{{Note|if you want to force the clients to use only packages from the cache server, you can
# ln -s /var/lib/pacman/sync/*.db /var/cache/pacman/pkg/
in the server, and use the common
{{hc|/etc/pacman.conf|2=
Server = http://''server-ip'':''port''}}
statement for each client.}} [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 12:25, 12 October 2024 (UTC)

:::No, if you use {{ic|Server}}, it is not a ''cache'' server. In your use case, the clients will not be able to download packages missing on the cache server and if you add another {{ic|Server}} directive for that purpose, you won't get exactly the same packages served by both servers (if your "cache" server becomes outdated, the other mirror will purge its old packages in the mean time).
:::I really doubt that this tip is worth mentioning on the page.
:::— [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:50, 12 October 2024 (UTC)
::::It would be a cache for the packages the cache server has. The intention is the client will not be able to download packages that the cache server admin has not approved. He will not add another {{ic|Server}} directive to the clients. Quoting [[Package proxy cache]]:
:::::If you want to install the same Arch packages over and over - e.g. for testing purposes - it could help if you would not have to get the packages every time from the internet.
::::Or someone might want to have a group of machines with exactly the same set of packages. And the [[Special:Diff/810046|original tip]] was here for a long time. I find that tip useful.
::::{{unsigned|17:26, 12 October 2024 (UTC)|Regid}}
:::::The original intention was not to forbid downloading packages that are not already in the cache. It said to ''add'' {{ic|Server}} at the top of the mirrorlist, not to use it as the only entry. This solution had the exact issue that I described, which is solved by using {{ic|CacheServer}} since pacman 6.1.0. Your quote from [[Package proxy cache]] is just a definition of a ''cache server'' and the {{ic|CacheServer}} also does exactly that. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:35, 12 October 2024 (UTC)

== Is PackageKit warning and bugs still relevant? ==

Bugs seem to be closed, while unresolved, and from comments it seems that they are no longer relevant [[User:Karakurt|Karakurt]] ([[User talk:Karakurt|talk]]) 14:24, 26 July 2025 (UTC)

Package proxy cache

2026-05-09T15:13:14Z

Indigo: /* Read-write cache */ update, bug was closed; re Talk:Pacman/Tips and tricks#pacman cache

[[Category:Package management]]
[[hu:Package proxy cache]]
{{Related articles start}}
{{Related|pacman}}
{{Related articles end}}

If you want to install the same Arch packages over and over —e.g. for testing purposes— it could help if you would not have to get the packages every time from the internet. This article shows you how to share packages so that you can greatly decrease your download times.

Which solution is best depends on your individual use-case. The methods can be grouped into [[#Package cache sharing]] of the machines, or deploying a [[#Proxy server]] for extra caching on one machine and configuring the machines to use it accordingly.

== Package cache sharing ==

For all solutions to share the package cache, keep in mind that, 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.

To clean up the cache so that only ''outdated'' tarballs are deleted:

{{hc|/etc/pacman.conf|2=
[options]
CleanMethod = KeepCurrent
}}

=== Read-only cache ===

Pacman supports cache servers directly. Cache servers will be tried before any non-cache servers, will not be removed from the server pool because of HTTP 404 download errors, and will not be used for database files.

If you are looking for a quick solution, you can simply run a [https://gist.github.com/willurd/5720255 basic temporary webserver] which other computers can use as their cache server.

Start serving this directory. For example, with [[Python]] [https://docs.python.org/3/library/http.server.html#http-server-cli http.server] module:

$ python -m http.server -d /var/cache/pacman/pkg/

{{Tip|By default, Python {{ic|http.server}} listens on port {{ic|8000}} of any interface. To use another port, or bind only to specific address, simply add a parameter and an argument:

$ python -m http.server -d /var/cache/pacman/pkg/ --bind 127.0.0.1 8080
}}

Then [[textedit|edit]] {{ic|/etc/pacman.d/mirrorlist}} on each client machine to add this server:

{{hc|/etc/pacman.d/mirrorlist|2=
CacheServer = http://''server-ip'':''port''
}}

{{Warning|Do '''not''' append {{ic|/repos/$repo/os/$arch}} to this custom server like for other entries, as this hierarchy does not exist and therefore queries will fail.}}

If looking for a more standalone solution, {{Pkg|darkhttpd}} offers a very minimal webserver. Replace the previous {{ic|python}} command with e.g.:

[http]$ darkhttpd /var/cache/pacman/pkg --no-server-id

You could also run darkhttpd as a ''systemd'' service for convenience: see [[Systemd#Writing unit files]].

[[miniserve]], a small web server written in Rust, can also be used:

$ miniserve /var/cache/pacman/pkg

Then edit {{ic|/etc/pacman.d/mirrorlist}} as above with the first url miniserve is available at.

If you are already running a web server for some other purpose, you might wish to reuse that as your local repository server instead. For example, if you already serve a site with [[nginx]], you can add an ''nginx'' server block listening on port 8080:

{{hc|/etc/nginx/nginx.conf|
server {
listen 8080;
root /var/cache/pacman/pkg;
server_name myarchrepo.localdomain;
try_files $uri $uri/;
}
}}

Remember to [[restart]] {{ic|nginx.service}} after making this change.

{{Tip|Whichever web server you use, make sure the firewall configuration (if any) allows the configured port to be reached by the desired traffic, and disallows any undesired traffic. See [[Security#Network and firewalls]].}}

=== Overlay mount of read-only cache ===

It is possible to use one machine on a local network as a read-only package cache by [[Overlay filesystem|overlay mounting]] its {{ic|/var/cache/pacman/pkg}} directory. Such a configuration is advantageous if this server has installed on it a reasonably comprehensive selection of up-to-date packages which are also used by other boxes. This is useful for maintaining a number of machines at the end of a low bandwidth upstream connection.

As an example, to use this method:

# mkdir /tmp/remote_pkg /mnt/workdir_pkg /tmp/pacman_pkg
# sshfs ''remote_username''@''remote_pkgcache_addr'':/var/cache/pacman/pkg /tmp/remote_pkg -C
# mount -t overlay overlay -o lowerdir=/tmp/remote_pkg,upperdir=/var/cache/pacman/pkg,workdir=/mnt/workdir_pkg /tmp/pacman_pkg

{{Note|The working directory must be an empty directory on the same mounted device as the upper directory. See [[Overlay filesystem#Usage]].}}

{{Tip|1=If listing the {{ic|/tmp/pacman_pkg}} overlay directory gives errors, e.g., "Stale file handle", try overlay mounting with options {{ic|1=-o redirect_dir=off -o index=off}}. }}

After this, run ''pacman'' using the option {{ic|--cachedir /tmp/pacman_pkg}}, e.g.:

# pacman -Syu --cachedir /tmp/pacman_pkg

=== Distributed read-only cache ===

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 Wi-Fi and Ethernet.

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.

=== Read-write cache ===

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 [[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.

First, install any network-supporting filesystem packages: {{Pkg|sshfs}}, {{Pkg|curlftpfs}}, {{Pkg|samba}} or {{Pkg|nfs-utils}}.

{{Tip|
* To use ''sshfs'', consider reading [[Using SSH Keys]].
* 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.
}}

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.

{{Warning|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. See the issue {{Issue|pacman/pacman|5}} for details.}}

=== Two-way with rsync or FTP ===

Another approach in a local environment is [[rsync]]. Choose a server for caching and enable the [[Rsync#As a daemon|rsync daemon]]. On clients synchronize two-way with this share via the rsync protocol. Filenames that contain colons are no problem for the rsync protocol.

Draft example for a client, using {{ic|uname -m}} within the share name ensures an architecture-dependent sync:

# rsync ... rsync://server/share_$(uname -m)/ /var/cache/pacman/pkg/
# pacman -Syu
# paccache --remove --keep 3
# rsync --delete ... /var/cache/pacman/pkg/ rsync://server/share_$(uname -m)/

Instead of relying on unencrypted [[Rsync#As a daemon|rsync daemon]] a more secure security option is rsync over ssh,
[[Rsync#Automated backup with SSH]] gives an overview.

In case rsync is not available in your local environment, a simple ftp service is suitable for the two-way sync as well. {{Pkg|lftp}} provides a {{ic|--mirror}} and a {{ic|--delete}} option to sync a local with a remote storage.

=== Synchronize pacman package cache using synchronization programs ===

Use [[Syncthing]] or [[Resilio Sync]] to synchronize the ''pacman'' cache directories (i.e. {{ic|/var/cache/pacman/pkg}}).

== Proxy server ==

For proxy server solutions, keep in mind the machines should only use HTTP mirrors, because a proxy server cannot introspect [[HTTPS]] connections by default.

=== Dynamic reverse proxy cache using nginx ===

[[nginx]] can be used to proxy package requests to official upstream mirrors and cache the results to the local disk. All subsequent requests for that package will be served directly from the local cache, minimizing the amount of internet traffic needed to update a large number of computers.

In this example, the cache server will run at {{ic|<nowiki>http://cache.domain.example:8080/</nowiki>}} and store the packages in {{ic|/srv/http/pacman-cache/}}.

Install [[nginx]] on the computer that is going to host the cache. Create the directory for the cache and adjust the permissions so nginx can write files to it:

# mkdir /srv/http/pacman-cache
# chown http:http /srv/http/pacman-cache

Use the [https://github.com/nastasie-octavian/nginx_pacman_cache_config/blob/c54eca4776ff162ab492117b80be4df95880d0e2/nginx.conf nginx pacman cache config] as a starting point for {{ic|/etc/nginx/nginx.conf}}. Check that the {{ic|resolver}} directive works for your needs. In the upstream server blocks, configure the {{ic|proxy_pass}} directives with addresses of official mirrors, see examples in the configuration file about the expected format. Once you are satisfied with the configuration file [[Nginx#Running|start and enable nginx]].

In order to use the cache each Arch Linux computer (including the one hosting the cache) must have the following line at the top of the {{ic|mirrorlist}} file:

{{hc|/etc/pacman.d/mirrorlist|<nowiki>
Server = http://cache.domain.example:8080/$repo/os/$arch
...
</nowiki>}}

{{Note| You will need to create a method to clear old packages, as the cache 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.}}

=== Squid ===

[[Squid]] proxy can be setup to only cache arch packages and can be used with aif/pacman/wget/etc with minimal configuration on the client system.

==== Install Squid ====

Install {{Pkg|squid}}.

==== Configure Squid ====

This is the minimum configuration to get squid cache arch packages.

===== Cache Rules =====

Before defining these rules, remove/comment (if you do not need them) all the default refresh_patterns
{{hc|/etc/squid/squid.conf |refresh_pattern \.pkg\.tar\. 0 20% 4320 reload-into-ims
refresh_pattern . 0 0% 0}}
That should define that *.pkg.tar.* gets cached, and anything else should not.
{{Tip|https://www.squid-cache.org/Doc/config/refresh_pattern}}

===== Maximum Filesize =====

Objects larger than this size will NOT be saved on disk:
{{hc|/etc/squid/squid.conf |maximum_object_size 256 MB}}
{{Tip|https://www.squid-cache.org/Doc/config/maximum_object_size}}

===== Cache Directory =====

Set the cache dir and its maximum size and subdirs:
{{hc|/etc/squid/squid.conf |cache_dir aufs /var/cache/squid 10000 16 256}}
{{Tip|https://www.squid-cache.org/Doc/config/cache_dir}}

===== Shutdown Lifetime =====

Time to wait until all active client sockets are closed:
{{hc|/etc/squid/squid.conf |shutdown_lifetime 1 seconds }}
{{Tip|https://www.squid-cache.org/Doc/config/shutdown_lifetime}}

{{Note|
Every time you change the cache_dir path (and after fresh install), you need to (re)create this directory:
{{bc|# squid -z}}
and it could be helpful to check the configuration file before running squid:
{{bc|# squid -k parse}}
}}

==== Start Squid ====

Just [[start]] {{ic|squid.service}} or if squid is already running [[restart]] it.
{{Note|
It could be helpful to check the configuration file before running:
{{bc|# squid -k check}}
}}

==== Follow Squid access log ====

To see the access to squid:
{{bc|# tail -f /var/log/squid/access.log}}
You should see this for packages that are directed to original host:
{{bc|...TCP_MISS/200...DIRECT...}}
and for packages that are delivered from the cache:
{{bc|...TCP_HIT/200...NONE...}}

==== Manual Arch Install ====

On the individual machines, add [[environment variables]] for your proxy. To do so for testing:

# export http_proxy='http://''your_squid_machine_ip'':3128/'
# export ftp_proxy='ftp://''your_squid_machine_ip'':3128/'

Now it should use your proxy. Watch the squid logs to verify this. Once it works, add the {{ic|http_proxy}} and/or {{ic|ftp_proxy}} variables in an appropriate place on the installed system, e.g. in {{ic|/etc/profile.d/proxy.sh}}.

==== Intercepting local requests ====

If you want all HTTP requests on local machine ''automagically'' go through squid, we first need to add an intercepting port for squid:

{{hc|/etc/squid/squid.conf |http_port 3127 intercept}}

and iptables rules to redirect all (except the ones from squid) port 80 requests to squid:

{{bc|# iptables -t nat -A OUTPUT -p tcp --dport 80 -m owner --uid-owner proxy -j ACCEPT
# iptables -t nat -A OUTPUT -p tcp --dport 80 -j REDIRECT --to-ports 3127}}

{{Tip|https://wiki.squid-cache.org/ConfigExamples/Intercept/LinuxLocalhost}}

{{Note|
if you get random slow download speeds in vagrant/packer/virtualbox, try using {{ic|virtio}} network device type.}}

=== Pacoloco proxy cache server ===

[https://github.com/anatol/pacoloco Pacoloco] is an easy-to-use proxy cache server for ''pacman'' repositories. It also allows [https://github.com/anatol/pacoloco/commit/048b09956b0d8ef71c0ed1f804fd332d9ab5e3c8 automatic prefetching] of the cached packages.

It can be installed as {{Pkg|pacoloco}}. Open the configuration file and add ''pacman'' mirrors:

{{hc|/etc/pacoloco.yaml|<nowiki>
port: 9129
repos:
mycopy:
urls:
- http://mirror.lty.me/archlinux
- http://mirrors.kernel.org/archlinux
</nowiki>}}

[[Restart]] {{ic|pacoloco.service}} and the proxy repository will be available at {{ic|http://''myserver'':9129/repo/mycopy}}.

=== Flexo proxy cache server ===

[https://github.com/nroi/flexo Flexo] is yet another proxy cache server for ''pacman'' repositories. Flexo is available as {{AUR|flexo-git}}. Once installed, [[start]] the {{ic|flexo.service}} unit.

Flexo runs on port {{ic|7878}} by default. Enter {{ic|1=Server = http://''myserver'':7878/$repo/os/$arch}} to the top of your {{ic|/etc/pacman.d/mirrorlist}} so that ''pacman'' downloads packages via Flexo.

Pacman/Tips and tricks

2026-05-09T14:18:44Z

Indigo: /* Custom local repository */ grammar fix; expand filepath and shorten a sentence

{{Lowercase title}}
[[Category:Package manager]]
[[de:Pacman-Tipps]]
[[es:Pacman (Español)/Tips and tricks]]
[[fr:Pacman (Français)/Tips and tricks]]
[[hu:Pacman (Magyar)/Tips and tricks]]
[[ja:Pacman ヒント]]
[[pt:Pacman (Português)/Tips and tricks]]
[[uk:Pacman (Українська)/Tips and tricks]]
[[ru:Pacman (Русский)/Tips and tricks]]
[[zh-hans:Pacman/Tips and tricks]]
{{Related articles start}}
{{Related|Mirrors}}
{{Related|Creating packages}}
{{Related articles end}}

For general methods to improve the flexibility of the provided tips or ''pacman'' itself, see [[Core utilities]] and [[Bash]].

== Maintenance ==

{{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}}.}}

See also [[System maintenance]].

=== Listing packages ===

==== In unused repositories ====

By default, repositories listed in {{ic|pacman.conf}} are used for syncing, searching, installing and upgrading from them. This can be changed for more versatility, for example by using some repositories only for searching in them[http://allanmcrae.com/2014/12/pacman-4-2-released/]:

{{hc|/etc/pacman.conf|2=
...
[multilib]
Usage = Sync Search
...
}}

See {{man|5|pacman.conf|REPOSITORY SECTIONS}}.

==== With version ====

You may want to get the list of installed packages with their version, which is useful when reporting bugs or discussing installed packages.

* List all explicitly installed packages: {{ic|pacman -Qe}}
* List all packages in the [[package group]] named {{ic|''group''}}: {{ic|pacman -Sg ''group''}}
* List all foreign packages (typically manually downloaded and installed or packages removed from the repositories): {{ic|pacman -Qm}}
* List all native packages (installed from the sync database): {{ic|pacman -Qn}}
* List all explicitly installed native packages (i.e. present in the sync database) that are not direct or optional dependencies: {{ic|pacman -Qent}}
* List packages by regex: {{ic|pacman -Qs ''regex''}}
* List packages by regex with custom output format (needs {{Pkg|expac}}): {{ic|expac -s "%-30n %v" ''regex''}}

==== With size ====

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.

===== Individual packages =====

The following command will list all installed packages and their individual sizes:

$ LC_ALL=C.UTF-8 pacman -Qi | awk '/^Name/{name=$3} /^Installed Size/{print $4$5, name}' | LC_ALL=C.UTF-8 sort -h

===== Packages and dependencies =====

To list package sizes with their dependencies,

* Install {{Pkg|expac}} and run {{ic|expac -H M '%m\t%n' {{!}} sort -h}}.
* Run {{AUR|pacgraph}} with the {{ic|-c}} option.

To list the download size of several packages (leave {{ic|''packages''}} blank to list all packages):

$ expac -S -H M '%k\t%n' ''packages''

To list explicitly installed packages not in the [[meta package]] {{Pkg|base}} nor [[package group]] {{Grp|xorg}} with size and description:

$ expac -H M "%011m\t%-20n\t%10d" $(comm -23 <(pacman -Qqen | sort) <({ pacman -Qqg xorg; expac -l '\n' '%E' base; } | sort -u)) | sort -n

To list the packages marked for upgrade with their download size:

$ expac -S -H M '%k\t%n' $(pacman -Qqu) | sort -sh

To list optional dependencies only:

$ expac -S "%o" ''package''

==== By date ====

To list the 20 last installed packages with {{Pkg|expac}}, run:

$ expac --timefmt='%Y-%m-%d %T' '%l\t%n' | sort | tail -n 20

or, with seconds since the epoch (1970-01-01 UTC):

$ expac --timefmt=%s '%l\t%n' | sort -n | tail -n 20

==== Not in a specified group, repository or meta package ====

{{Note|To get a list of packages installed as dependencies but no longer required by any installed package, see [[#Removing unused packages (orphans)]].
}}

List explicitly installed packages not in the {{Pkg|base}} [[meta package]]:

$ comm -23 <(pacman -Qqe | sort) <(expac -l '\n' '%E' base | sort)

List explicitly installed packages not in the {{Pkg|base}} meta package or {{Grp|xorg}} [[package group]]:

$ comm -23 <(pacman -Qqe | sort) <({ pacman -Qqg xorg; expac -l '\n' '%E' base; } | sort -u)

List all installed packages unrequired by other packages, and which are not in the {{Pkg|base}} meta package or {{Grp|xorg}} package group:

$ comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg xorg; echo base; } | sort -u)

As above, but with descriptions:

$ expac -H M '%-20n\t%10d' $(comm -23 <(pacman -Qqt | sort) <({ pacman -Qqg xorg; echo base; } | sort -u))

List all installed packages that are ''not'' in the specified repository ''repo_name'' (multiple repositories can be checked at once):

$ comm -23 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)

List all installed packages that are in the ''repo_name'' repository (multiple repositories can be checked at once):

$ comm -12 <(pacman -Qq | sort) <(pacman -Sql ''repo_name'' | sort)

List all packages on the Arch Linux ISO that are not in the {{Pkg|base}} meta package:

<nowiki>$ comm -23 <(curl https://gitlab.archlinux.org/archlinux/archiso/-/raw/master/configs/releng/packages.x86_64) <(expac -l '\n' '%E' base | sort)</nowiki>

{{Tip|Alternatively, use {{ic|combine}} (instead of {{ic|comm}}) from the {{Pkg|moreutils}} package which has a syntax that is easier to remember. See {{man|1|combine}}.}}

==== Development packages ====

To list all development/unstable packages, run:

$ pacman -Qq | grep -Ee '-(bzr|cvs|darcs|git|hg|svn)$'

==== Dependencies of a package ====

To obtain the list of the dependencies of a package, the simplest solution is reading the output of:

$ pacman -Qi ''package''

For automation, instead of the error-prone method of parsing pacman output, use {{Pkg|expac}}:

$ expac -S '%D' ''package''

==== With optional dependencies ====

To list explicitly-installed packages with their optional dependencies, run:

$ LC_ALL=C.UTF-8 pacman -Qei | sed '/^[^NO ]/d;/None$/d' | awk 'BEGIN{RS=ORS="\n\n";FS=OFS="\n\\S"} /Optional Deps/ {print $1"\nO"$2}'

Alternatively, with {{Pkg|expac}}:

$ expac -d '\n\n' -l '\n\t' -Q '%n\n\t%O' $(pacman -Qeq)

To list them while omitting optional dependencies you have already installed, run:

$ LC_ALL=C.UTF-8 pacman -Qei | sed '/^[^NO ]/d;/None$/d' | awk 'BEGIN{RS=ORS="\n\n";FS=OFS="\n\\S"} /Optional Deps/ {print $1"\nO"$2}' | sed 's/^Optional Deps ://;/\[installed\]$/d;s/\s\+/ /'

=== Browsing packages ===

To browse all installed packages with an instant preview of each package:

$ pacman -Qq | fzf --preview 'pacman -Qil {}' --layout=reverse --bind 'enter:execute(pacman -Qil {} | less)'

This uses [[fzf]] to present a two-pane view listing all packages with package info shown on the right.

Enter letters to filter the list of packages; use arrow keys (or {{ic|Ctrl-j}}/{{ic|Ctrl-k}}) to navigate; press {{ic|Enter}} to see package info under ''less''.

To browse all packages currently known to ''pacman'' (both installed and not yet installed) in a similar way, using fzf, use:

$ pacman -Slq | fzf --preview 'pacman -Si {}' --layout=reverse

The navigational keybindings are the same, although {{ic|Enter}} will not work in the same way.

=== Listing files owned by a package with size ===

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.

$ pacman -Qlq ''package'' | grep -v '/$' | xargs -r du -h | sort -h

=== Identify files not owned by any package ===

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.

One method is to list all files of interest and check them against ''pacman'':

# (export LC_ALL=C.UTF-8; comm -13 <(pacman -Qlq | sed 's,/$,,' | sort) <(find /etc /usr /opt -path /usr/lib/modules -prune -o -print | sort))

{{Tip|The {{Pkg|lostfiles}} script performs similar steps, but also includes an extensive blacklist to remove common false positives from the output.}}

=== Tracking unowned files created by packages ===

Most systems will slowly collect several [http://ftp.rpm.org/max-rpm/s1-rpm-inside-files-list-directives.html#S3-RPM-INSIDE-FLIST-GHOST-DIRECTIVE ghost] files such as state files, logs, indexes, etc. through the course of usual operation.

{{ic|pacreport}} from {{Pkg|pacutils}} can be used to track these files and their associations via {{ic|/etc/pacreport.conf}} (see {{man|1|pacreport|FILES}}).

An example may look something like this (abridged):

{{hc|/etc/pacreport.conf|2=
[Options]
IgnoreUnowned = usr/share/applications/mimeinfo.cache

[PkgIgnoreUnowned]
alsa-utils = var/lib/alsa/asound.state
bluez = var/lib/bluetooth
ca-certificates = etc/ca-certificates/trust-source/*
dbus = var/lib/dbus/machine-id
glibc = etc/ld.so.cache
grub = boot/grub/*
linux = boot/initramfs-linux.img
pacman = var/lib/pacman/local
update-mime-database = usr/share/mime/magic
}}

Then, when using {{ic|pacreport --unowned-files}} as the root user, any unowned files will be listed if the associated package is no longer installed (or if any new files have been created).

Additionally, [https://github.com/CyberShadow/aconfmgr aconfmgr] ({{AUR|aconfmgr-git}}) allows tracking modified and orphaned files using a configuration script.

=== Removing unused packages (orphans) ===

Orphans are packages that were installed as a dependency and are no longer required by any package.

They can accumulate on your system over time either due to uninstalling packages using {{ic|pacman -R ''package''}} instead of {{ic|pacman -Rs ''package''}}, installing packages as [[makedepends]], or packages removing dependencies in newer versions.

For recursively removing orphans and their configuration files:

# pacman -Qdtq | pacman -Rns -

If no orphans were found, the output is {{ic|error: argument '-' specified with empty stdin}}. This is expected as no arguments were passed to {{ic|pacman -Rns}}. The error can be avoided by prefixing the second command with {{man|1|ifne}} from the {{Pkg|moreutils}} package.

If there is a package listed that you do not want to remove, it can be excluded from the list of orphans by marking it as explicitly installed:

# pacman -D --asexplicit ''package''

{{Note|The arguments {{ic|-Qdt}} list only true orphans. To include packages which are ''optionally'' required by another package, pass the {{ic|-t}} flag twice (''i.e.'', {{ic|-Qdtt}}).}}

{{Tip|Add the {{ic|pacman -Qdt}} command to a ''pacman'' post-transaction [[Pacman#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any {{ic|failed to execute command}} errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qdt || /usr/bin/echo '=> None found.'"</nowiki>}} The package {{AUR|pacman-log-orphans-hook}} provides such hook with a more verbose instructions.}}

=== Detecting more unneeded packages ===

In some cases the method above will not detect all possible unneeded packages. E.g. dependency cycles (also known as "circular dependencies"), excessive dependencies (fulfilled more than once), some non-explicit optionals etc.

To detect such packages:

$ pacman -Qqd | pacman -Rsu --print -

If you want to remove all packages in the list at once, run the command without {{ic|--print}} argument.

Sometimes there may be multiple packages providing the same item. For example, there may be multiple packages which provide ttf-font. You may not want all such packages depending on your preference.

To detect packages which provide same item:

$ awk '/%(NAME|PROVIDES)%/{flag=1;next}/^$/{flag=0}flag{ printf "%s\t%s\n", FILENAME, $0}' /var/lib/pacman/local/*/desc | sed 's%/var/lib/pacman/local/$.*$/desc%\1%g' | sort -k2 | uniq -Df1 | column -etN Package,Provides

Check the output and [[Pacman#Removing packages|carefully remove]] redundant package which you do not require.

=== Removing everything but essential packages ===

If it is ever necessary to remove all packages except the essentials packages, one method is to set the installation reason of the non-essential ones as dependency and then remove all unnecessary dependencies.

First, for all the packages "explicitly installed", change their installation reason to "installed as a dependency":

# pacman -D --asdeps $(pacman -Qqe)

Then, change the installation reason to "explicitly installed" of only the essential packages, those you '''do not''' want to remove, in order to avoid targeting them:

# pacman -D --asexplicit base linux linux-firmware

{{Note|
* Additional packages can be added to the above command in order to avoid being removed. See [[Installation guide#Install essential packages]] for more info on other packages that may be necessary for a fully functional base system.
* This will also select the [[boot loader]] package for removal. The system should still be bootable, but the boot parameters might not be changeable without it.
}}

Finally, follow the instructions in [[#Removing unused packages (orphans)]] to remove all packages that are "installed as a dependency".

=== Getting the dependencies list of several packages ===

Dependencies are alphabetically sorted and doubles are removed.

{{Note|To only show the tree of local installed packages, use {{ic|pacman -Qi}}.}}

$ LC_ALL=C.UTF-8 pacman -Si ''packages'' | awk -F'[:<=>]' '/^Depends/ {print $2}' | xargs -n1 | sort -u

Alternatively, with {{Pkg|expac}}:

$ expac -l '\n' %E -S ''packages'' | sort -u

=== Listing changed backup files ===

To list configuration files tracked by ''pacman'' as [[Pacnew and Pacsave files#Package backup files|susceptible of containing user changes]] (i.e. files listed in the [[PKGBUILD#backup|PKGBUILD backup array]]) and having received user modifications, use the following command:

# pacman -Qii | awk '/\[modified\]/ {print $(NF - 1)}'

Running this command with root permissions will ensure that files readable only by root (such as {{ic|/etc/sudoers}}) are included in the output.

This can be used when doing a selective system backup or when trying to replicate a system configuration from one machine to another.

{{Tip|
* See [[#Listing all changed files from packages]] to list all changed files ''pacman'' knows about, not only backup files.
* See [[#Identify files not owned by any package]] to list all files in the system that are not tracked by ''pacman''.
}}

=== Back up the pacman database ===

The following command can be used to back up the local ''pacman'' database:

$ tar -cjf pacman_database.tar.bz2 /var/lib/pacman/local

Store the backup ''pacman'' database file on one or more offline media, such as a USB stick, external hard drive, or CD-R.

The database can be restored by moving the {{ic|pacman_database.tar.bz2}} file into the {{ic|/}} directory and executing the following command:

# tar -xjvf pacman_database.tar.bz2

{{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]].}}

{{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}}.}}

=== Check changelogs easily ===

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''}}.

== Installation and recovery ==

Alternative ways of getting and restoring packages.

=== Installing packages from a CD/DVD or USB stick ===

{{Merge|#Custom local repository|Use as an example and avoid duplication}}

To download packages, or groups of packages:

# cd ~/Packages
# pacman -Syw --cachedir "$PWD" base base-devel grub-bios xorg gimp
# repo-add ./custom.db.tar.zst ./*.pkg.tar.zst

Pacman, which will reference the host installation by default, will not properly resolve and download existing dependencies. In cases where all packages and dependencies are wanted, it is recommended to create a temporary blank DB and reference it with {{ic|--dbpath}}:

# mkdir /tmp/blankdb
# pacman -Syw --cachedir "$PWD" --dbpath /tmp/blankdb base base-devel grub-bios xorg gimp
# repo-add ./custom.db.tar.zst ./*.pkg.tar.zst

Then you can burn the "Packages" directory to an optical disc (e.g. CD, DVD) or transfer it to a USB flash drive, external HDD, etc.

To install:

'''1.''' Mount the media:

For an optical disc drive:

# mount --mkdir /dev/sr0 /mnt/repo

For a USB flash drive, hard disk drive, etc.:

# mount --mkdir /dev/sd''xY'' /mnt/repo

'''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:

{{hc|/etc/pacman.conf|2=
[custom]
SigLevel = PackageRequired
Server = file:///mnt/repo/Packages}}

'''3.''' Finally, synchronize the ''pacman'' database to be able to use the new repository:
# pacman -Syu

=== Custom local repository ===

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.
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'', ''.tar.zst'', or ''.tar.Z''. The file does not need to exist, but all parent directories must exist.

To add a new package to the database, or to replace the old version of an existing package in the database, run:

$ repo-add ''/path/to/repo.db.tar.zst /path/to/package-1.0-1-x86_64.pkg.tar.zst''

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:

$ repo-add ''/path/to/repo.db.tar.zst /path/to/*.pkg.tar.zst''

{{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 {{man|8|vercmp}} ordering used by ''pacman''.}}

If you are looking to support multiple architectures, then precautions should be taken to prevent errors from occurring. Each architecture should have its own directory tree:

{{hc|$ tree ~/customrepo/ {{!}} sed "s/$(uname -m)/''arch''/g"|
/home/archie/customrepo/
└── ''arch''
├── customrepo.db -> customrepo.db.tar.zst
├── customrepo.db.tar.zst
├── customrepo.files -> customrepo.files.tar.zst
├── customrepo.files.tar.zst
└── personal-website-git-b99cce0-1-''arch''.pkg.tar.zst

1 directory, 5 files
}}

The ''repo-add'' executable checks whether the package is appropriate. If this is not the case, you will be running into error messages similar to this:

==> ERROR: '/home/archie/customrepo/''arch''/foo-''arch''.pkg.tar.zst' does not have a valid database archive extension.

''repo-remove'' is used to remove packages from the package database, except that only package names are specified on the command line.

$ repo-remove ''/path/to/repo.db.tar.zst pkgname''

Once the local repository database has been created, add the repository to {{ic|/etc/pacman.conf}} of each system that is to use the repository. An example of a custom repository is in {{ic|/etc/pacman.conf}}. The repository's name is the database filename with the file extension omitted. In the example above the repository's name simply is ''repo''. Reference the repository's location using a {{ic|file://}} URL, or via HTTP using {{ic|<nowiki>http://localhost/path/to/directory</nowiki>}}.

If willing, add the custom repository to the [[Unofficial user repositories|list of unofficial user repositories]], so that the community can benefit from it.

=== Network shared pacman cache ===

See [[Package proxy cache]].

=== Recreate a package from the file system ===

To recreate a package from the file system, use {{AUR|fakepkg}}. 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.

=== List of installed packages ===

Keeping a list of all explicitly installed packages can be useful to backup a system or quicken the installation of a new one:

$ pacman -Qqe > pkglist.txt

{{Note|
* With option {{ic|-t}}, the packages already required by other explicitly installed packages are not mentioned. If reinstalling from this list they will be installed but as dependencies only.
* With option {{ic|-n}}, foreign packages (e.g. from [[AUR]]) would be omitted from the list.
* Use {{ic|comm -13 <(pacman -Qqdt {{!}} sort) <(pacman -Qqdtt {{!}} sort) > optdeplist.txt}} to also create a list of the installed optional dependencies which can be reinstalled with {{ic|--asdeps}}.
* Use {{ic|pacman -Qqem > foreignpkglist.txt}} to create the list of AUR and other foreign packages that have been explicitly installed.}}

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:

[Trigger]
Operation = Install
Operation = Remove
Type = Package
Target = *

[Action]
When = PostTransaction
Exec = /bin/sh -c '/usr/bin/pacman -Qqe > /etc/pkglist.txt'

=== Install packages from a list ===

To install packages from a previously saved list of packages, while not reinstalling previously installed packages that are already up-to-date, run:

# pacman -S --needed - < pkglist.txt

However, it is likely foreign packages such as from the AUR or installed locally are present in the list. To filter out from the list the foreign packages, the previous command line can be enriched as follows:

# pacman -S --needed $(comm -12 <(pacman -Slq | sort) <(sort pkglist.txt))

Eventually, to make sure the installed packages of your system match the list and remove all the packages that are not mentioned in it:

# pacman -Rsu $(comm -23 <(pacman -Qq | sort) <(sort pkglist.txt))

{{Tip|These tasks can be automated. See {{AUR|bacpac}}, {{AUR|packup}}, {{AUR|pacmanity}}, and {{AUR|pug}} for examples.}}

=== Listing all changed files from packages ===

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}}:

# paccheck --sha256sum --quiet

For recovery of the database see [[#Restore pacman's local database]]. The {{ic|mtree}} files can also be [[#Viewing files inside remote .pkg files|extracted as .MTREE from the respective package files]].

{{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.}}

=== Reinstalling all packages ===

To reinstall all native packages, use:

# pacman -Qqn | pacman -S -

Foreign (AUR) packages must be reinstalled separately; you can list them with {{ic|pacman -Qqm}}.

Pacman preserves the [[installation reason]] by default.

{{Warning|To force all packages to be overwritten, use {{ic|1=--overwrite=*}}, though this should be an absolute last resort. See [[System maintenance#Avoid certain pacman commands]].}}

=== Restore pacman's local database ===

See [[pacman/Restore local database]].

=== Recovering broken install from existing install ===

If you have managed to mess up an Arch install with broken packages, it is possible to re-install all the packages and hopefully get it back up and working again (assuming the root of the broken install is mounted in {{ic|/brokenArch}})

# pacman -S $(pacman -Qq --dbpath /brokenArch/var/lib/pacman) --root /brokenArch --dbpath /brokenArch/var/lib/pacman

=== Viewing files inside remote .pkg files ===

{{Pkg|paccat}} is a small utility that finds which package contains a given file, downloads it and then prints the contents. This can be used to read specific files, restore changed files back to their initial state, and extract files without installing the package.

For example, if you want to see the contents of {{ic|/etc/systemd/logind.conf}} supplied within the {{Pkg|systemd}} package:

$ paccat systemd etc/systemd/logind.conf

Or if you want to see the contents of {{ic|archive.h}} supplied by any package:

$ paccat -F archive.h

{{ic|bsdtar}} can also be used to show the contents:

$ bsdtar -xOf /var/cache/pacman/pkg/systemd-250.4-2-x86_64.pkg.tar.zst etc/systemd/logind.conf

Or you can use {{Pkg|vim}} to browse the archive:

$ vim /var/cache/pacman/pkg/systemd-250.4-2-x86_64.pkg.tar.zst

=== Find applications that use libraries from older packages ===

Already running processes do not automatically notice changes caused by updates. Instead, they continue using old library versions. That may be undesirable, due to potential issues related to security vulnerabilities or other bugs, and version incompatibility.

Processes depending on updated libraries may be found using either {{Pkg|htop}}, which highlights the names of the affected programs, or with a snippet based on {{Pkg|lsof}}, which also prints the names of the libraries:

# lsof +c 0 | grep -w DEL | awk '1 { print $1 ": " $NF }' | sort -u

This solution will only detect files, that are normally kept opened by running processes, which basically limits it to shared libraries ({{ic|.so}} files). It may miss some dependencies, like those of Java or Python applications.

=== Installing only content in required languages ===

Many packages install documentation and translations in several languages. Some programs are designed to remove such unnecessary files, such as {{AUR|localepurge}}, which runs after a package is installed to delete the unneeded locale files. A more preemptive approach is provided through the {{ic|NoExtract}} directive in {{ic|/etc/pacman.conf}}, which prevent these files from ever being installed.

{{Note|As explained in [[Pacman#Skip files from being installed to system]], "later rules override previous ones, and you can negate a rule by prepending {{ic|!}}".}}

To prevent the installation of all translations for help files, except for the C locale, add:

NoExtract = usr/share/help/* !usr/share/help/C/*

To prevent the installation of all the HTML documentation, add:

NoExtract = usr/share/gtk-doc/html/*
NoExtract = usr/share/doc/HTML/*

{{Warning|1=Some users noted that removing '''all''' locales has resulted in unintended consequences with [[Special:Permalink/460285#Dangerous NoExtract example|dmenu]], [[Special:Permalink/767628#Languages: NoExtract usr/share/X11/locale/*|Steam]], even under [https://bbs.archlinux.org/viewtopic.php?id=250846 Xorg]. The following example is adjusted to avoid such issues, by installing only English (US) files and the required C locales.}}

To prevent the installation of the various [[locale]]s, except the required ones, add:

{{bc|1=
NoExtract = usr/share/locale/* usr/share/X11/locale/*/* usr/share/i18n/locales/* opt/google/chrome/locales/* !usr/share/X11/locale/C/* !usr/share/X11/locale/en_US.UTF-8/*
NoExtract = !usr/share/X11/locale/compose.dir !usr/share/X11/locale/iso8859-1/*
NoExtract = !*locale*/en*/* !usr/share/*locale*/locale.*
NoExtract = !usr/share/*locales/en_?? !usr/share/*locales/i18n* !usr/share/*locales/iso*
NoExtract = usr/share/i18n/charmaps/* !usr/share/i18n/charmaps/UTF-8.gz !usr/share/i18n/charmaps/ANSI_X3.4-1968.gz
NoExtract = !usr/share/*locales/trans*
NoExtract = !usr/share/*locales/C !usr/share/*locales/POSIX
}}

To prevent the installation of the translated [[man page]]s, add:

NoExtract = usr/share/man/* !usr/share/man/man*

To prevent the installation of the language files in {{Pkg|vim-runtime}}, add:

NoExtract = usr/share/vim/vim*/lang/*

To prevent the installation of all but English content in [[Qt]] applications, add:

NoExtract = usr/share/*/translations/*.qm !usr/share/*/translations/*en.qm usr/share/*/nls/*.qm usr/share/qt/phrasebooks/*.qph usr/share/qt/translations/*.pak !*/en-US.pak

To prevent the installation of all but English content in [[Chromium]] and [[Electron]] applications, add:

NoExtract = usr/share/*/locales/*.pak opt/*/locales/*.pak usr/lib/*/locales/*.pak !*/en-US.pak

To prevent the installation of English help files in [[LibreOffice]], add:

NoExtract = usr/lib/libreoffice/help/en-US/*

To prevent the installation of all but English content from [[List of applications/Documents#Office suites|OnlyOffice]], add:

{{bc|1=
NoExtract = opt/onlyoffice/desktopeditors/dictionaries/* !opt/onlyoffice/desktopeditors/dictionaries/en_US/*
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/locale/* !*/en.json
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/resources/help/*/* !*/help/en/*
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/*/main/resources/symboltable/* !*/en.json
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/documenteditor/forms/locale/* !*/en.json
NoExtract = opt/onlyoffice/desktopeditors/editors/web-apps/apps/spreadsheeteditor/main/resources/formula-lang/* !*/en.json !*/en_desc.json
NoExtract = opt/onlyoffice/desktopeditors/converter/empty/*/* !opt/onlyoffice/desktopeditors/converter/empty/en-US/*
NoExtract = opt/onlyoffice/desktopeditors/converter/templates/*/* !opt/onlyoffice/desktopeditors/converter/templates/EN/*
}}

To prevent the installation of all but the English [[iBus]] dictionary for emojis, add:

NoExtract = usr/share/ibus/dicts/emoji-*.dict !usr/share/ibus/dicts/emoji-en.dict

=== Installing packages on bad connection ===

When trying to install a package from a bad connection (e.g. a train using a cell phone), use the {{ic|--disable-download-timeout}} option to lessen the chance of receiving errors such as:

error: failed retrieving file […] Operation too slow. Less than 1 bytes/sec transferred the last 10 seconds

or

error: failed retrieving file […] Operation timed out after 10014 milliseconds with 0 out of 0 bytes received

== Performance ==

=== Download speeds ===

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]].

Pacman's speed in downloading packages can also be improved by using [[pacman#Parallel downloads|parallel downloads]], a major feature request ({{Bug|20056}}) added with [https://gitlab.archlinux.org/pacman/pacman/-/blob/master/NEWS#L80 pacman 6.0.0]. It is enabled by default since [https://gitlab.archlinux.org/archlinux/packaging/packages/pacman/-/commit/e151844c10fab9f8ea070f9cb24a63675298303c pacman 7.0.0].

Instead of ''pacman''<nowiki/>'s built-in file downloader, a separate application can also be used to download packages.

In all cases, make sure you have the latest ''pacman'' before doing any modifications.

# pacman -Syu

==== wget ====

This is very handy if you need more powerful proxy settings than ''pacman''<nowiki/>'s built-in capabilities.

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:

XferCommand = /usr/bin/wget --passive-ftp --show-progress -c -q -N %u

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}}).

==== aria2 ====

[[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.

Install {{Pkg|aria2}}, then edit {{ic|/etc/pacman.conf}} by adding the following line to the {{ic|[options]}} section:

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

{{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.}}

See {{man|1|aria2c|OPTIONS}} for used aria2c options.

* {{ic|-d, --dir}}: The directory to store the downloaded file(s) as specified by ''pacman''.
* {{ic|-o, --out}}: The output file name(s) of the downloaded file(s).
* {{ic|%o}}: Variable which represents the local filename(s) as specified by ''pacman''.
* {{ic|%u}}: Variable which represents the download URL as specified by ''pacman''.

==== Other applications ====

There are other downloading applications that you can use with ''pacman''. Here they are, and their associated XferCommand settings:

* {{ic|snarf}}: {{ic|1=XferCommand = /usr/bin/snarf -N %u}}
* {{ic|lftp}}: {{ic|1=XferCommand = /usr/bin/lftp -c pget %u}}
* {{ic|axel}}: {{ic|1=XferCommand = /usr/bin/axel -n 2 -v -a -o %o %u}}
* {{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)
* {{ic|saldl}}: {{ic|1=XferCommand = /usr/bin/saldl -c6 -l4 -s2m -o %o %u}} (please read the [https://saldl.github.io documentation on the project page] for more info)

== Utilities ==

{{Tip|Many of the (unsupported) [[AUR helpers]] also function as Pacman wrappers, some of which are graphical.}}

* {{App|isfree|A Bash script to list non-free packages. Based on Parabola's blacklist.|https://github.com/leo-arch/isfree|{{AUR|isfree}}}}
* {{App|Lostfiles|Script that identifies files not owned by any package.|https://github.com/graysky2/lostfiles|{{Pkg|lostfiles}}}}
* {{App|pacutils|Helper library for libalpm based programs.|https://github.com/andrewgregory/pacutils|{{Pkg|pacutils}}}}
* {{App|[[pkgfile]]|Tool that finds what package owns a file.|https://github.com/falconindy/pkgfile|{{Pkg|pkgfile}}}}
* {{App|pkgtop|Interactive package manager and resource monitor designed for the GNU/Linux.|https://github.com/orhun/pkgtop|{{AUR|pkgtop-git}}}}
* {{App|repoctl|Tool to help manage local repositories.|https://github.com/cassava/repoctl|{{AUR|repoctl}}}}
* {{App|repose|An Arch Linux repository building tool.|https://github.com/vodik/repose|{{Pkg|repose}}}}
* {{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}}}}
* {{App|vrms-arch|A virtual Richard M. Stallman to tell you which non-free packages are installed.|https://github.com/orospakr/vrms-arch|{{AUR|vrms-arch-git}}}}

=== Graphical ===

{{Warning|PackageKit opens up system permissions by default, and is otherwise [https://github.com/archlinux/archinstall/issues/1321#issuecomment-1151343223 not recommended] for general usage. See {{Bug|50459}} and {{Bug|57943}}.}}

* {{App|Discover|Qt application manager using PackageKit written in C++/QML. Supports [https://www.freedesktop.org/wiki/Distributions/AppStream/ AppStream metadata], [[Flatpak]] and [[fwupd|firmware updates]]. Part of {{Grp|plasma}}.|https://apps.kde.org/discover/|{{Pkg|discover}}}}
* {{App|GNOME PackageKit|GTK package manager using PackageKit written in C.|https://freedesktop.org/software/PackageKit/|{{Pkg|gnome-packagekit}}}}
* {{App|pcurses|Curses TUI ''pacman'' wrapper written in C++.|https://github.com/schuay/pcurses|{{AUR|pcurses}}}}
* {{App|tkPacman|Tk pacman wrapper written in Tcl.|https://sourceforge.net/projects/tkpacman|{{AUR|tkpacman}}}}

User talk:Indigo

2026-05-09T13:47:00Z

Indigo: /* Configuring MAC address randomization */ re, close

Feel free to leave comments about my wiki edits or other points of interest. Please note my account does not automatically watch articles I edit, but I have enabled [[Special:Preferences#mw-prefsection-echo|web notifications]]. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 17:47, 16 November 2024 (UTC)

== Comments ==

== <s> Configuring MAC address randomization </s>==

Hi! The accuracy template for [[NetworkManager#Configuring MAC address randomization]] says an entry should be provided at [[MAC address spoofing#iwd]]. Please refer to the 1st note point in that section which talks specifically about that issue. The accuracy template is for disputed facts, but the note explicitly talks about the issue. Please clarify what the dispute is about. [[User:TheKnightSky|TheKnightSky]] ([[User talk:TheKnightSky|talk]]) 11:59, 8 May 2026 (UTC)

:Done with [https://wiki.archlinux.org/index.php?title=NetworkManager&diff=873421&oldid=873284]. Closing. You're welcome to adjust it or re-open this if unclear. An accuracy template always refers to the section it is added to, i.e. the crosslink was a suggestion to point to the section with the resolution. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 13:47, 9 May 2026 (UTC)

NetworkManager

2026-05-09T13:31:44Z

Indigo: /* Configuring MAC address randomization */ add diff reference to template

[[Category:Network managers]]
[[Category:DHCP]]
[[ar:Networkmanager]]
[[de:Networkmanager]]
[[fr:NetworkManager]]
[[hu:NetworkManager]]
[[ja:NetworkManager]]
[[pt:NetworkManager]]
[[ru:NetworkManager]]
[[zh-hans:NetworkManager]]
{{Related articles start}}
{{Related|NetworkManager/Privacy}}
{{Related|Network configuration}}
{{Related|Wireless network configuration}}
{{Related articles end}}

[[Wikipedia:NetworkManager|NetworkManager]] is a program for providing detection and configuration for systems to automatically connect to networks.

[https://networkmanager.dev/ NetworkManager] 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.

{{Warning|By default, secrets—e.g. Wi-Fi passwords—are accessible to the root user in the filesystem and to users with access to settings via the GUI (e.g. via [[#nm-applet]]). For more information, see [[#Encrypted Wi-Fi passwords]].}}

== Installation ==

NetworkManager can be [[install]]ed with the package {{Pkg|networkmanager}}, which contains a daemon, a command line interface (''nmcli'') and a curses‐based interface (''nmtui'').

=== Enable NetworkManager ===

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.

{{Note|
* Each network interface should be managed by only one [[Network configuration#Network managers|DHCP client or network manager]], so it is advised to run only one DHCP client or network manager on the system. Find a list of the currently running services with {{ic|1=systemctl --type=service}} and then [[stop]] or reconfigure those that conflict.
* If [[systemd-resolved]] is not [[started]], an error message will start flooding your logs. See [[#Unit dbus-org.freedesktop.resolve1.service not found]] for more info.
}}

=== Additional interfaces ===

* {{Pkg|nm-connection-editor}} for a graphical user interface,
* {{Pkg|network-manager-applet}} for a system tray applet (see the [[#nm-applet]] section).

=== Mobile broadband support ===

NetworkManager uses [[ModemManager]] for mobile broadband connection support.

[[Install]] {{Pkg|modemmanager}} and {{Pkg|usb_modeswitch}}. Afterwards [[enable]] and [[start]] {{ic|ModemManager.service}}.

It may be necessary to [[restart]] {{ic|NetworkManager.service}} for it to detect ModemManager. After you restart it, re-plug the modem again and it should be recognized.

Add connections from a front-end (e.g. {{Pkg|nm-connection-editor}}) and select mobile broadband as the connection type. After selecting your ISP and billing plan, [[Wikipedia:Access Point Name|APN]] and other settings should be filled in automatically using information from {{Pkg|mobile-broadband-provider-info}}.

=== PPPoE / DSL support ===

[[Install]] {{Pkg|ppp}} package for PPPoE / DSL connection support. To actually add PPPoE connection, use {{ic|1=nm-connection-editor}} and add new DSL/PPPoE connection.

=== VPN support ===

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.

Support for other VPN types is based on a plug-in system. They are provided in the following packages:

* {{Pkg|networkmanager-openconnect}} for [[OpenConnect]]
* {{Pkg|networkmanager-openvpn}} for [[OpenVPN]]
* {{Pkg|networkmanager-pptp}} for [[PPTP Client]]
* {{Pkg|networkmanager-strongswan}} for [[strongSwan]]
* {{Pkg|networkmanager-vpnc}}
* {{AUR|networkmanager-fortisslvpn}}
* {{AUR|networkmanager-iodine-git}}
* {{AUR|networkmanager-libreswan}}
* {{Pkg|networkmanager-l2tp}}
* {{AUR|networkmanager-ssh}}
* {{Pkg|network-manager-sstp}}

{{Warning|1=There are a lot of [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues?search=VPN&state=opened bugs] related to VPN support. Check the daemon processes options set via the GUI correctly and double-check with each package release.}}

{{Note|
* To have fully functioning DNS resolution when using VPN, you should set up [[#DNS caching and conditional forwarding|conditional forwarding]].
* These plug-ins may not have a documented command line interface, or may not work at all without an applet running. This is not an issue if you are using a regular desktop environment; if you are not, you should run [[#nm-applet]] while configuring or activating the connection so that you get the necessary dialogues. [https://bbs.archlinux.org/viewtopic.php?id{{=}}246698]
}}

== Usage ==

NetworkManager comes with {{man|1|nmcli}} and {{man|1|nmtui}}.

=== nmcli examples ===

List nearby Wi-Fi networks:

$ nmcli device wifi list

Connect to a Wi-Fi network:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password''

Connect to a hidden Wi-Fi network:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' hidden yes

Connect to a Wi-Fi on the {{ic|wlan1}} interface:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' ifname wlan1 ''profile_name''

Disconnect an interface:

$ nmcli device disconnect ifname eth0

Get a list of connections with their names, UUIDs, types and backing devices:

$ nmcli connection show

Activate a connection (i.e. connect to a network with an existing profile):

$ nmcli connection up ''name_or_uuid''

Delete a connection:

$ nmcli connection delete ''name_or_uuid''

See a list of network devices and their state:

$ nmcli device

Turn off Wi-Fi:

$ nmcli radio wifi off

=== Edit a connection ===

For a comprehensive list of settings, see {{man|5|nm-settings}}.

Firstly, you need to get a list of connections:

{{hc|$ nmcli connection|<nowiki>
NAME UUID TYPE DEVICE
Wired connection 2 e7054040-a421-3bef-965d-bb7d60b7cecf ethernet enp5s0
Wired connection 1 997f2782-f0fc-301d-bfba-15421a2735d8 ethernet enp0s25
MY-HOME-WIFI-5G 92a0f7b3-2eba-49ab-a899-24d83978f308 wifi --
</nowiki>}}

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.

You have three methods to configure a connection {{ic|Wired connection 2}} after it has been created:

; nmcli interactive editor
: {{ic|nmcli connection edit 'Wired connection 2'}}. Usage is well documented from the editor.

; nmcli command line interface
: {{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.
To remove a setting, pass an empty field ("") to it like this:
: {{ic|nmcli connection modify 'Wired connection 2' ''setting''.''property'' ""}}

; Connection file
: In {{ic|/etc/NetworkManager/system-connections/}}, modify the corresponding {{ic|Wired connection 2.nmconnection}} file . Do not forget to reload the configuration file with {{ic|nmcli connection reload}}.

=== nmtui ===

NetworkManager ships a text user interface (TUI) for managing connections, the system hostname and radio switches. It can be launched by running {{ic|nmtui}}.

== Front-ends ==

To provide integration with a [[desktop environment]], most users will want to install an applet. This not only provides easy access to network selection and configuration, but also provides the agent necessary for securely storing secrets. Various desktop environments have their own applet; otherwise, you can use [[#nm-applet]].

=== GNOME ===

[[GNOME]] has a built-in tool, accessible from the Network settings.

=== KDE Plasma ===

[[Install]] the {{Pkg|plasma-nm}} package. After that, add it to the KDE taskbar via the ''Panel options > Add widgets > Networks'' menu.

=== nm-applet ===

{{Pkg|network-manager-applet}} is a GTK 3 front-end which works under Xorg environments with a systray.

To store connection secrets install and configure an application which implements the [https://specifications.freedesktop.org/secret-service-spec/latest/ Secret Service D-Bus API] such as [[GNOME/Keyring]], [[KDE Wallet]], or [[KeePassXC]].

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]].

In order to run {{ic|nm-applet}} without a systray, you can use {{AUR|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:

{{hc|nmgui|<nowiki>
#!/bin/sh
nm-applet 2>&1 > /dev/null &
stalonetray 2>&1 > /dev/null
killall nm-applet
</nowiki>}}

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.

The applet can show notifications for events such as connecting to or disconnecting from a Wi-Fi 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 applet might hang. See [https://bugzilla.gnome.org/show_bug.cgi?id=788313].

In order to run {{ic|nm-applet}} with such notifications disabled, start the applet with the following command:

$ nm-applet --no-agent

{{Tip|{{ic|nm-applet}} might be started automatically with a [[XDG Autostart|autostart desktop file]], to add the {{ic|--no-agent}} option modify the Exec line there, i.e.

{{bc|1=Exec=nm-applet --no-agent}}

}}

{{Warning|On [[i3]], if nm-applet is started with the {{ic|--no-agent}} option, it is not possible to connect to a new encrypted Wi-Fi 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}}.}}

==== Appindicator ====

As of version 1.18.0 Appindicator support is [https://gitlab.archlinux.org/archlinux/packaging/packages/network-manager-applet/-/commit/527448fb2a87d85055f504f463dfe961dccd75c3 available] in the official {{Pkg|network-manager-applet}} package. To use nm-applet in an Appindicator environment start the applet with the following command:

$ nm-applet --indicator

=== networkmanager-dmenu ===

Alternatively there is {{Pkg|networkmanager-dmenu}} 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 Wi-Fi or wired connections, connect to new Wi-Fi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch ''nm-connection-editor'' GUI, connect to Bluetooth networks.

=== switchboard ===

Pantheon's {{Pkg|switchboard}} offers a desktop environment-agnostic way to configure NetworkManager when combined with {{Pkg|switchboard-plug-network}} and {{Pkg|nm-connection-editor}}. It can be ran with the following command:

$ io.elementary.settings

== Configuration ==

NetworkManager may 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.

NetworkManager has a global configuration file at {{ic|/etc/NetworkManager/NetworkManager.conf}}. Additional configuration files can be placed in {{ic|/etc/NetworkManager/conf.d/}}. Usually no configuration needs to be done to the global defaults.

After editing a configuration file, the changes can be applied by running:

# nmcli general reload

=== NetworkManager-wait-online ===

Enabling {{ic|NetworkManager.service}} also enables {{ic|NetworkManager-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 finish 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]].

By default, {{ic|NetworkManager-wait-online.service}} waits for NetworkManager startup to complete, rather than waiting for network connectivity specifically (see {{man|1|nm-online}}). If {{ic|NetworkManager-wait-online.service}} finishes before the network is really up, resulting in failed services on boot, [[extend the unit]] to remove the {{ic|-s}} from the {{ic|ExecStart}} line:

[Service]
ExecStart=
ExecStart=/usr/bin/nm-online -q

Be aware that this can cause [https://lists.fedoraproject.org/archives/list/users@lists.fedoraproject.org/thread/EGC324JD3HJCGVN7J55WYPRLFDA3TP7N/ other issues].

In some cases, the service will still fail to start successfully on boot due to the timeout setting being too short. [[Edit]] the service to change {{ic|NM_ONLINE_TIMEOUT}} from {{ic|60}} to a higher value.

=== Set up PolicyKit permissions ===

By default, all users in active local sessions are allowed to change most network settings without a password. See [[General troubleshooting#Session permissions]] to check your session type. In most cases, everything should work out of the box.

Some actions (such as changing the system hostname) require an administrator password. In this case, you need to [[Users and groups#Group management|add]] yourself to the {{ic|wheel}} group and run a [[Polkit#Authentication agents|Polkit authentication agent]] which will prompt for your password.

For remote sessions (e.g. [[TigerVNC#Running vncserver for virtual (headless) sessions|headless VNC]]), you have several options for obtaining the necessary privileges to use NetworkManager:

# [[Users and groups#Group management|Add]] yourself to the {{ic|wheel}} group. You will have to enter your password for every action. Note that your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.
# [[Users and groups#Group management|Add]] yourself to the {{ic|network}} group and create {{ic|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules}} with the following content: {{bc|<nowiki>
polkit.addRule(function(action, subject) {
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {
return polkit.Result.YES;
}
});
</nowiki>}} All users in the {{ic|network}} group will be able to add and remove networks without a password (which means you do not have to run a Polkit authentication agent, so this option will also work in SSH sessions).

=== Proxy settings ===

NetworkManager does support some proxy settings. While they can not be directly modified using ''nmtui'', ''nm-applet'' and ''nmcli'' support those.
See the proxy settings in {{man|5|nm-settings-nmcli}}.

Additionally, custom proxy commands can always be run using dispatcher scripts, see [[#Dispatcher examples]].

See also [[Proxy settings]].

=== Checking connectivity ===

NetworkManager can try to reach a webserver after connecting to a network in order to determine if it is e.g behind a captive portal. The default host (configured in {{ic|/usr/lib/NetworkManager/conf.d/20-connectivity.conf}}) is [https://ping.archlinux.org ping.archlinux.org] (a CNAME alias of redirect.archlinux.org). To use a different webserver or to 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]]):

{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki>
[connectivity]
uri=http://nmcheck.gnome.org/check_network_status.txt
</nowiki>}}

To disable NetworkManager's connectivity check, use the following configuration. This can be useful when connected to a VPN that blocks connectivity checks.

{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki>
[connectivity]
enabled=false
</nowiki>}}

{{Note|Although automatic connectivity checks are a potential privacy leak, Arch Linux's default connectivity URL is committed to not logging any access. See [https://gitlab.archlinux.org/archlinux/infrastructure/-/commit/fabccd0f61e5dea3925e8a0c6a46d56d5750c121#a4f34381bbb18ea77bfb3dd11a8aeca707078fca_0_26] [https://gitlab.archlinux.org/archlinux/infrastructure/-/blob/master/roles/ping/templates/nginx.d.conf.j2].}}

=== Captive portals ===

{{Style|Complex scripts should not be maintained on the wiki.}}

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 has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:

{{hc|/etc/NetworkManager/dispatcher.d/90-open_captive_portal|<nowiki>
#!/bin/sh -e
# Script to dispatch NetworkManager events
#
# Runs shows a login webpage on walled garden networks.
# See NetworkManager(8) for further documentation of the dispatcher events.

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

if [ -x "/usr/bin/logger" ]; then
logger="/usr/bin/logger -s -t captive-portal"
else
logger=":"
fi

wait_for_process() {
PNAME=$1
while [ -z "$(/usr/bin/pgrep $PNAME)" ]; do
sleep 3;
done
}

#launch the browser, but on boot we need to wait that nm-applet starts
start_browser() {
local user="$1"
local display="$2"

export DISPLAY="$display"
wait_for_process nm-applet

export XAUTHORITY="/home/$user/.Xauthority"

$logger "Running browser as '$user' with display '$display' to login in captive portal"
sudo -u "$user" --preserve-env=DISPLAY,XAUTHORITY -H xdg-open http://capnet.elementary.io 2>&1 > /dev/null
}

# Run the right scripts
case "$2" in
connectivity-change)
$logger -p user.debug "dispatcher script triggered on connectivity change: $CONNECTIVITY_STATE"
if [ "$CONNECTIVITY_STATE" = "PORTAL" ]; then
# Match last column of who's output with ' :[at least one digit] '
who | awk '$NF ~ /$:[0-9]+$/ { print $1 " " substr($NF, 2, length($NF)-2) };' | \
while read user display; do
start_browser $user $display || $logger -p user.err "Failed for user: '$user' display: '$display'"
done
fi
;;
*)
# In a down phase
exit 0
;;
esac
</nowiki>}}

Make the script [[executable]]. But that script assumes you use X and simply opens http page. It might not work for everyone.

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.

Simple solution is [https://github.com/Seme4eg/captive-portal-sh captive-portal-sh] - shell script that obtains captive portal URL and opens it in your default browser (for Wayland users only).

Another solution is {{AUR|captive-browser-git}} based on Google Chrome.

==== iwd support for captive portal support on legacy hardware ====

Some older Wi-Fi chips (e.g. Broadcom BCM4360) require the proprietary {{ic|wl}} driver, which lacks support for the OWE/Elliptic-Curve handshake that many captive-portal hotspots use before presenting a login page. By switching NetworkManager’s Wi-Fi backend to {{ic|iwd}} (see [[#Using iwd as the Wi-Fi backend]]), which implements the full OWE key exchange in userspace over the existing driver, you can complete the encrypted association, obtain a DHCP lease, and trigger the portal “PORTAL” state. Once that is done, any dispatcher script or browser-launcher will reliably pop up the login page on hardware that otherwise could never fully connect.

=== DHCP client ===

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.

To use a different DHCP client [[install]] one of the alternatives:

* {{Pkg|dhcpcd}} - [[dhcpcd]]
* {{Pkg|dhclient}} - [[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.:

{{hc|1=/etc/NetworkManager/conf.d/dhcp-client.conf|2=
[main]
dhcp=dhcpcd
}}

{{Note|
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.
}}

=== DNS management ===

NetworkManager's DNS management is described in the GNOME project's wiki page—[https://wiki.gnome.org/Projects/NetworkManager/DNS Projects/NetworkManager/DNS].

==== DNS caching and conditional forwarding ====

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.

{{Note|If {{ic|/etc/resolv.conf}} is a symlink to {{ic|/run/systemd/resolve/stub-resolv.conf}}, {{ic|/run/systemd/resolve/resolv.conf}},{{ic|/lib/systemd/resolv.conf}} or {{ic|/usr/lib/systemd/resolv.conf}}, NetworkManager will choose systemd-resolved automatically. To use dnsmasq, you must first remove that symlink, then restart NetworkManager.}}

===== dnsmasq =====

Make sure {{Pkg|dnsmasq}} has been installed. Then set {{ic|1=main.dns=dnsmasq}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=dnsmasq
}}

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.

{{Note|
* 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).
* 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.
}}

====== Custom dnsmasq configuration ======

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):

{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=
cache-size=1000
}}

You can check the configuration file syntax with:

$ dnsmasq --test --conf-file=/dev/null --conf-dir=/etc/NetworkManager/dnsmasq.d

See {{man|8|dnsmasq}} for all available options.

====== IPv6 ======

{{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}}.}}

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:

{{hc|/etc/NetworkManager/dnsmasq.d/ipv6-listen.conf|2=
listen-address=::1
}}

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.

====== DNSSEC ======

The dnsmasq instance started by NetworkManager by default will not validate [[DNSSEC]]. To enable DNSSEC validation, thus breaking DNS resolution with name servers that do not support it, create the following configuration file:

{{hc|/etc/NetworkManager/dnsmasq.d/dnssec.conf|2=
conf-file=/usr/share/dnsmasq/trust-anchors.conf
dnssec
}}

===== systemd-resolved =====

{{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]]?}}

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.

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}}.

You can enable it explicitly by setting {{ic|1=main.dns=systemd-resolved}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=systemd-resolved
}}

===== DNS resolver with an openresolv subscriber =====

If [[openresolv]] has a subscriber for your local [[DNS resolver]], set up the subscriber and [[#Use openresolv|configure NetworkManager to use openresolv]].

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].

This can be partially mitigated if you set {{ic|1=private_interfaces="*"}} in {{ic|/etc/resolvconf.conf}}[https://roy.marples.name/projects/openresolv/configuration/]. 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.

==== Custom DNS servers ====

===== Setting custom global DNS servers =====

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:

{{hc|/etc/NetworkManager/conf.d/dns-servers.conf|2=
[global-dns-domain-*]
servers=::1,127.0.0.1
}}

{{Note|
* 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.
* The specified servers do not get sent to [[systemd-resolved]], the connection's DNS servers are used instead. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/1366 NetworkManager issue 1366] and [https://github.com/systemd/systemd/issues/33754 systemd issue 33754].
}}

===== Setting custom DNS servers in a connection =====

====== Setting custom DNS servers in a connection (GUI) ======

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'', ...}}.

====== Setting custom DNS servers in a connection (nmcli / connection file) ======

To set up DNS Servers per connection, you change the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings (and their associated {{ic|dns-search}} and {{ic|dns-options}}) in the [[#Edit a connection|connection settings]].

If {{ic|method}} is set to {{ic|auto}} (when you use DHCP/RA), you need to set {{ic|ignore-auto-dns}} to {{ic|yes}}.

To use DNS over TLS ([[#systemd-resolved|requires systemd-resolved]]), specify the DNS servers using the syntax {{ic|1=dns=''ip.address''#''servername'';}} and additionally set the {{ic|connection.dns-over-tls}} setting to {{ic|2}}. For example, to use Quad9:

{{hc|/etc/NetworkManager/system-connections/Example Wi-Fi.nmconnection|2=
...
[connection]
...
dns-over-tls=2

[ipv4]
...
dns=9.9.9.9#dns.quad9.net;149.112.112.112#dns.quad9.net;
ignore-auto-dns=true

[ipv6]
...
dns=2620:fe::fe#dns.quad9.net;2620:fe::9#dns.quad9.net;
ignore-auto-dns=true
}}

{{Note|This example uses Quad9. Replace it with a DNS resolver you trust. See [[Domain name resolution#Third-party DNS services]].}}

==== /etc/resolv.conf ====

NetworkManager's {{ic|/etc/resolv.conf}} management mode is configured with the {{ic|main.rc-manager}} setting. {{Pkg|networkmanager}} sets it to {{ic|symlink}} as opposed to the upstream default {{ic|auto}}. The setting and its values are documented in the {{man|5|NetworkManager.conf}} man page.

{{Tip|Using openresolv allows NetworkManager to coexist 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]]. Note that conditional forwarding is [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 not yet fully supported] when using NetworkManager with openresolv.}}

''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.

{{Note|
* 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}}.
* The {{ic|resolv.conf}} file NetworkManager writes or would write to {{ic|/etc/resolv.conf}} can be found at {{ic|/run/NetworkManager/resolv.conf}}.
* A {{ic|resolv.conf}} file with the acquired name servers and search domains can be found at {{ic|/run/NetworkManager/no-stub-resolv.conf}}.
}}

===== Unmanaged /etc/resolv.conf =====

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/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=none
}}

{{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]].}}

{{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}}.}}

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.

===== Use openresolv =====

{{Note|NetworkManager does not support using systemd-resolved's ''resolvconf'' interface ({{man|1|resolvectl|COMPATIBILITY WITH RESOLVCONF(8)}}) which is provided by {{Pkg|systemd-resolvconf}}.
* Do not set {{ic|1=main.rc-manager=resolvconf}} when using [[systemd-resolved]], instead make sure to [[systemd-resolved#DNS|correctly create the /etc/resolv.conf symlink]] or [[#systemd-resolved|configure NetworkManager to use systemd-resolved explicitly]].
* Make sure the {{Pkg|systemd-resolvconf}} package is not installed when systemd-resolved is not used. Unless {{ic|systemd-resolved.service}} started, it will break all networking software (not just NetworkManager) that use resolvconf.
}}

To configure NetworkManager to use [[openresolv]], set {{ic|1=main.rc-manager=resolvconf}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/rc-manager.conf|2=
[main]
rc-manager=resolvconf
}}

=== Firewall ===

You can [[Firewalld#Using NetworkManager to manage zones|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.

This can also be done with [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher]].

== Network services with NetworkManager dispatcher ==

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]]).

To activate the feature you need to [[enable]] and [[start]] the {{ic|NetworkManager-dispatcher.service}}.

Once the service is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory.

Scripts must be owned by '''root''', otherwise the dispatcher will not execute them. For added security, set group [[ownership]] to root as well:

# chown root:root /etc/NetworkManager/dispatcher.d/''10-script.sh''

Make sure the file is [[executable]].

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).

Scripts will receive the following arguments:

* '''Interface name:''' e.g. {{ic|eth0}}
* '''Action:''' ''up'', ''down'', ''vpn-up'', ''vpn-down'', ... (see {{man|8|NetworkManager-dispatcher}} for the complete list)

{{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.}}

=== Avoiding the dispatcher timeout ===

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 use a [[drop-in file]] for the {{ic|NetworkManager-dispatcher.service}} to remain active after exit:

{{hc|/etc/systemd/system/NetworkManager-dispatcher.service.d/remain_after_exit.conf|2=
[Service]
RemainAfterExit=yes
}}

Now start and enable the modified {{ic|NetworkManager-dispatcher}} service.

{{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.}}

=== Dispatcher examples ===

==== Automatically set the timezone ====

Create a [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]] and make it [[executable]]:

{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|
#!/bin/sh
case "$2" in
up)
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"
;;
esac
}}

{{Tip|Using {{ic|connectivity-change}} instead of {{ic|up}} can prevent timezone changes when connecting to VPNs with clients such as [[OpenConnect]].}}

Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.

==== Mount remote directory with sshfs ====

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}}.

{{bc|<nowiki>
#!/bin/sh
USER='username'
REMOTE='user@host:/remote/path'
LOCAL='/local/path'

interface=$1 status=$2
if [ "$CONNECTION_UUID" = "</nowiki>''uuid''<nowiki>" ]; then
case $status in
up)
# sleep 10
SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')
export SSH_AUTH_SOCK
su "$USER" -c "sshfs $REMOTE $LOCAL"
;;
down)
fusermount -u "$LOCAL"
;;
esac
fi
</nowiki>}}

==== Mounting of SMB shares ====

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.

The following script will check if we connected to a specific network and mount shares accordingly:

{{hc|/etc/NetworkManager/dispatcher.d/30-mount-smb.sh|<nowiki>
#!/bin/sh

# Find the connection UUID with "nmcli connection show" in terminal.
# All NetworkManager connection types are supported: wireless, VPN, wired...
if [ "$2" = "up" ]; then
if [ "$CONNECTION_UUID" = "uuid" ]; then
mount /your/mount/point &
# add more shares as needed
fi
fi
</nowiki>}}

The following script will unmount all SMB shares before a software initiated disconnect from a specific network:

{{hc|/etc/NetworkManager/dispatcher.d/pre-down.d/30-umount-smb.sh|<nowiki>
#!/bin/sh

if [ "$CONNECTION_UUID" = "uuid" ]; then
umount -a -l -t cifs
fi
</nowiki>}}

{{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.}}

The following script will attempt to unmount all SMB shares following an unexpected disconnect from a specific network:

{{hc|/etc/NetworkManager/dispatcher.d/40-umount-smb.sh|<nowiki>
#!/bin/sh

if [ "$CONNECTION_UUID" = "uuid" ]; then
if [ "$2" = "down" ]; then
umount -a -l -t cifs
fi
fi
</nowiki>}}

{{Note|
* 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=701242 this bug report] for more info.
* The previous ''umount'' scripts are still prone to leaving applications actually accessing the mount to 'hang'.
}}

An alternative is to use the script as seen in [[NFS#Using a NetworkManager dispatcher]]:

{{hc|/etc/NetworkManager/dispatcher.d/30-smb.sh|<nowiki>
#!/bin/sh

# Find the connection UUID with "nmcli con show" in terminal.
# All NetworkManager connection types are supported: wireless, VPN, wired...
WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"

if [ "$CONNECTION_UUID" = "$WANTED_CON_UUID" ]; then

# Script parameter $1: network interface name, not used
# Script parameter $2: dispatched event

case "$2" in
"up")
mount -a -t cifs
;;
"down"|"pre-down"|"vpn-pre-down")
umount -l -a -t cifs >/dev/null
;;
esac
fi
</nowiki>}}

{{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.}}

Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down/}} to catch the {{ic|pre-down}} events:

# ln -s ../30-smb.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-smb.sh

==== Mounting of NFS shares ====

See [[NFS#Using a NetworkManager dispatcher]].

==== Use dispatcher to automatically toggle wireless depending on LAN cable being plugged in ====

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.

Create the following dispatcher script[https://superuser.com/questions/233448/disable-wlan-if-wired-cable-network-is-available], replacing {{ic|''Your_Ethernet_Interface''}} with your ethernet interface's device name.

{{Note|You can get a list of interfaces using [[#nmcli examples|nmcli]] ({{ic|nmcli d {{!}} grep ethernet}}). The Ethernet interfaces start with {{ic|en}} or {{ic|eth}}, e.g. {{ic|enp0s5}} or {{ic|eth0}}.}}

Remember to make the script [[executable]]. You can verify that it works by [[restart]]ing {{ic|NetworkManager.service}}, running {{ic|ip a}}, and checking that {{ic|wlp3s0}} (or whatever your Wi-Fi interface is called) is in {{ic|state DOWN}}. If you encounter unexpected behavior, check the [[journal]] of {{ic|NetworkManager-dispatcher.service}}.

{{hc|/etc/NetworkManager/dispatcher.d/99-wifi-auto-toggle.sh|2=
#!/bin/sh

LOG_PREFIX="WiFi Auto-Toggle"
ETHERNET_INTERFACE="''Your_Ethernet_Interface''"

if [ "$1" = "$ETHERNET_INTERFACE" ]; then
case "$2" in
up)
echo "$LOG_PREFIX ethernet up"
nmcli radio wifi off
;;
down)
echo "$LOG_PREFIX ethernet down"
nmcli radio wifi on
;;
esac
elif [ "$(nmcli -g GENERAL.STATE device show $ETHERNET_INTERFACE)" = "20 (unavailable)" ]; then
echo "$LOG_PREFIX failsafe"
nmcli radio wifi on
fi
}}

{{Note|There is a fail-safe for the case when the LAN interface was connected when the computer was last on, and then disconnected while the computer was off. That would mean the radio would still be off when the computer is turned back on, and with a disconnected LAN interface, you would have no network.}}

==== Use dispatcher to connect to a VPN after a network connection is established ====

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.

{{Accuracy|A scripting without {{ic|iwgetid}} does work too and may be more reliable?|section=Fixes for automatic VPN dispatcher script}}

{{Note|This script will require {{Pkg|wireless_tools}} in order to use {{ic|iwgetid}}.}}

{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki>
#!/bin/sh
VPN_NAME="name of VPN connection defined in NetworkManager"
ESSID="Wi-Fi network ESSID (not connection name)"

interface=$1 status=$2
case $status in
up|vpn-down)
if iwgetid | grep -qs ":\"$ESSID\""; then
nmcli connection up id "$VPN_NAME"
fi
;;
down)
if iwgetid | grep -qs ":\"$ESSID\""; then
if nmcli connection show --active | grep "$VPN_NAME"; then
nmcli connection down id "$VPN_NAME"
fi
fi
;;
esac
</nowiki>}}

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]].

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.

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''.nmconnection}} and change the {{ic|password-flags}} and {{ic|secret-flags}} from {{ic|1}} to {{ic|0}}.

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:

{{hc|/path/to/passwd-file|
vpn.secrets.password:YOUR_PASSWORD
}}

The script must be changed accordingly, so that it gets the password from the file:

{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki>
#!/bin/sh
VPN_NAME="name of VPN connection defined in NetworkManager"
ESSID="Wi-Fi network ESSID (not connection name)"

interface=$1 status=$2
case $status in
up|vpn-down)
if iwgetid | grep -qs ":\"$ESSID\""; then
nmcli connection up id "$VPN_NAME" passwd-file /path/to/passwd-file
fi
;;
down)
if iwgetid | grep -qs ":\"$ESSID\""; then
if nmcli connection show --active | grep "$VPN_NAME"; then
nmcli connection down id "$VPN_NAME"
fi
fi
;;
esac
</nowiki>}}

2: Alternatively, change the {{ic|password-flags}} and put the password directly in the configuration file adding the section {{ic|vpn-secrets}}:

[vpn]
....
password-flags=0

[vpn-secrets]
password=''your_password''

{{Note|It may now be necessary to re-open the NetworkManager connection editor and save the VPN passwords/secrets again.}}

==== Use dispatcher to disable IPv6 on VPN provider connections ====

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.

{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki>
#!/bin/sh

case "$2" in
vpn-up)
echo 1 > /proc/sys/net/ipv6/conf/all/disable_ipv6
;;
vpn-down)
echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6
;;
esac
</nowiki>}}

{{Note|The above script does not work for WireGuard since NetworkManager does not send the {{ic|vpn-up/down}} events for it. Instead you have to rely on generic events for your WireGuard interfaces as demonstrated in [https://gist.github.com/TheDcoder/85e1ec99a31180e20ba8e4896024f265].}}

As an alternative, dispatcher can be used to temporarily set the IPv6 mode of the device used by the VPN connection to {{ic|link-local}}. This will avoid NetworkManager log spam about IPv6 being disabled. This script will not work if multiple devices or connections provide IPv6 connectivity, but could be adapted to iterate over multiple devices. Note that any change to the connection (using {{man|1|nmcli}} or a [[desktop environment]]) will reapply the entire connection to the device and re-enable IPv6 (if it is enabled in the connection).

{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki>
#!/bin/sh

case "$2" in
vpn-up)
nmcli device modify "${DEVICE_IFACE}" ipv6.method link-local
;;
vpn-down)
nmcli device reapply "${DEVICE_IFACE}"
;;
esac
</nowiki>}}

==== OpenNTPD ====

See [[OpenNTPD#Using NetworkManager dispatcher]].

==== Dynamically set NTP servers received via DHCP with systemd-timesyncd ====

When roaming between different networks (e.g. a company's LAN, Wi-Fi at home, various other Wi-Fi now and then) you might want to set the NTP server(s) used by timesyncd to those provided by DHCP. However, NetworkManager itself is not capable to communicate with systemd-timesyncd to set the NTP server(s).

The dispatcher can work around it.

[[Create]] the overlay directory for your systemd-timesyncd configuration {{ic|/etc/systemd/timesyncd.conf.d}} if it does not already exist. Inside {{ic|/etc/NetworkManager/dispatcher.d}}, put the following:

{{hc|/etc/NetworkManager/dispatcher.d/10-update-timesyncd|<nowiki>
#!/bin/sh

[ -z "$CONNECTION_UUID" ] && exit 0
INTERFACE="$1"
ACTION="$2"

case $ACTION in
up | dhcp4-change | dhcp6-change)
# `DHCP6_DHCP6_NTP_SERVERS` with double `DHCP6` is the correct variable name as varified by `printenv` as of NetworkManager 1.56.0-1
set -- ${DHCP6_DHCP6_NTP_SERVERS-} ${DHCP4_NTP_SERVERS-}
servers=$*
[ -n "$servers" ] || exit 0
mkdir -p /etc/systemd/timesyncd.conf.d
cat <<-THE_END >"/etc/systemd/timesyncd.conf.d/${CONNECTION_UUID}.conf"
[Time]
NTP=$servers
THE_END
systemctl restart systemd-timesyncd.service
;;
down)
rm -f "/etc/systemd/timesyncd.conf.d/${CONNECTION_UUID}.conf"
systemctl restart systemd-timesyncd.service
;;
esac
</nowiki>}}

Every time NetworkManager sets up a new network connection ({{ic|1=ACTION=up}}) or gets some update for an existing connection ({{ic|1=ACTION=dhcp4-change}} or {{ic|1=ACTION=dhcp6-change}}) and the provided connection data contains information about NTP server(s) ({{ic|DHCP6_DHCP6_NTP_SERVERS}} and {{ic|DHCP4_NTP_SERVERS}}), a connection specific overlay configuration file is written to {{ic|/etc/systemd/timesyncd.conf.d}}, containing the provided NTP server(s). Whenever a connection is taken down ({{ic|1=ACTION=down}}) the connection specific overlay file is removed. After each change to the configuration of systemd-timesyncd, this service is restarted to pick up the updated configuration. The use of connection specific configuration files is intentional so that when two or more connections are managed by NetworkManager in parallel the different NTP server names in the configuration are not overwritten as {{ic|up}}, {{ic|dhcp4-change}}, {{ic|dhcp6-change}} and {{ic|down}} actions might come in an arbitrary order.

{{Note|{{ic|1=DHCP6_DHCP6_NTP_SERVERS}} with double {{ic|1=DHCP6}} is the correct variable name as varified by {{ic|1=printenv}} as of NetworkManager 1.56.0-1 }}

== Testing ==

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}}.

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.

To start the GNOME applet in non-xdg-compliant window managers like [[awesome]]:

nm-applet --sm-disable &

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'.

== Tips and tricks ==

=== Encrypted Wi-Fi passwords ===

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:

# grep -r '^psk=' /etc/NetworkManager/system-connections/

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}}).

It is preferable to save the passwords in encrypted form in a keyring instead of clear text. The downside to this is that the connections have to be set up for each user.

In order to read and write to the keyring, there must be a secret agent available. This can be one of:

* {{ic|nmcli}} with the {{ic|--ask}} option
* One of the graphical interfaces from [[#Front-ends]]

If you make neither of these available, then authentication will fail with the error {{ic|no secrets: No agents were available for this request.}}

==== Using GNOME Keyring ====

The keyring daemon has to be started and the keyring needs to be unlocked for the following to work.

Furthermore, NetworkManager needs to be configured not to store the password for all users. Using GNOME's {{Pkg|network-manager-applet}}, run {{ic|nm-connection-editor}} from a terminal, select a network connection, click ''Edit'', select the ''Wi-Fi Security'' tab and click on the right icon of password and check ''Store the password only for this user''.

==== Using KDE Wallet ====

Using KDE's {{Pkg|plasma-nm}}, click the applet, click on the top right ''Settings'' icon, click on a network connection, in the ''General configuration'' tab, untick ''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.

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.

=== Sharing internet connection over Wi-Fi ===

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.

You will need a Wi-Fi card which supports AP mode, see [[Software access point#Wi-Fi device must support AP mode]] for details.

[[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.

Create the shared connection:

* Click on applet and choose ''Create new wireless network''.
* Follow wizard (choose WPA2 or higher, be sure to use at least 8 character long password, lower lengths will fail).
** Choose either [[Fedora:Features/RealHotspot|Hotspot]] or Ad-hoc as Wi-Fi mode.

The connection will be saved and remain stored for the next time you need it.

{{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").}}

=== Sharing internet connection over Ethernet ===

Scenario: your device has internet connection over Wi-Fi and you want to share the internet connection to other devices over Ethernet.

Requirements:

* [[Install]] the {{Pkg|dnsmasq}} and {{Pkg|nm-connection-editor}} packages to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.
* 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).
* Internet sharing is not blocked by a [[firewall]].

Steps:

* Run {{ic|nm-connection-editor}} from terminal.
* Add a new Ethernet connection.
* Give it some sensible name. For example "Shared Internet"
* Go to "IPv4 Settings".
* For "Method:" select "Shared to other computers".
* Save

Now you should have a new option "Shared Internet" under the Wired connections in NetworkManager.

=== Checking if networking is up inside a cron job or script ===

{{Out of date|''nm-tool'' was removed from NetworkManager for long time now[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/bb8c75bd536d4f8fb80a4366025a279078f0ec81]. ''nmcli'' should be used instead.}}

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.

{{bc|<nowiki>
if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then
#Whatever you want to do if the network is online
else
#Whatever you want to do if the network is offline - note, this and the else above are optional
fi
</nowiki>}}

This is 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.

=== Connect to network with secret on boot ===

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:

# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab
# Select the connection you want to work with and click the Edit button
# Check the boxes “Connect Automatically” and “Available to all users”
# Additionally, ensure that under "Wi-Fi Security", "Store password for all users (not encrypted)" is selected

Log out and log back in to complete.

=== OpenConnect with password in KWallet ===

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]].

Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and
enter your credentials in key "VpnSecrets" in this form (replace ''username'' and ''password'' accordingly):

form:main:username%SEP%''username''%SEP%form:main:password%SEP%''password''

Next time you connect, username and password should appear in the "VPN secrets" dialog box.

=== Ignore specific devices ===

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}}:

[keyfile]
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth0

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.

=== Configuring MAC address randomization ===

{{Merge|NetworkManager/Privacy#MAC Randomization|There is a dedicated sub-page for Privacy now.}}

{{Accuracy|The [[iwd]] backend reportedly refuses MAC address randomisation due to open issues, and entry in [[iwd#Troubleshooting]] or link to [[MAC address spoofing#iwd]] (where [[Special:diff/873389/873277]] explains it) might be suitable to account for it; see:|section=iwd backend doesn't support mac spoofing}}

{{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.}}

{{Note| See [[#Using iwd as the Wi-Fi backend]] for iwd specific MAC randomization.}}

MAC randomization can be used for increased privacy by not disclosing your real MAC address to the network.

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 configuration file may be overwritten by NetworkManager.

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}}:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device]
wifi.scan-rand-mac-address=no
}}

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.

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}}:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device-mac-randomization]
# "yes" is already the default for scanning
wifi.scan-rand-mac-address=yes

[connection-mac-randomization]
# Randomize MAC for every ethernet connection
ethernet.cloned-mac-address=random
# Generate a random MAC for each Wi-Fi and associate the two permanently.
wifi.cloned-mac-address=stable
}}

To configure MAC randomization for a specific connection (for example, if the network does not like random MAC addresses), [[#Edit a connection|edit the connection]] to set {{ic|802-11-wireless.cloned-mac-address}} to one of the modes (e.g. {{ic|stable}} or {{ic|random}}).

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.

=== Turn off hostname sending ===

NetworkManager by default sends the hostname to the DHCP server.

To disable sending your hostname to the DHCP server globally, set the {{ic|ipv4.dhcp-send-hostname{{=}}0}} and {{ic|ipv6.dhcp-send-hostname{{=}}0}} options with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}. E.g.:

{{hc|/etc/NetworkManager/conf.d/dhcp-send-hostname.conf|2=
[connection]
ipv4.dhcp-send-hostname=0
ipv6.dhcp-send-hostname=0
}}

To disable sending your hostname to the DHCP server for a specific connection (or alternatively, enable it for a connection if it is disabled globally), add the following to your network connection file:

{{hc|/etc/NetworkManager/system-connections/''your_connection_file''.nmconnection|2=
...
[ipv4]
dhcp-send-hostname=false
...
[ipv6]
dhcp-send-hostname=false
...
}}

{{Note|These options are only honored by the default [[#DHCP client|internal DHCP client]]. To omit sending the hostname when using NetworkManager with dhcpcd, edit {{ic|/etc/dhcpcd.conf}} and insert {{ic|anonymous}} as the last line.}}

=== Enable IPv6 Privacy Extensions ===

See [[IPv6#NetworkManager]].

=== Configure a unique DUID per connection ===

The DHCPv6 Unique Identifier (DUID) is a value used by the DHCPv6 client to identify itself to DHCPv6 servers. NetworkManager supports 3 types of DUID:

* DUID-UUID ([[RFC:6355|RFC 6355]]): generated from an Universally Unique IDentifier (UUID).
* DUID-LL ([[RFC:3315|RFC 3315]]): generated from the Link-Layer address (a.k.a. MAC address).
* DUID-LLT ([[RFC:3315|RFC 3315]]): generated from the Link-Layer address plus a timestamp.

If the internal NetworkManager's DHCP client is in use (the default) it will identify itself with a global and permanent DUID-UUID generated from the machine-id ({{ic|/etc/machine-id}}). This means that all connections share the same UUID, which may be a privacy breach.

Fortunately, NetworkManager is able to provide unique DUIDs per connection, derived from the connection's stable-id and a per-host unique key. You can enable that by adding the following configuration under {{ic|/etc/NetworkManager/conf.d}}:

{{hc|/etc/NetworkManager/conf.d/duid.conf|2=
[connection]
ipv6.dhcp-duid=stable-uuid
}}

The {{ic|stable-ll}} and {{ic|stable-llt}} values are also supported. For further information read the description for {{ic|dhcp-duid}} in {{man|5|nm-settings|ipv6 setting}}.

=== Working with wired connections ===

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.

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 {{Pkg|nm-connection-editor}} for this task.

=== Using iwd as the Wi-Fi backend ===

{{Note|1=<nowiki/>
* Do not enable {{ic|iwd.service}} or manually configure [[iwd]]. NetworkManager will start and manage it itself.
* Consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before switching to ''iwd''.}}

To enable the [https://archive.kernel.org/oldwiki/iwd.wiki.kernel.org/networkmanager.html experimental iwd backend], first [[install]] {{Pkg|iwd}} and then create the following configuration file:

{{hc|/etc/NetworkManager/conf.d/wifi_backend.conf|2=
[device]
wifi.backend=iwd
}}

To use MAC randomization with iwd see [[MAC address spoofing#iwd]].

Alternatively, you can install {{AUR|networkmanager-iwd}}, a modified package configured to build ''NetworkManager'' working exclusively with ''iwd'', with the main difference being that ''iwd'' is required and ''wpa_supplicant'' can be uninstalled after building.

{{Note|1=You may need to [https://archive.kernel.org/oldwiki/iwd.wiki.kernel.org/networkmanager.html#converting_network_profiles convert existing NetworkManager network profiles] after switching to ''iwd''.}}

=== Running in a network namespace ===

If you would like to run NetworkManager inside a network namespace (e.g., to manage a specific device which should be used by selected applications), bring the device down before moving it to the namespace:

$ ip link set dev ''MY_DEVICE'' down
$ ip link set dev ''MY_DEVICE'' netns ''MY_NAMESPACE''
$ ip netns exec ''MY_NAMESPACE'' NetworkManager
...
$ ip netns exec ''MY_NAMESPACE'' killall NetworkManager

otherwise NetworkManager will later fail to establish the connection with a {{ic|device is strictly unmanaged}} error.

=== Automatically connect to VPN ===

NetworkManager can be set to automatically connect to a VPN when connecting to the internet, on a per network basis. The VPN connection itself can be added in GNOME's NetworkManager front-end, but to make it automatically use the VPN {{ic|nmcli}} must be used. Other front-ends might not have this limitation.

First, make sure to make the VPN connection available to all users. In the GNOME this is a matter of checking a box under the {{ic|details}} tab. Under the {{ic|Identity}} tab, in the password field, click the icon on the right side in the field, and set it to {{ic|Store the password for all users}}.

Then find the UUID of the VPN connection, and add that to {{ic|connection.secondaries}} of the Internet connection:

# UUID=$(nmcli --get-values connection.uuid connection show ''name-of-VPN-connection'')
# nmcli connection modify ''name-of-Internet-connection'' connection.secondaries "$UUID"

Now when NetworkManager is restarted and you connect to the Internet connection you have configured, you should automatically get connected to the VPN.

== Troubleshooting ==

=== No prompt for password of secured Wi-Fi networks ===

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''.

=== Network management disabled ===

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:

# rm /var/lib/NetworkManager/NetworkManager.state

=== Problems with internal DHCP client ===

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.

=== DHCP problems with dhclient ===

If you have problems with getting an IP address via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:

interface "eth0" {
send dhcp-client-identifier 01:''aa:bb:cc:dd:ee:ff'';
}

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.

=== 3G modem not detected ===

See [[Mobile broadband modem#NetworkManager]].

=== Switching off WLAN on laptops ===

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:

$ watch -n1 rfkill list all

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):

# rfkill event unblock X

=== Static IP address settings revert to DHCP ===

{{Out of date|This section is [[Special:Diff/119236|added in 2010]] and describes an ancient version of ''nm-applet''. Is this still relevant in 2024?}}

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.

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.

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.

=== Cannot edit connections as normal user ===

See [[#Set up PolicyKit permissions]].

=== Forget hidden wireless network ===

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:

# rm /etc/NetworkManager/system-connections/''SSID''.nmconnection

This also works for any other connection.

=== VPN not working in GNOME ===

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}}:

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.

This is caused by the GNOME NetworkManager Applet expecting dialog scripts to be at {{ic|/usr/lib/gnome-shell}}, when NetworkManager's packages put them in {{ic|/usr/lib/networkmanager}}.
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):

* For OpenConnect: {{ic|ln -s /usr/lib/nm-openconnect-auth-dialog /usr/lib/gnome-shell/}}
* For VPNC (i.e. Cisco VPN): {{ic|ln -s /usr/lib/nm-vpnc-auth-dialog /usr/lib/gnome-shell/}}

This may need to be done for any other NetworkManager VPN plugins as well, but these are the two most common.

=== Unable to connect to visible European wireless networks ===

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:

# [[Install]] {{Pkg|wireless-regdb}}.
# Uncomment the correct country code in {{ic|/etc/conf.d/wireless-regdom}}.
# Reboot the system, because the setting is only read on boot.

=== Automatic connect to VPN on boot is not working ===

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.

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]].

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.

=== systemd bottleneck ===

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]].

=== Regular network disconnects, latency and lost packets (Wi-Fi) ===

NetworkManager does a scan every 2 minutes.

Some Wi-Fi 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.

Running {{ic|journalctl -f}} as root will indicate that this is taking place, messages like the following will be contained in the logs at regular intervals.

NetworkManager[410]: <info> (wlp3s0): roamed from BSSID 00:14:48:11:20:CF (my-wifi-name) to (none) ((none))

If roaming is not important, the periodic scanning behavior can be disabled by locking the BSSID of the access point in the Wi-Fi connection profile.

=== Unable to turn on Wi-Fi with Lenovo laptop (IdeaPad, Legion, etc.) ===

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.

{{Accuracy|Try to use {{ic|rfkill.default_state}} and {{ic|rfkill.master_switch_mode}} (see [https://docs.kernel.org/admin-guide/kernel-parameters.html kernel-parameters.html]) to fix the rfkill problem.}}

[[modprobe|Unloading]] the {{ic|ideapad_laptop}} module should fix this. ('''warning''': this may disable the laptop keyboard and touchpad also!).

=== nm-applet disappears in i3wm ===

If you use the {{ic|xfce4-notifyd.service}} for notifications you must [[edit]] the unit and add the following:

{{hc|/etc/systemd/user/xfce4-notifyd.service.d/display_env.conf|2=
[Service]
Environment="DISPLAY=:0.0"
}}

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.

=== Unit dbus-org.freedesktop.resolve1.service not found ===

If {{ic|systemd-resolved.service}} is not started, NetworkManager will try to start it using D-Bus and fail:

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 ")
dbus-daemon[991]: [system] Activation via systemd failed for unit 'dbus-org.freedesktop.resolve1.service': Unit dbus-org.freedesktop.resolve1.service not found.
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 ")

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]

This can be disabled with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/no-systemd-resolved.conf|2=
[main]
systemd-resolved=false
}}

See {{Bug|62138}}.

=== Secrets were required, but not provided ===

If you received the following error when attempting to connect to a network:

{{hc|$ nmcli device wifi connect ''SSID'' password ''password''|
Error: Connection activation failed: (7) Secrets were required, but not provided
}}

This error can have numerous causes and you should read the [[journal]] (filter it with {{ic|-u NetworkManager}}). For example, if NetworkManager took too long to establish connection, it will believe that the password is incorrect:

{{bc|
NetworkManager[1372]: <warn> [1643991888.3808] device (wlan0): Activation: (wifi) association took too long
NetworkManager[1372]: <info> [1643991888.3809] device (wlan0): state change: config -> need-auth (reason 'none', sys-iface-state: 'managed')
NetworkManager[1372]: <warn> [1643991888.3838] device (wlan0): Activation: (wifi) asking for new secrets
}}

You can try deleting the connection profile and creating a new one:

$ nmcli connection delete ''SSID''
$ nmcli device wifi connect ''SSID'' password ''password''

You can also try disabling MAC address randomization:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device]
wifi.scan-rand-mac-address=no
}}

=== WPA Enterprise connection with iwd ===

If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the [[#Using iwd as the Wi-Fi backend|iwd backend]] then you will get the following error from NetworkManager:

Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)

This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd configuration file {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[iwd#WPA Enterprise]].

=== Failed to request VPN secrets ===

If you get this error:
Failed to request VPN secrets #1: No agents were available for this request.

It is either because the password is empty or you have to [[#Set up PolicyKit permissions|set up PolicyKit permissions]].

=== OpenVPN connections fail with "secrets: failed to request VPN secrets" warn ===

{{Remove|This does not warrant a troubleshooting section. Optional dependencies are pointed out by pacman, if this is not clear enough it should be covered in [[#VPN support]].|section=Remove unnecessary section 8.22}}

The package {{Pkg|networkmanager-openvpn}} requires {{Pkg|libnma-gtk4}} and optionally {{Pkg|libnma}} (Gtk3) when integrated within the GNOME-Shell. If {{Pkg|libnma}} is required but not installed a message will be printed to the system log:

{{bc|
NetworkManager[642]: <warn> [...] vpn[..."name_of_vpn_profile VPN"]: secrets: failed to request VPN secrets #3: No agents were available for this request.
}}

=== OpenVPN connections fail with OpenSSL "ca md too weak" error ===

Since {{Pkg|openssl}} was updated to version 3, certificates generated with legacy cryptographic algorithms are rejected by default. Attempting to use {{Pkg|networkmanager-openvpn}} with such a setup can result in the following error in the logs:

{{bc|
nm-openvpn[14359]: OpenSSL: error:0A00018E:SSL routines::ca md too weak
nm-openvpn[14359]: Cannot load certificate file /home/archie/.local/share/networkmanagement/certificates/my_issued_cert.crt
nm-openvpn[14359]: Exiting due to fatal error
}}

The correct approach is to have the OpenVPN server administrator generate and re-issue more secure certificates. However, as an immediate work-around, OpenVPN requires {{ic|1=tls-cipher "DEFAULT:@SECLEVEL=0"}}. This may not be possible through the plugin GUI, but it is possible with ''nmcli''. Separately, you will also need to enable the ''legacy'' provider in OpenSSL.

Firstly, obtain the name of the VPN connection with the issue, from the output of the following:

$ nmcli connection show

Assuming the connection name is ''vpn.example.com'', use ''nmcli'' like so:

$ nmcli connection modify vpn.example.com +vpn.data tls-cipher=DEFAULT:@SECLEVEL=0

The change should instantly be reflected in {{ic|/etc/NetworkManager/system-connections/vpn.example.com.nmconnection}}.

As for OpenSSL, edit {{ic|/etc/ssl/openssl.cnf}} as described on the [https://wiki.openssl.org/index.php/OpenSSL_3.0#Providers OpenSSL wiki].

Specifically, at the end of the {{ic|[provider_sect]}} section add {{ic|1=legacy = legacy_sect}}. Under {{ic|[default_sect]}} uncomment {{ic|1=activate = 1}}. Lastly, add a new section {{ic|[legacy_sect]}} that also contains the line {{ic|1=activate = 1}}. Excluding most other preexisting configuration sections, the end result will look something like:

{{hc|/etc/ssl/openssl.cnf|2=
openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1
}}

Finally, [[restart]] the {{ic|NetworkManager.service}} to have the new OpenSSL configuration take effect.

=== WPA Enterprise connections fail to authenticate with OpenSSL "unsupported protocol" error ===

Since {{Pkg|openssl}} was updated to version 3, "SSL 3, TLS 1.0, TLS 1.1, and DTLS 1.0 only work at security level 0" [https://www.openssl.org/news/openssl-3.0-notes.html by default]. Attempting to authenticate to a Wi-Fi network only supporting older standards results in the following error in the logs:

{{bc|
wpa_supplicant[3320]: SSL: SSL3 alert: write (local SSL3 detected an error):fatal:protocol version
wpa_supplicant[3320]: OpenSSL: openssl_handshake - SSL_connect error:0A000102:SSL routines::unsupported protocol
wpa_supplicant[3320]: wlp3s0: CTRL-EVENT-EAP-FAILURE EAP authentication failed
}}

The correct approach is to convince the institution's administrator to upgrade the encrypted networking tunnel protocol to TLS 1.3 and optionally drop support for deprecated security standards, including TLS 1.0/1.1, DTLS 1.0 and SSL 1-3. However, as an immediate workaround, there are multiple ways to allow TLS 1.0 and/or 1.1 by default. One way would be to manually patch or revert the breaking changes in OpenSSL ([https://github.com/openssl/openssl/commit/7bf2e4d7f0c7ae19b7a8c416910886a7171e9820]). As this also lowers security for all other programs using OpenSSL level 1, it is not recommended. Instead, one can directly set the level used by wpa_supplicant, like described in [https://bbs.archlinux.org/viewtopic.php?id=286417#p2104492 BBS#286417]. To only change the affected connection, it is possible to set {{ic|1=phase1-auth-flags=32}} or {{ic|1=phase1-auth-flags=64}} in the {{ic|1=[802-1x]}} section of the connection's configuration file. This may not be possible through GUIs, but it is possible with ''nmcli''.

Firstly, obtain the name of the Wi-Fi connection with the issue, from the output of the following:

$ nmcli connection show

Assuming the connection uses TLS 1.0 and its name is ''Example Wi-Fi'', use ''nmcli'' like so:

$ nmcli connection modify 'Example Wi-Fi' 802-1x.phase1-auth-flags 32

And for a TLS 1.1 connection, type "64" instead:

$ nmcli connection modify 'Example Wi-Fi' 802-1x.phase1-auth-flags 64

{{Note|1=The number you type in refers to the number you get from raising 2 to the power of '''n'''. Here, '''n''' is the index of the network authentication bit octet, read from right to left. Flipping the fifth bit enables TLS 1.0 '''[log(2) 32]''' and flipping the sixth bit enables TLS 1.1 '''[log(2) 64]'''.}}

The change should instantly be reflected in {{ic|/etc/NetworkManager/system-connections/Example Wi-Fi.nmconnection}}.

Finally, [[restart]] the {{ic|NetworkManager.service}} to have the new OpenSSL configuration take effect.

== See also ==

* [https://blogs.gnome.org/dcbw/2015/02/16/networkmanager-for-administrators-part-1/ NetworkManager for Administrators Part 1]

NetworkManager

2026-05-08T09:57:06Z

Indigo: /* Configuring MAC address randomization */ add relevant crosslink to template

[[Category:Network managers]]
[[Category:DHCP]]
[[ar:Networkmanager]]
[[de:Networkmanager]]
[[fr:NetworkManager]]
[[hu:NetworkManager]]
[[ja:NetworkManager]]
[[pt:NetworkManager]]
[[ru:NetworkManager]]
[[zh-hans:NetworkManager]]
{{Related articles start}}
{{Related|NetworkManager/Privacy}}
{{Related|Network configuration}}
{{Related|Wireless network configuration}}
{{Related articles end}}

[[Wikipedia:NetworkManager|NetworkManager]] is a program for providing detection and configuration for systems to automatically connect to networks.

[https://networkmanager.dev/ NetworkManager] 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.

{{Warning|By default, secrets—e.g. Wi-Fi passwords—are accessible to the root user in the filesystem and to users with access to settings via the GUI (e.g. via [[#nm-applet]]). For more information, see [[#Encrypted Wi-Fi passwords]].}}

== Installation ==

NetworkManager can be [[install]]ed with the package {{Pkg|networkmanager}}, which contains a daemon, a command line interface (''nmcli'') and a curses‐based interface (''nmtui'').

=== Enable NetworkManager ===

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.

{{Note|
* Each network interface should be managed by only one [[Network configuration#Network managers|DHCP client or network manager]], so it is advised to run only one DHCP client or network manager on the system. Find a list of the currently running services with {{ic|1=systemctl --type=service}} and then [[stop]] or reconfigure those that conflict.
* If [[systemd-resolved]] is not [[started]], an error message will start flooding your logs. See [[#Unit dbus-org.freedesktop.resolve1.service not found]] for more info.
}}

=== Additional interfaces ===

* {{Pkg|nm-connection-editor}} for a graphical user interface,
* {{Pkg|network-manager-applet}} for a system tray applet (see the [[#nm-applet]] section).

=== Mobile broadband support ===

NetworkManager uses [[ModemManager]] for mobile broadband connection support.

[[Install]] {{Pkg|modemmanager}} and {{Pkg|usb_modeswitch}}. Afterwards [[enable]] and [[start]] {{ic|ModemManager.service}}.

It may be necessary to [[restart]] {{ic|NetworkManager.service}} for it to detect ModemManager. After you restart it, re-plug the modem again and it should be recognized.

Add connections from a front-end (e.g. {{Pkg|nm-connection-editor}}) and select mobile broadband as the connection type. After selecting your ISP and billing plan, [[Wikipedia:Access Point Name|APN]] and other settings should be filled in automatically using information from {{Pkg|mobile-broadband-provider-info}}.

=== PPPoE / DSL support ===

[[Install]] {{Pkg|ppp}} package for PPPoE / DSL connection support. To actually add PPPoE connection, use {{ic|1=nm-connection-editor}} and add new DSL/PPPoE connection.

=== VPN support ===

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.

Support for other VPN types is based on a plug-in system. They are provided in the following packages:

* {{Pkg|networkmanager-openconnect}} for [[OpenConnect]]
* {{Pkg|networkmanager-openvpn}} for [[OpenVPN]]
* {{Pkg|networkmanager-pptp}} for [[PPTP Client]]
* {{Pkg|networkmanager-strongswan}} for [[strongSwan]]
* {{Pkg|networkmanager-vpnc}}
* {{AUR|networkmanager-fortisslvpn}}
* {{AUR|networkmanager-iodine-git}}
* {{AUR|networkmanager-libreswan}}
* {{Pkg|networkmanager-l2tp}}
* {{AUR|networkmanager-ssh}}
* {{Pkg|network-manager-sstp}}

{{Warning|1=There are a lot of [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues?search=VPN&state=opened bugs] related to VPN support. Check the daemon processes options set via the GUI correctly and double-check with each package release.}}

{{Note|
* To have fully functioning DNS resolution when using VPN, you should set up [[#DNS caching and conditional forwarding|conditional forwarding]].
* These plug-ins may not have a documented command line interface, or may not work at all without an applet running. This is not an issue if you are using a regular desktop environment; if you are not, you should run [[#nm-applet]] while configuring or activating the connection so that you get the necessary dialogues. [https://bbs.archlinux.org/viewtopic.php?id{{=}}246698]
}}

== Usage ==

NetworkManager comes with {{man|1|nmcli}} and {{man|1|nmtui}}.

=== nmcli examples ===

List nearby Wi-Fi networks:

$ nmcli device wifi list

Connect to a Wi-Fi network:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password''

Connect to a hidden Wi-Fi network:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' hidden yes

Connect to a Wi-Fi on the {{ic|wlan1}} interface:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' ifname wlan1 ''profile_name''

Disconnect an interface:

$ nmcli device disconnect ifname eth0

Get a list of connections with their names, UUIDs, types and backing devices:

$ nmcli connection show

Activate a connection (i.e. connect to a network with an existing profile):

$ nmcli connection up ''name_or_uuid''

Delete a connection:

$ nmcli connection delete ''name_or_uuid''

See a list of network devices and their state:

$ nmcli device

Turn off Wi-Fi:

$ nmcli radio wifi off

=== Edit a connection ===

For a comprehensive list of settings, see {{man|5|nm-settings}}.

Firstly, you need to get a list of connections:

{{hc|$ nmcli connection|<nowiki>
NAME UUID TYPE DEVICE
Wired connection 2 e7054040-a421-3bef-965d-bb7d60b7cecf ethernet enp5s0
Wired connection 1 997f2782-f0fc-301d-bfba-15421a2735d8 ethernet enp0s25
MY-HOME-WIFI-5G 92a0f7b3-2eba-49ab-a899-24d83978f308 wifi --
</nowiki>}}

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.

You have three methods to configure a connection {{ic|Wired connection 2}} after it has been created:

; nmcli interactive editor
: {{ic|nmcli connection edit 'Wired connection 2'}}. Usage is well documented from the editor.

; nmcli command line interface
: {{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.
To remove a setting, pass an empty field ("") to it like this:
: {{ic|nmcli connection modify 'Wired connection 2' ''setting''.''property'' ""}}

; Connection file
: In {{ic|/etc/NetworkManager/system-connections/}}, modify the corresponding {{ic|Wired connection 2.nmconnection}} file . Do not forget to reload the configuration file with {{ic|nmcli connection reload}}.

=== nmtui ===

NetworkManager ships a text user interface (TUI) for managing connections, the system hostname and radio switches. It can be launched by running {{ic|nmtui}}.

== Front-ends ==

To provide integration with a [[desktop environment]], most users will want to install an applet. This not only provides easy access to network selection and configuration, but also provides the agent necessary for securely storing secrets. Various desktop environments have their own applet; otherwise, you can use [[#nm-applet]].

=== GNOME ===

[[GNOME]] has a built-in tool, accessible from the Network settings.

=== KDE Plasma ===

[[Install]] the {{Pkg|plasma-nm}} package. After that, add it to the KDE taskbar via the ''Panel options > Add widgets > Networks'' menu.

=== nm-applet ===

{{Pkg|network-manager-applet}} is a GTK 3 front-end which works under Xorg environments with a systray.

To store connection secrets install and configure an application which implements the [https://specifications.freedesktop.org/secret-service-spec/latest/ Secret Service D-Bus API] such as [[GNOME/Keyring]], [[KDE Wallet]], or [[KeePassXC]].

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]].

In order to run {{ic|nm-applet}} without a systray, you can use {{AUR|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:

{{hc|nmgui|<nowiki>
#!/bin/sh
nm-applet 2>&1 > /dev/null &
stalonetray 2>&1 > /dev/null
killall nm-applet
</nowiki>}}

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.

The applet can show notifications for events such as connecting to or disconnecting from a Wi-Fi 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 applet might hang. See [https://bugzilla.gnome.org/show_bug.cgi?id=788313].

In order to run {{ic|nm-applet}} with such notifications disabled, start the applet with the following command:

$ nm-applet --no-agent

{{Tip|{{ic|nm-applet}} might be started automatically with a [[XDG Autostart|autostart desktop file]], to add the {{ic|--no-agent}} option modify the Exec line there, i.e.

{{bc|1=Exec=nm-applet --no-agent}}

}}

{{Warning|On [[i3]], if nm-applet is started with the {{ic|--no-agent}} option, it is not possible to connect to a new encrypted Wi-Fi 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}}.}}

==== Appindicator ====

As of version 1.18.0 Appindicator support is [https://gitlab.archlinux.org/archlinux/packaging/packages/network-manager-applet/-/commit/527448fb2a87d85055f504f463dfe961dccd75c3 available] in the official {{Pkg|network-manager-applet}} package. To use nm-applet in an Appindicator environment start the applet with the following command:

$ nm-applet --indicator

=== networkmanager-dmenu ===

Alternatively there is {{Pkg|networkmanager-dmenu}} 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 Wi-Fi or wired connections, connect to new Wi-Fi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch ''nm-connection-editor'' GUI, connect to Bluetooth networks.

=== switchboard ===

Pantheon's {{Pkg|switchboard}} offers a desktop environment-agnostic way to configure NetworkManager when combined with {{Pkg|switchboard-plug-network}} and {{Pkg|nm-connection-editor}}. It can be ran with the following command:

$ io.elementary.settings

== Configuration ==

NetworkManager may 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.

NetworkManager has a global configuration file at {{ic|/etc/NetworkManager/NetworkManager.conf}}. Additional configuration files can be placed in {{ic|/etc/NetworkManager/conf.d/}}. Usually no configuration needs to be done to the global defaults.

After editing a configuration file, the changes can be applied by running:

# nmcli general reload

=== NetworkManager-wait-online ===

Enabling {{ic|NetworkManager.service}} also enables {{ic|NetworkManager-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 finish 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]].

By default, {{ic|NetworkManager-wait-online.service}} waits for NetworkManager startup to complete, rather than waiting for network connectivity specifically (see {{man|1|nm-online}}). If {{ic|NetworkManager-wait-online.service}} finishes before the network is really up, resulting in failed services on boot, [[extend the unit]] to remove the {{ic|-s}} from the {{ic|ExecStart}} line:

[Service]
ExecStart=
ExecStart=/usr/bin/nm-online -q

Be aware that this can cause [https://lists.fedoraproject.org/archives/list/users@lists.fedoraproject.org/thread/EGC324JD3HJCGVN7J55WYPRLFDA3TP7N/ other issues].

In some cases, the service will still fail to start successfully on boot due to the timeout setting being too short. [[Edit]] the service to change {{ic|NM_ONLINE_TIMEOUT}} from {{ic|60}} to a higher value.

=== Set up PolicyKit permissions ===

By default, all users in active local sessions are allowed to change most network settings without a password. See [[General troubleshooting#Session permissions]] to check your session type. In most cases, everything should work out of the box.

Some actions (such as changing the system hostname) require an administrator password. In this case, you need to [[Users and groups#Group management|add]] yourself to the {{ic|wheel}} group and run a [[Polkit#Authentication agents|Polkit authentication agent]] which will prompt for your password.

For remote sessions (e.g. [[TigerVNC#Running vncserver for virtual (headless) sessions|headless VNC]]), you have several options for obtaining the necessary privileges to use NetworkManager:

# [[Users and groups#Group management|Add]] yourself to the {{ic|wheel}} group. You will have to enter your password for every action. Note that your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.
# [[Users and groups#Group management|Add]] yourself to the {{ic|network}} group and create {{ic|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules}} with the following content: {{bc|<nowiki>
polkit.addRule(function(action, subject) {
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {
return polkit.Result.YES;
}
});
</nowiki>}} All users in the {{ic|network}} group will be able to add and remove networks without a password (which means you do not have to run a Polkit authentication agent, so this option will also work in SSH sessions).

=== Proxy settings ===

NetworkManager does support some proxy settings. While they can not be directly modified using ''nmtui'', ''nm-applet'' and ''nmcli'' support those.
See the proxy settings in {{man|5|nm-settings-nmcli}}.

Additionally, custom proxy commands can always be run using dispatcher scripts, see [[#Dispatcher examples]].

See also [[Proxy settings]].

=== Checking connectivity ===

NetworkManager can try to reach a webserver after connecting to a network in order to determine if it is e.g behind a captive portal. The default host (configured in {{ic|/usr/lib/NetworkManager/conf.d/20-connectivity.conf}}) is [https://ping.archlinux.org ping.archlinux.org] (a CNAME alias of redirect.archlinux.org). To use a different webserver or to 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]]):

{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki>
[connectivity]
uri=http://nmcheck.gnome.org/check_network_status.txt
</nowiki>}}

To disable NetworkManager's connectivity check, use the following configuration. This can be useful when connected to a VPN that blocks connectivity checks.

{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki>
[connectivity]
enabled=false
</nowiki>}}

{{Note|Although automatic connectivity checks are a potential privacy leak, Arch Linux's default connectivity URL is committed to not logging any access. See [https://gitlab.archlinux.org/archlinux/infrastructure/-/commit/fabccd0f61e5dea3925e8a0c6a46d56d5750c121#a4f34381bbb18ea77bfb3dd11a8aeca707078fca_0_26] [https://gitlab.archlinux.org/archlinux/infrastructure/-/blob/master/roles/ping/templates/nginx.d.conf.j2].}}

=== Captive portals ===

{{Style|Complex scripts should not be maintained on the wiki.}}

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 has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:

{{hc|/etc/NetworkManager/dispatcher.d/90-open_captive_portal|<nowiki>
#!/bin/sh -e
# Script to dispatch NetworkManager events
#
# Runs shows a login webpage on walled garden networks.
# See NetworkManager(8) for further documentation of the dispatcher events.

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

if [ -x "/usr/bin/logger" ]; then
logger="/usr/bin/logger -s -t captive-portal"
else
logger=":"
fi

wait_for_process() {
PNAME=$1
while [ -z "$(/usr/bin/pgrep $PNAME)" ]; do
sleep 3;
done
}

#launch the browser, but on boot we need to wait that nm-applet starts
start_browser() {
local user="$1"
local display="$2"

export DISPLAY="$display"
wait_for_process nm-applet

export XAUTHORITY="/home/$user/.Xauthority"

$logger "Running browser as '$user' with display '$display' to login in captive portal"
sudo -u "$user" --preserve-env=DISPLAY,XAUTHORITY -H xdg-open http://capnet.elementary.io 2>&1 > /dev/null
}

# Run the right scripts
case "$2" in
connectivity-change)
$logger -p user.debug "dispatcher script triggered on connectivity change: $CONNECTIVITY_STATE"
if [ "$CONNECTIVITY_STATE" = "PORTAL" ]; then
# Match last column of who's output with ' :[at least one digit] '
who | awk '$NF ~ /$:[0-9]+$/ { print $1 " " substr($NF, 2, length($NF)-2) };' | \
while read user display; do
start_browser $user $display || $logger -p user.err "Failed for user: '$user' display: '$display'"
done
fi
;;
*)
# In a down phase
exit 0
;;
esac
</nowiki>}}

Make the script [[executable]]. But that script assumes you use X and simply opens http page. It might not work for everyone.

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.

Simple solution is [https://github.com/Seme4eg/captive-portal-sh captive-portal-sh] - shell script that obtains captive portal URL and opens it in your default browser (for Wayland users only).

Another solution is {{AUR|captive-browser-git}} based on Google Chrome.

==== iwd support for captive portal support on legacy hardware ====

Some older Wi-Fi chips (e.g. Broadcom BCM4360) require the proprietary {{ic|wl}} driver, which lacks support for the OWE/Elliptic-Curve handshake that many captive-portal hotspots use before presenting a login page. By switching NetworkManager’s Wi-Fi backend to {{ic|iwd}} (see [[#Using iwd as the Wi-Fi backend]]), which implements the full OWE key exchange in userspace over the existing driver, you can complete the encrypted association, obtain a DHCP lease, and trigger the portal “PORTAL” state. Once that is done, any dispatcher script or browser-launcher will reliably pop up the login page on hardware that otherwise could never fully connect.

=== DHCP client ===

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.

To use a different DHCP client [[install]] one of the alternatives:

* {{Pkg|dhcpcd}} - [[dhcpcd]]
* {{Pkg|dhclient}} - [[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.:

{{hc|1=/etc/NetworkManager/conf.d/dhcp-client.conf|2=
[main]
dhcp=dhcpcd
}}

{{Note|
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.
}}

=== DNS management ===

NetworkManager's DNS management is described in the GNOME project's wiki page—[https://wiki.gnome.org/Projects/NetworkManager/DNS Projects/NetworkManager/DNS].

==== DNS caching and conditional forwarding ====

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.

{{Note|If {{ic|/etc/resolv.conf}} is a symlink to {{ic|/run/systemd/resolve/stub-resolv.conf}}, {{ic|/run/systemd/resolve/resolv.conf}},{{ic|/lib/systemd/resolv.conf}} or {{ic|/usr/lib/systemd/resolv.conf}}, NetworkManager will choose systemd-resolved automatically. To use dnsmasq, you must first remove that symlink, then restart NetworkManager.}}

===== dnsmasq =====

Make sure {{Pkg|dnsmasq}} has been installed. Then set {{ic|1=main.dns=dnsmasq}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=dnsmasq
}}

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.

{{Note|
* 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).
* 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.
}}

====== Custom dnsmasq configuration ======

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):

{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=
cache-size=1000
}}

You can check the configuration file syntax with:

$ dnsmasq --test --conf-file=/dev/null --conf-dir=/etc/NetworkManager/dnsmasq.d

See {{man|8|dnsmasq}} for all available options.

====== IPv6 ======

{{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}}.}}

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:

{{hc|/etc/NetworkManager/dnsmasq.d/ipv6-listen.conf|2=
listen-address=::1
}}

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.

====== DNSSEC ======

The dnsmasq instance started by NetworkManager by default will not validate [[DNSSEC]]. To enable DNSSEC validation, thus breaking DNS resolution with name servers that do not support it, create the following configuration file:

{{hc|/etc/NetworkManager/dnsmasq.d/dnssec.conf|2=
conf-file=/usr/share/dnsmasq/trust-anchors.conf
dnssec
}}

===== systemd-resolved =====

{{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]]?}}

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.

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}}.

You can enable it explicitly by setting {{ic|1=main.dns=systemd-resolved}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=systemd-resolved
}}

===== DNS resolver with an openresolv subscriber =====

If [[openresolv]] has a subscriber for your local [[DNS resolver]], set up the subscriber and [[#Use openresolv|configure NetworkManager to use openresolv]].

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].

This can be partially mitigated if you set {{ic|1=private_interfaces="*"}} in {{ic|/etc/resolvconf.conf}}[https://roy.marples.name/projects/openresolv/configuration/]. 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.

==== Custom DNS servers ====

===== Setting custom global DNS servers =====

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:

{{hc|/etc/NetworkManager/conf.d/dns-servers.conf|2=
[global-dns-domain-*]
servers=::1,127.0.0.1
}}

{{Note|
* 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.
* The specified servers do not get sent to [[systemd-resolved]], the connection's DNS servers are used instead. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/1366 NetworkManager issue 1366] and [https://github.com/systemd/systemd/issues/33754 systemd issue 33754].
}}

===== Setting custom DNS servers in a connection =====

====== Setting custom DNS servers in a connection (GUI) ======

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'', ...}}.

====== Setting custom DNS servers in a connection (nmcli / connection file) ======

To set up DNS Servers per connection, you change the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings (and their associated {{ic|dns-search}} and {{ic|dns-options}}) in the [[#Edit a connection|connection settings]].

If {{ic|method}} is set to {{ic|auto}} (when you use DHCP/RA), you need to set {{ic|ignore-auto-dns}} to {{ic|yes}}.

To use DNS over TLS ([[#systemd-resolved|requires systemd-resolved]]), specify the DNS servers using the syntax {{ic|1=dns=''ip.address''#''servername'';}} and additionally set the {{ic|connection.dns-over-tls}} setting to {{ic|2}}. For example, to use Quad9:

{{hc|/etc/NetworkManager/system-connections/Example Wi-Fi.nmconnection|2=
...
[connection]
...
dns-over-tls=2

[ipv4]
...
dns=9.9.9.9#dns.quad9.net;149.112.112.112#dns.quad9.net;
ignore-auto-dns=true

[ipv6]
...
dns=2620:fe::fe#dns.quad9.net;2620:fe::9#dns.quad9.net;
ignore-auto-dns=true
}}

{{Note|This example uses Quad9. Replace it with a DNS resolver you trust. See [[Domain name resolution#Third-party DNS services]].}}

==== /etc/resolv.conf ====

NetworkManager's {{ic|/etc/resolv.conf}} management mode is configured with the {{ic|main.rc-manager}} setting. {{Pkg|networkmanager}} sets it to {{ic|symlink}} as opposed to the upstream default {{ic|auto}}. The setting and its values are documented in the {{man|5|NetworkManager.conf}} man page.

{{Tip|Using openresolv allows NetworkManager to coexist 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]]. Note that conditional forwarding is [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 not yet fully supported] when using NetworkManager with openresolv.}}

''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.

{{Note|
* 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}}.
* The {{ic|resolv.conf}} file NetworkManager writes or would write to {{ic|/etc/resolv.conf}} can be found at {{ic|/run/NetworkManager/resolv.conf}}.
* A {{ic|resolv.conf}} file with the acquired name servers and search domains can be found at {{ic|/run/NetworkManager/no-stub-resolv.conf}}.
}}

===== Unmanaged /etc/resolv.conf =====

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/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=none
}}

{{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]].}}

{{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}}.}}

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.

===== Use openresolv =====

{{Note|NetworkManager does not support using systemd-resolved's ''resolvconf'' interface ({{man|1|resolvectl|COMPATIBILITY WITH RESOLVCONF(8)}}) which is provided by {{Pkg|systemd-resolvconf}}.
* Do not set {{ic|1=main.rc-manager=resolvconf}} when using [[systemd-resolved]], instead make sure to [[systemd-resolved#DNS|correctly create the /etc/resolv.conf symlink]] or [[#systemd-resolved|configure NetworkManager to use systemd-resolved explicitly]].
* Make sure the {{Pkg|systemd-resolvconf}} package is not installed when systemd-resolved is not used. Unless {{ic|systemd-resolved.service}} started, it will break all networking software (not just NetworkManager) that use resolvconf.
}}

To configure NetworkManager to use [[openresolv]], set {{ic|1=main.rc-manager=resolvconf}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/rc-manager.conf|2=
[main]
rc-manager=resolvconf
}}

=== Firewall ===

You can [[Firewalld#Using NetworkManager to manage zones|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.

This can also be done with [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher]].

== Network services with NetworkManager dispatcher ==

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]]).

To activate the feature you need to [[enable]] and [[start]] the {{ic|NetworkManager-dispatcher.service}}.

Once the service is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory.

Scripts must be owned by '''root''', otherwise the dispatcher will not execute them. For added security, set group [[ownership]] to root as well:

# chown root:root /etc/NetworkManager/dispatcher.d/''10-script.sh''

Make sure the file is [[executable]].

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).

Scripts will receive the following arguments:

* '''Interface name:''' e.g. {{ic|eth0}}
* '''Action:''' ''up'', ''down'', ''vpn-up'', ''vpn-down'', ... (see {{man|8|NetworkManager-dispatcher}} for the complete list)

{{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.}}

=== Avoiding the dispatcher timeout ===

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 use a [[drop-in file]] for the {{ic|NetworkManager-dispatcher.service}} to remain active after exit:

{{hc|/etc/systemd/system/NetworkManager-dispatcher.service.d/remain_after_exit.conf|2=
[Service]
RemainAfterExit=yes
}}

Now start and enable the modified {{ic|NetworkManager-dispatcher}} service.

{{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.}}

=== Dispatcher examples ===

==== Automatically set the timezone ====

Create a [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]] and make it [[executable]]:

{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|
#!/bin/sh
case "$2" in
up)
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"
;;
esac
}}

{{Tip|Using {{ic|connectivity-change}} instead of {{ic|up}} can prevent timezone changes when connecting to VPNs with clients such as [[OpenConnect]].}}

Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.

==== Mount remote directory with sshfs ====

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}}.

{{bc|<nowiki>
#!/bin/sh
USER='username'
REMOTE='user@host:/remote/path'
LOCAL='/local/path'

interface=$1 status=$2
if [ "$CONNECTION_UUID" = "</nowiki>''uuid''<nowiki>" ]; then
case $status in
up)
# sleep 10
SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')
export SSH_AUTH_SOCK
su "$USER" -c "sshfs $REMOTE $LOCAL"
;;
down)
fusermount -u "$LOCAL"
;;
esac
fi
</nowiki>}}

==== Mounting of SMB shares ====

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.

The following script will check if we connected to a specific network and mount shares accordingly:

{{hc|/etc/NetworkManager/dispatcher.d/30-mount-smb.sh|<nowiki>
#!/bin/sh

# Find the connection UUID with "nmcli connection show" in terminal.
# All NetworkManager connection types are supported: wireless, VPN, wired...
if [ "$2" = "up" ]; then
if [ "$CONNECTION_UUID" = "uuid" ]; then
mount /your/mount/point &
# add more shares as needed
fi
fi
</nowiki>}}

The following script will unmount all SMB shares before a software initiated disconnect from a specific network:

{{hc|/etc/NetworkManager/dispatcher.d/pre-down.d/30-umount-smb.sh|<nowiki>
#!/bin/sh

if [ "$CONNECTION_UUID" = "uuid" ]; then
umount -a -l -t cifs
fi
</nowiki>}}

{{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.}}

The following script will attempt to unmount all SMB shares following an unexpected disconnect from a specific network:

{{hc|/etc/NetworkManager/dispatcher.d/40-umount-smb.sh|<nowiki>
#!/bin/sh

if [ "$CONNECTION_UUID" = "uuid" ]; then
if [ "$2" = "down" ]; then
umount -a -l -t cifs
fi
fi
</nowiki>}}

{{Note|
* 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=701242 this bug report] for more info.
* The previous ''umount'' scripts are still prone to leaving applications actually accessing the mount to 'hang'.
}}

An alternative is to use the script as seen in [[NFS#Using a NetworkManager dispatcher]]:

{{hc|/etc/NetworkManager/dispatcher.d/30-smb.sh|<nowiki>
#!/bin/sh

# Find the connection UUID with "nmcli con show" in terminal.
# All NetworkManager connection types are supported: wireless, VPN, wired...
WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"

if [ "$CONNECTION_UUID" = "$WANTED_CON_UUID" ]; then

# Script parameter $1: network interface name, not used
# Script parameter $2: dispatched event

case "$2" in
"up")
mount -a -t cifs
;;
"down"|"pre-down"|"vpn-pre-down")
umount -l -a -t cifs >/dev/null
;;
esac
fi
</nowiki>}}

{{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.}}

Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down/}} to catch the {{ic|pre-down}} events:

# ln -s ../30-smb.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-smb.sh

==== Mounting of NFS shares ====

See [[NFS#Using a NetworkManager dispatcher]].

==== Use dispatcher to automatically toggle wireless depending on LAN cable being plugged in ====

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.

Create the following dispatcher script[https://superuser.com/questions/233448/disable-wlan-if-wired-cable-network-is-available], replacing {{ic|''Your_Ethernet_Interface''}} with your ethernet interface's device name.

{{Note|You can get a list of interfaces using [[#nmcli examples|nmcli]] ({{ic|nmcli d {{!}} grep ethernet}}). The Ethernet interfaces start with {{ic|en}} or {{ic|eth}}, e.g. {{ic|enp0s5}} or {{ic|eth0}}.}}

Remember to make the script [[executable]]. You can verify that it works by [[restart]]ing {{ic|NetworkManager.service}}, running {{ic|ip a}}, and checking that {{ic|wlp3s0}} (or whatever your Wi-Fi interface is called) is in {{ic|state DOWN}}. If you encounter unexpected behavior, check the [[journal]] of {{ic|NetworkManager-dispatcher.service}}.

{{hc|/etc/NetworkManager/dispatcher.d/99-wifi-auto-toggle.sh|2=
#!/bin/sh

LOG_PREFIX="WiFi Auto-Toggle"
ETHERNET_INTERFACE="''Your_Ethernet_Interface''"

if [ "$1" = "$ETHERNET_INTERFACE" ]; then
case "$2" in
up)
echo "$LOG_PREFIX ethernet up"
nmcli radio wifi off
;;
down)
echo "$LOG_PREFIX ethernet down"
nmcli radio wifi on
;;
esac
elif [ "$(nmcli -g GENERAL.STATE device show $ETHERNET_INTERFACE)" = "20 (unavailable)" ]; then
echo "$LOG_PREFIX failsafe"
nmcli radio wifi on
fi
}}

{{Note|There is a fail-safe for the case when the LAN interface was connected when the computer was last on, and then disconnected while the computer was off. That would mean the radio would still be off when the computer is turned back on, and with a disconnected LAN interface, you would have no network.}}

==== Use dispatcher to connect to a VPN after a network connection is established ====

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.

{{Accuracy|A scripting without {{ic|iwgetid}} does work too and may be more reliable?|section=Fixes for automatic VPN dispatcher script}}

{{Note|This script will require {{Pkg|wireless_tools}} in order to use {{ic|iwgetid}}.}}

{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki>
#!/bin/sh
VPN_NAME="name of VPN connection defined in NetworkManager"
ESSID="Wi-Fi network ESSID (not connection name)"

interface=$1 status=$2
case $status in
up|vpn-down)
if iwgetid | grep -qs ":\"$ESSID\""; then
nmcli connection up id "$VPN_NAME"
fi
;;
down)
if iwgetid | grep -qs ":\"$ESSID\""; then
if nmcli connection show --active | grep "$VPN_NAME"; then
nmcli connection down id "$VPN_NAME"
fi
fi
;;
esac
</nowiki>}}

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]].

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.

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''.nmconnection}} and change the {{ic|password-flags}} and {{ic|secret-flags}} from {{ic|1}} to {{ic|0}}.

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:

{{hc|/path/to/passwd-file|
vpn.secrets.password:YOUR_PASSWORD
}}

The script must be changed accordingly, so that it gets the password from the file:

{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki>
#!/bin/sh
VPN_NAME="name of VPN connection defined in NetworkManager"
ESSID="Wi-Fi network ESSID (not connection name)"

interface=$1 status=$2
case $status in
up|vpn-down)
if iwgetid | grep -qs ":\"$ESSID\""; then
nmcli connection up id "$VPN_NAME" passwd-file /path/to/passwd-file
fi
;;
down)
if iwgetid | grep -qs ":\"$ESSID\""; then
if nmcli connection show --active | grep "$VPN_NAME"; then
nmcli connection down id "$VPN_NAME"
fi
fi
;;
esac
</nowiki>}}

2: Alternatively, change the {{ic|password-flags}} and put the password directly in the configuration file adding the section {{ic|vpn-secrets}}:

[vpn]
....
password-flags=0

[vpn-secrets]
password=''your_password''

{{Note|It may now be necessary to re-open the NetworkManager connection editor and save the VPN passwords/secrets again.}}

==== Use dispatcher to disable IPv6 on VPN provider connections ====

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.

{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki>
#!/bin/sh

case "$2" in
vpn-up)
echo 1 > /proc/sys/net/ipv6/conf/all/disable_ipv6
;;
vpn-down)
echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6
;;
esac
</nowiki>}}

{{Note|The above script does not work for WireGuard since NetworkManager does not send the {{ic|vpn-up/down}} events for it. Instead you have to rely on generic events for your WireGuard interfaces as demonstrated in [https://gist.github.com/TheDcoder/85e1ec99a31180e20ba8e4896024f265].}}

As an alternative, dispatcher can be used to temporarily set the IPv6 mode of the device used by the VPN connection to {{ic|link-local}}. This will avoid NetworkManager log spam about IPv6 being disabled. This script will not work if multiple devices or connections provide IPv6 connectivity, but could be adapted to iterate over multiple devices. Note that any change to the connection (using {{man|1|nmcli}} or a [[desktop environment]]) will reapply the entire connection to the device and re-enable IPv6 (if it is enabled in the connection).

{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki>
#!/bin/sh

case "$2" in
vpn-up)
nmcli device modify "${DEVICE_IFACE}" ipv6.method link-local
;;
vpn-down)
nmcli device reapply "${DEVICE_IFACE}"
;;
esac
</nowiki>}}

==== OpenNTPD ====

See [[OpenNTPD#Using NetworkManager dispatcher]].

==== Dynamically set NTP servers received via DHCP with systemd-timesyncd ====

When roaming between different networks (e.g. a company's LAN, Wi-Fi at home, various other Wi-Fi now and then) you might want to set the NTP server(s) used by timesyncd to those provided by DHCP. However, NetworkManager itself is not capable to communicate with systemd-timesyncd to set the NTP server(s).

The dispatcher can work around it.

[[Create]] the overlay directory for your systemd-timesyncd configuration {{ic|/etc/systemd/timesyncd.conf.d}} if it does not already exist. Inside {{ic|/etc/NetworkManager/dispatcher.d}}, put the following:

{{hc|/etc/NetworkManager/dispatcher.d/10-update-timesyncd|<nowiki>
#!/bin/sh

[ -z "$CONNECTION_UUID" ] && exit 0
INTERFACE="$1"
ACTION="$2"

case $ACTION in
up | dhcp4-change | dhcp6-change)
# `DHCP6_DHCP6_NTP_SERVERS` with double `DHCP6` is the correct variable name as varified by `printenv` as of NetworkManager 1.56.0-1
set -- ${DHCP6_DHCP6_NTP_SERVERS-} ${DHCP4_NTP_SERVERS-}
servers=$*
[ -n "$servers" ] || exit 0
mkdir -p /etc/systemd/timesyncd.conf.d
cat <<-THE_END >"/etc/systemd/timesyncd.conf.d/${CONNECTION_UUID}.conf"
[Time]
NTP=$servers
THE_END
systemctl restart systemd-timesyncd.service
;;
down)
rm -f "/etc/systemd/timesyncd.conf.d/${CONNECTION_UUID}.conf"
systemctl restart systemd-timesyncd.service
;;
esac
</nowiki>}}

Every time NetworkManager sets up a new network connection ({{ic|1=ACTION=up}}) or gets some update for an existing connection ({{ic|1=ACTION=dhcp4-change}} or {{ic|1=ACTION=dhcp6-change}}) and the provided connection data contains information about NTP server(s) ({{ic|DHCP6_DHCP6_NTP_SERVERS}} and {{ic|DHCP4_NTP_SERVERS}}), a connection specific overlay configuration file is written to {{ic|/etc/systemd/timesyncd.conf.d}}, containing the provided NTP server(s). Whenever a connection is taken down ({{ic|1=ACTION=down}}) the connection specific overlay file is removed. After each change to the configuration of systemd-timesyncd, this service is restarted to pick up the updated configuration. The use of connection specific configuration files is intentional so that when two or more connections are managed by NetworkManager in parallel the different NTP server names in the configuration are not overwritten as {{ic|up}}, {{ic|dhcp4-change}}, {{ic|dhcp6-change}} and {{ic|down}} actions might come in an arbitrary order.

{{Note|{{ic|1=DHCP6_DHCP6_NTP_SERVERS}} with double {{ic|1=DHCP6}} is the correct variable name as varified by {{ic|1=printenv}} as of NetworkManager 1.56.0-1 }}

== Testing ==

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}}.

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.

To start the GNOME applet in non-xdg-compliant window managers like [[awesome]]:

nm-applet --sm-disable &

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'.

== Tips and tricks ==

=== Encrypted Wi-Fi passwords ===

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:

# grep -r '^psk=' /etc/NetworkManager/system-connections/

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}}).

It is preferable to save the passwords in encrypted form in a keyring instead of clear text. The downside to this is that the connections have to be set up for each user.

In order to read and write to the keyring, there must be a secret agent available. This can be one of:

* {{ic|nmcli}} with the {{ic|--ask}} option
* One of the graphical interfaces from [[#Front-ends]]

If you make neither of these available, then authentication will fail with the error {{ic|no secrets: No agents were available for this request.}}

==== Using GNOME Keyring ====

The keyring daemon has to be started and the keyring needs to be unlocked for the following to work.

Furthermore, NetworkManager needs to be configured not to store the password for all users. Using GNOME's {{Pkg|network-manager-applet}}, run {{ic|nm-connection-editor}} from a terminal, select a network connection, click ''Edit'', select the ''Wi-Fi Security'' tab and click on the right icon of password and check ''Store the password only for this user''.

==== Using KDE Wallet ====

Using KDE's {{Pkg|plasma-nm}}, click the applet, click on the top right ''Settings'' icon, click on a network connection, in the ''General configuration'' tab, untick ''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.

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.

=== Sharing internet connection over Wi-Fi ===

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.

You will need a Wi-Fi card which supports AP mode, see [[Software access point#Wi-Fi device must support AP mode]] for details.

[[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.

Create the shared connection:

* Click on applet and choose ''Create new wireless network''.
* Follow wizard (choose WPA2 or higher, be sure to use at least 8 character long password, lower lengths will fail).
** Choose either [[Fedora:Features/RealHotspot|Hotspot]] or Ad-hoc as Wi-Fi mode.

The connection will be saved and remain stored for the next time you need it.

{{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").}}

=== Sharing internet connection over Ethernet ===

Scenario: your device has internet connection over Wi-Fi and you want to share the internet connection to other devices over Ethernet.

Requirements:

* [[Install]] the {{Pkg|dnsmasq}} and {{Pkg|nm-connection-editor}} packages to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.
* 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).
* Internet sharing is not blocked by a [[firewall]].

Steps:

* Run {{ic|nm-connection-editor}} from terminal.
* Add a new Ethernet connection.
* Give it some sensible name. For example "Shared Internet"
* Go to "IPv4 Settings".
* For "Method:" select "Shared to other computers".
* Save

Now you should have a new option "Shared Internet" under the Wired connections in NetworkManager.

=== Checking if networking is up inside a cron job or script ===

{{Out of date|''nm-tool'' was removed from NetworkManager for long time now[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/bb8c75bd536d4f8fb80a4366025a279078f0ec81]. ''nmcli'' should be used instead.}}

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.

{{bc|<nowiki>
if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then
#Whatever you want to do if the network is online
else
#Whatever you want to do if the network is offline - note, this and the else above are optional
fi
</nowiki>}}

This is 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.

=== Connect to network with secret on boot ===

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:

# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab
# Select the connection you want to work with and click the Edit button
# Check the boxes “Connect Automatically” and “Available to all users”
# Additionally, ensure that under "Wi-Fi Security", "Store password for all users (not encrypted)" is selected

Log out and log back in to complete.

=== OpenConnect with password in KWallet ===

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]].

Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and
enter your credentials in key "VpnSecrets" in this form (replace ''username'' and ''password'' accordingly):

form:main:username%SEP%''username''%SEP%form:main:password%SEP%''password''

Next time you connect, username and password should appear in the "VPN secrets" dialog box.

=== Ignore specific devices ===

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}}:

[keyfile]
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth0

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.

=== Configuring MAC address randomization ===

{{Merge|NetworkManager/Privacy#MAC Randomization|There is a dedicated sub-page for Privacy now.}}

{{Accuracy|The [[iwd]] backend reportedly refuses MAC address randomisation due to open issues, and entry in [[iwd#Troubleshooting]] or link to [[MAC address spoofing#iwd]] might be suitable to account for it; see:|section=iwd backend doesn't support mac spoofing}}

{{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.}}

{{Note| See [[#Using iwd as the Wi-Fi backend]] for iwd specific MAC randomization.}}

MAC randomization can be used for increased privacy by not disclosing your real MAC address to the network.

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 configuration file may be overwritten by NetworkManager.

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}}:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device]
wifi.scan-rand-mac-address=no
}}

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.

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}}:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device-mac-randomization]
# "yes" is already the default for scanning
wifi.scan-rand-mac-address=yes

[connection-mac-randomization]
# Randomize MAC for every ethernet connection
ethernet.cloned-mac-address=random
# Generate a random MAC for each Wi-Fi and associate the two permanently.
wifi.cloned-mac-address=stable
}}

To configure MAC randomization for a specific connection (for example, if the network does not like random MAC addresses), [[#Edit a connection|edit the connection]] to set {{ic|802-11-wireless.cloned-mac-address}} to one of the modes (e.g. {{ic|stable}} or {{ic|random}}).

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.

=== Turn off hostname sending ===

NetworkManager by default sends the hostname to the DHCP server.

To disable sending your hostname to the DHCP server globally, set the {{ic|ipv4.dhcp-send-hostname{{=}}0}} and {{ic|ipv6.dhcp-send-hostname{{=}}0}} options with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}. E.g.:

{{hc|/etc/NetworkManager/conf.d/dhcp-send-hostname.conf|2=
[connection]
ipv4.dhcp-send-hostname=0
ipv6.dhcp-send-hostname=0
}}

To disable sending your hostname to the DHCP server for a specific connection (or alternatively, enable it for a connection if it is disabled globally), add the following to your network connection file:

{{hc|/etc/NetworkManager/system-connections/''your_connection_file''.nmconnection|2=
...
[ipv4]
dhcp-send-hostname=false
...
[ipv6]
dhcp-send-hostname=false
...
}}

{{Note|These options are only honored by the default [[#DHCP client|internal DHCP client]]. To omit sending the hostname when using NetworkManager with dhcpcd, edit {{ic|/etc/dhcpcd.conf}} and insert {{ic|anonymous}} as the last line.}}

=== Enable IPv6 Privacy Extensions ===

See [[IPv6#NetworkManager]].

=== Configure a unique DUID per connection ===

The DHCPv6 Unique Identifier (DUID) is a value used by the DHCPv6 client to identify itself to DHCPv6 servers. NetworkManager supports 3 types of DUID:

* DUID-UUID ([[RFC:6355|RFC 6355]]): generated from an Universally Unique IDentifier (UUID).
* DUID-LL ([[RFC:3315|RFC 3315]]): generated from the Link-Layer address (a.k.a. MAC address).
* DUID-LLT ([[RFC:3315|RFC 3315]]): generated from the Link-Layer address plus a timestamp.

If the internal NetworkManager's DHCP client is in use (the default) it will identify itself with a global and permanent DUID-UUID generated from the machine-id ({{ic|/etc/machine-id}}). This means that all connections share the same UUID, which may be a privacy breach.

Fortunately, NetworkManager is able to provide unique DUIDs per connection, derived from the connection's stable-id and a per-host unique key. You can enable that by adding the following configuration under {{ic|/etc/NetworkManager/conf.d}}:

{{hc|/etc/NetworkManager/conf.d/duid.conf|2=
[connection]
ipv6.dhcp-duid=stable-uuid
}}

The {{ic|stable-ll}} and {{ic|stable-llt}} values are also supported. For further information read the description for {{ic|dhcp-duid}} in {{man|5|nm-settings|ipv6 setting}}.

=== Working with wired connections ===

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.

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 {{Pkg|nm-connection-editor}} for this task.

=== Using iwd as the Wi-Fi backend ===

{{Note|1=<nowiki/>
* Do not enable {{ic|iwd.service}} or manually configure [[iwd]]. NetworkManager will start and manage it itself.
* Consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before switching to ''iwd''.}}

To enable the [https://archive.kernel.org/oldwiki/iwd.wiki.kernel.org/networkmanager.html experimental iwd backend], first [[install]] {{Pkg|iwd}} and then create the following configuration file:

{{hc|/etc/NetworkManager/conf.d/wifi_backend.conf|2=
[device]
wifi.backend=iwd
}}

To use MAC randomization with iwd see [[MAC address spoofing#iwd]].

Alternatively, you can install {{AUR|networkmanager-iwd}}, a modified package configured to build ''NetworkManager'' working exclusively with ''iwd'', with the main difference being that ''iwd'' is required and ''wpa_supplicant'' can be uninstalled after building.

{{Note|1=You may need to [https://archive.kernel.org/oldwiki/iwd.wiki.kernel.org/networkmanager.html#converting_network_profiles convert existing NetworkManager network profiles] after switching to ''iwd''.}}

=== Running in a network namespace ===

If you would like to run NetworkManager inside a network namespace (e.g., to manage a specific device which should be used by selected applications), bring the device down before moving it to the namespace:

$ ip link set dev ''MY_DEVICE'' down
$ ip link set dev ''MY_DEVICE'' netns ''MY_NAMESPACE''
$ ip netns exec ''MY_NAMESPACE'' NetworkManager
...
$ ip netns exec ''MY_NAMESPACE'' killall NetworkManager

otherwise NetworkManager will later fail to establish the connection with a {{ic|device is strictly unmanaged}} error.

=== Automatically connect to VPN ===

NetworkManager can be set to automatically connect to a VPN when connecting to the internet, on a per network basis. The VPN connection itself can be added in GNOME's NetworkManager front-end, but to make it automatically use the VPN {{ic|nmcli}} must be used. Other front-ends might not have this limitation.

First, make sure to make the VPN connection available to all users. In the GNOME this is a matter of checking a box under the {{ic|details}} tab. Under the {{ic|Identity}} tab, in the password field, click the icon on the right side in the field, and set it to {{ic|Store the password for all users}}.

Then find the UUID of the VPN connection, and add that to {{ic|connection.secondaries}} of the Internet connection:

# UUID=$(nmcli --get-values connection.uuid connection show ''name-of-VPN-connection'')
# nmcli connection modify ''name-of-Internet-connection'' connection.secondaries "$UUID"

Now when NetworkManager is restarted and you connect to the Internet connection you have configured, you should automatically get connected to the VPN.

== Troubleshooting ==

=== No prompt for password of secured Wi-Fi networks ===

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''.

=== Network management disabled ===

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:

# rm /var/lib/NetworkManager/NetworkManager.state

=== Problems with internal DHCP client ===

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.

=== DHCP problems with dhclient ===

If you have problems with getting an IP address via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:

interface "eth0" {
send dhcp-client-identifier 01:''aa:bb:cc:dd:ee:ff'';
}

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.

=== 3G modem not detected ===

See [[Mobile broadband modem#NetworkManager]].

=== Switching off WLAN on laptops ===

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:

$ watch -n1 rfkill list all

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):

# rfkill event unblock X

=== Static IP address settings revert to DHCP ===

{{Out of date|This section is [[Special:Diff/119236|added in 2010]] and describes an ancient version of ''nm-applet''. Is this still relevant in 2024?}}

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.

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.

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.

=== Cannot edit connections as normal user ===

See [[#Set up PolicyKit permissions]].

=== Forget hidden wireless network ===

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:

# rm /etc/NetworkManager/system-connections/''SSID''.nmconnection

This also works for any other connection.

=== VPN not working in GNOME ===

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}}:

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.

This is caused by the GNOME NetworkManager Applet expecting dialog scripts to be at {{ic|/usr/lib/gnome-shell}}, when NetworkManager's packages put them in {{ic|/usr/lib/networkmanager}}.
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):

* For OpenConnect: {{ic|ln -s /usr/lib/nm-openconnect-auth-dialog /usr/lib/gnome-shell/}}
* For VPNC (i.e. Cisco VPN): {{ic|ln -s /usr/lib/nm-vpnc-auth-dialog /usr/lib/gnome-shell/}}

This may need to be done for any other NetworkManager VPN plugins as well, but these are the two most common.

=== Unable to connect to visible European wireless networks ===

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:

# [[Install]] {{Pkg|wireless-regdb}}.
# Uncomment the correct country code in {{ic|/etc/conf.d/wireless-regdom}}.
# Reboot the system, because the setting is only read on boot.

=== Automatic connect to VPN on boot is not working ===

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.

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]].

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.

=== systemd bottleneck ===

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]].

=== Regular network disconnects, latency and lost packets (Wi-Fi) ===

NetworkManager does a scan every 2 minutes.

Some Wi-Fi 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.

Running {{ic|journalctl -f}} as root will indicate that this is taking place, messages like the following will be contained in the logs at regular intervals.

NetworkManager[410]: <info> (wlp3s0): roamed from BSSID 00:14:48:11:20:CF (my-wifi-name) to (none) ((none))

If roaming is not important, the periodic scanning behavior can be disabled by locking the BSSID of the access point in the Wi-Fi connection profile.

=== Unable to turn on Wi-Fi with Lenovo laptop (IdeaPad, Legion, etc.) ===

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.

{{Accuracy|Try to use {{ic|rfkill.default_state}} and {{ic|rfkill.master_switch_mode}} (see [https://docs.kernel.org/admin-guide/kernel-parameters.html kernel-parameters.html]) to fix the rfkill problem.}}

[[modprobe|Unloading]] the {{ic|ideapad_laptop}} module should fix this. ('''warning''': this may disable the laptop keyboard and touchpad also!).

=== nm-applet disappears in i3wm ===

If you use the {{ic|xfce4-notifyd.service}} for notifications you must [[edit]] the unit and add the following:

{{hc|/etc/systemd/user/xfce4-notifyd.service.d/display_env.conf|2=
[Service]
Environment="DISPLAY=:0.0"
}}

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.

=== Unit dbus-org.freedesktop.resolve1.service not found ===

If {{ic|systemd-resolved.service}} is not started, NetworkManager will try to start it using D-Bus and fail:

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 ")
dbus-daemon[991]: [system] Activation via systemd failed for unit 'dbus-org.freedesktop.resolve1.service': Unit dbus-org.freedesktop.resolve1.service not found.
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 ")

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]

This can be disabled with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/no-systemd-resolved.conf|2=
[main]
systemd-resolved=false
}}

See {{Bug|62138}}.

=== Secrets were required, but not provided ===

If you received the following error when attempting to connect to a network:

{{hc|$ nmcli device wifi connect ''SSID'' password ''password''|
Error: Connection activation failed: (7) Secrets were required, but not provided
}}

This error can have numerous causes and you should read the [[journal]] (filter it with {{ic|-u NetworkManager}}). For example, if NetworkManager took too long to establish connection, it will believe that the password is incorrect:

{{bc|
NetworkManager[1372]: <warn> [1643991888.3808] device (wlan0): Activation: (wifi) association took too long
NetworkManager[1372]: <info> [1643991888.3809] device (wlan0): state change: config -> need-auth (reason 'none', sys-iface-state: 'managed')
NetworkManager[1372]: <warn> [1643991888.3838] device (wlan0): Activation: (wifi) asking for new secrets
}}

You can try deleting the connection profile and creating a new one:

$ nmcli connection delete ''SSID''
$ nmcli device wifi connect ''SSID'' password ''password''

You can also try disabling MAC address randomization:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device]
wifi.scan-rand-mac-address=no
}}

=== WPA Enterprise connection with iwd ===

If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the [[#Using iwd as the Wi-Fi backend|iwd backend]] then you will get the following error from NetworkManager:

Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)

This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd configuration file {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[iwd#WPA Enterprise]].

=== Failed to request VPN secrets ===

If you get this error:
Failed to request VPN secrets #1: No agents were available for this request.

It is either because the password is empty or you have to [[#Set up PolicyKit permissions|set up PolicyKit permissions]].

=== OpenVPN connections fail with "secrets: failed to request VPN secrets" warn ===

{{Remove|This does not warrant a troubleshooting section. Optional dependencies are pointed out by pacman, if this is not clear enough it should be covered in [[#VPN support]].|section=Remove unnecessary section 8.22}}

The package {{Pkg|networkmanager-openvpn}} requires {{Pkg|libnma-gtk4}} and optionally {{Pkg|libnma}} (Gtk3) when integrated within the GNOME-Shell. If {{Pkg|libnma}} is required but not installed a message will be printed to the system log:

{{bc|
NetworkManager[642]: <warn> [...] vpn[..."name_of_vpn_profile VPN"]: secrets: failed to request VPN secrets #3: No agents were available for this request.
}}

=== OpenVPN connections fail with OpenSSL "ca md too weak" error ===

Since {{Pkg|openssl}} was updated to version 3, certificates generated with legacy cryptographic algorithms are rejected by default. Attempting to use {{Pkg|networkmanager-openvpn}} with such a setup can result in the following error in the logs:

{{bc|
nm-openvpn[14359]: OpenSSL: error:0A00018E:SSL routines::ca md too weak
nm-openvpn[14359]: Cannot load certificate file /home/archie/.local/share/networkmanagement/certificates/my_issued_cert.crt
nm-openvpn[14359]: Exiting due to fatal error
}}

The correct approach is to have the OpenVPN server administrator generate and re-issue more secure certificates. However, as an immediate work-around, OpenVPN requires {{ic|1=tls-cipher "DEFAULT:@SECLEVEL=0"}}. This may not be possible through the plugin GUI, but it is possible with ''nmcli''. Separately, you will also need to enable the ''legacy'' provider in OpenSSL.

Firstly, obtain the name of the VPN connection with the issue, from the output of the following:

$ nmcli connection show

Assuming the connection name is ''vpn.example.com'', use ''nmcli'' like so:

$ nmcli connection modify vpn.example.com +vpn.data tls-cipher=DEFAULT:@SECLEVEL=0

The change should instantly be reflected in {{ic|/etc/NetworkManager/system-connections/vpn.example.com.nmconnection}}.

As for OpenSSL, edit {{ic|/etc/ssl/openssl.cnf}} as described on the [https://wiki.openssl.org/index.php/OpenSSL_3.0#Providers OpenSSL wiki].

Specifically, at the end of the {{ic|[provider_sect]}} section add {{ic|1=legacy = legacy_sect}}. Under {{ic|[default_sect]}} uncomment {{ic|1=activate = 1}}. Lastly, add a new section {{ic|[legacy_sect]}} that also contains the line {{ic|1=activate = 1}}. Excluding most other preexisting configuration sections, the end result will look something like:

{{hc|/etc/ssl/openssl.cnf|2=
openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1
}}

Finally, [[restart]] the {{ic|NetworkManager.service}} to have the new OpenSSL configuration take effect.

=== WPA Enterprise connections fail to authenticate with OpenSSL "unsupported protocol" error ===

Since {{Pkg|openssl}} was updated to version 3, "SSL 3, TLS 1.0, TLS 1.1, and DTLS 1.0 only work at security level 0" [https://www.openssl.org/news/openssl-3.0-notes.html by default]. Attempting to authenticate to a Wi-Fi network only supporting older standards results in the following error in the logs:

{{bc|
wpa_supplicant[3320]: SSL: SSL3 alert: write (local SSL3 detected an error):fatal:protocol version
wpa_supplicant[3320]: OpenSSL: openssl_handshake - SSL_connect error:0A000102:SSL routines::unsupported protocol
wpa_supplicant[3320]: wlp3s0: CTRL-EVENT-EAP-FAILURE EAP authentication failed
}}

The correct approach is to convince the institution's administrator to upgrade the encrypted networking tunnel protocol to TLS 1.3 and optionally drop support for deprecated security standards, including TLS 1.0/1.1, DTLS 1.0 and SSL 1-3. However, as an immediate workaround, there are multiple ways to allow TLS 1.0 and/or 1.1 by default. One way would be to manually patch or revert the breaking changes in OpenSSL ([https://github.com/openssl/openssl/commit/7bf2e4d7f0c7ae19b7a8c416910886a7171e9820]). As this also lowers security for all other programs using OpenSSL level 1, it is not recommended. Instead, one can directly set the level used by wpa_supplicant, like described in [https://bbs.archlinux.org/viewtopic.php?id=286417#p2104492 BBS#286417]. To only change the affected connection, it is possible to set {{ic|1=phase1-auth-flags=32}} or {{ic|1=phase1-auth-flags=64}} in the {{ic|1=[802-1x]}} section of the connection's configuration file. This may not be possible through GUIs, but it is possible with ''nmcli''.

Firstly, obtain the name of the Wi-Fi connection with the issue, from the output of the following:

$ nmcli connection show

Assuming the connection uses TLS 1.0 and its name is ''Example Wi-Fi'', use ''nmcli'' like so:

$ nmcli connection modify 'Example Wi-Fi' 802-1x.phase1-auth-flags 32

And for a TLS 1.1 connection, type "64" instead:

$ nmcli connection modify 'Example Wi-Fi' 802-1x.phase1-auth-flags 64

{{Note|1=The number you type in refers to the number you get from raising 2 to the power of '''n'''. Here, '''n''' is the index of the network authentication bit octet, read from right to left. Flipping the fifth bit enables TLS 1.0 '''[log(2) 32]''' and flipping the sixth bit enables TLS 1.1 '''[log(2) 64]'''.}}

The change should instantly be reflected in {{ic|/etc/NetworkManager/system-connections/Example Wi-Fi.nmconnection}}.

Finally, [[restart]] the {{ic|NetworkManager.service}} to have the new OpenSSL configuration take effect.

== See also ==

* [https://blogs.gnome.org/dcbw/2015/02/16/networkmanager-for-administrators-part-1/ NetworkManager for Administrators Part 1]

NetworkManager

2026-05-08T09:47:10Z

Indigo: /* Configuring MAC address randomization */ add accuracy template with references in Talk:NetworkManager#iwd backend doesn't support mac spoofing

[[Category:Network managers]]
[[Category:DHCP]]
[[ar:Networkmanager]]
[[de:Networkmanager]]
[[fr:NetworkManager]]
[[hu:NetworkManager]]
[[ja:NetworkManager]]
[[pt:NetworkManager]]
[[ru:NetworkManager]]
[[zh-hans:NetworkManager]]
{{Related articles start}}
{{Related|NetworkManager/Privacy}}
{{Related|Network configuration}}
{{Related|Wireless network configuration}}
{{Related articles end}}

[[Wikipedia:NetworkManager|NetworkManager]] is a program for providing detection and configuration for systems to automatically connect to networks.

[https://networkmanager.dev/ NetworkManager] 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.

{{Warning|By default, secrets—e.g. Wi-Fi passwords—are accessible to the root user in the filesystem and to users with access to settings via the GUI (e.g. via [[#nm-applet]]). For more information, see [[#Encrypted Wi-Fi passwords]].}}

== Installation ==

NetworkManager can be [[install]]ed with the package {{Pkg|networkmanager}}, which contains a daemon, a command line interface (''nmcli'') and a curses‐based interface (''nmtui'').

=== Enable NetworkManager ===

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.

{{Note|
* Each network interface should be managed by only one [[Network configuration#Network managers|DHCP client or network manager]], so it is advised to run only one DHCP client or network manager on the system. Find a list of the currently running services with {{ic|1=systemctl --type=service}} and then [[stop]] or reconfigure those that conflict.
* If [[systemd-resolved]] is not [[started]], an error message will start flooding your logs. See [[#Unit dbus-org.freedesktop.resolve1.service not found]] for more info.
}}

=== Additional interfaces ===

* {{Pkg|nm-connection-editor}} for a graphical user interface,
* {{Pkg|network-manager-applet}} for a system tray applet (see the [[#nm-applet]] section).

=== Mobile broadband support ===

NetworkManager uses [[ModemManager]] for mobile broadband connection support.

[[Install]] {{Pkg|modemmanager}} and {{Pkg|usb_modeswitch}}. Afterwards [[enable]] and [[start]] {{ic|ModemManager.service}}.

It may be necessary to [[restart]] {{ic|NetworkManager.service}} for it to detect ModemManager. After you restart it, re-plug the modem again and it should be recognized.

Add connections from a front-end (e.g. {{Pkg|nm-connection-editor}}) and select mobile broadband as the connection type. After selecting your ISP and billing plan, [[Wikipedia:Access Point Name|APN]] and other settings should be filled in automatically using information from {{Pkg|mobile-broadband-provider-info}}.

=== PPPoE / DSL support ===

[[Install]] {{Pkg|ppp}} package for PPPoE / DSL connection support. To actually add PPPoE connection, use {{ic|1=nm-connection-editor}} and add new DSL/PPPoE connection.

=== VPN support ===

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.

Support for other VPN types is based on a plug-in system. They are provided in the following packages:

* {{Pkg|networkmanager-openconnect}} for [[OpenConnect]]
* {{Pkg|networkmanager-openvpn}} for [[OpenVPN]]
* {{Pkg|networkmanager-pptp}} for [[PPTP Client]]
* {{Pkg|networkmanager-strongswan}} for [[strongSwan]]
* {{Pkg|networkmanager-vpnc}}
* {{AUR|networkmanager-fortisslvpn}}
* {{AUR|networkmanager-iodine-git}}
* {{AUR|networkmanager-libreswan}}
* {{Pkg|networkmanager-l2tp}}
* {{AUR|networkmanager-ssh}}
* {{Pkg|network-manager-sstp}}

{{Warning|1=There are a lot of [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues?search=VPN&state=opened bugs] related to VPN support. Check the daemon processes options set via the GUI correctly and double-check with each package release.}}

{{Note|
* To have fully functioning DNS resolution when using VPN, you should set up [[#DNS caching and conditional forwarding|conditional forwarding]].
* These plug-ins may not have a documented command line interface, or may not work at all without an applet running. This is not an issue if you are using a regular desktop environment; if you are not, you should run [[#nm-applet]] while configuring or activating the connection so that you get the necessary dialogues. [https://bbs.archlinux.org/viewtopic.php?id{{=}}246698]
}}

== Usage ==

NetworkManager comes with {{man|1|nmcli}} and {{man|1|nmtui}}.

=== nmcli examples ===

List nearby Wi-Fi networks:

$ nmcli device wifi list

Connect to a Wi-Fi network:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password''

Connect to a hidden Wi-Fi network:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' hidden yes

Connect to a Wi-Fi on the {{ic|wlan1}} interface:

$ nmcli device wifi connect ''SSID_or_BSSID'' password ''password'' ifname wlan1 ''profile_name''

Disconnect an interface:

$ nmcli device disconnect ifname eth0

Get a list of connections with their names, UUIDs, types and backing devices:

$ nmcli connection show

Activate a connection (i.e. connect to a network with an existing profile):

$ nmcli connection up ''name_or_uuid''

Delete a connection:

$ nmcli connection delete ''name_or_uuid''

See a list of network devices and their state:

$ nmcli device

Turn off Wi-Fi:

$ nmcli radio wifi off

=== Edit a connection ===

For a comprehensive list of settings, see {{man|5|nm-settings}}.

Firstly, you need to get a list of connections:

{{hc|$ nmcli connection|<nowiki>
NAME UUID TYPE DEVICE
Wired connection 2 e7054040-a421-3bef-965d-bb7d60b7cecf ethernet enp5s0
Wired connection 1 997f2782-f0fc-301d-bfba-15421a2735d8 ethernet enp0s25
MY-HOME-WIFI-5G 92a0f7b3-2eba-49ab-a899-24d83978f308 wifi --
</nowiki>}}

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.

You have three methods to configure a connection {{ic|Wired connection 2}} after it has been created:

; nmcli interactive editor
: {{ic|nmcli connection edit 'Wired connection 2'}}. Usage is well documented from the editor.

; nmcli command line interface
: {{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.
To remove a setting, pass an empty field ("") to it like this:
: {{ic|nmcli connection modify 'Wired connection 2' ''setting''.''property'' ""}}

; Connection file
: In {{ic|/etc/NetworkManager/system-connections/}}, modify the corresponding {{ic|Wired connection 2.nmconnection}} file . Do not forget to reload the configuration file with {{ic|nmcli connection reload}}.

=== nmtui ===

NetworkManager ships a text user interface (TUI) for managing connections, the system hostname and radio switches. It can be launched by running {{ic|nmtui}}.

== Front-ends ==

To provide integration with a [[desktop environment]], most users will want to install an applet. This not only provides easy access to network selection and configuration, but also provides the agent necessary for securely storing secrets. Various desktop environments have their own applet; otherwise, you can use [[#nm-applet]].

=== GNOME ===

[[GNOME]] has a built-in tool, accessible from the Network settings.

=== KDE Plasma ===

[[Install]] the {{Pkg|plasma-nm}} package. After that, add it to the KDE taskbar via the ''Panel options > Add widgets > Networks'' menu.

=== nm-applet ===

{{Pkg|network-manager-applet}} is a GTK 3 front-end which works under Xorg environments with a systray.

To store connection secrets install and configure an application which implements the [https://specifications.freedesktop.org/secret-service-spec/latest/ Secret Service D-Bus API] such as [[GNOME/Keyring]], [[KDE Wallet]], or [[KeePassXC]].

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]].

In order to run {{ic|nm-applet}} without a systray, you can use {{AUR|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:

{{hc|nmgui|<nowiki>
#!/bin/sh
nm-applet 2>&1 > /dev/null &
stalonetray 2>&1 > /dev/null
killall nm-applet
</nowiki>}}

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.

The applet can show notifications for events such as connecting to or disconnecting from a Wi-Fi 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 applet might hang. See [https://bugzilla.gnome.org/show_bug.cgi?id=788313].

In order to run {{ic|nm-applet}} with such notifications disabled, start the applet with the following command:

$ nm-applet --no-agent

{{Tip|{{ic|nm-applet}} might be started automatically with a [[XDG Autostart|autostart desktop file]], to add the {{ic|--no-agent}} option modify the Exec line there, i.e.

{{bc|1=Exec=nm-applet --no-agent}}

}}

{{Warning|On [[i3]], if nm-applet is started with the {{ic|--no-agent}} option, it is not possible to connect to a new encrypted Wi-Fi 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}}.}}

==== Appindicator ====

As of version 1.18.0 Appindicator support is [https://gitlab.archlinux.org/archlinux/packaging/packages/network-manager-applet/-/commit/527448fb2a87d85055f504f463dfe961dccd75c3 available] in the official {{Pkg|network-manager-applet}} package. To use nm-applet in an Appindicator environment start the applet with the following command:

$ nm-applet --indicator

=== networkmanager-dmenu ===

Alternatively there is {{Pkg|networkmanager-dmenu}} 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 Wi-Fi or wired connections, connect to new Wi-Fi connections, requests passphrase if required, connect to existing VPN connections, enable/disable networking, launch ''nm-connection-editor'' GUI, connect to Bluetooth networks.

=== switchboard ===

Pantheon's {{Pkg|switchboard}} offers a desktop environment-agnostic way to configure NetworkManager when combined with {{Pkg|switchboard-plug-network}} and {{Pkg|nm-connection-editor}}. It can be ran with the following command:

$ io.elementary.settings

== Configuration ==

NetworkManager may 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.

NetworkManager has a global configuration file at {{ic|/etc/NetworkManager/NetworkManager.conf}}. Additional configuration files can be placed in {{ic|/etc/NetworkManager/conf.d/}}. Usually no configuration needs to be done to the global defaults.

After editing a configuration file, the changes can be applied by running:

# nmcli general reload

=== NetworkManager-wait-online ===

Enabling {{ic|NetworkManager.service}} also enables {{ic|NetworkManager-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 finish 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]].

By default, {{ic|NetworkManager-wait-online.service}} waits for NetworkManager startup to complete, rather than waiting for network connectivity specifically (see {{man|1|nm-online}}). If {{ic|NetworkManager-wait-online.service}} finishes before the network is really up, resulting in failed services on boot, [[extend the unit]] to remove the {{ic|-s}} from the {{ic|ExecStart}} line:

[Service]
ExecStart=
ExecStart=/usr/bin/nm-online -q

Be aware that this can cause [https://lists.fedoraproject.org/archives/list/users@lists.fedoraproject.org/thread/EGC324JD3HJCGVN7J55WYPRLFDA3TP7N/ other issues].

In some cases, the service will still fail to start successfully on boot due to the timeout setting being too short. [[Edit]] the service to change {{ic|NM_ONLINE_TIMEOUT}} from {{ic|60}} to a higher value.

=== Set up PolicyKit permissions ===

By default, all users in active local sessions are allowed to change most network settings without a password. See [[General troubleshooting#Session permissions]] to check your session type. In most cases, everything should work out of the box.

Some actions (such as changing the system hostname) require an administrator password. In this case, you need to [[Users and groups#Group management|add]] yourself to the {{ic|wheel}} group and run a [[Polkit#Authentication agents|Polkit authentication agent]] which will prompt for your password.

For remote sessions (e.g. [[TigerVNC#Running vncserver for virtual (headless) sessions|headless VNC]]), you have several options for obtaining the necessary privileges to use NetworkManager:

# [[Users and groups#Group management|Add]] yourself to the {{ic|wheel}} group. You will have to enter your password for every action. Note that your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.
# [[Users and groups#Group management|Add]] yourself to the {{ic|network}} group and create {{ic|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules}} with the following content: {{bc|<nowiki>
polkit.addRule(function(action, subject) {
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {
return polkit.Result.YES;
}
});
</nowiki>}} All users in the {{ic|network}} group will be able to add and remove networks without a password (which means you do not have to run a Polkit authentication agent, so this option will also work in SSH sessions).

=== Proxy settings ===

NetworkManager does support some proxy settings. While they can not be directly modified using ''nmtui'', ''nm-applet'' and ''nmcli'' support those.
See the proxy settings in {{man|5|nm-settings-nmcli}}.

Additionally, custom proxy commands can always be run using dispatcher scripts, see [[#Dispatcher examples]].

See also [[Proxy settings]].

=== Checking connectivity ===

NetworkManager can try to reach a webserver after connecting to a network in order to determine if it is e.g behind a captive portal. The default host (configured in {{ic|/usr/lib/NetworkManager/conf.d/20-connectivity.conf}}) is [https://ping.archlinux.org ping.archlinux.org] (a CNAME alias of redirect.archlinux.org). To use a different webserver or to 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]]):

{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki>
[connectivity]
uri=http://nmcheck.gnome.org/check_network_status.txt
</nowiki>}}

To disable NetworkManager's connectivity check, use the following configuration. This can be useful when connected to a VPN that blocks connectivity checks.

{{hc|/etc/NetworkManager/conf.d/20-connectivity.conf|<nowiki>
[connectivity]
enabled=false
</nowiki>}}

{{Note|Although automatic connectivity checks are a potential privacy leak, Arch Linux's default connectivity URL is committed to not logging any access. See [https://gitlab.archlinux.org/archlinux/infrastructure/-/commit/fabccd0f61e5dea3925e8a0c6a46d56d5750c121#a4f34381bbb18ea77bfb3dd11a8aeca707078fca_0_26] [https://gitlab.archlinux.org/archlinux/infrastructure/-/blob/master/roles/ping/templates/nginx.d.conf.j2].}}

=== Captive portals ===

{{Style|Complex scripts should not be maintained on the wiki.}}

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 has a broken NetworkManager dispatcher script). Alternatively, you can create a NetworkManager dispatcher script with the following content:

{{hc|/etc/NetworkManager/dispatcher.d/90-open_captive_portal|<nowiki>
#!/bin/sh -e
# Script to dispatch NetworkManager events
#
# Runs shows a login webpage on walled garden networks.
# See NetworkManager(8) for further documentation of the dispatcher events.

PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

if [ -x "/usr/bin/logger" ]; then
logger="/usr/bin/logger -s -t captive-portal"
else
logger=":"
fi

wait_for_process() {
PNAME=$1
while [ -z "$(/usr/bin/pgrep $PNAME)" ]; do
sleep 3;
done
}

#launch the browser, but on boot we need to wait that nm-applet starts
start_browser() {
local user="$1"
local display="$2"

export DISPLAY="$display"
wait_for_process nm-applet

export XAUTHORITY="/home/$user/.Xauthority"

$logger "Running browser as '$user' with display '$display' to login in captive portal"
sudo -u "$user" --preserve-env=DISPLAY,XAUTHORITY -H xdg-open http://capnet.elementary.io 2>&1 > /dev/null
}

# Run the right scripts
case "$2" in
connectivity-change)
$logger -p user.debug "dispatcher script triggered on connectivity change: $CONNECTIVITY_STATE"
if [ "$CONNECTIVITY_STATE" = "PORTAL" ]; then
# Match last column of who's output with ' :[at least one digit] '
who | awk '$NF ~ /$:[0-9]+$/ { print $1 " " substr($NF, 2, length($NF)-2) };' | \
while read user display; do
start_browser $user $display || $logger -p user.err "Failed for user: '$user' display: '$display'"
done
fi
;;
*)
# In a down phase
exit 0
;;
esac
</nowiki>}}

Make the script [[executable]]. But that script assumes you use X and simply opens http page. It might not work for everyone.

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.

Simple solution is [https://github.com/Seme4eg/captive-portal-sh captive-portal-sh] - shell script that obtains captive portal URL and opens it in your default browser (for Wayland users only).

Another solution is {{AUR|captive-browser-git}} based on Google Chrome.

==== iwd support for captive portal support on legacy hardware ====

Some older Wi-Fi chips (e.g. Broadcom BCM4360) require the proprietary {{ic|wl}} driver, which lacks support for the OWE/Elliptic-Curve handshake that many captive-portal hotspots use before presenting a login page. By switching NetworkManager’s Wi-Fi backend to {{ic|iwd}} (see [[#Using iwd as the Wi-Fi backend]]), which implements the full OWE key exchange in userspace over the existing driver, you can complete the encrypted association, obtain a DHCP lease, and trigger the portal “PORTAL” state. Once that is done, any dispatcher script or browser-launcher will reliably pop up the login page on hardware that otherwise could never fully connect.

=== DHCP client ===

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.

To use a different DHCP client [[install]] one of the alternatives:

* {{Pkg|dhcpcd}} - [[dhcpcd]]
* {{Pkg|dhclient}} - [[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.:

{{hc|1=/etc/NetworkManager/conf.d/dhcp-client.conf|2=
[main]
dhcp=dhcpcd
}}

{{Note|
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.
}}

=== DNS management ===

NetworkManager's DNS management is described in the GNOME project's wiki page—[https://wiki.gnome.org/Projects/NetworkManager/DNS Projects/NetworkManager/DNS].

==== DNS caching and conditional forwarding ====

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.

{{Note|If {{ic|/etc/resolv.conf}} is a symlink to {{ic|/run/systemd/resolve/stub-resolv.conf}}, {{ic|/run/systemd/resolve/resolv.conf}},{{ic|/lib/systemd/resolv.conf}} or {{ic|/usr/lib/systemd/resolv.conf}}, NetworkManager will choose systemd-resolved automatically. To use dnsmasq, you must first remove that symlink, then restart NetworkManager.}}

===== dnsmasq =====

Make sure {{Pkg|dnsmasq}} has been installed. Then set {{ic|1=main.dns=dnsmasq}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=dnsmasq
}}

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.

{{Note|
* 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).
* 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.
}}

====== Custom dnsmasq configuration ======

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):

{{hc|/etc/NetworkManager/dnsmasq.d/cache.conf|2=
cache-size=1000
}}

You can check the configuration file syntax with:

$ dnsmasq --test --conf-file=/dev/null --conf-dir=/etc/NetworkManager/dnsmasq.d

See {{man|8|dnsmasq}} for all available options.

====== IPv6 ======

{{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}}.}}

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:

{{hc|/etc/NetworkManager/dnsmasq.d/ipv6-listen.conf|2=
listen-address=::1
}}

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.

====== DNSSEC ======

The dnsmasq instance started by NetworkManager by default will not validate [[DNSSEC]]. To enable DNSSEC validation, thus breaking DNS resolution with name servers that do not support it, create the following configuration file:

{{hc|/etc/NetworkManager/dnsmasq.d/dnssec.conf|2=
conf-file=/usr/share/dnsmasq/trust-anchors.conf
dnssec
}}

===== systemd-resolved =====

{{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]]?}}

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.

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}}.

You can enable it explicitly by setting {{ic|1=main.dns=systemd-resolved}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=systemd-resolved
}}

===== DNS resolver with an openresolv subscriber =====

If [[openresolv]] has a subscriber for your local [[DNS resolver]], set up the subscriber and [[#Use openresolv|configure NetworkManager to use openresolv]].

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].

This can be partially mitigated if you set {{ic|1=private_interfaces="*"}} in {{ic|/etc/resolvconf.conf}}[https://roy.marples.name/projects/openresolv/configuration/]. 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.

==== Custom DNS servers ====

===== Setting custom global DNS servers =====

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:

{{hc|/etc/NetworkManager/conf.d/dns-servers.conf|2=
[global-dns-domain-*]
servers=::1,127.0.0.1
}}

{{Note|
* 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.
* The specified servers do not get sent to [[systemd-resolved]], the connection's DNS servers are used instead. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/1366 NetworkManager issue 1366] and [https://github.com/systemd/systemd/issues/33754 systemd issue 33754].
}}

===== Setting custom DNS servers in a connection =====

====== Setting custom DNS servers in a connection (GUI) ======

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'', ...}}.

====== Setting custom DNS servers in a connection (nmcli / connection file) ======

To set up DNS Servers per connection, you change the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings (and their associated {{ic|dns-search}} and {{ic|dns-options}}) in the [[#Edit a connection|connection settings]].

If {{ic|method}} is set to {{ic|auto}} (when you use DHCP/RA), you need to set {{ic|ignore-auto-dns}} to {{ic|yes}}.

To use DNS over TLS ([[#systemd-resolved|requires systemd-resolved]]), specify the DNS servers using the syntax {{ic|1=dns=''ip.address''#''servername'';}} and additionally set the {{ic|connection.dns-over-tls}} setting to {{ic|2}}. For example, to use Quad9:

{{hc|/etc/NetworkManager/system-connections/Example Wi-Fi.nmconnection|2=
...
[connection]
...
dns-over-tls=2

[ipv4]
...
dns=9.9.9.9#dns.quad9.net;149.112.112.112#dns.quad9.net;
ignore-auto-dns=true

[ipv6]
...
dns=2620:fe::fe#dns.quad9.net;2620:fe::9#dns.quad9.net;
ignore-auto-dns=true
}}

{{Note|This example uses Quad9. Replace it with a DNS resolver you trust. See [[Domain name resolution#Third-party DNS services]].}}

==== /etc/resolv.conf ====

NetworkManager's {{ic|/etc/resolv.conf}} management mode is configured with the {{ic|main.rc-manager}} setting. {{Pkg|networkmanager}} sets it to {{ic|symlink}} as opposed to the upstream default {{ic|auto}}. The setting and its values are documented in the {{man|5|NetworkManager.conf}} man page.

{{Tip|Using openresolv allows NetworkManager to coexist 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]]. Note that conditional forwarding is [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/153 not yet fully supported] when using NetworkManager with openresolv.}}

''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.

{{Note|
* 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}}.
* The {{ic|resolv.conf}} file NetworkManager writes or would write to {{ic|/etc/resolv.conf}} can be found at {{ic|/run/NetworkManager/resolv.conf}}.
* A {{ic|resolv.conf}} file with the acquired name servers and search domains can be found at {{ic|/run/NetworkManager/no-stub-resolv.conf}}.
}}

===== Unmanaged /etc/resolv.conf =====

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/}}:

{{hc|/etc/NetworkManager/conf.d/dns.conf|2=
[main]
dns=none
}}

{{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]].}}

{{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}}.}}

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.

===== Use openresolv =====

{{Note|NetworkManager does not support using systemd-resolved's ''resolvconf'' interface ({{man|1|resolvectl|COMPATIBILITY WITH RESOLVCONF(8)}}) which is provided by {{Pkg|systemd-resolvconf}}.
* Do not set {{ic|1=main.rc-manager=resolvconf}} when using [[systemd-resolved]], instead make sure to [[systemd-resolved#DNS|correctly create the /etc/resolv.conf symlink]] or [[#systemd-resolved|configure NetworkManager to use systemd-resolved explicitly]].
* Make sure the {{Pkg|systemd-resolvconf}} package is not installed when systemd-resolved is not used. Unless {{ic|systemd-resolved.service}} started, it will break all networking software (not just NetworkManager) that use resolvconf.
}}

To configure NetworkManager to use [[openresolv]], set {{ic|1=main.rc-manager=resolvconf}} with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/rc-manager.conf|2=
[main]
rc-manager=resolvconf
}}

=== Firewall ===

You can [[Firewalld#Using NetworkManager to manage zones|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.

This can also be done with [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher]].

== Network services with NetworkManager dispatcher ==

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]]).

To activate the feature you need to [[enable]] and [[start]] the {{ic|NetworkManager-dispatcher.service}}.

Once the service is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory.

Scripts must be owned by '''root''', otherwise the dispatcher will not execute them. For added security, set group [[ownership]] to root as well:

# chown root:root /etc/NetworkManager/dispatcher.d/''10-script.sh''

Make sure the file is [[executable]].

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).

Scripts will receive the following arguments:

* '''Interface name:''' e.g. {{ic|eth0}}
* '''Action:''' ''up'', ''down'', ''vpn-up'', ''vpn-down'', ... (see {{man|8|NetworkManager-dispatcher}} for the complete list)

{{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.}}

=== Avoiding the dispatcher timeout ===

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 use a [[drop-in file]] for the {{ic|NetworkManager-dispatcher.service}} to remain active after exit:

{{hc|/etc/systemd/system/NetworkManager-dispatcher.service.d/remain_after_exit.conf|2=
[Service]
RemainAfterExit=yes
}}

Now start and enable the modified {{ic|NetworkManager-dispatcher}} service.

{{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.}}

=== Dispatcher examples ===

==== Automatically set the timezone ====

Create a [[#Network services with NetworkManager dispatcher|NetworkManager dispatcher script]] and make it [[executable]]:

{{hc|/etc/NetworkManager/dispatcher.d/09-timezone|
#!/bin/sh
case "$2" in
up)
timedatectl set-timezone "$(curl --fail <nowiki>https://ipapi.co/timezone</nowiki>)"
;;
esac
}}

{{Tip|Using {{ic|connectivity-change}} instead of {{ic|up}} can prevent timezone changes when connecting to VPNs with clients such as [[OpenConnect]].}}

Alternatively, the tool {{aur|tzupdate}} automatically sets the timezone based on the geolocation of the IP address. This [https://medium.com/@ipdata_co/what-is-the-best-commercial-ip-geolocation-api-d8195cda7027 comparison of the most popular IP geolocation apis] may be helpful in deciding which API to use in production.

==== Mount remote directory with sshfs ====

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}}.

{{bc|<nowiki>
#!/bin/sh
USER='username'
REMOTE='user@host:/remote/path'
LOCAL='/local/path'

interface=$1 status=$2
if [ "$CONNECTION_UUID" = "</nowiki>''uuid''<nowiki>" ]; then
case $status in
up)
# sleep 10
SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')
export SSH_AUTH_SOCK
su "$USER" -c "sshfs $REMOTE $LOCAL"
;;
down)
fusermount -u "$LOCAL"
;;
esac
fi
</nowiki>}}

==== Mounting of SMB shares ====

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.

The following script will check if we connected to a specific network and mount shares accordingly:

{{hc|/etc/NetworkManager/dispatcher.d/30-mount-smb.sh|<nowiki>
#!/bin/sh

# Find the connection UUID with "nmcli connection show" in terminal.
# All NetworkManager connection types are supported: wireless, VPN, wired...
if [ "$2" = "up" ]; then
if [ "$CONNECTION_UUID" = "uuid" ]; then
mount /your/mount/point &
# add more shares as needed
fi
fi
</nowiki>}}

The following script will unmount all SMB shares before a software initiated disconnect from a specific network:

{{hc|/etc/NetworkManager/dispatcher.d/pre-down.d/30-umount-smb.sh|<nowiki>
#!/bin/sh

if [ "$CONNECTION_UUID" = "uuid" ]; then
umount -a -l -t cifs
fi
</nowiki>}}

{{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.}}

The following script will attempt to unmount all SMB shares following an unexpected disconnect from a specific network:

{{hc|/etc/NetworkManager/dispatcher.d/40-umount-smb.sh|<nowiki>
#!/bin/sh

if [ "$CONNECTION_UUID" = "uuid" ]; then
if [ "$2" = "down" ]; then
umount -a -l -t cifs
fi
fi
</nowiki>}}

{{Note|
* 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=701242 this bug report] for more info.
* The previous ''umount'' scripts are still prone to leaving applications actually accessing the mount to 'hang'.
}}

An alternative is to use the script as seen in [[NFS#Using a NetworkManager dispatcher]]:

{{hc|/etc/NetworkManager/dispatcher.d/30-smb.sh|<nowiki>
#!/bin/sh

# Find the connection UUID with "nmcli con show" in terminal.
# All NetworkManager connection types are supported: wireless, VPN, wired...
WANTED_CON_UUID="CHANGE-ME-NOW-9c7eff15-010a-4b1c-a786-9b4efa218ba9"

if [ "$CONNECTION_UUID" = "$WANTED_CON_UUID" ]; then

# Script parameter $1: network interface name, not used
# Script parameter $2: dispatched event

case "$2" in
"up")
mount -a -t cifs
;;
"down"|"pre-down"|"vpn-pre-down")
umount -l -a -t cifs >/dev/null
;;
esac
fi
</nowiki>}}

{{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.}}

Create a symlink inside {{ic|/etc/NetworkManager/dispatcher.d/pre-down/}} to catch the {{ic|pre-down}} events:

# ln -s ../30-smb.sh /etc/NetworkManager/dispatcher.d/pre-down.d/30-smb.sh

==== Mounting of NFS shares ====

See [[NFS#Using a NetworkManager dispatcher]].

==== Use dispatcher to automatically toggle wireless depending on LAN cable being plugged in ====

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.

Create the following dispatcher script[https://superuser.com/questions/233448/disable-wlan-if-wired-cable-network-is-available], replacing {{ic|''Your_Ethernet_Interface''}} with your ethernet interface's device name.

{{Note|You can get a list of interfaces using [[#nmcli examples|nmcli]] ({{ic|nmcli d {{!}} grep ethernet}}). The Ethernet interfaces start with {{ic|en}} or {{ic|eth}}, e.g. {{ic|enp0s5}} or {{ic|eth0}}.}}

Remember to make the script [[executable]]. You can verify that it works by [[restart]]ing {{ic|NetworkManager.service}}, running {{ic|ip a}}, and checking that {{ic|wlp3s0}} (or whatever your Wi-Fi interface is called) is in {{ic|state DOWN}}. If you encounter unexpected behavior, check the [[journal]] of {{ic|NetworkManager-dispatcher.service}}.

{{hc|/etc/NetworkManager/dispatcher.d/99-wifi-auto-toggle.sh|2=
#!/bin/sh

LOG_PREFIX="WiFi Auto-Toggle"
ETHERNET_INTERFACE="''Your_Ethernet_Interface''"

if [ "$1" = "$ETHERNET_INTERFACE" ]; then
case "$2" in
up)
echo "$LOG_PREFIX ethernet up"
nmcli radio wifi off
;;
down)
echo "$LOG_PREFIX ethernet down"
nmcli radio wifi on
;;
esac
elif [ "$(nmcli -g GENERAL.STATE device show $ETHERNET_INTERFACE)" = "20 (unavailable)" ]; then
echo "$LOG_PREFIX failsafe"
nmcli radio wifi on
fi
}}

{{Note|There is a fail-safe for the case when the LAN interface was connected when the computer was last on, and then disconnected while the computer was off. That would mean the radio would still be off when the computer is turned back on, and with a disconnected LAN interface, you would have no network.}}

==== Use dispatcher to connect to a VPN after a network connection is established ====

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.

{{Accuracy|A scripting without {{ic|iwgetid}} does work too and may be more reliable?|section=Fixes for automatic VPN dispatcher script}}

{{Note|This script will require {{Pkg|wireless_tools}} in order to use {{ic|iwgetid}}.}}

{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki>
#!/bin/sh
VPN_NAME="name of VPN connection defined in NetworkManager"
ESSID="Wi-Fi network ESSID (not connection name)"

interface=$1 status=$2
case $status in
up|vpn-down)
if iwgetid | grep -qs ":\"$ESSID\""; then
nmcli connection up id "$VPN_NAME"
fi
;;
down)
if iwgetid | grep -qs ":\"$ESSID\""; then
if nmcli connection show --active | grep "$VPN_NAME"; then
nmcli connection down id "$VPN_NAME"
fi
fi
;;
esac
</nowiki>}}

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]].

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.

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''.nmconnection}} and change the {{ic|password-flags}} and {{ic|secret-flags}} from {{ic|1}} to {{ic|0}}.

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:

{{hc|/path/to/passwd-file|
vpn.secrets.password:YOUR_PASSWORD
}}

The script must be changed accordingly, so that it gets the password from the file:

{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki>
#!/bin/sh
VPN_NAME="name of VPN connection defined in NetworkManager"
ESSID="Wi-Fi network ESSID (not connection name)"

interface=$1 status=$2
case $status in
up|vpn-down)
if iwgetid | grep -qs ":\"$ESSID\""; then
nmcli connection up id "$VPN_NAME" passwd-file /path/to/passwd-file
fi
;;
down)
if iwgetid | grep -qs ":\"$ESSID\""; then
if nmcli connection show --active | grep "$VPN_NAME"; then
nmcli connection down id "$VPN_NAME"
fi
fi
;;
esac
</nowiki>}}

2: Alternatively, change the {{ic|password-flags}} and put the password directly in the configuration file adding the section {{ic|vpn-secrets}}:

[vpn]
....
password-flags=0

[vpn-secrets]
password=''your_password''

{{Note|It may now be necessary to re-open the NetworkManager connection editor and save the VPN passwords/secrets again.}}

==== Use dispatcher to disable IPv6 on VPN provider connections ====

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.

{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki>
#!/bin/sh

case "$2" in
vpn-up)
echo 1 > /proc/sys/net/ipv6/conf/all/disable_ipv6
;;
vpn-down)
echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6
;;
esac
</nowiki>}}

{{Note|The above script does not work for WireGuard since NetworkManager does not send the {{ic|vpn-up/down}} events for it. Instead you have to rely on generic events for your WireGuard interfaces as demonstrated in [https://gist.github.com/TheDcoder/85e1ec99a31180e20ba8e4896024f265].}}

As an alternative, dispatcher can be used to temporarily set the IPv6 mode of the device used by the VPN connection to {{ic|link-local}}. This will avoid NetworkManager log spam about IPv6 being disabled. This script will not work if multiple devices or connections provide IPv6 connectivity, but could be adapted to iterate over multiple devices. Note that any change to the connection (using {{man|1|nmcli}} or a [[desktop environment]]) will reapply the entire connection to the device and re-enable IPv6 (if it is enabled in the connection).

{{hc|/etc/NetworkManager/dispatcher.d/10-vpn-ipv6|<nowiki>
#!/bin/sh

case "$2" in
vpn-up)
nmcli device modify "${DEVICE_IFACE}" ipv6.method link-local
;;
vpn-down)
nmcli device reapply "${DEVICE_IFACE}"
;;
esac
</nowiki>}}

==== OpenNTPD ====

See [[OpenNTPD#Using NetworkManager dispatcher]].

==== Dynamically set NTP servers received via DHCP with systemd-timesyncd ====

When roaming between different networks (e.g. a company's LAN, Wi-Fi at home, various other Wi-Fi now and then) you might want to set the NTP server(s) used by timesyncd to those provided by DHCP. However, NetworkManager itself is not capable to communicate with systemd-timesyncd to set the NTP server(s).

The dispatcher can work around it.

[[Create]] the overlay directory for your systemd-timesyncd configuration {{ic|/etc/systemd/timesyncd.conf.d}} if it does not already exist. Inside {{ic|/etc/NetworkManager/dispatcher.d}}, put the following:

{{hc|/etc/NetworkManager/dispatcher.d/10-update-timesyncd|<nowiki>
#!/bin/sh

[ -z "$CONNECTION_UUID" ] && exit 0
INTERFACE="$1"
ACTION="$2"

case $ACTION in
up | dhcp4-change | dhcp6-change)
# `DHCP6_DHCP6_NTP_SERVERS` with double `DHCP6` is the correct variable name as varified by `printenv` as of NetworkManager 1.56.0-1
set -- ${DHCP6_DHCP6_NTP_SERVERS-} ${DHCP4_NTP_SERVERS-}
servers=$*
[ -n "$servers" ] || exit 0
mkdir -p /etc/systemd/timesyncd.conf.d
cat <<-THE_END >"/etc/systemd/timesyncd.conf.d/${CONNECTION_UUID}.conf"
[Time]
NTP=$servers
THE_END
systemctl restart systemd-timesyncd.service
;;
down)
rm -f "/etc/systemd/timesyncd.conf.d/${CONNECTION_UUID}.conf"
systemctl restart systemd-timesyncd.service
;;
esac
</nowiki>}}

Every time NetworkManager sets up a new network connection ({{ic|1=ACTION=up}}) or gets some update for an existing connection ({{ic|1=ACTION=dhcp4-change}} or {{ic|1=ACTION=dhcp6-change}}) and the provided connection data contains information about NTP server(s) ({{ic|DHCP6_DHCP6_NTP_SERVERS}} and {{ic|DHCP4_NTP_SERVERS}}), a connection specific overlay configuration file is written to {{ic|/etc/systemd/timesyncd.conf.d}}, containing the provided NTP server(s). Whenever a connection is taken down ({{ic|1=ACTION=down}}) the connection specific overlay file is removed. After each change to the configuration of systemd-timesyncd, this service is restarted to pick up the updated configuration. The use of connection specific configuration files is intentional so that when two or more connections are managed by NetworkManager in parallel the different NTP server names in the configuration are not overwritten as {{ic|up}}, {{ic|dhcp4-change}}, {{ic|dhcp6-change}} and {{ic|down}} actions might come in an arbitrary order.

{{Note|{{ic|1=DHCP6_DHCP6_NTP_SERVERS}} with double {{ic|1=DHCP6}} is the correct variable name as varified by {{ic|1=printenv}} as of NetworkManager 1.56.0-1 }}

== Testing ==

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}}.

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.

To start the GNOME applet in non-xdg-compliant window managers like [[awesome]]:

nm-applet --sm-disable &

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'.

== Tips and tricks ==

=== Encrypted Wi-Fi passwords ===

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:

# grep -r '^psk=' /etc/NetworkManager/system-connections/

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}}).

It is preferable to save the passwords in encrypted form in a keyring instead of clear text. The downside to this is that the connections have to be set up for each user.

In order to read and write to the keyring, there must be a secret agent available. This can be one of:

* {{ic|nmcli}} with the {{ic|--ask}} option
* One of the graphical interfaces from [[#Front-ends]]

If you make neither of these available, then authentication will fail with the error {{ic|no secrets: No agents were available for this request.}}

==== Using GNOME Keyring ====

The keyring daemon has to be started and the keyring needs to be unlocked for the following to work.

Furthermore, NetworkManager needs to be configured not to store the password for all users. Using GNOME's {{Pkg|network-manager-applet}}, run {{ic|nm-connection-editor}} from a terminal, select a network connection, click ''Edit'', select the ''Wi-Fi Security'' tab and click on the right icon of password and check ''Store the password only for this user''.

==== Using KDE Wallet ====

Using KDE's {{Pkg|plasma-nm}}, click the applet, click on the top right ''Settings'' icon, click on a network connection, in the ''General configuration'' tab, untick ''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.

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.

=== Sharing internet connection over Wi-Fi ===

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.

You will need a Wi-Fi card which supports AP mode, see [[Software access point#Wi-Fi device must support AP mode]] for details.

[[Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.

Create the shared connection:

* Click on applet and choose ''Create new wireless network''.
* Follow wizard (choose WPA2 or higher, be sure to use at least 8 character long password, lower lengths will fail).
** Choose either [[Fedora:Features/RealHotspot|Hotspot]] or Ad-hoc as Wi-Fi mode.

The connection will be saved and remain stored for the next time you need it.

{{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").}}

=== Sharing internet connection over Ethernet ===

Scenario: your device has internet connection over Wi-Fi and you want to share the internet connection to other devices over Ethernet.

Requirements:

* [[Install]] the {{Pkg|dnsmasq}} and {{Pkg|nm-connection-editor}} packages to be able to actually share the connection. Note that NetworkManager starts its own instance of ''dnsmasq'', independent of {{ic|dnsmasq.service}}, as a DHCP server. See [[#dnsmasq]] for the caveats.
* 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).
* Internet sharing is not blocked by a [[firewall]].

Steps:

* Run {{ic|nm-connection-editor}} from terminal.
* Add a new Ethernet connection.
* Give it some sensible name. For example "Shared Internet"
* Go to "IPv4 Settings".
* For "Method:" select "Shared to other computers".
* Save

Now you should have a new option "Shared Internet" under the Wired connections in NetworkManager.

=== Checking if networking is up inside a cron job or script ===

{{Out of date|''nm-tool'' was removed from NetworkManager for long time now[https://gitlab.freedesktop.org/NetworkManager/NetworkManager/commit/bb8c75bd536d4f8fb80a4366025a279078f0ec81]. ''nmcli'' should be used instead.}}

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.

{{bc|<nowiki>
if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then
#Whatever you want to do if the network is online
else
#Whatever you want to do if the network is offline - note, this and the else above are optional
fi
</nowiki>}}

This is 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.

=== Connect to network with secret on boot ===

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:

# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab
# Select the connection you want to work with and click the Edit button
# Check the boxes “Connect Automatically” and “Available to all users”
# Additionally, ensure that under "Wi-Fi Security", "Store password for all users (not encrypted)" is selected

Log out and log back in to complete.

=== OpenConnect with password in KWallet ===

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]].

Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and
enter your credentials in key "VpnSecrets" in this form (replace ''username'' and ''password'' accordingly):

form:main:username%SEP%''username''%SEP%form:main:password%SEP%''password''

Next time you connect, username and password should appear in the "VPN secrets" dialog box.

=== Ignore specific devices ===

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}}:

[keyfile]
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4;interface-name:eth0

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.

=== Configuring MAC address randomization ===

{{Merge|NetworkManager/Privacy#MAC Randomization|There is a dedicated sub-page for Privacy now.}}

{{Accuracy|The [[iwd]] backend reportedly refuses MAC address randomisation due to open issues, and entry in [[iwd#Troubleshooting]] with link might be suitable to account for it; see:|section=iwd backend doesn't support mac spoofing}}

{{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.}}

{{Note| See [[#Using iwd as the Wi-Fi backend]] for iwd specific MAC randomization.}}

MAC randomization can be used for increased privacy by not disclosing your real MAC address to the network.

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 configuration file may be overwritten by NetworkManager.

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}}:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device]
wifi.scan-rand-mac-address=no
}}

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.

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}}:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device-mac-randomization]
# "yes" is already the default for scanning
wifi.scan-rand-mac-address=yes

[connection-mac-randomization]
# Randomize MAC for every ethernet connection
ethernet.cloned-mac-address=random
# Generate a random MAC for each Wi-Fi and associate the two permanently.
wifi.cloned-mac-address=stable
}}

To configure MAC randomization for a specific connection (for example, if the network does not like random MAC addresses), [[#Edit a connection|edit the connection]] to set {{ic|802-11-wireless.cloned-mac-address}} to one of the modes (e.g. {{ic|stable}} or {{ic|random}}).

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.

=== Turn off hostname sending ===

NetworkManager by default sends the hostname to the DHCP server.

To disable sending your hostname to the DHCP server globally, set the {{ic|ipv4.dhcp-send-hostname{{=}}0}} and {{ic|ipv6.dhcp-send-hostname{{=}}0}} options with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}. E.g.:

{{hc|/etc/NetworkManager/conf.d/dhcp-send-hostname.conf|2=
[connection]
ipv4.dhcp-send-hostname=0
ipv6.dhcp-send-hostname=0
}}

To disable sending your hostname to the DHCP server for a specific connection (or alternatively, enable it for a connection if it is disabled globally), add the following to your network connection file:

{{hc|/etc/NetworkManager/system-connections/''your_connection_file''.nmconnection|2=
...
[ipv4]
dhcp-send-hostname=false
...
[ipv6]
dhcp-send-hostname=false
...
}}

{{Note|These options are only honored by the default [[#DHCP client|internal DHCP client]]. To omit sending the hostname when using NetworkManager with dhcpcd, edit {{ic|/etc/dhcpcd.conf}} and insert {{ic|anonymous}} as the last line.}}

=== Enable IPv6 Privacy Extensions ===

See [[IPv6#NetworkManager]].

=== Configure a unique DUID per connection ===

The DHCPv6 Unique Identifier (DUID) is a value used by the DHCPv6 client to identify itself to DHCPv6 servers. NetworkManager supports 3 types of DUID:

* DUID-UUID ([[RFC:6355|RFC 6355]]): generated from an Universally Unique IDentifier (UUID).
* DUID-LL ([[RFC:3315|RFC 3315]]): generated from the Link-Layer address (a.k.a. MAC address).
* DUID-LLT ([[RFC:3315|RFC 3315]]): generated from the Link-Layer address plus a timestamp.

If the internal NetworkManager's DHCP client is in use (the default) it will identify itself with a global and permanent DUID-UUID generated from the machine-id ({{ic|/etc/machine-id}}). This means that all connections share the same UUID, which may be a privacy breach.

Fortunately, NetworkManager is able to provide unique DUIDs per connection, derived from the connection's stable-id and a per-host unique key. You can enable that by adding the following configuration under {{ic|/etc/NetworkManager/conf.d}}:

{{hc|/etc/NetworkManager/conf.d/duid.conf|2=
[connection]
ipv6.dhcp-duid=stable-uuid
}}

The {{ic|stable-ll}} and {{ic|stable-llt}} values are also supported. For further information read the description for {{ic|dhcp-duid}} in {{man|5|nm-settings|ipv6 setting}}.

=== Working with wired connections ===

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.

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 {{Pkg|nm-connection-editor}} for this task.

=== Using iwd as the Wi-Fi backend ===

{{Note|1=<nowiki/>
* Do not enable {{ic|iwd.service}} or manually configure [[iwd]]. NetworkManager will start and manage it itself.
* Consider [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues?scope=all&utf8=%E2%9C%93&state=opened&search=iwd existing issues] before switching to ''iwd''.}}

To enable the [https://archive.kernel.org/oldwiki/iwd.wiki.kernel.org/networkmanager.html experimental iwd backend], first [[install]] {{Pkg|iwd}} and then create the following configuration file:

{{hc|/etc/NetworkManager/conf.d/wifi_backend.conf|2=
[device]
wifi.backend=iwd
}}

To use MAC randomization with iwd see [[MAC address spoofing#iwd]].

Alternatively, you can install {{AUR|networkmanager-iwd}}, a modified package configured to build ''NetworkManager'' working exclusively with ''iwd'', with the main difference being that ''iwd'' is required and ''wpa_supplicant'' can be uninstalled after building.

{{Note|1=You may need to [https://archive.kernel.org/oldwiki/iwd.wiki.kernel.org/networkmanager.html#converting_network_profiles convert existing NetworkManager network profiles] after switching to ''iwd''.}}

=== Running in a network namespace ===

If you would like to run NetworkManager inside a network namespace (e.g., to manage a specific device which should be used by selected applications), bring the device down before moving it to the namespace:

$ ip link set dev ''MY_DEVICE'' down
$ ip link set dev ''MY_DEVICE'' netns ''MY_NAMESPACE''
$ ip netns exec ''MY_NAMESPACE'' NetworkManager
...
$ ip netns exec ''MY_NAMESPACE'' killall NetworkManager

otherwise NetworkManager will later fail to establish the connection with a {{ic|device is strictly unmanaged}} error.

=== Automatically connect to VPN ===

NetworkManager can be set to automatically connect to a VPN when connecting to the internet, on a per network basis. The VPN connection itself can be added in GNOME's NetworkManager front-end, but to make it automatically use the VPN {{ic|nmcli}} must be used. Other front-ends might not have this limitation.

First, make sure to make the VPN connection available to all users. In the GNOME this is a matter of checking a box under the {{ic|details}} tab. Under the {{ic|Identity}} tab, in the password field, click the icon on the right side in the field, and set it to {{ic|Store the password for all users}}.

Then find the UUID of the VPN connection, and add that to {{ic|connection.secondaries}} of the Internet connection:

# UUID=$(nmcli --get-values connection.uuid connection show ''name-of-VPN-connection'')
# nmcli connection modify ''name-of-Internet-connection'' connection.secondaries "$UUID"

Now when NetworkManager is restarted and you connect to the Internet connection you have configured, you should automatically get connected to the VPN.

== Troubleshooting ==

=== No prompt for password of secured Wi-Fi networks ===

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''.

=== Network management disabled ===

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:

# rm /var/lib/NetworkManager/NetworkManager.state

=== Problems with internal DHCP client ===

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.

=== DHCP problems with dhclient ===

If you have problems with getting an IP address via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:

interface "eth0" {
send dhcp-client-identifier 01:''aa:bb:cc:dd:ee:ff'';
}

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.

=== 3G modem not detected ===

See [[Mobile broadband modem#NetworkManager]].

=== Switching off WLAN on laptops ===

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:

$ watch -n1 rfkill list all

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):

# rfkill event unblock X

=== Static IP address settings revert to DHCP ===

{{Out of date|This section is [[Special:Diff/119236|added in 2010]] and describes an ancient version of ''nm-applet''. Is this still relevant in 2024?}}

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.

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.

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.

=== Cannot edit connections as normal user ===

See [[#Set up PolicyKit permissions]].

=== Forget hidden wireless network ===

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:

# rm /etc/NetworkManager/system-connections/''SSID''.nmconnection

This also works for any other connection.

=== VPN not working in GNOME ===

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}}:

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.

This is caused by the GNOME NetworkManager Applet expecting dialog scripts to be at {{ic|/usr/lib/gnome-shell}}, when NetworkManager's packages put them in {{ic|/usr/lib/networkmanager}}.
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):

* For OpenConnect: {{ic|ln -s /usr/lib/nm-openconnect-auth-dialog /usr/lib/gnome-shell/}}
* For VPNC (i.e. Cisco VPN): {{ic|ln -s /usr/lib/nm-vpnc-auth-dialog /usr/lib/gnome-shell/}}

This may need to be done for any other NetworkManager VPN plugins as well, but these are the two most common.

=== Unable to connect to visible European wireless networks ===

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:

# [[Install]] {{Pkg|wireless-regdb}}.
# Uncomment the correct country code in {{ic|/etc/conf.d/wireless-regdom}}.
# Reboot the system, because the setting is only read on boot.

=== Automatic connect to VPN on boot is not working ===

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.

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]].

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.

=== systemd bottleneck ===

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]].

=== Regular network disconnects, latency and lost packets (Wi-Fi) ===

NetworkManager does a scan every 2 minutes.

Some Wi-Fi 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.

Running {{ic|journalctl -f}} as root will indicate that this is taking place, messages like the following will be contained in the logs at regular intervals.

NetworkManager[410]: <info> (wlp3s0): roamed from BSSID 00:14:48:11:20:CF (my-wifi-name) to (none) ((none))

If roaming is not important, the periodic scanning behavior can be disabled by locking the BSSID of the access point in the Wi-Fi connection profile.

=== Unable to turn on Wi-Fi with Lenovo laptop (IdeaPad, Legion, etc.) ===

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.

{{Accuracy|Try to use {{ic|rfkill.default_state}} and {{ic|rfkill.master_switch_mode}} (see [https://docs.kernel.org/admin-guide/kernel-parameters.html kernel-parameters.html]) to fix the rfkill problem.}}

[[modprobe|Unloading]] the {{ic|ideapad_laptop}} module should fix this. ('''warning''': this may disable the laptop keyboard and touchpad also!).

=== nm-applet disappears in i3wm ===

If you use the {{ic|xfce4-notifyd.service}} for notifications you must [[edit]] the unit and add the following:

{{hc|/etc/systemd/user/xfce4-notifyd.service.d/display_env.conf|2=
[Service]
Environment="DISPLAY=:0.0"
}}

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.

=== Unit dbus-org.freedesktop.resolve1.service not found ===

If {{ic|systemd-resolved.service}} is not started, NetworkManager will try to start it using D-Bus and fail:

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 ")
dbus-daemon[991]: [system] Activation via systemd failed for unit 'dbus-org.freedesktop.resolve1.service': Unit dbus-org.freedesktop.resolve1.service not found.
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 ")

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]

This can be disabled with a configuration file in {{ic|/etc/NetworkManager/conf.d/}}:

{{hc|/etc/NetworkManager/conf.d/no-systemd-resolved.conf|2=
[main]
systemd-resolved=false
}}

See {{Bug|62138}}.

=== Secrets were required, but not provided ===

If you received the following error when attempting to connect to a network:

{{hc|$ nmcli device wifi connect ''SSID'' password ''password''|
Error: Connection activation failed: (7) Secrets were required, but not provided
}}

This error can have numerous causes and you should read the [[journal]] (filter it with {{ic|-u NetworkManager}}). For example, if NetworkManager took too long to establish connection, it will believe that the password is incorrect:

{{bc|
NetworkManager[1372]: <warn> [1643991888.3808] device (wlan0): Activation: (wifi) association took too long
NetworkManager[1372]: <info> [1643991888.3809] device (wlan0): state change: config -> need-auth (reason 'none', sys-iface-state: 'managed')
NetworkManager[1372]: <warn> [1643991888.3838] device (wlan0): Activation: (wifi) asking for new secrets
}}

You can try deleting the connection profile and creating a new one:

$ nmcli connection delete ''SSID''
$ nmcli device wifi connect ''SSID'' password ''password''

You can also try disabling MAC address randomization:

{{hc|/etc/NetworkManager/conf.d/wifi_rand_mac.conf|2=
[device]
wifi.scan-rand-mac-address=no
}}

=== WPA Enterprise connection with iwd ===

If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the [[#Using iwd as the Wi-Fi backend|iwd backend]] then you will get the following error from NetworkManager:

Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)

This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd configuration file {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[iwd#WPA Enterprise]].

=== Failed to request VPN secrets ===

If you get this error:
Failed to request VPN secrets #1: No agents were available for this request.

It is either because the password is empty or you have to [[#Set up PolicyKit permissions|set up PolicyKit permissions]].

=== OpenVPN connections fail with "secrets: failed to request VPN secrets" warn ===

{{Remove|This does not warrant a troubleshooting section. Optional dependencies are pointed out by pacman, if this is not clear enough it should be covered in [[#VPN support]].|section=Remove unnecessary section 8.22}}

The package {{Pkg|networkmanager-openvpn}} requires {{Pkg|libnma-gtk4}} and optionally {{Pkg|libnma}} (Gtk3) when integrated within the GNOME-Shell. If {{Pkg|libnma}} is required but not installed a message will be printed to the system log:

{{bc|
NetworkManager[642]: <warn> [...] vpn[..."name_of_vpn_profile VPN"]: secrets: failed to request VPN secrets #3: No agents were available for this request.
}}

=== OpenVPN connections fail with OpenSSL "ca md too weak" error ===

Since {{Pkg|openssl}} was updated to version 3, certificates generated with legacy cryptographic algorithms are rejected by default. Attempting to use {{Pkg|networkmanager-openvpn}} with such a setup can result in the following error in the logs:

{{bc|
nm-openvpn[14359]: OpenSSL: error:0A00018E:SSL routines::ca md too weak
nm-openvpn[14359]: Cannot load certificate file /home/archie/.local/share/networkmanagement/certificates/my_issued_cert.crt
nm-openvpn[14359]: Exiting due to fatal error
}}

The correct approach is to have the OpenVPN server administrator generate and re-issue more secure certificates. However, as an immediate work-around, OpenVPN requires {{ic|1=tls-cipher "DEFAULT:@SECLEVEL=0"}}. This may not be possible through the plugin GUI, but it is possible with ''nmcli''. Separately, you will also need to enable the ''legacy'' provider in OpenSSL.

Firstly, obtain the name of the VPN connection with the issue, from the output of the following:

$ nmcli connection show

Assuming the connection name is ''vpn.example.com'', use ''nmcli'' like so:

$ nmcli connection modify vpn.example.com +vpn.data tls-cipher=DEFAULT:@SECLEVEL=0

The change should instantly be reflected in {{ic|/etc/NetworkManager/system-connections/vpn.example.com.nmconnection}}.

As for OpenSSL, edit {{ic|/etc/ssl/openssl.cnf}} as described on the [https://wiki.openssl.org/index.php/OpenSSL_3.0#Providers OpenSSL wiki].

Specifically, at the end of the {{ic|[provider_sect]}} section add {{ic|1=legacy = legacy_sect}}. Under {{ic|[default_sect]}} uncomment {{ic|1=activate = 1}}. Lastly, add a new section {{ic|[legacy_sect]}} that also contains the line {{ic|1=activate = 1}}. Excluding most other preexisting configuration sections, the end result will look something like:

{{hc|/etc/ssl/openssl.cnf|2=
openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
legacy = legacy_sect

[default_sect]
activate = 1

[legacy_sect]
activate = 1
}}

Finally, [[restart]] the {{ic|NetworkManager.service}} to have the new OpenSSL configuration take effect.

=== WPA Enterprise connections fail to authenticate with OpenSSL "unsupported protocol" error ===

Since {{Pkg|openssl}} was updated to version 3, "SSL 3, TLS 1.0, TLS 1.1, and DTLS 1.0 only work at security level 0" [https://www.openssl.org/news/openssl-3.0-notes.html by default]. Attempting to authenticate to a Wi-Fi network only supporting older standards results in the following error in the logs:

{{bc|
wpa_supplicant[3320]: SSL: SSL3 alert: write (local SSL3 detected an error):fatal:protocol version
wpa_supplicant[3320]: OpenSSL: openssl_handshake - SSL_connect error:0A000102:SSL routines::unsupported protocol
wpa_supplicant[3320]: wlp3s0: CTRL-EVENT-EAP-FAILURE EAP authentication failed
}}

The correct approach is to convince the institution's administrator to upgrade the encrypted networking tunnel protocol to TLS 1.3 and optionally drop support for deprecated security standards, including TLS 1.0/1.1, DTLS 1.0 and SSL 1-3. However, as an immediate workaround, there are multiple ways to allow TLS 1.0 and/or 1.1 by default. One way would be to manually patch or revert the breaking changes in OpenSSL ([https://github.com/openssl/openssl/commit/7bf2e4d7f0c7ae19b7a8c416910886a7171e9820]). As this also lowers security for all other programs using OpenSSL level 1, it is not recommended. Instead, one can directly set the level used by wpa_supplicant, like described in [https://bbs.archlinux.org/viewtopic.php?id=286417#p2104492 BBS#286417]. To only change the affected connection, it is possible to set {{ic|1=phase1-auth-flags=32}} or {{ic|1=phase1-auth-flags=64}} in the {{ic|1=[802-1x]}} section of the connection's configuration file. This may not be possible through GUIs, but it is possible with ''nmcli''.

Firstly, obtain the name of the Wi-Fi connection with the issue, from the output of the following:

$ nmcli connection show

Assuming the connection uses TLS 1.0 and its name is ''Example Wi-Fi'', use ''nmcli'' like so:

$ nmcli connection modify 'Example Wi-Fi' 802-1x.phase1-auth-flags 32

And for a TLS 1.1 connection, type "64" instead:

$ nmcli connection modify 'Example Wi-Fi' 802-1x.phase1-auth-flags 64

{{Note|1=The number you type in refers to the number you get from raising 2 to the power of '''n'''. Here, '''n''' is the index of the network authentication bit octet, read from right to left. Flipping the fifth bit enables TLS 1.0 '''[log(2) 32]''' and flipping the sixth bit enables TLS 1.1 '''[log(2) 64]'''.}}

The change should instantly be reflected in {{ic|/etc/NetworkManager/system-connections/Example Wi-Fi.nmconnection}}.

Finally, [[restart]] the {{ic|NetworkManager.service}} to have the new OpenSSL configuration take effect.

== See also ==

* [https://blogs.gnome.org/dcbw/2015/02/16/networkmanager-for-administrators-part-1/ NetworkManager for Administrators Part 1]

GNOME

2026-05-07T15:00:37Z

Indigo: /* Device Security Settings */ remove old release number; apply sentence case to section and update menu path

[[Category:GNOME]]
[[cs:GNOME]]
[[de:GNOME]]
[[es:GNOME]]
[[it:GNOME]]
[[hu:GNOME]]
[[ja:GNOME]]
[[pt:GNOME]]
[[ru:GNOME]]
[[zh-hans:GNOME]]
{{Related articles start}}
{{Related|Desktop environment}}
{{Related|GTK}}
{{Related|GDM}}
{{Related|GNOME/Tips and tricks}}
{{Related|GNOME/Troubleshooting}}
{{Related|GNOME/Files}}
{{Related|GNOME/Gedit}}
{{Related|GNOME/Web}}
{{Related|GNOME/Evolution}}
{{Related|GNOME/Flashback}}
{{Related|GNOME/Keyring}}
{{Related|GNOME/Document viewer}}
{{Related|Official repositories#gnome-unstable}}
{{Related articles end}}

[[Wikipedia:GNOME|GNOME]] (/(ɡ)noʊm/) is a [[desktop environment]] that aims to be simple and easy to use. It is designed by [[Wikipedia:The GNOME Project|The GNOME Project]] and is composed entirely of free and open-source software. It uses [[Wayland]], and the available sessions are

* '''GNOME''', the default, runs GNOME Shell on [[Wayland]]. Traditional X applications are run through Xwayland.
* '''GNOME Classic''' provides a "[https://help.gnome.org/users/gnome-help/stable/gnome-classic.html.en traditional desktop experience]" (with an interface similar to GNOME 2) by using [https://web.archive.org/web/20190503163814/http://www.worldofgnome.org/welcome-to-gnome-3-8-flintstones-mode/ certain extensions and values]. Thus, it is a customized form of GNOME Shell rather than a truly distinct mode.

== Installation ==

The following [[package group]]s are available:

* {{Grp|gnome}} contains the base GNOME desktop and the well-integrated [https://apps.gnome.org/#core core applications];
* {{Grp|gnome-circle}} contains various [https://apps.gnome.org/#circle extra applications] extending the GNOME ecosystem.
* {{Grp|gnome-extra}} contains [https://apps.gnome.org/#development development tools] as well as some further applications and games that fits well into GNOME.

The base desktop consists of [[Wikipedia:GNOME Shell|GNOME Shell]], a plugin for the [[Wikipedia:Mutter (software)|Mutter]] window manager. It can be installed separately with {{Pkg|gnome-shell}}.

{{Note|''mutter'' acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter. The GNOME session manager automatically detects if your video driver is capable of running GNOME Shell and if not, falls back to software rendering using ''llvmpipe''.}}

Unstable releases can also be used, see [[Official repositories#gnome-unstable]].

== Starting ==

GNOME can be started either graphically with a [[display manager]] or manually from the console (some features may be missing). The display manager included in {{Grp|gnome}} is [[GDM]].

{{Note|Support for screen locking (and more) in GNOME is provided by GDM. If GNOME is not started with GDM, another screen locker may be used. See [[List of applications/Security#Screen lockers]].}}

=== Graphically ===

If you installed the {{Grp|gnome}} group and want GNOME to start automatically on next boot, [[enable]] {{ic|gdm.service}}. You can then select the desired session: ''GNOME'' or ''GNOME Classic'' (only displayed if {{Pkg|gnome-shell-extensions}} is installed) from the display manager's session menu.

If you prefer to start GNOME right away, thereby avoiding a reboot, [[start]] the aforementioned {{ic|gdm.service}} from a graphically unoccupied tty instead.

=== Manually ===

{{Note|An X server is still necessary to run applications that have not yet been ported to [[Wayland]], see [[Wayland#Xwayland]] for details. Applications using certain graphics libraries, such as Qt, can be forced to use Wayland by setting environment variables. See [[Wayland#GUI libraries]] for more information.}}

==== Session type ====

GNOME session inherits session type from systemd. Systemd session type is determined from {{ic|XDG_SESSION_TYPE}} environment variable when the session is started, and can only be changed by the controller of that session afterwards. See the systemd issue on [https://github.com/systemd/systemd/issues/14489 Github].

Therefore merely setting {{ic|XDG_SESSION_TYPE}} after login does not work. Instead, create a systemd drop-in file to set environment for getty :

{{hc|/etc/systemd/system/getty@tty1.service.d/wayland.conf
|<nowiki>
[Service]
Environment=XDG_SESSION_TYPE=wayland
</nowiki>}}

To show session type after reload:
$ loginctl session-status

==== Start session ====

After {{ic|XDG_SESSION_TYPE}} and login session type is set correctly, manually starting a Wayland session is possible with:
$ gnome-session

Running {{ic|gnome-shell --wayland}} directly is not recommended, because it lacks session management.

Note that manual invocation of Gnome does '''not''' require {{ic|gdm}} (consequently also the accompanying {{ic|gdm.service}}) at all and is thus also accessible for users with a (possibly very) minimal installation of Gnome composing of a selected few packages included in the more inclusive {{ic|gnome}} group in accordance to personal preference.

To start on login to tty1, add to your {{ic|.bash_profile}}:
{{bc|<nowiki>
gnome-session --no-reexec
</nowiki>}}
The {{ic|--no-reexec}} flag prevents gnome-session from starting a login shell which sources the profile again and loops.

Firefox and QT applications do not respect {{ic|XDG_SESSION_TYPE}}, so add variables for them as well:

{{bc|<nowiki>
if [[ -z $DISPLAY && $(tty) == /dev/tty1 && $XDG_SESSION_TYPE == wayland ]]; then
MOZ_ENABLE_WAYLAND=1 QT_QPA_PLATFORM=wayland exec gnome-session --no-reexec
fi
</nowiki>}}

=== GNOME applications in Wayland ===

When the ''GNOME'' session is used, GNOME applications will be run using Wayland. For debugging cases, https://docs.gtk.org/gtk3/running.html and https://docs.gtk.org/gtk4/running.html list options and environment variables.

== Navigation ==

To learn how to use the GNOME shell effectively, read the [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]; it highlights GNOME shell features and keyboard shortcuts. Features include task switching, keyboard use, window control, the panel, overview mode, and more. A few of the shortcuts are:

* {{ic|Super+m}}: show notification list
* {{ic|Super+a}}: show application grid
* {{ic|Alt+Tab}}: cycle active applications
* {{ic|Alt+`}} (the key above {{ic|Tab}} on US keyboard layouts): cycle windows of the application in the foreground
* {{ic|Alt+F2}}, then enter {{ic|r}} or {{ic|restart}}: restart the shell in case of graphical shell problems (only in X/legacy mode, not in Wayland mode).

See [[/Tips and tricks#Navigation]] for changes to the default configuration making the window-switching resemble that of Windows.

See [https://help.gnome.org/users/gnome-help/stable/keyboard-nav.html.en Keyboard navigation] for more shortcuts.

== Legacy names ==

{{Note|Some GNOME programs have undergone name changes where the application's name in documentation and about dialogs has been changed but the executable name has not. A few such applications are listed in the table below.}}

{{Tip|Searching for the legacy name of an application in the Shell search bar will successfully return the application in question. For instance, searching for ''nautilus'' will return ''Files''.}}

{| class="wikitable"
! Legacy
! Current
|-
| Baobab
| Disk Usage Analyzer
|-
| Decibels
| Audio Player
|-
| Epiphany
| [[GNOME/Web|Web]]
|-
| Loupe
| Image Viewer
|-
| Nautilus
| [[GNOME/Files|Files]]
|-
| Papers
| Document Viewer
|-
| Showtime
| Video Player
|-
| Simple Scan
| Document Scanner
|-
| Snapshot
| Camera
|}

== Configuration ==

GNOME Settings (''gnome-control-center'') and GNOME applications use the [[wikipedia:Dconf|dconf]] configuration system to store their settings.

You can directly access the dconf database using the {{man|1|gsettings}} command line tool. This also allows you to configure settings not exposed by the user interfaces. Command line tool {{man|1|dconf}} can directly modify the underlying database, bypassing validation. The configuration keys of gsettings and dconf are equivalent, but in a slightly different format: {{ic|gsettings set mygroup.mysubgroup mysetting myvalue}} in gsettings would be {{ic|dconf write /mygroup/mysubgroup/mysetting myvalue}} in dconf.

Up until GNOME 3.24, settings were applied by the GNOME settings daemon (located at {{ic|/usr/lib/gnome-settings-daemon/gnome-settings-daemon}}), which could be run outside of a GNOME session.

GNOME 3.24, however, replaced the GNOME settings daemon with several separate settings plugins {{ic|/usr/lib/gnome-settings-daemon/gsd-*}} which were later moved to {{ic|/usr/lib/gsd-*}}. These plugins are now controlled via desktop files under {{ic|/etc/xdg/autostart/}} (matching {{ic|org.gnome.SettingsDaemon.*.desktop}}). To run these plugins outside of a GNOME session, you will now need to copy/edit the appropriate [[desktop entries]] to {{ic|~/.config/autostart}}.

The configuration is usually performed user-specific; this section does not cover how to create configuration templates for multiple users.

=== System settings ===

==== Color ====

The daemon {{ic|colord}} reads the display's EDID and extracts the appropriate color profile. Most color profiles are accurate and no setup is required; however, for those that are not accurate, or for older displays, color profiles can be put in {{ic|~/.local/share/icc/}} and directed to.

==== Night Light ====

GNOME comes with a built-in blue light filter similar to [[Redshift]]. You can enable and customise the time you want to enable Night Light from the display settings menu. Furthermore, you can tweak the kelvin temperature with the following {{Pkg|dconf}} setting, where 5000 is an example value:

$ gsettings set org.gnome.settings-daemon.plugins.color night-light-temperature 5000

{{Tip|To change the daytime temperature in a Wayland session, install the [https://extensions.gnome.org/extension/1276/night-light-slider/ Night Light Slider extension].}}
{{Note| Night Light works on NVIDIA cards in Wayland sessions since version 545.29.02 }}

==== Date & time ====

If the system has a configured [[Network Time Protocol daemon]], it will be effective for GNOME as well. The synchronization can be set to manual control from the menu, if required.

GNOME supports automatic time zone selection (can be enabled in ''Date & Time'' section of the system settings, given that location services are enabled (see ''Privacy'' section of the settings).

{{Note|Automatic time zone selection might not work anymore because of the retirement of Mozilla Location Services. See [https://gitlab.gnome.org/GNOME/gnome-settings-daemon/-/issues/841#note_2300635]. For workarounds see [[System time#Setting based on geolocation]].}}

To show the date in the top bar, execute:

$ gsettings set org.gnome.desktop.interface clock-show-date true

Additionally, to show week numbers in the calendar opened on the top bar, execute:

$ gsettings set org.gnome.desktop.calendar show-weekdate true

==== Default applications ====

Upon installing GNOME for the first time, you may find that the wrong applications are handling certain protocols. For example, ''totem'' opens videos instead of a previously used [[VLC]]. Some of the associations can be set from system settings via ''Default Applications''.

For other protocols and methods, see [[Default applications]] for configuration.

==== Mouse and touchpad ====

Most touchpad settings can be set from system settings via ''Mouse & Touchpad''.

Depending on your device, other configuration settings may be available, but not exposed via the default GUI. For example, a different touchpad {{ic|click-method}}

{{hc|$ gsettings range org.gnome.desktop.peripherals.touchpad click-method|
enum
'default'
'none'
'areas'
'fingers'
}}

to be set manually:

$ gsettings set org.gnome.desktop.peripherals.touchpad click-method 'fingers'

or via {{Pkg|gnome-tweaks}}.

{{Note|1=The [[synaptics]] driver is not supported by GNOME. Instead, you should use [[libinput]]. See [https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12 this bug report].}}

===== Resize windows by mouse =====

By default, you can use your mouse to move windows by holding down {{ic|Super}}, clicking and holding the left mouse button and dragging the mouse around.

Additionally, you can enable using your mouse to resize windows by holding down {{ic|Super}}, clicking and holding the right mouse button and dragging the mouse around:

$ gsettings set org.gnome.desktop.wm.preferences resize-with-right-button true

If you don't like the {{ic|Super}} key, you can also change the modifier to something else, like {{ic|Alt}} or {{ic|Ctrl}}:

$ gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier "'<Alt>'"

==== Network ====

[[NetworkManager]] is the native tool of the GNOME project to control network settings from the shell. If you have not already, [[install]] the {{Pkg|networkmanager}} package and [[enable]] the {{ic|NetworkManager.service}} systemd unit.

While any other [[network manager]] can be used alternatively, NetworkManager provides the full integration via the shell network settings and a status indicator applet {{Pkg|network-manager-applet}} (not required for GNOME).

{{Note|1=Hidden wireless networks set up with {{Pkg|networkmanager}}'s ''nmtui'' do not connect automatically. You need to create a new profile using GNOME control center in order to restore auto-connect capabilities for that network.}}

==== Online accounts ====

Some online accounts, such as [[Nextcloud]], require {{Pkg|gvfs-goa}} and {{Pkg|gvfs-dnssd}} to be installed for full functionality in GNOME applications such as [[GNOME Files]] and GNOME Documents [https://wiki.gnome.org/ThreePointSeven/Features/Owncloud].

See [https://help.gnome.org/users/gnome-help/stable/accounts.html.en Online accounts] for more information.

==== Search ====

The GNOME shell has a search that can be quickly accessed by pressing the {{ic|Super}} key and starting to type. The {{Pkg|localsearch}} package is installed by default as a dependency of {{Pkg|nautilus}} from the {{Grp|gnome}} group and provides an indexing application and metadata database. It can be configured with the ''Search'' menu item in ''Settings''. It is started automatically by ''gnome-session'' when the user logs in.

localsearch does not automatically recurse into all directories under the user's home directory, so you may need to add custom paths via the ''Search > Search locations'' menu item. To exclude a directory from the indexing, create an empty {{ic|.nomedia}} file.

A status is available with {{ic|localsearch status}} and the indexed content can be searched ({{ic|localsearch search --help}}), edited ({{ic|localsearch tag --help}}), or reset from the commandline. See {{ic|localsearch help}} and {{ic|localsearch ''command'' --help}}, or the [https://gnome.pages.gitlab.gnome.org/localsearch/commandline.html online help] for reference.

The database uses {{man|1|tinysparql-sql}} and can also be queried directly, if needed.

==== Accessibility ====

GNOME has accessibility settings available via ''Settings > Accessibility''. The main settings may be toggled directly after enabling a top bar icon, but note further settings are available via the sub-menus for ''Seeing'', ''Hearing'', ''Typing'', ''Pointing and clicking'' and ''Zoom''. See https://help.gnome.org/users/gnome-help/stable/a11y.html.en for information on them.

Additionally, a default set of keyboard shortcuts can be set via ''Settings > Keyboard > View and Customize Keyboard Shortcuts > Accessibility''. For example, pressing {{ic|Alt}}, {{ic|Super}} and {{ic|8}} toggles zooming.

==== Device security settings ====

GNOME has a [https://release.gnome.org/43/ Device Security] panel via the ''Settings > Privacy & Security > Device Security'' menu. This requires {{Pkg|fwupd}} in order to function.[https://gitlab.gnome.org/GNOME/gnome-control-center/-/issues/2122]

=== Advanced settings ===

As noted above, many configuration options such as changing the [[GTK]] theme or the [[window manager]] theme are not exposed in GNOME Settings (''gnome-control-center''). Those users that want to configure these settings may wish to use the GNOME Tweaks ({{Pkg|gnome-tweaks}}), a convenient graphical tool which exposes many of these settings.

GNOME settings (which are stored in the DConf database) can also be configured using the {{Pkg|dconf-editor}} (a graphical DConf configuration tool) or the [https://developer.gnome.org/gio/stable/GSettings.html gsettings] command line tool. The GNOME Tweaks does not do anything else in the background of the GUI; note though that you will not find all settings described in the following sections in it.

==== Extensions ====

The catalogue of extensions is available at https://extensions.gnome.org, they can be installed either through [https://archlinux.org/packages/?q=gnome-shell-extension official repositories] (only a few), [https://aur.archlinux.org/packages?K=gnome-shell-extension the AUR] or through [https://extensions.gnome.org the browser] directly from the GNOME project.

{{Note|
* Installing extensions through the browser makes them available for the current user only and requires you to handle updates the same way. Install {{Pkg|gnome-browser-connector}} first for this option.
* Installing extensions through the AUR (or through official repositories, if you find them there) makes them available system-wide (and automates the update process if using an [[AUR helper]]).
}}

Installed extensions can also be configured, enabled or disabled through a GUI with ''gnome-extensions-app'', from the command line with {{man|1|gnome-extensions}}, or from the browser. In your browser, extensions can be installed then activated in the browser by setting the switch in right top right of the screen to '''ON''' and clicking '''Install''' on the popup window (if the extension in question is not installed). Installed extensions may be seen at https://extensions.gnome.org/local/, where available updates can be checked.

The {{Pkg|gnome-shell-extensions}} package provides a set of very useful extensions maintained as part of the GNOME project.

{{Pkg|extension-manager}} is a graphical tool which can also be used to install and remove extensions, as well as enable and disable them, both system-wide and for a user. Prior to using it, consider its [https://github.com/mjakeman/extension-manager/labels/bug list of known issues].

To enable usage of extensions (disabled by default):

$ gsettings set org.gnome.shell disable-user-extensions false

To list currently enabled extensions:

$ gsettings get org.gnome.shell enabled-extensions

The above command may list extensions that have been removed. To only list extensions that are enabled ''and'' installed, use ''gnome-extensions'' instead:

$ gnome-extensions list --enabled

For more information about GNOME shell extensions, see https://extensions.gnome.org/about/.

==== Appearance ====

===== Themes =====

{{Note|As of [https://release.gnome.org/42/ Gnome 42], many default Gnome applications use GTK 4 with libadwaita. These apps do not currently support changing themes through gsettings or {{pkg|gnome-tweaks}}, the only visual configuration available is through Settings > Appearance. See [[GTK#Themes]] for setting a GTK theme other than Adwaita or Adwaita-dark.}}

GNOME uses Adwaita by default. To apply Adwaita-dark only to GTK 2 applications, use the following symlink:

$ ln -s /usr/share/themes/Adwaita-dark ~/.themes/Adwaita

{{Note|The Adwaita-dark theme is provided by {{Pkg|gnome-themes-extra}} which may not be installed on a minimal installation of GNOME.}}

To select new themes (move them to the appropriate directory and) use GNOME Tweaks or the GSettings commands below.

For the GTK theme:

$ gsettings set org.gnome.desktop.interface gtk-theme ''theme-name''

For the icon theme:

$ gsettings set org.gnome.desktop.interface icon-theme ''theme-name''

{{Note|The window manager theme follows the GTK theme. Using {{ic|org.gnome.desktop.wm.preferences theme}} is deprecated and ignored.}}

See [[GTK#Themes]] and [[Icons#Icon themes]].

===== Titlebar button order =====

To set the order for the GNOME window manager (Mutter, Metacity):

$ gsettings set org.gnome.desktop.wm.preferences button-layout ':minimize,maximize,close'

{{Tip|The colon indicates which side of the titlebar the window buttons will appear.}}

===== GNOME Shell themes =====

The theme of GNOME Shell itself is configurable. To use a Shell theme, firstly ensure that you have the {{Pkg|gnome-shell-extensions}} package installed. Then enable the ''User Themes'' extension, either through the GNOME Extensions application or through the [https://extensions.gnome.org GNOME Shell Extensions] webpage. Shell themes can then be loaded and selected using GNOME Extensions.

There are a number of GNOME Shell themes available [https://aur.archlinux.org/packages?K=gtk+theme in the AUR], many themes do not have the same name format, so instead try searching for the appropriate theme in the AUR. Shell themes can also be downloaded from [https://gnome-look.org/ gnome-look.org].

===== AppIndicators/Top bar icons =====

To enable AppIndicators, which is useful for controlling/monitoring certain applications running in the background, Install {{Pkg|gnome-shell-extension-appindicator}} or {{AUR|gnome-shell-extension-appindicator-git}}, [[#Navigation|restart the GNOME Shell]], then enable the AppIndicator extension in the GNOME Extensions application or by running

$ gnome-extensions enable $(gnome-extensions list {{!}} grep -m 1 appindicatorsupport)

===== Shell animation speed =====

The GNOME shell animation can be sped up, slowed down or disabled. See [[GNOME/Tips and tricks#Change animation speed]].

===== Shell blur =====

Blur my Shell is an extension that adds blur effects to the overview screen as well as the shell itself and other apps. Install {{AUR|gnome-shell-extension-blur-my-shell}} or {{AUR|gnome-shell-extension-blur-my-shell-git}} for development updates. This extension is highly customizable, and you may choose to blur certain applications.

===== Better Alt-Tab Functionality =====

The default Alt-Tab in GNOME is very simple and does not show overviews of the selected windows. You can change the Alt-Tab shortcut from "Switch Applications" to "Switch Windows" in Settings to show window overviews.

You can also use Coverflow Alt-Tab. It is an extension that expands the Alt-Tab behavior and adds features to make switching between applications easier while also giving it a better look. Install {{AUR|gnome-shell-extension-coverflow-alt-tab-git}}, then you may change the configuration of this extension to your liking.

Note: Super-` provides "Switch windows of an application` by default.

==== Autostart ====

GNOME implements [[XDG Autostart]].

The {{Pkg|gnome-tweaks}} allows managing autostart-entries.

{{Tip|1=If the plus sign button in the Tweaks's Startup Applications section is unresponsive, try starting the Tweaks from the terminal using the following command: {{ic|gnome-tweaks}}. See the following [https://bbs.archlinux.org/viewtopic.php?pid=1413631#p1413631 forum thread].}}

==== Desktop ====

===== Dash to Dock =====

To move the dash out of the overview and turn it into a dock to easily launch and switch applications, [[install]] {{AUR|gnome-shell-extension-dash-to-dock}}.

===== Startup in Overview Mode =====

Starting from GNOME 40, the desktop will start directly into Overview Mode instead of an empty desktop (like in previous versions). To mimic legacy behaviour, one may [[install]] {{AUR|gnome-shell-extension-no-overview}}.

Alternatively, you can disable it using gsettings if using {{AUR|gnome-shell-extension-dash-to-dock}}:

$ gsettings set org.gnome.shell.extensions.dash-to-dock disable-overview-on-startup true

See the discussion at [https://discourse.gnome.org/t/gnome-40-login-is-to-the-activities-overview-mode-how-do-you-disable-this/5783].

==== Clipboard history ====

Unlike other desktop environments, GNOME does not have a built-in tool to manage the clipboard history. This can be done however with the help of an extension. Install {{AUR|gnome-shell-extension-clipboard-indicator}}.

==== Weather ====

To display the current weather information in the top panel based on a chosen location, install {{AUR|gnome-shell-extension-openweather}}. The weather information is updated in real-time and displays useful data such as conditions, wind speed, pressure, etc...

==== Sound input/output device selector ====
{{Remove|Probably not needed anymore. [https://github.com/kgshank/gse-sound-output-device-chooser Packages compatible] up to Gnome 43 only.}}
By default, if you want to change your sound input or output device or change your microphone's volume, you need to open GNOME Control Center and configure these settings from there. To integrate a device selector and a microphone volume slider, install {{AUR|gnome-shell-extension-sound-output-device-chooser}} or {{AUR|gnome-shell-extension-sound-output-device-chooser-git}}. Further configuration can be done after installation.

==== Fonts ====

{{Tip|If you set the ''Scaling factor'' to a value above 1.00, the Accessibility menu will be automatically enabled.}}

Fonts can be set for Window titles, Interface (applications), Documents and Monospace. See the Fonts tab in the Tweaks for the relevant options.

For hinting, RGBA will likely be desired as this fits most monitors types, and if fonts appear too blocked reduce hinting to ''Slight'' or ''None''.

==== Input methods ====

GNOME has integrated support for [[input method]]s through [[IBus]]. Only {{Pkg|ibus}} and the wanted input method engine (e.g. {{Pkg|ibus-libpinyin}} for Intelligent Pinyin) needed to be installed. After installation, the input method engine can be added as a keyboard layout under ''Keyboard > Input Sources'' in GNOME Settings (''gnome-control-center'').

==== Keyboard Layout quirks ====

If you are using an alternative keyboard layout like Neo2 which uses multiple layers/modifiers, you might need to go to ''Keyboard > Type Special Characters'' in GNOME Settings (''gnome-control-center'') and change the ''Alternate Characters Key'' away from ''Right Alt'' so that it can be used as a native modifier of the keyboard layout. Setting it to e.g. ''Left Alt'' prevents ''Alt+Tab'', so be careful what you change it to.
Without this change, your left ''Mod3'' key might work, but the right one (''AltGr'') does not. (As of 2021-05-18)

==== Power ====

When you are using a laptop, you might want to alter the following settings controlling behavior when idle, screen lock power button presses and lid close:

$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout ''3600''
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type ''hibernate''
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-timeout ''1800''
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-type ''hibernate''
$ gsettings set org.gnome.settings-daemon.plugins.power power-button-action ''suspend''
$ gsettings set org.gnome.desktop.lockdown disable-lock-screen ''true''

To keep the monitor active when the lid is closed:

$ gsettings set org.gnome.settings-daemon.plugins.xrandr default-monitors-setup do-nothing

GNOME 3.24 deprecated the following settings:

org.gnome.settings-daemon.plugins.power button-hibernate
org.gnome.settings-daemon.plugins.power button-power
org.gnome.settings-daemon.plugins.power button-sleep
org.gnome.settings-daemon.plugins.power button-suspend
org.gnome.settings-daemon.plugins.power critical-battery-action

===== Do not suspend when laptop lid is closed =====

The settings panel of GNOME does not provide an option for the user to change the action triggered when the laptop lid is closed. To change the lid switch action system-wide, edit the systemd settings in {{ic|/etc/systemd/logind.conf}}. To turn off suspend on lid close, set {{ic|1=HandleLidSwitch=ignore}}, as described in [[Power management#ACPI events]].

===== Change critical battery level action =====

The settings panel does not provide an option for changing the critical battery level action. These settings have been removed from dconf as well. They are now managed by upower. Edit the upower settings in {{ic|/etc/UPower/UPower.conf}}. Find these settings and adjust to your needs.

{{hc|head=/etc/UPower/UPower.conf|output=
PercentageLow=10
PercentageCritical=3
PercentageAction=2
CriticalPowerAction=HybridSleep
}}

===== Power modes =====

Install the [[power-profiles-daemon]] optional dependency (of {{Pkg|gnome-control-center}}) for power profiles support. Explicitly [[starting/enabling]] the {{ic|power-profiles-daemon}} service is unnecessary since ''gnome-shell'' and GNOME Settings both request its activation upon launching.

When the service is active, power profiles can be managed through the ''Power'' section of GNOME Settings and in the system menu.

==== Screencast ====

The built-in screenshot tool comes without the Screencast option by default. Install the {{Pkg|gst-plugin-pipewire}} optional dependency (of {{Pkg|gnome-shell}}) to enable screen recording.

=== Use a different window manager ===

GNOME Shell does not support using a different [[window manager]], however [[GNOME Flashback]] provides sessions for Metacity and [[Compiz]]. Furthermore, it is possible to define your own [[GNOME/Tips and tricks#Custom GNOME sessions|custom GNOME sessions]] which use alternative components.

Replacing GNOME Shell with a different [[Wayland compositor]] will cause certain sections of {{Pkg|gnome-control-center}} (GNOME Settings) to populate incorrectly. ''gnome-control-center'' will work, but since {{Pkg|mutter}} (GNOME Shell) will not be available to provide settings for populating these sections, they will not have an effect or may not populate accurately with your settings. Sections affected are bluetooth, display, and mouse/touchpad to name a few.

== See also ==

* [https://www.gnome.org/ Official Website]
* [https://blogs.gnome.org/tbernard/2021/06/15/community-power-2/ Contributing to GNOME, feature requests, bugs, code]
* [[Wikipedia:GNOME|Wikipedia article]]
* [https://extensions.gnome.org/ GNOME-Shell Extensions]
* [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]
* Customization (themes, icons...):
** [https://wiki.gnome.org/Personalization Personalize GNOME]
** [https://www.gnome-look.org/ GNOME Look]
* GNOME applications:
** [https://wiki.gnome.org/Apps GNOME Apps Index]
** [[Wikipedia:GNOME Core Applications]]
* GNOME Source/Mirrors:
** [https://gitlab.gnome.org/ GNOME GitLab]
** [https://github.com/GNOME GNOME Github Mirror]

GNOME

2026-05-07T14:52:08Z

Indigo: /* Extensions */ handle accuracy template by condensing note and remove template; "easier" can apply to both, depending on what a user seeks; done

[[Category:GNOME]]
[[cs:GNOME]]
[[de:GNOME]]
[[es:GNOME]]
[[it:GNOME]]
[[hu:GNOME]]
[[ja:GNOME]]
[[pt:GNOME]]
[[ru:GNOME]]
[[zh-hans:GNOME]]
{{Related articles start}}
{{Related|Desktop environment}}
{{Related|GTK}}
{{Related|GDM}}
{{Related|GNOME/Tips and tricks}}
{{Related|GNOME/Troubleshooting}}
{{Related|GNOME/Files}}
{{Related|GNOME/Gedit}}
{{Related|GNOME/Web}}
{{Related|GNOME/Evolution}}
{{Related|GNOME/Flashback}}
{{Related|GNOME/Keyring}}
{{Related|GNOME/Document viewer}}
{{Related|Official repositories#gnome-unstable}}
{{Related articles end}}

[[Wikipedia:GNOME|GNOME]] (/(ɡ)noʊm/) is a [[desktop environment]] that aims to be simple and easy to use. It is designed by [[Wikipedia:The GNOME Project|The GNOME Project]] and is composed entirely of free and open-source software. It uses [[Wayland]], and the available sessions are

* '''GNOME''', the default, runs GNOME Shell on [[Wayland]]. Traditional X applications are run through Xwayland.
* '''GNOME Classic''' provides a "[https://help.gnome.org/users/gnome-help/stable/gnome-classic.html.en traditional desktop experience]" (with an interface similar to GNOME 2) by using [https://web.archive.org/web/20190503163814/http://www.worldofgnome.org/welcome-to-gnome-3-8-flintstones-mode/ certain extensions and values]. Thus, it is a customized form of GNOME Shell rather than a truly distinct mode.

== Installation ==

The following [[package group]]s are available:

* {{Grp|gnome}} contains the base GNOME desktop and the well-integrated [https://apps.gnome.org/#core core applications];
* {{Grp|gnome-circle}} contains various [https://apps.gnome.org/#circle extra applications] extending the GNOME ecosystem.
* {{Grp|gnome-extra}} contains [https://apps.gnome.org/#development development tools] as well as some further applications and games that fits well into GNOME.

The base desktop consists of [[Wikipedia:GNOME Shell|GNOME Shell]], a plugin for the [[Wikipedia:Mutter (software)|Mutter]] window manager. It can be installed separately with {{Pkg|gnome-shell}}.

{{Note|''mutter'' acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter. The GNOME session manager automatically detects if your video driver is capable of running GNOME Shell and if not, falls back to software rendering using ''llvmpipe''.}}

Unstable releases can also be used, see [[Official repositories#gnome-unstable]].

== Starting ==

GNOME can be started either graphically with a [[display manager]] or manually from the console (some features may be missing). The display manager included in {{Grp|gnome}} is [[GDM]].

{{Note|Support for screen locking (and more) in GNOME is provided by GDM. If GNOME is not started with GDM, another screen locker may be used. See [[List of applications/Security#Screen lockers]].}}

=== Graphically ===

If you installed the {{Grp|gnome}} group and want GNOME to start automatically on next boot, [[enable]] {{ic|gdm.service}}. You can then select the desired session: ''GNOME'' or ''GNOME Classic'' (only displayed if {{Pkg|gnome-shell-extensions}} is installed) from the display manager's session menu.

If you prefer to start GNOME right away, thereby avoiding a reboot, [[start]] the aforementioned {{ic|gdm.service}} from a graphically unoccupied tty instead.

=== Manually ===

{{Note|An X server is still necessary to run applications that have not yet been ported to [[Wayland]], see [[Wayland#Xwayland]] for details. Applications using certain graphics libraries, such as Qt, can be forced to use Wayland by setting environment variables. See [[Wayland#GUI libraries]] for more information.}}

==== Session type ====

GNOME session inherits session type from systemd. Systemd session type is determined from {{ic|XDG_SESSION_TYPE}} environment variable when the session is started, and can only be changed by the controller of that session afterwards. See the systemd issue on [https://github.com/systemd/systemd/issues/14489 Github].

Therefore merely setting {{ic|XDG_SESSION_TYPE}} after login does not work. Instead, create a systemd drop-in file to set environment for getty :

{{hc|/etc/systemd/system/getty@tty1.service.d/wayland.conf
|<nowiki>
[Service]
Environment=XDG_SESSION_TYPE=wayland
</nowiki>}}

To show session type after reload:
$ loginctl session-status

==== Start session ====

After {{ic|XDG_SESSION_TYPE}} and login session type is set correctly, manually starting a Wayland session is possible with:
$ gnome-session

Running {{ic|gnome-shell --wayland}} directly is not recommended, because it lacks session management.

Note that manual invocation of Gnome does '''not''' require {{ic|gdm}} (consequently also the accompanying {{ic|gdm.service}}) at all and is thus also accessible for users with a (possibly very) minimal installation of Gnome composing of a selected few packages included in the more inclusive {{ic|gnome}} group in accordance to personal preference.

To start on login to tty1, add to your {{ic|.bash_profile}}:
{{bc|<nowiki>
gnome-session --no-reexec
</nowiki>}}
The {{ic|--no-reexec}} flag prevents gnome-session from starting a login shell which sources the profile again and loops.

Firefox and QT applications do not respect {{ic|XDG_SESSION_TYPE}}, so add variables for them as well:

{{bc|<nowiki>
if [[ -z $DISPLAY && $(tty) == /dev/tty1 && $XDG_SESSION_TYPE == wayland ]]; then
MOZ_ENABLE_WAYLAND=1 QT_QPA_PLATFORM=wayland exec gnome-session --no-reexec
fi
</nowiki>}}

=== GNOME applications in Wayland ===

When the ''GNOME'' session is used, GNOME applications will be run using Wayland. For debugging cases, https://docs.gtk.org/gtk3/running.html and https://docs.gtk.org/gtk4/running.html list options and environment variables.

== Navigation ==

To learn how to use the GNOME shell effectively, read the [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]; it highlights GNOME shell features and keyboard shortcuts. Features include task switching, keyboard use, window control, the panel, overview mode, and more. A few of the shortcuts are:

* {{ic|Super+m}}: show notification list
* {{ic|Super+a}}: show application grid
* {{ic|Alt+Tab}}: cycle active applications
* {{ic|Alt+`}} (the key above {{ic|Tab}} on US keyboard layouts): cycle windows of the application in the foreground
* {{ic|Alt+F2}}, then enter {{ic|r}} or {{ic|restart}}: restart the shell in case of graphical shell problems (only in X/legacy mode, not in Wayland mode).

See [[/Tips and tricks#Navigation]] for changes to the default configuration making the window-switching resemble that of Windows.

See [https://help.gnome.org/users/gnome-help/stable/keyboard-nav.html.en Keyboard navigation] for more shortcuts.

== Legacy names ==

{{Note|Some GNOME programs have undergone name changes where the application's name in documentation and about dialogs has been changed but the executable name has not. A few such applications are listed in the table below.}}

{{Tip|Searching for the legacy name of an application in the Shell search bar will successfully return the application in question. For instance, searching for ''nautilus'' will return ''Files''.}}

{| class="wikitable"
! Legacy
! Current
|-
| Baobab
| Disk Usage Analyzer
|-
| Decibels
| Audio Player
|-
| Epiphany
| [[GNOME/Web|Web]]
|-
| Loupe
| Image Viewer
|-
| Nautilus
| [[GNOME/Files|Files]]
|-
| Papers
| Document Viewer
|-
| Showtime
| Video Player
|-
| Simple Scan
| Document Scanner
|-
| Snapshot
| Camera
|}

== Configuration ==

GNOME Settings (''gnome-control-center'') and GNOME applications use the [[wikipedia:Dconf|dconf]] configuration system to store their settings.

You can directly access the dconf database using the {{man|1|gsettings}} command line tool. This also allows you to configure settings not exposed by the user interfaces. Command line tool {{man|1|dconf}} can directly modify the underlying database, bypassing validation. The configuration keys of gsettings and dconf are equivalent, but in a slightly different format: {{ic|gsettings set mygroup.mysubgroup mysetting myvalue}} in gsettings would be {{ic|dconf write /mygroup/mysubgroup/mysetting myvalue}} in dconf.

Up until GNOME 3.24, settings were applied by the GNOME settings daemon (located at {{ic|/usr/lib/gnome-settings-daemon/gnome-settings-daemon}}), which could be run outside of a GNOME session.

GNOME 3.24, however, replaced the GNOME settings daemon with several separate settings plugins {{ic|/usr/lib/gnome-settings-daemon/gsd-*}} which were later moved to {{ic|/usr/lib/gsd-*}}. These plugins are now controlled via desktop files under {{ic|/etc/xdg/autostart/}} (matching {{ic|org.gnome.SettingsDaemon.*.desktop}}). To run these plugins outside of a GNOME session, you will now need to copy/edit the appropriate [[desktop entries]] to {{ic|~/.config/autostart}}.

The configuration is usually performed user-specific; this section does not cover how to create configuration templates for multiple users.

=== System settings ===

==== Color ====

The daemon {{ic|colord}} reads the display's EDID and extracts the appropriate color profile. Most color profiles are accurate and no setup is required; however, for those that are not accurate, or for older displays, color profiles can be put in {{ic|~/.local/share/icc/}} and directed to.

==== Night Light ====

GNOME comes with a built-in blue light filter similar to [[Redshift]]. You can enable and customise the time you want to enable Night Light from the display settings menu. Furthermore, you can tweak the kelvin temperature with the following {{Pkg|dconf}} setting, where 5000 is an example value:

$ gsettings set org.gnome.settings-daemon.plugins.color night-light-temperature 5000

{{Tip|To change the daytime temperature in a Wayland session, install the [https://extensions.gnome.org/extension/1276/night-light-slider/ Night Light Slider extension].}}
{{Note| Night Light works on NVIDIA cards in Wayland sessions since version 545.29.02 }}

==== Date & time ====

If the system has a configured [[Network Time Protocol daemon]], it will be effective for GNOME as well. The synchronization can be set to manual control from the menu, if required.

GNOME supports automatic time zone selection (can be enabled in ''Date & Time'' section of the system settings, given that location services are enabled (see ''Privacy'' section of the settings).

{{Note|Automatic time zone selection might not work anymore because of the retirement of Mozilla Location Services. See [https://gitlab.gnome.org/GNOME/gnome-settings-daemon/-/issues/841#note_2300635]. For workarounds see [[System time#Setting based on geolocation]].}}

To show the date in the top bar, execute:

$ gsettings set org.gnome.desktop.interface clock-show-date true

Additionally, to show week numbers in the calendar opened on the top bar, execute:

$ gsettings set org.gnome.desktop.calendar show-weekdate true

==== Default applications ====

Upon installing GNOME for the first time, you may find that the wrong applications are handling certain protocols. For example, ''totem'' opens videos instead of a previously used [[VLC]]. Some of the associations can be set from system settings via ''Default Applications''.

For other protocols and methods, see [[Default applications]] for configuration.

==== Mouse and touchpad ====

Most touchpad settings can be set from system settings via ''Mouse & Touchpad''.

Depending on your device, other configuration settings may be available, but not exposed via the default GUI. For example, a different touchpad {{ic|click-method}}

{{hc|$ gsettings range org.gnome.desktop.peripherals.touchpad click-method|
enum
'default'
'none'
'areas'
'fingers'
}}

to be set manually:

$ gsettings set org.gnome.desktop.peripherals.touchpad click-method 'fingers'

or via {{Pkg|gnome-tweaks}}.

{{Note|1=The [[synaptics]] driver is not supported by GNOME. Instead, you should use [[libinput]]. See [https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12 this bug report].}}

===== Resize windows by mouse =====

By default, you can use your mouse to move windows by holding down {{ic|Super}}, clicking and holding the left mouse button and dragging the mouse around.

Additionally, you can enable using your mouse to resize windows by holding down {{ic|Super}}, clicking and holding the right mouse button and dragging the mouse around:

$ gsettings set org.gnome.desktop.wm.preferences resize-with-right-button true

If you don't like the {{ic|Super}} key, you can also change the modifier to something else, like {{ic|Alt}} or {{ic|Ctrl}}:

$ gsettings set org.gnome.desktop.wm.preferences mouse-button-modifier "'<Alt>'"

==== Network ====

[[NetworkManager]] is the native tool of the GNOME project to control network settings from the shell. If you have not already, [[install]] the {{Pkg|networkmanager}} package and [[enable]] the {{ic|NetworkManager.service}} systemd unit.

While any other [[network manager]] can be used alternatively, NetworkManager provides the full integration via the shell network settings and a status indicator applet {{Pkg|network-manager-applet}} (not required for GNOME).

{{Note|1=Hidden wireless networks set up with {{Pkg|networkmanager}}'s ''nmtui'' do not connect automatically. You need to create a new profile using GNOME control center in order to restore auto-connect capabilities for that network.}}

==== Online accounts ====

Some online accounts, such as [[Nextcloud]], require {{Pkg|gvfs-goa}} and {{Pkg|gvfs-dnssd}} to be installed for full functionality in GNOME applications such as [[GNOME Files]] and GNOME Documents [https://wiki.gnome.org/ThreePointSeven/Features/Owncloud].

See [https://help.gnome.org/users/gnome-help/stable/accounts.html.en Online accounts] for more information.

==== Search ====

The GNOME shell has a search that can be quickly accessed by pressing the {{ic|Super}} key and starting to type. The {{Pkg|localsearch}} package is installed by default as a dependency of {{Pkg|nautilus}} from the {{Grp|gnome}} group and provides an indexing application and metadata database. It can be configured with the ''Search'' menu item in ''Settings''. It is started automatically by ''gnome-session'' when the user logs in.

localsearch does not automatically recurse into all directories under the user's home directory, so you may need to add custom paths via the ''Search > Search locations'' menu item. To exclude a directory from the indexing, create an empty {{ic|.nomedia}} file.

A status is available with {{ic|localsearch status}} and the indexed content can be searched ({{ic|localsearch search --help}}), edited ({{ic|localsearch tag --help}}), or reset from the commandline. See {{ic|localsearch help}} and {{ic|localsearch ''command'' --help}}, or the [https://gnome.pages.gitlab.gnome.org/localsearch/commandline.html online help] for reference.

The database uses {{man|1|tinysparql-sql}} and can also be queried directly, if needed.

==== Accessibility ====

GNOME has accessibility settings available via ''Settings > Accessibility''. The main settings may be toggled directly after enabling a top bar icon, but note further settings are available via the sub-menus for ''Seeing'', ''Hearing'', ''Typing'', ''Pointing and clicking'' and ''Zoom''. See https://help.gnome.org/users/gnome-help/stable/a11y.html.en for information on them.

Additionally, a default set of keyboard shortcuts can be set via ''Settings > Keyboard > View and Customize Keyboard Shortcuts > Accessibility''. For example, pressing {{ic|Alt}}, {{ic|Super}} and {{ic|8}} toggles zooming.

==== Device Security Settings ====

GNOME 43 comes with a new [https://release.gnome.org/43/ Device Security] panel in Settings. This requires {{Pkg|fwupd}} in order to function. See [https://gitlab.gnome.org/GNOME/gnome-control-center/-/issues/2122].

=== Advanced settings ===

As noted above, many configuration options such as changing the [[GTK]] theme or the [[window manager]] theme are not exposed in GNOME Settings (''gnome-control-center''). Those users that want to configure these settings may wish to use the GNOME Tweaks ({{Pkg|gnome-tweaks}}), a convenient graphical tool which exposes many of these settings.

GNOME settings (which are stored in the DConf database) can also be configured using the {{Pkg|dconf-editor}} (a graphical DConf configuration tool) or the [https://developer.gnome.org/gio/stable/GSettings.html gsettings] command line tool. The GNOME Tweaks does not do anything else in the background of the GUI; note though that you will not find all settings described in the following sections in it.

==== Extensions ====

The catalogue of extensions is available at https://extensions.gnome.org, they can be installed either through [https://archlinux.org/packages/?q=gnome-shell-extension official repositories] (only a few), [https://aur.archlinux.org/packages?K=gnome-shell-extension the AUR] or through [https://extensions.gnome.org the browser] directly from the GNOME project.

{{Note|
* Installing extensions through the browser makes them available for the current user only and requires you to handle updates the same way. Install {{Pkg|gnome-browser-connector}} first for this option.
* Installing extensions through the AUR (or through official repositories, if you find them there) makes them available system-wide (and automates the update process if using an [[AUR helper]]).
}}

Installed extensions can also be configured, enabled or disabled through a GUI with ''gnome-extensions-app'', from the command line with {{man|1|gnome-extensions}}, or from the browser. In your browser, extensions can be installed then activated in the browser by setting the switch in right top right of the screen to '''ON''' and clicking '''Install''' on the popup window (if the extension in question is not installed). Installed extensions may be seen at https://extensions.gnome.org/local/, where available updates can be checked.

The {{Pkg|gnome-shell-extensions}} package provides a set of very useful extensions maintained as part of the GNOME project.

{{Pkg|extension-manager}} is a graphical tool which can also be used to install and remove extensions, as well as enable and disable them, both system-wide and for a user. Prior to using it, consider its [https://github.com/mjakeman/extension-manager/labels/bug list of known issues].

To enable usage of extensions (disabled by default):

$ gsettings set org.gnome.shell disable-user-extensions false

To list currently enabled extensions:

$ gsettings get org.gnome.shell enabled-extensions

The above command may list extensions that have been removed. To only list extensions that are enabled ''and'' installed, use ''gnome-extensions'' instead:

$ gnome-extensions list --enabled

For more information about GNOME shell extensions, see https://extensions.gnome.org/about/.

==== Appearance ====

===== Themes =====

{{Note|As of [https://release.gnome.org/42/ Gnome 42], many default Gnome applications use GTK 4 with libadwaita. These apps do not currently support changing themes through gsettings or {{pkg|gnome-tweaks}}, the only visual configuration available is through Settings > Appearance. See [[GTK#Themes]] for setting a GTK theme other than Adwaita or Adwaita-dark.}}

GNOME uses Adwaita by default. To apply Adwaita-dark only to GTK 2 applications, use the following symlink:

$ ln -s /usr/share/themes/Adwaita-dark ~/.themes/Adwaita

{{Note|The Adwaita-dark theme is provided by {{Pkg|gnome-themes-extra}} which may not be installed on a minimal installation of GNOME.}}

To select new themes (move them to the appropriate directory and) use GNOME Tweaks or the GSettings commands below.

For the GTK theme:

$ gsettings set org.gnome.desktop.interface gtk-theme ''theme-name''

For the icon theme:

$ gsettings set org.gnome.desktop.interface icon-theme ''theme-name''

{{Note|The window manager theme follows the GTK theme. Using {{ic|org.gnome.desktop.wm.preferences theme}} is deprecated and ignored.}}

See [[GTK#Themes]] and [[Icons#Icon themes]].

===== Titlebar button order =====

To set the order for the GNOME window manager (Mutter, Metacity):

$ gsettings set org.gnome.desktop.wm.preferences button-layout ':minimize,maximize,close'

{{Tip|The colon indicates which side of the titlebar the window buttons will appear.}}

===== GNOME Shell themes =====

The theme of GNOME Shell itself is configurable. To use a Shell theme, firstly ensure that you have the {{Pkg|gnome-shell-extensions}} package installed. Then enable the ''User Themes'' extension, either through the GNOME Extensions application or through the [https://extensions.gnome.org GNOME Shell Extensions] webpage. Shell themes can then be loaded and selected using GNOME Extensions.

There are a number of GNOME Shell themes available [https://aur.archlinux.org/packages?K=gtk+theme in the AUR], many themes do not have the same name format, so instead try searching for the appropriate theme in the AUR. Shell themes can also be downloaded from [https://gnome-look.org/ gnome-look.org].

===== AppIndicators/Top bar icons =====

To enable AppIndicators, which is useful for controlling/monitoring certain applications running in the background, Install {{Pkg|gnome-shell-extension-appindicator}} or {{AUR|gnome-shell-extension-appindicator-git}}, [[#Navigation|restart the GNOME Shell]], then enable the AppIndicator extension in the GNOME Extensions application or by running

$ gnome-extensions enable $(gnome-extensions list {{!}} grep -m 1 appindicatorsupport)

===== Shell animation speed =====

The GNOME shell animation can be sped up, slowed down or disabled. See [[GNOME/Tips and tricks#Change animation speed]].

===== Shell blur =====

Blur my Shell is an extension that adds blur effects to the overview screen as well as the shell itself and other apps. Install {{AUR|gnome-shell-extension-blur-my-shell}} or {{AUR|gnome-shell-extension-blur-my-shell-git}} for development updates. This extension is highly customizable, and you may choose to blur certain applications.

===== Better Alt-Tab Functionality =====

The default Alt-Tab in GNOME is very simple and does not show overviews of the selected windows. You can change the Alt-Tab shortcut from "Switch Applications" to "Switch Windows" in Settings to show window overviews.

You can also use Coverflow Alt-Tab. It is an extension that expands the Alt-Tab behavior and adds features to make switching between applications easier while also giving it a better look. Install {{AUR|gnome-shell-extension-coverflow-alt-tab-git}}, then you may change the configuration of this extension to your liking.

Note: Super-` provides "Switch windows of an application` by default.

==== Autostart ====

GNOME implements [[XDG Autostart]].

The {{Pkg|gnome-tweaks}} allows managing autostart-entries.

{{Tip|1=If the plus sign button in the Tweaks's Startup Applications section is unresponsive, try starting the Tweaks from the terminal using the following command: {{ic|gnome-tweaks}}. See the following [https://bbs.archlinux.org/viewtopic.php?pid=1413631#p1413631 forum thread].}}

==== Desktop ====

===== Dash to Dock =====

To move the dash out of the overview and turn it into a dock to easily launch and switch applications, [[install]] {{AUR|gnome-shell-extension-dash-to-dock}}.

===== Startup in Overview Mode =====

Starting from GNOME 40, the desktop will start directly into Overview Mode instead of an empty desktop (like in previous versions). To mimic legacy behaviour, one may [[install]] {{AUR|gnome-shell-extension-no-overview}}.

Alternatively, you can disable it using gsettings if using {{AUR|gnome-shell-extension-dash-to-dock}}:

$ gsettings set org.gnome.shell.extensions.dash-to-dock disable-overview-on-startup true

See the discussion at [https://discourse.gnome.org/t/gnome-40-login-is-to-the-activities-overview-mode-how-do-you-disable-this/5783].

==== Clipboard history ====

Unlike other desktop environments, GNOME does not have a built-in tool to manage the clipboard history. This can be done however with the help of an extension. Install {{AUR|gnome-shell-extension-clipboard-indicator}}.

==== Weather ====

To display the current weather information in the top panel based on a chosen location, install {{AUR|gnome-shell-extension-openweather}}. The weather information is updated in real-time and displays useful data such as conditions, wind speed, pressure, etc...

==== Sound input/output device selector ====
{{Remove|Probably not needed anymore. [https://github.com/kgshank/gse-sound-output-device-chooser Packages compatible] up to Gnome 43 only.}}
By default, if you want to change your sound input or output device or change your microphone's volume, you need to open GNOME Control Center and configure these settings from there. To integrate a device selector and a microphone volume slider, install {{AUR|gnome-shell-extension-sound-output-device-chooser}} or {{AUR|gnome-shell-extension-sound-output-device-chooser-git}}. Further configuration can be done after installation.

==== Fonts ====

{{Tip|If you set the ''Scaling factor'' to a value above 1.00, the Accessibility menu will be automatically enabled.}}

Fonts can be set for Window titles, Interface (applications), Documents and Monospace. See the Fonts tab in the Tweaks for the relevant options.

For hinting, RGBA will likely be desired as this fits most monitors types, and if fonts appear too blocked reduce hinting to ''Slight'' or ''None''.

==== Input methods ====

GNOME has integrated support for [[input method]]s through [[IBus]]. Only {{Pkg|ibus}} and the wanted input method engine (e.g. {{Pkg|ibus-libpinyin}} for Intelligent Pinyin) needed to be installed. After installation, the input method engine can be added as a keyboard layout under ''Keyboard > Input Sources'' in GNOME Settings (''gnome-control-center'').

==== Keyboard Layout quirks ====

If you are using an alternative keyboard layout like Neo2 which uses multiple layers/modifiers, you might need to go to ''Keyboard > Type Special Characters'' in GNOME Settings (''gnome-control-center'') and change the ''Alternate Characters Key'' away from ''Right Alt'' so that it can be used as a native modifier of the keyboard layout. Setting it to e.g. ''Left Alt'' prevents ''Alt+Tab'', so be careful what you change it to.
Without this change, your left ''Mod3'' key might work, but the right one (''AltGr'') does not. (As of 2021-05-18)

==== Power ====

When you are using a laptop, you might want to alter the following settings controlling behavior when idle, screen lock power button presses and lid close:

$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout ''3600''
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type ''hibernate''
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-timeout ''1800''
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-type ''hibernate''
$ gsettings set org.gnome.settings-daemon.plugins.power power-button-action ''suspend''
$ gsettings set org.gnome.desktop.lockdown disable-lock-screen ''true''

To keep the monitor active when the lid is closed:

$ gsettings set org.gnome.settings-daemon.plugins.xrandr default-monitors-setup do-nothing

GNOME 3.24 deprecated the following settings:

org.gnome.settings-daemon.plugins.power button-hibernate
org.gnome.settings-daemon.plugins.power button-power
org.gnome.settings-daemon.plugins.power button-sleep
org.gnome.settings-daemon.plugins.power button-suspend
org.gnome.settings-daemon.plugins.power critical-battery-action

===== Do not suspend when laptop lid is closed =====

The settings panel of GNOME does not provide an option for the user to change the action triggered when the laptop lid is closed. To change the lid switch action system-wide, edit the systemd settings in {{ic|/etc/systemd/logind.conf}}. To turn off suspend on lid close, set {{ic|1=HandleLidSwitch=ignore}}, as described in [[Power management#ACPI events]].

===== Change critical battery level action =====

The settings panel does not provide an option for changing the critical battery level action. These settings have been removed from dconf as well. They are now managed by upower. Edit the upower settings in {{ic|/etc/UPower/UPower.conf}}. Find these settings and adjust to your needs.

{{hc|head=/etc/UPower/UPower.conf|output=
PercentageLow=10
PercentageCritical=3
PercentageAction=2
CriticalPowerAction=HybridSleep
}}

===== Power modes =====

Install the [[power-profiles-daemon]] optional dependency (of {{Pkg|gnome-control-center}}) for power profiles support. Explicitly [[starting/enabling]] the {{ic|power-profiles-daemon}} service is unnecessary since ''gnome-shell'' and GNOME Settings both request its activation upon launching.

When the service is active, power profiles can be managed through the ''Power'' section of GNOME Settings and in the system menu.

==== Screencast ====

The built-in screenshot tool comes without the Screencast option by default. Install the {{Pkg|gst-plugin-pipewire}} optional dependency (of {{Pkg|gnome-shell}}) to enable screen recording.

=== Use a different window manager ===

GNOME Shell does not support using a different [[window manager]], however [[GNOME Flashback]] provides sessions for Metacity and [[Compiz]]. Furthermore, it is possible to define your own [[GNOME/Tips and tricks#Custom GNOME sessions|custom GNOME sessions]] which use alternative components.

Replacing GNOME Shell with a different [[Wayland compositor]] will cause certain sections of {{Pkg|gnome-control-center}} (GNOME Settings) to populate incorrectly. ''gnome-control-center'' will work, but since {{Pkg|mutter}} (GNOME Shell) will not be available to provide settings for populating these sections, they will not have an effect or may not populate accurately with your settings. Sections affected are bluetooth, display, and mouse/touchpad to name a few.

== See also ==

* [https://www.gnome.org/ Official Website]
* [https://blogs.gnome.org/tbernard/2021/06/15/community-power-2/ Contributing to GNOME, feature requests, bugs, code]
* [[Wikipedia:GNOME|Wikipedia article]]
* [https://extensions.gnome.org/ GNOME-Shell Extensions]
* [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]
* Customization (themes, icons...):
** [https://wiki.gnome.org/Personalization Personalize GNOME]
** [https://www.gnome-look.org/ GNOME Look]
* GNOME applications:
** [https://wiki.gnome.org/Apps GNOME Apps Index]
** [[Wikipedia:GNOME Core Applications]]
* GNOME Source/Mirrors:
** [https://gitlab.gnome.org/ GNOME GitLab]
** [https://github.com/GNOME GNOME Github Mirror]

Rsyslog

2026-05-07T14:11:21Z

Indigo: /* Enabling and starting service */ apply Help:Style#systemd units operations; the error reads like an old and remedied systemd issue, can't check it

{{Lowercase title}}
[[Category:Logging]]
[[ja:Rsyslog]]
{{Related articles start}}
{{Related|syslog-ng}}
{{Related articles end}}

{{Out of date|References out of date documentation}}

[https://www.rsyslog.com rsyslog] is a [[w:syslog|syslog]] implementation that offers many benefits over [[syslog-ng]]. It can be configured to receive log entries from [[systemd/Journal|systemd's journal]] in order to process or filter them before quickly writing them to disk or sending them over network.

== Installation ==

{{Note|It is recommended to disable and uninstall the {{Pkg|syslog-ng}} package to prevent possible conflicts.}}

[[Install]] the {{AUR|rsyslog}} package.

=== Enabling and starting service ===

After installation, [[enable]] {{ic|rsyslog.service}} and [[start]] it afterwards.

Starting the {{ic|rsyslog.service}} unit first would likely fail, because enabling the service creates a symlink for {{ic|syslog.service}} which would be missing otherwise; {{ic|rsyslog.service}} would raise the error: {{bc|1=rsyslog.service: Job rsyslog.service/start failed with result 'dependency'}}

=== Configure hostname ===

Rsyslog uses the {{Pkg|glibc}} routine {{ic|gethostname()}} or {{ic|gethostbyname()}} to determine the hostname of the local machine. The {{ic|gethostname()}} or {{ic|gethostbyname()}} routine check the contents of {{ic|/etc/hosts}} for the fully qualified domain name (FQDN) if you are not using [[BIND]] or [[NIS]].

You can check what the local machine's currently configured FQDN is by running {{ic|hostname --fqdn}}. The output of {{ic|hostname --short}} will be used by rsyslog when writing log messages. If you want to have full hostnames in logs, you need to add {{ic|$PreserveFQDN on}} to the beginning of the file (before using any directive that write to files). This is because, rsyslog reads its configuration file and applies it on-the-go and then reads the later lines.

The {{ic|/etc/hosts}} file contains a number of lines that map FQDNs to IP addresses and that map aliases to FQDNs. See the example {{ic|/etc/hosts}} file below:

{{hc|/etc/hosts|<nowiki>
#<ip-address> <hostname.domain.org> <hostname>
#<ip-address> <actual FQDN> <aliases>
127.0.0.1 localhost.localdomain somehost.localdomain localhost somehost
::1 localhost.localdomain somehost.localdomain localhost somehost
</nowiki>}}

{{ic|localhost.localdomain}} is the first item following the IP address, so {{ic|gethostbyname()}} function will return '''localhost.localdomain''' as the local machine's FQDN. Then {{ic|/var/log/messages}} file will use '''localhost''' as hostname.

To use '''somehost''' as the hostname. Move '''somehost.localdomain''' to the first item:

{{hc|/etc/hosts|<nowiki>
#<ip-address> <hostname.domain.org> <hostname>
#<ip-address> <actual FQDN> <aliases>
127.0.0.1 somehost.localdomain localhost.localdomain localhost somehost
::1 somehost.localdomain localhost.localdomain localhost somehost
</nowiki>}}

== Configuration ==

rsyslog is configured in {{ic|/etc/rsyslog.conf}}. See [https://www.rsyslog.com/doc/v8-stable/configuration/index.html the official documentation] for more information on the available configuration options.

By default, all syslog messages are handled by [[systemd/Journal|systemd's journal]]. In order to gather system logs in rsyslog, you either have to turn on [[#journald's syslog-forward feature]] or use the [[#imjournal]] module of rsyslog to gather the logs by importing it from the systemd journald.

=== imjournal ===

If you want rsyslog to pull messages from systemd, load the ''imjournal'' module:

{{hc|/etc/rsyslog.conf|
$ModLoad imjournal
}}

See [https://www.rsyslog.com/doc/v8-stable/configuration/modules/imjournal.html the documentation on the imjournal input module] for more information.

=== journald's syslog-forward feature ===

{{hc|/etc/systemd/journald.conf|
<nowiki>ForwardToSyslog=yes</nowiki>
}}

Log output can be fine tuned in {{ic|/etc/rsyslog.conf}}. The daemon uses Facility levels (see below) to determine what gets put where. For example:

{{hc|/etc/rsyslog.conf|
# The authpriv file has restricted access.
authpriv.* /var/log/secure
}}

States that all messages falling under the '''authpriv''' facility are logged to {{ic|/var/log/secure}}.

Another example, which would be similar to the behaviour of ''syslog-ng'' for the old {{ic|auth.log}}:

{{hc|/etc/rsyslog.conf|
auth.* -/var/log/auth
}}

See [[Systemd/Journal#Journald in conjunction with syslog]] for more information.

== Facility levels ==

{{Note|The mapping between Facility Number and Keyword is not uniform over different operating systems and different syslog implementations. Use the keyword where possible, until it is determined which numbers are used by Arch.}}

{| class="wikitable"
|-
! Facility Number !! Keyword !! Facility Description
|-
| 0 || kern || kernel messages
|-
| 1 || user || user-level messages
|-
| 2 || mail || mail system
|-
| 3 || daemon || system daemons
|-
| 4 || auth || security/authorization messages
|-
| 5 || syslog || messages generated internally by syslogd
|-
| 6 || lpr || line printer subsystem
|-
| 7 || news || network news subsystem
|-
| 8 || uucp || UUCP subsystem
|-
| 9 || || clock daemon
|-
| 10 || authpriv || security/authorization messages
|-
| 11 || ftp || FTP daemon
|-
| 12 || - || NTP subsystem
|-
| 13 || - || log audit
|-
| 14 || - || log alert
|-
| 15 || cron || clock daemon
|-
| 16 || local0 || local use 0 (local0)
|-
| 17 || local1 || local use 1 (local1)
|-
| 18 || local2 || local use 2 (local2)
|-
| 19 || local3 || local use 3 (local3)
|-
| 20 || local4 || local use 4 (local4)
|-
| 21 || local5 || local use 5 (local5)
|-
| 22 || local6 || local use 6 (local6)
|-
| 23 || local7 || local use 7 (local7)
|}

== Severity levels ==

As defined in [[RFC:5424|RFC 5424]], there are eight severity levels:

{| class="wikitable"
|-
! Code !! Severity !! Keyword !! Description !! General Description
|-
| 0 || Emergency || emerg (panic) || System is unusable. || A "panic" condition usually affecting multiple apps/servers/sites. At this level it would usually notify all tech staff on call.
|-
| 1 || Alert || alert || Action must be taken immediately. || Should be corrected immediately, therefore notify staff who can fix the problem. An example would be the loss of a primary ISP connection.
|-
| 2 || Critical || crit || Critical conditions. || Should be corrected immediately, but indicates failure in a primary system, an example is a loss of a backup ISP connection.
|-
| 3 || Error || err (error) || Error conditions. || Non-urgent failures, these should be relayed to developers or admins; each item must be resolved within a given time.
|-
| 4 || Warning || warning (warn) || Warning conditions. || Warning messages, not an error, but indication that an error will occur if action is not taken, e.g. file system 85% full - each item must be resolved within a given time.
|-
| 5 || Notice || notice || Normal but significant condition. || Events that are unusual but not error conditions - might be summarized in an email to developers or admins to spot potential problems - no immediate action required.
|-
| 6 || Informational || info || Informational messages. || Normal operational messages - may be harvested for reporting, measuring throughput, etc. - no action required.
|-
| 7 || Debug || debug || Debug-level messages. || Info useful to developers for debugging the application, not useful during operations.
|}

{{Tip|A common mnemonic used to remember the syslog levels in reverse order: "Do I Notice When Evenings Come Around Early".}}

== Examples ==

=== journald with rsyslog for kernel messages ===

{{Style|Redundant instructions, systemd commands...}}

Since the syslog component of systemd, journald, does not flush its logs to disk during normal operation, these logs will be gone when the machine is shut down abnormally (power loss, kernel lock-ups, ...). In the case of kernel lock-ups, it can be important to have some kernel logs for debugging. Until journald gains a configuration option for flushing kernel logs, rsyslog can be used in conjunction with journald.

Summary of requirements:

* journald must still get all log messages.
* rsyslog must only log kernel messages, all other logs are handled by journald.
* Kernel logs must be logged separatedly to {{ic|/var/log/kernel.log}}.
* Use systemd to start the service.

Installation and configuration steps:

# Install {{AUR|rsyslog}}.
# Edit {{ic|/etc/logrotate.d/rsyslog}} and add {{ic|/var/log/kernel.log}} to the list of logs. Without this modification, the kernel log would grow indefinitely.
# Edit {{ic|/etc/rsyslog.conf}} and comment everything except for {{ic|$ModLoad imklog}}. If a heart-beat (repeated confirmation that the log is alive) is preferred, {{ic|$ModLoad immark}} should remain uncommented as well.
# Add the next line to the same configuration file:
#:{{bc|kern.* /var/log/kernel.log;RSYSLOG_TraditionalFileFormat}}
#:The {{ic|kern.*}} part catches all messages originating from the kernel. {{ic|;RSYSLOG_TraditionalFileFormat}} is used here to use a less verbose date format. By default, a date format like {{ic|2013-03-09T19:29:33.103897+01:00}} is used. Since the kernel log contains a precision already (printk time) and the actual log time is irrelevant, a format like {{ic|Mar 9 19:29:13}} might be preferred.
# Since rsyslog should operate completely separated from systemd, remove the option that shares a socket with systemd:
#:{{bc|1=# sed 's/^Sockets=/#&/' /usr/lib/systemd/system/rsyslog.service > /etc/systemd/system/rsyslog.service}}
# Next, make rsyslog start on boot and start it for this session by [[start]]ing and enabling {{ic|rsyslog.service}}.

{{note|rsyslog reads from {{ic|/proc/kmsg}}. This means that subsequent reads from that file (either the user or a syslog daemon) will not read "old" logs from that file anymore. journald is not affected as it reads from {{ic|/dev/kmsg}} which allows multiple readers.}}

== See also ==

* [https://www.rsyslog.com/doc/v8-stable/ Rsyslog manual]

KeePass

2026-05-06T18:21:45Z

Indigo: /* Configuration with KeePass */ remove OOD; done

[[Category:Password managers]]
[[ja:KeePass]]
[[pt:KeePass]]
[[ru:KeePass]]
KeePass is an encrypted password database format. It is an alternative to online password managers and is supported on all major platforms.

There are two versions of the format: ''KeePass 1.x (Classic)'' and ''KeePass 2.x''

== Installation ==

There are three major implementations of KeePass available in the official repositories:

* {{App|[[Wikipedia:KeePass|KeePass]]|A cross-platform password manager that has autotype and clipboard support when respectively {{Pkg|xdotool}} and {{Pkg|xsel}} are installed. It lets you import [https://keepass.info/help/base/importexport.html many formats] and has [https://keepass.info/plugins.html many plugins].|https://keepass.info|{{Pkg|keepass}}}}
* {{App|[[Wikipedia:KeePassXC|KeePassXC]]|Fork of KeePassX that is actively maintained and has additional features like browser integration, support for SSH agent, secret service, Yubikey, finger-print reader, TOTP generator and KeeShare. Also provides a CLI through {{ic|keepassxc-cli}}.|https://keepassxc.org|{{Pkg|keepassxc}}}}
* {{App|{{Pkg|secrets}}|A modern GNOME password manager built on top of KeePass.|https://gitlab.gnome.org/World/secrets/|{{Pkg|secrets}}}}

Other lesser-known alternatives can be found in the AUR:

* {{App|keepassc|A curses-based password manager compatible to KeePass v.1.x and KeePassX. It uses {{ic|xsel}} for clipboard functions.|https://raymontag.github.io/keepassc/|{{AUR|keepassc}}}}
* {{App|kpcli|A command line interface for KeePass database files {{ic|*.kdb}} or {{ic|*.kdbx}}.|https://sourceforge.net/projects/kpcli/|{{AUR|kpcli}}}}
* {{App|keepmenu|Dmenu/Rofi frontend for Keepass database files.|https://github.com/firecat53/keepmenu|{{AUR|keepmenu}}}}
* {{App|AuthPass|KeePass compatible password manager based on Flutter. Comes with default sync suport for Gdrive, Dropbox, and WebDav.|https://authpass.app|{{AUR|authpass-bin}}}}
* {{App|keeweb|A web app (online / Electron) compatible with KeePass 2.x. KeeWeb comes with default Sync support for major cloud services, Gdrive, Onedrive, Dropbox etc. No active development since release of 1.18.7 on July 18th 2021.|https://keeweb.info|{{AUR|keeweb}} {{AUR|nextcloud-app-keeweb}} {{AUR|keeweb-desktop-bin}}}}
* {{App|[[Wikipedia:KeePassX|KeePassX]]|Started as a Linux port of KeePass. {{AUR|keepassx2}} uses the KeePass 2.x format, but can import 1.x databases. It also lets you import PwManager and KWallet XML databases. It does not support plugins. [https://www.keepassx.org/faq] No active development since 2016. [https://dev.keepassx.org/projects/keepassx/repository/revisions] |https://www.keepassx.org/|{{AUR|keepassx}} {{AUR|keepassx2}}}}

== Integration ==

Many [https://keepass.info/plugins.html plugins and extensions] are available for integrating KeePass to other software. KeePassX and KeePassXC do not have a plugin interface, but KeePassXC has various integrations built-in.

=== Plugin installation in KeePass ===

KeePass is by default installed at {{ic|/usr/share/keepass/}}. Copy {{ic|plugin.plgx}} to a plugins sub-directory under the KeePass installation directory as demonstrated below:

{{bc|
# mkdir /usr/share/keepass/plugins
# cp plugin.plgx /usr/share/keepass/plugins
}}

=== Browser integration ===

==== keepassxc-browser for KeePassXC ====

[https://github.com/keepassxreboot/keepassxc-browser keepassxc-browser] is the browser extension of KeePassXC’s built-in browser integration using native-messaging and transport encryption using libsodium. It was developed to replace KeePassHTTP, as KeePassHTTP’s protocol has fundamental security problems.

The developers provide the browser extension on

* [https://addons.mozilla.org/firefox/addon/keepassxc-browser/ Firefox Add-ons] (for [[Firefox]] and [[Tor Browser]]) and
* in the [https://chrome.google.com/webstore/detail/keepassxc-browser/oboonakemofpalcgghocfoadofidjkkk chrome web store] (for [[Chromium]], [[Google Chrome]], [[Vivaldi]] and [[Brave]]).

Support for Firefox and Chromium forks is available. For {{AUR|librewolf}}, open KeePassXC, go to ''Tools'' > ''Settings'' > ''Browser Integration'' > ''Advanced'' > ''Config Location:'', and add {{ic|~/.librewolf/native-messaging-hosts}}.

The [https://github.com/keepassxreboot/keepassxc-browser source code and an explanation how it works] can be found on GitHub, the KeePassXC developers provide a [https://keepassxc.org/docs/KeePassXC_GettingStarted.html#_configure_keepassxc_browser configuration guide] on their website.

==== KeePassRPC and Kee ====

[https://www.kee.pm/ Kee] ([https://github.com/kee-org/browser-addon GitHub repo]) is a browser extension for [[Firefox]] and [[Chromium]] which integrates KeePass through [https://github.com/kee-org/keepassrpc KeePassRPC], a KeePass plugin from the same developers.

The KeePass plugin is available from [https://github.com/kee-org/keepassrpc/releases GitHub] or from the AUR ({{aur|keepass-plugin-rpc}}).

The browser extension can be found on [https://github.com/kee-org/browser-addon/releases GitHub], [https://addons.mozilla.org/firefox/addon/keefox/ Firefox Add-ons] and the [https://chrome.google.com/webstore/detail/kee-password-manager/mmhlniccooihdimnnjhamobppdhaolme chrome web store].

==== Via autotype feature ====

An alternative to having a direct channel between browser and KeePass(XC) is using the autotype feature.

To enable the autotype feature on Wayland, force KeePass(XC) to fallback to X11. [[Textedit|Edit]] {{ic|/usr/share/applications/org.keepassxc.KeePassXC.desktop}} and change the value of {{ic|Exec}} to {{ic|keepassxc -platform xcb}}. Alternatively, set the {{ic|1=QT_QPA_PLATFORM=xcb}} [[environment variable]] before launching KeePassXC. However, native Wayland applications will not work with autotype. For example, autotype works when running Firefox without Wayland, but not with.

There are browser extensions which support this way by putting the page URL into the window name:

* [https://addons.mozilla.org/firefox/addon/keepass-helper-url-in-title/ KeePass Helper] or [https://addons.mozilla.org/firefox/addon/url-in-title/ TitleURL] for [[Firefox]]
* [https://chrome.google.com/webstore/detail/url-in-title/ignpacbgnbnkaiooknalneoeladjnfgb URL in title] for [[Chromium]]

{{Warning|Auto typing has its own risks and limitations, therefore check the technical documentation of the password safe you are using: [https://keepass.info/help/base/faq_tech.html#autotypelog KeePass], [https://keepassxc.org/docs/#faq-autotype KeePassXC].}}

=== Yubikey ===

[[YubiKey]] can be integrated with KeePass thanks to contributors of KeePass plugins. KeepassXC provides built-in support for Yubikey Challenge-Response without plugins.

==== Configuration with KeePass ====

For an explanation of the configuration options, see https://keepass.info/help/kb/yubikey.html.

# StaticPassword
#:Configure one of Yubikey slots to store static password. You can make the password as strong as 65 characters (64 characters with leading "!"). This password can then be used as master password for your KeePass database.
# One-time passwords (OATH-HOTP)
## Download plugin from KeePass website: https://keepass.info/plugins.html#otpkeyprov
## Setup the [[YubiKey#OTP_slot_implementation|Yubikey OATH-HOTP slot]] (program the same, if a backup Yubikey is used)
## In advanced mode untick ''OATH Token Identifier''
## In KeePass additional option will show up under ''Key file / provider'' called ''One-Time Passwords (OATH HOTP)''
## Copy secret, key length (6 or 8), and counter you set
## You may need to setup ''Look-ahead count'' option to something greater than 0, please see [https://forum.yubico.com/viewtopicf146.html?f=16&t=1120 this thread] for more information
## See [https://vimeo.com/94352853 this video] for more help
#Challenge-Response (HMAC-SHA1)
## Get the plugin from AUR: {{AUR|keepass-plugin-keechallenge}}
## In KeePass additional option will show up under ''Key file / provider'' called ''Yubikey challenge-response''
## Plugin assumes slot 2 is used

=== SSH agent ===

KeePassXC offers SSH agent support, a similar feature is also available for KeePass using the [https://lechnology.com/software/keeagent/ KeeAgent] plugin.

The feature allows to store SSH keys in KeePass databases, KeePassXC/KeeAgent acts as OpenSSH Client and dynamically adds and removes the key to the Agent.

The feature in KeePassXC is documented in its [https://keepassxc.org/docs/#faq-ssh-agent-how FAQ]. First configure [[SSH agent]] to start on login and make sure the {{ic|SSH_AUTH_SOCK}} variable is set. Then logout and log back in. Now, in KeePassXC settings, enable SSH agent integration. The {{ic|SSH_AUTH_SOCK}} value exposed in the UI should correspond to what you configured earlier.

{{Note|The [[GnuPG#SSH agent|SSH agent emulation of ''gpg-agent'']] does not support removing keys from the agent on demand using {{ic|ssh-add -d}} or {{ic|ssh-add -D}}, therefore KeePassXC/KeeAgent cannot remove them when locking the database. [https://github.com/keepassxreboot/keepassxc/issues/2029#issuecomment-395933402] [https://unix.stackexchange.com/questions/185393/gpg-agent-doesnt-remove-my-ssh-key-from-the-keyring]}}

=== Secret Service ===

KeePassXC contains a [https://specifications.freedesktop.org/secret-service-spec/latest/ Freedesktop.org Secret Service] integration. It will allow external applications to use KeePassXC as an encrypted database (''a.k.a.'' as a vault, wallet, or keyring) to store user credentials (''e.g.'', messaging applications, games).

It can be enabled by going into the settings (under the ''Tools'' menu), and selecting which group(s) you want to share ('''for each database''', open ''Database > Database Settings...'', then go to the ''Secret Service Integration'' tab).

KeePassXC will refuse to enable its integration if it detects that another program (such as [[GNOME/Keyring]]) is already providing that service. You should first stop that program (for example, by [[stop]]ping {{ic|gnome-keyring-daemon.service}} [[user unit]] for {{Pkg|gnome-keyring}}). Note that you will likely want to disable the program permanently, otherwise KeePassXC's integration will fail on the next reboot (for example, by [[disabling]] the {{ic|gnome-keyring-daemon.socket}} of a [[systemd/User]] for {{Pkg|gnome-keyring}}).

{{Tip|To avoid confirmation of every access to the database by other applications, but transparently allow the access like GNOME Keyring or KDE Keyring, you can go to ''Tools > Secret Service Integration'' and uncheck the two ''Confirm when [...]'' checkboxes.}}

An application that requests access to the database will connect to KeePassXC through [[D-Bus]], where KeePassXC will be "seen" just as [https://wiki.gnome.org/Projects/Libsecret GNOME libsecret] by the application. The database that will be exposed can be stored anywhere on the disk, just like any other KeePassXC database, and the master password of this database will be the one to type when applications will want to retrieve a credential in the future.

{{Tip|Note that if an application tries to access the KeePassXC database while it is not already created, the process can appear to "freeze" for one or two minutes because of a timeout, but then a pop-up for database creation will appear.}}

{{Warning|Note that an application (''e.g.'' Tutanota using Chromium and Electron as backend) can fail to access Chromium's Safe Storage if the KeePassXC database is not already opened manually by the user or using the D-Bus autostart file.}}

==== Autostart ====

KeePassXC will not be automatically started when an application requests secrets, which may cause them to break. [https://github.com/keepassxreboot/keepassxc/discussions/9009 A D-Bus auto-start file] can be [[create]]d:

{{hc|${XDG_DATA_HOME:-$HOME/.local/share}/dbus-1/services/org.freedesktop.secrets.service|2=
[D-BUS Service]
Name=org.freedesktop.secrets
Exec=/usr/bin/keepassxc
}}

{{Tip|The above will only apply to the user the commands are executed as. To apply the fix to ''all'' users, create the file as root in {{ic|/usr/local/share}}.}}

{{Warning|Remember to delete this file if uninstalling {{Pkg|keepassxc}}. Otherwise, other applications may be unable to provide the Secret Service.}}

== Tips and tricks ==

=== Disable your clipboard manager ===

If you are an avid user of clipboard managers, you may need to disable your clipboard manager before you launch Keepass and then re-start your clipboard manager afterwards.

KeePassXC implementations has the option to auto-clear the clipboard manager after an amount of time, enough to paste copied items.

{{Tip|Some advanced clipboard managers like CopyQ have the option to ignore input from specified applications.}}

=== Dark theme ===

To enable the dark theme for KeePass, install {{AUR|keepass-keetheme}}. After installation, the plugin will get compiled upon starting KeePass. It can then be activated via ''Tools > Dark Theme'', or by pressing {{ic|Ctrl+t}}.

=== Synchronization ===

Without using specialized plugin, a KeePass database is well-suited to be synchronized through [[Syncthing]]. On conflicts, some applications provides a way to resolve them, such as the ''Merge from database'' feature of KeePassXC.

== Troubleshooting ==

=== User interface scaling issues with KeePassXC 2.6 ===

If the user interface elements are not scaled properly, see [[HiDPI#Qt 5]] and [https://github.com/keepassxreboot/keepassxc/issues/5029 upstream bug report].

=== Greyed-out options ===

Some options like ''Start minimized and locked'' may appear greyed-out. According to a discussion on [https://sourceforge.net/p/keepass/discussion/329220/thread/5a14d949/ SourceForge], since version 2.31, KeePass has disabled two options because of their [https://sourceforge.net/p/keepass/bugs/1418/ broken behaviors] on Mono.

To force these features to be enabled, launch KeePass with the {{ic|-wa-disable:1418}} argument.

=== Wrongly scaled tray icons ===

In some [[desktop environment]]s, the tray icon of KeePass may appear too big or too small due to Mono's bug, according to a bug report on [https://sourceforge.net/p/keepass/bugs/1733/#925e SourceForge].

[https://github.com/dlech/Keebuntu/ Keebuntu] contains three plugins to provide desktop integration:

* {{AUR|keepass2-plugin-tray-icon}}: For [[Cinnamon]] and [[MATE]];
* {{AUR|keepass-plugin-statusnotifier-git}}: For [[Plasma]] and [[GNOME]] with {{Pkg|gnome-shell-extension-appindicator}};
* [https://github.com/dlech/Keebuntu/#launcher-quicklist keepass2-plugin-launcher]: For the {{Pkg|plank}} dock.

After installing one of these plugins, it is sometimes necessary to hide the original tray icon to prevent duplicate icons in the system tray.

=== Secret Service Integration ===

First, check that the group under which your passwords are stored is exposed; the ''Tools > Settings'' menu contains a list of groups enabled for each database. If a database isn't exposing the proper group, select its tab, open ''Database > Database Settings...'', then select the group in the ''Secret Service Integration'' tab).

Note that [https://github.com/keepassxreboot/keepassxc/issues/9371 merging a database can cause it to stop exposing any groups].

=== Graphical glitches with KeePassXC, Plasma6 and Wayland ===

If you are experiencing graphical glitches, install the {{Pkg|qt5-wayland}} and {{Pkg|plasma5-integration}} packages. KeePassXC (as of version v2.7.7) still uses Qt5.

== See also ==

* [[List of applications/Security#Password managers]]

KeePass

2026-05-06T18:21:08Z

Indigo: /* Configuration with KeePass */ add intro sentence with link; update hotp method and slice deprecated tool references out, replacing with current

[[Category:Password managers]]
[[ja:KeePass]]
[[pt:KeePass]]
[[ru:KeePass]]
KeePass is an encrypted password database format. It is an alternative to online password managers and is supported on all major platforms.

There are two versions of the format: ''KeePass 1.x (Classic)'' and ''KeePass 2.x''

== Installation ==

There are three major implementations of KeePass available in the official repositories:

* {{App|[[Wikipedia:KeePass|KeePass]]|A cross-platform password manager that has autotype and clipboard support when respectively {{Pkg|xdotool}} and {{Pkg|xsel}} are installed. It lets you import [https://keepass.info/help/base/importexport.html many formats] and has [https://keepass.info/plugins.html many plugins].|https://keepass.info|{{Pkg|keepass}}}}
* {{App|[[Wikipedia:KeePassXC|KeePassXC]]|Fork of KeePassX that is actively maintained and has additional features like browser integration, support for SSH agent, secret service, Yubikey, finger-print reader, TOTP generator and KeeShare. Also provides a CLI through {{ic|keepassxc-cli}}.|https://keepassxc.org|{{Pkg|keepassxc}}}}
* {{App|{{Pkg|secrets}}|A modern GNOME password manager built on top of KeePass.|https://gitlab.gnome.org/World/secrets/|{{Pkg|secrets}}}}

Other lesser-known alternatives can be found in the AUR:

* {{App|keepassc|A curses-based password manager compatible to KeePass v.1.x and KeePassX. It uses {{ic|xsel}} for clipboard functions.|https://raymontag.github.io/keepassc/|{{AUR|keepassc}}}}
* {{App|kpcli|A command line interface for KeePass database files {{ic|*.kdb}} or {{ic|*.kdbx}}.|https://sourceforge.net/projects/kpcli/|{{AUR|kpcli}}}}
* {{App|keepmenu|Dmenu/Rofi frontend for Keepass database files.|https://github.com/firecat53/keepmenu|{{AUR|keepmenu}}}}
* {{App|AuthPass|KeePass compatible password manager based on Flutter. Comes with default sync suport for Gdrive, Dropbox, and WebDav.|https://authpass.app|{{AUR|authpass-bin}}}}
* {{App|keeweb|A web app (online / Electron) compatible with KeePass 2.x. KeeWeb comes with default Sync support for major cloud services, Gdrive, Onedrive, Dropbox etc. No active development since release of 1.18.7 on July 18th 2021.|https://keeweb.info|{{AUR|keeweb}} {{AUR|nextcloud-app-keeweb}} {{AUR|keeweb-desktop-bin}}}}
* {{App|[[Wikipedia:KeePassX|KeePassX]]|Started as a Linux port of KeePass. {{AUR|keepassx2}} uses the KeePass 2.x format, but can import 1.x databases. It also lets you import PwManager and KWallet XML databases. It does not support plugins. [https://www.keepassx.org/faq] No active development since 2016. [https://dev.keepassx.org/projects/keepassx/repository/revisions] |https://www.keepassx.org/|{{AUR|keepassx}} {{AUR|keepassx2}}}}

== Integration ==

Many [https://keepass.info/plugins.html plugins and extensions] are available for integrating KeePass to other software. KeePassX and KeePassXC do not have a plugin interface, but KeePassXC has various integrations built-in.

=== Plugin installation in KeePass ===

KeePass is by default installed at {{ic|/usr/share/keepass/}}. Copy {{ic|plugin.plgx}} to a plugins sub-directory under the KeePass installation directory as demonstrated below:

{{bc|
# mkdir /usr/share/keepass/plugins
# cp plugin.plgx /usr/share/keepass/plugins
}}

=== Browser integration ===

==== keepassxc-browser for KeePassXC ====

[https://github.com/keepassxreboot/keepassxc-browser keepassxc-browser] is the browser extension of KeePassXC’s built-in browser integration using native-messaging and transport encryption using libsodium. It was developed to replace KeePassHTTP, as KeePassHTTP’s protocol has fundamental security problems.

The developers provide the browser extension on

* [https://addons.mozilla.org/firefox/addon/keepassxc-browser/ Firefox Add-ons] (for [[Firefox]] and [[Tor Browser]]) and
* in the [https://chrome.google.com/webstore/detail/keepassxc-browser/oboonakemofpalcgghocfoadofidjkkk chrome web store] (for [[Chromium]], [[Google Chrome]], [[Vivaldi]] and [[Brave]]).

Support for Firefox and Chromium forks is available. For {{AUR|librewolf}}, open KeePassXC, go to ''Tools'' > ''Settings'' > ''Browser Integration'' > ''Advanced'' > ''Config Location:'', and add {{ic|~/.librewolf/native-messaging-hosts}}.

The [https://github.com/keepassxreboot/keepassxc-browser source code and an explanation how it works] can be found on GitHub, the KeePassXC developers provide a [https://keepassxc.org/docs/KeePassXC_GettingStarted.html#_configure_keepassxc_browser configuration guide] on their website.

==== KeePassRPC and Kee ====

[https://www.kee.pm/ Kee] ([https://github.com/kee-org/browser-addon GitHub repo]) is a browser extension for [[Firefox]] and [[Chromium]] which integrates KeePass through [https://github.com/kee-org/keepassrpc KeePassRPC], a KeePass plugin from the same developers.

The KeePass plugin is available from [https://github.com/kee-org/keepassrpc/releases GitHub] or from the AUR ({{aur|keepass-plugin-rpc}}).

The browser extension can be found on [https://github.com/kee-org/browser-addon/releases GitHub], [https://addons.mozilla.org/firefox/addon/keefox/ Firefox Add-ons] and the [https://chrome.google.com/webstore/detail/kee-password-manager/mmhlniccooihdimnnjhamobppdhaolme chrome web store].

==== Via autotype feature ====

An alternative to having a direct channel between browser and KeePass(XC) is using the autotype feature.

To enable the autotype feature on Wayland, force KeePass(XC) to fallback to X11. [[Textedit|Edit]] {{ic|/usr/share/applications/org.keepassxc.KeePassXC.desktop}} and change the value of {{ic|Exec}} to {{ic|keepassxc -platform xcb}}. Alternatively, set the {{ic|1=QT_QPA_PLATFORM=xcb}} [[environment variable]] before launching KeePassXC. However, native Wayland applications will not work with autotype. For example, autotype works when running Firefox without Wayland, but not with.

There are browser extensions which support this way by putting the page URL into the window name:

* [https://addons.mozilla.org/firefox/addon/keepass-helper-url-in-title/ KeePass Helper] or [https://addons.mozilla.org/firefox/addon/url-in-title/ TitleURL] for [[Firefox]]
* [https://chrome.google.com/webstore/detail/url-in-title/ignpacbgnbnkaiooknalneoeladjnfgb URL in title] for [[Chromium]]

{{Warning|Auto typing has its own risks and limitations, therefore check the technical documentation of the password safe you are using: [https://keepass.info/help/base/faq_tech.html#autotypelog KeePass], [https://keepassxc.org/docs/#faq-autotype KeePassXC].}}

=== Yubikey ===

[[YubiKey]] can be integrated with KeePass thanks to contributors of KeePass plugins. KeepassXC provides built-in support for Yubikey Challenge-Response without plugins.

==== Configuration with KeePass ====

For an explanation of the configuration options, see https://keepass.info/help/kb/yubikey.html.

{{Out of date|yubikey-personalization-gui-git was apparently replaced with {{Pkg|yubikey-manager}} or {{AUR|yubico-authenticator}}[https://lists.archlinux.org/archives/list/aur-requests@lists.archlinux.org/thread/FM3Y56EOSBFTO35UMYAWIKSKK45U2FLG/#FM3Y56EOSBFTO35UMYAWIKSKK45U2FLG]}}

# StaticPassword
#:Configure one of Yubikey slots to store static password. You can make the password as strong as 65 characters (64 characters with leading "!"). This password can then be used as master password for your KeePass database.
# One-time passwords (OATH-HOTP)
## Download plugin from KeePass website: https://keepass.info/plugins.html#otpkeyprov
## Setup the [[YubiKey#OTP_slot_implementation|Yubikey OATH-HOTP slot]] (program the same, if a backup Yubikey is used)
## In advanced mode untick ''OATH Token Identifier''
## In KeePass additional option will show up under ''Key file / provider'' called ''One-Time Passwords (OATH HOTP)''
## Copy secret, key length (6 or 8), and counter you set
## You may need to setup ''Look-ahead count'' option to something greater than 0, please see [https://forum.yubico.com/viewtopicf146.html?f=16&t=1120 this thread] for more information
## See [https://vimeo.com/94352853 this video] for more help
#Challenge-Response (HMAC-SHA1)
## Get the plugin from AUR: {{AUR|keepass-plugin-keechallenge}}
## In KeePass additional option will show up under ''Key file / provider'' called ''Yubikey challenge-response''
## Plugin assumes slot 2 is used

=== SSH agent ===

KeePassXC offers SSH agent support, a similar feature is also available for KeePass using the [https://lechnology.com/software/keeagent/ KeeAgent] plugin.

The feature allows to store SSH keys in KeePass databases, KeePassXC/KeeAgent acts as OpenSSH Client and dynamically adds and removes the key to the Agent.

The feature in KeePassXC is documented in its [https://keepassxc.org/docs/#faq-ssh-agent-how FAQ]. First configure [[SSH agent]] to start on login and make sure the {{ic|SSH_AUTH_SOCK}} variable is set. Then logout and log back in. Now, in KeePassXC settings, enable SSH agent integration. The {{ic|SSH_AUTH_SOCK}} value exposed in the UI should correspond to what you configured earlier.

{{Note|The [[GnuPG#SSH agent|SSH agent emulation of ''gpg-agent'']] does not support removing keys from the agent on demand using {{ic|ssh-add -d}} or {{ic|ssh-add -D}}, therefore KeePassXC/KeeAgent cannot remove them when locking the database. [https://github.com/keepassxreboot/keepassxc/issues/2029#issuecomment-395933402] [https://unix.stackexchange.com/questions/185393/gpg-agent-doesnt-remove-my-ssh-key-from-the-keyring]}}

=== Secret Service ===

KeePassXC contains a [https://specifications.freedesktop.org/secret-service-spec/latest/ Freedesktop.org Secret Service] integration. It will allow external applications to use KeePassXC as an encrypted database (''a.k.a.'' as a vault, wallet, or keyring) to store user credentials (''e.g.'', messaging applications, games).

It can be enabled by going into the settings (under the ''Tools'' menu), and selecting which group(s) you want to share ('''for each database''', open ''Database > Database Settings...'', then go to the ''Secret Service Integration'' tab).

KeePassXC will refuse to enable its integration if it detects that another program (such as [[GNOME/Keyring]]) is already providing that service. You should first stop that program (for example, by [[stop]]ping {{ic|gnome-keyring-daemon.service}} [[user unit]] for {{Pkg|gnome-keyring}}). Note that you will likely want to disable the program permanently, otherwise KeePassXC's integration will fail on the next reboot (for example, by [[disabling]] the {{ic|gnome-keyring-daemon.socket}} of a [[systemd/User]] for {{Pkg|gnome-keyring}}).

{{Tip|To avoid confirmation of every access to the database by other applications, but transparently allow the access like GNOME Keyring or KDE Keyring, you can go to ''Tools > Secret Service Integration'' and uncheck the two ''Confirm when [...]'' checkboxes.}}

An application that requests access to the database will connect to KeePassXC through [[D-Bus]], where KeePassXC will be "seen" just as [https://wiki.gnome.org/Projects/Libsecret GNOME libsecret] by the application. The database that will be exposed can be stored anywhere on the disk, just like any other KeePassXC database, and the master password of this database will be the one to type when applications will want to retrieve a credential in the future.

{{Tip|Note that if an application tries to access the KeePassXC database while it is not already created, the process can appear to "freeze" for one or two minutes because of a timeout, but then a pop-up for database creation will appear.}}

{{Warning|Note that an application (''e.g.'' Tutanota using Chromium and Electron as backend) can fail to access Chromium's Safe Storage if the KeePassXC database is not already opened manually by the user or using the D-Bus autostart file.}}

==== Autostart ====

KeePassXC will not be automatically started when an application requests secrets, which may cause them to break. [https://github.com/keepassxreboot/keepassxc/discussions/9009 A D-Bus auto-start file] can be [[create]]d:

{{hc|${XDG_DATA_HOME:-$HOME/.local/share}/dbus-1/services/org.freedesktop.secrets.service|2=
[D-BUS Service]
Name=org.freedesktop.secrets
Exec=/usr/bin/keepassxc
}}

{{Tip|The above will only apply to the user the commands are executed as. To apply the fix to ''all'' users, create the file as root in {{ic|/usr/local/share}}.}}

{{Warning|Remember to delete this file if uninstalling {{Pkg|keepassxc}}. Otherwise, other applications may be unable to provide the Secret Service.}}

== Tips and tricks ==

=== Disable your clipboard manager ===

If you are an avid user of clipboard managers, you may need to disable your clipboard manager before you launch Keepass and then re-start your clipboard manager afterwards.

KeePassXC implementations has the option to auto-clear the clipboard manager after an amount of time, enough to paste copied items.

{{Tip|Some advanced clipboard managers like CopyQ have the option to ignore input from specified applications.}}

=== Dark theme ===

To enable the dark theme for KeePass, install {{AUR|keepass-keetheme}}. After installation, the plugin will get compiled upon starting KeePass. It can then be activated via ''Tools > Dark Theme'', or by pressing {{ic|Ctrl+t}}.

=== Synchronization ===

Without using specialized plugin, a KeePass database is well-suited to be synchronized through [[Syncthing]]. On conflicts, some applications provides a way to resolve them, such as the ''Merge from database'' feature of KeePassXC.

== Troubleshooting ==

=== User interface scaling issues with KeePassXC 2.6 ===

If the user interface elements are not scaled properly, see [[HiDPI#Qt 5]] and [https://github.com/keepassxreboot/keepassxc/issues/5029 upstream bug report].

=== Greyed-out options ===

Some options like ''Start minimized and locked'' may appear greyed-out. According to a discussion on [https://sourceforge.net/p/keepass/discussion/329220/thread/5a14d949/ SourceForge], since version 2.31, KeePass has disabled two options because of their [https://sourceforge.net/p/keepass/bugs/1418/ broken behaviors] on Mono.

To force these features to be enabled, launch KeePass with the {{ic|-wa-disable:1418}} argument.

=== Wrongly scaled tray icons ===

In some [[desktop environment]]s, the tray icon of KeePass may appear too big or too small due to Mono's bug, according to a bug report on [https://sourceforge.net/p/keepass/bugs/1733/#925e SourceForge].

[https://github.com/dlech/Keebuntu/ Keebuntu] contains three plugins to provide desktop integration:

* {{AUR|keepass2-plugin-tray-icon}}: For [[Cinnamon]] and [[MATE]];
* {{AUR|keepass-plugin-statusnotifier-git}}: For [[Plasma]] and [[GNOME]] with {{Pkg|gnome-shell-extension-appindicator}};
* [https://github.com/dlech/Keebuntu/#launcher-quicklist keepass2-plugin-launcher]: For the {{Pkg|plank}} dock.

After installing one of these plugins, it is sometimes necessary to hide the original tray icon to prevent duplicate icons in the system tray.

=== Secret Service Integration ===

First, check that the group under which your passwords are stored is exposed; the ''Tools > Settings'' menu contains a list of groups enabled for each database. If a database isn't exposing the proper group, select its tab, open ''Database > Database Settings...'', then select the group in the ''Secret Service Integration'' tab).

Note that [https://github.com/keepassxreboot/keepassxc/issues/9371 merging a database can cause it to stop exposing any groups].

=== Graphical glitches with KeePassXC, Plasma6 and Wayland ===

If you are experiencing graphical glitches, install the {{Pkg|qt5-wayland}} and {{Pkg|plasma5-integration}} packages. KeePassXC (as of version v2.7.7) still uses Qt5.

== See also ==

* [[List of applications/Security#Password managers]]

YubiKey

2026-05-06T18:08:29Z

Indigo: /* OTP slot implementation */ add tip for options

[[Category:OpenPGP]]
[[Category:Smartcards]]
[[Category:Universal 2nd Factor]]
[[ja:Yubikey]]
[[zh-hans:YubiKey]]
{{Related articles start}}
{{Related|Universal 2nd Factor}}
{{Related|OATH}}
{{Related|dm-crypt/Encrypting an entire system}}
{{Related|PAM}}
{{Related|GnuPG}}
{{Related|KeePass}}
{{Related|OpenPGP-card-tools}}
{{Related|Smartcards}}
{{Related articles end}}

The [https://www.yubico.com/ YubiKey] is a small [[Wikipedia:Security token|USB security token]]. Depending on the model, it can:

* Act as a smartcard using the [[Wikipedia:CCID (protocol)|CCID protocol]], allowing storage of both [https://developers.yubico.com/PGP/ PGP] and [https://developers.yubico.com/PIV/ PIV] secret keys.
* Handle [[Universal 2nd Factor]] (U2F) requests.
* Store and query approximately 30 [[Initiative for Open Authentication]] (OATH) credentials.
* Handle [[Wikipedia:Challenge–response authentication|challenge-response requests]], in either the Yubico OTP mode or the HMAC-SHA1 mode.
* Generate [[Wikipedia:One-time password|one-time passwords]] (OTPs) with [https://developers.yubico.com/OTP/ Yubico's AES-based standard].
* "Type" a static password up to 63 characters.

While offering many features, newer versions of the YubiKey are [https://www.yubico.com/blog/secure-hardware-vs-open-source/ not released as open source]. Alternatives are the [[Solo]], [[Tillitis TKey|TKey]] or [[Nitrokey]].

== Installation ==

=== Management tools ===

* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring and querying a YubiKey over USB.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}}}
::{{Note|After installation, [[enable]] {{ic|pcscd.service}}; alternatively, it might be useful to [[enable]] {{ic|pcscd.socket}}.}}
::{{Warning|{{AUR|yubikey-manager-qt}} was available as a GUI but is now [https://github.com/Yubico/yubikey-manager-qt/commit/28dc02d11b081683b59d16d12043aaa3c0a6c75f deprecated by Yubico]. The package is also [https://github.com/Yubico/yubikey-manager-qt/issues/361 completely broken] due to incompatibility with recent versions of Python and {{ic|ykman}}.}}
* {{App|Yubico Authenticator|GUI tool to access and reset information, configure [https://docs.yubico.com/software/yubikey/tools/authenticator/auth-guide/yubico-otp.html slot-based credentials], and read OATH codes from your YubiKey.|https://developers.yubico.com/yubioath-flutter/|{{AUR|yubico-authenticator}}}}
* {{App|YubiKey Personalization|Library and tool for configuring and querying a YubiKey over the OTP USB connection. More powerful than {{ic|ykman}}, but harder to use. Has an optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}
::{{Warning|Yubico announced the End of Life of YubiKey Personalization on February 19, 2025. It will not be updated after February 19, 2026.}}

=== Authentication tools ===

* {{App|pam-u2f|[[PAM]] user authentication with [[U2F]] by Yubico. Supplement or replace password authentication with your YubiKey.|https://developers.yubico.com/pam-u2f/|{{Pkg|pam-u2f}}}}
* {{App|libfido2|Client-side U2F support. Enables web browsers to use the U2F protocol for authentication with your YubiKey.|https://developers.yubico.com/libfido2/|{{Pkg|libfido2}}}}
* {{App|YubiKey Full Disk Encryption|Use challenge-response mode to create strong LUKS passphrases. Supports full disk encryption.|https://github.com/agherzan/yubikey-full-disk-encryption|{{Pkg|yubikey-full-disk-encryption}}}}

=== Udev rules ===

{{Pkg|yubikey-personalization}} (and, by extension, {{Pkg|yubikey-personalization-gui}}) include [[udev]] rules to allows non-root users to access some of the functionality, such as OTP. Users of the other clients will need to add the following rules:

{{hc|/etc/udev/rules.d/51-yubikey.rules|2=
ACTION=="add{{!}}change", ATTRS{idVendor}=="1050", ATTRS{idProduct}=="0010{{!}}0110{{!}}0111{{!}}0114{{!}}0116{{!}}0401{{!}}0403{{!}}0405{{!}}0407{{!}}0410", ENV{ID_SECURITY_TOKEN}="1"
}}

== Inputs ==

The YubiKey takes inputs in the form of API calls over USB and button presses.

The button is very sensitive. Depending on the context, touching it does one of these things:

* Trigger a static password or one-time password (OTP) (Short press for slot 1, long press for slot 2). This is the default behavior, and easy to trigger inadvertently.
* Confirm / allow a function or access. The LED will illuminate to prompt the user.
* Insert / eject the smartcard

== Outputs ==

The YubiKey transforms these inputs into outputs:

* Keystrokes (emulating a USB keyboard), used to type static passwords and OTPs. (Note that static passwords are vulnerable to keyloggers.)
* The built-in LED:
** Blinks once when plugged in, useful for troubleshooting.
** Blinks steadily when a button press is required to permit an API response.
* API responses over USB. This is used for:
** Challenge-Response requests (calculated using either Yubico OTP mode or HMAC-SHA1 mode)
** U2F Challenge-Response requests
** CCID Smartcard related requests

== USB connection modes ==

Depending on the YubiKey model, the device provides up to three different USB interfaces. Two of the interfaces implement the USB HID (Human Interface Device) device class; the third is a smart card interface (CCID). All three can be enabled or disabled independently, allowing control of their associated protocols.

The following table shows which protocols use which interfaces:

{| class="wikitable"
! Protocol !! Interface
|-
|OTP || Keyboard HID
|-
|FIDO || Other HID
|-
|PIV || CCID
|-
|OpenPGP || CCID
|-
|OATH || CCID
|}

{{ic|ykman}} uses the term "modes", named OTP, FIDO, and CCID.

{{Note|ykman renamed "U2F" to "FIDO" in release 0.6.1 (2018-04-16). https://developers.yubico.com/yubikey-manager/Release_Notes.html}}

=== Get enabled modes ===

For YubiKey prior to version 5:

{{hc|$ ykman config mode|
Current connection mode is: OTP+FIDO+CCID
}}

{{Note|The command {{ic|ykman mode}} has been deprecated and may be removed later.}}

For YubiKey version 5:

{{hc|$ ykman info|
Device type: YubiKey 5 NFC
Serial number: XXXXXXXXX
Firmware version: 5.4.3
Form factor: Keychain (USB-A)
Enabled USB interfaces: OTP, FIDO, CCID
NFC transport is enabled.

Applications USB NFC
FIDO2 Enabled Enabled
OTP Enabled Enabled
FIDO U2F Enabled Enabled
OATH Enabled Enabled
YubiHSM Auth Enabled Enabled
OpenPGP Enabled Enabled
PIV Enabled Enabled
}}

=== Set modes ===

All modes are enabled from the factory. To change them:

$ ykman mode ''[OPTIONS]'' ''MODE''

* {{ic|''MODE''}} can be a string, such as {{ic|OTP+FIDO+CCID}}, or a shortened form {{ic|o+f+c}}.
* {{ic|''MODE''}} can be a mode-number, which encodes several enabled modes.

Here is a table of mode-numbers, if you care to use them:

{| class="wikitable"
|0||OTP device only.
|-
|1||CCID device only.
|-
|2||OTP/CCID composite device.
|-
|3||U2F device only.
|-
|4||OTP/U2F composite device.
|-
|5||U2F/CCID composite device.
|-
|6||OTP/U2F/CCID composite device.
|-
|81||CCID device only, with touch-eject.
|}

{{Note|Some examples use mode number 86, which is [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 invalid]. The 80 will be ignored, and it will behave like 6.}}

Options:

* {{ic|--touch-eject}} - The button will insert and eject the smart card. This only works if the mode is CCID only; FIDO and OTP must be disabled.
* {{ic|--autoeject-timeout ''SECONDS''}} - Automatically eject the smart card after some time. Same restrictions as {{ic|--touch-eject}}.
* {{ic|--chalresp-timeout ''SECONDS''}} - Set the challenge-response timeout.

For more information, see {{ic|ykman mode --help}}.

== One-time password ==

This feature has a somewhat misleading name, because it also encompasses the static password and challenge-response functions.

2 slots are provided for this feature, accessible by short and long button presses respectively. Each can be configured with '''one''' of the following:

* Yubico OTP
* OATH-HOTP
* OATH-TOTP
* Challenge-response
* Static Password

Each function has several configuration options provided at the time of creation, but once set they cannot be read back. It is possible to swap slots 1 and 2, with {{ic|ykman otp swap}}.

=== Factory configuration ===

On a new YubiKey, Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and on the Yubico Authentication server. This allows validating against YubiCloud, allowing the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).

{{Warning|If you ever overwrite the factory key in slot 1, you cannot create a new key of the same trust level. Factory generated Yubico OTP credentials begin with a {{ic|CC}} prefix, while user generated credentials begin with {{ic|VV}}. There is no fundamental difference in security or functionality, though some services only trust {{ic|CC}} credentials. More information can be found in this [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 forum thread].}}

=== Yubico OTP ===

The [https://developers.yubico.com/OTP/ Yubico OTP] is based on [[Wikipedia:Symmetric cryptography|symmetric cryptography]]. More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced Encryption Standard|AES]] key unique to that device, which is also stored on a validation server. When asked for a password, the YubiKey will create a token by concatenating different fields such as the ID of the key, a counter, and a random number, and encrypting the result.

This OTP is sent to the target system, which passes it to a validation server. The validation server (also in posession of the secret key) decrypts it and verifies the information inside. The result is returned to the target system, which can then decide whether to grant access.

==== Configuration and usage ====

Generate a new key in slot 2, and upload it to YubiCloud (opens in a browser):

$ ykman otp yubiotp --generate-key --upload 2

For more information, see {{ic|ykman otp yubiotp --help}}.

==== Security risks ====

===== AES key compromise =====

As you can imagine, the AES key should be kept secret. It cannot be retrieved from the YubiKey itself (or it should not, at least not with software). It is also present in the validation server, so the security of this server is very important.

===== Validation requests/responses tampering =====

Since the target system relies on a validation server, a possible attack would be to impersonate it. To prevent this, the target system needs to authenticate the validation server, either using HMAC or HTTPS.

=== Challenge-response ===

A challenge is sent to the YubiKey, which calculates a response based on some secret. The same challenge always results in the same response. Without the secret this calculation is not feasible, even with many challenge-response pairs.

This can be used for

* True 2-factor authentication: The user is provided a challenge, they must provide the correct response in addition to a password. Both parties must have the secret key.
* "Semi" 2-factor authentication: the challenge acts as a password, and the server stores the correct response. This is not an OTP, and if anyone can obtain the response they will gain access, but it is simpler as the server does not need the secret key.

There are two Challenge-Response algorithms:

* HMAC-SHA1
* Yubico OTP

You can set them up with a GUI using the {{Pkg|yubikey-personalization-gui}}, or with the following instructions:

==== HMAC-SHA1 algorithm ====

Set up slot 2 in challenge response mode with a generated key:

$ ykman otp chalresp --generate 2

You can omit the {{ic|--generate}} flag in order to provide a key, see {{ic|ykman otp chalresp --help}}. A main advantage of providing a key is that it can be used to setup a second device as a backup. The command {{ic|openssl rand -hex 20}} generates a suitable key, for example.

==== Yubico OTP algorithm ====

{{ic|ykman}} Does not appear to support setting the chal-yubico algorithm, but you can use {{ic|ykpersonalize}}. Generate a random key in slot 2:

$ ykpersonalize -2 -ochal-resp -ochal-yubico

For more information, see {{man|1|ykpersonalize}}.

==== Sending a challenge ====

To send a challenge and get a response, the {{ic|ykchalresp -''slot'' ''challenge''}} command can be used. For example,

{{hc|$ ykchalresp -2 ''archie''|
12a19763be77d75af46fb76f0b737c117fa47205
}}

returns a 40-byte SHA1-hash unique to the programmed slot 2. A different challenge produces another unique response.

=== Static password ===

You can either generate a static password:

$ ykman otp static --generate ''slot''

or provide one:

$ ykman otp static ''slot'' ''password''

You have several options; you can set the length and character set of the generated password, and whether or not to send an Enter keystroke. See {{ic|ykman otp static --help}} for more.

{{Tip|Most YubiKeys provide only limited (2) slots to save static passwords. A setup challenge-response slot provides static hash responses for unlimited challenges. While these are numeric and lower alphabet only, the response length provides considerable entropy.}}

=== Emulated USB keyboard limitations, or "Why does my password look so weak?" ===

In order for the YubiKey to work with most keyboard layouts, passwords are by default limited to the ModHex alphabet ({{ic|cbdefghijklnrtuv}}), digits {{ic|0-9}}, and {{ic|!}}. These characters use the same scan codes across a very large number of keyboard layouts, ensuring compatibility with most computers.

Yubico has provided a [https://resources.yubico.com/53ZDUYE6/as/9hccqgx9bwwqq96mhkk8jb4h/Static_Password_Function.pdf whitepaper] on the subject.

== OATH ==

The YubiKey offers 2 [[OATH]] implementations:

; OATH API: Newer method, can store approximately 30 credentials depending on the model. (YubiKey 4, NEO, and newer)
; OTP slot: Older method, both OTP slots can store a single credential. (All models which support challenge-response)

=== OATH API ===

If you prefer a GUI, you can use {{AUR|yubico-authenticator}}.

{{ic|ykman}} can add codes in the URI format with {{ic|ykman oath uri}}. Here is a one-liner that will add a credential from an image of a QR code:

$ zbarimg qr_code.png --quiet --raw | xargs ykman oath accounts uri

You can also do things manually. Program a TOTP key, requiring a button touch to generate a code:

$ ykman oath accounts add --touch ''name'' ''secret''

Program an HOTP key:

$ ykman oath accounts add --oath-type HOTP ''name'' ''secret''

List credentials:

$ ykman oath accounts list

Generate codes:

$ ykman oath accounts code ''query''

To see all available subcommands see {{ic|ykman oath --help}}. To see information about each, use {{ic|ykman oath ''subcommand'' --help}}.

=== OTP slot implementation ===

Program an HOTP in slot 2:

$ ykman otp hotp 2 ''key''

{{Tip|Options for {{ic|--digits}} and {{ic|--counter}} can be specified. They are needed to register the HOTP secret in applications.}}

Program a TOTP:

$ ykman otp chalresp --totp ''slot'' ''key''

Generate an HOTP:

$ ykman otp calculate ''slot''

Generate a TOTP:

$ ykman otp calculate --totp ''slot''

See also: {{ic|ykman otp --help}} and https://developers.yubico.com/OATH/

== U2F ==

[[Universal 2nd Factor]] (U2F) with a YubiKey is very simple, requiring no configuration for the key itself. Note that this mode is also referred to as 'FIDO' in some documentation and utilities. You have a few limited management options through the {{ic|ykman}} utility:

* Set a PIN: {{ic|ykman fido access change-pin}}
* delete individual credentials: {{ic|ykman fido credentials delete ''QUERY''}}
* Reset all credentials and PIN: {{ic|ykman fido reset}}

To use U2F for authentication, see the instructions in [[U2F]].

Also see [[WebAuthn]].

== CCID smartcard ==

CCID (Chip Card Interface Device) is a USB standard device class for use by USB devices that act as smart card readers or with security tokens that connect directly via USB, like the YubiKey. HID (Human Interface Device) and CCID are both USB device classes, i.e. they are in the same category of USB specifications. HID is a specification for computer peripherals, like keyboards. The YubiKey works like a USB (HID) keyboard when used in the OTP and FIDO modes, but switches to the CCID protocol when using the PIV application, or as an OpenPGP device.

CCID mode should be enabled by default on all YubiKeys shipped since November 2015 [https://www.yubico.com/support/knowledge-base/categories/articles/use-yubikey-yubikey-windows-hello-app/]{{Dead link|2025|04|06|status=404}}. Enable at least the CCID mode. Please see [[#Get enabled modes]].

=== PIV ===

Starting with the YubiKey NEO, the YubiKeys contain a PIV (Personal Identity Verification) application on the chip. PIV is a US government standard (FIPS 201) that specifies how a token using RSA or ECC (Elliptic Curve Cryptography) is used for personal electronic identification. The YubiKey NEO only supports RSA encryption, later models (YubiKey 4 and 5) support both RSA and ECC. The exact algorithms supported depends on the firmware. For example, only YubiKeys with firmware 5.7 and up support RSA 3072, RSA 4096, Ed25519, and X25519 keys [https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html]. The distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on-chip. A private key never leaves the token after it has been installed on it. Optionally, the private key can even be generated on-chip with the aid of an on-chip random number generator. If generated on-chip, the private key is never handled outside of the chip, and there is no way to recover it from the token. When using the PIV mechanism, the YubiKey functions as a CCID device.

=== OpenPGP smartcards ===

The YubiKey can act as a standard OpenPGP smartcard; see [[GnuPG#Smartcards]] for instructions on how to set up and use it with [[GnuPG]]. Yubico also provides some documentation in https://developers.yubico.com/PGP/.

If you do not want to use the other features (U2F and OTP), the button can be configured to insert and eject it, and an auto-eject timeout can be set as well. See [[#USB connection modes]] for more.

The default user pin is {{ic|123456}} and the default admin pin is {{ic|12345678}}. The default PUK is also {{ic|12345678}}. Remember to change all 3.

== Use cases ==

This section details how to use your YubiKey for various authentication purposes. It is by no means an exhaustive list.

=== Full disk encryption with LUKS ===

You have several options:

* '''Challenge-Response:''' the [[#Challenge-response|response]] to some challenge is used as a LUKS key. The challenge can act as a password for true 2-factor authentication, or stored in plain-text for one-factor authentication.
* '''GnuPG:''' Uses the yubikey's [[#CCID smartcard|PGP smartcard]] functionality. Offers strong 2-factor authentication without needing a huge passphrase.
* '''FIDO HMAC Secret:''' If your YubiKey supports [[U2F]], it can be configured to return a symmetric secret.

{{Note|A disk's encryption is only as strong as its weakest key. Once you configure one of these tools, consider removing the initial passphrase, or replacing it with a very long one.}}

==== Common prerequisites ====

* A bootable [[dm-crypt/Encrypting an entire system|LUKS encrypted]] system, using the {{ic|encrypt}} [[mkinitcpio]] hook, with at least one free keyslot.
** With the exception of {{AUR|mkinitcpio-ykfde}}, the {{ic|sd-encrypt}} hook is not supported by any of these tools.
* Backed up LUKS header (Optional, though advisable)

==== Challenge-response ====

See {{Pkg|yubikey-full-disk-encryption}}'s [https://github.com/agherzan/yubikey-full-disk-encryption#usage official documentation] for complete instructions. Broadly:

# Install {{Pkg|yubikey-full-disk-encryption}}.
# Configure {{ic|/etc/ykfde.conf}}.
# Enroll the disk: {{ic|# ykfde-enroll -d /dev/''DISK'' -s ''LUKS_SLOT''}}
# Add the {{ic|ykfde}} [[mkinitcpio#HOOKS|mkinitcpio hook]] before the {{ic|encrypt}} hook.
# [[Regenerate the initramfs]].

:{{Note|Plymouth users: replace the {{ic|plymouth-encrypt}} hook with the {{ic|ykfde}} hook.}}

There are a few variations available:

* 2FA: default behavior. You must provide the challenge as a password when enrolling the device, and upon boot.
* 1FA: Set {{ic|YKFDE_CHALLENGE}} in {{ic|ykfde.conf}}. Note that this is stored in plaintext. Consider disabling non-root read permissions to this file.
* [https://github.com/agherzan/yubikey-full-disk-encryption#enable-nfc-support-in-ykfde-initramfs-hook-experimental NFC support] (Experimental)
* [https://github.com/agherzan/yubikey-full-disk-encryption#enable-ykfde-suspend-service-experimental Suspend & Resume support] (Experimental) Automatically lock encrypted volumes on suspend, unlock them on resume.

You must regenerate the initramfs for any configuration changes to take effect.

==== systemd-based initramfs ====

Users of the {{ic|sd-encrypt}} hook may install {{AUR|mkinitcpio-ykfde}} or {{AUR|mkinitcpio-ykfde-git}} and follow the instruction in the [https://github.com/eworm-de/mkinitcpio-ykfde/blob/master/README-mkinitcpio.md project documentation]. The procedure is broadly similar to {{Pkg|yubikey-full-disk-encryption}}.

==== GnuPG encrypted keyfile ====

One tool to accomplish this is [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt]; see its docs for complete instructions. Note that as of October 2022 this package is not in the AUR and is not thoroughly tested, though the GitHub repository offers a PKGBUILD.

The [[dm-crypt/Specialties#Using GPG, LUKS, or OpenSSL encrypted keyfiles|dm-crypt pages]] offer a few alternatives, though they are mostly links to old forum posts.

==== HMAC secret extension of FIDO2 protocol ====

Yet another way of using YubiKey for full disk encryption is to utilize [https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-client-to-authenticator-protocol-v2.0-id-20180227.html#sctn-hmac-secret-extension HMAC Secret Extension] to retrieve the LUKS password from YubiKey. This can be protected by a passphrase. This functionality requires at least [https://support.yubico.com/hc/en-us/articles/360016649319-YubiKey-5-2-3-Enhancements-to-FIDO-2-Support YubiKey 5 with firmware 5.2.3+].
For a passphrase protected solution, install {{AUR|khefin}} and follow instructions available in [https://github.com/mjec/khefin/wiki/Arch-Linux-LUKS-configuration project documentation].
For single factor (optionally PIN-protected) solution and starting with systemd 248, it is possible to use your FIDO2 key as LUKS2 keyslot. Instructions available in the [https://0pointer.net/blog/unlocking-luks2-volumes-with-tpm2-fido2-pkcs11-security-hardware-on-systemd-248.html author's blog post].

=== KeePass ===

[[KeePass]] can be configured for YubiKey support; see the [[KeePass#Yubikey|YubiKey section]] for instructions.

=== SSH keys ===

==== CCID ====

If your YubiKey supports CCID smartcards, you can use it as a hardware-backed [[SSH key]], either based on GPG or PIV keys. Yubico offers good documentation:
* An [https://developers.yubico.com/PIV/Guides/Securing_SSH_with_OpenPGP_or_PIV.html overview of both] possibilities, giving their advantages and disadvantages
* Instructions for [https://developers.yubico.com/PGP/SSH_authentication/index.html PGP authentication]
* Instructions for [https://developers.yubico.com/PIV/Guides/SSH_user_certificates.html PIV authentication through user certificates]
* Instructions for [https://developers.yubico.com/PIV/Guides/SSH_with_PIV_and_PKCS11.html PIV authentication through #PKCS11]

:{{Note|The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it, as well as the default management key. See the [https://developers.yubico.com/PIV/Guides/Device_setup.html device setup instructions] for more.}}

==== U2F ====

You may also use the U2F feature of the YubiKey to create hardware-backed SSH keys. See [[SSH keys#FIDO/U2F]] for instructions.

==== PIV ====

{{AUR|yubikey-agent}} stores the SSH key as PIV token. See https://github.com/FiloSottile/yubikey-agent#readme for a setup guide.

=== Linux user authentication with PAM ===

[[PAM]], and therefore anything which uses PAM for user authentication, can be configured to use a YubiKey as a factor of its user authentication process. This includes sudo, su, ssh, screen lockers, display managers, and nearly every other instance where a Linux system needs to authenticate a user. Its flexible configuration allows you to set whichever authentication requirements fit your needs, for the entire system, a specific application, or for groups of applications. For example, you could accept the YubiKey as an alternative to a password for local sessions, while requiring both for remote sessions. In addition to the Arch Wiki, You are encouraged to read {{man|8|pam}} and {{man|5|pam.conf}} to understand how it works and how to configure it.

There are several modules available which integrate YubiKey-supported protocols into PAM:

* {{Pkg|pam-u2f}} - Supports [[#U2F]] via the FIDO2 standard. If you are not sure which method to use, this one is a good choice.
** [[Universal 2nd Factor#Authentication for user sessions]]
** [https://developers.yubico.com/pam-u2f/ Yubico's official docs], including a list of supported module parameters.
** Man Pages: {{man|8|pam_u2f}}, {{man|1|pamu2fcfg}}
* {{Pkg|oath-toolkit}} - Supports [[#OATH]] one-time passwords (either HOTP or TOTP)
** [[pam_oath]]
* {{Pkg|yubico-pam}} - Supports [[#Yubico OTP]] and challenge-response OTPs. Note that Yubico OTP mode requires a network connection to a validation server, while challenge-response mode does not.
** [https://developers.yubico.com/yubico-pam/ Yubico's official docs]{{Dead link|2025|03|15|status=404}}
** {{man|8|pam_yubico}} - Take note of the {{ic|mode}} parameter, used to set challenge-response mode.
::{{Warning|yubico-pam [https://github.com/Yubico/yubico-pam repository] on GitHub was archived on February 20, 2025.}}

{{Warning|Exercise caution when modifying PAM configuration files. Mistakes can render a system completely insecure, or so secure that no authentication is possible.}}

PAM configuration is beyond the scope of this article, but for a brief overview:

* Create file(s) containing authorized keys, either in users' home directories or centrally.
* Add a line in the appropriate place in the appropriate PAM configuration file which follows this format:
auth [required|sufficient] [module_name].so [module arguments]
* {{ic|auth required}} for multifactor, {{ic|auth sufficient}} for single factor.
* {{ic|module_name}} - Example: {{ic|pam_u2f.so}}. See a list of installed modules: {{ic|ls /usr/lib/security}}
* Module configuration arguments are for things like the location of the keyfile, or which method the module should use for authentication.

==== SSH notes ====

* Yubico has provided [https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html additional guidance]{{Dead link|2025|03|15|status=404}}. It is written for an old version of Ubuntu, but much of it still applies to an updated Arch system.
* If you are configuring a distant server to use YubiKey, you should open at least one additional, rescue SSH session, so that you are not locked out if the configuration fails.
* Check that {{ic|/etc/ssh/sshd_config}} contains the following settings. The {{ic|sshd_config}} shipped with {{Pkg|openssh}} has these set correctly by default.
ChallengeResponseAuthentication no
UsePAM yes

=== Browser/web integration ===

Many web services are beginning to support FIDO hardware tokens. See the [[U2F]] and [[WebAuthn]] pages for more information, but usually the only thing you need to do is to install {{Pkg|libfido2}} and [https://demo.yubico.com/webauthn-technical/registration try it].

== Tips and tricks ==

=== Executing actions on insertion/removal of YubiKey device ===

For example, you want to perform an action when you pull your YubiKey out of the USB slot, create the following:

{{hc|/etc/udev/rules.d/80-yubikey-actions.rules|2=<nowiki>
ACTION=="remove", ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", RUN+="''/usr/local/bin/script args''"
</nowiki>
}}

Please note, most keys are covered within this example but it may not work for all versions of YubiKey. You will have to look at the output of lsusb to get the vendor and model ID's, along with the description of the device or you could use udevadm to get information. Of course, to execute a script on insertion, you would change the action to 'add' instead of remove.

=== Start Yubico Authenticator on insertion ===

The authenticator is a long-running GUI process. If run directly in a udev rule, the process would block udev's processing. If forked, udev would unconditionally kill the process after the event handling finishes. Thus you cannot start the authenticator from udev rules. However, systemd.device may be used to handle this case.

Similar to above, create:

{{hc|/etc/udev/rules.d/80-yubikey-actions.rules|2=<nowiki>
ENV{ID_VENDOR}=="Yubico", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0010|0111|0112|0113|0114|0115|0116|0401|0402|0403|0404|0405|0406|0407|0410", SYMLINK+="yubikey", TAG+="systemd"
</nowiki>
}}

Then [[create]] a new systemd [[user unit]]:

{{hc|~/.config/systemd/user/yubioath-desktop.service|2=
[Unit]
Description=Autostart Yubico Authenticator
# Uncomment if you want to stop the authenticator when unplugged.
#StopPropagatedFrom=dev-yubikey.device

[Install]
WantedBy=dev-yubikey.device

[Service]
Type=oneshot
ExecStart=/usr/bin/yubioath-desktop
}}

and [[enable]] it. ''systemctl'' would warn that it is added as a dependency to a non-existent unit {{ic|dev-yubikey.device}}. But it is okay. Such unit will start existing once the YubiKey is plugged in.

== Maintenance / upgrades ==

=== Installing the OATH Applet for a YubiKey NEO ===

These steps will allow you to install the OATH applet onto your YubiKey NEO. This allows the use of Yubico Authenticator in the Google Play Store.

{{Note|1=These steps are only for NEOs with a firmware version <= 3.1.2. The current generation NEOs (with U2F) come with the OpenPGP applet already installed)}}

==== Configure the NEO as a CCID device ====

{{Out of date|yubikey-personalization-gui is dead and its repository has been archived. Apparently {{Pkg|yubikey-manager}} or {{AUR|yubico-authenticator}} are recommended alternatives. [https://lists.archlinux.org/archives/list/aur-requests@lists.archlinux.org/message/FM3Y56EOSBFTO35UMYAWIKSKK45U2FLG/]}}

# Install {{Pkg|yubikey-personalization-gui}}.
# Add the udev rules and reboot so you can manage the YubiKey without needing to be root
# Run {{ic|ykpersonalize -m82}}, enter {{ic|y}}, and hit enter.

==== Install the applet ====

# Install {{AUR|gpshell}}, {{AUR|gppcscconnectionplugin}}, {{AUR|globalplatform}}, and {{Pkg|pcsclite}}.
# [[Start]] {{ic|pcscd.service}}.
# Download the most recent CAP file from the [https://developers.yubico.com/ykneo-oath/Releases/ ykneo-oath] site.
# Download {{ic|gpinstall.txt}} from [https://github.com/Yubico/ykneo-oath/blob/master/gpinstall.txt GitHub].
# Edit the line in gpinstall.txt beginning with {{ic|install -file}} to reflect the path where the CAP file is located.
# Open a terminal and run {{ic|gpshell ''path/to/gpinstall.txt''}}.
# Ideally, a bunch of text will scroll by and it ends saying something like{{bc|<nowiki>Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A100
Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A15D848CB77
27D0EDA00
Response <-- 009000
Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000
Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00
Response <-- 009000
card_disconnect
release_context</nowiki>}}
# Unplug the NEO and try it with the Yubico Authenticator app.

==== (Optional) Install the Yubico Authenticator desktop client ====

{{Out of date|Package got merged into {{AUR|yubico-authenticator}}.}}

You can get the desktop version of the Yubico Authenticator by installing {{AUR|yubioath-desktop}}{{Broken package link|package not found}}.

While {{ic|pcscd.service}} is running, run {{ic|yubioath-desktop}} and insert your YubiKey when prompted.

== Troubleshooting ==

Restart, especially if you have completed updates since your YubiKey last worked. Do this even if some functions appear to be functioning.

=== YubiKey not acting as HID device ===

{{Note|1=These steps are no longer necessary after [https://github.com/systemd/systemd/commit/d45ee2f31a8358db0accde2e7c81777cedadc3c2 systemd since v244] added native support for this functionality.}}

Add udev rule as described in [https://michaelheap.com/yubikey-on-arch/ this article]:

{{hc|/etc/udev/rules.d/10-security-key.rules|2=
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="users", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0"
}}

Run {{ic|udevadm trigger}} afterwards.

=== ykman fails to connect to the YubiKey ===

If the manager fails to connect to the YubiKey, make sure you have started {{ic|pcscd.service}} or {{ic|pcscd.socket}}.

=== Error: Failed connecting to YubiKey 5 [OTP+FIDO+CCID]. Make sure the application have the required permissions. ===

This can occur when using {{ic|ykman}} to access the oath credentials on the device if {{ic|scdaemon}} has already taken exclusive control of the device. [https://github.com/Yubico/yubikey-manager/issues/35]

To fix this you can set the {{ic|reader-port}} option with the correct value for your device in {{ic|~/.gnupg/scdaemon.conf}}. [https://support.yubico.com/hc/en-us/articles/360013714479-Troubleshooting-Issues-with-GPG]

{{Note|This will cause the gpgagent to re-prompt you to unlock the YubiKey after each time you access the YubiKey through ykman.}}

For YubiKey NEO and YubiKey 4:

reader-port Yubico Yubikey

or for YubiKey 5:

reader-port Yubico Yubi

=== YubiKey fails to bind within a guest VM ===

Assuming the YubiKey is available to the guest, the issue results from a driver binding to the device on the host. To unbind the device, the bus and port information is needed from [[dmesg]] on the host:

# dmesg | grep -B1 Yubico | tail -n 2 | head -n 1 | sed -E 's/^\<nowiki>[[^]]</nowiki>+\] usb (<nowiki>[^:]</nowiki>*):.*/\1/'

The resulting USB id should be of the form {{ic|X-Y.Z}} or {{ic|X-Y}}. Then, on the host, use {{ic|find}} to search {{ic|/sys/bus/usb/drivers}} for which driver the YubiKey is binded to (e.g. {{ic|usbhid}} or {{ic|usbfs}}).

$ find /sys/bus/usb/drivers -name "*X-Y.Z*"

To unbind the device, use the result from the previous command (i.e. {{ic|/sys/bus/usb/drivers/''DRIVER''/X-Y.Z:1.0}}):

# echo 'X-Y.Z:1.0' > /sys/bus/usb/drivers/''DRIVER''/unbind

=== Error: [key] could not be locally signed or gpg: No default secret key: No public key ===

Occurs when attempting to sign keys on a non-standard keyring while a YubiKey is plugged in, e.g. as [[pacman/Package signing|Pacman]] does in {{ic|pacman-key --populate}}. The solution is to remove the offending YubiKey and start over.

=== YubiKey disappears and reappears in Yubico Authenticator ===

This happens when the CCID driver is not installed. You may need to [[install]] the {{Pkg|ccid}} package.

=== YubiKey core error: timeout ===

You are probably using the wrong slot. Try the other one.

=== gpg: no such device ===

gpg (scdaemon) tries to acquire exclusive access to the yubikey. It needs to be configured to use PSCS and use shared access.[https://blog.apdu.fr/posts/2024/12/gnupg-and-pcsc-conflicts-episode-3/][https://github.com/LudovicRousseau/PCSC/issues/65]

Your configuration file should contain:

{{hc|~/.gnupg/scdaemon.conf|
disable-ccid
pcsc-shared
}}

For old versions of GnuPG, the {{ic|pcsc-shared}} option is not available. Only keep {{ic|disable-ccid}} and [[restart]] {{ic|pcscd.service}} as a workaround.

Common Access Card

2026-05-05T17:44:16Z

Indigo: /* See also */ update dead link

[[Category:Smartcards]]
{{Related articles start}}
{{Related|Smartcards}}
{{Related articles end}}
This page explains how to setup Arch to use a US Department of Defense [[wikipedia:Common_Access_Card|Common Access Card]] (CAC).

== Installation ==

Install {{Pkg|ccid}} and {{Pkg|opensc}}.

=== Configuration ===

{{Note|You should not have to edit your opensc configuration files by default. You should check all other setup items first (e.g. certificate imports)}}

If your card reader does not have a pin pad, [[append]] {{ic|1=enable_pinpad = false}} to {{ic|/etc/opensc.conf}}.

Sometimes {{Pkg|opensc}} can struggle to identify the proper driver for CAC, instead it may choose PIV or something else. You can force the CAC driver by editing {{ic|/etc/opensc.conf}} for {{ic|1=card_drivers = cac}} and {{ic|1=force_card_driver = cac}}

== Enable pcscd ==

[[Start/enable]] {{ic|pcscd.socket}}.

== Configure browser ==

# Go to: https://www.cyber.mil/pki-pke/document-library
# Download certs: ''"PKI CA Certificate Bundles: PKCS#7 For DoD PKI Only - Version 5.14"'' (ZIP Download)
# Unzip the DoD PKI zip
# Follow browser-specific instructions

=== Firefox ===

==== Load security device ====

Navigate to ''Edit > Settings > Privacy & Security > Certificates > Security Devices'' and click "Load" to load a module using {{ic|/usr/lib/opensc-pkcs11.so}} or {{ic|/usr/lib/pkcs11/opensc-pkcs11.so}}.

{{Note|Firefox may report the module did not load correctly however you will have to check in the security devices to confirm whether the module properly loaded or not}}

==== Import the DoD Certificates ====

Install the certificates from the mentioned zip-file in ''this'' order, by going to ''Edit > Settings > Privacy & Security > Certificates > Manage Certificates > Authorities > Import'' (make sure to at-least check the box for "Trust this CA to identify websites"):

{{Note|As of the 5.14 version of the certificate zip}}

# Certificates_PKCS7_v5_14_DoD_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_3_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_4_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_5_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_6_der.p7b
# DOD_PKE_Chain.pem

=== Chromium/Google Chrome ===

1. Add the CAC Module to the NSS DB.

Ensure that your CAC is connected, that [[Chromium]] is closed and enter the following in a terminal:
{{ic|<nowiki>$ modutil -dbdir sql:$HOME/.pki/nssdb/ -add "CAC Module" -libfile /usr/lib/opensc-pkcs11.so</nowiki>}}
{{Note|You may see the message 'Failure to load dynamic library'. This can be ignored.}}
Upon success you will see "Module "CAC Module" added to database."

2. Check if the CAC Module was successfully added with {{ic|<nowiki>$ modutil -dbdir sql:$HOME/.pki/nssdb/ -list</nowiki>}}

3. Navigate (in a shell) to the location of the unzipped DoD PKI files and install via:

for n in *der.p7b; do certutil -d sql:$HOME/.pki/nssdb -A -t TC -n $n -i $n; done

or

Re-open Chrome, Navigate to ''Settings > Show Advanced Settings > Manage Certificates > Authorities'' to load CA bundle from the PEM-formatted file from above.

4. Verify the authority is in Chrome under ''Settings > Show Advanced Settings > Manage Certificates > Authorities'' then expand "org-U.S. Government" and you should see a number of "DoD" certificates listed.

== VMware/Omnissa Horizon Client ==
Please note that Omnissa purchased the horizon-view solution from VMware.

===Omnissa:===

Install {{AUR|omnissa-horizon-client}}, and {{AUR|omnissa-horizon-usb}}.
To integrate CAC authentication with the VMware Horizon Client, create the directory {{ic|/usr/lib/omnissa/horizon/pkcs11}} and link the pkcs11 library:

# ln -s /usr/lib/pkcs11/opensc-pkcs11.so /usr/lib/omnissa/horizon/pkcs11/libopenscpkcs11.so
Also create the following symlinks to enable ssl_3.4.0.
# ln -sf /usr/lib/libcrypto.so.3 /usr/lib/omnissa/libcrypto.so.3
# ln -sf /usr/lib/libssl.so.3 /usr/lib/omnissa/libssl.so.3

If utilizing an external CAC reader, the following command must be utilized
# sudo systemctl enable --now horizon-usb.service

===VMware:===
Install {{AUR|vmware-horizon-client}}, {{AUR|vmware-horizon-usb}}, and {{AUR|vmware-horizon-smartcard}}. [[Start]] and [[enable]] {{ic|vmware-horizon-usb.service}}.

To integrate CAC authentication with the VMware Horizon Client, create the directory {{ic|/usr/lib/vmware/view/pkcs11}} and link the pkcs11 library:

# ln -s /usr/lib/pkcs11/opensc-pkcs11.so /usr/lib/vmware/view/pkcs11/libopenscpkcs11.so
Also create the following symlinks to enable ssl_3.4.0
# ln -sf /usr/lib/libcrypto.so.3 /usr/lib/vmware/libcrypto.so.3
# ln -sf /usr/lib/libssl.so.3 /usr/lib/vmware/libssl.so.3

== Testing ==

Visit your favorite CAC secured web page and you should be asked for the ''Master Password'' for your certificate. Enter it and if you get in, you know it is working.

If some sites/pages seem to have a problem working correctly (e.g. outlook web access will not authenticate the session for DoD webmail) try using a private/incognito session to test validity of the cert chain and remove some variables.

If you would like to manually query the certificates on a PIN enabled CAC/SmartCard, use the following command:

$ p11tool --login --provider=/usr/lib/pkcs11/opensc-pkcs11.so --list-all-certs -d 100

== Debugging ==

=== opensc-tool ===

Most of this information was found in a [https://web.archive.org/web/20200505031254/http://blog.fkraiem.org/2013/03/13/linux-smart-card-authentication-howto/ blog post by Firas Kraïem]

Verify {{Pkg|opensc}} can see your reader:

{{hc|$ opensc-tool --list-readers |
# Detected readers (pcsc)
Nr. Card Features Name
0 Yes Generic USB2.0-CRW [Smart Card Reader Interface] (20070818000000000) 00 00
}}

List plugged in card:

{{hc|$ opensc-tool --reader 0 --name |Personal Identity Verification Card}}

List plugged in card and drive in use:

{{hc|$ opensc-tool --reader 0 --name -v|
Connecting to card in reader Generic USB2.0-CRW [Smart Card Reader Interface] (20070818000000000) 00 00...
Using card driver Personal Identity Verification Card.
Card name: Personal Identity Verification Card
}}

=== pcsc-tools ===

An other option is {{Pkg|pcsc-tools}}. The program {{ic|pcsc_scan}} may be helpful

{{hc|$ pcsc_scan|<nowiki>
PC/SC device scanner
V 1.4.21 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.8.6
Using reader plug'n play mechanism
Scanning present readers...
0: Dell Dell Smart Card Reader Keyboard 00 00

Thu Sep 5 10:41:53 2013
Reader 0: Dell Dell Smart Card Reader Keyboard 00 00
Card state: Card removed,

Thu Sep 5 10:41:58 2013
Reader 0: Dell Dell Smart Card Reader Keyboard 00 00
Card state: Card inserted,
ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80

ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
+ TS = 3B --> Direct Convention
+ T0 = DB, Y(1): 1101, K: 11 (historical bytes)
TA(1) = 96 --> Fi=512, Di=32, 16 cycles/ETU
250000 bits/s at 4 MHz, fMax for Fi = 5 MHz => 312500 bits/s
TC(1) = 00 --> Extra guard time: 0
TD(1) = 80 --> Y(i+1) = 1000, Protocol T = 0
-----
TD(2) = 1F --> Y(i+1) = 0001, Protocol T = 15 - Global interface bytes following
-----
TA(3) = 03 --> Clock stop: not supported - Class accepted by the card: (3G) A 5V B 3V
+ Historical bytes: 00 31 C0 64 B0 F3 10 00 07 90 00
Category indicator byte: 00 (compact TLV data object)
Tag: 3, len: 1 (card service data byte)
Card service data byte: C0
- Application selection: by full DF name
- Application selection: by partial DF name
- EF.DIR and EF.ATR access services: by GET RECORD(s) command
- Card with MF
Tag: 6, len: 4 (pre-issuing data)
Data: B0 F3 10 00
Mandatory status indicator (3 last bytes)
LCS (life card cycle): 07 (Operational state (activated))
SW: 9000 (Normal processing.)
+ TCK = 80 (correct checksum)

Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
DoD CAC, Oberthur ID One 128 v5.5 Dual
</nowiki>}}

== See also ==

* [https://www.idmanagement.gov/university/piv/ PIV Usage Guides]

Common Access Card

2026-05-05T17:39:06Z

Indigo: /* Omnissa: */ apply Help:Style/White space

[[Category:Smartcards]]
{{Related articles start}}
{{Related|Smartcards}}
{{Related articles end}}
This page explains how to setup Arch to use a US Department of Defense [[wikipedia:Common_Access_Card|Common Access Card]] (CAC).

== Installation ==

Install {{Pkg|ccid}} and {{Pkg|opensc}}.

=== Configuration ===

{{Note|You should not have to edit your opensc configuration files by default. You should check all other setup items first (e.g. certificate imports)}}

If your card reader does not have a pin pad, [[append]] {{ic|1=enable_pinpad = false}} to {{ic|/etc/opensc.conf}}.

Sometimes {{Pkg|opensc}} can struggle to identify the proper driver for CAC, instead it may choose PIV or something else. You can force the CAC driver by editing {{ic|/etc/opensc.conf}} for {{ic|1=card_drivers = cac}} and {{ic|1=force_card_driver = cac}}

== Enable pcscd ==

[[Start/enable]] {{ic|pcscd.socket}}.

== Configure browser ==

# Go to: https://www.cyber.mil/pki-pke/document-library
# Download certs: ''"PKI CA Certificate Bundles: PKCS#7 For DoD PKI Only - Version 5.14"'' (ZIP Download)
# Unzip the DoD PKI zip
# Follow browser-specific instructions

=== Firefox ===

==== Load security device ====

Navigate to ''Edit > Settings > Privacy & Security > Certificates > Security Devices'' and click "Load" to load a module using {{ic|/usr/lib/opensc-pkcs11.so}} or {{ic|/usr/lib/pkcs11/opensc-pkcs11.so}}.

{{Note|Firefox may report the module did not load correctly however you will have to check in the security devices to confirm whether the module properly loaded or not}}

==== Import the DoD Certificates ====

Install the certificates from the mentioned zip-file in ''this'' order, by going to ''Edit > Settings > Privacy & Security > Certificates > Manage Certificates > Authorities > Import'' (make sure to at-least check the box for "Trust this CA to identify websites"):

{{Note|As of the 5.14 version of the certificate zip}}

# Certificates_PKCS7_v5_14_DoD_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_3_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_4_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_5_der.p7b
# Certificates_PKCS7_v5_14_DoD_DoD_Root_CA_6_der.p7b
# DOD_PKE_Chain.pem

=== Chromium/Google Chrome ===

1. Add the CAC Module to the NSS DB.

Ensure that your CAC is connected, that [[Chromium]] is closed and enter the following in a terminal:
{{ic|<nowiki>$ modutil -dbdir sql:$HOME/.pki/nssdb/ -add "CAC Module" -libfile /usr/lib/opensc-pkcs11.so</nowiki>}}
{{Note|You may see the message 'Failure to load dynamic library'. This can be ignored.}}
Upon success you will see "Module "CAC Module" added to database."

2. Check if the CAC Module was successfully added with {{ic|<nowiki>$ modutil -dbdir sql:$HOME/.pki/nssdb/ -list</nowiki>}}

3. Navigate (in a shell) to the location of the unzipped DoD PKI files and install via:

for n in *der.p7b; do certutil -d sql:$HOME/.pki/nssdb -A -t TC -n $n -i $n; done

or

Re-open Chrome, Navigate to ''Settings > Show Advanced Settings > Manage Certificates > Authorities'' to load CA bundle from the PEM-formatted file from above.

4. Verify the authority is in Chrome under ''Settings > Show Advanced Settings > Manage Certificates > Authorities'' then expand "org-U.S. Government" and you should see a number of "DoD" certificates listed.

== VMware/Omnissa Horizon Client ==
Please note that Omnissa purchased the horizon-view solution from VMware.

===Omnissa:===

Install {{AUR|omnissa-horizon-client}}, and {{AUR|omnissa-horizon-usb}}.
To integrate CAC authentication with the VMware Horizon Client, create the directory {{ic|/usr/lib/omnissa/horizon/pkcs11}} and link the pkcs11 library:

# ln -s /usr/lib/pkcs11/opensc-pkcs11.so /usr/lib/omnissa/horizon/pkcs11/libopenscpkcs11.so
Also create the following symlinks to enable ssl_3.4.0.
# ln -sf /usr/lib/libcrypto.so.3 /usr/lib/omnissa/libcrypto.so.3
# ln -sf /usr/lib/libssl.so.3 /usr/lib/omnissa/libssl.so.3

If utilizing an external CAC reader, the following command must be utilized
# sudo systemctl enable --now horizon-usb.service

===VMware:===
Install {{AUR|vmware-horizon-client}}, {{AUR|vmware-horizon-usb}}, and {{AUR|vmware-horizon-smartcard}}. [[Start]] and [[enable]] {{ic|vmware-horizon-usb.service}}.

To integrate CAC authentication with the VMware Horizon Client, create the directory {{ic|/usr/lib/vmware/view/pkcs11}} and link the pkcs11 library:

# ln -s /usr/lib/pkcs11/opensc-pkcs11.so /usr/lib/vmware/view/pkcs11/libopenscpkcs11.so
Also create the following symlinks to enable ssl_3.4.0
# ln -sf /usr/lib/libcrypto.so.3 /usr/lib/vmware/libcrypto.so.3
# ln -sf /usr/lib/libssl.so.3 /usr/lib/vmware/libssl.so.3

== Testing ==

Visit your favorite CAC secured web page and you should be asked for the ''Master Password'' for your certificate. Enter it and if you get in, you know it is working.

If some sites/pages seem to have a problem working correctly (e.g. outlook web access will not authenticate the session for DoD webmail) try using a private/incognito session to test validity of the cert chain and remove some variables.

If you would like to manually query the certificates on a PIN enabled CAC/SmartCard, use the following command:

$ p11tool --login --provider=/usr/lib/pkcs11/opensc-pkcs11.so --list-all-certs -d 100

== Debugging ==

=== opensc-tool ===

Most of this information was found in a [https://web.archive.org/web/20200505031254/http://blog.fkraiem.org/2013/03/13/linux-smart-card-authentication-howto/ blog post by Firas Kraïem]

Verify {{Pkg|opensc}} can see your reader:

{{hc|$ opensc-tool --list-readers |
# Detected readers (pcsc)
Nr. Card Features Name
0 Yes Generic USB2.0-CRW [Smart Card Reader Interface] (20070818000000000) 00 00
}}

List plugged in card:

{{hc|$ opensc-tool --reader 0 --name |Personal Identity Verification Card}}

List plugged in card and drive in use:

{{hc|$ opensc-tool --reader 0 --name -v|
Connecting to card in reader Generic USB2.0-CRW [Smart Card Reader Interface] (20070818000000000) 00 00...
Using card driver Personal Identity Verification Card.
Card name: Personal Identity Verification Card
}}

=== pcsc-tools ===

An other option is {{Pkg|pcsc-tools}}. The program {{ic|pcsc_scan}} may be helpful

{{hc|$ pcsc_scan|<nowiki>
PC/SC device scanner
V 1.4.21 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.8.6
Using reader plug'n play mechanism
Scanning present readers...
0: Dell Dell Smart Card Reader Keyboard 00 00

Thu Sep 5 10:41:53 2013
Reader 0: Dell Dell Smart Card Reader Keyboard 00 00
Card state: Card removed,

Thu Sep 5 10:41:58 2013
Reader 0: Dell Dell Smart Card Reader Keyboard 00 00
Card state: Card inserted,
ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80

ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
+ TS = 3B --> Direct Convention
+ T0 = DB, Y(1): 1101, K: 11 (historical bytes)
TA(1) = 96 --> Fi=512, Di=32, 16 cycles/ETU
250000 bits/s at 4 MHz, fMax for Fi = 5 MHz => 312500 bits/s
TC(1) = 00 --> Extra guard time: 0
TD(1) = 80 --> Y(i+1) = 1000, Protocol T = 0
-----
TD(2) = 1F --> Y(i+1) = 0001, Protocol T = 15 - Global interface bytes following
-----
TA(3) = 03 --> Clock stop: not supported - Class accepted by the card: (3G) A 5V B 3V
+ Historical bytes: 00 31 C0 64 B0 F3 10 00 07 90 00
Category indicator byte: 00 (compact TLV data object)
Tag: 3, len: 1 (card service data byte)
Card service data byte: C0
- Application selection: by full DF name
- Application selection: by partial DF name
- EF.DIR and EF.ATR access services: by GET RECORD(s) command
- Card with MF
Tag: 6, len: 4 (pre-issuing data)
Data: B0 F3 10 00
Mandatory status indicator (3 last bytes)
LCS (life card cycle): 07 (Operational state (activated))
SW: 9000 (Normal processing.)
+ TCK = 80 (correct checksum)

Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
DoD CAC, Oberthur ID One 128 v5.5 Dual
</nowiki>}}

== See also ==

* [https://piv.idmanagement.gov/engineering/ PIV Usage Guides]{{Dead link|2023|09|16|status=404}}