https://wiki.archlinux.org/api.php?action=feedcontributions&user=Simon04&feedformat=atomArchWiki - User contributions [en]2024-03-28T09:14:55ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=OpenSSH&diff=764226OpenSSH2023-01-15T23:14:37Z<p>Simon04: /* Network specific configuration */ add example for ProxyJump</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[Category:Servers]]<br />
[[Category:OpenBSD]]<br />
[[de:SSH]]<br />
[[es:OpenSSH]]<br />
[[fa:SSH]]<br />
[[fr:OpenSSH]]<br />
[[ja:OpenSSH]]<br />
[[pt:Secure Shell]]<br />
[[ru:OpenSSH]]<br />
[[zh-hans:OpenSSH]]<br />
{{Related articles start}}<br />
{{Related|SSH keys}}<br />
{{Related|Pam abl}}<br />
{{Related|fail2ban}}<br />
{{Related|sshguard}}<br />
{{Related|Sshfs}}<br />
{{Related|Syslog-ng}}<br />
{{Related|SFTP chroot}}<br />
{{Related|SCP and SFTP}}<br />
{{Related|VPN over SSH}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:OpenSSH|OpenSSH]] (OpenBSD Secure Shell) is a set of computer programs providing encrypted communication sessions over a computer network using the [[Secure Shell]] (SSH) protocol. It was created as an open source alternative to the proprietary Secure Shell software suite offered by SSH Communications Security. OpenSSH is developed as part of the OpenBSD project, which is led by Theo de Raadt.<br />
<br />
OpenSSH is occasionally confused with the similarly-named OpenSSL; however, the projects have different purposes and are developed by different teams, the similar name is drawn only from similar goals.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|openssh}} package.<br />
<br />
== Client usage ==<br />
<br />
To connect to a server, run:<br />
<br />
$ ssh -p ''port'' ''user''@''server-address''<br />
<br />
If the server only allows public-key authentication, follow [[SSH keys]].<br />
<br />
=== Configuration ===<br />
<br />
The client can be configured to store common options and hosts. All options can be declared globally or restricted to specific hosts. For example:<br />
<br />
{{hc|~/.ssh/config|# global options<br />
User ''user''<br />
<br />
# host-specific options<br />
Host ''myserver''<br />
Hostname ''server-address''<br />
Port ''port''<br />
}}<br />
<br />
With such a configuration, the following commands are equivalent<br />
<br />
$ ssh -p ''port'' ''user''@''server-address''<br />
$ ssh ''myserver''<br />
<br />
See {{man|5|ssh_config}} for more information.<br />
<br />
Some options do not have command line switch equivalents, but you can specify configuration options on the command line with {{ic|-o}}. For example {{ic|1=-oKexAlgorithms=+diffie-hellman-group1-sha1}}.<br />
<br />
== Server usage ==<br />
<br />
{{ic|sshd}} is the OpenSSH server daemon, configured with {{ic|/etc/ssh/sshd_config}} and managed by {{ic|sshd.service}}. Whenever changing the configuration, use {{ic|sshd}} in test mode before restarting the service to ensure it will be able to start cleanly. Valid configurations produce no output.<br />
<br />
# sshd -t<br />
<br />
=== Configuration ===<br />
<br />
To allow access only for some users, add this line:<br />
<br />
AllowUsers ''user1 user2''<br />
<br />
To allow access only for some groups:<br />
<br />
AllowGroups ''group1 group2''<br />
<br />
To add a nice welcome message (e.g. from the {{ic|/etc/issue}} file), configure the {{ic|Banner}} option:<br />
<br />
Banner /etc/issue<br />
<br />
Public and private host keys are automatically generated in {{ic|/etc/ssh}} by the ''sshdgenkeys'' [[#Daemon management|service]] and regenerated if missing even if {{ic|HostKeyAlgorithms}} option in {{ic|sshd_config}} allows only some. Four key pairs are provided based on the algorithms [[SSH keys#Choosing the authentication key type|dsa, rsa, ecdsa and ed25519]]. To have sshd use a particular key, specify the following option:<br />
<br />
HostKey /etc/ssh/ssh_host_rsa_key<br />
<br />
If the server is to be exposed to the WAN, it is recommended to change the default port from 22 to a random higher one like this:<br />
Port 39901<br />
<br />
{{Tip|<br />
* To help select an alternative port that is not already assigned to a common service, review the [[Wikipedia:List of TCP and UDP port numbers|list of TCP and UDP port numbers]]. You can also find port information locally in {{ic|/etc/services}}. A port change from default port 22 will reduce the number of log entries caused by automated authentication attempts but will not eliminate them. See [[Port knocking]] for related information.<br />
* It is recommended to disable password logins entirely. This will greatly increase security, see [[#Force public key authentication]] for more information. See [[#Protection]] for more recommend security methods.<br />
* OpenSSH can listen to multiple ports simply by having multiple {{ic|Port ''port_number''}} lines in the configuration file.<br />
* New (or missing) host key pairs can be generated by removing the pair(s) that you want to replace from {{ic|/etc/ssh}} and running {{ic|ssh-keygen -A}} as root.<br />
}}<br />
<br />
=== Daemon management ===<br />
<br />
[[Start/enable]] {{ic|sshd.service}}. It will keep the SSH daemon permanently active and fork for each incoming connection.[https://github.com/archlinux/svntogit-packages/blob/packages/openssh/trunk/sshd.service]<br />
<br />
{{Note|{{Pkg|openssh}} 8.0p1-3 removed {{ic|sshd.socket}} that used systemd's socket activation due to it being susceptible to denial of service. See {{Bug|62248}} for details. If {{ic|sshd.socket}} is enabled when updating to {{Pkg|openssh}} 8.0p1-3, the {{ic|sshd.socket}} and {{ic|sshd@.service}} units will be copied to {{ic|/etc/systemd/system/}} and [[reenable]]d. This is only done to not break existing setups; users are still advised to migrate to {{ic|sshd.service}}.}}<br />
<br />
{{Warning|If you continue using {{ic|sshd.socket}}, be aware of its issues:<br />
* {{ic|sshd.socket}} unit may fail (e.g. due to out-of-memory situation) and {{ic|1=Restart=always}} cannot be specified on socket units. See [https://github.com/systemd/systemd/issues/11553 systemd issue 11553].<br />
* Using socket activation can result in denial of service, as too many connections can cause refusal to further activate the service. See {{Bug|62248}}.<br />
}}<br />
<br />
{{Note|Using {{ic|sshd.socket}} negates the {{ic|ListenAddress}} setting, so it will allow connections over any address. To achieve the effect of setting {{ic|ListenAddress}}, you must specify the port ''and'' IP for {{ic|ListenStream}} (e.g. {{ic|1=ListenStream=192.168.1.100:22}}) by [[edit]]ing {{ic|sshd.socket}}. You must also add {{ic|1=FreeBind=true}} under {{ic|[Socket]}} or else setting the IP address will have the same drawback as setting {{ic|ListenAddress}}: the socket will fail to start if the network is not up in time.}}<br />
<br />
{{Tip|When using socket activation, a transient instance of {{ic|sshd@.service}} will be started for each connection (with different instance names). Therefore, neither {{ic|sshd.socket}} nor the daemon's regular {{ic|sshd.service}} allow to monitor connection attempts in the log. The logs of socket-activated instances of SSH can be seen by running {{ic|journalctl -u "sshd@*"}} as root or by running {{ic|journalctl /usr/bin/sshd}} as root.}}<br />
<br />
=== Protection ===<br />
<br />
Allowing remote log-on through SSH is good for administrative purposes, but can pose a threat to your server's security. Often the target of brute force attacks, SSH access needs to be limited properly to prevent third parties gaining access to your server.<br />
<br />
{{Pkg|ssh-audit}} offers an automated analysis of server and client configuration. Several other good guides and tools are available on the topic, for example:<br />
<br />
* [[MozillaWiki:Security/Guidelines/OpenSSH|Article by Mozilla Infosec Team]]<br />
* [https://www.ssh-audit.com/hardening_guides.html SSH Hardening Guides]<br />
<br />
==== Force public key authentication ====<br />
<br />
If a client cannot authenticate through a public key, by default, the SSH server falls back to password authentication, thus allowing a malicious user to attempt to gain access by [[#Protecting against brute force attacks|brute-forcing]] the password. One of the most effective ways to protect against this attack is to disable password logins entirely, and force the use of [[SSH keys]]. This can be accomplished by setting the following options in the daemon configuration file:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
PasswordAuthentication no<br />
AuthenticationMethods publickey<br />
}}<br />
<br />
{{Warning|Before adding this to your configuration, make sure that all accounts which require SSH access have public-key authentication set up in the corresponding {{ic|authorized_keys}} files. See [[SSH keys#Copying the public key to the remote server]] for more information.}}<br />
<br />
==== Two-factor authentication and public keys ====<br />
<br />
SSH can be set up to require multiple ways of authentication; you can tell which authentication methods are required using the {{ic|AuthenticationMethods}} option. This enables you to use public keys as well as a two-factor authorization.<br />
<br />
===== Authentication providers =====<br />
<br />
See [[Google Authenticator]] to set up Google Authenticator.<br />
<br />
For [https://duo.com/ Duo], [[install]] {{AUR|duo_unix}} which will supply the {{ic|pam_duo.so}} module. Read the [https://duo.com/docs/duounix Duo Unix documentation] for instructions on how to setup the necessary Duo credentials (Integration Key, Secret Key, API Hostname).<br />
<br />
===== PAM setup =====<br />
<br />
To use [[PAM]] with OpenSSH, edit the following files:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
KbdInteractiveAuthentication yes<br />
AuthenticationMethods publickey keyboard-interactive:pam<br />
}}<br />
<br />
Then you can log in with either a publickey '''or''' the user authentication as required by your PAM setup.<br />
<br />
If, on the other hand, you want to authenticate the user on both a publickey '''and''' the user authentication as required by your PAM setup, use a comma instead of a space to separate the AuthenticationMethods:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
KbdInteractiveAuthentication yes<br />
AuthenticationMethods publickey''','''keyboard-interactive:pam<br />
}}<br />
<br />
With required pubkey '''and''' pam authentication, you may wish to disable the password requirement:<br />
<br />
{{hc|/etc/pam.d/sshd|<br />
auth required pam_securetty.so #disable remote root<br />
#Require google authenticator<br />
auth required pam_google_authenticator.so<br />
#But not password<br />
#auth include system-remote-login<br />
account include system-remote-login<br />
password include system-remote-login<br />
session include system-remote-login<br />
}}<br />
<br />
==== Protecting against brute force attacks ====<br />
<br />
Brute forcing is a simple concept: one continuously tries to log in to a webpage or server log-in prompt like SSH with a high number of random username and password combinations.<br />
<br />
See [[ufw#Rate limiting with ufw]] or [[Simple stateful firewall#Bruteforce attacks]] for [[iptables]].<br />
<br />
Alternatively, you can protect yourself from brute force attacks by using an automated script that blocks anybody trying to brute force their way in, for example [[fail2ban]] or [[sshguard]].<br />
<br />
* Only allow incoming SSH connections from trusted locations<br />
* Use [[fail2ban]] or [[sshguard]] to automatically block IP addresses that fail password authentication too many times.<br />
* Use [https://github.com/jtniehof/pam_shield pam_shield] to block IP addresses that perform too many login attempts within a certain period of time. In contrast to [[fail2ban]] or [[sshguard]], this program does not take login success or failure into account.<br />
<br />
==== Limit root login ====<br />
<br />
{{Out of date|Root login has been disabled by default upstream in the current version. Unclear to me what parts of this section and subsections are redundant.}}<br />
<br />
It is generally considered bad practice to allow the root user to log in without restraint over SSH. There are two methods by which SSH root access can be restricted for increased security.<br />
<br />
===== Deny =====<br />
<br />
Sudo selectively provides root rights for actions requiring these without requiring authenticating against the root account. This allows locking the root account against access via SSH and potentially functions as a security measure against brute force attacks, since now an attacker must guess the account name in addition to the password.<br />
<br />
SSH can be configured to deny remote logins with the root user by editing the "Authentication" section in the daemon configuration file. Simply set {{ic|PermitRootLogin}} to {{ic|no}}:<br />
<br />
{{hc|/etc/ssh/sshd_config|PermitRootLogin no}}<br />
<br />
Next, [[restart]] the SSH daemon.<br />
<br />
You will now be unable to log in through SSH under root, but will still be able to log in with your normal user and use [[su]] or [[sudo]] to do system administration.<br />
<br />
===== Restrict =====<br />
<br />
Some automated tasks such as remote, full-system backup require full root access. To allow these in a secure way, instead of disabling root login via SSH, it is possible to only allow root logins for selected commands. This can be achieved by editing {{ic|~root/.ssh/authorized_keys}}, by prefixing the desired key, e.g. as follows:<br />
<br />
command="/usr/lib/rsync/rrsync -ro /" ssh-rsa …<br />
<br />
This will allow any login with this specific key only to execute the command specified between the quotes.<br />
<br />
The increased attack surface created by exposing the root user name at login can be compensated by adding the following to {{ic|sshd_config}}:<br />
<br />
PermitRootLogin forced-commands-only<br />
<br />
This setting will not only restrict the commands which root may execute via SSH, but it will also disable the use of passwords, forcing use of public key authentication for the root account.<br />
<br />
A slightly less restrictive alternative will allow any command for root, but makes brute force attacks infeasible by enforcing public key authentication. For this option, set:<br />
<br />
PermitRootLogin prohibit-password<br />
<br />
==== Locking the authorized_keys file ====<br />
<br />
{{Warning|Locking this file only protects against user mistakes and a particular naive in-person attack. It '''does not''' provide any protection against malicious programs or breaches. Use multi-factor authentication, firewalling and practice defence in depth to prevent breaches in the first place.}}<br />
<br />
If, for whatever reason, you think that the user in question should not be able to add or change existing keys, you can prevent them from manipulating the file.<br />
<br />
On the server, make the {{ic|authorized_keys}} file read-only for the user and deny all other permissions:<br />
<br />
$ chmod 400 ~/.ssh/authorized_keys<br />
<br />
To prevent the user from simply changing the permissions back, [[File permissions and attributes#File attributes|set the immutable bit]] on the {{ic|authorized_keys}} file. To prevent the user from renaming the {{ic|~/.ssh}} directory and creating a new {{ic|~/.ssh}} directory and {{ic|authorized_keys}} file, set the immutable bit on the {{ic|~/.ssh}} directory too. To add or remove keys, you will have to remove the immutable bit from {{ic|authorized_keys}} and make it writable temporarily.<br />
<br />
{{Tip|It is recommended to log changes to any {{ic|authorized_keys}} file via e.g [[Audit framework#Audit files and directories access|auditd]].}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Encrypted SOCKS tunnel ===<br />
<br />
{{Style|Written like a blog post.}}<br />
<br />
This is highly useful for laptop users connected to various unsafe wireless connections. The only thing you need is an SSH server running at a somewhat secure location, like your home or at work. It might be useful to use a dynamic DNS service like [https://dyn.com/dns/ DynDNS] so you do not have to remember your IP-address.<br />
<br />
==== Step 1: start the connection ====<br />
<br />
You only have to execute this single command to start the connection:<br />
<br />
$ ssh -TND 4711 ''user''@''host''<br />
<br />
where {{Ic|''user''}} is your username at the SSH server running at the {{Ic|''host''}}. It will ask for your password, and then you are connected. The {{Ic|N}} flag disables the interactive prompt, and the {{Ic|D}} flag specifies the local port on which to listen on (you can choose any port number if you want). The {{Ic|T}} flag disables pseudo-tty allocation.<br />
<br />
It is nice to add the verbose ({{Ic|-v}}) flag, because then you can verify that it is actually connected from that output.<br />
<br />
==== Step 2 (Variant A): configure your browser (or other programs) ====<br />
<br />
The above step is useful only in combination with a web browser or another program that uses this newly created SOCKS tunnel. Since SSH currently supports both SOCKS v4 and SOCKS v5, you can use either of them.<br />
<br />
* For Firefox: At ''Preferences > General'' navigates to the bottom of the page and click ''Settings...'', which is to the right of the Network Settings title. Next, within the new semi window, check the ''Manual proxy configuration'' option and enter {{ic|localhost}} in the ''SOCKS host'' text field, and the port number in the ''Port'' text field ({{ic|4711}} in the example above) next to it.<br />
:Firefox does not automatically make DNS requests through the socks tunnel. This potential privacy concern can be mitigated by scrolling further down, checking in the ''Proxy DNS when using SOCKS v5''. Obviously, this will only work if you chooses SOCKS v5 rather than v4.<br />
: Restart Firefox to activate these settings.<br />
<br />
* For Chromium: You can set the SOCKS settings as environment variables or as command line options. I recommend to add one of the following functions to your {{ic|.bashrc}}:<br />
<br />
function secure_chromium {<br />
port=4711<br />
export SOCKS_SERVER=localhost:$port<br />
export SOCKS_VERSION=5<br />
chromium &<br />
exit<br />
}<br />
<br />
OR<br />
<br />
function secure_chromium {<br />
port=4711<br />
chromium --proxy-server="socks://localhost:$port" &<br />
exit<br />
}<br />
<br />
Now open a terminal and just do:<br />
<br />
$ secure_chromium<br />
<br />
Enjoy your secure tunnel!<br />
<br />
==== Step 2 (Variant B): set up a local TUN interface ====<br />
<br />
This variant is slightly more involved upfront but results in you not having to manually configure every single application one by one to use the SOCKS proxy. It involves setting up a local TUN interface and routing traffic through it.<br />
<br />
See [[VPN over SSH#Set up badvpn and tunnel interface]].<br />
<br />
=== X11 forwarding ===<br />
<br />
X11 forwarding is a mechanism that allows graphical interfaces of X11 programs running on a remote system to be displayed on a local client machine. For X11 forwarding the remote host does not need to have a full X11 system installed; however, it needs at least to have ''xauth'' installed. ''xauth'' is a utility that maintains {{ic|Xauthority}} configurations used by server and client for authentication of X11 session ([http://xmodulo.com/2012/11/how-to-enable-x11-forwarding-using-ssh.html source]).<br />
<br />
{{Warning|X11 forwarding has important security implications which should be at least acknowledged by reading relevant sections of {{man|1|ssh}}, {{man|5|sshd_config}}, and {{man|5|ssh_config}} manual pages. See also [https://security.stackexchange.com/questions/14815/security-concerns-with-x11-forwarding this StackExchange question.]}}<br />
<br />
==== Setup ====<br />
<br />
===== Remote =====<br />
<br />
* [[install]] the {{Pkg|xorg-xauth}} packages<br />
* in {{ic|/etc/ssh/ssh'''d'''_config}}:<br />
** set {{ic|X11Forwarding}} to ''yes''<br />
** verify that {{ic|AllowTcpForwarding}} and {{ic|X11UseLocalhost}} options are set to ''yes'', and that {{ic|X11DisplayOffset}} is set to ''10'' (those are the default values if nothing has been changed, see {{man|5|sshd_config}})<br />
* then [[restart]] the [[#Daemon management|''sshd'' daemon]].<br />
<br />
===== Client =====<br />
<br />
* [[install]] the {{Pkg|xorg-xauth}} package<br />
* enable the {{ic|ForwardX11}} option by either specifying the {{ic|-X}} switch on the command line for opportunistic connections, or by setting {{ic|ForwardX11}} to ''yes'' in the [[#Configuration|client's configuration]].<br />
<br />
{{Tip|You can enable the {{ic|ForwardX11Trusted}} option ({{ic|-Y}} switch on the command line) if GUI is drawing badly or you receive errors; this will prevent X11 forwardings from being subjected to the [https://www.x.org/wiki/Development/Documentation/Security/ X11 SECURITY extension] controls. Be sure you have read [[#X11 forwarding|the warning]] at the beginning of this section if you do so.}}<br />
<br />
==== Usage ====<br />
<br />
Log on to the remote machine normally, specifying the {{ic|-X}} switch if ''ForwardX11'' was not enabled in the client's configuration file:<br />
<br />
$ ssh -X ''user@host''<br />
<br />
If you receive errors trying to run graphical applications, try ''ForwardX11Trusted'' instead:<br />
<br />
$ ssh -Y ''user@host''<br />
<br />
Given the output {{ic|X11 forwarding request failed}}, redo the setup for your remote machine. Once the X11 forwarding request succeeds, you can start any X program on the remote server, and it will be forwarded to your local session:<br />
<br />
$ xclock<br />
<br />
Error output containing {{ic|Can't open display}} indicates that {{ic|DISPLAY}} is improperly set.<br />
<br />
Be careful with some applications as they check for a running instance on the local machine. [[Firefox]] is an example: either close the running Firefox instance or use the following start parameter to start a remote instance on the local machine:<br />
<br />
$ firefox --no-remote<br />
<br />
If you get "X11 forwarding request failed on channel 0" when you connect (and the server {{ic|/var/log/errors.log}} shows "Failed to allocate internet-domain X11 display socket"), make sure package {{Pkg|xorg-xauth}} is installed. If its installation is not working, try to either:<br />
<br />
* enable the {{ic|AddressFamily any}} option in {{ic|ssh'''d'''_config}} on the ''server'', or<br />
* set the {{ic|AddressFamily}} option in {{ic|ssh'''d'''_config}} on the ''server'' to inet.<br />
Setting it to inet may fix problems with Ubuntu clients on IPv4.<br />
<br />
For running X applications as another user on the SSH server, you need to {{Ic|xauth add}} the authentication line taken from {{Ic|xauth list}} of the SSH logged in user.<br />
<br />
{{Tip|[https://unix.stackexchange.com/a/12772 Here] are [https://unix.stackexchange.com/a/46748 some] useful [https://superuser.com/a/805060 links] for troubleshooting {{ic|X11 Forwarding}} issues.}}<br />
<br />
=== Forwarding other ports ===<br />
<br />
In addition to SSH's built-in support for X11, it can also be used to securely tunnel any TCP connection, by use of local forwarding or remote forwarding.<br />
<br />
Local forwarding opens a port on the local machine, connections to which will be forwarded to the remote host and from there on to a given destination. Very often, the forwarding destination will be the same as the remote host, thus providing a secure shell and, e.g. a secure [[VNC]] connection, to the same machine. Local forwarding is accomplished by means of the {{Ic|-L}} switch and it is accompanying forwarding specification in the form of {{Ic|<tunnel port>:<destination address>:<destination port>}}.<br />
<br />
Thus:<br />
<br />
$ ssh -L 1000:mail.google.com:25 192.168.0.100<br />
<br />
will use SSH to login to and open a shell on {{ic|192.168.0.100}}, and will also create a tunnel from the local machine's TCP port 1000 to mail.google.com on port 25. Once established, connections to {{ic|localhost:1000}} will connect to the Gmail SMTP port. To Google, it will appear that any such connection (though not necessarily the data conveyed over the connection) originated from {{ic|192.168.0.100}}, and such data will be secure between the local machine and 192.168.0.100, but not between {{ic|192.168.0.100}} and Google, unless other measures are taken.<br />
<br />
Similarly:<br />
<br />
$ ssh -L 2000:192.168.0.100:6001 192.168.0.100<br />
<br />
will allow connections to {{ic|localhost:2000}} which will be transparently sent to the remote host on port 6001. The preceding example is useful for VNC connections using the vncserver utility--part of the [[tightvnc]] package--which, though very useful, is explicit about its lack of security.<br />
<br />
Remote forwarding allows the remote host to connect to an arbitrary host via the SSH tunnel and the local machine, providing a functional reversal of local forwarding, and is useful for situations where, e.g., the remote host has limited connectivity due to firewalling. It is enabled with the {{Ic|-R}} switch and a forwarding specification in the form of {{Ic|<tunnel port>:<destination address>:<destination port>}}.<br />
<br />
Thus:<br />
<br />
$ ssh -R 3000:irc.libera.chat:6667 192.168.0.200<br />
<br />
will bring up a shell on {{ic|192.168.0.200}}, and connections from {{ic|192.168.0.200}} to itself on port 3000 (the remote host's {{ic|localhost:3000}}) will be sent over the tunnel to the local machine and then on to irc.libera.chat on port 6667, thus, in this example, allowing the use of IRC programs on the remote host to be used, even if port 6667 would normally be blocked to it.<br />
<br />
Both local and remote forwarding can be used to provide a secure "gateway", allowing other computers to take advantage of an SSH tunnel, without actually running SSH or the SSH daemon by providing a bind-address for the start of the tunnel as part of the forwarding specification, e.g. {{Ic|<tunnel address>:<tunnel port>:<destination address>:<destination port>}}. The {{Ic|<tunnel address>}} can be any address on the machine at the start of the tunnel. The address {{Ic|localhost}} allows connections via the {{ic|localhost}} or loopback interface, and an empty address or {{Ic|*}} allow connections via any interface. By default, forwarding is limited to connections from the machine at the "beginning" of the tunnel, i.e. the {{Ic|<tunnel address>}} is set to {{Ic|localhost}}. Local forwarding requires no additional configuration; however, remote forwarding is limited by the remote server's SSH daemon configuration. See the {{Ic|GatewayPorts}} option in {{man|5|sshd_config}} and {{ic|-L address}} option in {{man|1|ssh}} for more information about remote forwarding and local forwarding, respectively.<br />
<br />
=== Jump hosts ===<br />
<br />
In certain scenarios, there might not be a direct connection to your target SSH daemon, and the use of a jump server (or bastion server) is required. Thus, we attempt to connect together two or more SSH tunnels, and assuming your local keys are authorized against each server in the chain. This is possible using SSH agent forwarding ({{ic|-A}}) and pseudo-terminal allocation ({{ic|-t}}) which forwards your local key with the following syntax:<br />
<br />
$ ssh -A -t -l user1 bastion1 \<br />
ssh -A -t -l user2 intermediate2 \<br />
ssh -A -t -l user3 target<br />
<br />
An easier way to do this is using the {{ic|-J}} flag:<br />
<br />
$ ssh -J user1@bastion1,user2@intermediate2 user3@target<br />
<br />
Multiple hosts in the {{ic|-J}} directive can be separated with a comma; they will be connected to in the order listed. The {{ic|user...@}} part is not required, but can be used. The host specifications for {{ic|-J}} use the ssh configuration file, so specific per-host options can be set there, if needed.<br />
<br />
An equivalent of the {{ic|-J}} flag in the configuration file is the {{ic|ProxyJump}} option; see {{man|5|ssh_config}} for details.<br />
<br />
=== Reverse SSH through a relay ===<br />
<br />
{{Style|The idea of SSH tunneling is classic, so some references for detailed explanation would be nice. E.g. [https://unix.stackexchange.com/questions/46235/how-does-reverse-ssh-tunneling-work/118650#118650] which includes other scenarios.}}<br />
<br />
The idea is that the client connects to the server via another relay while the server is connected to the same relay using a reverse SSH tunnel. This is useful when the server is behind a NAT, and the relay is a publicly accessible SSH server used as a proxy to which the user has access. Therefore, the prerequisite is that the client's keys are authorized against both the relay and the server, and the server needs to be authorized against the relay as well for the reverse SSH connection.<br />
<br />
The following configuration example assumes that user1 is the user account used on client, user2 on relay and user3 on server. First, the server needs to establish the reverse tunnel with:<br />
<br />
ssh -R 2222:localhost:22 -N user2@relay<br />
<br />
Which can also be automated with a startup script, systemd service or [[#Autossh - automatically restarts SSH sessions and tunnels|autossh]].<br />
<br />
{{Expansion|Explain why {{ic|ssh user3@relay -p 2222}} is not sufficient.}}<br />
<br />
At the client side, the connection is established with:<br />
<br />
ssh -t user2@relay ssh user3@localhost -p 2222<br />
<br />
The remote command to establish the connection to reverse tunnel can also be defined in relay's {{ic|~/.ssh/authorized_keys}} by including the {{ic|command}} field as follows:<br />
<br />
command="ssh user3@localhost -p 2222" ssh-rsa KEY2 user1@client<br />
<br />
In this case the connection is established with:<br />
<br />
ssh user2@relay<br />
<br />
Note that SCP's autocomplete function in client's terminal is not working and even the SCP transfers themselves are not working under some configurations.<br />
<br />
=== Multiplexing ===<br />
<br />
The SSH daemon usually listens on port 22. However, it is common practice for many public internet hotspots to block all traffic that is not on the regular HTTP/S ports (80 and 443, respectively), thus effectively blocking SSH connections. The immediate solution for this is to have {{ic|sshd}} listen additionally on one of the whitelisted ports:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
Port 22<br />
Port 443<br />
}}<br />
<br />
However, it is likely that port 443 is already in use by a web server serving HTTPS content, in which case it is possible to use a multiplexer, such as {{Pkg|sslh}}, which listens on the multiplexed port and can intelligently forward packets to many services.<br />
<br />
=== Speeding up SSH ===<br />
<br />
There are several [[#Configuration|client configuration]] options which can speed up connections either globally or for specific hosts. See {{man|5|ssh_config}} for full descriptions of these options.<br />
<br />
* ''Use a faster cipher'': on modern CPUs with AESNI instructions, {{ic|aes128-gcm@openssh.com}} and {{ic|aes256-gcm@openssh.com}} should offer significantly better performance over openssh's default preferred cipher, usually {{ic|chacha20-poly1305@openssh.com}}. Cipher can be selected with the {{ic|-c}} flag. For a permanent effect, put {{ic|Ciphers}} option in your {{ic|~/.ssh/config}} with ciphers in new preferred order, e.g.:{{bc|Ciphers aes128-gcm@openssh.com,aes256-gcm@openssh.com,chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr}}<br />
<br />
* ''Enable or disable compression'': compression can increase speed on slow connections; it is enabled with the {{ic|Compression yes}} option or the {{ic|-C}} flag. However, the compression algorithm used is the relatively slow {{man|1|gzip}} which becomes the bottleneck on fast networks. In order to speed up the connection, one should use the {{ic|Compression no}} option on local or fast networks.<br />
<br />
* ''Connection sharing'': you can make all sessions to the same host share a single connection using these options:{{bc|<nowiki><br />
ControlMaster auto<br />
ControlPersist yes<br />
ControlPath ~/.ssh/sockets/socket-%r@%h:%p<br />
</nowiki>}}<br />
: where {{ic|~/.ssh/sockets}} can be any directory not writable by other users.<br />
<br />
* {{ic|ControlPersist}} specifies how long the master should wait in the background for new clients after the initial client connection has been closed. Possible values are either: <br />
** {{ic|no}} to close the connection immediately after the last client disconnects, <br />
** a time in seconds,<br />
** {{ic|yes}} to wait forever, the connection will never be closed automatically.<br />
<br />
* Login time can be shortened by bypassing IPv6 lookup using the {{ic|AddressFamily inet}} option or {{ic|-4}} flag.<br />
<br />
* Last, if you intend to use SSH for SFTP or SCP, [https://www.psc.edu/index.php/hpn-ssh High Performance SSH/SCP] can significantly increase throughput by dynamically raising the SSH buffer sizes. Install the package {{AUR|openssh-hpn-git}} to use a patched version of OpenSSH with this enhancement.<br />
<br />
=== Mounting a remote filesystem with SSHFS ===<br />
<br />
Please refer to the [[SSHFS]] article to mount a SSH-accessible remote system to a local directory, so you will be able to do any operation on the mounted files with any tool (copy, rename, edit with vim, etc.). ''sshfs'' is generally preferred over ''shfs'', the latter has not been updated since 2004.<br />
<br />
=== Keep alive ===<br />
<br />
By default, the SSH session automatically logs out if it has been idle for a certain time. To keep the session up, the client can send a keep-alive signal to the server if no data has been received for some time, or symmetrically the server can send messages at regular intervals if it has not heard from the client.<br />
<br />
* On the '''server''' side, {{ic|ClientAliveInterval}} sets the timeout in seconds after which if no data has been received from the client, ''sshd'' will send a request for response. The default is 0, no message is sent. For example to request a response every 60 seconds from the client, set the {{ic|ClientAliveInterval 60}} option in your [[#Configuration_2|server configuration]]. See also the {{ic|ClientAliveCountMax}} and {{ic|TCPKeepAlive}} options.<br />
* On the '''client''' side, {{ic|ServerAliveInterval}} controls the interval between the requests for response sent from the client to the server. For example to request a response every 120 seconds from the server, add the {{ic|ServerAliveInterval 120}} option to your [[#Configuration|client configuration]]. See also the {{ic|ServerAliveCountMax}} and {{ic|TCPKeepAlive}} options.<br />
<br />
{{Note| To ensure a session is kept alive, only one of either the client or the server needs to send keep alive requests. If ones control both the servers and the clients, a reasonable choice is to only configure the clients that require a persistent session with a positive {{ic|ServerAliveInterval}} and leave other clients and servers in their default configuration.}}<br />
<br />
=== Automatically restart SSH tunnels with systemd ===<br />
<br />
[[systemd]] can automatically start SSH connections on boot/login ''and'' restart them when they fail. This makes it a useful tool for maintaining SSH tunnels.<br />
<br />
The following service can start an SSH tunnel on login using the connection settings in your [[#Configuration|ssh configuration]]. If the connection closes for any reason, it waits 10 seconds before restarting it:<br />
<br />
{{hc|~/.config/systemd/user/tunnel.service|<nowiki><br />
[Unit]<br />
Description=SSH tunnel to myserver<br />
<br />
[Service]<br />
Type=simple<br />
Restart=always<br />
RestartSec=10<br />
ExecStart=/usr/bin/ssh -F %h/.ssh/config -N myserver<br />
</nowiki>}}<br />
<br />
Then [[enable]] and [[start]] the [[Systemd/User]] service. See [[#Keep alive]] for how to prevent the tunnel from timing out. If you wish to start the tunnel on boot, you might want to [[Systemd#Writing unit files|rewrite the unit]] as a system service.<br />
<br />
=== Autossh - automatically restarts SSH sessions and tunnels ===<br />
<br />
When a session or tunnel cannot be kept alive, for example due to bad network conditions causing client disconnections, you can use {{Pkg|autossh}} to automatically restart them.<br />
<br />
Usage examples:<br />
<br />
$ autossh -M 0 -o "ServerAliveInterval 45" -o "ServerAliveCountMax 2" username@example.com<br />
<br />
Combined with [[SSHFS]]:<br />
<br />
$ sshfs -o reconnect,compression=yes,transform_symlinks,ServerAliveInterval=45,ServerAliveCountMax=2,ssh_command='autossh -M 0' username@example.com: /mnt/example <br />
<br />
Connecting through a SOCKS-proxy set by [[Proxy settings]]:<br />
<br />
$ autossh -M 0 -o "ServerAliveInterval 45" -o "ServerAliveCountMax 2" -NCD 8080 username@example.com <br />
<br />
With the {{ic|-f}} option autossh can be made to run as a background process. Running it this way however means the passphrase cannot be entered interactively.<br />
<br />
The session will end once you type {{ic|exit}} in the session, or the autossh process receives a SIGTERM, SIGINT of SIGKILL signal.<br />
<br />
==== Run autossh automatically at boot via systemd ====<br />
<br />
If you want to automatically start autossh, you can create a systemd unit file:<br />
<br />
{{hc|/etc/systemd/system/autossh.service|2=<br />
[Unit]<br />
Description=AutoSSH service for port 2222<br />
After=network.target<br />
<br />
[Service]<br />
Environment="AUTOSSH_GATETIME=0"<br />
ExecStart=/usr/bin/autossh -M 0 -NL 2222:localhost:2222 -o TCPKeepAlive=yes foo@bar.com<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
}}<br />
<br />
Here {{ic|1=AUTOSSH_GATETIME=0}} is an environment variable specifying how long ssh must be up before autossh considers it a successful connection, setting it to 0 autossh also ignores the first run failure of ssh. This may be useful when running autossh at boot. Other environment variables are available at {{man|1|autossh}}. Of course, you can make this unit more complex if necessary (see the systemd documentation for details), and obviously you can use your own options for autossh, but note that the {{ic|-f}} implying {{ic|1=AUTOSSH_GATETIME=0}} does not work with systemd. <br />
<br />
Remember to [[start]] and/or [[enable]] the service afterwards.<br />
<br />
You may also need to disable ControlMaster e.g.<br />
<br />
ExecStart=/usr/bin/autossh -M 0 -o ControlMaster=no -NL 2222:localhost:2222 -o TCPKeepAlive=yes foo@bar.com<br />
<br />
{{Tip|It is also easy to maintain several autossh processes, to keep several tunnels alive. Just create multiple service files with different names.}}<br />
<br />
=== Alternative service should SSH daemon fail ===<br />
<br />
For remote or headless servers which rely exclusively on SSH, a failure to start the SSH daemon (e.g., after a system upgrade) may prevent administration access. [[systemd]] offers a simple solution via {{ic|OnFailure}} option.<br />
<br />
Let us suppose the server runs {{ic|sshd}} and [[telnet]] is the fail-safe alternative of choice. Create a file as follows. Do '''not''' [[enable]] {{ic|telnet.socket}}!<br />
<br />
{{hc|/etc/systemd/system/sshd.service.d/override.conf|2=<br />
[Unit]<br />
OnFailure=telnet.socket<br />
}}<br />
<br />
That's it. Telnet is not available when {{ic|sshd}} is running. Should {{ic|sshd}} fail to start, a telnet session can be opened for recovery.<br />
<br />
=== Terminal background color based on host ===<br />
<br />
To better distinguish when you are on different hosts, you can set a [https://bryangilbert.com/post/etc/term/dynamic-ssh-terminal-background-colors/ different background color based on the kind of host].<br />
<br />
This solution works, but is not universal (ZSH only).<br />
<br />
=== Network specific configuration ===<br />
<br />
You can use host configuration specific to the network you are connected to using a {{ic|Match exec}}.<br />
<br />
For example, when using {{man|1|nmcli}}, and the connection is configured (manually or through DHCP) to use a search-domain:<br />
<br />
{{bc|1=<br />
Match exec "nmcli {{!}} grep domains: {{!}} grep example.com"<br />
CanonicalDomains example.com<br />
# Should you use a different username on this network<br />
#User username<br />
# Use a different known_hosts file (for private network or synchronisation)<br />
#UserKnownHostsFile <network>_known_hosts<br />
}}<br />
<br />
Another example for {{ic|Match host ... exec "..."}}: Consider that connecting to internal.example.com requires a bastion/proxy (via {{ic|ProxyJump}}) unless you are already connected via VPN. The fragment {{ic|!exec "host internal.example.com"}} applies only when internal.example.com cannot be looked up via DNS. Various alternatives are discussed at [https://serverfault.com/q/536043/117525].<br />
<br />
{{bc|1=<br />
Match host internal.example.com !exec "host internal.example.com"<br />
ProxyJump bastion.example.com<br />
Host internal.example.com<br />
User foobar<br />
}}<br />
<br />
=== Private networks hostkeys verification ===<br />
<br />
Because different servers on different networks are likely to share a common private IP address, you might want to handle them differently.<br />
<br />
{{Accuracy|The best solution would not need a warning to use something else in practice.}}<br />
<br />
The best solution is to use the [[#Network specific configuration]] to use a different {{ic|UserKnownHostsFile}} depending on the network you are on. The second solution, best used as default when you are working on new/prototype networks, would be to simply ignore hostkeys for private networks:<br />
<br />
{{bc|1=<br />
Host 10.* 192.168.*.* 172.31.* 172.30.* 172.2?.* 172.1?.*<br />
# Disable HostKey verification<br />
# Trust HostKey automatically<br />
StrictHostKeyChecking no<br />
# Do not save the HostKey<br />
UserKnownHostsFile=/dev/null<br />
# Do not display: "Warning: Permanently Added ..."<br />
LogLevel Error<br />
}}<br />
<br />
{{Accuracy|The {{ic|known_hosts}} file records an IP address even when you use hostname to access the server.}}<br />
<br />
{{Warning|In a production environment, make sure to either use the hostname to access the host and/or to use network specific known_hosts files.}}<br />
<br />
=== Run command at login ===<br />
<br />
If you are using an interactive session, there are multiple ways to execute a command on login:<br />
<br />
* use the {{ic|authorized_keys}} file on the remote host (see {{ic|AUTHORIZED_KEYS FILE FORMAT}} in {{man|8|sshd}})<br />
* use {{ic|~/.ssh/rc}} on the remote host if the server has enabled the {{ic|PermitUserRC}} option<br />
* use your shell configuration file on the remote host, e.g. {{ic|.bashrc}}<br />
<br />
=== Agent forwarding ===<br />
<br />
SSH agent forwarding allows you to use your local keys when connected to a server. It is recommended to only enable agent forwarding for selected hosts.<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''myserver.com''<br />
ForwardAgent yes<br />
}}<br />
<br />
Next, configure an [[SSH agent]] and add your local key with ''ssh-add''.<br />
<br />
If you now connect to a remote server you will be able to connect to other services using your local keys.<br />
<br />
=== Generating new keys ===<br />
<br />
New server private keys can be generated by:<br />
<br />
# Deleting all the keys, e.g.: {{bc|# rm /etc/ssh/ssh_host_*_key*}}<br />
# [[Restart]]ing {{ic|sshdgenkeys.service}} or running {{ic|ssh-keygen -A}} as root.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Checklist ===<br />
<br />
Check these simple issues before you look any further.<br />
<br />
# The configuration directory {{ic|~/.ssh}}, its contents should be accessible only by the user (check this on both the client and the server), and the user's home directory should only be writable by the user: {{bc|<nowiki><br />
$ chmod go-w ~<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/*<br />
$ chown -R $USER ~/.ssh<br />
</nowiki>}}<br />
# Check that the client's public key (e.g. {{ic|id_rsa.pub}}) is in {{ic|~/.ssh/authorized_keys}} on the server.<br />
# Check that you did not limit SSH access with {{ic|AllowUsers}} or {{ic|AllowGroups}} in the [[#Configuration_2|server config]].<br />
# Check if the user has set a password. Sometimes new users who have not yet logged in to the server do not have a password.<br />
# [[Append]] {{ic|LogLevel DEBUG}} to {{ic|/etc/ssh/sshd_config}}.<br />
# Run {{ic|journalctl -xe}} as root for possible (error) messages.<br />
# [[Restart]] {{ic|sshd}} and logout/login on both client and server.<br />
<br />
=== Connection refused or timeout problem ===<br />
<br />
==== Port forwarding ====<br />
<br />
If you are behind a NAT mode/router (which is likely unless you are on a VPS or publicly addressed host), make sure that your router is forwarding incoming ssh connections to your machine. Find the server's internal IP address with {{ic|$ ip addr}} and set up your router to forward TCP on your SSH port to that IP. [https://portforward.com portforward.com] can help with that.<br />
<br />
==== Is SSH running and listening? ====<br />
<br />
The [[ss]] utility shows all the processes listening to a TCP port with the following command line:<br />
<br />
$ ss --tcp --listening<br />
<br />
If the above command do not show the system is listening to the port {{ic|ssh}}, then SSH is not running: check the [[journal]] for errors etc.<br />
<br />
==== Are there firewall rules blocking the connection? ====<br />
<br />
[[Iptables]] may be blocking connections on port {{ic|22}}. Check this with:<br />
{{bc|# iptables -nvL}}<br />
and look for rules that might be dropping packets on the {{ic|INPUT}} chain. Then, if necessary, unblock the port with a command like: <br />
{{bc|<br />
# iptables -I INPUT 1 -p tcp --dport 22 -j ACCEPT<br />
}}<br />
For more help configuring firewalls, see [[firewalls]].<br />
<br />
==== Is the traffic even getting to your computer? ====<br />
<br />
Start a traffic dump on the computer you are having problems with:<br />
<br />
# tcpdump -lnn -i any port ssh and tcp-syn<br />
<br />
This should show some basic information, then wait for any matching traffic to happen before displaying it. Try your connection now. If you do not see any output when you attempt to connect, then something outside of your computer is blocking the traffic (e. g., hardware firewall, NAT router etc.).<br />
<br />
==== Your ISP or a third party blocking default port? ====<br />
<br />
{{Note|Try this step if you '''know''' you are not running any firewalls and you know you have configured the router for DMZ or have forwarded the port to your computer and it still does not work. Here you will find diagnostic steps and a possible solution.}}<br />
<br />
In some cases, your ISP might block the default port (SSH port 22) so whatever you try (opening ports, hardening the stack, defending against flood attacks, et al) ends up useless. To confirm this, create a server on all interfaces (0.0.0.0) and connect remotely. <br />
<br />
If you get an error message comparable to this:<br />
<br />
ssh: connect to host www.inet.hr port 22: Connection refused<br />
<br />
That means the port is '''not''' being blocked by the ISP, but the server does not run SSH on that port (See [[wikipedia:Security through obscurity|security through obscurity]]).<br />
<br />
However, if you get an error message comparable to this:<br />
<br />
ssh: connect to host 111.222.333.444 port 22: Operation timed out <br />
<br />
That means that something is rejecting your TCP traffic on port 22. Basically that port is stealth, either by your firewall or 3rd party intervention (like an ISP blocking and/or rejecting incoming traffic on port 22). If you know you are not running any firewall on your computer, and you know that Gremlins are not growing in your routers and switches, then your ISP is blocking the traffic.<br />
<br />
To double check, you can run Wireshark on your server and listen to traffic on port 22. Since Wireshark is a Layer 2 Packet Sniffing utility, and TCP/UDP are Layer 3 and above (see [[wikipedia:Internet protocol suite|IP Network stack]]), if you do not receive anything while connecting remotely, a third party is most likely to be blocking the traffic on that port to your server.<br />
<br />
===== Diagnosis =====<br />
<br />
[[Install]] either {{Pkg|tcpdump}} or Wireshark with the {{Pkg|wireshark-cli}} package.<br />
<br />
For tcpdump:<br />
<br />
# tcpdump -ni ''interface'' "port 22"<br />
<br />
For Wireshark:<br />
<br />
$ tshark -f "tcp port 22" -i ''interface''<br />
<br />
where {{ic|''interface''}} is the network interface for a WAN connection (see {{ic|ip a}} to check). If you are not receiving any packets while trying to connect remotely, you can be very sure that your ISP is blocking the incoming traffic on port 22.<br />
<br />
===== Possible solution =====<br />
<br />
The solution is just to use some other port that the ISP is not blocking. Open the {{ic|/etc/ssh/sshd_config}} and configure the file to use different ports. For example, add:<br />
<br />
Port 22<br />
Port 1234<br />
<br />
Also make sure that other "Port" configuration lines in the file are commented out. Just commenting "Port 22" and putting "Port 1234" will not solve the issue because then sshd will only listen on port 1234. Use both lines to run the SSH server on both ports. <br />
<br />
[[Restart]] the server {{ic|sshd.service}} and you are almost done. You still have to configure your client(s) to use the other port instead of the default port. There are numerous solutions to that problem, but let us cover two of them here.<br />
<br />
==== Read from socket failed: connection reset by peer ====<br />
<br />
Recent versions of openssh sometimes fail with the above error message when connecting to older ssh servers. This can be worked around by setting various [[#Configuration|client options]] for that host. See {{man|5|ssh_config}} for more information about the following options.<br />
<br />
The problem could be the {{ic|ecdsa-sha2-nistp*-cert-v01@openssh}} elliptical host key algorithms. These can be disabled by setting {{ic|HostKeyAlgorithms}} to a list excluding those algorithms.<br />
<br />
If that does not work, it could be that the list of ciphers is too long. Set the {{ic|Ciphers}} option to a shorter list (fewer than 80 characters should be enough). Similarly, you can also try shortening the list of {{ic|MACs}}.<br />
<br />
See also the [https://www.gossamer-threads.com/lists/openssh/dev/51339 discussion] on the openssh bug forum.<br />
<br />
=== "[your shell]: No such file or directory" / ssh_exchange_identification problem ===<br />
<br />
One possible cause for this is the need of certain SSH clients to find an absolute path (one returned by {{Ic|whereis -b [your shell]}}, for instance) in {{Ic|$SHELL}}, even if the shell's binary is located in one of the {{Ic|$PATH}} entries.<br />
<br />
=== "Terminal unknown" or "Error opening terminal" error message ===<br />
<br />
If you receive the above errors upon logging in, this means the server does not recognize your terminal. Ncurses applications like nano may fail with the message "Error opening terminal".<br />
<br />
The correct solution is to install the client terminal's terminfo file on the server. This tells console programs on the server how to correctly interact with your terminal. You can get info about current terminfo using {{ic|$ infocmp}} and then find out [[pacman#Querying package databases|which package owns it]].<br />
<br />
If you cannot [[install]] it normally, you can copy your terminfo to your home directory on the server:<br />
<br />
$ ssh myserver mkdir -p ~/.terminfo/${TERM:0:1}<br />
$ scp /usr/share/terminfo/${TERM:0:1}/$TERM myserver:~/.terminfo/${TERM:0:1}/<br />
<br />
After logging in and out from the server the problem should be fixed.<br />
<br />
==== TERM hack ====<br />
<br />
{{Note|This should only be used as a last resort.}}<br />
<br />
Alternatively, you can simply set {{ic|1=TERM=xterm}} in your environment on the server (e.g. in {{ic|.bash_profile}}). This will silence the error and allow ncurses applications to run again, but you may experience strange behavior and graphical glitches unless your terminal's control sequences exactly match xterm's.<br />
<br />
=== Connection closed by x.x.x.x [preauth] ===<br />
<br />
If you are seeing this error in your sshd logs, make sure you have set a valid HostKey<br />
<br />
HostKey /etc/ssh/ssh_host_rsa_key<br />
<br />
=== subsystem request failed ===<br />
<br />
Since ''OpenSSH'' 8.8, ''scp'' uses ''SFTP'' as the default protocol for data transfers by requesting the subsystem named {{ic|sftp}}. If you run ''scp'' in verbose mode, {{ic|scp -v}}, you can determine which subsystem your client is using (e.g. {{ic|Sending subsystem: <subsystem-name>}}). Errors such as {{ic|subsystem request failed on channel 0}} may be fixed by configuring the server's Subsystem settings: {{man|5|sshd_config|Subsystem}}. The server configuration should resemble the example below.<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
Subsystem subsystem-name /path/to/subsystem-executable<br />
...<br />
}}<br />
<br />
=== id_dsa refused by OpenSSH 7.0 ===<br />
<br />
OpenSSH 7.0 deprecated DSA public keys for security reasons. If you absolutely must enable them, set the [[#Configuration|configuration]] option {{ic|PubkeyAcceptedKeyTypes +ssh-dss}} (https://www.openssh.com/legacy.html does not mention this).<br />
<br />
=== No matching key exchange method found by OpenSSH 7.0 ===<br />
<br />
OpenSSH 7.0 deprecated the diffie-hellman-group1-sha1 key algorithm because it is weak and within theoretical range of the so-called Logjam attack (see https://www.openssh.com/legacy.html). If the key algorithm is needed for a particular host, ssh will produce an error message like this:<br />
<br />
Unable to negotiate with 127.0.0.1: no matching key exchange method found.<br />
Their offer: diffie-hellman-group1-sha1<br />
<br />
The best resolution for these failures is to upgrade/configure the server to not use deprecated algorithms. If that is not possible, you can force the client to reenable the algorithm with the [[#Configuration|client option]] {{ic|KexAlgorithms +diffie-hellman-group1-sha1}}.<br />
<br />
=== tmux/screen session killed when disconnecting from SSH ===<br />
<br />
If your processes get killed at the end of the session, it is possible that you are using socket activation and it gets killed by {{Pkg|systemd}} when it notices that the SSH session process exited. In that case there are two solutions. One is to avoid using socket activation by using {{ic|ssh.service}} instead of {{ic|ssh.socket}}. The other is to set {{ic|1=KillMode=process}} in the Service section of {{ic|ssh@.service}}.<br />
<br />
The {{ic|1=KillMode=process}} setting may also be useful with the classic {{ic|ssh.service}}, as it avoids killing the SSH session process or the {{Pkg|screen}} or {{Pkg|tmux}} processes when the server gets stopped or restarted.<br />
<br />
=== SSH session stops responding ===<br />
<br />
SSH responds to [[Wikipedia:Software flow control|flow control commands]] {{ic|XON}} and {{ic|XOFF}}. It will freeze/hang/stop responding when you hit {{ic|Ctrl+s}}. Use {{ic|Ctrl+q}} to resume your session.<br />
<br />
=== Broken pipe ===<br />
<br />
If you attempt to create a connection which results in a {{ic|Broken pipe}} response for {{ic|packet_write_wait}}, you should reattempt the connection in debug mode and see if the output ends in error:<br />
{{bc|debug3: send packet: type 1<br />
packet_write_wait: Connection to A.B.C.D port 22: Broken pipe}}<br />
The {{ic|send packet}} line above indicates that the reply packet was never received. So, it follows that this is a ''QoS'' issue. To decrease the likely-hood of a packet being dropped, set {{ic|IPQoS}}:<br />
{{hc|/etc/ssh/ssh_config|Host *<br />
IPQoS reliability}}<br />
The {{ic|reliability}} ({{ic|0x04}}) type-of-service should resolve the issue, as well as {{ic|0x00}} and {{ic|throughput}} ({{ic|0x08}}).<br />
<br />
=== Slow daemon startup after reboot ===<br />
<br />
If you are experiencing excessively long daemon startup times after reboots (e.g. several minutes before the daemon starts accepting connections), especially on headless or virtualized servers, it may be due to a lack of entropy.[https://bbs.archlinux.org/viewtopic.php?id=241954] This can be remedied by installing either [[Rng-tools]] or [[Haveged]], as appropriate for your system. However, take note of the associated security implications discussed in each package's respective wiki page.<br />
<br />
=== Terminate unresponsive SSH connection ===<br />
<br />
If a client session is no longer responding and cannot be terminated by instructing the running program (e.g. [[shell]]), you can still terminate the session by pressing {{ic|Enter}}, {{ic|~}} and {{ic|.}} one after another in that order.<br />
<br />
The {{ic|~}} is a pseudo-terminal escape character (see {{man|1|ssh|ESCAPE CHARACTERS}}), which can be added multiple times depending on the client session to terminate. For example, if you connected from A to B and then from B to C and the session from B to C freezes, you can terminate it by pressing {{ic|Enter}} and typing {{ic|~~.}}, which will leave you in a working session on B.<br />
<br />
=== WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! ===<br />
<br />
If the client warns that the key of an ssh server has changed, you should verify that the newly offered key really belongs to the server operator. Then remove the old key from the {{ic|known_hosts}} file with {{ic|ssh-keygen -R $SSH_HOST}} and accept the new key as if it was a new server.<br />
<br />
=== Connecting to a remote without the appropriate terminfo entry ===<br />
<br />
When connecting to hosts that do not have a terminfo entry for your terminal, for example, when using a terminal emulator whose terminfo entry is not shipped with {{Pkg|ncurses}} (e.g. [[kitty]] and [[rxvt-unicode]]), or when connecting to hosts with a limited terminfo database (e.g. systems running [[Wikipedia:OpenWrt|OpenWrt]]), various issues will occur with software that relies on {{man|5|terminfo}}.<br />
<br />
A proper solution is to place the appropriate terminfo entry on the host. If that is not feasible, an alternative is to set {{ic|TERM}} to a value that is both supported by the remote host and compatible with the terminal.<br />
<br />
Since OpenSSH 8.7, a custom {{ic|TERM}} environment variable can be passed to remote hosts with a simple configuration snippet:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Host example.com<br />
SetEnv TERM=xterm-256color<br />
}}<br />
<br />
=== Connection through jump host fails with "bash: No such file or directory" ===<br />
<br />
If you do not have the {{ic|SHELL}} environment variable set to a full valid path (on the jump server), connection will fail with an error message simmilar to this one:<br />
<br />
bash: No such file or directory<br />
kex_exchange_identification: Connection closed by remote host<br />
Connection closed by UNKNOWN port 65535<br />
<br />
You can simply solve this by setting your {{ic|SHELL}} to a full path name of a shell that will also be valid on the jump server or by setting a specific {{ic|SHELL}} variable for each server in your {{ic|~/.ssh/config}} file.<br />
<br />
== See also ==<br />
<br />
* [https://www.la-samhna.de/library/brutessh.html Defending against brute force ssh attacks]<br />
* OpenSSH key management: [https://www.ibm.com/developerworks/library/l-keyc/index.html Part 1] on IBM developerWorks, [[Funtoo:OpenSSH Key Management, Part 2|Part 2]], [[Funtoo:OpenSSH Key Management, Part 3|Part 3]] on funtoo.org<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Simon04https://wiki.archlinux.org/index.php?title=Environment_variables&diff=764087Environment variables2023-01-14T00:14:49Z<p>Simon04: /* Using shell initialization files */ envsubst</p>
<hr />
<div>[[Category:System administration]]<br />
[[de:Umgebungsvariablen]]<br />
[[es:Environment variables]]<br />
[[ja:環境変数]]<br />
[[pt:Environment variables]]<br />
[[ru:Environment variables]]<br />
[[zh-hans:Environment variables]]<br />
{{Related articles start}}<br />
{{Related|Default applications}}<br />
{{Related|systemd/User#Environment variables}}<br />
{{Related articles end}}<br />
<br />
An environment variable is a named object that contains data used by one or more applications. In simple terms, it is a variable with a name and a value. The value of an environmental variable can for example be the location of all executable files in the file system, the default editor that should be used, or the system locale settings. Users new to Linux may often find this way of managing settings a bit unmanageable. However, environment variables provide a simple way to share configuration settings between multiple applications and processes in Linux.<br />
<br />
== Utilities ==<br />
<br />
The {{Pkg|coreutils}} package contains the programs ''printenv'' and ''env''. To list the current environmental variables with values: <br />
<br />
$ printenv<br />
<br />
{{Note|Some environment variables are user-specific. Check by comparing the outputs of ''printenv'' as an unprivileged user and as ''root''.}}<br />
<br />
The ''env'' utility can be used to run a command under a modified environment. The following example will launch ''xterm'' with the environment variable {{ic|EDITOR}} set to {{ic|vim}}. This will not affect the global environment variable {{ic|EDITOR}}.<br />
<br />
$ env EDITOR=vim xterm<br />
<br />
The [[shell]] builtin {{man|1p|set}} allows you to change the values of shell options, set the positional parameters and to display the names and values of shell variables.<br />
<br />
Each process stores their environment in the {{ic|/proc/$PID/environ}} file. This file contains each key value pair delimited by a nul character ({{ic|\x0}}). A more human readable format can be obtained with [[sed]], e.g. {{ic|sed 's:\x0:\n:g' /proc/$PID/environ}}.<br />
<br />
== Defining variables ==<br />
<br />
To avoid needlessly polluting the environment, you should seek to restrict the scope of variables. In fact, graphical sessions and systemd services require you to set variables in certain locations for them to take effect. The scopes of environment variables are broken down into the contexts they affect:<br />
<br />
* [[#Globally|Global]]: All programs that any user runs, not including systemd services.<br />
* [[#Per user|By user]]: All programs that a particular user runs, not including user systemd services (see [[Systemd/User#Environment variables]]) or graphical applications (see [[#Graphical environment]]).<br />
<br />
=== Globally ===<br />
<br />
==== Using shell initialization files ====<br />
<br />
Most Linux distributions tell you to change or add environment variable definitions in {{ic|/etc/profile}} or other locations. Keep in mind that there are also package-specific configuration files containing variable settings such as {{ic|/etc/locale.conf}}. Be sure to maintain and manage the environment variables and pay attention to the numerous files that can contain environment variables. In principle, any shell script can be used for initializing environmental variables, but following traditional UNIX conventions, these statements should only be present in some particular files. <br />
<br />
The following files can be used for defining global environment variables on your system, each with different limitations:<br />
<br />
* {{ic|/etc/environment}} is used by the [[#Using pam_env|pam_env module]] and is shell agnostic so scripting or glob expansion cannot be used. The file only accepts {{ic|1=''variable=value''}} pairs.<br />
* {{ic|/etc/profile}} initializes variables for login shells ''only''. It does, however, run scripts (e.g. those in {{ic|/etc/profile.d/}}) and can be used by all [[wikipedia:Bourne shell|Bourne shell]] compatible shells.<br />
* Shell specific configuration files - Global configuration files of your [[shell]], initializes variables and runs scripts. For example [[Bash#Configuration files]] or [[Zsh#Startup/Shutdown files]].<br />
<br />
In this example, we will create a function to add several directories (e.g. {{ic|~/bin}} and {{ic|~/scripts}}) to {{ic|PATH}} for the respective user. To do this, just put this in your preferred global environment variable configuration file ({{ic|/etc/profile}} or {{ic|/etc/bash.bashrc}}):<br />
<br />
{{bc|<nowiki><br />
set_path(){<br />
<br />
# Check if user id is 1000 or higher<br />
[ "$(id -u)" -ge 1000 ] || return<br />
<br />
for i in "$@";<br />
do<br />
# Check if the directory exists<br />
[ -d "$i" ] || continue<br />
<br />
# Check if it is not already in your $PATH.<br />
echo "$PATH" | grep -Eq "(^|:)$i(:|$)" && continue<br />
<br />
# Then append it to $PATH and export it<br />
export PATH="${PATH}:$i"<br />
done<br />
}<br />
<br />
set_path ~/bin ~/scripts<br />
</nowiki>}}<br />
<br />
To share environment variables between different shells, consider this approach (inspired by [https://unix.stackexchange.com/questions/176322/share-environment-variables-between-bash-and-fish]):<br />
<br />
{{hc|head=.env (no not add comments, do not add blank lines)|output=<br />
EDITOR=vim<br />
XDG_CACHE_HOME=$HOME/.cache<br />
XDG_CONFIG_HOME=$HOME/.config<br />
XDG_DATA_HOME=$HOME/.local/share<br />
XDG_STATE_HOME=$HOME/.local/state<br />
}}<br />
<br />
{{hc|head=.bashrc|output=export $(envsubst < .env)}}<br />
<br />
{{hc|head=.config/fish/config.fish|output=export (envsubst < .env)}}<br />
<br />
==== Using pam_env ====<br />
<br />
The [[PAM]] module {{man|8|pam_env}} loads the variables to be set in the environment from the following files in order: {{ic|/etc/security/pam_env.conf}} and {{ic|/etc/environment}}.<br />
<br />
{{Note|<br />
* These files are read before other files, in particular before {{ic|~/.profile}}, {{ic|~/.bash_profile}} and {{ic|~/.zshenv}}.<br />
* The deprecated {{ic|~/.pam_environment}} is not read anymore. See {{Bug|68945}}.<br />
}}<br />
<br />
{{ic|/etc/environment}} must consist of simple {{ic|1=''VARIABLE''=''value''}} pairs on separate lines, for example: <br />
<br />
EDITOR=nano<br />
<br />
{{ic|/etc/security/pam_env.conf}} has the following format: <br />
<br />
VARIABLE [DEFAULT=''value''] [OVERRIDE=''value'']<br />
<br />
{{ic|@{HOME} }} and {{ic|@{SHELL} }} are special variables that expand to what is defined in {{ic|/etc/passwd}}. The following example illustrates how to expand the {{ic|HOME}} environment variable into another variable: <br />
<br />
XDG_CONFIG_HOME DEFAULT=@{HOME}/.config<br />
<br />
{{Note|The variables {{ic|${HOME} }} and {{ic|${SHELL} }} are not linked to the {{ic|HOME}} and {{ic|SHELL}} environment variables, they are not set by default.}} <br />
<br />
The format also allows to expand already defined variables in the values of other variables using {{ic|${''VARIABLE''} }}, like this: <br />
<br />
GOPATH DEFAULT=${XDG_DATA_HOME}/go<br />
<br />
{{ic|1=''VARIABLE''=''value''}} pairs are also allowed, but variable expansion is not supported in those pairs. See {{man|5|pam_env.conf}} for more information.<br />
<br />
=== Per user ===<br />
<br />
You do not always want to define an environment variable globally. For instance, you might want to add {{ic|/home/my_user/bin}} to the {{ic|PATH}} variable but do not want all other users on your system to have that in their {{ic|PATH}} too. Local environment variables can be defined in many different files:<br />
<br />
* User configuration files of your [[shell]], for example [[Bash#Configuration files]] or [[Zsh#Startup/Shutdown files]].<br />
* [[systemd/User#Environment variables|systemd user environment variables]] are read from {{ic|~/.config/environment.d/*.conf}}.<br />
<br />
To add a directory to the {{ic|PATH}} for local usage, put following in {{ic|~/.bash_profile}}:<br />
<br />
export PATH="${PATH}:/home/my_user/bin"<br />
<br />
To update the variable, re-login or [[source]] the file: {{ic|$ source ~/.bash_profile}}.<br />
<br />
{{Note|The dbus daemon and the user instance of systemd do not inherit any of the environment variables set in places like {{ic|~/.bashrc}} etc. This means that, for example, dbus activated programs like [[GNOME Files]] will not use them by default. See [[systemd/User#Environment variables]].}}<br />
<br />
==== Graphical environment ====<br />
<br />
If an environment variable only affects graphical applications, you may want to restrict the scope of it by only setting it within the graphical session. In order of decreasing scope:<br />
<br />
* [[#Per Xorg session]] and [[#Per Wayland session]] affect the whole graphical session, certainly including the DE.<br />
* [[#Per desktop environment session]] affects the applications spawned within graphical session, potentially including the DE itself.<br />
* [[#Per application]] affects just a particular graphical application.<br />
<br />
===== Per desktop environment session =====<br />
<br />
Some graphical environments, (e.g. [[KDE Plasma]]) support executing shell scripts at login: they can be used to set environment variables. See [[KDE#Autostart]] for example.<br />
<br />
===== Per Xorg session =====<br />
<br />
The procedure for modifying the environment of the Xorg session depends on how it is started:<br />
* Most [[Display manager|display managers]] source [[xprofile]].<br />
* [[startx]] and [[SLiM]] execute [[xinitrc]].<br />
* [[XDM]] executes {{ic|~/.xsession}}; see [[XDM#Defining the session]].<br />
* [[SDDM]] additionally sources startup scripts for login shells, like {{ic|~/.bash_profile}} for [[bash]] or {{ic|~/.zprofile}} and {{ic|~/.zlogin}} for [[zsh]]. [https://github.com/sddm/sddm/blob/master/data/scripts/Xsession]<br />
<br />
Though the end of the script depends on which file it is, and any advanced syntax depends on the shell used, the basic usage is universal:<br />
<br />
{{hc|~/.xprofile, ~/.xinitrc, or ~/.xsession|2=<br />
...<br />
export ''GUI_VAR''=''value''<br />
...<br />
}}<br />
<br />
===== Per Wayland session =====<br />
<br />
Since [[Wayland]] does not initiate any Xorg related files, [[GDM]] and [[KDE Plasma]] source [[systemd/User#Environment variables|systemd user environment variables]] instead. <br />
<br />
{{hc|~/.config/environment.d/envvars.conf|2=<br />
''GUI_VAR''=''value''<br />
}}<br />
<br />
No other display managers supporting Wayland sessions (e.g. [[SDDM]]) provide direct support for this yet. However, [[SDDM]] sources startup scripts for login shells on Wayland sessions too.<br />
<br />
{{Style|The following depends on {{pkg|run-parts}}.}}<br />
<br />
If your display manager sources startup scripts like {{ic|~/.bash_profile}} and you want to use {{ic|environment.d}}, you can source it like so:<br />
<br />
{{hc|~/.bash_profile|<br />
# use systemd-environment-d-generator(8) to generate environment, and export those variables<br />
export $(run-parts /usr/lib/systemd/user-environment-generators {{!}} xargs)<br />
}}<br />
{{Note|The above runs all executables in {{ic|/usr/lib/systemd/user-environment-generators}}, which may or may not be desirable. Feel free to run {{ic|/usr/lib/systemd/user-environment-generators/30-systemd-environment-d-generator}} directly instead.}}<br />
<br />
===== Per application =====<br />
<br />
To set environment variables only for a specific application instead of the whole session, edit the application's ''.desktop'' file. See [[Desktop entries#Modify environment variables]] for instructions.<br />
<br />
For [[Steam]] games, you can configure a program's environment by editing its launch options; see [[Steam#Launch options]].<br />
<br />
=== Per session ===<br />
<br />
Sometimes even stricter definitions are required. One might want to temporarily run executables from a specific directory created without having to type the absolute path to each one, or editing shell configuration files for the short time needed to run them.<br />
<br />
In this case, you can define the {{ic|PATH}} variable in your current session, combined with the ''export'' command. As long as you do not log out, the {{ic|PATH}} variable will be using the temporary settings. To add a session-specific directory to {{ic|PATH}}, issue:<br />
<br />
$ export PATH="${PATH}:/home/my_user/tmp/usr/bin"<br />
<br />
== Examples ==<br />
<br />
The following section lists a number of common environment variables used by a Linux system and describes their values.<br />
<br />
* {{ic|XDG_CURRENT_DESKTOP}} is a [[freedesktop.org]] variable containing a colon separated list of strings that the current [[desktop environment]] identifies as [https://specifications.freedesktop.org/mime-apps-spec/1.0.1/ar01s02.html]. Standardized values for actively developed environments are {{ic|GNOME}}, {{ic|GNOME-Flashback}}, {{ic|KDE}}, {{ic|LXDE}}, {{ic|LXQt}}, {{ic|MATE}}, {{ic|TDE}}, {{ic|Unity}}, {{ic|XFCE}}, {{ic|EDE}}, {{ic|Cinnamon}}, and {{ic|Pantheon}} [https://specifications.freedesktop.org/menu-spec/latest/apb.html].<br />
** [https://bugs.freedesktop.org/show_bug.cgi?id=73497 Cinnamon was registered later than the rest of the desktop environments]. As a result, some software may still be expecting its pre-registration value {{ic|X-CINNAMON}}, such as [[Qt]] versions as recent as 6.3 [https://github.com/qt/qtbase/blob/6.3/src/gui/platform/unix/qgenericunixthemes.cpp#L858].<br />
<br />
* {{ic|XDG_SESSION_DESKTOP}} is similar to {{ic|XDG_CURRENT_DESKTOP}}, but only permits a single string. Despite its name, [https://gitlab.gnome.org/GNOME/gtk/-/issues/1224#note_270915 it is not standardized by freedesktop.org].<br />
<br />
* {{ic|DE}} is a legacy variable indicating the ''d''esktop ''e''nvironment being used. There is no central documentation for what possible values are, but [[xdg-utils#Environment variables|xdg-utils]] provides a reference for many desktop environments.<br />
<br />
* {{ic|DESKTOP_SESSION}} is another legacy variable, similar to {{ic|DE}} but less common. It may be a path to the session's [[desktop entry]], in {{ic|/usr/share/xsessions/}} [https://github.com/qt/qtbase/blob/6.3/src/gui/platform/unix/qgenericunixservices.cpp#L92-L107].<br />
<br />
* {{ic|WINDOW_MANAGER}} is a variable sometimes used to ''choose'' the [[window manager]] to be used in a desktop environment, as opposed to the other variables here which are set by the already chosen display manager or desktop environment, for other programs to read.<br />
<br />
* {{ic|PATH}} contains a colon-separated list of directories in which your system looks for executable files. When a regular command (e.g. ''ls'', ''systemctl'' or ''pacman'') is interpreted by the shell (e.g. ''bash'' or ''zsh''), the shell looks for an executable file with the same name as your command in the listed directories, and executes it. To run executables that are not listed in {{ic|PATH}}, a relative or absolute path to the executable must be given, e.g. {{ic|./a.out}} or {{ic|/bin/ls}}.<br />
<br />
{{Note|It is advised not to include the current working directory ({{ic|.}}) into your {{ic|PATH}} for security reasons, as it may trick the user to execute malicious commands.}}<br />
<br />
* {{ic|HOME}} contains the path to the home directory of the current user. This variable can be used by applications to associate configuration files and such like with the user running it.<br />
<br />
* {{ic|PWD}} contains the [[Wikipedia:Pwd|path to the working directory]].<br />
<br />
* {{ic|OLDPWD}} contains the path to the previous working directory, that is, the value of {{ic|PWD}} before last ''cd'' was executed.<br />
<br />
* {{ic|TERM}} contains the type of the running ''term''inal, e.g. {{ic|xterm-256color}}. It is used by programs running in the terminal that wish to use terminal-specific capabilities.<br />
<br />
* {{ic|MAIL}} contains the location of incoming email. The traditional setting is {{ic|/var/spool/mail/$LOGNAME}}.<br />
<br />
* {{ic|ftp_proxy}} and {{ic|http_proxy}} contains FTP and HTTP proxy server, respectively:<br />
ftp_proxy="<nowiki>ftp://192.168.0.1:21</nowiki>"<br />
http_proxy="<nowiki>http://192.168.0.1:80</nowiki>"<br />
<br />
* {{ic|MANPATH}} contains a colon-separated list of directories in which ''man'' searches for the man pages.<br />
{{Note|In {{ic|/etc/profile}}, there is a comment that states "Man is much better than us at figuring this out", so this variable should generally be left unset. See {{man|5|manpath}}.<br />
}}<br />
<br />
* {{ic|INFODIR}} contains a colon-separated list of directories in which the ''info'' command searches for the info pages, e.g., {{ic|/usr/share/info:/usr/local/share/info}}<br />
<br />
* {{ic|TZ}} can be used to to set a time zone different to the system zone for a user. The zones listed in {{ic|/usr/share/zoneinfo/}} can be used as reference, for example {{ic|1=TZ=":/usr/share/zoneinfo/Pacific/Fiji"}}. When pointing the {{ic|TZ}} variable to a zoneinfo file, it should start with a colon per [https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html the GNU manual].<br />
<br />
=== Default programs ===<br />
<br />
* {{ic|SHELL}} contains the path to the user's [https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03 preferred shell]. Note that this is not necessarily the shell that is currently running. In the event that it has no value, [[Bash]] will automatically set this variable to the user's login shell as defined in {{ic|/etc/passwd}} or to {{ic|/bin/sh}} if this cannot be determined. <br />
<br />
* {{ic|PAGER}} contains command to run the program used to list the contents of files, e.g., {{ic|/bin/less}}.<br />
<br />
* {{ic|EDITOR}} contains the command to run the lightweight program used for editing files, e.g., {{ic|/usr/bin/nano}}. For example, you can write an interactive switch between ''gedit'' under [[X]] or ''nano'', in this example:<br />
<br />
[ -n "$DISPLAY" ] && export EDITOR=gedit || export EDITOR=nano<br />
<br />
* {{ic|VISUAL}} contains command to run the full-fledged editor that is used for more demanding tasks, such as editing mail (e.g., {{ic|vi}}, [[vim]], [[emacs]] etc).<br />
<br />
* {{ic|BROWSER}} contains the path to the web browser. Helpful to set in an interactive shell configuration file so that it may be dynamically altered depending on the availability of a graphic environment, such as [[X]]:<br />
<br />
[ -n "$DISPLAY" ] && export BROWSER=firefox || export BROWSER=links<br />
<br />
{{Tip|These default programs can also be set conditionally if a [[Wayland#Compositors|Wayland compositor]] is running by using the {{ic|WAYLAND_DISPLAY}} environment variable.}}<br />
<br />
== See also ==<br />
<br />
* [[Gentoo:Handbook:X86/Working/EnvVar]]<br />
* [https://help.ubuntu.com/community/EnvironmentVariables Ubuntu Community Wiki - Environment Variables]</div>Simon04https://wiki.archlinux.org/index.php?title=Environment_variables&diff=764086Environment variables2023-01-13T23:33:01Z<p>Simon04: /* Using shell initialization files */ share-environment-variables-between-bash-and-fish</p>
<hr />
<div>[[Category:System administration]]<br />
[[de:Umgebungsvariablen]]<br />
[[es:Environment variables]]<br />
[[ja:環境変数]]<br />
[[pt:Environment variables]]<br />
[[ru:Environment variables]]<br />
[[zh-hans:Environment variables]]<br />
{{Related articles start}}<br />
{{Related|Default applications}}<br />
{{Related|systemd/User#Environment variables}}<br />
{{Related articles end}}<br />
<br />
An environment variable is a named object that contains data used by one or more applications. In simple terms, it is a variable with a name and a value. The value of an environmental variable can for example be the location of all executable files in the file system, the default editor that should be used, or the system locale settings. Users new to Linux may often find this way of managing settings a bit unmanageable. However, environment variables provide a simple way to share configuration settings between multiple applications and processes in Linux.<br />
<br />
== Utilities ==<br />
<br />
The {{Pkg|coreutils}} package contains the programs ''printenv'' and ''env''. To list the current environmental variables with values: <br />
<br />
$ printenv<br />
<br />
{{Note|Some environment variables are user-specific. Check by comparing the outputs of ''printenv'' as an unprivileged user and as ''root''.}}<br />
<br />
The ''env'' utility can be used to run a command under a modified environment. The following example will launch ''xterm'' with the environment variable {{ic|EDITOR}} set to {{ic|vim}}. This will not affect the global environment variable {{ic|EDITOR}}.<br />
<br />
$ env EDITOR=vim xterm<br />
<br />
The [[shell]] builtin {{man|1p|set}} allows you to change the values of shell options, set the positional parameters and to display the names and values of shell variables.<br />
<br />
Each process stores their environment in the {{ic|/proc/$PID/environ}} file. This file contains each key value pair delimited by a nul character ({{ic|\x0}}). A more human readable format can be obtained with [[sed]], e.g. {{ic|sed 's:\x0:\n:g' /proc/$PID/environ}}.<br />
<br />
== Defining variables ==<br />
<br />
To avoid needlessly polluting the environment, you should seek to restrict the scope of variables. In fact, graphical sessions and systemd services require you to set variables in certain locations for them to take effect. The scopes of environment variables are broken down into the contexts they affect:<br />
<br />
* [[#Globally|Global]]: All programs that any user runs, not including systemd services.<br />
* [[#Per user|By user]]: All programs that a particular user runs, not including user systemd services (see [[Systemd/User#Environment variables]]) or graphical applications (see [[#Graphical environment]]).<br />
<br />
=== Globally ===<br />
<br />
==== Using shell initialization files ====<br />
<br />
Most Linux distributions tell you to change or add environment variable definitions in {{ic|/etc/profile}} or other locations. Keep in mind that there are also package-specific configuration files containing variable settings such as {{ic|/etc/locale.conf}}. Be sure to maintain and manage the environment variables and pay attention to the numerous files that can contain environment variables. In principle, any shell script can be used for initializing environmental variables, but following traditional UNIX conventions, these statements should only be present in some particular files. <br />
<br />
The following files can be used for defining global environment variables on your system, each with different limitations:<br />
<br />
* {{ic|/etc/environment}} is used by the [[#Using pam_env|pam_env module]] and is shell agnostic so scripting or glob expansion cannot be used. The file only accepts {{ic|1=''variable=value''}} pairs.<br />
* {{ic|/etc/profile}} initializes variables for login shells ''only''. It does, however, run scripts (e.g. those in {{ic|/etc/profile.d/}}) and can be used by all [[wikipedia:Bourne shell|Bourne shell]] compatible shells.<br />
* Shell specific configuration files - Global configuration files of your [[shell]], initializes variables and runs scripts. For example [[Bash#Configuration files]] or [[Zsh#Startup/Shutdown files]].<br />
<br />
In this example, we will create a function to add several directories (e.g. {{ic|~/bin}} and {{ic|~/scripts}}) to {{ic|PATH}} for the respective user. To do this, just put this in your preferred global environment variable configuration file ({{ic|/etc/profile}} or {{ic|/etc/bash.bashrc}}):<br />
<br />
{{bc|<nowiki><br />
set_path(){<br />
<br />
# Check if user id is 1000 or higher<br />
[ "$(id -u)" -ge 1000 ] || return<br />
<br />
for i in "$@";<br />
do<br />
# Check if the directory exists<br />
[ -d "$i" ] || continue<br />
<br />
# Check if it is not already in your $PATH.<br />
echo "$PATH" | grep -Eq "(^|:)$i(:|$)" && continue<br />
<br />
# Then append it to $PATH and export it<br />
export PATH="${PATH}:$i"<br />
done<br />
}<br />
<br />
set_path ~/bin ~/scripts<br />
</nowiki>}}<br />
<br />
To share environment variables between different shells, consider this approach (inspired by [https://unix.stackexchange.com/questions/176322/share-environment-variables-between-bash-and-fish]):<br />
<br />
{{hc|head=.env (no not add comments, do not add blank lines)|output=<br />
EDITOR=vim<br />
XDG_CACHE_HOME=$HOME/.cache<br />
XDG_CONFIG_HOME=$HOME/.config<br />
XDG_DATA_HOME=$HOME/.local/share<br />
XDG_STATE_HOME=$HOME/.local/state<br />
}}<br />
<br />
{{hc|head=.bashrc|output=<nowiki>export `cat .env | xargs`</nowiki>}}<br />
<br />
{{hc|head=.config/fish/config.fish|output=export (cat .env)}}<br />
<br />
==== Using pam_env ====<br />
<br />
The [[PAM]] module {{man|8|pam_env}} loads the variables to be set in the environment from the following files in order: {{ic|/etc/security/pam_env.conf}} and {{ic|/etc/environment}}.<br />
<br />
{{Note|<br />
* These files are read before other files, in particular before {{ic|~/.profile}}, {{ic|~/.bash_profile}} and {{ic|~/.zshenv}}.<br />
* The deprecated {{ic|~/.pam_environment}} is not read anymore. See {{Bug|68945}}.<br />
}}<br />
<br />
{{ic|/etc/environment}} must consist of simple {{ic|1=''VARIABLE''=''value''}} pairs on separate lines, for example: <br />
<br />
EDITOR=nano<br />
<br />
{{ic|/etc/security/pam_env.conf}} has the following format: <br />
<br />
VARIABLE [DEFAULT=''value''] [OVERRIDE=''value'']<br />
<br />
{{ic|@{HOME} }} and {{ic|@{SHELL} }} are special variables that expand to what is defined in {{ic|/etc/passwd}}. The following example illustrates how to expand the {{ic|HOME}} environment variable into another variable: <br />
<br />
XDG_CONFIG_HOME DEFAULT=@{HOME}/.config<br />
<br />
{{Note|The variables {{ic|${HOME} }} and {{ic|${SHELL} }} are not linked to the {{ic|HOME}} and {{ic|SHELL}} environment variables, they are not set by default.}} <br />
<br />
The format also allows to expand already defined variables in the values of other variables using {{ic|${''VARIABLE''} }}, like this: <br />
<br />
GOPATH DEFAULT=${XDG_DATA_HOME}/go<br />
<br />
{{ic|1=''VARIABLE''=''value''}} pairs are also allowed, but variable expansion is not supported in those pairs. See {{man|5|pam_env.conf}} for more information.<br />
<br />
=== Per user ===<br />
<br />
You do not always want to define an environment variable globally. For instance, you might want to add {{ic|/home/my_user/bin}} to the {{ic|PATH}} variable but do not want all other users on your system to have that in their {{ic|PATH}} too. Local environment variables can be defined in many different files:<br />
<br />
* User configuration files of your [[shell]], for example [[Bash#Configuration files]] or [[Zsh#Startup/Shutdown files]].<br />
* [[systemd/User#Environment variables|systemd user environment variables]] are read from {{ic|~/.config/environment.d/*.conf}}.<br />
<br />
To add a directory to the {{ic|PATH}} for local usage, put following in {{ic|~/.bash_profile}}:<br />
<br />
export PATH="${PATH}:/home/my_user/bin"<br />
<br />
To update the variable, re-login or [[source]] the file: {{ic|$ source ~/.bash_profile}}.<br />
<br />
{{Note|The dbus daemon and the user instance of systemd do not inherit any of the environment variables set in places like {{ic|~/.bashrc}} etc. This means that, for example, dbus activated programs like [[GNOME Files]] will not use them by default. See [[systemd/User#Environment variables]].}}<br />
<br />
==== Graphical environment ====<br />
<br />
If an environment variable only affects graphical applications, you may want to restrict the scope of it by only setting it within the graphical session. In order of decreasing scope:<br />
<br />
* [[#Per Xorg session]] and [[#Per Wayland session]] affect the whole graphical session, certainly including the DE.<br />
* [[#Per desktop environment session]] affects the applications spawned within graphical session, potentially including the DE itself.<br />
* [[#Per application]] affects just a particular graphical application.<br />
<br />
===== Per desktop environment session =====<br />
<br />
Some graphical environments, (e.g. [[KDE Plasma]]) support executing shell scripts at login: they can be used to set environment variables. See [[KDE#Autostart]] for example.<br />
<br />
===== Per Xorg session =====<br />
<br />
The procedure for modifying the environment of the Xorg session depends on how it is started:<br />
* Most [[Display manager|display managers]] source [[xprofile]].<br />
* [[startx]] and [[SLiM]] execute [[xinitrc]].<br />
* [[XDM]] executes {{ic|~/.xsession}}; see [[XDM#Defining the session]].<br />
* [[SDDM]] additionally sources startup scripts for login shells, like {{ic|~/.bash_profile}} for [[bash]] or {{ic|~/.zprofile}} and {{ic|~/.zlogin}} for [[zsh]]. [https://github.com/sddm/sddm/blob/master/data/scripts/Xsession]<br />
<br />
Though the end of the script depends on which file it is, and any advanced syntax depends on the shell used, the basic usage is universal:<br />
<br />
{{hc|~/.xprofile, ~/.xinitrc, or ~/.xsession|2=<br />
...<br />
export ''GUI_VAR''=''value''<br />
...<br />
}}<br />
<br />
===== Per Wayland session =====<br />
<br />
Since [[Wayland]] does not initiate any Xorg related files, [[GDM]] and [[KDE Plasma]] source [[systemd/User#Environment variables|systemd user environment variables]] instead. <br />
<br />
{{hc|~/.config/environment.d/envvars.conf|2=<br />
''GUI_VAR''=''value''<br />
}}<br />
<br />
No other display managers supporting Wayland sessions (e.g. [[SDDM]]) provide direct support for this yet. However, [[SDDM]] sources startup scripts for login shells on Wayland sessions too.<br />
<br />
{{Style|The following depends on {{pkg|run-parts}}.}}<br />
<br />
If your display manager sources startup scripts like {{ic|~/.bash_profile}} and you want to use {{ic|environment.d}}, you can source it like so:<br />
<br />
{{hc|~/.bash_profile|<br />
# use systemd-environment-d-generator(8) to generate environment, and export those variables<br />
export $(run-parts /usr/lib/systemd/user-environment-generators {{!}} xargs)<br />
}}<br />
{{Note|The above runs all executables in {{ic|/usr/lib/systemd/user-environment-generators}}, which may or may not be desirable. Feel free to run {{ic|/usr/lib/systemd/user-environment-generators/30-systemd-environment-d-generator}} directly instead.}}<br />
<br />
===== Per application =====<br />
<br />
To set environment variables only for a specific application instead of the whole session, edit the application's ''.desktop'' file. See [[Desktop entries#Modify environment variables]] for instructions.<br />
<br />
For [[Steam]] games, you can configure a program's environment by editing its launch options; see [[Steam#Launch options]].<br />
<br />
=== Per session ===<br />
<br />
Sometimes even stricter definitions are required. One might want to temporarily run executables from a specific directory created without having to type the absolute path to each one, or editing shell configuration files for the short time needed to run them.<br />
<br />
In this case, you can define the {{ic|PATH}} variable in your current session, combined with the ''export'' command. As long as you do not log out, the {{ic|PATH}} variable will be using the temporary settings. To add a session-specific directory to {{ic|PATH}}, issue:<br />
<br />
$ export PATH="${PATH}:/home/my_user/tmp/usr/bin"<br />
<br />
== Examples ==<br />
<br />
The following section lists a number of common environment variables used by a Linux system and describes their values.<br />
<br />
* {{ic|XDG_CURRENT_DESKTOP}} is a [[freedesktop.org]] variable containing a colon separated list of strings that the current [[desktop environment]] identifies as [https://specifications.freedesktop.org/mime-apps-spec/1.0.1/ar01s02.html]. Standardized values for actively developed environments are {{ic|GNOME}}, {{ic|GNOME-Flashback}}, {{ic|KDE}}, {{ic|LXDE}}, {{ic|LXQt}}, {{ic|MATE}}, {{ic|TDE}}, {{ic|Unity}}, {{ic|XFCE}}, {{ic|EDE}}, {{ic|Cinnamon}}, and {{ic|Pantheon}} [https://specifications.freedesktop.org/menu-spec/latest/apb.html].<br />
** [https://bugs.freedesktop.org/show_bug.cgi?id=73497 Cinnamon was registered later than the rest of the desktop environments]. As a result, some software may still be expecting its pre-registration value {{ic|X-CINNAMON}}, such as [[Qt]] versions as recent as 6.3 [https://github.com/qt/qtbase/blob/6.3/src/gui/platform/unix/qgenericunixthemes.cpp#L858].<br />
<br />
* {{ic|XDG_SESSION_DESKTOP}} is similar to {{ic|XDG_CURRENT_DESKTOP}}, but only permits a single string. Despite its name, [https://gitlab.gnome.org/GNOME/gtk/-/issues/1224#note_270915 it is not standardized by freedesktop.org].<br />
<br />
* {{ic|DE}} is a legacy variable indicating the ''d''esktop ''e''nvironment being used. There is no central documentation for what possible values are, but [[xdg-utils#Environment variables|xdg-utils]] provides a reference for many desktop environments.<br />
<br />
* {{ic|DESKTOP_SESSION}} is another legacy variable, similar to {{ic|DE}} but less common. It may be a path to the session's [[desktop entry]], in {{ic|/usr/share/xsessions/}} [https://github.com/qt/qtbase/blob/6.3/src/gui/platform/unix/qgenericunixservices.cpp#L92-L107].<br />
<br />
* {{ic|WINDOW_MANAGER}} is a variable sometimes used to ''choose'' the [[window manager]] to be used in a desktop environment, as opposed to the other variables here which are set by the already chosen display manager or desktop environment, for other programs to read.<br />
<br />
* {{ic|PATH}} contains a colon-separated list of directories in which your system looks for executable files. When a regular command (e.g. ''ls'', ''systemctl'' or ''pacman'') is interpreted by the shell (e.g. ''bash'' or ''zsh''), the shell looks for an executable file with the same name as your command in the listed directories, and executes it. To run executables that are not listed in {{ic|PATH}}, a relative or absolute path to the executable must be given, e.g. {{ic|./a.out}} or {{ic|/bin/ls}}.<br />
<br />
{{Note|It is advised not to include the current working directory ({{ic|.}}) into your {{ic|PATH}} for security reasons, as it may trick the user to execute malicious commands.}}<br />
<br />
* {{ic|HOME}} contains the path to the home directory of the current user. This variable can be used by applications to associate configuration files and such like with the user running it.<br />
<br />
* {{ic|PWD}} contains the [[Wikipedia:Pwd|path to the working directory]].<br />
<br />
* {{ic|OLDPWD}} contains the path to the previous working directory, that is, the value of {{ic|PWD}} before last ''cd'' was executed.<br />
<br />
* {{ic|TERM}} contains the type of the running ''term''inal, e.g. {{ic|xterm-256color}}. It is used by programs running in the terminal that wish to use terminal-specific capabilities.<br />
<br />
* {{ic|MAIL}} contains the location of incoming email. The traditional setting is {{ic|/var/spool/mail/$LOGNAME}}.<br />
<br />
* {{ic|ftp_proxy}} and {{ic|http_proxy}} contains FTP and HTTP proxy server, respectively:<br />
ftp_proxy="<nowiki>ftp://192.168.0.1:21</nowiki>"<br />
http_proxy="<nowiki>http://192.168.0.1:80</nowiki>"<br />
<br />
* {{ic|MANPATH}} contains a colon-separated list of directories in which ''man'' searches for the man pages.<br />
{{Note|In {{ic|/etc/profile}}, there is a comment that states "Man is much better than us at figuring this out", so this variable should generally be left unset. See {{man|5|manpath}}.<br />
}}<br />
<br />
* {{ic|INFODIR}} contains a colon-separated list of directories in which the ''info'' command searches for the info pages, e.g., {{ic|/usr/share/info:/usr/local/share/info}}<br />
<br />
* {{ic|TZ}} can be used to to set a time zone different to the system zone for a user. The zones listed in {{ic|/usr/share/zoneinfo/}} can be used as reference, for example {{ic|1=TZ=":/usr/share/zoneinfo/Pacific/Fiji"}}. When pointing the {{ic|TZ}} variable to a zoneinfo file, it should start with a colon per [https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html the GNU manual].<br />
<br />
=== Default programs ===<br />
<br />
* {{ic|SHELL}} contains the path to the user's [https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03 preferred shell]. Note that this is not necessarily the shell that is currently running. In the event that it has no value, [[Bash]] will automatically set this variable to the user's login shell as defined in {{ic|/etc/passwd}} or to {{ic|/bin/sh}} if this cannot be determined. <br />
<br />
* {{ic|PAGER}} contains command to run the program used to list the contents of files, e.g., {{ic|/bin/less}}.<br />
<br />
* {{ic|EDITOR}} contains the command to run the lightweight program used for editing files, e.g., {{ic|/usr/bin/nano}}. For example, you can write an interactive switch between ''gedit'' under [[X]] or ''nano'', in this example:<br />
<br />
[ -n "$DISPLAY" ] && export EDITOR=gedit || export EDITOR=nano<br />
<br />
* {{ic|VISUAL}} contains command to run the full-fledged editor that is used for more demanding tasks, such as editing mail (e.g., {{ic|vi}}, [[vim]], [[emacs]] etc).<br />
<br />
* {{ic|BROWSER}} contains the path to the web browser. Helpful to set in an interactive shell configuration file so that it may be dynamically altered depending on the availability of a graphic environment, such as [[X]]:<br />
<br />
[ -n "$DISPLAY" ] && export BROWSER=firefox || export BROWSER=links<br />
<br />
{{Tip|These default programs can also be set conditionally if a [[Wayland#Compositors|Wayland compositor]] is running by using the {{ic|WAYLAND_DISPLAY}} environment variable.}}<br />
<br />
== See also ==<br />
<br />
* [[Gentoo:Handbook:X86/Working/EnvVar]]<br />
* [https://help.ubuntu.com/community/EnvironmentVariables Ubuntu Community Wiki - Environment Variables]</div>Simon04https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=764083XDG Base Directory2023-01-13T22:40:42Z<p>Simon04: xdg-ninja</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[Category:Configuration files]]<br />
[[Category:Development]]<br />
[[ja:XDG Base Directory]]<br />
[[pt:XDG Base Directory]]<br />
{{Related articles start}}<br />
{{Related|dotfiles}}<br />
{{Related|XDG user directories}}<br />
{{Related articles end}}<br />
<br />
This article summarizes the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory specification] in [[#Specification]] and tracks software support in [[#Support]].<br />
<br />
== Specification ==<br />
<br />
Please read the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html full specification]. This section will attempt to break down the essence of what it tries to achieve.<br />
<br />
Only {{ic|XDG_RUNTIME_DIR}} is set by default through [https://www.freedesktop.org/software/systemd/man/pam_systemd.html pam_systemd]. It is up to the user to explicitly define the other variables according to the specification.<br />
<br />
See [[Environment variables#Globally]] for information on defining variables.<br />
<br />
=== User directories ===<br />
<br />
* {{ic|XDG_CONFIG_HOME}}<br />
** Where user-specific configurations should be written (analogous to {{ic|/etc}}).<br />
** Should default to {{ic|$HOME/.config}}.<br />
<br />
* {{ic|XDG_CACHE_HOME}}<br />
** Where user-specific non-essential (cached) data should be written (analogous to {{ic|/var/cache}}).<br />
** Should default to {{ic|$HOME/.cache}}.<br />
<br />
* {{ic|XDG_DATA_HOME}}<br />
** Where user-specific data files should be written (analogous to {{ic|/usr/share}}).<br />
** Should default to {{ic|$HOME/.local/share}}.<br />
<br />
* {{ic|XDG_STATE_HOME}}<br />
** Where user-specific state files should be written (analogous to {{ic|/var/lib}}).<br />
** Should default to {{ic|$HOME/.local/state}}.<br />
<br />
* {{ic|XDG_RUNTIME_DIR}}<br />
** Used for non-essential, user-specific data files such as sockets, named pipes, etc.<br />
** Not required to have a default value; warnings should be issued if not set or equivalents provided.<br />
** Must be owned by the user with an access mode of {{ic|0700}}.<br />
** Filesystem fully featured by standards of OS.<br />
** Must be on the local filesystem.<br />
** May be subject to periodic cleanup.<br />
** Modified every 6 hours or set sticky bit if persistence is desired.<br />
** Can only exist for the duration of the user's login.<br />
** Should not store large files as it may be mounted as a tmpfs.<br />
** pam_systemd sets this to {{ic|/run/user/$UID}}.<br />
<br />
=== System directories ===<br />
<br />
* {{ic|XDG_DATA_DIRS}}<br />
** List of directories separated by {{ic|:}} (analogous to {{ic|PATH}}).<br />
** Should default to {{ic|/usr/local/share:/usr/share}}.<br />
<br />
* {{ic|XDG_CONFIG_DIRS}}<br />
** List of directories separated by {{ic|:}} (analogous to {{ic|PATH}}).<br />
** Should default to {{ic|/etc/xdg}}.<br />
<br />
== Support ==<br />
<br />
{{Expansion|The current supported/partial/hardcoded split is not detailed enough and can be misleading. The tables could be merged into one (with more fields added on how the programs work with the specification) or differently named categories could be used.|section=Add description of support categories}}<br />
<br />
This section exists to catalog the growing set of software using the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory Specification] introduced in 2003.<br />
This is here to demonstrate the viability of this specification by listing commonly found dotfiles and their support status.<br />
For those not currently supporting the Base Directory Specification, workarounds will be demonstrated to emulate it instead.<br />
<br />
The workarounds will be limited to anything not involving patching the source, executing code stored in [[environment variables]] or compile-time options.<br />
The rationale for this is that configurations should be portable across systems and having compile-time options prevent that.<br />
<br />
Hopefully this will provide a source of information about exactly what certain kinds of dotfiles are and where they come from.<br />
<br />
=== Contributing ===<br />
<br />
When contributing make sure to use the correct section.<br />
<br />
Nothing should require code evaluation (such as [[vim]] and {{ic|VIMINIT}}), patches or compile-time options to gain support and anything which does must be deemed hardcoded.<br />
Additionally, if the process is error prone or difficult, it should also be classified as hardcoded.<br />
<br />
* The first column should be either a link to an internal article, a [[Template:Pkg]] or a [[Template:AUR]].<br />
* The second column is for any legacy files and directories the project had (one per line), this is done so people can find them even if they are no longer read.<br />
* In the third, try to find the commit or version a project switched to XDG Base Directory or any open discussions and include them in the next two columns (two per line).<br />
* The last column should include any appropriate workarounds or solutions. Please verify that your solution is correct and functional.<br />
<br />
=== Supported ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Supported Since<br />
! Discussion<br />
! Notes<br />
|-<br />
| {{AUR|aerc-git}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[ALSA]]<br />
| {{ic|~/.asoundrc}}<br />
| [https://github.com/alsa-project/alsa-lib/commit/577df365f66ee09579864fc771136e690927b3bf 577df36]<br />
[https://github.com/alsa-project/alsa-lib/releases/tag/v1.2.3 1.2.3]<br />
| [https://github.com/alsa-project/alsa-lib/issues/49]<br />
| {{ic|XDG_CONFIG_HOME/alsa/asoundrc}}<br />
|-<br />
| {{AUR|anaconda}}<br />
| {{ic|~/.conda/.condarc}}, {{ic|~/.conda/condarc}}, {{ic|~/.conda/condarc.d/}}, {{ic|~/.condarc}}<br />
| [https://github.com/conda/conda/blob/main/CHANGELOG.md#4110-2021-11-22 4.11.0]<br />
| [https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html#searching-for-condarc] [https://github.com/conda/conda/pull/10982]<br />
| Previous versions required setting variables in {{ic|condarc}}:<br />
{{hc|1=$XDG_CONFIG_HOME/conda/condarc|2=conda-build:<br />
# Replace /home/user/.local/share with your $XDG_DATA_HOME path, as the<br />
# `conda-build.root-dir` option does not support environment expansion<br />
root-dir: /home/user/.local/share/conda/conda-bld<br />
envs_dirs:<br />
- ${XDG_DATA_HOME}/conda/envs<br />
pkgs_dirs:<br />
- ${XDG_CACHE_HOME}/conda/pkgs}}<br />
|-<br />
| [https://developer.android.com/studio/index.html Android Studio]<br />
| {{ic|~/.AndroidStudioX.X}}<br />
| [https://developer.android.com/studio/intro/studio-config#file_location Android Studio 4.1]<br />
|<br />
|<br />
XDG_CONFIG_HOME/Google/AndroidStudioX.X<br />
XDG_DATA_HOME/Google/AndroidStudioX.X<br />
XDG_CACHE_HOME/Google/AndroidStudioX.X<br />
[https://developer.android.com/studio/intro/studio-config#file_location Location overview by Google] does not mention XDG - paths could be hardcoded instead of using the proper variable, though that is unlikely as Intellij IDEA, which Android Studio is based on, implements it properly as well<br />
|-<br />
| [[Anki]]<br />
| {{ic|~/Anki}}, {{ic|~/Documents/Anki}}<br />
|<br />
| [https://github.com/dae/anki/pull/49] [https://github.com/dae/anki/pull/58] [https://docs.ankiweb.net/files.html]<br />
| Uses {{ic|$XDG_DATA_HOME/Anki2}} as default if no older location exists, can be changed by using {{ic|1=anki -b <anki_dir>}}<br />
|-<br />
| {{AUR|antimicrox}}<br />
| {{ic|~/.antimicro}}, {{ic|~/.antimicrox}}<br />
| [https://github.com/Antimicrox/antimicrox/commit/edba864 edba864]<br />
| [https://github.com/Antimicro/antimicro/issues/5]<br />
| <br />
|-<br />
| {{Aur|apvlv}}<br />
| {{ic|~/.apvlvrc}}<br />
| [https://github.com/naihe2010/apvlv/commit/ed0e0112b05b0cafa13ca4e215ee559c82194caf]<br />
| [https://github.com/naihe2010/apvlv/issues/70]<br />
| Uses {{ic|XDG_CONFIG_HOME/apvlv/apvlvrc}} now if it exist.<br />
|-<br />
| [[aria2]]<br />
| {{ic|~/.aria2}}<br />
| [https://github.com/tatsuhiro-t/aria2/commit/8bc1d37 8bc1d37]<br />
| [https://github.com/tatsuhiro-t/aria2/issues/27]<br />
|<br />
XDG_CONFIG_HOME/aria2/<br />
XDG_CACHE_HOME/aria2/<br />
|-<br />
| {{Pkg|asunder}}<br />
| {{ic|~/.asunder}} {{ic|~/.asunder_album_artist}} {{ic|~/.asunder_album_genre}} {{ic|~/.asunder_album_title}}<br />
| [https://littlesvr.ca/bugs/show_bug.cgi?id=31 2.9.0]{{Dead link|2021|05|17|status=SSL error}}<br />
| [https://littlesvr.ca/bugs/show_bug.cgi?id=52]{{Dead link|2021|05|17|status=SSL error}}<br />
| Uses {{ic|XDG_CONFIG_HOME/asunder/asunder}} for {{ic|~/.asunder}} and {{ic|XDG_CACHE_HOME/asunder/asunder_album_...}} for the other 3 files. Legacy paths are not removed after migration, they have to be deleted manually.<br />
|-<br />
| {{Pkg|audacity}}<br />
| {{ic|~/.audacity-data/}}<br />
| [https://github.com/audacity/audacity/releases/tag/Audacity-3.2.0 3.2.0]<br />
| [https://bugzilla.audacityteam.org/show_bug.cgi?id=2201]<br />
|<br />
XDG_CONFIG_HOME/audacity<br />
XDG_DATA_HOME/audacity<br />
|-<br />
| {{Pkg|binwalk}}<br />
| {{ic|~/.binwalk}}<br />
| [https://github.com/ReFirmLabs/binwalk/commit/2051757 2051757]<br />
| [https://github.com/ReFirmLabs/binwalk/issues/216]<br />
| {{ic|XDG_CONFIG_HOME/binwalk}}<br />
|-<br />
| {{Pkg|bitwarden-cli}}<br />
| {{ic|~/.config/Bitwarden CLI}}<br />
| [https://github.com/bitwarden/cli/releases/tag/v1.7.1 1.7.1]<br />
| [https://github.com/bitwarden/cli/pull/46]<br />
|<br />
XDG_CONFIG_HOME/Bitwarden CLI<br />
XDG_DATA_HOME/audacity<br />
<br />
The {{ic|BITWARDENCLI_APPDATA_DIR}} environment variable takes precedence.<br />
<br />
Currently contains a single {{ic|data.json}} file with all the vault data, so it ought to belong in {{ic|XDG_DATA_HOME}}<br />
|-<br />
| [[Blender]]<br />
| {{ic|~/.blender}}<br />
| [https://git.blender.org/gitweb/gitweb.cgi/blender.git/commit/4293f47 4293f47]<br />
| [https://developer.blender.org/T28943]<br />
|<br />
|- <br />
| {{Pkg|byobu}}<br />
| {{ic|~/.byobu}}<br />
| [https://launchpad.net/byobu/+milestone/4.17 4.17]<br />
| [https://bugs.launchpad.net/byobu/+bug/553105]<br />
| <br />
{{ic|XDG_CONFIG_HOME/byobu}}<br />
<br />
Legacy path takes precedence if present, or if {{ic|XDG_CONFIG_HOME}} is ''not'' set.<br />
|-<br />
| [https://www.haskell.org/cabal cabal]<br />
| {{ic|~/.cabal/}}<br />
| [https://github.com/haskell/cabal/commit/9f7dc55 9f7dc55]<br />
| [https://github.com/haskell/cabal/issues/680]<br />
|<br />
|-<br />
| {{Pkg|calcurse}}<br />
| {{ic|~/.calcurse}}<br />
| [https://github.com/lfos/calcurse/commit/04162d 04162d]<br />
| [https://github.com/lfos/calcurse/pull/254] [https://github.com/lfos/calcurse/issues/252]<br />
|<br />
XDG_CONFIG_HOME/calcurse<br />
XDG_DATA_HOME/calcurse<br />
<br />
If the legacy path {{ic|~/.calcurse}} is present, it will take precedence.<br />
|-<br />
| {{Pkg|calibre}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|ccache}}<br />
| {{ic|~/.ccache}}<br />
| [https://ccache.dev/releasenotes.html#_ccache_4_0 4.0]<br />
| [https://github.com/ccache/ccache/issues/191]<br />
|<br />
XDG_CACHE_HOME/ccache<br />
XDG_CONFIG_HOME/ccache/ccache.conf<br />
|-<br />
| {{AUR|citra-git}}<br />
| {{ic|~/.citra-emu}}<br />
| [https://github.com/citra-emu/citra/commit/f7c3193 f7c3193]<br />
| [https://github.com/citra-emu/citra/pull/575]<br />
|<br />
|-<br />
| [https://clangd.llvm.org/config.html clangd]<br />
| {{ic|~/.clangd}}<br />
| [https://github.com/JohnHolmesII/llvm-project/commit/fdf7dcc fdf7dcc]{{Dead link|2022|09|23|status=404}}<br />
| [https://github.com/clangd/clangd/issues/341]<br />
| {{ic|XDG_CONFIG_HOME/clangd/config.yml}}<br />
<br />
{{ic|XDG_CACHE_HOME/clangd}}<br />
<br />
Project specific configuration can be specified in {{ic|proj/.clangd}}.<br />
Configuration is combined when this is sensible. In case of conflicts, user config has the highest precedence, then inner project, then outer project.<br />
|-<br />
| [[Composer]]<br />
| {{ic|~/.composer}}<br />
| [https://github.com/composer/composer/releases/tag/1.0.0-beta1 1.0.0-beta1]<br />
| [https://github.com/composer/composer/pull/1407]<br />
|<br />
|-<br />
| [[cURL]]<br />
| {{ic|~/.curlrc}}<br />
| [https://curl.se/changes.html#7_73_0 7.73.0]<br />
| [https://github.com/curl/curl/issues/5829]<br />
| {{ic|XDG_CONFIG_HOME/.curlrc}}<br />
|-<br />
| {{Pkg|d-feet}}<br />
| {{ic|~/.d-feet}}<br />
| [https://gitlab.gnome.org/GNOME/d-feet/commit/7f6104b 7f6104b]<br />
|<br />
|<br />
|-<br />
| {{Pkg|dconf}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[Dolphin emulator]]<br />
| {{ic|~/.dolphin-emu}}<br />
| [https://github.com/dolphin-emu/dolphin/commit/a498c68 a498c68]<br />
| [https://github.com/dolphin-emu/dolphin/pull/2304]<br />
|<br />
|-<br />
| {{AUR|dr14_tmeter}}<br />
|<br />
| [https://github.com/simon-r/dr14_t.meter/commit/7e777ca 7e777ca]<br />
| [https://github.com/simon-r/dr14_t.meter/pull/30]<br />
| {{ic|XDG_CONFIG_HOME/dr14tmeter/}}<br />
|-<br />
| {{Pkg|dunst}}<br />
|<br />
| [https://github.com/dunst-project/dunst/commit/78b6e2b 78b6e2b]<br />
| [https://github.com/dunst-project/dunst/issues/22]<br />
|<br />
|-<br />
| [[Emacs]]<br />
| {{ic|~/.emacs}} {{ic|~/.emacs.d/init.el}}<br />
| [https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=4118297ae2fab4886b20d193ba511a229637aea3]<br />
[https://www.gnu.org/savannah-checkouts/gnu/emacs/emacs.html#Releases 27.1]<br />
|<br />
| {{ic|XDG_CONFIG_HOME/emacs/init.el}}<br />
Legacy paths have precedence over XDG paths. Emacs will never create {{ic|XDG_CONFIG_HOME/emacs/}}.<br />
Workaround for 26.3 or older: It's possible to set {{ic|HOME}}, but it has unexpected side effects.<br />
|-<br />
| [[fish]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|fltk}}<br />
| {{ic|~/.fltk/}}<br />
| [https://github.com/fltk/fltk/commit/7308bcdb74e34626c6459699cb57371afd7b343b 7308bcd]<br />
| [https://www.fltk.org/str.php?L3370+P0+S0+C0+I0+E0+V%25+Qxdg] [https://github.com/fltk/fltk/issues/79]<br />
| Only supported in version 1.4.0, which hasn't been released yet (as of 9-July-2022)<br />
|-<br />
| [[fontconfig]]<br />
| {{ic|~/.fontconfig}} {{ic|~/.fonts}}<br />
| [https://gitlab.freedesktop.org/fontconfig/fontconfig/-/commit/8c255fb 8c255fb], [https://gitlab.freedesktop.org/fontconfig/fontconfig/-/commit/437f03299bd1adc9673cd576072f1657be8fd4e0]<br />
|<br />
| Config goes in {{ic|XDG_CONFIG_HOME/fontconfig/fonts.conf}} or {{ic|XDG_CONFIG_HOME/fontconfig/conf.d/}}, fonts are stored in {{ic|XDG_DATA_HOME/fonts/}}<br />
|-<br />
| {{Pkg|fontforge}}<br />
| {{ic|~/.FontForge}} {{ic|~/.PfaEdit}}<br />
| [https://github.com/fontforge/fontforge/commit/e4c2cc7 e4c2cc7]<br />
|<br />
[https://github.com/fontforge/fontforge/issues/847]<br />
[https://github.com/fontforge/fontforge/issues/991]<br />
|<br />
|-<br />
| {{Pkg|freecad}}<br />
| {{ic|~/.FreeCAD}}<br />
| [https://github.com/FreeCAD/FreeCAD/commit/e7e2994ba e7e2994ba]<br />
[https://github.com/FreeCAD/FreeCAD/releases/tag/0.20 0.20.0]<br />
| [https://forum.freecad.org/viewtopic.php?f=9&t=63648]<br />
| Defaults to<br />
XDG_CONFIG_HOME/FreeCAD<br />
XDG_DATA_HOME/FreeCAD<br />
XDG_CACHE_HOME/FreeCAD<br />
legacy path can be used with {{ic|FreeCAD --keep-deprecated-paths}}<br />
|-<br />
| {{Pkg|freerdp}}<br />
| {{ic|~/.freerdp}}<br />
| [https://github.com/FreeRDP/FreeRDP/commit/edf6e72 edf6e72]<br />
|<br />
|<br />
|-<br />
| [[Gajim]]<br />
| {{ic|~/.gajim}}<br />
| [https://dev.gajim.org/gajim/gajim/commit/3e777ea 3e777ea]<br />
| [https://dev.gajim.org/gajim/gajim/issues/2149]<br />
|<br />
|-<br />
| {{AUR|gconf}}<br />
| {{ic|~/.gconf}}<br />
| [https://gitlab.gnome.org/Archive/gconf/commit/fc28caa fc28caa]<br />
| [https://bugzilla.gnome.org/show_bug.cgi?id=674803]<br />
|-<br />
| [[GDB]]<br />
| {{ic|~/.gdbinit}}, {{ic|~/.gdb_history}}<br />
| [https://lists.gnu.org/archive/html/info-gnu/2021-09/msg00007.html 11.1]<br />
|<br />
| {{ic|XDG_CONFIG_HOME/gdb/gdbinit}}, {{ic|1=export GDBHISTFILE="$XDG_DATA_HOME"/gdb/history}}<br />
|-<br />
| [[GIMP]]<br />
| {{ic|~/.gimp-x.y}} {{ic|~/.thumbnails}}<br />
|<br />
[https://gitlab.gnome.org/GNOME/gimp/commit/60e0cfe 60e0cfe]<br />
[https://gitlab.gnome.org/GNOME/gimp/commit/483505f 483505f]<br />
|<br />
[https://bugzilla.gnome.org/show_bug.cgi?id=166643]<br />
[https://bugzilla.gnome.org/show_bug.cgi?id=646644]<br />
|<br />
|-<br />
| [[Git]]<br />
| {{ic|~/.gitconfig}}<br />
| [https://github.com/git/git/commit/0d94427 0d94427]<br />
|<br />
| {{ic|XDG_CONFIG_HOME/git/config}}<br />
|-<br />
| [https://github.com/google/gops gops]<br />
|<br />
| [https://github.com/google/gops/commit/71c4255 71c4255]<br />
|<br />
|<br />
|-<br />
| [[Wikipedia:gnuplot|gnuplot]]<br />
| {{ic|~/.gnuplot_history}}<br />
| [https://sourceforge.net/p/gnuplot/gnuplot-main/ci/a5562b1/ a5562b1]<br />
[https://sourceforge.net/p/gnuplot/gnuplot-main/merge-requests/12/]<br />
|<br />
|<br />
|-<br />
| {{AUR|goobook}}<br />
| {{ic|~/.goobookrc}}<br />
| [https://gitlab.com/goobook/goobook/-/blob/master/CHANGES.rst 3.5]<br />
| [https://gitlab.com/goobook/goobook/-/merge_requests/11]<br />
| {{ic|XDG_CONFIG_HOME/goobookrc}}<br />
|-<br />
| [[Godot Engine]]<br />
| {{ic|~/.godot}}<br />
| [https://github.com/godotengine/godot/pull/12988/commits/73049d115e190b8c356f0689a9079c3c73cc5765 73049d1]<br />
[https://github.com/godotengine/godot/releases/tag/3.0-stable 3.0-stable]<br />
| [https://github.com/godotengine/godot/issues/3513]<br />
|<br />
|-<br />
| [[GStreamer]]<br />
| {{ic|~/.gstreamer-0.10}}<br />
| [https://gitlab.freedesktop.org/gstreamer/gstreamer/-/commit/4e36f93 4e36f93]<br />
| [https://bugzilla.gnome.org/show_bug.cgi?id=518597]<br />
|<br />
|-<br />
| [[GTK]] 3<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|helm}}<br />
| {{ic|~/.helm}}<br />
| [https://github.com/helm/helm/releases/tag/v3.0.0 3.0.0]<br />
|<br />
|<br />
|-<br />
| {{Pkg|htop}}<br />
| {{ic|~/.htoprc}}<br />
| [https://github.com/hishamhm/htop/commit/93233a6 93233a6]<br />
|<br />
|<br />
|-<br />
| {{Pkg|httpie}}<br />
| {{ic|~/.httpie}}<br />
| [https://github.com/httpie/httpie/commit/5af0874ed302e9ef79cec97836529ccf353e53f7 5af0874]<br />
| [https://github.com/httpie/httpie/issues/145]<br />
|<br />
|-<br />
| [[i3]]<br />
| {{ic|~/.i3}}<br />
| [http://code.stapelberg.de/git/i3/commit/?id=7c130fb 7c130fb]<br />
|<br />
|<br />
|-<br />
| {{Pkg|i3blocks}}, {{AUR|i3blocks-git}}<br />
|<br />
| [https://github.com/vivien/i3blocks/commit/a1782404c7d933145b048d0d1872ea40d7a293b6]<br />
|<br />
|<br />
|-<br />
| [https://archlinux.org/packages/?name=i3-gaps i3-gaps]<br />
|<br />
| [https://github.com/Airblader/i3/commit/7c130fb540da378c4ba3744d2ff39983df3ad705]<br />
|<br />
|<br />
|-<br />
| {{Pkg|i3status}}<br />
| {{ic|~/.i3status.conf}}<br />
| [http://code.stapelberg.de/git/i3status/commit/?id=c3f7fc4 c3f7fc4]<br />
|<br />
|<br />
|-<br />
| {{Pkg|i3status-rust}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|imagemagick}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[Inkscape]]<br />
| {{ic|~/.inkscape}}<br />
| [https://wiki.inkscape.org/wiki/index.php/Release_notes/0.47#Preferences 0.47]<br />
| [https://bugs.launchpad.net/inkscape/+bug/199720]<br />
|<br />
|-<br />
| [http://ipython.org ipython]<br />
| {{ic|~/.ipython}}<br />
| [https://ipython.readthedocs.io/en/stable/whatsnew/version8.html#re-added-support-for-xdg-config-directories 8.0.0]<br />
| [https://github.com/ipython/ipython/pull/13224]<br />
| The default dotfile path is still $HOME but xdg directories (or ~/.config/ipython if XDG_* vars are unset) are supported and work correctly.<br />
|-<br />
| [https://iwd.wiki.kernel.org/ iwd] / iwctl<br />
| {{ic|~/.iwctl_history}}<br />
| [https://git.kernel.org/pub/scm/network/wireless/iwd.git/commit/?id=d3e00d7f d3e00d7f]<br />
|<br />
|<br />
|-<br />
| {{Pkg|intellij-idea-community-edition}} / {{AUR|intellij-idea-ultimate-edition}}<br />
| {{ic|~/.IntelliJIdeaXXXX.X}}<br />
| [https://confluence.jetbrains.com/display/IDEADEV/IntelliJ%2BIDEA%2B2020.1%2B%28201.6668.121%2Bbuild%29%2BRelease%2BNotes 2020.1]<br />
| [https://youtrack.jetbrains.com/issue/IDEA-22407]<br />
|<br />
XDG_CONFIG_HOME/JetBrains/IntelliJIdeaXXXX.X<br />
XDG_DATA_HOME/JetBrains/IntelliJIdeaXXXX.X<br />
XDG_CACHE_HOME/JetBrains/IntelliJIdeaXXXX.X<br />
|-<br />
| {{Pkg|josm}}<br />
| {{ic|~/.josm}}<br />
| [https://josm.openstreetmap.de/changeset/11162/josm 11162]<br />
| [https://josm.openstreetmap.de/ticket/6664]<br />
|<br />
|-<br />
| [https://github.com/jupyter jupyter]<br />
| {{ic|~/.jupyter}}<br />
| opt-in in 5.0, opt-out in 6.0, compulsory in 7.0 ([https://github.com/jupyter/jupyter_core/blob/f5ab1ac19225c7925282e9c5ae466767b4086361/CHANGELOG.md#migrate-to-standard-platform-directories changelog])<br />
| <br />
| {{ic|XDG_CONFIG_HOME/jupyter}}<br />
|-<br />
| [[Kakoune]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|keynav}}<br />
| {{ic|~/.keynavrc}}<br />
|<br />
|<br />
| {{ic|XDG_CONFIG_HOME/keynav/keynavrc}}<br />
|-<br />
| [[Core utilities|less]]<br />
| {{ic|~/.lesshst}}, {{ic|~/.lesskey}}<br />
| [https://www.greenwoodsoftware.com/less/news.590.html 590]<br />
full support in [https://www.greenwoodsoftware.com/less/news.600.html 600]<br />
| [https://github.com/gwsw/less/issues/153]<br />
| The environment variables {{ic|XDG_CONFIG_HOME}} and {{ic|XDG_DATA_HOME}} '''must''' be set in version 590. This is no longer necessary when version 600 lands.<br />
|-<br />
| latexmk (in {{Pkg|texlive-core}})<br />
| {{ic|~/.latexmkrc}}<br />
|<br />
|<br />
|<br />
{{ic|XDG_CONFIG_HOME/latexmk/latexmkrc}}<br />
|-<br />
| {{Pkg|lftp}}<br />
| {{ic|~/.lftp}}<br />
| [https://github.com/lavv17/lftp/commit/21dc400 21dc400]<br />
| [https://www.mail-archive.com/lftp@uniyar.ac.ru/msg04301.html]<br />
|<br />
|-<br />
| {{AUR|lgogdownloader}}<br />
| {{ic|~/.gogdownloader}}<br />
| [https://github.com/Sude-/lgogdownloader/commit/d430af6 d430af6]<br />
| [https://github.com/Sude-/lgogdownloader/issues/4]<br />
|<br />
|-<br />
| [[LibreOffice]]<br />
|<br />
|<br />
[https://cgit.freedesktop.org/libreoffice/ure/commit/?id=a6f56f7 a6f56f7]<br />
[https://cgit.freedesktop.org/libreoffice/bootstrap/commit/?id=25bd2ee 25bd2ee]<br />
| [https://bugs.documentfoundation.org/show_bug.cgi?id=32263]<br />
|<br />
|-<br />
| {{Pkg|luarocks}}<br />
| {{ic|~/.luarocks}}<br />
| [https://github.com/luarocks/luarocks/pull/1298/commits/cd16cdd5f889024f28cc384e3d721a4f4a3261d3 cd16cdd]<br />
| [https://github.com/luarocks/luarocks/pull/1298]<br />
|<br />
XDG_CONFIG_HOME/luarocks<br />
XDG_CACHE_HOME/luarocks<br />
<br />
If the legacy path {{ic|~/.luarocks}} is present, it will take precedence.<br />
|-<br />
| [https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS NSS]<br />
| {{ic|~/.pki}}<br />
| [https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/NSS_3.42_release_notes 3.42]<br />
| [https://bugzilla.mozilla.org/show_bug.cgi?id=818686]<br />
|<br />
|-<br />
| [[Streamlink]]<br />
| {{ic|~/.livestreamerrc}}<br />
| [https://github.com/chrippa/livestreamer/commit/ea80591 ea80591]<br />
| [https://github.com/chrippa/livestreamer/pull/106]<br />
|<br />
|-<br />
| [[mc]]<br />
| {{ic|~/.mc}}<br />
|<br />
[https://github.com/MidnightCommander/mc/commit/1b99570 1b99570]<br />
[https://github.com/MidnightCommander/mc/commit/0b71156 0b71156]<br />
[https://github.com/MidnightCommander/mc/commit/ce401d7 ce401d7]<br />
| [https://www.midnight-commander.org/ticket/1851]<br />
|<br />
|-<br />
| [[Mercurial]]<br />
| {{ic|~/.hgrc}}<br />
|<br />
[https://www.mercurial-scm.org/repo/hg/rev/3540200 3540200]<br />
[https://www.mercurial-scm.org/wiki/Release4.2 4.2]<br />
|<br />
| {{ic|XDG_CONFIG_HOME/hg/hgrc}}.<br />
|-<br />
| [[msmtp]]<br />
| {{ic|~/.msmtprc}}<br />
|<br />
[https://github.com/marlam/msmtp-mirror/commit/af2f409 af2f409]<br />
v1.6.7+<br />
|<br />
| {{ic| XDG_CONFIG_HOME/msmtp/config}}.<br />
|-<br />
| {{Pkg|mesa}}<br />
|<br />
| [https://gitlab.freedesktop.org/mesa/mesa/-/commit/87ab26b 87ab26b]<br />
|<br />
| {{ic|XDG_CACHE_HOME/mesa}}<br />
|-<br />
| {{Pkg|milkytracker}}<br />
| {{ic|~/.milkytracker_config}}<br />
| [https://github.com/Deltafire/MilkyTracker/commit/eb487c5 eb487c5]<br />
| [https://github.com/Deltafire/MilkyTracker/issues/12]<br />
|<br />
|-<br />
| [[mozc]]<br />
| {{ic|~/.mozc}}<br />
| [https://github.com/google/mozc/commit/91cc1e19ef34aeb12888b697fefa52907f1a834d 91cc1e1]<br />
| [https://github.com/google/mozc/issues/474]<br />
|<br />
|-<br />
| [[mpd]]<br />
| {{ic|~/.mpdconf}}<br />
| [https://github.com/MusicPlayerDaemon/MPD/commit/87b7328 87b7328]<br />
|<br />
|<br />
|-<br />
| [[mpv]]<br />
| {{ic|~/.mpv}}<br />
| [https://github.com/mpv-player/mpv/commit/cb250d4 cb250d4]<br />
| [https://github.com/mpv-player/mpv/pull/864]<br />
|<br />
|-<br />
| [[mutt]]<br />
| {{ic|~/.mutt}}<br />
| [https://gitlab.com/muttmua/mutt/commit/b17cd67 b17cd67]<br />
| [https://gitlab.com/muttmua/trac-tickets/raw/master/tickets/closed/3207-Conform_to_XDG_Base_Directory_Specification.txt]<br />
|<br />
|-<br />
| {{Pkg|mypaint}}<br />
| {{ic|~/.mypaint}}<br />
| [https://github.com/mypaint/mypaint/commit/cf723b7 cf723b7]<br />
|<br />
|<br />
|-<br />
| [[nano]]<br />
| {{ic|~/.nano/}} {{ic|~/.nanorc}}<br />
| [https://git.savannah.gnu.org/cgit/nano.git/commit/?id=c16e79b c16e79b]<br />
| [https://savannah.gnu.org/patch/?8523]<br />
|<br />
|-<br />
| [[ncmpcpp]]<br />
| {{ic|~/.ncmpcpp}}<br />
|<br />
[https://github.com/arybczak/ncmpcpp/commit/38d9f81 38d9f81]<br />
[https://github.com/arybczak/ncmpcpp/commit/27cd86e 27cd86e]<br />
|<br />
[https://github.com/arybczak/ncmpcpp/issues/79]<br />
[https://github.com/arybczak/ncmpcpp/issues/110]<br />
| {{ic|ncmpcpp_directory}} should be set to avoid an {{ic|error.log}} file in {{ic|~/.ncmpcpp}}.<br />
|-<br />
| [[Neovim]]<br />
| {{ic|~/.nvim}} {{ic|~/.nvimlog}} {{ic|~/.nviminfo}}<br />
| [https://github.com/neovim/neovim/commit/1ca5646 1ca5646]<br />
|<br />
[https://github.com/neovim/neovim/issues/78]<br />
[https://github.com/neovim/neovim/pull/3198]<br />
|<br />
|-<br />
| [http://0ldsk00l.ca/nestopia/ Nestopia UE]<br />
| {{ic|~/.nestopia/}}<br />
| [https://github.com/0ldsk00l/nestopia/commit/d78381198a26a10333128e9bf28bc530a610c008 610c008] [https://github.com/0ldsk00l/nestopia/releases/tag/1.51.0 1.51.0]<br />
| [https://github.com/0ldsk00l/nestopia/issues/343]<br />
|<br />
|-<br />
| [[newsboat]]<br />
| {{ic|~/.newsboat}}<br />
| [https://github.com/akrennmair/newsbeuter/commit/3c57824 3c57824]<br />
| [https://github.com/akrennmair/newsbeuter/pull/39]<br />
| It is required to create both directories [https://man.archlinux.org/man/newsboat.1#FILES]:<br />
<br />
{{ic|1=mkdir -p "$XDG_DATA_HOME"/newsboat "$XDG_CONFIG_HOME"/newsboat}}<br />
|-<br />
| [https://github.com/nodejs/node-gyp node-gyp]<br />
| {{ic|~/.node-gyp}}<br />
| [https://github.com/nodejs/node-gyp/commit/2b5ce52a 2b5ce52a]<br />
| [https://github.com/nodejs/node-gyp/pull/1570]<br />
|<br />
|-<br />
| {{AUR|np2kai-git}}<br />
| {{ic|~/.config/np2kai}} {{ic|~/.config/xnp2kai}}<br />
| [https://github.com/AZO234/NP2kai/commit/56a1cc2 56a1cc2]<br />
| [https://github.com/AZO234/NP2kai/pull/50]<br />
|<br />
|-<br />
| [[notmuch]]<br />
| {{ic|~/.notmuch-config}}<br />
|<br />
| [https://notmuchmail.org/pipermail/notmuch/2011/007007.html]<br />
| {{ic|mkdir -p $XDG_CONFIG_HOME/notmuch/default; mv ~/.notmuch-config $XDG_CONFIG_HOME/notmuch/default/config}}<br />
|-<br />
| {{AUR|nteract-bin}}<br />
|<br />
| [https://github.com/nteract/nteract/commit/4593e72 4593e72]<br />
| [https://github.com/nteract/nteract/issues/180] [https://github.com/nteract/nteract/pull/3870]<br />
| [https://github.com/nteract/nteract/issues/4517 does not recognize workarounds for ipython/jupyter]<br />
|-<br />
| [[OfflineIMAP]]<br />
| {{ic|~/.offlineimaprc}}<br />
| [https://github.com/OfflineIMAP/offlineimap/commit/5150de5 5150de5]<br />
| [https://github.com/OfflineIMAP/offlineimap/issues/32]<br />
| {{ic|XDG_CONFIG_HOME/offlineimap/config}}<br />
|-<br />
| {{AUR|opentyrian}}<br />
| {{ic|~/.opentyrian}}<br />
| [https://github.com/opentyrian/opentyrian/commit/39559c3 39559c3]<br />
| [https://web.archive.org/web/20140815181350/http://code.google.com/p/opentyrian/issues/detail?id=125]<br />
|<br />
|-<br />
| {{AUR|osc}}<br />
| {{ic|~/.oscrc}} {{ic|~/.osc_cookiejar}} <br />
| [https://github.com/openSUSE/osc/commit/6bc2d3f939c2518ae555fbf75e3a11cc16fc5302 6bc2d3f]<br />
[https://github.com/openSUSE/osc/commit/ebcf3de6abe1ae142baa5bee4c9867cc1968bad1 ebcf3de]<br />
|[https://github.com/openSUSE/osc/pull/940 github.com/openSUSE/osc/pull/940]<br />
[https://github.com/openSUSE/osc/pull/940 github.com/osc/pull/940]<br />
|<br />
{{ic|XDG_CONFIG_HOME/osc/oscrc}}<br />
{{ic|XDG_STATE_HOME/osc/cookiejar}}<br />
<br />
Legacy path takes precedence if it exists<br />
|-<br />
| {{Pkg|pam-u2f}}<br />
| {{ic|~/.config/Yubico/u2f_keys}}<br />
| [https://github.com/Yubico/pam-u2f/commit/ad52dd82dead525dab94ded1916dcf6334459106 ad52dd8]<br />
| [https://github.com/Yubico/pam-u2f/issues/9]<br />
| {{ic|XDG_CONFIG_HOME/Yubico/u2f_keys}}<br />
|-<br />
| {{Pkg|pandoc}}<br />
| {{ic|~/.pandoc/}}<br />
| [https://github.com/jgm/pandoc/commit/0bed0ab5a308f5e72a01fa9bee76488556288862 0bed0ab]<br />
| [https://github.com/jgm/pandoc/issues/3582]<br />
|<br />
|-<br />
| [[PCManFM]]<br />
| {{ic|~/.thumbnails}}<br />
| [https://github.com/lxde/libfm/issues/57 1.3.2]<br />
|<br />
|<br />
|-<br />
| {{AUR|pcsx2}}<br />
| {{ic|~/.pcsx2}}<br />
|<br />
[https://github.com/PCSX2/pcsx2/commit/87f1e8f 87f1e8f]<br />
[https://github.com/PCSX2/pcsx2/commit/a9020c6 a9020c6]<br />
[https://github.com/PCSX2/pcsx2/commit/3b22f0f 3b22f0f]<br />
[https://github.com/PCSX2/pcsx2/commit/0a012ae 0a012ae]<br />
| [https://github.com/PCSX2/pcsx2/issues/352] [https://github.com/PCSX2/pcsx2/issues/381]<br />
| <br />
|-<br />
| {{AUR|pdfsam}}<br />
| {{ic|~/.openjfx}}<br />
|<br />
|<br />
| {{ic|1=export _JAVA_OPTIONS=-Djavafx.cachedir="$XDG_CACHE_HOME"/openjfx}}<br />
|-<br />
| [https://pry.github.io/ Pry]<br />
| {{ic|~/.pryrc}} {{ic|~/.pry_history}}<br />
|<br />
[https://github.com/pry/pry/commit/a0be0cc7b2070edff61c0c7f10fa37fce9b730bd a0be0cc7]<br />
[https://github.com/pry/pry/commit/15e1fc929ed84c161abc5afc9be73488a41df397 15e1fc92]<br />
[https://github.com/pry/pry/commit/e9d1be0e17b294318dbb2f70f74a50486cfa044c e9d1be0e]<br />
| [https://github.com/pry/pry/issues/1316]<br />
|<br />
|-<br />
| {{Pkg|python-pylint}}<br />
| {{ic|~/.pylint.d}}<br />
| [https://github.com/PyCQA/pylint/pull/4661 2.10]<br />
| [https://github.com/PyCQA/pylint/issues/1364]<br />
| Formerly {{ic|1=export PYLINTHOME="$XDG_CACHE_HOME"/pylint}}, global config still needs: {{ic|1=export PYLINTRC="$XDG_CONFIG_HOME"/pylint/pylintrc}}<br />
|-<br />
| {{Pkg|python-pip}}<br />
| {{ic|~/.pip}}<br />
| [https://github.com/pypa/pip/blob/548a9136525815dff41acd845c558a0b36eb1c5f/NEWS.rst#60-2014-12-22 6.0]<br />
| [https://github.com/pypa/pip/issues/1733]<br />
|<br />
|-<br />
| {{Pkg|python-poetry}}<br />
| {{ic|~/.poetry}}<br />
| [https://github.com/python-poetry/poetry/pull/3706]<br />
| [https://github.com/python-poetry/poetry/issues/2148]<br />
| Still creates {{ic|~/.poetry}} according to [https://github.com/python-poetry/poetry/issues/2148#issuecomment-943951697]<br />
|-<br />
| {{AUR|powershell}}<br />
|<br />
| [https://docs.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-core-60#filesystem 6.0]<br />
|<br />
|<br />
|-<br />
| {{Pkg|ppsspp}}<br />
| {{ic|~/.ppsspp}}<br />
| [https://github.com/hrydgard/ppsspp/commit/132fe47 132fe47]<br />
| [https://github.com/hrydgard/ppsspp/issues/4623]<br />
|<br />
|-<br />
| {{Pkg|procps-ng}}<br />
| {{ic|~/.toprc}}<br />
| [https://gitlab.com/procps-ng/procps/commit/af53e17 af53e17]<br />
|<br />
[https://gitlab.com/procps-ng/procps/merge_requests/38]<br />
[https://bugzilla.redhat.com/show_bug.cgi?id=1155265]<br />
|<br />
|-<br />
| [[pacman]]<br />
| {{ic|~/.makepkg.conf}}<br />
| [https://gitlab.archlinux.org/pacman/pacman/commit/80eca94 80eca94]<br />
| [https://lists.archlinux.org/archives/list/pacman-dev@lists.archlinux.org/thread/KTD2FW7YKY724UB7PT3GGP5L7TNWZYEP/]<br />
|<br />
|-<br />
| {{AUR|panda3d}}<br />
| {{ic|~/.panda3d}}<br />
| [https://github.com/panda3d/panda3d/commit/2b537d2 2b537d2]<br />
|<br />
|<br />
|-<br />
| {{AUR|poezio}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[PulseAudio]]<br />
| {{ic|~/.pulse}} {{ic|~/.pulse-cookie}}<br />
|<br />
[https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/commit/59a8618 59a8618]<br />
[https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/commit/87ae830 87ae830]<br />
[https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/commit/9ab510a 9ab510a]<br />
[https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/commit/4c195bc 4c195bc]<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=845607]<br />
|<br />
|-<br />
| {{AUR|pyroom}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|quodlibet}}<br />
| {{ic|~/.quodlibet}}<br />
| 3.10.0<br />
| [https://github.com/quodlibet/quodlibet/issues/138]<br />
|<br />
|-<br />
| [[qutebrowser]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[qtile]]<br />
|<br />
|<br />
[https://github.com/qtile/qtile/commit/fd8686e fd8686e]<br />
[https://github.com/qtile/qtile/commit/66d704b 66d704b]<br />
[https://github.com/qtile/qtile/commit/51cff01 51cff01]<br />
| [https://github.com/qtile/qtile/pull/835]<br />
| Some optional bar widgets can create files and directories in non-compliant paths, but most often these are still configurable.<br />
|-<br />
| {{Pkg|rclone}}<br />
| {{ic|~/.rclone.conf}}<br />
| [https://github.com/ncw/rclone/commit/9d36258 9d36258]<br />
| [https://github.com/ncw/rclone/issues/868]<br />
|<br />
|-<br />
| {{Pkg|retroarch}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|rr}}<br />
| {{ic|~/.rr}}<br />
| [https://github.com/mozilla/rr/commit/02e7d41 02e7d41]<br />
| [https://github.com/mozilla/rr/issues/1455]<br />
|<br />
|-<br />
| [https://rspec.info RSpec]<br />
| {{ic|~/.rspec}}<br />
| [https://github.com/rspec/rspec-core/commit/5e395e2016f1da19475e6db2817eb26dae828c4c 5e395e2]<br />
| [https://github.com/rspec/rspec-core/issues/1773]<br />
|<br />
|-<br />
| [[rTorrent]]<br />
| {{ic|~/.rtorrent.rc}}<br />
| [https://github.com/rakshasa/rtorrent/commit/6a8d332 6a8d332]<br />
|<br />
|<br />
|-<br />
| [https://www.rubocop.org RuboCop]<br />
| {{ic|~/.rubocop.yml}}<br />
| [https://github.com/rubocop-hq/rubocop/commit/6fe5956c177ca369cfaa70bdf748b70020a56bf4 6fe5956]<br />
| [https://github.com/rubocop-hq/rubocop/issues/6662]<br />
|<br />
|-<br />
| [[Ruby#RubyGems]]<br />
| {{ic|~/.gem}}<br />
| [https://github.com/ruby/ruby/commit/5c6269c 3.0.0 (5c6269c)]<br />
| [https://github.com/ruby/ruby/pull/2174]<br />
|<br />
XDG_CONFIG_HOME/gemrc<br />
XDG_CONFIG_HOME/irb<br />
XDG_DATA_HOME/gem<br />
XDG_DATA_HOME/rdoc<br />
|-<br />
| [https://github.com/benvan/sandboxd sandboxd]<br />
| {{ic|~/.sandboxrc}}<br />
| [https://github.com/benvan/sandboxd/pull/14]<br />
| [https://github.com/benvan/sandboxd/issues/11]<br />
| {{ic|XDG_CONFIG_HOME/sandboxd/sandboxrc}}<br />
|-<br />
| {{Pkg|scribus}}<br />
| {{ic|~/.scribus}}<br />
| [https://wiki.scribus.net/canvas/Versione_1.5.3 1.5.3]<br />
| <br />
|-<br />
| {{Pkg|scummvm}}<br />
| {{ic|~/.scummvmrc}} {{ic|~/.scummvm/}}<br />
| [https://github.com/scummvm/scummvm/commit/7d014be0a2b796175a7ce40a9315603f711b2a30 7d014be]<br />
| [https://github.com/scummvm/scummvm/pull/656]<br />
| It is required to migrate data by hand.<br />
{{ic|mkdir "$XDG_CONFIG_HOME"/scummvm/ "$XDG_DATA_HOME"/scummvm}}<br />
{{ic|mv ~/.scummvmrc "$XDG_CONFIG_HOME"/scummvm/scummvm.ini}}<br />
{{ic|mv ~/.scummvm "$XDG_DATA_HOME"/scummvm/saves}}<br />
|-<br />
| {{Pkg|sdcv}}<br />
| {{ic|~/.stardict/}} {{ic|~/.sdcv_history}}<br />
| [https://github.com/Dushistov/sdcv/commit/958ec35 958ec35]<br />
| [https://github.com/Dushistov/sdcv/issues/51]<br />
|<br />
|-<br />
| {{AUR|skypeforlinux-stable-bin}}<br />
| {{ic|~/.Skype}}<br />
| 8.0<br />
|<br />
|<br />
|-<br />
| {{Pkg|snes9x}}<br />
| {{ic|~/.snes9x}}<br />
| [https://github.com/snes9xgit/snes9x/commit/93b5f11 93b5f11]<br />
| [https://github.com/snes9xgit/snes9x/issues/194]<br />
| By default, the configuration file is left blank with intention that the user will fill it at their will (through the gui or manually).<br />
|-<br />
| [[spectrwm]]<br />
| {{ic|~/.spectrwm}}<br />
| [https://github.com/conformal/spectrwm/commit/a30bbb a30bbb]<br />
| [https://github.com/conformal/spectrwm/pull/153]<br />
|<br />
|-<br />
| {{AUR|sublime-text-dev}}<br />
|<br />
| [https://www.sublimetext.com/dev build 4105]<br />
|<br />
| Prior to build 4105, the cache was placed in {{ic|XDG_CONFIG_HOME/sublime-text-3/Cache}}.<br />
|-<br />
| [[surfraw]]<br />
| {{ic|~/.surfraw.conf}} {{ic|~/.surfraw.bookmarks}}<br />
|<br />
[https://gitlab.com/surfraw/Surfraw/commit/3e4591d 3e4591d]<br />
[https://gitlab.com/surfraw/Surfraw/commit/bd8c427 bd8c427]<br />
[https://gitlab.com/surfraw/Surfraw/commit/f57fc71 f57fc71]<br />
|<br />
|<br />
|-<br />
| [[sway]]<br />
| {{ic|~/.sway/config}}<br />
| [https://github.com/SirCmpwn/sway/commit/614393c 614393c]<br />
| [https://github.com/SirCmpwn/sway/issues/5]<br />
| {{ic|XDG_CONFIG_HOME/sway/config}}<br />
|-<br />
| [[sxhkd]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[systemd]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|teeworlds}}<br />
| {{ic|~/.teeworlds}}<br />
| [https://github.com/teeworlds/teeworlds/commit/d2e39d2f50684151490da446156622e69dd84a48]<br />
|<br />
|<br />
|-<br />
| [[termite]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|tig}}<br />
| {{ic|~/.tigrc}}, {{ic|~/.tig_history}}<br />
| [https://github.com/jonas/tig/blob/master/NEWS.adoc#tig-22 2.2]<br />
| [https://github.com/jonas/tig/issues/513]<br />
| {{ic|~/.local/share/tig}} directory must exist, writes to {{ic|~/.tig_history}} otherwise.<br />
|-<br />
| [[tmux]]<br />
| {{ic|~/.tmux.conf}}<br />
| [https://raw.githubusercontent.com/tmux/tmux/3.1/CHANGES 3.1]<br />
| [https://github.com/tmux/tmux/issues/142]<br />
| 3.1 introduced {{ic|~/.config/tmux/tmux.conf}} and in [https://github.com/tmux/tmux/blob/a5f99e14c6f264e568b860692b89d11f5298a3f2/CHANGES#L145 3.2] {{ic|XDG_CONFIG_HOME/tmux/tmux.conf}} was added<br />
|-<br />
| [[tmuxp]]<br />
| {{ic|~/.tmuxp}}<br />
| [https://tmuxp.git-pull.com/history.html#tmuxp-1-5-0-2018-10-02 1.5.0]<br />
| [https://github.com/tmux-python/tmuxp/pull/404]<br />
| Fixed in [https://tmuxp.git-pull.com/history.html#tmuxp-1-5-2-2019-06-02 1.5.2]<br />
|-<br />
| {{AUR|tmuxinator}}<br />
| {{ic|~/.tmuxinator}}<br />
| [https://github.com/tmuxinator/tmuxinator/pull/511/commits/2636923 2636923]<br />
| [https://github.com/tmuxinator/tmuxinator/pull/511]<br />
|<br />
|-<br />
| [[Transmission]]<br />
| {{ic|~/.transmission}}<br />
| [https://github.com/transmission/transmission/commit/b71a298 b71a298]<br />
|<br />
|<br />
|-<br />
| {{Pkg|util-linux}}<br />
|<br />
| [https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git/commit/?id=570b321 570b321]<br />
|<br />
|<br />
|-<br />
| [[Uzbl]]<br />
|<br />
| [https://github.com/uzbl/uzbl/commit/c6fd63a c6fd63a]<br />
| [https://github.com/uzbl/uzbl/pull/150]<br />
|<br />
|-<br />
| {{Pkg|vimb}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[VirtualBox]]<br />
| {{ic|~/.VirtualBox}}<br />
| [https://www.virtualbox.org/ticket/5099?action=diff&version=7 4.3]<br />
| [https://www.virtualbox.org/ticket/5099]<br />
|<br />
|-<br />
| {{Pkg|vis}}<br />
| {{ic|~/.vis}}<br />
|<br />
[https://github.com/martanne/vis/commit/68a25c7 68a25c7]<br />
[https://github.com/martanne/vis/commit/d138908 d138908]<br />
| [https://github.com/martanne/vis/pull/303]<br />
|<br />
|-<br />
| [[VLC]]<br />
| {{ic|~/.vlcrc}}<br />
| [https://git.videolan.org/?p=vlc.git;a=commit;h=16f32e1 16f32e1]<br />
| [https://trac.videolan.org/vlc/ticket/1267]<br />
|<br />
|-<br />
| {{Pkg|warsow}}<br />
| {{ic|~/.warsow-2.x}}<br />
| [https://github.com/Qfusion/qfusion/commit/98ece3f 98ece3f]<br />
| [https://github.com/Qfusion/qfusion/issues/298]<br />
|<br />
|-<br />
| [[WeeChat]]<br />
| {{ic|~/.weechat}}<br />
| [https://github.com/weechat/weechat/commit/70cdf21681d75090c3df9858c9e7ce5a85433856]<br />
[https://github.com/weechat/weechat/releases/tag/v3.2 3.2]<br />
| [https://github.com/weechat/weechat/issues/1285] [https://specs.weechat.org/specs/001285-follow-xdg-base-dir-spec.html]<br />
|<br />
XDG_CONFIG_HOME/weechat<br />
XDG_CACHE_HOME/weechat<br />
XDG_DATA_HOME/weechat<br />
|-<br />
| [[Wireshark]]<br />
| {{ic|~/.wireshark}}<br />
| [https://code.wireshark.org/review/gitweb?p=wireshark.git;a=commit;h=b0b53fa b0b53fa]{{Dead link|2022|09|23|status=domain name not resolved}}<br />
|<br />
|<br />
|-<br />
| [https://wxwidgets.org/ wxWidgets]<br />
| <br />
| [https://trac.wxwidgets.org/ticket/17727]<br />
|<br />
|<br />
|-<br />
| [[Xsettingsd]]<br />
| {{ic|~/.xsettingsd}}<br />
| [https://github.com/derat/xsettingsd/commit/b4999f5 b4999f5]<br />
|<br />
|<br />
|-<br />
| [[xmobar]]<br />
| {{ic|~/.xmobarrc}}<br />
| [https://github.com/jaor/xmobar/commit/7b0d6bf 7b0d6bf]<br />
[https://github.com/jaor/xmobar/commit/9fc6b37 9fc6b37]<br />
[https://github.com/jaor/xmobar/commit/eaccf70 eaccf70]<br />
| [https://github.com/jaor/xmobar/pull/99]<br />
[https://github.com/jaor/xmobar/pull/131]<br />
| {{ic|XDG_CONFIG_HOME/xmobar/xmobarrc}}<br />
|-<br />
| [[xmonad]]<br />
| {{ic|~/.xmonad/}}<br />
| [https://github.com/xmonad/xmonad/commit/40fc10b 40fc10b]<br />
|<br />
[https://github.com/xmonad/xmonad/issues/61]<br />
[https://code.google.com/p/xmonad/issues/detail?id=484]<br />
| All of these must exist, otherwise it gives up and falls back to {{ic|~/.xmonad/}} for each:<br />
XDG_CACHE_HOME/xmonad<br />
XDG_CONFIG_HOME/xmonad<br />
XDG_DATA_HOME/xmonad<br />
Alternatively, it always respects {{ic|XMONAD_CACHE_DIR}}, {{ic|XMONAD_CONFIG_DIR}}, and {{ic|XMONAD_DATA_DIR}}.<br />
|-<br />
| {{Pkg|xournalpp}}<br />
| {{ic|~/.xournalpp}}<br />
|<br />
[https://github.com/xournalpp/xournalpp/commit/20db937f 20db937f]<br />
[https://github.com/xournalpp/xournalpp/releases/tag/1.1.0 1.1.0]<br />
|<br />
[https://github.com/xournalpp/xournalpp/issues/1101]<br />
[https://github.com/xournalpp/xournalpp/pull/1384]<br />
|-<br />
| {{Pkg|xsel}}<br />
| {{ic|~/.xsel.log}}<br />
| [https://github.com/kfish/xsel/commit/ee7b481 ee7b481]<br />
| [https://github.com/kfish/xsel/issues/10]<br />
|<br />
|-<br />
| [[Zim]]<br />
| <br />
| [https://github.com/zim-desktop-wiki/zim-desktop-wiki/commit/e42b8b0 e42b8b0]<br />
| <br />
|<br />
|-<br />
| {{Pkg|zoxide}}<br />
| {{ic|~/.zo}}<br />
| [https://github.com/ajeetdsouza/zoxide/releases/tag/v0.3.0 0.3.0]<br />
| [https://github.com/ajeetdsouza/zoxide/pull/47]<br />
|<br />
|}<br />
<br />
=== Partial ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Supported Since<br />
! Discussion<br />
! Notes<br />
|-<br />
| {{AUR|abook}}<br />
| {{ic|~/.abook}}<br />
|<br />
|<br />
| {{ic|1=abook --config "$XDG_CONFIG_HOME"/abook/abookrc --datafile "$XDG_DATA_HOME"/abook/addressbook}}<br />
|-<br />
| {{Pkg|ack}}<br />
| {{ic|~/.ackrc}}<br />
|<br />
| [https://github.com/beyondgrep/ack2/issues/516]<br />
| {{ic|1=export ACKRC="$XDG_CONFIG_HOME/ack/ackrc"}}<br />
|-<br />
| {{AUR|asdf-vm}}<br />
| {{ic|~/.asdfrc}}, {{ic|~/.asdf/}}<br />
|<br />
| [https://github.com/asdf-vm/asdf/issues/687]<br />
| {{ic|1=export ASDF_CONFIG_FILE="${XDG_CONFIG_HOME}/asdf/asdfrc"}}, {{ic|1=export ASDF_DATA_DIR=${XDG_DATA_HOME}/asdf"}}<br />
|-<br />
| [[aspell]]<br />
| {{ic|~/.aspell.conf}}<br />
|<br />
| [https://github.com/GNUAspell/aspell/issues/560]<br />
| {{ic|1=export ASPELL_CONF="per-conf $XDG_CONFIG_HOME/aspell/aspell.conf; personal $XDG_CONFIG_HOME/aspell/en.pws; repl $XDG_CONFIG_HOME/aspell/en.prepl"}}<br />
|-<br />
| [[Atom]]<br />
| {{ic|~/.atom}}<br />
|<br />
| [https://github.com/atom/atom/issues/8281]<br />
| {{ic|1=export ATOM_HOME="$XDG_DATA_HOME"/atom}}<br />
|-<br />
| {{Pkg|aws-cli}}<br />
| {{ic|~/.aws}}<br />
| [https://github.com/aws/aws-cli/commit/fc5961ea2cc0b5976ac9f777e20e4236fd7540f5 1.7.45]<br />
| [https://github.com/aws/aws-cli/issues/2433]<br />
| {{ic|1=export AWS_SHARED_CREDENTIALS_FILE="$XDG_CONFIG_HOME"/aws/credentials}}, {{ic|1=export AWS_CONFIG_FILE="$XDG_CONFIG_HOME"/aws/config}}<br />
|-<br />
| {{Pkg|bash-completion}}<br />
| {{ic|~/.bash_completion}}<br />
|<br />
|<br />
| {{ic|1=export BASH_COMPLETION_USER_FILE="$XDG_CONFIG_HOME"/bash-completion/bash_completion}}<br />
|-<br />
| {{AUR|bashdb}}<br />
| {{ic|~/.bashdbinit, ~/.bashdb_hist}}<br />
|<br />
|<br />
| Like documented at [https://bashdb.sourceforge.net/bashdb.html#Command-Files], you can specify a file to run commands from. Thus, move the init file to {{ic|XDG_CONFIG_HOME/bashdb/bashdbinit}} and create an alias {{ic|1=alias bashdb='bashdb -x ${XDG_CONFIG_HOME:-$HOME/.config}/bashdb/bashdbinit'}}. Unfortunately the history file is hardcoded [https://sourceforge.net/p/bashdb/code/ci/bash-5.1/tree/lib/hist.sh#l28].<br />
|-<br />
| [[bazaar]]<br />
| {{ic|~/.bazaar}}, {{ic|~/.bzr.log}}<br />
| [https://bugs.launchpad.net/bzr/+bug/195397/comments/15 2.3.0]<br />
| [https://bugs.launchpad.net/bzr/+bug/195397]<br />
| Discussion in upstream bug states that bazaar will use {{ic|~/.config/bazaar}} if it exists. The logfile {{ic|~/.bzr.log}} might still be written.<br />
|-<br />
| {{Aur|btpd-git}}<br />
| {{ic|~/.btpd/}}<br />
|<br />
| [https://github.com/btpd/btpd/issues/55]<br />
| {{ic|1=btpd -d "$XDG_DATA_HOME"/.btpd}}<br />
{{ic|1=HOME="$XDG_DATA_HOME" btcli}}<br />
|-<br />
| {{Pkg|calc}}<br />
| {{ic|~/.calc_history}}<br />
|<br />
|<br />
|<br />
export CALCHISTFILE="$XDG_CACHE_HOME"/calc_history<br />
|-<br />
| [[Rust#Cargo]]<br />
| {{ic|~/.cargo}}<br />
|<br />
| [https://github.com/rust-lang/cargo/issues/1734] [https://github.com/rust-lang/rfcs/pull/1615] [https://github.com/rust-lang/cargo/pull/5183] [https://github.com/rust-lang/cargo/pull/148]<br />
| {{ic|1=export CARGO_HOME="$XDG_DATA_HOME"/cargo}}<br />
|-<br />
| {{Pkg|cataclysm-dda}}<br />
| {{ic|~/.cataclysm-dda}}<br />
|[https://github.com/archlinux/svntogit-community/commit/e81e479cbb02eaf0c9c3475810127f55bd3a7a7e 0.D-1]<br />
|[https://github.com/CleverRaven/Cataclysm-DDA/issues/12315]<br />
| partial support due to required compile time option<br />
|-<br />
| [https://github.com/mollifier/cd-bookmark cd-bookmark]<br />
| {{ic|~/.cdbookmark}}<br />
|<br />
| [https://github.com/mollifier/cd-bookmark/issues/3]<br />
| {{ic|1=export CD_BOOKMARK_FILE=$XDG_CONFIG_HOME/cd-bookmark/bookmarks}}<br />
or use the fork that has native XDG support: [https://github.com/erikw/cd-bookmark/]<br />
|-<br />
| {{pkg|cgdb}}<br />
| {{ic|~/.cgdb}}<br />
| [On master branch, but no release yet]<br />
| [https://github.com/cgdb/cgdb/issues/203] [https://github.com/cgdb/cgdb/blob/master/NEWS]<br />
| Set {{ic|1=export CGDB_DIR=$XDG_CONFIG_HOME/cgdb}} and move the config file to {{ic|XDG_CONFIG_HOME/cgdb/cgdbrc}}<br />
|-<br />
| {{AUR|chez-scheme}}<br />
| {{ic|~/.chezscheme_history}}<br />
|<br />
|<br />
| {{ic|1=petite --eehistory "$XDG_DATA_HOME"/chezscheme/history}}<br />
|-<br />
| [[Chromium]]<br />
| {{ic|~/.chromium}}, {{ic|~/.pki}}<br />
| [https://src.chromium.org/viewvc/chrome?revision=23057&view=revision 23057]<br />
| [https://groups.google.com/forum/#!topic/chromium-dev/QekVQxF3nho] [https://code.google.com/p/chromium/issues/detail?id=16976] [https://bugs.chromium.org/p/chromium/issues/detail?id=1038587]<br />
|<br />
|-<br />
| [https://www.cinelerra-gg.org/ cinelerra]<br />
| {{ic|~/.bcast5}}<br />
|<br />
| [https://cinelerra-gg.org/download/CinelerraGG_Manual/Environment_Variables_Custo.html]<br />
| {{ic|1=export CIN_CONFIG="$XDG_CONFIG_HOME"/bcast5}}<br />
|-<br />
| [[conky]]<br />
| {{ic|~/.conkyrc}}<br />
| [https://github.com/brndnmtthws/conky/commit/00481ee9a97025e8e2acd7303d080af1948f7980 00481ee]<br />
| [https://github.com/brndnmtthws/conky/issues/144]<br />
| {{ic|1=conky --config="$XDG_CONFIG_HOME"/conky/conkyrc}}<br />
|-<br />
| {{Pkg|claws-mail}}<br />
| {{ic|~/.claws-mail}}<br />
|<br />
| [https://lists.claws-mail.org/pipermail/users/2013-April/006087.html]<br />
| {{ic|1=claws-mail --alternate-config-dir "$XDG_DATA_HOME"/claws-mail}}<br />
|-<br />
| [[coreutils]]<br />
| {{ic|~/.dircolors}}<br />
|<br />
|<br />
| {{ic|1=eval $(dircolors "$XDG_CONFIG_HOME"/dircolors)}}<br />
|-<br />
| [http://www.dungeoncrawl.org/ crawl]<br />
| {{ic|~/.crawl}}<br />
|<br />
|<br />
| The trailing slash is required:<br />
<br />
{{ic|1=export CRAWL_DIR="$XDG_DATA_HOME"/crawl/}}<br />
|-<br />
| {{Pkg|clusterssh}}<br />
| {{ic|~/.clusterssh/}}<br />
|<br />
|<br />
| {{ic|1=alias cssh="cssh --config-file '$XDG_CONFIG_HOME/clusterssh/config'" }}<br />
{{hc|$XDG_CONFIG_HOME/clusterssh/config|2=<br />
extra_cluster_file=$HOME/.config/clusterssh/clusters<br />
extra_tag_file=$HOME/.config/clusterssh/tags<br />
}}<br />
Despite this, clusterssh will still create {{ic|~/.clusterssh/}}.<br />
|-<br />
| [[CUDA]]<br />
| {{ic|~/.nv}}<br />
|<br />
|<br />
| {{ic|1=export CUDA_CACHE_PATH="$XDG_CACHE_HOME"/nv}}<br />
|-<br />
| [[dict]]<br />
| {{ic|~/.dictrc}}<br />
|<br />
|<br />
| {{ic|1=dict -c "$XDG_CONFIG_HOME"/dict/dictrc}}<br />
|-<br />
| [[Docker]]<br />
| {{ic|~/.docker}}<br />
|<br />
|<br />
| {{ic|1=export DOCKER_CONFIG="$XDG_CONFIG_HOME"/docker}}<br />
|-<br />
| {{Pkg|docker-machine}}<br />
| {{ic|~/.docker/machine}}<br />
|<br />
|<br />
| {{ic|1=export MACHINE_STORAGE_PATH="$XDG_DATA_HOME"/docker-machine}}<br />
|-<br />
| [[DOSBox]]<br />
| {{ic|~/.dosbox/dosbox-0.74-2.conf}}<br />
|<br />
| [https://www.vogons.org/viewtopic.php?t=29599]<br />
| {{ic|1=dosbox -conf "$XDG_CONFIG_HOME"/dosbox/dosbox.conf}}<br />
|-<br />
| {{Pkg|dub}}<br />
| {{ic|~/.dub}}<br />
| [https://github.com/dlang/dub/pull/2281 v1.30.0-beta.1]<br />
| <br />
| Dub uses the {{ic|~/.dub}} directory for both user settings and caching downloaded packages. The directory can only be moved as a whole, using {{ic|1=export DUB_HOME="path/to/new/dub"}}.<br />
|-<br />
| [https://electrum.org Electrum Bitcoin Wallet]<br />
| {{ic|~/.electrum}}<br />
| [https://github.com/spesmilo/electrum/commit/c121230 c121230]<br />
|<br />
| {{ic|1=export ELECTRUMDIR="$XDG_DATA_HOME/electrum"}}<br />
|-<br />
| [[ELinks]]<br />
| {{ic|~/.elinks}}<br />
|<br />
|<br />
| {{ic|1=export ELINKS_CONFDIR="$XDG_CONFIG_HOME"/elinks}}<br />
|-<br />
| {{Pkg|elixir}}<br />
| {{ic|~/.mix}}<br />
| [https://github.com/elixir-lang/elixir/commit/afaf889 afaf889]<br />
| [https://github.com/elixir-lang/elixir/issues/8818] [https://github.com/elixir-lang/elixir/pull/9937]<br />
| Elixir do not fully conform to XDG specs, it will use XDG only if the environment variables are present, otherwise it will by default use legacy path.<br />
|-<br />
| [https://elm-lang.org/ Elm]<br />
| {{ic|~/.elm}}<br />
| <br />
| <br />
| {{ic|1=export ELM_HOME="$XDG_CONFIG_HOME"/elm}}<br />
|-<br />
| {{Pkg|fceux}}<br />
| {{ic|~/.fceux/}}<br />
|<br />
| [https://github.com/TASEmulators/fceux/issues/412]<br />
| {{ic|1=export FCEUX_HOME="$XDG_CONFIG_HOME"/fceux}}. Fceux will create {{ic|1=.fceux}} directory inside {{ic|1=$FCEUX_HOME}}.<br />
|-<br />
| [[FFmpeg]]<br />
| {{ic|~/.ffmpeg}}<br />
|<br />
|<br />
| {{ic|1=export FFMPEG_DATADIR="$XDG_CONFIG_HOME"/ffmpeg}}<br />
|-<br />
| {{AUR|flutter}}<br />
| {{ic|~/.flutter}}, {{ic|~/.flutter_settings}}, {{ic|~/.flutter_tool_state}}, {{ic|~/.pub-cache}}<br />
|<br />
| [https://github.com/flutter/flutter/issues/59430]<br />
|<br />
|-<br />
| {{AUR|fzf-git}}<br />
| {{ic|~/.fzf.bash, ~/.fzf.zsh}}<br />
| <br />
| [https://github.com/junegunn/fzf/pull/1282]<br />
| The shell init files will be installed to {{ic|XDG_CONFIG_HOME/fzf}} if the installation script is called with {{ic|--xdg}} for example {{ic| /usr/local/opt/fzf/install --xdg}}.<br />
|-<br />
| {{Pkg|emscripten}}<br />
| {{ic|~/.emscripten}}, {{ic|~/.emscripten_sanity}}, {{ic|~/.emscripten_ports}}, {{ic|~/.emscripten_cache__last_clear}}<br />
|<br />
| [https://github.com/kripken/emscripten/issues/3624]<br />
| {{ic|1=export EM_CONFIG="$XDG_CONFIG_HOME"/emscripten/config}}, {{ic|1=export EM_CACHE="$XDG_CACHE_HOME"/emscripten/cache}}, {{ic|1=export EM_PORTS="$XDG_DATA_HOME"/emscripten/cache}}, {{ic|emcc --em-config "$XDG_CONFIG_HOME"/emscripten/config --em-cache "$XDG_CACHE_HOME"/emscripten/cache}}<br />
|-<br />
| {{AUR|get_iplayer}}<br />
| {{ic|~/.get_iplayer}}<br />
|<br />
|<br />
| {{ic|1=export GETIPLAYERUSERPREFS="$XDG_DATA_HOME"/get_iplayer}}<br />
|-<br />
| [[getmail]]<br />
| {{ic|~/.getmail/getmailrc}}<br />
|<br />
|<br />
| {{ic|1=getmail --rcfile="$XDG_CONFIG_HOME/getmail/getmailrc" --getmaildir="$XDG_DATA_HOME/getmail"}}<br />
|-<br />
| {{Pkg|ghc}}<br />
| {{ic|~/.ghci}}<br />
| [https://gitlab.haskell.org/ghc/ghc/-/commit/763d28551de32377a1dca8bdde02979e3686f400]<br />
| [https://ghc.haskell.org/trac/ghc/ticket/6077]<br />
| Supported upstream from 9.4.1 [https://downloads.haskell.org/~ghc/9.4.1/docs/users_guide/9.4.1-notes.html?highlight=xdg], but as of 2022-09-24 Arch package is 9.0.2 and not yet up-to-date.<br />
|-<br />
| {{AUR|ghcup-hs-bin}}<br />
| {{ic|~/.ghcup}}<br />
| [https://gitlab.haskell.org/haskell/ghcup-hs/-/commit/80603662b4fcc42fd936f45608dc3bc924c7e498]<br />
| [https://gitlab.haskell.org/haskell/ghcup-hs/issues/39]<br />
| {{ic|1=export GHCUP_USE_XDG_DIRS=true}}<br />
The environment variable {{ic|GHCUP_USE_XDG_DIRS}} can be set to any non-empty value. See [https://www.haskell.org/ghcup/guide/#xdg-support].<br />
|-<br />
| {{AUR|gliv}}<br />
| {{ic|~/.glivrc}}<br />
|<br />
|<br />
| {{ic|1=gliv --glivrc="$XDG_CONFIG_HOME"/gliv/glivrc}}<br />
|-<br />
| {{Pkg|gnuradio}}<br />
| {{ic|~/.gnuradio}}<br />
|<br />
| [https://github.com/gnuradio/gnuradio/issues/3631]<br />
|<br />
|-<br />
| [[GnuPG]]<br />
| {{ic|~/.gnupg}}<br />
|<br />
| [https://bugs.gnupg.org/gnupg/issue1456] [https://bugs.gnupg.org/gnupg/issue1018]<br />
| {{ic|1=export GNUPGHOME="$XDG_DATA_HOME"/gnupg}}, {{ic|gpg2 --homedir "$XDG_DATA_HOME"/gnupg}}<br />
Note that this currently does not work out-of-the-box using systemd user units and socket-based activation, since the socket directory changes based on the hash of {{ic|$GNUPGHOME}}. You can get the new socket directory using {{ic|gpgconf --dry-run --create-socketdir}} and have to modify the systemd user units to listen on the correct sockets accordingly.<br />
|-<br />
| [[Go]]<br />
| {{ic|~/go}}<br />
| [https://github.com/golang/go/commit/ca8a055f5cc7c1dfa0eb542c60071c7a24350f76]<br />
|<br />
| {{ic|1=export GOPATH="$XDG_DATA_HOME"/go}}, {{ic|1=export GOMODCACHE="$XDG_CACHE_HOME"/go/mod}}<br />
If {{ic|GOMODCACHE}} is not set, it defaults to {{ic|$GOPATH/pkg/mod}} (see [https://go.dev/ref/mod#environment-variables]).<br />
{{ic|GOCACHE}} is supported and defaults to {{ic|$XDG_CACHE_HOME/go-build}} (see [https://pkg.go.dev/cmd/go#hdr-Build_and_test_caching]).<br />
|-<br />
| [[Google Earth]]<br />
| {{ic|~/.googleearth}}<br />
|<br />
|<br />
| Some paths can be changed with the {{ic|KMLPath}} and {{ic|CachePath}} options in {{ic|~/.config/Google/GoogleEarthPlus.conf}}<br />
|-<br />
| {{Pkg|gopass}}<br />
| {{ic|~/.password-store}}<br />
|<br />
|<br />
| Override settings in {{ic|~/.config/gopass/config.yml}}:<br />
{{hc|~/.config/gopass/config.yml|<br />
root:<br />
path: gpgcli-gitcli-fs+file:///home/<userid>/.config/password-store<br />
}}<br />
|-<br />
| {{Pkg|gpodder}}<br />
| {{ic|~/gPodder}}<br />
|<br />
|<br />
| {{ic|1=GPODDER_DOWNLOAD_DIR}} sets the download folder. {{ic|1=GPODDER_HOME}} - where config and database files are stored, downloads also if {{ic|1=GPODDER_DOWNLOAD_DIR}} is not set.<br />
|-<br />
| [https://sourceforge.net/projects/gqclient GQ LDAP client]<br />
| {{ic|~/.gq}}, {{ic|~/.gq-state}}<br />
| [https://sourceforge.net/p/gqclient/mailman/message/2053978 1.51]<br />
|<br />
| {{ic|1=export GQRC="$XDG_CONFIG_HOME"/gqrc}}, {{ic|1=export GQSTATE="$XDG_DATA_HOME"/gq/gq-state}}, {{ic|mkdir -p "$(dirname "$GQSTATE")"}}<br />
|-<br />
| [[Gradle]]<br />
| {{ic|~/.gradle}}<br />
|<br />
| [https://discuss.gradle.org/t/be-a-nice-freedesktop-citizen-move-the-gradle-to-the-appropriate-location-in-linux/2199]<br />
| {{ic|1=export GRADLE_USER_HOME="$XDG_DATA_HOME"/gradle}}<br />
|-<br />
| [[GTK]] 1<br />
| {{ic|~/.gtkrc}}<br />
|<br />
|<br />
| {{ic|1=export GTK_RC_FILES="$XDG_CONFIG_HOME"/gtk-1.0/gtkrc}}<br />
|-<br />
| [[GTK]] 2<br />
| {{ic|~/.gtkrc-2.0}}<br />
|<br />
|<br />
| {{ic|1=export GTK2_RC_FILES="$XDG_CONFIG_HOME"/gtk-2.0/gtkrc}}<br />
|-<br />
| {{Pkg|hledger}}<br />
| {{ic|~/.hledger.journal}}<br />
|<br />
| [https://github.com/simonmichael/hledger/issues/1081]<br />
| {{ic|1=export LEDGER_FILE="$XDG_DATA_HOME"/hledger.journal}}<br />
|-<br />
| [https://www.sidefx.com/products/houdini/ Houdini]<br />
| {{ic|~/houdini''MAJOR''.''MINOR'')}}<br />
|<br />
| [https://forums.odforce.net/topic/43138-changing-home-location/]<br />
[https://www.sidefx.com/docs/houdini/ref/env.html]<br />
| {{ic|1=export HOUDINI_USER_PREF_DIR="$XDG_CACHE_HOME"/houdini__HVER__}}<br />
The value of this variable must include the substring {{ic|__HVER__}}, which will be replaced at run time with the current {{ic|''MAJOR''.''MINOR''}} version string.<br />
|-<br />
| {{AUR|imapfilter}}<br />
| {{ic|~/.imapfilter}}<br />
|<br />
|<br />
| {{ic|1=export IMAPFILTER_HOME="$XDG_CONFIG_HOME/imapfilter"}}<br />
|-<br />
| [[IPFS]]<br />
| {{ic|~/.ipfs}}<br />
|<br />
|<br />
| {{ic|1=export IPFS_PATH="$XDG_DATA_HOME"/ipfs}}<br />
|-<br />
| [https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html irb]<br />
| {{ic|~/.irbrc}}<br />
|<br />
|<br />
| {{hc|1=~/.profile|2=$ export IRBRC="$XDG_CONFIG_HOME"/irb/irbrc}}<br />
{{hc|1="$XDG_CONFIG_HOME"/irb/irbrc|2=IRB.conf[:SAVE_HISTORY] {{!}}{{!}}= 1000<br />
IRB.conf[:HISTORY_FILE] {{!}}{{!}}= File.join(ENV["XDG_DATA_HOME"], "irb", "history")}}<br />
|-<br />
| [[irssi]]<br />
| {{ic|~/.irssi}}<br />
|<br />
| [https://github.com/irssi/irssi/pull/511]<br />
| {{ic|1=irssi --config="$XDG_CONFIG_HOME"/irssi/config --home="$XDG_DATA_HOME"/irssi}}<br />
|-<br />
| [[isync]]<br />
| {{ic|~/.mbsyncrc}}<br />
|<br />
| [https://sourceforge.net/p/isync/feature-requests/14/]<br />
| {{ic|1=mbsync -c "$XDG_CONFIG_HOME"/isync/mbsyncrc}}<br />
|-<br />
| [[Java#OpenJDK]]<br />
| {{ic|~/.java/.userPrefs}}<br />
|<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=1154277]<br />
| {{ic|1=export _JAVA_OPTIONS=-Djava.util.prefs.userRoot="$XDG_CONFIG_HOME"/java}}<br />
|-<br />
| [[jupyter]]<br />
| {{ic|~/.jupyter}}<br />
| [https://github.com/jupyter/jupyter_core/releases/tag/5.0.0rc0 5.0.0rc0]<br />
| [https://github.com/jupyter/jupyter_core/issues/185] [https://github.com/jupyter/jupyter_core/pull/292]<br />
| {{Pkg|python-jupyter_core}} < v5.0.0:<br />
<br />
{{ic|1=export JUPYTER_CONFIG_DIR="$XDG_CONFIG_HOME"/jupyter}}<br />
<br />
v5.0.0 <= {{Pkg|python-jupyter_core}} < v6.0.0:<br />
<br />
{{ic|1=export JUPYTER_PLATFORM_DIRS="1"}} (see [https://github.com/jupyter/jupyter_core/blob/3efd00e5804424198285c63ebc6dc6c085d8c857/jupyter_core/paths.py#L176-L181])<br />
<br />
{{Pkg|python-jupyter_core}} >= v6.0.0: full support (via {{Pkg|python-platformdirs}}) enabled by default<br />
|-<br />
| {{Pkg|k9s}}<br />
| {{ic|~/.k9s}}<br />
| [https://github.com/derailed/k9s/releases/tag/v0.20.4 0.20.4]<br />
| [https://github.com/derailed/k9s/issues/743]<br />
| {{ic|1=export K9SCONFIG="$XDG_CONFIG_HOME"/k9s}}<br />
|-<br />
| [[KDE]]<br />
| {{ic|~/.kde}}, {{ic|~/.kde4}}<br />
|<br />
| [https://userbase.kde.org/KDE_System_Administration/KDE_Filesystem_Hierarchy#KDEHOME]<br />
| {{ic|1=export KDEHOME="$XDG_CONFIG_HOME"/kde}}<br />
|-<br />
| {{Pkg|keychain}}<br />
| {{ic|~/.keychain}}<br />
| [https://github.com/funtoo/keychain/commit/d43099bcff315d24a2ca31ae83da85e115d22ef6]<br />
| [https://github.com/funtoo/keychain/issues/8]<br />
| {{ic|1=keychain --absolute --dir "$XDG_RUNTIME_DIR"/keychain}}<br />
|-<br />
| {{Pkg|kodi}}<br />
| {{ic|~/.kodi}}<br />
| [https://github.com/xbmc/xbmc/pull/14460]<br />
| [https://github.com/xbmc/xbmc/pull/6142]<br />
| {{ic|1=KODI_DATA=$XDG_DATA_HOME/kodi}}<br />
|-<br />
| {{AUR|kscript}}<br />
| {{ic|~/.kscript}}<br />
|<br />
| [https://github.com/holgerbrandl/kscript/issues/323]<br />
| {{ic|1=export KSCRIPT_CACHE_DIR="$XDG_CACHE_HOME"/kscript}}<br />
|-<br />
| [[ledger]]<br />
| {{ic|~/.ledgerrc}}, {{ic|~/.pricedb}}<br />
|<br />
| [https://github.com/ledger/ledger/issues/1820]<br />
| {{ic|1=ledger --init-file "$XDG_CONFIG_HOME"/ledgerrc}}<br />
|-<br />
| [[Leiningen]]<br />
| {{ic|~/.lein}}, {{ic|~/.m2}}<br />
|<br />
|<br />
| {{ic|1=export LEIN_HOME="$XDG_DATA_HOME"/lein}}<br />
<br />
to change the m2 repo location used by leiningen look here: [[Leiningen#m2_repo_location]]<br />
|-<br />
| {{Pkg|libdvdcss}}<br />
| {{ic|~/.dvdcss}}<br />
|<br />
| [https://mailman.videolan.org/pipermail/libdvdcss-devel/2014-August/001022.html]<br />
| {{ic|1=export DVDCSS_CACHE="$XDG_DATA_HOME"/dvdcss}}<br />
|-<br />
| {{Pkg|libice}}<br />
| {{ic|~/.ICEauthority}}<br />
|<br />
| [https://gitlab.freedesktop.org/xorg/lib/libice/issues/2]<br />
| {{ic|1=export ICEAUTHORITY="$XDG_CACHE_HOME"/ICEauthority}}<br />
Make sure {{ic|XDG_CACHE_HOME}} is set beforehand to directory user running [[Xorg]] has write access to.<br />
<br />
'''Do not''' use {{ic|XDG_RUNTIME_DIR}} as it is available '''after''' login. Display managers that launch [[Xorg]] (like [[GDM]]) will repeatedly fail otherwise.<br />
|-<br />
| [[Xorg|libx11]]<br />
| {{ic|~/.XCompose}}, {{ic|~/.compose-cache}}<br />
|<br />
|<br />
| {{ic|1=export XCOMPOSEFILE="$XDG_CONFIG_HOME"/X11/xcompose}}, {{ic|1=export XCOMPOSECACHE="$XDG_CACHE_HOME"/X11/xcompose}}<br />
|-<br />
| {{Pkg|ltrace}}<br />
| {{ic|~/.ltrace.conf}}<br />
|<br />
|<br />
| {{ic|1=ltrace -F "$XDG_CONFIG_HOME"/ltrace/ltrace.conf}}<br />
|-<br />
| {{Pkg|lynx}}<br />
| {{ic|/etc/lynx.cfg}}<br />
|<br />
|<br />
| {{ic|1=export LYNX_CFG_PATH="$XDG_CONFIG_HOME"/lynx.cfg}}<br />
|-<br />
| [https://git.savannah.nongnu.org/cgit/m17n/m17n-db.git m17n-db]<br />
| {{ic|~/.m17n.d}}<br />
|<br />
| [https://savannah.nongnu.org/bugs/?63056]<br />
| <br />
|-<br />
| {{AUR|maptool-bin}}<br />
| {{ic|~/.maptool-rptools}}<br />
|<br />
| [https://github.com/RPTools/maptool/issues/2786]<br />
| {{hc|1=/opt/maptool/lib/app/MapTool.cfg|2=[JavaOptions]<br />
-DMAPTOOL_DATADIR=.local/share/maptool-rptools}}<br />
However, no way to change the location of this configuration file.<br />
|-<br />
| {{Pkg|maven}}<br />
| {{ic|~/.m2}}<br />
|<br />
| [https://issues.apache.org/jira/browse/MNG-6603]<br />
| {{ic|1=mvn -gs "$XDG_CONFIG_HOME"/maven/settings.xml}} and set {{ic|<localRepository>}} as appropriate in [https://maven.apache.org/settings.html#Simple_Values settings.xml]<br />
|-<br />
| [[Mathematica]]<br />
| {{ic|~/.Mathematica}}<br />
|<br />
|<br />
| {{ic|1=export MATHEMATICA_USERBASE="$XDG_CONFIG_HOME"/mathematica}}<br />
|-<br />
| {{Pkg|maxima}}<br />
| {{ic|~/.maxima}}<br />
|<br />
|<br />
| {{ic|1=export MAXIMA_USERDIR="$XDG_CONFIG_HOME"/maxima}}<br />
|-<br />
| {{Pkg|mednafen}}<br />
| {{ic|~/.mednafen}}<br />
|<br />
|<br />
| {{ic|1=export MEDNAFEN_HOME="$XDG_CONFIG_HOME"/mednafen}}<br />
|-<br />
| {{Pkg|minikube}}<br />
| {{ic|~/.minikube}}<br />
|<br />
| [https://github.com/kubernetes/minikube/issues/4109]<br />
| {{ic|1=export MINIKUBE_HOME="$XDG_DATA_HOME"/minikube}}<br />
<br />
Creates a further {{ic|.minikube}} directory in {{ic|MINIKUBE_HOME}} for whatever reason.<br />
|-<br />
| {{Pkg|mitmproxy}}<br />
| {{ic|~/.mitmproxy}}<br />
|<br />
|<br />
| {{ic|1=alias mitmproxy="mitmproxy --set confdir=$XDG_CONFIG_HOME/mitmproxy"}}, {{ic|1=alias mitmweb="mitmweb --set confdir=$XDG_CONFIG_HOME/mitmproxy"}}<br />
|-<br />
| [[MOC]]<br />
| {{ic|~/.moc}}<br />
|<br />
|<br />
| {{ic|1=mocp -M "$XDG_CONFIG_HOME"/moc}}, {{ic|1=mocp -O MOCDir="$XDG_CONFIG_HOME"/moc}}<br />
|-<br />
| {{Pkg|monero}}<br />
| {{ic|~/.bitmonero}}<br />
|<br />
|<br />
| {{ic|1=monerod --data-dir "$XDG_DATA_HOME"/bitmonero}}<br />
|-<br />
| {{Pkg|most}}<br />
| {{ic|~/.mostrc}}<br />
|<br />
|<br />
| {{ic|1=export MOST_INITFILE="$XDG_CONFIG_HOME"/mostrc}}<br />
|-<br />
| [[MPlayer]]<br />
| {{ic|~/.mplayer}}<br />
|<br />
|<br />
| {{ic|1=export MPLAYER_HOME="$XDG_CONFIG_HOME"/mplayer}}<br />
|-<br />
| {{Pkg|mypy}}<br />
| {{ic|~/.mypy_cache}}<br />
|<br />
| [https://github.com/python/mypy/issues/8790]<br />
| {{ic|1=export MYPY_CACHE_DIR="$XDG_CACHE_HOME"/mypy}}<br />
|-<br />
| [[MySQL]]<br />
| {{ic|~/.mysql_history}}, {{ic|~/.my.cnf }}, {{ic|~/.mylogin.cnf}}<br />
|<br />
|<br />
| {{ic|1=export MYSQL_HISTFILE="$XDG_DATA_HOME"/mysql_history}}<br />
<br />
{{ic|~/.my.cnf}} only supported for mysql-server, not mysql-client [https://dev.mysql.com/doc/refman/8.0/en/option-files.html]<br />
<br />
{{ic|~/.mylogin.cnf}} unsupported<br />
|-<br />
| {{Pkg|mysql-workbench}}<br />
| {{ic|~/.mysql/workbench}}<br />
|<br />
|<br />
| You can run MySQL Workbench with the {{ic|1=---configdir}} flag, such as {{ic|1=mysql-workbench --configdir="$XDG_DATA_HOME/mysql/workbench"}}. The directory needs to be created manually, since MySQL Workbench default location is {{ic|1=$HOME/.mysql/workbench}} .<br />
|-<br />
|-<br />
| {{Pkg|ncurses}}<br />
| {{ic|~/.terminfo}}<br />
|<br />
|<br />
| Precludes system path searching:<br />
<br />
{{ic|1=export TERMINFO="$XDG_DATA_HOME"/terminfo}}, {{ic|1=export TERMINFO_DIRS="$XDG_DATA_HOME"/terminfo:/usr/share/terminfo}}<br />
|-<br />
| [https://github.com/tj/n n]<br />
| {{ic|/usr/local/n}}<br />
|<br />
|<br />
| {{ic|1=export N_PREFIX=$XDG_DATA_HOME/n<br />
}}<br />
|-<br />
| {{Pkg|ncmpc}}<br />
| {{ic|~/.ncmpc}}<br />
|<br />
|<br />
| {{ic|ncmpc -f "$XDG_CONFIG_HOME"/ncmpc/config}}<br />
|-<br />
| [[Netbeans]]<br />
| {{ic|~/.netbeans}}<br />
|<br />
| [https://bz.apache.org/netbeans/show_bug.cgi?id=215961]<br />
| {{ic|1=netbeans --userdir "${XDG_CONFIG_HOME}"/netbeans}}<br />
|-<br />
| [[Node.js]]<br />
| {{ic|~/.node_repl_history}}<br />
|<br />
| [https://nodejs.org/api/repl.html#repl_environment_variable_options]<br />
| {{ic|1=export NODE_REPL_HISTORY="$XDG_DATA_HOME"/node_repl_history}}<br />
|-<br />
| {{Pkg|npm}}<br />
| {{ic|~/.npm}}, {{ic|~/.npmrc}}<br />
|<br />
| [https://github.com/npm/cli/issues/654]<br />
| {{ic|1=export NPM_CONFIG_USERCONFIG=$XDG_CONFIG_HOME/npm/npmrc}}<br />
{{hc|npmrc|<nowiki><br />
prefix=${XDG_DATA_HOME}/npm<br />
cache=${XDG_CACHE_HOME}/npm<br />
init-module=${XDG_CONFIG_HOME}/npm/config/npm-init.js<br />
</nowiki>}}<br />
{{ic|prefix}} is unnecessary (and unsupported) if Node.js is installed by {{AUR|nvm}}.<br />
<br />
If you want to configure this system-wide, the file to edit is {{ic|/usr/etc/npmrc}}, not {{ic|/etc/npmrc}}. You can confirm that the config is loaded by running {{ic|npm config list}}<br />
|-<br />
| {{Pkg|opam}}<br />
| {{ic|~/.opam}}<br />
|<br />
| [https://github.com/ocaml/opam/issues/3766]<br />
| {{ic|1=export OPAMROOT="$XDG_DATA_HOME/opam"}}<br />
Both configuration and state data are stored in {{ic|OPAMROOT}}, so this solution is not fully compliant.<br />
|-PKG_CONFIG_PATH<br />
| {{Aur|pnpm}}<br />
| {{ic|~/.pnpm-store}}<br />
|<br />
|<br />
| Add the line {{ic|1=store-dir=${XDG_DATA_HOME}/pnpm-store}} to your {{ic|npmrc}}.<br />
|-<br />
| [[PuTTY]]<br />
| {{ic|~/.putty/}}<br />
| [https://git.tartarus.org/?p=simon/putty.git;a=commit;h=9952b2d5bd5c8fbac4f5731a805bce10fe4ce47c 9952b2d]<br />
|<br />
| Will use {{ic|$XDG_CONFIG_HOME/putty}} if it already exists. Creates {{ic|~/.putty}} if not. Prioritises {{ic|$XDG_CONFIG_HOME/putty}} if both exist. Tested in 0.74<br />
|-<br />
| {{Pkg|nuget}}<br />
| {{ic|~/.nuget/packages}}<br />
|<br />
| [https://docs.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders]<br />
| {{ic|1=export NUGET_PACKAGES="$XDG_CACHE_HOME"/NuGetPackages}}<br />
|-<br />
| [[NVIDIA]]<br />
| {{ic|~/.nv}}<br />
|<br />
|<br />
| Uses {{ic|XDG_CACHE_HOME}} if set, otherwise improperly falls back to {{ic|~/.nv}} instead of {{ic|~/.cache}}.<br />
|-<br />
| {{Pkg|nvidia-settings}}<br />
| {{ic|~/.nvidia-settings-rc}}<br />
|<br />
|<br />
| {{ic|1=nvidia-settings --config="$XDG_CONFIG_HOME"/nvidia/settings}}<br />
|-<br />
| {{AUR|nvm}}<br />
| {{ic|~/.nvm}}<br />
|<br />
|<br />
| {{ic|1=export NVM_DIR="$XDG_DATA_HOME"/nvm}}<br />
|-<br />
| [[Octave]]<br />
| {{ic|~/octave}}, {{ic|~/.octave_packages}}, {{ic|~/.octave_hist}}<br />
|<br />
|<br />
| {{ic|1=export OCTAVE_HISTFILE="$XDG_CACHE_HOME/octave-hsts"}}, {{ic|1=export OCTAVE_SITE_INITFILE="$XDG_CONFIG_HOME/octave/octaverc"}}<br />
<br />
{{hc|$XDG_CONFIG_HOME/octave/octaverc|<nowiki><br />
source /usr/share/octave/site/m/startup/octaverc;<br />
pkg prefix ~/.local/share/octave/packages ~/.local/share/octave/packages;<br />
pkg local_list /home/<your username>/.local/share/octave/octave_packages;<br />
</nowiki>}}<br />
The {{ic|local_list}} option must be given an absolute path.<br />
|-<br />
| {{Pkg|openscad}}<br />
| {{ic|~/.OpenSCAD}}<br />
| [https://github.com/openscad/openscad/commit/7c3077b0f 7c3077b0f]<br />
| [https://github.com/openscad/openscad/issues/125]<br />
| Does not fully honour XDG Base Directory Specification, see [https://github.com/openscad/openscad/issues/373]<br />
<br />
Currently it [https://github.com/openscad/openscad/blob/master/src/PlatformUtils-posix.cc#L20 hard-codes]{{Dead link|2022|09|23|status=404}} {{ic|~/.local/share}}.<br />
|-<br />
| [[OpenSSL]]<br />
| {{ic|~/.rnd}}<br />
|<br />
|<br />
| Seeding file {{ic|.rnd}}'s location can be set with {{ic|RANDFILE}} environment variable per [https://www.openssl.org/docs/faq.html FAQ].<br />
|-<br />
| {{Pkg|parallel}}<br />
| {{ic|~/.parallel}}<br />
| [https://git.savannah.gnu.org/cgit/parallel.git/commit/?id=685018f532f4e2d24b84eb28d5de3d759f0d1af1 20170422]<br />
|<br />
| {{ic|1=export PARALLEL_HOME="$XDG_CONFIG_HOME"/parallel}}<br />
|-<br />
| [[pass]]<br />
| {{ic|~/.password-store}}<br />
|<br />
|<br />
| {{ic|1=export PASSWORD_STORE_DIR="$XDG_DATA_HOME"/pass}}<br />
|-<br />
| [[Pidgin]]<br />
| {{ic|~/.purple}}<br />
|<br />
| [https://developer.pidgin.im/ticket/4911]<br />
| {{ic|1=pidgin --config="$XDG_DATA_HOME"/purple}}<br />
|-<br />
| [[PostgreSQL]]<br />
| {{ic|~/.psqlrc}}, {{ic|~/.psql_history}}, {{ic|~/.pgpass}}, {{ic|~/.pg_service.conf}}<br />
| 9.2<br />
| [https://www.postgresql.org/docs/current/static/app-psql.html] [https://www.postgresql.org/docs/current/static/libpq-envars.html]<br />
| {{ic|1=export PSQLRC="$XDG_CONFIG_HOME/pg/psqlrc"}}, {{ic|1=export PSQL_HISTORY="$XDG_STATE_HOME/psql_history"}}, {{ic|1=export PGPASSFILE="$XDG_CONFIG_HOME/pg/pgpass"}}, {{ic|1=export PGSERVICEFILE="$XDG_CONFIG_HOME/pg/pg_service.conf"}}<br />
<br />
It is required to create both directories: {{ic|1=mkdir "$XDG_CONFIG_HOME/pg" && mkdir "$XDG_STATE_HOME"}}<br />
|-<br />
| [[PulseAudio]]<br />
| {{ic|~/.esd_auth}}<br />
|<br />
|<br />
| Very likely generated by the {{ic|module-esound-protocol-unix.so}} module. It can be configured to use a different location but it makes much more sense to just comment out this module in {{ic|/etc/pulse/default.pa}} or {{ic|"$XDG_CONFIG_HOME"/pulse/default.pa}}.<br />
|-<br />
| {{Pkg|pyenv}}<br />
| {{ic|~/.pyenv}}<br />
|<br />
| [https://github.com/pyenv/pyenv/issues/139] [https://github.com/pyenv/pyenv/issues/1789]<br />
| {{ic|1=export PYENV_ROOT=$XDG_DATA_HOME/pyenv}}<br />
|-<br />
| {{aur|python-azure-cli}}<br />
| {{ic|~/.azure}}<br />
|<br />
|<br />
| {{ic|1=export AZURE_CONFIG_DIR=$XDG_DATA_HOME/azure}}<br />
|-<br />
| {{AUR|python-grip}}<br />
| {{ic|~/.grip}}<br />
|<br />
|<br />
| {{ic|1=export GRIPHOME="$XDG_CONFIG_HOME/grip"}}<br />
|-<br />
| {{Pkg|python-setuptools}}<br />
| {{ic|~/.python-eggs}}<br />
|<br />
|<br />
| {{ic|1=export PYTHON_EGG_CACHE="$XDG_CACHE_HOME"/python-eggs}}<br />
|-<br />
| {{Pkg|racket}}<br />
| {{ic|~/.racketrc}}, {{ic|~/.racket}}<br />
|<br />
| [https://github.com/racket/racket/issues/2740]<br />
| {{ic|1=export PLTUSERHOME="$XDG_DATA_HOME"/racket}}<br />
|-<br />
| {{AUR|rbenv}}<br />
| {{ic|~/.rbenv}}<br />
|<br />
| [https://github.com/rbenv/rbenv/issues/811] [https://github.com/rbenv/rbenv/issues/1146]<br />
| {{ic|1=export RBENV_ROOT="$XDG_DATA_HOME"/rbenv}}<br />
|-<br />
| {{AUR|nodenv}}<br />
| {{ic|~/.nodenv}}<br />
|<br />
|<br />
| {{ic|1=export NODENV_ROOT="$XDG_DATA_HOME"/nodenv}}<br />
|-<br />
| [[readline]]<br />
| {{ic|~/.inputrc}}<br />
|<br />
|<br />
| {{ic|1=export INPUTRC="$XDG_CONFIG_HOME"/readline/inputrc}}<br />
|-<br />
| {{Pkg|recoll}}<br />
| {{ic|~/.recoll}}<br />
|<br />
|<br />
| {{ic|1=export RECOLL_CONFDIR="$XDG_CONFIG_HOME/recoll"}}<br />
|-<br />
| [[redis]]<br />
| {{ic|~/.rediscli_history}}, {{ic|~/.redisclirc}}<br />
|<br />
|<br />
|{{ic|1=export REDISCLI_HISTFILE="$XDG_DATA_HOME"/redis/rediscli_history}}, {{ic|1=export REDISCLI_RCFILE="$XDG_CONFIG_HOME"/redis/redisclirc}}<br />
|-<br />
| {{Pkg|ripgrep}}<br />
|<br />
|<br />
| [https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md#configuration-file]<br />
|{{ic|1=export RIPGREP_CONFIG_PATH=$XDG_CONFIG_HOME/ripgrep/config}}<br />
|-<br />
| {{Pkg|rlwrap}}<br />
| {{ic|~/.*_history}}<br />
|<br />
| [https://github.com/hanslub42/rlwrap/issues/25]<br />
| {{ic|1=export RLWRAP_HOME="$XDG_DATA_HOME"/rlwrap}}<br />
|-<br />
| {{Aur|ruby-solargraph}}<br />
| {{ic|~/.solargraph/cache/}}<br />
|<br />
| [https://github.com/castwide/solargraph/blob/master/README.md]<br />
| {{ic|1=export SOLARGRAPH_CACHE=$XDG_CACHE_HOME/solargraph}}<br />
|-<br />
| [[Rust#Rustup]]<br />
| {{ic|~/.rustup}}<br />
|<br />
| [https://github.com/rust-lang-nursery/rustup.rs/issues/247]<br />
| {{ic|1=export RUSTUP_HOME="$XDG_DATA_HOME"/rustup}}<br />
|-<br />
| {{Pkg|sbt}}<br />
| {{ic|~/.sbt}}<br />
{{ic|~/.ivy2}}<br />
|<br />
| [https://github.com/sbt/sbt/issues/3681]<br />
| {{ic|1=sbt -ivy "$XDG_DATA_HOME"/ivy2 -sbt-dir "$XDG_DATA_HOME"/sbt}} (beware [https://github.com/sbt/sbt/issues/3598])<br />
|-<br />
| [[SageMath]]<br />
| {{ic|~/.sage}}<br />
|<br />
|<br />
| {{ic|1=export DOT_SAGE="$XDG_CONFIG_HOME"/sage}}<br />
|-<br />
| [[GNU Screen]]<br />
| {{ic|~/.screenrc}}<br />
|<br />
|<br />
| {{ic|1=export SCREENRC="$XDG_CONFIG_HOME"/screen/screenrc}}<br />
|-<br />
| {{Pkg|simplescreenrecorder}}<br />
| {{ic|~/.ssr/}}<br />
| [https://github.com/MaartenBaert/ssr/releases/tag/0.4.3 0.4.3]<br />
| [https://github.com/MaartenBaert/ssr/issues/407]<br />
[https://github.com/MaartenBaert/ssr/issues/813]<br />
| Will use {{ic|$XDG_CONFIG_HOME/simplescreenrecorder/}} ONLY if it already was created otherwise defaults to {{ic|~/.ssr}}<br />
<br />
{{ic|1=mv ~/.ssr "$XDG_CONFIG_HOME"/simplescreenrecorder}}<br />
|-<br />
| [https://www.spacemacs.org/ spacemacs]<br />
| {{ic|~/.spacemacs}}, {{ic|~/.spacemacs.d}}<br />
| [https://github.com/syl20bnr/spacemacs/commit/e1eed07c30ea395fb9cfebc8ec3376dcffbace11]<br />
| [https://github.com/syl20bnr/spacemacs/issues/3589]<br />
| Move the {{ic|~/.spacemacs}} file.<br />
<br />
{{ic|1=export SPACEMACSDIR="$XDG_CONFIG_HOME"/spacemacs}}, {{ic|mv ~/.spacemacs "$SPACEMACSDIR"/init.el}}<br />
<br />
Other files need to be configured like Emacs.<br />
|-<br />
| [[Haskell#Stack]]<br />
| {{ic|~/.stack}}<br />
|<br />
| [https://github.com/commercialhaskell/stack/issues/342]<br />
| {{ic|1=export STACK_ROOT="$XDG_DATA_HOME"/stack}}<br />
|-<br />
| {{Pkg|starship}}<br />
| {{ic|~/.config/starship}}, {{ic|~/.cache/starship}}<br />
| [https://github.com/starship/starship/pull/86] ([https://github.com/starship/starship/releases/tag/v0.2.0 v0.2.0]), [https://github.com/starship/starship/pull/1576] ([https://github.com/starship/starship/releases/tag/v0.45.0 v0.45.0])<br />
| [https://github.com/starship/starship/issues/896#issuecomment-952402978]<br />
| {{ic|1=export STARSHIP_CONFIG="$XDG_CONFIG_HOME"/starship.toml}}, {{ic|1=export STARSHIP_CACHE="$XDG_CACHE_HOME"/starship}}<br />
|-<br />
| [[subversion]]<br />
| {{ic|~/.subversion}}<br />
|<br />
| [https://issues.apache.org/jira/browse/SVN-4599] [https://mail-archives.apache.org/mod_mbox/subversion-users/201204.mbox/%3c4F8FBCC6.4080205@ritsuka.org%3e][https://mail-archives.apache.org/mod_mbox/subversion-dev/201509.mbox/%3C20150917222954.GA20331@teapot%3E]<br />
| {{ic|1=alias svn="svn --config-dir \"$XDG_CONFIG_HOME\"/subversion"}}<br />
|-<br />
| {{Pkg|sudo}}<br />
| {{ic|~/.sudo_as_admin_successful}}<br />
| [https://www.sudo.ws/stable.html#1.9.6 1.9.6]<br />
| [https://github.com/sudo-project/sudo/issues/56] [https://www.sudo.ws/repos/sudo/rev/d77c3876fa95]<br />
| Only present when activated at compile-time (default none). An admin_flag parameter can be used in /etc/sudoers since 1.9.6.<br />
|-<br />
| {{Pkg|task}}<br />
| {{ic|~/.task}}, {{ic|~/.taskrc}}<br />
|<br />
|<br />
| {{ic|1=export TASKDATA="$XDG_DATA_HOME"/task}}, {{ic|1=export TASKRC="$XDG_CONFIG_HOME"/task/taskrc}}}}, {{ic|[https://github.com/GothenburgBitFactory/taskwarrior/pull/2316 Fully supported in version 2.6] (note $XDG_CONFIG_HOME/task/taskrc ''must'' exist, otherwise taskwarrior will offer to create sample config in legacy $HOME/.taskrc location, even if $XDG_CONFIG_HOME is set [https://github.com/GothenburgBitFactory/taskwarrior/pull/2316#issuecomment-732821437][https://github.com/GothenburgBitFactory/taskwarrior/blob/112ac54a57adfb3cc2e6e60dbbb1f5c7d9db3e18/doc/man/task.1.in#L1451])<br />
|-<br />
| Local [[TeX Live]] TeXmf tree, TeXmf caches and config<br />
| {{ic|~/texmf}}, {{ic|~/.texlive/texmf-var}}, {{ic|~/.texlive/texmf-config}}<br />
|<br />
|<br />
| {{ic|1=export TEXMFHOME=$XDG_DATA_HOME/texmf}}, {{ic|1=export TEXMFVAR=$XDG_CACHE_HOME/texlive/texmf-var}}, {{ic|1=export TEXMFCONFIG=$XDG_CONFIG_HOME/texlive/texmf-config}}<br />
|-<br />
| [https://www.texmacs.org/ TeXmacs]<br />
| {{ic|~/.TeXmacs}}<br />
|<br />
|<br />
| {{ic|1=export TEXMACS_HOME_PATH=$XDG_STATE_HOME/texmacs}}<br />
|-<br />
| {{AUR|tiptop}}<br />
| {{ic|~/.tiptoprc}}<br />
|<br />
|<br />
| This will still expect the {{ic|.tiptoprc}} file.<br />
{{ic|tiptop -W "$XDG_CONFIG_HOME"/tiptop}}<br />
|-<br />
| {{AUR|ruby-travis}}<br />
| {{ic|~/.travis/}}<br />
|<br />
| [https://github.com/travis-ci/travis.rb/issues/219]<br />
| {{ic|1=export TRAVIS_CONFIG_PATH=$XDG_CONFIG_HOME/travis}}<br />
|-<br />
| {{Pkg|uncrustify}}<br />
| {{ic|~/.uncrustify.cfg}}<br />
|<br />
|<br />
| {{ic|1=export UNCRUSTIFY_CONFIG="$XDG_CONFIG_HOME"/uncrustify/uncrustify.cfg}}<br />
|-<br />
| [[Unison]]<br />
| {{ic|~/.unison}}<br />
|<br />
|<br />
| {{ic|1=export UNISON="$XDG_DATA_HOME"/unison}}<br />
|-<br />
| {{Pkg|units}}<br />
| {{ic|~/.units_history}}<br />
|<br />
|<br />
| {{ic|1=units --history "$XDG_CACHE_HOME"/units_history}}<br />
|-<br />
| [[rxvt-unicode/Tips and tricks#Daemon-client|urxvtd]]<br />
| {{ic|~/.urxvt/urxvtd-hostname}}<br />
|<br />
|<br />
| {{ic|1=export RXVT_SOCKET="$XDG_RUNTIME_DIR"/urxvtd}}<br />
|-<br />
| [[Vagrant]]<br />
| {{ic|~/.vagrant.d}}, {{ic|~/.vagrant.d/aliases}}<br />
|<br />
| [https://www.vagrantup.com/docs/other/environmental-variables.html]<br />
| {{ic|1=export VAGRANT_HOME="$XDG_DATA_HOME"/vagrant}}, {{ic|1=export VAGRANT_ALIAS_FILE="$XDG_DATA_HOME"/vagrant/aliases}}<br />
|-<br />
| [[virtualenv]]<br />
| {{ic|~/.virtualenvs}}<br />
|<br />
|<br />
| {{ic|1=export WORKON_HOME="$XDG_DATA_HOME/virtualenvs"}}<br />
|-<br />
| [[Visual Studio Code]]<br />
| {{ic|~/.vscode-oss/}}<br />
|<br />
| [https://github.com/Microsoft/vscode/issues/3884]<br />
| You can use {{ic|1=export VSCODE_PORTABLE="$XDG_DATA_HOME"/vscode}}, which is not documented and might break unexpectedly.<br />
Setting this makes the editor look for the contents of {{ic|1=.config/Code - OSS}} in {{ic|1=$VSCODE_PORTABLE/user-data}}.<br />
<br />
You can also run Visual Studio with the {{ic|1=--extensions-dir}} flag, such as {{ic|1=code --extensions-dir "$XDG_DATA_HOME/vscode"}}. This is documented and probably will not break as unexpectedly, as it is {{ic|[https://github.com/microsoft/vscode/issues/329 has other use cases]}}.<br />
|-<br />
| {{AUR|VSCodium}}<br />
| {{ic|~/.vscode-oss/}}<br />
|<br />
| [https://github.com/VSCodium/vscodium/issues/561] [https://github.com/VSCodium/vscodium/issues/671]<br />
| You can run VSCodium with the {{ic|1=--extensions-dir}} flag, such as {{ic|1=vscodium --extensions-dir "$XDG_DATA_HOME/vscode"}}. This however won't prevent the creation of {{ic|1=~/.vscode-oss/}} directory.<br />
|-<br />
| {{Pkg|wakatime}}<br />
| {{ic|~/.wakatime.cfg}}, {{ic|~/.wakatime.data}}, {{ic|~/.wakatime.db}}, {{ic|~/.wakatime.log}}<br />
|<br />
|<br />
| {{ic|1=export WAKATIME_HOME="$XDG_CONFIG_HOME/wakatime"}}<br />
<br />
The directory needs to be created manually<br />
<br />
{{ic|1=mkdir "$XDG_CONFIG_HOME/wakatime"}}<br />
<br />
|-<br />
| [[wget]]<br />
| {{ic|~/.wgetrc}}, {{ic|~/.wget-hsts}}<br />
|<br />
|<br />
| {{ic|1=export WGETRC="$XDG_CONFIG_HOME/wgetrc"}} and add the following as an alias for wget: {{ic|1=wget --hsts-file="$XDG_CACHE_HOME/wget-hsts"}}, or set the {{ic|1=hsts-file}} variable with an absolute path as wgetrc does not support environment variables: {{ic|1=echo hsts-file \= "$XDG_CACHE_HOME"/wget-hsts >> "$XDG_CONFIG_HOME/wgetrc"}}<br />
|-<br />
| [[wine]]<br />
| {{ic|~/.wine}}<br />
|<br />
| [https://bugs.winehq.org/show_bug.cgi?id=20888]<br />
| [[Wine#Winetricks|Winetricks]] uses XDG-alike location below for [[Wine#WINEPREFIX|WINEPREFIX]] management:<br />
{{ic|1=mkdir -p "$XDG_DATA_HOME"/wineprefixes}}, {{ic|1=export WINEPREFIX="$XDG_DATA_HOME"/wineprefixes/default}}<br />
|-<br />
| [[xbindkeys]]<br />
| {{ic|~/.xbindkeysrc}}<br />
|<br />
|<br />
| {{ic|1=xbindkeys -f "$XDG_CONFIG_HOME"/xbindkeys/config}}<br />
|-<br />
| {{Pkg|xorg-xauth}}<br />
| {{ic|~/.Xauthority}}<br />
|<br />
|<br />
| {{ic|1=export XAUTHORITY="$XDG_RUNTIME_DIR"/Xauthority}}<br />
<br />
Note that [[LightDM]] does not allow you to change this variable. If you change it nonetheless, you will not be able to login. Use [[startx]] instead or [https://askubuntu.com/a/961459 configure LightDM]. According to [https://unix.stackexchange.com/a/175331] [[SLiM]] has {{ic|~/.Xauthority}} hardcoded.<br />
<br />
The [[SDDM]] Xauthority path can be changed in its own configuration files as shown below. Unfortunately, it is relative to the home directory.<br />
{{hc|1=/etc/sddm.conf.d/xauth-path.conf|2=[X11]<br />
UserAuthFile=.Xauthority}}<br />
|-<br />
| [[xinit]]<br />
| {{ic|~/.xinitrc}}, {{ic|~/.xserverrc}}<br />
|<br />
| [https://gitlab.freedesktop.org/xorg/app/xinit/issues/14]<br />
| {{ic|1=export XINITRC="$XDG_CONFIG_HOME"/X11/xinitrc}}, {{ic|1=export XSERVERRC="$XDG_CONFIG_HOME"/X11/xserverrc}}<br />
|-<br />
| {{Pkg|xorg-xrdb}}<br />
| {{ic|~/.Xresources}}, {{ic|~/.Xdefaults}}<br />
|<br />
|<br />
| Ultimately you [https://superuser.com/questions/243914/xresources-or-xdefaults should be] using {{ic|Xresources}} and since these resources are loaded via {{ic|xrdb}} you can specify a path such as {{ic|1=xrdb -load ~/.config/X11/xresources}}.<br />
|-<br />
| [[Xorg]]<br />
| {{ic|~/.xsession}}, {{ic|~/.xsessionrc}}, {{ic|~/.Xsession}}, {{ic|~/.xsession-errors}}<br />
|<br />
|<br />
| These can be added as part of your Xorg init script ({{ic|~/.xinitrc}}) or Xsession start script (which will often be based on {{ic|/etc/X11/Xsession}}).<br />
Depending on where you have configured your {{ic|$XDG_CACHE_HOME}}, you made need to expand the paths yourself.<br />
{{hc|# xsession start script|<nowiki><br />
USERXSESSION="$XDG_CACHE_HOME/X11/xsession"<br />
USERXSESSIONRC="$XDG_CACHE_HOME/X11/xsessionrc"<br />
ALTUSERXSESSION="$XDG_CACHE_HOME/X11/Xsession"<br />
ERRFILE="$XDG_CACHE_HOME/X11/xsession-errors"<br />
</nowiki>}}<br />
Unlike most other examples in this table, actual X11 init scripts will vary a lot between installations.<br />
|-<br />
| {{Pkg|z}}<br />
| {{ic|~/.z}}<br />
|<br />
| [https://github.com/rupa/z/issues/267]<br />
| {{ic|1=export _Z_DATA="$XDG_DATA_HOME/z"}}<br />
|-<br />
| {{Pkg|yarn}}<br />
| {{ic|~/.yarnrc}}, {{ic|~/.yarn/}}, {{ic|~/.yarncache/}}, {{ic|~/.yarn-config/}}<br />
| [https://github.com/yarnpkg/yarn/commit/2d454b5 2d454b5]<br />
| [https://github.com/yarnpkg/yarn/pull/5336] [https://github.com/yarnpkg/yarn/issues/2334]<br />
| {{ic|1=alias yarn='yarn --use-yarnrc "$XDG_CONFIG_HOME/yarn/config"'}}<br />
|-<br />
|}<br />
<br />
=== Hardcoded ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Discussion<br />
! Notes<br />
|-<br />
| [[adb]] & [https://developer.android.com/studio/index.html Android Studio]<br />
| {{ic|~/.android/}}<br />
|<br />
| Despite [https://android.googlesource.com/platform/system/core/+/d5fcafaf41f8ec90986c813f75ec78402096af2d%5E%21/ appearances otherwise], adb will ''always'' generate {{ic|~/.android/adbkeys}}, though it will try keys in {{ic|ADB_VENDOR_KEYS}} as well.<br />
|-<br />
| {{Pkg|aegisub}}<br />
| {{ic|~/.aegisub/}}<br />
| [https://github.com/Aegisub/Aegisub/issues/226]<br />
|<br />
|-<br />
| [[alpine]]<br />
| {{ic|~/.pinerc}}, {{ic|~/.addressbook}}, {{ic|~/.pine-debug[1-4]}}, {{ic|~/.newsrc}}, {{ic|~/.mailcap}}, {{ic|~/.mime.types}}, {{ic|~/.pine-interrupted-mail}}<br />
| <br />
| {{ic|1=alias alpine="alpine -p $XDG_CONFIG_HOME/alpine/pinerc"}}<br />
In the above config file, some locations can be customized using options like {{ic|1=newsrc-path=}} and {{ic|1=address-book=}}.<br />
|-<br />
| [[Ansible]]<br />
| {{ic|~/.ansible}}<br />
| [https://github.com/ansible/ansible/issues/52354] [https://github.com/ansible/ansible/issues/68587] [https://github.com/ansible/ansible/issues/75788]<br />
|<br />
|-<br />
| [[aMule]]<br />
| {{ic|~/.aMule}}<br />
| [https://bugs.amule.org/view.php?id=1308] [http://forum.amule.org/index.php?topic=18056] [https://github.com/amule-project/amule/issues/254]<br />
|<br />
|-<br />
| [https://osdn.net/projects/anthy/ anthy]<br />
| {{ic|~/.anthy}}<br />
| [https://osdn.net/ticket/browse.php?group_id=14&tid=28397]<br />
|<br />
|-<br />
| [https://directory.apache.org/studio/ Apache Directory Studio]<br />
| {{ic|~/.ApacheDirectoryStudio}}<br />
|<br />
|<br />
|-<br />
| [https://christian.amsuess.com/tools/arandr/ ARandR]<br />
| {{ic|~/.screenlayout}}<br />
| [https://gitlab.com/arandr/arandr/-/issues/45]<br />
|<br />
|-<br />
| [[Arduino]]<br />
| {{ic|~/.arduino15}}, {{ic|~/.jssc}}<br />
| [https://github.com/arduino/Arduino/issues/3915 won't fix]<br />
|<br />
|-<br />
| {{Pkg|arduino-cli}}<br />
| {{ic|~.arduino15/}}<br />
| [https://github.com/arduino/arduino-cli/pull/140]<br />
| {{ic|1=mv ~/.arduino15 $XDG_CONFIG_HOME/arduino15}}<br />
Specify the new directories used by Arduino CLI in arduino-cli.yaml as mentioned in the documentation [https://arduino.github.io/arduino-cli/latest/configuration/ here].<br />
{{ic|1=alias arduino-cli='arduino-cli --config-file $XDG_CONFIG_HOME/arduino15/arduino-cli.yaml'}}<br />
|-<br />
| [http://fixounet.free.fr/avidemux/ Avidemux]<br />
| {{ic|~/.avidemux6}}<br />
| [https://avidemux.org/smif/index.php/topic,19596.0.html]<br />
|<br />
|-<br />
| [[Bash]]<br />
| {{ic|~/.bashrc}}, {{ic|~/.bash_history}}, {{ic|~/.bash_profile}}, {{ic|~/.bash_login}}, {{ic|~/.bash_logout}}<br />
| [https://savannah.gnu.org/support/?108134 won't fix]<br />
| {{ic|1=mkdir -p "$XDG_STATE_HOME"/bash}}<br />
{{ic|1=export HISTFILE="$XDG_STATE_HOME"/bash/history}}<br />
<br />
{{ic|bashrc}} can be sourced from a different location in {{ic|/etc/bash.bashrc}}.<br />
Specify {{ic|--init-file <file>}} as an alternative to {{ic|~/.bashrc}} for interactive shells.<br />
|-<br />
| [[Chef|Berkshelf]]<br />
| {{ic|~/.berkshelf/}}<br />
|<br />
|<br />
|-<br />
| {{AUR|chatty}}<br />
| {{ic|~/.chatty/}}<br />
| [https://github.com/chatty/chatty/issues/273]<br />
|<br />
|-<br />
| {{Pkg|cmake}}<br />
| {{ic|~/.cmake/}}<br />
| [https://gitlab.kitware.com/cmake/cmake/-/issues/22480]<br />
| Used for the user package registry {{ic|~/.cmake/packages/<package>}}, detailed in {{man|7|cmake-packages|User Package Registry}} and [https://gitlab.kitware.com/cmake/community/wikis/doc/tutorials/Package-Registry the Package registry wiki page]. Looks like it's hardcoded, for example in [https://gitlab.kitware.com/cmake/cmake/blob/v3.12.1/Source/cmFindPackageCommand.cxx#L1221 cmFindPackageCommand.cxx].<br />
|-<br />
| [[Cinnamon]]<br />
| {{ic|~/.cinnamon/}}<br />
| [https://github.com/linuxmint/Cinnamon/issues/7807]<br />
|<br />
|-<br />
| {{AUR|conan}}<br />
| {{ic|~/.conan/}}<br />
| [https://github.com/conan-io/conan/issues/2526]<br />
| {{ic|1=export CONAN_USER_HOME="$XDG_CONFIG_HOME"}} will set the directory in which {{ic|.conan/}} is created. It was [https://docs.conan.io/en/latest/reference/env_vars.html#conan-user-home designed to simplify CI], but can be used here too.<br />
|-<br />
| {{AUR|cryptomator}}<br />
| {{ic|~/.Cryptomator}}<br />
| [https://github.com/cryptomator/cryptomator/issues/710]<br />
|<br />
|-<br />
| {{Pkg|ctags}} (universial-ctags)<br />
| {{ic|~/.ctagsrc, .ctags.d}}<br />
| [https://github.com/universal-ctags/ctags/issues/89]<br />
|<br />
|-<br />
| [[CUPS]]<br />
| {{ic|~/.cups/}}<br />
| [https://github.com/OpenPrinting/cups/issues/10]<br />
|<br />
|-<br />
| [https://chrome.google.com/webstore/detail/cvim/ihlenndgcmojhcghmfjfneahoeklbjjh cVim]{{Dead link|2022|09|23|status=404}}<br />
| {{ic|~/.cvimrc}}<br />
| [https://github.com/1995eaton/chromium-vim/issues/750]<br />
|<br />
|-<br />
| [[darcs]]<br />
| {{ic|~/.darcs/}}<br />
| [http://bugs.darcs.net/issue2453]<br />
|<br />
|-<br />
| {{Pkg|dart}}<br />
| {{ic|~/.dart}}, {{ic|~/.dartServer}}<br />
| [https://github.com/dart-lang/sdk/issues/41560]<br />
|<br />
|-<br />
| [[dbus]]<br />
| {{ic|~/.dbus/}}<br />
| [https://gitlab.freedesktop.org/dbus/dbus/issues/46]<br />
| Consider using {{pkg|dbus-broker}}, as it does not create or use this directory.<br />
|-<br />
| {{Pkg|devede}}<br />
| {{ic|~/.devedeng}}<br />
|<br />
| Hardcoded [https://gitlab.com/rastersoft/devedeng/blob/f0893b3ff7b14723bd148db35bdfe2d284156d19/src/devedeng/configuration_data.py#L111 here]<br />
|-<br />
| [https://wiki.gnome.org/Apps/Dia Dia]<br />
| {{ic|~/.dia/}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|dotnet-sdk}}<br />
| {{ic|~/.dotnet/}}<br />
| [https://github.com/dotnet/cli/issues/7569]<br />
|<br />
|-<br />
| [[dropbox]]<br />
| {{ic|~/.dropbox/}}<br />
|<br />
|<br />
|-<br />
| [[Eclipse]]<br />
| {{ic|~/.eclipse/}}<br />
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=200809]<br />
| Option {{ic|1=-Dosgi.configuration.area=@user.home/.config/..}} overrides but must be added to {{ic|"$ECLIPSE_HOME"/eclipse.ini"}} rather than command line which means you must have write access to {{ic|$ECLIPSE_HOME}}. (Arch Linux hard-codes {{ic|$ECLIPSE_HOME}} in {{ic|/usr/bin/eclipse}})<br />
|-<br />
| [https://www.fetchmail.info/ Fetchmail]<br />
| {{ic|~/.fetchmailrc}}<br />
|<br />
|<br />
|-<br />
| [[Firefox]]<br />
| {{ic|~/.mozilla/}}<br />
| [https://bugzil.la/259356] [https://phabricator.services.mozilla.com/D6995]<br />
|<br />
|-<br />
| [[Flatpak]]<br />
| {{ic|~/.var/}}<br />
| [https://github.com/flatpak/flatpak/issues/46] [https://github.com/flatpak/flatpak.github.io/issues/191] [https://github.com/flatpak/flatpak/issues/1651 won't fix]<br />
|<br />
|-<br />
| [https://github.com/rwestlund/freesweep freesweep]<br />
| {{ic|~/.sweeprc}}<br />
| [https://github.com/rwestlund/freesweep/issues/9]<br />
|<br />
|-<br />
| {{Pkg|gftp}}<br />
| {{ic|~/.gftp/}}<br />
| [https://github.com/masneyb/gftp/issues/99#issuecomment-735030824]<br />
| Following the XDG spec is planned for gftp.<br />
|-<br />
| {{Pkg|ghidra}}<br />
|<br />
| [https://github.com/NationalSecurityAgency/ghidra/issues/908]<br />
|<br />
|-<br />
|-<br />
| {{AUR|gitkraken}}<br />
| {{ic|~/.gitkraken/}}<br />
| [https://feedback.gitkraken.com/suggestions/197923/support-for-moving-the-config-directory-on-linux]<br />
|<br />
|-<br />
| [[GoldenDict]]<br />
| {{ic|~/.goldendict/}}<br />
| [https://github.com/goldendict/goldendict/issues/151]<br />
|<br />
|-<br />
| {{Pkg|gphoto2}}<br />
| {{ic|~/.gphoto}}<br />
| [https://github.com/gphoto/gphoto2/issues/249]<br />
|<br />
|-<br />
| {{Pkg|gramps}}<br />
| {{ic|~/.gramps/}}<br />
| [https://gramps-project.org/bugs/view.php?id=8025]<br />
| 2022 Support XDG base directory specification (for next release Gramps 5.2 ) - Patch https://github.com/gramps-project/gramps/pull/1368<br />
|-<br />
| {{Pkg|groovy}}<br />
| {{ic|~/.groovy/}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|grsync}}<br />
| {{ic|~/.grsync/}}<br />
| [https://sourceforge.net/p/grsync/feature-requests/15/]<br />
|<br />
|-<br />
| {{AUR|google-cloud-sdk}}<br />
| {{ic|~/.gsutil/}}<br />
| [https://github.com/GoogleCloudPlatform/gsutil/issues/991]<br />
|<br />
|-<br />
| [http://recordmydesktop.sourceforge.net/about.php gtk-recordMyDesktop]<br />
| {{ic|~/.gtk-recordmydesktop}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|hplip}}<br />
| {{ic|~/.hplip/}}<br />
| [https://bugs.launchpad.net/hplip/+bug/307152]<br />
|<br />
|-<br />
| {{Pkg|hydrogen}}<br />
| {{ic|~/.hydrogen/}}<br />
| [https://github.com/hydrogen-music/hydrogen/issues/643]<br />
|<br />
|-<br />
| [https://www.idris-lang.org/ idris]<br />
| {{ic|~/.idris}}<br />
| [https://github.com/idris-lang/Idris-dev/pull/3456]<br />
|<br />
|-<br />
| {{AUR|itch-setup-bin}}<br />
| {{ic|~/.itch}}<br />
| [https://github.com/itchio/itch/issues/2356 won't fix]<br />
| You can move the Game install location in the app settings.<br />
|-<br />
| [https://sourceforge.net/projects/jmol/ Jmol]<br />
| {{ic|~/.jmol/}}<br />
| [https://sourceforge.net/p/jmol/feature-requests/261/]<br />
|<br />
|-<br />
| {{Aur|lbdb}}<br />
| {{ic|~/.lbdbrc, ~/.lbdb/}}<br />
| [https://github.com/RolandRosenfeld/lbdb/blob/eb162aa9da36f699cf821c6487210c7979fcd8ee/TODO#L18]<br />
|<br />
|-<br />
| [[llpp]]<br />
| {{ic|~/.config/llpp.conf}}<br />
| [https://github.com/moosotc/llpp/issues/180]{{Dead link|2022|09|23|status=404}}<br />
| Added in [https://repo.or.cz/w/llpp.git/commit/3ab86f0 3ab86f0] but subsequently reverted in [https://github.com/moosotc/llpp/commit/e253c9f1 e253c9f1]{{Dead link|2022|09|23|status=404}}<br />
|-<br />
| [[Java]] OpenJDK<br />
| {{ic|~/.java/fonts}}<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=1154277]<br />
| {{ic|1=export _JAVA_OPTIONS=-Djava.util.prefs.userRoot="$XDG_CONFIG_HOME"/java}}<br />
|-<br />
| [[Java]] OpenJFX<br />
| {{ic|~/.java/webview}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|jgmenu}}<br />
| {{ic|~/.jgmenu-lockfile}}<br />
| [https://github.com/johanmalm/jgmenu/blob/3e48121dc28d06efb23c7901b7e138c2de167a84/src/lockfile.c#L11] [https://github.com/johanmalm/jgmenu/blob/4e45d04502fc5f77392bef0ff33b7bada0cf07d1/src/jgmenu_run#L7]<br />
|<br />
|-<br />
| [https://julialang.org/ julia]<br />
| {{ic|~/.juliarc.jl}}, {{ic|~/.julia_history}}, {{ic|~/.julia}}<br />
| [https://github.com/JuliaLang/julia/issues/4630] [https://github.com/JuliaLang/julia/issues/10016]<br />
| The trailing {{ic|:$JULIA_DEPOT_PATH}} is necessary. See [https://docs.julialang.org/en/v1/manual/environment-variables/#JULIA_DEPOT_PATH]<br />
{{ic|1=export JULIA_DEPOT_PATH="$XDG_DATA_HOME/julia:$JULIA_DEPOT_PATH"}}<br />
|-<br />
| {{AUR|kite}}<br />
| {{ic|~/.kite/}}<br />
| [https://github.com/kiteco/issue-tracker/issues/242]<br />
|<br />
|-<br />
| {{Pkg|kotlin}}<br />
| {{ic|~/.kotlinc_history}}<br />
|<br />
| Related Konan issue: [https://youtrack.jetbrains.com/issue/KT-40763]<br />
|-<br />
| [[Kubernetes]]<br />
| {{ic|~/.kube/}}<br />
| [https://github.com/kubernetes/kubectl/issues/942][https://github.com/kubernetes/kubernetes/issues/56402]<br />
|<br />
|-<br />
| {{AUR|librewolf}}<br />
| {{ic|~/.mozilla}}<br />
{{ic|~/.librewolf}}<br />
| [https://gitlab.com/librewolf-community/browser/linux/-/issues/129]<br />
|<br />
|-<br />
| [https://lldb.llvm.org/ lldb]<br />
| {{ic|~/.lldb}}, {{ic|~/.lldbinit}}<br />
|<br />
|<br />
|-<br />
| [[LMMS]]<br />
| {{ic|~/.lmmsrc.xml}}<br />
| [https://github.com/LMMS/lmms/issues/5869]<br />
|<br />
|-<br />
| [http://www.mathomatic.org/ mathomatic]<br />
| {{ic|~/.mathomaticrc}}, {{ic|~/.matho_history}}<br />
|<br />
| History can be moved by using {{ic|rlwrap mathomatic -r}} with the {{ic|RLWRAP_HOME}} environment set appropriately.<br />
|-<br />
| [[Minecraft]]<br />
| {{ic|~/.minecraft/}}<br />
| [https://bugs.mojang.com/browse/MCL-2563 won't fix]<br />
|<br />
|-<br />
| [[Minetest]]<br />
| {{ic|~/.minetest/}}<br />
| [https://github.com/minetest/minetest/issues/864 won't fix] [https://github.com/minetest/minetest/issues/8151]<br />
|<br />
|-<br />
| {{Pkg|minicom}}<br />
| {{ic|~/.minirc.dfl}}<br />
|<br />
| Upstream has a TODO entry for supporting configuration files under {{ic|~/.config/minicom}}. [https://salsa.debian.org/minicom-team/minicom/-/blob/fe9ff103/TODO#L27]<br />
|-<br />
|-<br />
| [[Mono]]<br />
| {{ic|~/.mono/}}<br />
| [https://github.com/mono/mono/pull/12764]<br />
|<br />
|-<br />
| [https://www.mongodb.org/ mongodb]<br />
| {{ic|~/.mongorc.js}}, {{ic|~/.dbshell}}<br />
| [https://jira.mongodb.org/browse/DOCS-5652?jql=text%20~%20%22.mongorc.js%22]<br />
| [https://stackoverflow.com/questions/22348604/the-mongorc-js-is-not-found-but-there-is-one/22349050#22349050 This Stack Overflow thread] suggests a partial workaround using command-line switch {{ic|--norc}}.<br />
|-<br />
|<br />
| {{ic|~/.netrc}}<br />
|<br />
| Like {{ic|~/.ssh}}, many programs expect this file to be here. These include projects like curl ({{ic|CURLOPT_NETRC_FILE}}), [[ftp]] ({{ic|NETRC}}), [[s-nail]] ({{ic|NETRC}}), etc. While some of them offer alternative configurable locations, many do not such as w3m, wget and lftp.<br />
|-<br />
| [[NetworkManager|nmcli]]<br />
| {{ic|~/.nmcli-history}}<br />
| [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/64]<br />
| Hardcoded to {{ic|g_get_home_dir()}}[https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-get-home-dir] [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/blob/main/src/nmcli/connections.c#L6598]<br />
|-<br />
| [[Networkmanager-openvpn]]<br />
| {{ic|~/.cert/nm-openvpn}}<br />
| [https://gitlab.gnome.org/GNOME/NetworkManager-openvpn/issues/35]<br />
|<br />
|-<br />
| {{Aur|ocaml-utop}}<br />
| {{ic|~/.utop-history}}<br />
| [https://github.com/ocaml-community/utop/issues/361]<br />
| There's an open PR to move {{ic|~/.utop-hostory}} to {{ic|$XDG_CACHE_HOME}} [https://github.com/ocaml-community/utop/pull/362]<br />
|-<br />
| [[OpenSSH]]<br />
| {{ic|~/.ssh}}<br />
| [https://bugzilla.mindrot.org/show_bug.cgi?id=2050 won't fix]<br />
| Assumed to be present by many ssh daemons and clients such as DropBear and OpenSSH.<br />
|-<br />
| [https://www.palemoon.org/ palemoon]<br />
| {{ic|~/.moonchild productions}}<br />
| [https://forum.palemoon.org/viewtopic.php?f=5&t=9639]<br />
|<br />
|-<br />
| {{AUR|parsec-bin}}<br />
| {{ic|~/.parsec}}<br />
|<br />
|<br />
|-<br />
| {{AUR|pcsxr}}<br />
| {{ic|~/.pcsxr}}<br />
|<br />
| A {{ic|-cfg}} flag exists, but can only be set relative to {{ic|~/.pcsxr}}.<br />
|-<br />
| [https://perf.wiki.kernel.org/index.php/Main_Page perf]<br />
| {{ic|~/.debug}}<br />
|<br />
| Hardcoded in [https://github.com/torvalds/linux/blob/7d42e98182586f57f376406d033f05fe135edb75/tools/perf/util/config.c#L35 tools/perf/util/config.c]. Commit: [https://github.com/torvalds/linux/commit/45de34bbe3e1b8f4c8bc8ecaf6c915b4b4c545f8]<br />
|-<br />
| [[perl]]<br />
| {{ic|~/.cpan}}, {{ic|~/perl5}}<br />
| [https://github.com/andk/cpanpm/issues/149]<br />
| Perl5's [https://github.com/andk/cpanpm CPAN] expects {{ic|~/.cpan}}<br />
|-<br />
| {{AUR|portfolio-performance-bin}}<br />
| {{ic|~/.PortfolioPerformance/}}<br />
| [https://github.com/buchen/portfolio/issues/1922]<br />
| <br />
|-<br />
| various [[shell]]s and [[display manager]]s<br />
| {{ic|~/.profile}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|psensor}}<br />
| {{ic|~/.psensor}}<br />
| [https://gitlab.com/jeanfi/psensor/-/issues/38]<br />
|<br />
|-<br />
| [[python]]<br />
| {{ic|~/.python_history}}<br />
| [https://bugs.python.org/issue29779] [https://bugs.python.org/issue20886] [https://github.com/python/cpython/pull/13208]<br />
| All history from interactive sessions is saved to {{ic|~/.python_history}} by default since [https://bugs.python.org/issue5845 version 3.4]. This can still be customized the same way as in older versions (see [https://docs.python.org/3/library/readline.html?highlight=readline#example this example]), including to [https://bugs.python.org/msg318437 use a custom path] or [https://bugs.python.org/msg265568 disable history saving].<br />
<br />
[https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPYCACHEPREFIX PYTHONPYCACHEPREFIX]: {{ic|1=export $XDG_CACHE_HOME/python}}<br />
[https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUSERBASE PYTHONUSERBASE]: {{ic|1=export $XDG_DATA_HOME/python}}<br />
|-<br />
| {{Pkg|python-tensorflow}}<br />
| {{ic|~/.keras}}<br />
| [https://github.com/tensorflow/tensorflow/issues/38831]<br />
| The issues is for {{ic|tf.keras}} module<br />
|-<br />
| {{Pkg|qmmp}}<br />
| {{ic|~/.qmmp}}<br />
| [https://sourceforge.net/p/qmmp-dev/tickets/776]<br />
|<br />
|-<br />
| [https://doc.qt.io/qt-5/qtdesigner-manual.html Qt Designer]<br />
| {{ic|~/.designer}}<br />
| [https://bugreports.qt.io/browse/QTCREATORBUG-26093]<br />
|<br />
|-<br />
| [http://rednotebook.sourceforge.net/ RedNotebook]<br />
| {{ic|~/.rednotebook}}<br />
| [https://github.com/jendrikseipp/rednotebook/issues/404]<br />
|<br />
|-<br />
| [https://remarkableapp.github.io/linux.html Remarkable]<br />
| {{ic|~/.remarkable}}<br />
|<br />
|<br />
|-<br />
| {{AUR|renderdoc}}<br />
| {{ic|~/.renderdoc}}<br />
| [https://github.com/baldurk/renderdoc/pull/1741 won't fix]<br />
|<br />
|-<br />
| [https://www.renpy.org/ Ren'Py]<br />
| {{ic|~/.renpy}}<br />
| [https://github.com/renpy/renpy/issues/1377#issuecomment-370118555 won't fix]<br />
|<br />
|-<br />
| [https://gerrit.googlesource.com/git-repo/ repo]<br />
| {{ic|~/.repoconfig}}<br />
| [https://bugs.chromium.org/p/gerrit/issues/detail?id=13997]<br />
|<br />
|-<br />
| [[rpm]]<br />
| {{ic|~/.rpmrc}} {{ic|~/.rpmmacros}}<br />
| [https://github.com/rpm-software-management/rpm/issues/2153 Backlog]<br />
| Workaround is to use --rcfile and --macros however this come with sideeffects.<br />
|<br />
|-<br />
| [[SANE]]<br />
| {{ic|~/.sane/}}<br />
|<br />
| {{ic|scanimage}} creates a {{ic|.cal}} file there<br />
|-<br />
| {{Pkg|sbcl}}<br />
| {{ic|~/.sbclrc}}<br />
|<br />
| {{hc|/etc/sbclrc|<br />
(require :asdf)<br />
(setf sb-ext:*userinit-pathname-function*<br />
(lambda () (uiop:xdg-config-home #P"sbcl/sbclrc")))<br />
}}<br />
<br />
Note that this requires root privileges and will change the location of {{ic|~/.sbclrc}} for all users. This can be mitigated by checking for an existing {{ic|~/.sbclrc}} inside the {{ic|lambda}} form.<br />
|-<br />
| [https://www.seamonkey-project.org/ SeaMonkey]<br />
| {{ic|~/.mozilla/seamonkey}}<br />
| [https://bugzil.la/726939]<br />
|<br />
|-<br />
| [https://signal.org/ Signal Desktop]<br />
| <br />
| [https://github.com/signalapp/Signal-Desktop/issues/4975]<br />
| Currently keeps messages in {{ic|~/.config/Signal}}<br />
|-<br />
| [[Snap]]<br />
| {{ic|~/snap/}}<br />
| [https://bugs.launchpad.net/ubuntu/+source/snapd/+bug/1575053]<br />
|<br />
|-<br />
| [https://www.gnu.org/software/solfege/solfege.html Solfege]<br />
| {{ic|~/.solfege}}, {{ic|~/.solfegerc}}, {{ic|~/lessonfiles}}<br />
| [https://savannah.gnu.org/bugs/index.php?50251]<br />
|<br />
|-<br />
| [https://spamassassin.apache.org/ SpamAssassin]<br />
| {{ic|~/.spamassassin}}<br />
|<br />
|<br />
|-<br />
| [[SQLite]]<br />
| {{ic|~/.sqlite_history}}, {{ic|~/.sqliterc}}<br />
| [https://www.sqlite.org/src/info/696e82f7c82d1720]<br />
| {{ic|1=export SQLITE_HISTORY=$XDG_DATA_HOME/sqlite_history}}, {{ic|sqlite3 -init "$XDG_CONFIG_HOME"/sqlite3/sqliterc}}<br />
|-<br />
| [[Steam]]<br />
| {{ic|~/.steam}}, {{ic|~/.steampath}}, {{ic|~/.steampid}}<br />
| [https://github.com/ValveSoftware/steam-for-linux/issues/1890]<br />
| Many game engines (Unity 3D, Unreal) follow the specification, but then individual game publishers hardcode the paths in [https://www.ctrl.blog/entry/flatpak-steamcloud-xdg Steam Auto-Cloud] causing game-saves to sync to the wrong directory.<br />
|-<br />
| {{AUR|python-streamlit}}<br />
| {{ic|~/.streamlit}}<br />
| [https://github.com/streamlit/streamlit/issues/2068]<br />
| <br />
|-<br />
| [[TeamSpeak]]<br />
| {{ic|~/.ts3client}}<br />
|<br />
| {{ic|1=export TS3_CONFIG_DIR="$XDG_CONFIG_HOME/ts3client"}}<br />
|-<br />
| {{Pkg|terraform}}<br />
| {{ic|~/.terraform.d/}}<br />
| [https://github.com/hashicorp/terraform/issues/15389]<br />
|<br />
|-<br />
| {{pkg|texinfo}}<br />
| {{ic|~/.infokey}}<br />
|<br />
| {{ic|info --init-file "$XDG_CONFIG_HOME/infokey"}}<br />
|-<br />
| [[Thunderbird]]<br />
| {{ic|~/.thunderbird/}}<br />
| [https://bugzil.la/735285]<br />
|<br />
|-<br />
| [[TigerVNC]]<br />
| {{ic|~/.vnc}}<br />
| [https://github.com/TigerVNC/tigervnc/issues/1195]<br />
|<br />
|-<br />
| [https://gitlab.archlinux.org/remy/texlive-localmanager tllocalmgr]<br />
| {{ic|~/.texlive}}<br />
|<br />
|<br />
|-<br />
| {{Aur|urlview}}<br />
| {{ic|~/.urlview}}<br />
|<br />
| Use fork {{Aur|urlview-xdg-git}} instead. The fork will use {{ic|XDG_CONFIG_HOME/urlview/config}}<br />
|-<br />
| {{AUR|vale}}<br />
| {{ic|~/.vale.ini}}<br />
| [https://github.com/errata-ai/vale/issues/152 won't fix]<br />
| {{ic|vale --config "$XDG_CONFIG_HOME/vale/config.ini"}}<br />
|-<br />
| [[vim]]<br />
| {{ic|~/.vim}}, {{ic|~/.vimrc}}, {{ic|~/.viminfo}}<br />
| [https://github.com/vim/vim/issues/2034]<br />
| Since [https://github.com/vim/vim/commit/6a459902592e2a4ba68 7.3.1178] vim will search for {{ic|~/.vim/vimrc}} if {{ic|~/.vimrc}} is not found.<br />
<br />
{{hc|"$XDG_CONFIG_HOME"/vim/vimrc|<nowiki><br />
set runtimepath^=$XDG_CONFIG_HOME/vim<br />
set runtimepath+=$XDG_DATA_HOME/vim<br />
set runtimepath+=$XDG_CONFIG_HOME/vim/after<br />
<br />
set packpath^=$XDG_DATA_HOME/vim,$XDG_CONFIG_HOME/vim<br />
set packpath+=$XDG_CONFIG_HOME/vim/after,$XDG_DATA_HOME/vim/after<br />
<br />
let g:netrw_home = $XDG_DATA_HOME."/vim"<br />
call mkdir($XDG_DATA_HOME."/vim/spell", 'p')<br />
<br />
set backupdir=$XDG_STATE_HOME/vim/backup | call mkdir(&backupdir, 'p')<br />
set directory=$XDG_STATE_HOME/vim/swap | call mkdir(&directory, 'p')<br />
set undodir=$XDG_STATE_HOME/vim/undo | call mkdir(&undodir, 'p')<br />
set viewdir=$XDG_STATE_HOME/vim/view | call mkdir(&viewdir, 'p')<br />
<br />
if !has('nvim') | set viminfofile=$XDG_STATE_HOME/vim/viminfo | endif<br />
</nowiki>}}<br />
<br />
{{hc|~/.profile|2=<br />
export GVIMINIT='let $MYGVIMRC="$XDG_CONFIG_HOME/vim/gvimrc" {{!}} source $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC="$XDG_CONFIG_HOME/vim/vimrc" {{!}} source $MYVIMRC'<br />
}}<br />
<br />
{{ic|[G]VIMINIT}} environment variable will also affect Neovim. If separate configs for Vim and Neovim are desired then the following will be a better choice:<br />
export GVIMINIT='let $MYGVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/gvimrc" : "$XDG_CONFIG_HOME/nvim/init.gvim" | so $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/vimrc" : "$XDG_CONFIG_HOME/nvim/init.vim" | so $MYVIMRC'<br />
<br />
* https://blog.joren.ga/vim-xdg<br />
* https://tlvince.com/vim-respect-xdg<br />
|-<br />
| [http://www.vimperator.org/ vimperator]<br />
| {{ic|~/.vimperatorrc}}<br />
| [https://web.archive.org/web/20200514081339/http://www.mozdev.org/pipermail/vimperator/2009-October/004848.html]<br />
| {{ic|1=export VIMPERATOR_INIT=":source $XDG_CONFIG_HOME/vimperator/vimperatorrc"}}<br />
<br />
{{ic|1=export VIMPERATOR_RUNTIME="$XDG_CONFIG_HOME"/vimperator}}<br />
|-<br />
| {{Pkg|visidata}}<br />
| {{ic|~/.visidata}}<br />
| [https://github.com/saulpw/visidata/issues/487]<br />
|<br />
|-<br />
| {{Pkg|w3m}}<br />
| {{ic|~/.w3m}}<br />
| [https://sourceforge.net/p/w3m/feature-requests/31/] [https://github.com/tats/w3m/issues/130]<br />
|<br />
|-<br />
| [https://w1.fi/ wpa_cli]<br />
| {{ic|~/.wpa_cli_history}}<br />
|<br />
|<br />
|-<br />
| {{Aur|wego}}<br />
| {{ic|~/.wegorc}}<br />
| [https://github.com/schachmat/wego/issues/116]<br />
|<br />
|-<br />
| {{AUR|x2goclient}}<br />
| {{ic|~/.x2goclient}}<br />
|<br />
| {{ic|1=alias x2goclient="x2goclient --home=$HOME/.config"}}<br />
|-<br />
| {{Pkg|xdg-utils}}<br />
| {{ic|~/.gnome}}<br />
| [https://bugs.freedesktop.org/show_bug.cgi?id=90775] [https://gitlab.freedesktop.org/xdg/xdg-utils/-/issues/81] [https://gitlab.freedesktop.org/xdg/xdg-utils/-/merge_requests/22]<br />
| For some reason the script {{ic|xdg-desktop-menu}} hard-codes {{ic|1=gnome_user_dir="$HOME/.gnome/apps"}}. This is used by [[chromium]] among others. Bug discussion has moved to gitlab and PR with fix exists, however it is not merged yet.<br />
|-<br />
| {{Pkg|xpdf}}<br />
| {{ic|~/.xpdfrc}}<br />
|<br />
|<br />
|-<br />
| {{AUR|xrdp}}<br />
| {{ic|~/thinclient_drives}}<br />
|<br />
| For the directory {{ic|~/thinclient_drives}}, you may consider editing {{ic|/etc/xrdp/sesman.ini}} and modifying the section {{ic|[Chansrv]}} following the example config.<br />
|-<br />
| [https://github.com/XVimProject/XVim2 XVim2]<br />
| {{ic|~/.xvimrc}}<br />
| [https://github.com/XVimProject/XVim2/issues/389]<br />
|<br />
|-<br />
| [https://yardoc.org YARD]<br />
| {{ic|~/.yard}}<br />
| [https://github.com/lsegal/yard/issues/1230]<br />
| Would accept Pull Request if anyone want to implement it.<br />
|-<br />
| [https://nmap.org/zenmap/ zenmap] {{Pkg|nmap}}<br />
| {{ic|~/.zenmap}}<br />
| [https://seclists.org/nmap-dev/2012/q2/163] [https://github.com/nmap/nmap/issues/590]<br />
|<br />
|-<br />
| {{AUR|zoom}}<br />
| {{ic|~/.zoom}}<br />
|<br />
| Unrecommended: setting the following variable moves the contents of .zoom but the directory itself always gets created. Moreover, it breaks some functionalities eg. being able to start a meeting. {{ic|1=export SSB_HOME="$XDG_DATA_HOME"/zoom}}<br />
|-<br />
| {{AUR|zotero-bin}}<br />
| {{ic|~/.zotero}} {{ic|~/Zotero}}<br />
| [https://github.com/zotero/zotero/issues/1203]<br />
|<br />
|-<br />
| [[zsh]]<br />
| {{ic|~/.zshrc}}, {{ic|~/.zprofile}}, {{ic|~/.zshenv}}, {{ic|~/.zlogin}}, {{ic|~/.zlogout}}, {{ic|~/.histfile}}, {{ic|~/.zcompdump}}, {{ic|~/.zcompcache}}<br />
| [https://www.zsh.org/mla/workers/2013/msg00692.html]<br />
| Consider exporting {{ic|1=ZDOTDIR=$HOME/.config/zsh}} in {{ic|~/.zshenv}} (this is hardcoded due to the bootstrap problem). You could also add this to {{ic|/etc/zsh/zshenv}} and avoid the need for any dotfiles in your {{ic|HOME}}. Doing this however requires root privilege which may not be viable and is system-wide.<br />
<br />
{{ic|1=export HISTFILE="$XDG_STATE_HOME"/zsh/history}}<br />
<br />
{{ic|compinit -d $XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION}} [https://unix.stackexchange.com/questions/391641/separate-path-for-zcompdump-files] /!\ The folder needs to exist<br />
<br />
{{ic|zstyle ':completion:*' cache-path $XDG_CACHE_HOME/zsh/zcompcache}}<br />
<br />
|}<br />
<br />
== Tools ==<br />
<br />
The tool {{aur|xdg-ninja}} detects unwanted files/directories in $HOME which can be moved to XDG base directories, for instance:<br />
<br />
{{hc|head=> xdg-ninja|output=<br />
[bash]: $HOME/.bashrc<br />
<br />
Currently unsupported.<br />
<br />
Relevant issue: https://savannah.gnu.org/support/?108134<br />
<br />
[bash]: $HOME/.bash_history<br />
<br />
Export the following environment variables:<br />
<br />
export HISTFILE="${XDG_STATE_HOME}"/bash/history<br />
<br />
[git]: $HOME/.gitconfig<br />
<br />
XDG is supported out-of-the-box, so we can simply move the file to XDG_CONFIG_HOME/git/config.<br />
<br />
}}<br />
<br />
== Libraries ==<br />
<br />
; C<br />
: [https://github.com/Jorengarenar/libXDGdirs libXDGdirs]<br />
: [https://github.com/devnev/libxdg-basedir libxdg-basedir]<br />
: [https://github.com/Cloudef/chck/tree/master/chck/xdg C99: Cloudef's simple implementation].<br />
<br />
; C++<br />
: [https://github.com/azubieta/xdg-utils-cxx xdg-utils-cxx]<br />
: [https://sr.ht/~danyspin97/xdgpp xdgpp]<br />
<br />
; Go<br />
: [https://github.com/adrg/xdg adrg/xdg]<br />
: [https://github.com/ProtonMail/go-appdir go-appdir] (deprecated, archived)<br />
: [https://github.com/shibukawa/configdir configdir] (deprecated, abandoned)<br />
: [https://github.com/kyoh86/xdg kyoh86/xdg] (deprecated, archived)<br />
<br />
; Haskell<br />
: Officially in [https://hackage.haskell.org/package/directory directory] since 1.2.3.0 [https://github.com/haskell/directory/commit/ab9d0810ce ab9d0810ce].<br />
: [https://hackage.haskell.org/package/xdg-basedir xdg-basedir]<br />
<br />
; JVM: Java, Kotlin, Clojure, Scala, ...<br />
: [https://github.com/soc/directories-jvm directories-jvm]<br />
<br />
; Perl<br />
: [https://search.cpan.org/dist/File-BaseDir/lib/File/BaseDir.pm File-BaseDir]<br />
<br />
; Python<br />
: [https://freedesktop.org/wiki/Software/pyxdg/ pyxdg]<br />
<br />
; Ruby<br />
: [https://github.com/bkuhlmann/xdg bkuhlmann/xdg]<br />
: [https://github.com/rubyworks/xdg rubyworks/xdg] (deprecated, abandoned)<br />
<br />
; Rust<br />
: [https://github.com/soc/directories-rs directories-rs]<br />
: [https://github.com/whitequark/rust-xdg rust-xdg]<br />
<br />
; Swift<br />
: [https://github.com/Frizlab/swift-xdg swift-xdg]<br />
<br />
; Vala<br />
: Builtin support via [https://valadoc.org/#!api=glib-2.0/GLib.Environment GLib.Environment].<br />
: See {{ic|get_user_cache_dir}}, {{ic|get_user_data_dir}}, {{ic|get_user_config_dir}}, etc.<br />
<br />
== See also ==<br />
<br />
* [https://wiki.gnome.org/Initiatives/GnomeGoals/XDGConfigFolders GNOME Goal: XDG Base Directory Specification Usage]<br />
* [https://web.archive.org/web/20180827160401/plus.google.com/+RobPikeTheHuman/posts/R58WgWwN9jp Rob Pike: "Dotfiles" being hidden is a UNIXv2 mistake].<br />
* {{man|1|systemd-path}}<br />
* {{man|7|file-hierarchy}}<br />
* [https://github.com/grawity/dotfiles/blob/master/.dotfiles.notes Grawity's notes on dotfiles].<br />
* [https://github.com/grawity/dotfiles/blob/master/.environ.notes Grawity's notes on environment variables].<br />
* [https://ploum.net/207-modify-your-application-to-use-xdg-folders/ ploum.net: Modify Your Application to use XDG Folders].<br />
* The [https://pcgamingwiki.com/wiki/Home PCGamingWiki] attempts to document whether or not Linux PC games follow the XDG Base Directory Specification.</div>Simon04https://wiki.archlinux.org/index.php?title=OpenConnect&diff=756555OpenConnect2022-11-11T06:39:08Z<p>Simon04: typesetting; +ocproxy/rdesktop</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:OpenConnect]]<br />
[[pt:OpenConnect]]<br />
[https://www.infradead.org/openconnect/ OpenConnect] is a client for Cisco's [https://www.cisco.com/go/asm AnyConnect SSL VPN]{{Dead link|2022|09|22|status=404}} and Pulse Secure's [[Pulse Connect Secure]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|openconnect}} package.<br />
<br />
== Usage ==<br />
<br />
See {{man|8|openconnect}}. Simply run ''openconnect'' as root and enter your username and password when prompted:<br />
<br />
# openconnect ''vpnserver''<br />
<br />
More advanced invocation with username and password. Input the password after running the command.<br />
<br />
# openconnect -u ''user'' --passwd-on-stdin ''vpnserver''<br />
<br />
Often VPN providers are offering different authentication groups for different access configurations like for example for a full tunnel or split tunnel connection. To show the different offered auth-groups and to get more information about the connection to the server in general use:<br />
<br />
# openconnect --authenticate ''vpnserver''<br />
<br />
Sometimes, connecting to a Cisco VPN, the CSD (Cisco Secure Desktop) mechanism is required (see: https://www.infradead.org/openconnect/csd.html). In that case using the "--csd-wrapper" parameter can help, the wrappers are stored under "/usr/lib/openconnect/".<br />
<br />
# openconnect --csd-wrapper=/usr/lib/openconnect/csd-post.sh ''vpnserver''<br />
<br />
=== Juniper Pulse Client ===<br />
<br />
In order to connect to a [[Pulse Connect Secure]] server you need to know the SHA-1 of its certificate.<br />
<br />
# openconnect --servercert=sha1:<HASH> --authgroup="single-Factor Pulse Clients" --protocol=nc <VPN_SERVER_ADDRESS>/dana-na/auth/url_6/welcome.cgi --pid-file="/var/run/work-vpn.pid" --user=<USERNAME><br />
<br />
=== GlobalProtect ===<br />
<br />
Connecting to a GlobalProtect VPN server where the address is usually https://vpn.your-domain.tld/, simply do<br />
<br />
# openconnect --protocol=gp <VPN_SERVER_ADDRESS><br />
<br />
Some VPN server requires you to use the alternative address<br />
<br />
# openconnect --protocol=gp <VPN_SERVER_ADDRESS>/gateway<br />
<br />
also your VPN might require you to generate a HIP report (gathers information about your computer), you can do that by passing in<br />
<br />
# openconnect --csd-wrapper /usr/lib/openconnect/hipreport.sh --protocol=gp <VPN_SERVER_ADDRESS>/gateway<br />
<br />
=== Split routing ===<br />
<br />
Split routing can be achieved using {{AUR|vpn-slice-git}} in place of ''vpnc-script'', so that you can selectively access hosts over the VPN but otherwise remain on your own LAN. Example:<br />
<br />
# openconnect gateway.bigcorp.com \<br />
-u user1234 \<br />
-s 'vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'<br />
<br />
$ cat /etc/hosts<br />
...<br />
# vpn-slice-tun0 AUTOCREATED<br />
192.168.1.1 dns0.tun0 <br />
192.168.1.2 dns1.tun0<br />
192.168.1.57 hostname1 hostname1.bigcorp.com<br />
192.168.1.43 alias2 alias2.bigcorp.com<br />
<br />
=== Proxy ===<br />
<br />
{{AUR|ocproxy-git}} may be used to setup a user-level SOCKS and port forwarding proxy for OpenConnect based on lwIP:<br />
<br />
* {{ic|-D port}} – Set up a SOCKS5 server on PORT<br />
* {{ic|-L lport:rhost:rport}} – Connections to localhost:LPORT will be redirected over the VPN to RHOST:RPORT<br />
<br />
Use-case to open RDP session in combination with [[rdesktop]]:<br />
<br />
$ openconnect --script-tun --script "ocproxy -L 3389:rds.example.com:3389" ''vpnserver''<br />
$ rdesktop localhost:3389<br />
<br />
== Integration ==<br />
<br />
=== NetworkManager ===<br />
<br />
[[Install]] the {{pkg|networkmanager-openconnect}} package, then [[restart]] {{ic|NetworkManager.service}}.<br />
<br />
Configure and connect with ''nm-applet'' (NetworkManager's icon tray utility from {{pkg|network-manager-applet}}) or similar utility.<br />
<br />
See [[NetworkManager]] for details.<br />
<br />
=== netctl ===<br />
<br />
A simple {{ic|tuntap}} {{man|5|netctl.profile}} can be used to integrate OpenConnect in the normal [[Netctl]] workflow. For example:<br />
<br />
{{hc|/etc/netctl/vpn|<nowiki><br />
Description='VPN'<br />
Interface=vpn<br />
Connection=tuntap<br />
Mode=tun<br />
#User=root<br />
#Group=root<br />
<br />
BindsToInterfaces=(enp0s25 wlp2s0)<br />
IP=no<br />
<br />
PIDFILE=/run/openconnect_${Interface}.pid<br />
SERVER=vpn.example.net<br />
AUTHGROUP='<AUTHGROUP>'<br />
LOCAL_USERNAME=<USERNAME><br />
REMOTE_USERNAME=<VPN_USERNAME><br />
# Assuming the use of pass(1): <br />
PASSWORD_CMD="su ${LOCAL_USERNAME} -c \"pass ${REMOTE_USERNAME} | head -n 1\""<br />
<br />
ExecUpPost="${PASSWORD_CMD} | /usr/bin/openconnect --background --pid-file=${PIDFILE} --interface='${Interface}' --authgroup='${AUTHGROUP}' --user='${REMOTE_USERNAME}' --passwd-on-stdin ${SERVER}"<br />
ExecDownPre="kill -INT $(cat ${PIDFILE}) ; resolvconf -d ${Interface} ; ip link delete ${Interface}"<br />
</nowiki>}}<br />
<br />
This allows execution like: <br />
<br />
$ netctl start vpn<br />
$ netctl restart vpn<br />
$ netctl stop vpn<br />
<br />
Note that this relies on {{ic|LOCAL_USERNAME}} having a [[gpg-agent]] running, with the passphrase for the PGP key already cached.<br />
<br />
If [[pass]]'s interactive query is wanted, use the following line for {{ic|PASSWORD_CMD}}:<br />
<br />
DISPLAY=":0"<br />
PASSWORD_CMD="su ${LOCAL_USERNAME} -c \"DISPLAY=${DISPLAY} pass ${REMOTE_USERNAME} | head -n 1\""<br />
<br />
Adjust the {{ic|DISPLAY}} variable as necessary.</div>Simon04https://wiki.archlinux.org/index.php?title=Firefox&diff=711531Firefox2022-01-19T12:15:13Z<p>Simon04: /* Profiles */ ffprofile.com</p>
<hr />
<div>[[Category:Web browser]]<br />
[[Category:Mozilla]]<br />
[[ar:Firefox]]<br />
[[de:Firefox]]<br />
[[es:Firefox]]<br />
[[fr:Firefox]]<br />
[[ja:Firefox]]<br />
[[ru:Firefox]]<br />
[[zh-hans:Firefox]]<br />
[[zh-hant:Firefox]]<br />
{{Related articles start}}<br />
{{Related|Firefox/Tweaks}}<br />
{{Related|Firefox/Profile on RAM}}<br />
{{Related|Firefox/Privacy}}<br />
{{Related|Browser extensions}}<br />
{{Related|Chromium}}<br />
{{Related|Opera}}<br />
{{Related articles end}}<br />
[https://www.mozilla.org/firefox Firefox] is a popular open source graphical web browser from [https://www.mozilla.org Mozilla].<br />
<br />
== Installing ==<br />
<br />
Firefox can be [[install]]ed with the {{Pkg|firefox}} package.<br />
<br />
Other alternatives include:<br />
<br />
* {{App|Firefox Developer Edition|for developers|https://www.mozilla.org/firefox/developer/|{{Pkg|firefox-developer-edition}}}}<br />
* {{App|Firefox Extended Support Release|long-term supported version|https://www.mozilla.org/firefox/organizations/|{{AUR|firefox-esr}} or {{AUR|firefox-esr-bin}}}}<br />
* {{App|Firefox Beta|cutting-edge version|https://www.mozilla.org/firefox/channel/desktop/#beta|{{AUR|firefox-beta}} or {{AUR|firefox-beta-bin}}}}<br />
* {{App|Firefox Nightly|nightly builds for testing ([https://developer.mozilla.org/Firefox/Experimental_features experimental features])|https://www.mozilla.org/firefox/channel/desktop/#nightly|{{AUR|firefox-nightly}}}} <br />
* {{App|Firefox KDE|Version of Firefox that incorporates an OpenSUSE patch for better [[#KDE integration|KDE integration]] than is possible through simple Firefox plugins.|https://build.opensuse.org/package/show/mozilla:Factory/MozillaFirefox|{{AUR|firefox-kde-opensuse}}}}<br />
* On top of the different Mozilla build channels, a number of forks exist with more or less special features; see [[List of applications#Gecko-based]].<br />
<br />
A number of language packs are available for Firefox, other than the standard English. Language packs are usually named as {{ic|firefox-i18n-''languagecode''}} (where {{ic|''languagecode''}} can be any language code, such as '''de''', '''ja''', '''fr''', etc.). For a list of available language packs see [https://archlinux.org/packages/extra/any/firefox-i18n/ firefox-i18n] for {{Pkg|firefox}}, [https://archlinux.org/packages/community/any/firefox-developer-edition-i18n/ firefox-developer-edition-i18n] for {{Pkg|firefox-developer-edition}} and [https://aur.archlinux.org/packages/?K=firefox-nightly- firefox-nightly-] for {{AUR|firefox-nightly}}.<br />
<br />
{{Note|1=Language packs are disabled on ''-nightly'' and ''-developer-edition'' due to frequent string changes that may cause crashes. To force a change to the UI language, you may need to set {{ic|intl.locale.requested}} in {{ic|about:config}} [https://www.reddit.com/r/firefox/comments/lx3dp9/how_to_change_interface_language/gpovlsp/?context=8&depth=9].}}<br />
<br />
== Add-ons ==<br />
<br />
Firefox is well known for its large library of add-ons which can be used to add new features or modify the behavior of existing features. Firefox's "Add-ons Manager" is used to manage installed add-ons or find new ones. <br />
<br />
For instructions on how to install add-ons and a list of add-ons, see [[Browser extensions]].<br />
<br />
=== Adding search engines ===<br />
<br />
Search engines may be added to Firefox by creating bookmarks with the {{ic|Location}} field using search URLs completed with %s in place of the query and the {{ic|Keyword}} field completed with user-defined characters:<br />
<br />
Location:<br />
https://duckduckgo.com/html/?q=%s<br />
Keyword:<br />
d<br />
<br />
Searches are performed by pre-pending the search term with the keyword of the specified search engine: {{ic|d archwiki}} will query DuckDuckGo using the search term {{ic|archwiki}}<br />
<br />
Search engines may also be added to Firefox through add-on extensions, see [https://addons.mozilla.org/firefox/search-tools/ this page] for a list of available search tools and engines.<br />
<br />
A very extensive list of search engines can be found at the [https://mycroftproject.com/ Mycroft Project].<br />
<br />
Also, you can use the [https://firefox.maltekraus.de/extensions/add-to-search-bar add-to-searchbar] extension to add a search to your search bar from any web site, by simply right clicking on the site's search field and selecting ''Add to Search Bar...''<br />
<br />
==== firefox-extension-arch-search ====<br />
<br />
[[Install]] the {{AUR|firefox-extension-arch-search}} package to add Arch-specific searches (AUR, wiki, forum, packages, etc) to the Firefox search toolbar.<br />
<br />
== Plugins ==<br />
<br />
Support for all plugins, including Flash Player, was removed in Firefox 85.[https://support.mozilla.org/kb/npapi-plugins][https://support.mozilla.org/kb/end-support-adobe-flash]<br />
<br />
== Configuration ==<br />
<br />
Firefox exposes a number of configuration options. To examine them, enter in the Firefox address bar:<br />
<br />
about:config<br />
<br />
Once set, these affect the user's current profile, and may be synchronized across all devices via [https://www.mozilla.org/firefox/sync/ Firefox Sync]. Please note that only a subset of the {{ic|about:config}} entries are synchronized by this method, and the exact subset may be found by searching for {{ic|services.sync.prefs}} in {{ic|about:config}}. Additional preferences and third party preferences may be synchronized by creating new boolean entries prepending the config value with [https://support.mozilla.org/en-US/kb/sync-custom-preferences services.sync.prefs.sync]. To synchronize the whitelist for the extension [https://addons.mozilla.org/firefox/addon/noscript/ NoScript]:<br />
<br />
services.sync.prefs.sync.capability.policy.maonoscript.sites<br />
<br />
The boolean {{ic|noscript.sync.enabled}} must be set to {{ic|true}} to synchronize the remainder of NoScript's preferences via Firefox Sync.<br />
<br />
=== Settings storage ===<br />
<br />
Firefox stores the configuration for a profile via a {{ic|prefs.js}} in the profile folder, usually {{ic|~/.mozilla/firefox/xxxxxxxx.default/}}. <br />
<br />
Firefox also allows configuration for a profile via a {{ic|user.js}} file: [http://kb.mozillazine.org/User.js_file user.js] kept also in the profile folder. A {{ic|user.js}} configuration supersedes a {{ic|prefs.js}}. For a useful starting point, see e.g [https://github.com/pyllyukko/user.js custom user.js] which is targeted at privacy/security conscious users.<br />
<br />
One drawback of the above approach is that it is not applied system-wide. Furthermore, this is not useful as a "pre-configuration", since the profile directory is created after first launch of the browser. You can, however, let ''firefox'' create a new profile and, after closing it again, [https://support.mozilla.org/en-US/kb/back-and-restore-information-firefox-profiles#w_restoring-a-profile-backup copy the contents] of an already created profile folder into it. <br />
<br />
Sometimes it may be desired to lock certain settings, a feature useful in widespread deployments of customized Firefox. In order to create a system-wide configuration, follow the steps outlined in [http://kb.mozillazine.org/Locking_preferences Locking preferences]:<br />
<br />
1. Create {{ic|/usr/lib/firefox/defaults/pref/local-settings.js}}:<br />
<br />
pref("general.config.obscure_value", 0);<br />
pref("general.config.filename", "mozilla.cfg");<br />
<br />
2. Create {{ic|/usr/lib/firefox/mozilla.cfg}} (this stores the actual configuration):<br />
<br />
//<br />
//...your settings...<br />
// e.g to disable Pocket, uncomment the following lines<br />
// lockPref("extensions.pocket.enabled", false);<br />
// lockPref("browser.newtabpage.activity-stream.feeds.section.topstories", false);<br />
<br />
Please note that the first line must contain exactly {{ic|//}}. The syntax of the file is similar to that of {{ic|user.js}}.<br />
<br />
=== Multimedia playback ===<br />
<br />
Firefox uses [[FFmpeg]] for playing multimedia inside HTML5 {{ic|<audio>}} and {{ic|<video>}} elements. Go to [http://demo.nimius.net/video_test/ video-test page] or [https://hpr.dogphilosophy.net/test/ audio-test page] to check which formats are actually supported.<br />
<br />
Firefox uses [[PulseAudio]] for audio playback and capture. If PulseAudio is not installed, Firefox uses [[alsa]] instead.<br />
<br />
==== HTML5 DRM/Widevine ====<br />
<br />
Widevine is a digital rights management tool that Netflix, Amazon Prime Video, and others use to protect their video content. It can be enabled in ''Preferences > General > Digital Rights Management (DRM) Content''. If you visit a Widevine-enabled page when this setting is disabled, Firefox will display a prompt below the address bar asking for permission to install DRM. Approve this and then wait for the "Downloading" bar to disappear, you are now able to watch videos from Widevine protected sites. <br />
<br />
Firefox can only play 720p video (or lower) with Widevine, due to not using [https://bugzilla.mozilla.org/show_bug.cgi?id=1700815 hardware DRM playback]. It is also required that the private mode browsing is disabled, for the window and in the preferences.<br />
<br />
==== Open With extension ====<br />
<br />
# Install [https://addons.mozilla.org/firefox/addon/open-with/ Open With] add-on.<br />
# Go to ''Add-ons > Open With > Preferences''.<br />
# Proceed with instructions to install a file in your system and test the installation. <br />
# Click ''Add browser''.<br />
# In the dialog write a name for this menu entry and command to start a video streaming capable player (e.g. [[mpv|/usr/bin/mpv]]).<br />
# (Optional step) Add needed arguments to the player (e.g. you may want {{ic|--force-window --ytdl}} for ''mpv'')<br />
# Right click on links or visit pages containing videos. Select newly created entry from Open With's menu and if the site is supported, the player will open as expected.<br />
<br />
The same procedure can be used to associate video downloaders such as ''youtube-dl''.<br />
<br />
==== Hardware video acceleration ====<br />
<br />
[[Hardware video acceleration]] via VA-API is available under [[Wayland]] [https://mastransky.wordpress.com/2020/06/03/firefox-on-fedora-finally-gets-va-api-on-wayland/] and [[Xorg]] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619523] [https://www.phoronix.com/scan.php?page=news_item&px=Firefox-80-VA-API-X11].<br />
<br />
To enable VA-API in Firefox:<br />
<br />
# Ensure that your video card is correctly configured for VA-API:<br />
#* See [[Hardware video acceleration]] for steps to verify and install VA-API drivers if required.<br />
# Ensure WebRender is enabled.<br />
#* Verify WebRender is enabled by opening {{ic|about:support}} and then {{ic|Compositing}}. It is enabled by default in GNOME and other desktop environments [https://mastransky.wordpress.com/2021/01/10/firefox-were-finally-getting-hw-acceleration-on-linux/]. <br />
#** Ensure you are not running Software WebRender as that will not work as of August 2021 [https://bugzilla.mozilla.org/show_bug.cgi?id=1723540#c1]. If necessary WebRender can be force enabled as explained in [[/Tweaks#Enable WebRender compositor]].<br />
# Set the following flags in {{ic|about:config}}:{{Note|1=on Firefox 96 only setting {{ic|media.ffmpeg.vaapi.enabled}} and {{ic|media.rdd-ffmpeg.enabled}} to true ''should'' be necessary. Many below preferences no longer need to be set since [https://bugzilla.mozilla.org/show_bug.cgi?id=1698778#c32 the RDD sandbox] was mostly fixed. However, some issues still remain [https://bugzilla.mozilla.org/show_bug.cgi?id=1743926].}}{{Note|1=starting from Firefox 97, only setting {{ic|media.ffmpeg.vaapi.enabled}} to true ''should'' be necessary.[https://bugzilla.mozilla.org/show_bug.cgi?id=1683808#c36]}}<br />
#* {{ic|media.ffmpeg.vaapi.enabled}} to {{ic|true}} in order to enable the use of VA-API with FFmpeg.<br />
#* {{ic|media.ffvpx.enabled}} to {{ic|false}} to disable the internal decoders for VP8/VP9. This is necessary despite [https://bugzilla.mozilla.org/show_bug.cgi?id=1660336 this bug] being fixed [https://bugzilla.mozilla.org/show_bug.cgi?id=1720363#c6][https://bugzilla.mozilla.org/show_bug.cgi?id=1683808].<br />
#* {{ic|media.navigator.mediadatadecoder_vpx_enabled}} to {{ic|true}} to enable hardware VA-API decoding for WebRTC [https://bugzilla.mozilla.org/show_bug.cgi?id=1709009].<br />
#* {{ic|media.rdd-vpx.enabled}} to {{ic|false}} to disable the remote data decoder process for VP8/VP9. Firefox attempts to use the RDD process for VP8/VP9 but the RDD sandbox blocks VA-API access [https://bugzilla.mozilla.org/show_bug.cgi?id=1673184]. Disabling the remote data decoder for VP8/VP9 process means VA-API will run in the content process instead. In Firefox 96 mostly working support for running VA-API in the RDD process was added.<br />
#** Another possible workaround is to completely disable the RDD process by setting {{ic|media.rdd-process.enabled}} to {{ic|false}}, instead of just disabling it for VP8/VP9 as above.<br />
#* On Intel, in some cases VA-API might not work with the Intel iHD driver {{Pkg|intel-media-driver}}. This might be workaroundable by using the Intel i965 driver {{Pkg|libva-intel-driver}}. This workaround does not work anymore with Intel Iris Xe graphics, which are only supported by {{Pkg|intel-media-driver}}. Luckily Firefox 96 introduced better support for the RDD Process, which should help with {{Pkg|intel-media-driver}}. [https://bugzilla.mozilla.org/show_bug.cgi?id=1619585#c42] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619585#c62] [https://bugzilla.mozilla.org/show_bug.cgi?id=1619585#c63].<br />
#** As a last resort, the content process sandbox can be disabled. However, this is a serious security risk and disables protection against attackers. It is recommended to leave the sandbox settings as default [https://bugzilla.mozilla.org/show_bug.cgi?id=1683808#c26]. Nevertheless, to disable the content sandbox set {{ic|security.sandbox.content.level}} to {{ic|0}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1720363#c9].<br />
# Run Firefox with the following [[environment variable]] enabled:<br />
#* In Wayland, with {{ic|1=MOZ_ENABLE_WAYLAND=1}}, see [[#Wayland]].<br />
#* In X.org, since 94, Firefox will run in EGL mode by default which is sufficient [https://mozillagfx.wordpress.com/2021/10/30/switching-the-linux-graphics-stack-from-glx-to-egl/].<br />
#** For older releases, in X.org, enable EGL with {{ic|1=MOZ_X11_EGL=1}} or set {{ic|gfx.x11-egl.force-enabled}} to {{ic|true}} and {{ic|gfx.x11-egl.force-disabled}} to {{ic|false}} in {{ic|about:config}}.<br />
<br />
{{Warning|Disabling the content process sandbox is a security risk, starting in Firefox 96 initial support for working VA-API in the RDD process exists.}}<br />
<br />
{{Tip|<br />
* As well as following [[Hardware video acceleration#Verification]], one can confirm VA-API usage by checking Firefox VA-API logs. Run Firefox with the {{ic|1=MOZ_LOG="PlatformDecoderModule:5"}} environment variable and check in the log output that VA-API is enabled and used (search for the "VA-API" string) when playing a video for example. Pay attention to these logs as they might indicate that only one of the two possible compositors described before (WebRender or OpenGL) works with VA-API on your particular setup.<br />
* To allow hardware decoding in YouTube, the video codec used must be supported by the hardware. The profiles supported by your GPU can be checked with [[Hardware video acceleration#Verifying VA-API]] and the YouTube codecs used can ''sometimes'' (if offered by YouTube!) be controlled with the [https://addons.mozilla.org/firefox/addon/h264ify/ h264ify] or [https://addons.mozilla.org/firefox/addon/enhanced-h264ify/ enhanced-h264ify] extensions. Alternatively, you can install {{AUR|firefox-h264ify}}.<br />
}}<br />
<br />
{{Note|1=<nowiki/><br />
* NVIDIA's proprietary driver potentially has support for DMA-BUF in the 470 drivers [https://bugs.kde.org/show_bug.cgi?id=428089#c2][https://www.phoronix.com/scan.php?page=news_item&px=NVIDIA-DMA-BUF-Wayland-KDE]. By using [[CUDA]] and DMA-BUF with {{AUR|libva-nvidia-driver}} it should potentially work [https://github.com/elFarto/nvidia-vaapi-driver/#firefox]. DMA-BUF is necessary for hardware video acceleration in Firefox [https://bugzilla.mozilla.org/show_bug.cgi?id=1669189#c4] and since currently there is no DMA-BUF support for [[VDPAU]] nor {{Pkg|libva-vdpau-driver}} this lasts options will not work.<br />
* Currently Firefox's VA-API implementation can decode H.264/AVC, VP8 & VP9 encoded video. AV1 support may be added in the future [https://bugzilla.mozilla.org/show_bug.cgi?id=1652958].<br />
* Multi-GPU systems should automatically choose a suitable GPU for VA-API according to this [https://bugzilla.mozilla.org/show_bug.cgi?id=1588904#c36 solved issue].<br />
* Some videos (e.g. YouTube VR) may show a black image after setting {{ic|media.ffvpx.enabled}} to {{ic|false}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1667537].<br />
* To workaround VA-API not working correctly in the RDD process, the RDD process sandbox can be disabled instead of moving VA-API to the content process as suggested above. This is not recommended since disabling the sandbox is a large security risk and disables protection against attackers. Set the environment variable {{ic|1=MOZ_DISABLE_RDD_SANDBOX=1}} to disable RDD sandbox. <br />
* [[AMDGPU]] users under {{Pkg|linux-hardened}} may need to rebuild ''linux-hardened'' with {{ic|1=CONFIG_CHECKPOINT_RESTORE=y}} due to {{Pkg|mesa}} [https://gitweb.gentoo.org/repo/gentoo.git/tree/media-libs/mesa/mesa-9999.ebuild requiring the kcmp syscall]. This may no longer be necessary due to this [https://bugzilla.mozilla.org/show_bug.cgi?id=1624743 bug being solved].<br />
* While WebRender is default now (either software or hardware), Gecko's legacy OpenGL backend still exists. There might be cases where the legacy backend is useful as explained in [[/Tweaks#Enable Legacy OpenGL compositor]].<br />
}}<br />
<br />
=== Spell checking ===<br />
<br />
Firefox can use system-wide installed [[Hunspell]] dictionaries as well as dictionaries installed through its own extension system.<br />
<br />
To enable spell checking for a specific language right click on any text field and check the ''Check Spelling'' box. To select a language for spell checking to you have right click again and select your language from the ''Languages'' sub-menu.<br />
<br />
When your default language choice does not stick, see [[#Firefox does not remember default spell check language]].<br />
<br />
==== System-wide Hunspell dictionaries ====<br />
<br />
Install [[Hunspell]] and its dictionaries for the languages you require.<br />
<br />
==== Dictionaries as extensions ====<br />
<br />
To get more languages right click on any text field and just click ''Add Dictionaries...'' and select the dictionary you want to install from the [https://addons.mozilla.org/firefox/language-tools/ Dictionaries and Language Packs list].<br />
<br />
{{Tip|For Russian, the extension is packaged as {{Pkg|firefox-spell-ru}}.}}<br />
<br />
=== KDE integration ===<br />
<br />
* To bring the [[KDE]] look to GTK apps (including Firefox), install {{Pkg|breeze-gtk}} and {{Pkg|kde-gtk-config}}. Afterwards, go to System Settings and in ''Appearance > Application Style > Configure GNOME/GTK Application Style…'' choose 'Breeze'.<br />
* To use the KDE file selection and print dialogs in Firefox 64 or newer, install {{Pkg|xdg-desktop-portal}} and {{Pkg|xdg-desktop-portal-kde}}, then do one of the following:<br />
** Set {{ic|widget.use-xdg-desktop-portal}} to {{ic|true}} in {{ic|about:config}}.<br />
** Launch firefox with {{ic|1=GTK_USE_PORTAL=1}} [[environment variable]].<br />
::{{Note|1=Using {{ic|1=GTK_USE_PORTAL=1}} or setting {{ic|widget.use-xdg-desktop-portal}} to {{ic|true}} will result in [https://bugzilla.mozilla.org/show_bug.cgi?id=1516290 Firefox asking to set default browser every time Firefox starts].}}<br />
* For integration with [[KDE]] MIME type system, proxy and file dialog, one can use {{AUR|firefox-kde-opensuse}} variant from AUR with OpenSUSE’s patches applied. Alternatively, integration with MIME types can be achieved by creating a symbolic link to the MIME database {{ic|~/.config/mimeapps.list}} from the deprecated {{ic|~/.local/share/applications/mimeapps.list}} that is used by Firefox. See [[XDG MIME Applications#mimeapps.list]].<br />
* Extensions/add-ons may provide additional integration, such as:<br />
** Browser integration in [[Plasma]]: requires {{Pkg|plasma-browser-integration}} and the [https://addons.mozilla.org/firefox/addon/plasma-integration/ Plasma Integration add-on].<br />
::{{Tip|To prevent duplicate entries in the Media Player widget or tray icon, set {{ic|media.hardwaremediakeys.enabled}} to {{ic|false}}. This disables the media entry from Firefox and only uses the one from the Plasma integration add-on.}}<br />
<br />
== Tips and tricks ==<br />
<br />
For general enhancements see [[Firefox/Tweaks]], for privacy related enhancements see [[Firefox/Privacy]].<br />
<br />
=== Dark themes ===<br />
<br />
If a dark [[GTK]] theme is in use (e.g. Arc Dark), it is recommended to start Firefox with a brighter one (e.g. Adwaita). See [[GTK#Themes]] and [[Firefox/Tweaks#Unreadable input fields with dark GTK themes]] for more information.<br />
<br />
Alternatively, starting with Firefox 68 you can make all the Firefox interfaces and even other websites respect dark themes, irrespective of the system GTK theme and Firefox theme. To do this, set {{ic|ui.systemUsesDarkTheme}} to {{ic|1}} in {{ic|about:config}} [https://bugzilla.mozilla.org/show_bug.cgi?id=1488384#c23].<br />
<br />
=== Frame rate ===<br />
<br />
If Firefox is unable to automatically detect the right value, it will default to 60 fps. To manually correct this, set {{ic|layout.frame_rate}} to the refresh rate of your monitor (e.g. 144 for 144 Hz).<br />
<br />
=== Memory limit ===<br />
<br />
To prevent pages from abusing memory (and possible [[Wikipedia:Out_of_memory|OOM]]), we can use [[Firejail]] with the {{ic|rlimit-as}} option.<br />
<br />
=== New tabs position ===<br />
<br />
To control where new tabs appears (relative or absolute), use {{ic|browser.tabs.insertAfterCurrent}} and {{ic|browser.tabs.insertRelatedAfterCurrent}}. See [https://support.mozilla.org/en/questions/1229062] for more information.<br />
<br />
=== Screenshot of webpage ===<br />
<br />
You can ''Take a Screenshot'' by either clicking the ''Page actions'' button (the three horizontal dots) in the address bar or by right-clicking on the webpage. See [https://support.mozilla.org/en-US/kb/firefox-screenshots] for more information.<br />
<br />
As an alternative you can use the screenshot button in the [https://developer.mozilla.org/en-US/docs/Tools/Taking_screenshots Developer Tools].<br />
<br />
=== Wayland ===<br />
<br />
More recent versions of Firefox support opting into [[Wayland]] mode via an environment variable.<br />
<br />
$ MOZ_ENABLE_WAYLAND=1 firefox<br />
<br />
To make this permanent, see [[Environment variables#Graphical environment]] and start Firefox via the desktop launcher like you normally would.<br />
<br />
To verify it worked, look for {{ic|Window Protocol}} in {{ic|about:support}}. It should say {{ic|wayland}}. The presence of {{ic|x11}} means you are running Firefox under [[Xorg]] display server, while {{ic|xwayland}} means your system is running Wayland but executing Firefox as legacy X11 application. <br />
<br />
On native Wayland, Firefox rendering performance can be significantly improved by setting {{ic|gfx.webrender.compositor.force-enabled}} to {{ic|true}} in {{ic|about:config}}. As of Firefox 89, this feature is experimental and Firefox Nightly is recommended for testing. Keep in mind that this can possibly cause screen-tearing.<br />
<br />
All rendering is allowed to occur in native compositor surfaces, resulting in more efficient rendering, improving performance and battery life [https://bugzilla.mozilla.org/show_bug.cgi?id=1617498]. Ensure [[/Tweaks#Enable WebRender compositor]] is also enabled and working. GNOME 40.1/3.38.5 or KDE 5.22 or later are considered testable compositors [https://bugzilla.mozilla.org/show_bug.cgi?id=1617498#c13].<br />
<br />
=== Window manager rules ===<br />
<br />
To apply different configurations to Firefox windows, change the WM_CLASS string by using Firefox's {{ic|--class}} option, to a custom one.<br />
<br />
=== Profiles ===<br />
<br />
To start new Firefox instances, multiple profiles are required. To create a new profile:<br />
<br />
$ firefox [--new-instance] -P<br />
<br />
Class can be specified when launching Firefox with a not-in-use profile:<br />
<br />
$ firefox [--new-instance] -P ''profile_name'' --class=''class_name''<br />
<br />
Use the [https://ffprofile.com/ Firefox Profilemaker] to create a Firefox profile with the defaults you like.<br />
<br />
=== Touchscreen gestures and pixel-perfect trackpad scrolling ===<br />
<br />
{{Merge|Firefox/Tweaks#Enable touchscreen gestures|Same solution.}}<br />
<br />
To enable touch gestures (like scrolling and pinch-to-zoom) and one-to-one trackpad scrolling (as can be witnessed with GTK3 applications like Nautilus), set the {{ic|1=MOZ_USE_XINPUT2=1}} [[environment variable]] before starting Firefox.<br />
<br />
=== Multiple home pages ===<br />
<br />
To have multiple tabs opened when starting Firefox open a new window and then open the sites you want to have as "home tabs".<br />
<br />
Now go to ''Preferences > Home'' and under ''Homepage and new windows'' click the ''Use Current Pages'' button.<br />
<br />
Alternatively go directly to ''Preferences > Home'' and now under ''Homepage and new windows'' set the first field to ''Custom URLs..'' and enter the pages you want as new home pages in the following format:<br />
<br />
<nowiki>https://url1.com|https://url2.com|https://url3.com</nowiki><br />
<br />
== Troubleshooting ==<br />
<br />
=== Safe Mode ===<br />
<br />
The command line switch {{ic|--safe-mode}} starts Firefox in [http://kb.mozillazine.org/Safe_Mode Safe Mode], which disables extensions, themes and some other features for this session.<br />
<br />
=== Disable hardware video acceleration ===<br />
<br />
To force disable hardware video acceleration in Firefox, e.g. in case of freezes, start Firefox in [[#Safe Mode|Safe Mode]] or set {{ic|layers.acceleration.disabled}} to {{ic|true}} in {{ic|about:config}}.<br />
<br />
=== Extension X does not work on some Mozilla owned domains ===<br />
<br />
By default extensions will not affect pages designated by {{ic|extensions.webextensions.restrictedDomains}}. If this is not desired, this field can be cleared (special pages such as {{ic|about:*}} will not be affected).<br />
<br />
=== Firefox startup takes very long ===<br />
<br />
If Firefox takes much longer to start up than other browsers, it may be due to lacking configuration of the localhost in {{ic|/etc/hosts}}. See [[Network configuration#Local network hostname resolution]] on how to set it up.<br />
<br />
=== Font troubleshooting ===<br />
<br />
See [[Font configuration]].<br />
<br />
Firefox has a setting which determines how many replacements it will allow from Fontconfig. To allow it to use all your replacement rules, change {{ic|gfx.font_rendering.fontconfig.max_generic_substitutions}} to {{ic|127}} (the highest possible value).<br />
<br />
Firefox ships with the ''Twemoji Mozilla'' font. To use the system emoji font, set {{ic|font.name-list.emoji}} to {{ic|emoji}} in {{ic|about:config}}. Additionally, to prevent the Mozilla font interfering with your system emoji font, change {{ic|gfx.font_rendering.opentype_svg.enabled}} to {{ic|false}} or remove {{ic|/usr/lib/firefox/fonts/TwemojiMozilla.ttf}} (see also [[pacman#Skip files from being installed to system]]).<br />
<br />
=== Setting an email client ===<br />
<br />
Inside the browser, {{ic|mailto}} links by default are opened by a web application such as Gmail or Yahoo Mail. To set an external email program, go to ''Preferences > Applications'' and modify the ''action'' corresponding to the {{ic|mailto}} content type; the file path will need to be designated (e.g. {{ic|/usr/bin/kmail}} for Kmail).<br />
<br />
Outside the browser, {{ic|mailto}} links are handled by the {{ic|x-scheme-handler/mailto}} mime type, which can be easily configured with [[xdg-mime]]. See [[Default applications]] for details and alternatives.<br />
<br />
=== File association ===<br />
<br />
See [[Default applications]].<br />
<br />
=== Firefox keeps creating ~/Desktop even when this is not desired ===<br />
<br />
Firefox uses {{ic|~/Desktop}} as the default place for download and upload files. To change it to another folder, set the {{ic|XDG_DESKTOP_DIR}} option as explained in [[XDG user directories]].<br />
<br />
=== Make plugins respect blocked pop-ups ===<br />
<br />
Some plugins can misbehave and bypass the default settings, such as the Flash plugin. You can prevent this by doing the following:<br />
<br />
# Type {{ic|about:config}} into the address bar.<br />
# Right-click on the page and select ''New > Integer''.<br />
# Name it {{ic|privacy.popups.disable_from_plugins}}.<br />
# Set the value to {{ic|2}}.<br />
<br />
The possible values are:<br />
<br />
* {{ic|'''0'''}}: Allow all popups from plugins.<br />
* {{ic|'''1'''}}: Allow popups, but limit them to {{ic|dom.popup_maximum}}.<br />
* {{ic|'''2'''}}: Block popups from plugins.<br />
* {{ic|'''3'''}}: Block popups from plugins, even on whitelisted sites.<br />
<br />
=== Changes to userChrome.css and userContent.css are ignored ===<br />
<br />
Set {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|true}} in {{ic|about:config}}<br />
<br />
=== Middle-click behavior ===<br />
<br />
To use the middle mouse button to paste whatever text has been highlighted/added to the clipboard, as is common in UNIX-like operating systems, set either {{ic|middlemouse.contentLoadURL}} or {{ic|middlemouse.paste}} to {{ic|true}} in {{ic|about:config}}. Having {{ic|middlemouse.contentLoadURL}} enabled was the default behaviour prior to Firefox 57.<br />
<br />
To scroll on middle-click (default for Windows browsers) set {{ic|general.autoScroll}} to {{ic|true}}.<br />
<br />
=== Backspace does not work as the 'Back' button ===<br />
<br />
According to [http://kb.mozillazine.org/Browser.backspace_action MozillaZine], the {{ic|Backspace}} key was mapped based on which platform the browser was running on. As a compromise, this preference was created to allow the {{ic|Backspace}} key to either go back/forward, scroll up/down a page, or do nothing.<br />
<br />
To make {{ic|Backspace}} go back one page in the tab's history and {{ic|Shift+Backspace}} go forward, set {{ic|browser.backspace_action}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
To have the {{ic|Backspace}} key scroll up one page and {{ic|Shift+Backspace}} scroll down one page, set {{ic|browser.backspace_action}} to {{ic|1}}. Setting this property to any other value will leave the key unmapped (Arch Linux defaults to {{ic|2}}, in other words, it is unmapped by default).<br />
<br />
=== Firefox does not remember login information ===<br />
<br />
It may be due to a corrupted {{ic|cookies.sqlite}} file in [https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data Firefox's profile] folder. In order to fix this, just rename or remove {{ic|cookie.sqlite}} while Firefox is not running.<br />
<br />
Open a terminal of choice and type the following:<br />
<br />
$ rm -f ~/.mozilla/firefox/<profile id>.default/cookies.sqlite<br />
<br />
The profile id is a random 8 character string.<br />
<br />
Restart Firefox and see if it solved the problem.<br />
<br />
If it did not work, check if there exists a {{ic|cookies.sqlite.bak}} file that you could use to manually restore the cookies.<br />
<br />
=== Cannot enter/leave fullscreen ===<br />
<br />
If Firefox detects an [https://specifications.freedesktop.org/wm-spec/wm-spec-latest.html EWMH/ICCCM] compliant window manager, it will try to send a WM_STATE message to the root window to request Firefox be made to enter (or leave) full-screen mode (as defined by the window manager). Window managers are allowed to ignore it, but if they do, Firefox will assume the request got denied and propagate it to the end user which results in nothing happening. This may result in not being able to full screen a video. A general workaround is to set the {{ic|full-screen-api.ignore-widgets}} to {{ic|true}} in {{ic|about:config}}. <br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=1189622 Bugzilla 1189622].<br />
<br />
=== Firefox detects the wrong version of my plugin ===<br />
<br />
When you close Firefox, the latter saves the current timestamp and version of your plugins inside {{ic|pluginreg.dat}} located in your profile folder, typically in {{ic|~/.mozilla/firefox/''xxxxxxxx''.default/}}.<br />
<br />
If you upgraded your plugin when Firefox was still running, you will thus have the wrong information inside that file. The next time you will restart Firefox you will get that message {{ic|Firefox has prevented the outdated plugin "XXXX" from running on ...}} when you will be trying to open content dedicated to that plugin on the web. This problem often appears with the official [[Browser plugins#Adobe Flash Player|Adobe Flash Player plugin]] which has been upgraded while Firefox was still running.<br />
<br />
The solution is to remove the file {{ic|pluginreg.dat}} from your profile and that is it. Firefox will not complain about the missing file as it will be recreated the next time Firefox will be closed. [https://bugzilla.mozilla.org/show_bug.cgi?id=1109795#c16]<br />
<br />
=== JavaScript context menu does not appear on some sites ===<br />
<br />
You can try setting {{ic|dom.w3c_touch_events.enabled}} to {{ic|0}} in {{ic|about:config}}.<br />
<br />
=== Firefox does not remember default spell check language ===<br />
<br />
The default spell checking language can be set as follows:<br />
<br />
# Type {{ic|about:config}} in the address bar.<br />
# Set {{ic|spellchecker.dictionary}} to your language of choice, for instance {{ic|en_GB}}.<br />
# Notice that the for dictionaries installed as a Firefox plugin the notation is {{ic|en-GB}}, and for {{Pkg|hunspell}} dictionaries the notation is {{ic|en_GB}}.<br />
<br />
When you only have system wide dictionaries installed with {{Pkg|hunspell}}, Firefox might not remember your default dictionary language settings. This can be fixed by having at least one [https://addons.mozilla.org/firefox/language-tools/ dictionary] installed as a Firefox plugin. Notice that now you will also have a tab ''Dictionaries'' in ''Add-ons''. You may have to change the order of ''preferred language for displaying pages'' in {{ic|about:preferences#general}} to make the spell check default to the language of the addon dictionary.<br />
<br />
Related questions on the '''StackExchange''' platform: [https://stackoverflow.com/questions/26936792/change-firefox-spell-check-default-language/29446115], [https://stackoverflow.com/questions/21542515/change-default-language-on-firefox/29446353], [https://askubuntu.com/questions/184300/how-can-i-change-firefoxs-default-dictionary/576877]<br />
<br />
Related bug reports: [https://bugzilla.mozilla.org/show_bug.cgi?id=776028 Bugzilla 776028], [https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/1026869 Ubuntu bug 1026869]<br />
<br />
=== Some MathML symbols are missing ===<br />
<br />
You need some Math fonts, namely Latin Modern Math and STIX (see this MDN page: [https://developer.mozilla.org/en-US/docs/Mozilla/MathML_Project/Fonts#Linux]), to display MathML correctly.<br />
<br />
In Arch Linux, these fonts are provided by {{Pkg|texlive-core}} '''and''' {{Pkg|texlive-fontsextra}}, but they are not available to fontconfig by default. See [[TeX Live#Making fonts available to Fontconfig]] for details. You can also try other [[Fonts#Math|Math fonts]]. In case you encounter this bug [https://bugzilla.mozilla.org/show_bug.cgi?id=1208776] installing {{Pkg|otf-latinmodern-math}} can help.<br />
<br />
=== Tearing video in fullscreen mode ===<br />
<br />
If you are using the Xorg Intel or Nouveau drivers and experience tearing video in fullscreen mode, try [[Firefox/Tweaks#Enable Legacy OpenGL compositor]].<br />
<br />
=== Tearing when scrolling ===<br />
<br />
Try disabling smooth scrolling in ''Preferences > Browsing''.<br />
<br />
=== Firefox WebRTC module cannot detect a microphone ===<br />
<br />
WebRTC applications for instance [https://mozilla.github.io/webrtc-landing/gum_test.html Firefox WebRTC getUserMedia test page] say that microphone cannot be found. Issue is reproducible for both ALSA or PulseAudio setup. Firefox debug logs show the following error:<br />
<br />
{{hc|1=$ NSPR_LOG_MODULES=MediaManager:5,GetUserMedia:5 firefox|2=<br />
...<br />
[Unnamed thread 0x7fd7c0654340]: D/GetUserMedia VoEHardware:GetRecordingDeviceName: Failed 1<br />
}}<br />
<br />
You can try setting {{ic|media.navigator.audio.full_duplex}} property to {{ic|false}} at {{ic|about:config}} Firefox page and restart Firefox.<br />
<br />
This can also help if you are using the PulseAudio [[PulseAudio#Microphone echo/noise cancellation|module-echo-cancel]] and Firefox does not recognise the virtual echo canceling source.<br />
<br />
=== Cannot login with my Chinese account ===<br />
<br />
Firefox provides a local service for Chinese users, with a local account totally different from the international one. Firefox installed with the {{Pkg|firefox}} package uses the international account system by default, to change into the Chinese local service, you should install the add-on manager on [http://mozilla.com.cn/thread-343905-1-1.html this page], then you can login with your Chinese account now.<br />
<br />
=== No audio on certain videos when using JACK and PulseAudio ===<br />
<br />
If you are using JACK in combination with PulseAudio and cannot hear any sound on some videos it could be because those videos have mono audio. This happens if your JACK setup uses more than just stereo, but you use normal headphones. To fix this you simply have to connect the {{ic|front-center}} port from the PulseAudio JACK Sink to both {{ic|playback_1}} and {{ic|playback_2}} ports of the system output.<br />
<br />
You can also do this automatically using a script:<br />
<br />
{{hc|jack-mono.sh<br />
|2=#!/bin/sh<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_1"<br />
jack_connect "PulseAudio JACK Sink:front-center" "system:playback_2"<br />
}}<br />
<br />
Keep in mind that the names for the sink and the ports might be different for you. You can check what your JACK setup looks like with a Patchbay like Catia from {{Pkg|cadence}}.<br />
<br />
=== Geolocation does not work ===<br />
<br />
Recently, Google limited the use of its location service with Arch Linux, which causes the following error when geolocation is enabled on a website: {{ic|Geolocation error: Unknown error acquiring position}}. Region-locked services such as [https://www.hulu.com/ Hulu] may display a similar error indicating that your location could not be determined even though you have allowed location services for the site.<br />
<br />
To avoid these problems, you can switch to use the [https://location.services.mozilla.com/ Mozilla Location Service]. In {{ic|about:config}} change the {{ic|geo.provider.network.url}} setting to:<br />
<br />
<nowiki>https://location.services.mozilla.com/v1/geolocate?key=%MOZILLA_API_KEY%</nowiki><br />
<br />
See {{Bug|65241}} for more details.<br />
<br />
=== Right mouse button instantly clicks the first option in window managers ===<br />
<br />
This problem has been observed in [[i3]], [[bspwm]] and [[xmonad]].<br />
<br />
To fix it, navigate to {{ic|about:config}} and change {{ic|ui.context_menus.after_mouseup}} to {{ic|true}}.<br />
<br />
See [https://www.reddit.com/r/i3wm/comments/88k0yt/right_mouse_btn_instantly_clicks_first_option_in/]<br />
<br />
=== Applications on Wayland can not launch Firefox ===<br />
<br />
Some applications running in XWayland mode try to launch the X11 edition of Firefox. If the browser already runs in Wayland native mode, the user will receive the error {{ic|Firefox is already running, but is not responding. To use Firefox, you must first close the existing Firefox process, restart your device, or use a different profile.}} while Firefox itself is fully operational. <br />
<br />
This can be worked around by setting the [[environment variable]] {{ic|1=MOZ_DBUS_REMOTE=1}}.<br />
<br />
{{Note|1=It is not sufficient to only set this variable in the ''.desktop'' file for Firefox, as it must be set for either the whole session or all XWayland applications. Consider additionally setting [[#Wayland]] globally. [https://bugzilla.mozilla.org/show_bug.cgi?id=1508803]}}<br />
<br />
=== Firefox window does not repaint after disabling or enabling compositing ===<br />
<br />
Unset the environment variable {{ic|MOZ_X11_EGL}}.<br />
<br />
Related bug report: [https://bugzilla.mozilla.org/show_bug.cgi?id=1711039 Bugzilla 1711039].<br />
<br />
=== Firefox continuously asks to be set as default browser upon launch ===<br />
<br />
There are a couple things you can try: if you are using a [[desktop environment]], check if Firefox is set as the default browser in your system settings. If it is not, then set it, otherwise you can run the following {{man|1|xdg-settings}} command, provided by the [[xdg-utils]] package, to query which browser is set as default on your system:<br />
<br />
$ xdg-settings get default-web-browser<br />
<br />
If no value is returned or it is not Firefox, then run this command to set it:<br />
<br />
$ xdg-settings set default-web-browser firefox.desktop<br />
<br />
If Firefox still asks to be set as the default browser, then it may be quieted if it is set to handle ''http'' and ''https'' URL schemes. To do so, run these {{man|1|xdg-mime}} commands: <br />
<br />
$ xdg-mime default firefox.desktop x-scheme-handler/http<br />
$ xdg-mime default firefox.desktop x-scheme-handler/https<br />
<br />
If those do not work either, check if you have set the environment variable {{ic|GTK_USE_PORTAL}} (all values trigger the bug), in which case, unset it. Related bug report: [https://bugzilla.mozilla.org/show_bug.cgi?id=1516290 Bugzilla 1516290]. If that does not work or you did not set it, navigate Firefox to {{ic|about:config}}, check if the variable {{ic|widget.use-xdg-desktop-portal}} is set to {{ic|true}} and, if so, set it to {{ic|false}}.<br />
<br />
If you wish to disable default browser check entirely, navigate Firefox to {{ic|about:config}} and set {{ic|browser.shell.checkDefaultBrowser}} to {{ic|false}}.<br />
<br />
=== Video stuttering ===<br />
<br />
If you experience video stuttering and you notice that Firefox is only hitting one core at 100% when watching videos (especially higher resolution videos), this might help you.<br />
<br />
Go into {{ic|about:config}} and search for {{ic|dom.ipc.processCount}} and change {{ic|dom.ipc.processCount.file}} from 1 to a higher number. An ad hoc method to find a good number is to increase it one at a time until you get good results, but 4 seems to be a good value.<br />
<br />
== See also ==<br />
<br />
* [https://www.mozilla.org/firefox/ Official website]<br />
* [https://www.mozilla.org/ Mozilla Foundation]<br />
* [[MozillaWiki:Firefox]]<br />
* [[Wikipedia:Mozilla Firefox]]<br />
* [https://addons.mozilla.org/ Firefox Add-ons]<br />
* [https://addons.mozilla.org/firefox/themes/ Firefox themes]<br />
* [https://ftp.mozilla.org/pub/firefox/releases/ Mozilla's FTP]<br />
* [http://forums.mozillazine.org/ mozillaZine] unofficial forums</div>Simon04https://wiki.archlinux.org/index.php?title=YubiKey&diff=705582YubiKey2021-12-11T17:19:27Z<p>Simon04: /* SSH keys */ sub sections; add yubikey-agent</p>
<hr />
<div>[[Category:Universal 2nd Factor]]<br />
[[ja:Yubikey]]<br />
{{Related articles start}}<br />
{{Related|Universal 2nd Factor}}<br />
{{Related|OATH}}<br />
{{Related|dm-crypt/Encrypting an entire system}}<br />
{{Related|PAM}}<br />
{{Related|GnuPG}}<br />
{{Related|KeePass}}<br />
{{Related articles end}}<br />
The [https://www.yubico.com YubiKey] is a small [[Wikipedia:Security token|USB Security token]]. Depending on the model, it can:<br />
<br />
* 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.<br />
* Handle [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests.<br />
* Store and query approximately 30 [[Wikipedia:Initiative_for_Open_Authentication|OATH]] credentials. <br />
* Handle [[Wikipedia:Challenge–response authentication|challenge-response requests]], in either the Yubico OTP mode or the HMAC-SHA1 mode.<br />
* Generate [[Wikipedia:One-time password|One-time passwords]] (OTP) - [https://developers.yubico.com/OTP/ Yubico's AES based standard].<br />
* "Type" a static password up to 63 characters.<br />
<br />
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]. An alternative is the [[Solo]].<br />
<br />
== Installation ==<br />
<br />
=== Management tools ===<br />
<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring and querying a YubiKey over USB. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
::{{Note|After installation, enable {{ic|pcscd.service}}}}<br />
* {{App|YubiKey Personalization|Library and tool for configuring and querying a YubiKey over the OTP USB connection. More powerful than ykman, but harder to use. Has optional GUI. |https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Authentication tools ===<br />
<br />
* {{App|Yubico PAM|[[PAM]] user authentication with either Yubico OTP or challenge-response.|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|Yubico PAM-U2F|[[PAM]] user authentication with [[U2F]].|https://developers.yubico.com/pam-u2f/|{{Pkg|pam-u2f}}}}<br />
* {{App|Yubico Authenticator for Desktop| GUI to read OATH codes from your YubiKey over USB. Support the newer OATH implementation (YubiKey NEO and 4) as well as the older slot-based implementation (YubiKey Standard and Edge).|https://developers.yubico.com/OATH/YubiKey_OATH_software.html|{{Pkg|yubioath-desktop}}}}<br />
* {{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}}}}<br />
* {{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}}}}<br />
<br />
== Inputs ==<br />
<br />
The YubiKey takes inputs in the form of API calls over USB and button presses.<br />
<br />
The button is very sensitive. Depending on the context, touching it does one of these things:<br />
<br />
* 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.<br />
* Confirm / allow a function or access. The LED will illuminate to prompt the user.<br />
* Insert / eject the smartcard<br />
<br />
== Outputs ==<br />
<br />
The YubiKey transforms these inputs into outputs:<br />
<br />
* Keystrokes (emulating a USB keyboard), used to type static passwords and OTPs. (Note that static passwords are vulnerable to keyloggers.)<br />
* The built-in LED:<br />
** Blinks once when plugged in, useful for troubleshooting.<br />
** Blinks steadily when a button press is required to permit an API response.<br />
* API responses over USB. This is used for:<br />
** Challenge-Response requests (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** U2F Challenge-Response requests<br />
** CCID Smartcard related requests<br />
<br />
== USB connection modes ==<br />
<br />
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.<br />
<br />
The following table shows which protocols use which interfaces:<br />
<br />
{| class="wikitable"<br />
! Protocol !! Interface<br />
|-<br />
|OTP || Keyboard HID<br />
|-<br />
|FIDO || Other HID<br />
|-<br />
|PIV || CCID<br />
|-<br />
|OpenPGP || CCID<br />
|-<br />
|OATH || CCID<br />
|}<br />
<br />
{{ic|ykman}} uses the term "modes", named OTP, FIDO, and CCID. <br />
<br />
{{Note|ykman renamed "U2F" to "FIDO" in release 0.6.1 (2018-04-16). https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
=== Get enabled modes ===<br />
<br />
For YubiKey prior to version 5:<br />
<br />
{{hc|$ ykman mode|<br />
Current connection mode is: OTP+FIDO+CCID<br />
}}<br />
<br />
{{Note|The command "ykman mode" has been deprecated and may be removed later}}<br />
<br />
For YubiKey version 5:<br />
<br />
{{hc|$ ykman info|<br />
Device type: YubiKey 5 NFC<br />
Serial number: XXXXXXXXX<br />
Firmware version: 5.4.3<br />
Form factor: Keychain (USB-A)<br />
Enabled USB interfaces: OTP, FIDO, CCID<br />
NFC transport is enabled.<br />
<br />
Applications USB NFC <br />
FIDO2 Enabled Enabled<br />
OTP Enabled Enabled<br />
FIDO U2F Enabled Enabled<br />
OATH Enabled Enabled<br />
YubiHSM Auth Enabled Enabled<br />
OpenPGP Enabled Enabled<br />
PIV Enabled Enabled<br />
}}<br />
<br />
=== Set modes ===<br />
<br />
All modes are enabled from the factory. To change them:<br />
<br />
{{ic|$ ykman mode [OPTIONS] <MODE>}}<br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+FIDO+CCID}}, or a shortened form {{ic|o+f+c}}.<br />
* {{ic|<MODE>}} can be a mode-number, which encodes several enabled modes.<br />
<br />
Here is a table of mode-numbers, if you care to use them:<br />
<br />
{| class="wikitable"<br />
|0||OTP device only.<br />
|-<br />
|1||CCID device only.<br />
|-<br />
|2||OTP/CCID composite device.<br />
|-<br />
|3||U2F device only.<br />
|-<br />
|4||OTP/U2F composite device.<br />
|-<br />
|5||U2F/CCID composite device.<br />
|-<br />
|6||OTP/U2F/CCID composite device. <br />
|-<br />
|81||CCID device only, with touch-eject.<br />
|}<br />
<br />
{{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.}}<br />
<br />
Options:<br />
* {{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.<br />
* {{ic|--autoeject-timeout <SECONDS>}} - Automatically eject the smart card after some time. Same restrictions as {{ic|--touch-eject}}.<br />
* {{ic|--chalresp-timeout <SECONDS>}} - Set the challenge-response timeout.<br />
<br />
For more information, see {{ic|$ ykman mode --help}}<br />
<br />
== One-time password ==<br />
<br />
This feature has a somewhat misleading name, because it also encompasses the static password and challenge-response functions. <br />
<br />
2 slots are provided for this feature, accessible by short and long button presses respectively. Each can be configured with '''one''' of the following:<br />
<br />
* Yubico OTP<br />
* OATH-HOTP<br />
* OATH-TOTP<br />
* Challenge-response<br />
* Static Password<br />
<br />
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}}.<br />
<br />
=== Factory configuration ===<br />
<br />
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).<br />
<br />
{{Warning|If you ever overwrite the factory key in slot 1, you cannot create a new key of the same<br />
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].}}<br />
<br />
=== Yubico OTP ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
Yubico provides a validation server with free unlimited access, called YubiCloud. YubiCloud knows the factory configuration of all YubiKeys, and is the "default" validation service used by (for example) {{pkg|yubico-pam}}. Yubico also offers [https://developers.yubico.com/Software_Projects/Yubico_OTP/YubiCloud_Validation_Servers/ open-source implementations] of the server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can use:<br />
* '''HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have {{pkg|ca-certificates}} installed)}}<br />
<br />
==== Configuration and usage ====<br />
<br />
Generate a new key in slot 2, and upload it to YubiCloud (opens in a browser):<br />
<br />
$ ykman otp yubiotp --generate-key --upload 2<br />
<br />
For more information, see {{ic|$ ykman otp yubiotp --help}}<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
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.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
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.<br />
<br />
=== Challenge-response ===<br />
<br />
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.<br />
<br />
This can be used for<br />
<br />
* 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. <br />
* "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.<br />
<br />
There are two Challenge-Response algorithms:<br />
* HMAC-SHA1<br />
* Yubico OTP<br />
<br />
You can set them up with a GUI using the {{pkg|yubikey-personalization-gui}}, or with the following instructions:<br />
<br />
==== HMAC-SHA1 algorithm ====<br />
<br />
Set up slot 2 in challenge response mode with a generated key:<br />
<br />
$ ykman otp chalresp --generate 2<br />
<br />
You can omit the {{ic|--generate}} flag in order to provide a key. For more information, see {{ic|$ ykman otp chalresp --help}}<br />
<br />
==== Yubico OTP algorithm ====<br />
<br />
{{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:<br />
<br />
$ ykpersonalize -2 -ochal-resp -ochal-yubico<br />
<br />
For more information, see {{man|1|ykpersonalize}}.<br />
<br />
==== Sending a challenge ====<br />
<br />
To send a challenge and get a response:<br />
<br />
$ ykchalresp -''slot'' ''challenge''<br />
<br />
=== Static password ===<br />
<br />
You can either generate a static password:<br />
<br />
$ ykman otp static --generate ''slot''<br />
<br />
or provide one:<br />
<br />
$ ykman otp static ''slot'' ''password''<br />
<br />
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.<br />
<br />
=== Emulated USB keyboard limitations, or "Why does my password look so weak?" ===<br />
<br />
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.<br />
<br />
Yubico has provided a [https://resources.yubico.com/53ZDUYE6/as/9hccqgx9bwwqq96mhkk8jb4h/Static_Password_Function.pdf whitepaper] on the subject.<br />
<br />
== OATH ==<br />
<br />
The YubiKey offers 2 [[OATH]] implementations:<br />
; OATH API: Newer method, can store approximately 30 credentials depending on the model. (YubiKey 4, NEO, and newer)<br />
; OTP slot: Older method, both OTP slots can store a single credential. (All models which support challenge-response)<br />
<br />
=== OATH API ===<br />
<br />
If you prefer a GUI, you can use {{Pkg|yubioath-desktop}}.<br />
<br />
{{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:<br />
<br />
$ zbarimg qr_code.png --quiet --raw | xargs ykman oath uri<br />
<br />
You can also do things manually. Program a TOTP key, requiring a button touch to generate a code:<br />
<br />
$ ykman oath add --touch ''name'' ''secret''<br />
<br />
Program an HOTP key:<br />
<br />
$ ykman oath add --oath-type HOTP ''name'' ''secret''<br />
<br />
List credentials:<br />
<br />
$ ykman oath list<br />
<br />
Generate codes:<br />
<br />
$ ykman oath code ''query''<br />
<br />
To see all available subcommands see {{ic|ykman oath --help}}. To see information about each, use {{ic|ykman oath (subcommand) --help}}.<br />
<br />
=== OTP slot implementation ===<br />
<br />
Program an HOTP in slot 2:<br />
<br />
$ ykman otp hotp 2 ''key''<br />
<br />
Program a TOTP:<br />
<br />
$ ykman otp chalresp --totp ''slot'' ''key''<br />
<br />
Generate an HOTP:<br />
<br />
$ ykman otp calculate ''slot''<br />
<br />
Generate a TOTP:<br />
<br />
$ ykman otp calculate --totp ''slot''<br />
<br />
See also: {{ic|ykman otp --help}} and https://developers.yubico.com/OATH/<br />
<br />
== U2F ==<br />
<br />
[[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: <br />
* Set a PIN: {{ic|$ ykman fido access change-pin}}<br />
* delete individual credentials: {{ic|$ ykman fido delete <QUERY>}}<br />
* Reset all credentials and PIN: {{ic|$ ykman fido reset}}<br />
<br />
To use U2F for authentication, see the instructions in [[U2F]].<br />
<br />
== CCID smartcard ==<br />
<br />
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.<br />
<br />
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/]. Enable at least the CCID mode. Please see [[#Get enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
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 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.<br />
<br />
=== OpenPGP smartcards ===<br />
<br />
The YubiKey can act as a standard GPG smartcard; see the [[GnuPG#Smartcards|GPG Smartcard]] section for instructions on how to set up and use it. Yubico also provides some documentation [https://developers.yubico.com/PGP/ here].<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Use cases ==<br />
<br />
This section details how to use your YubiKey for various authentication purposes. It is by no means an exhaustive list.<br />
<br />
=== Full disk encryption with LUKS ===<br />
<br />
You have several options:<br />
<br />
* '''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.<br />
* '''GnuPG:''' Uses the yubikey's [[#CCID smartcard|PGP smartcard]] functionality. Offers strong 2-factor authentication without needing a huge passphrase.<br />
* '''FIDO HMAC Secret:''' If your YubiKey supports [[U2F]], it can be configured to return a symmetric secret.<br />
<br />
{{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.}}<br />
<br />
==== Common prerequisites ====<br />
<br />
* A bootable [[dm-crypt/Encrypting_an_entire_system|LUKS encrypted]] system, using the {{ic|encrypt}} [[mkinitcpio]] hook, with at least one free keyslot. <br />
** With the exception of {{AUR|mkinitcpio-ykfde}}, the {{ic|sd-encrypt}} hook is not supported by any of these tools.<br />
* Backed up LUKS header (Optional, though advisable)<br />
<br />
==== Challenge-response ====<br />
<br />
See {{Pkg|yubikey-full-disk-encryption}}'s [https://github.com/agherzan/yubikey-full-disk-encryption#usage official documentation] for complete instructions. Broadly:<br />
<br />
# Install {{Pkg|yubikey-full-disk-encryption}}<br />
# Configure {{ic|/etc/ykfde.conf}}<br />
# Enroll the disk: {{ic|# ykfde-enroll -d /dev/<DISK> -s <LUKS_SLOT>}}<br />
# Add the {{ic|ykfde}} [[mkinitcpio#HOOKS|mkinitcpio hook]] before the {{ic|encrypt}} hook. <br />
# Regenerate the initramfs: {{ic| # mkinitcpio -P}}<br />
<br />
:{{Note|Plymouth Users: Replace the {{ic|plymouth-encrypt}} hook with the {{ic|ykfde}} hook.}}<br />
<br />
There are a few variations available:<br />
<br />
* 2FA: default behavior. You must provide the challenge as a password when enrolling the device, and upon boot.<br />
* 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.<br />
* [https://github.com/agherzan/yubikey-full-disk-encryption#enable-nfc-support-in-ykfde-initramfs-hook-experimental NFC support] (Experimental)<br />
* [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.<br />
<br />
You must regenerate the initramfs for any configuration changes to take effect.<br />
<br />
==== systemd-based initramfs ====<br />
<br />
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}}.<br />
<br />
==== GnuPG encrypted keyfile ====<br />
<br />
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 2020 this package is not in the AUR and is not thoroughly tested, though the GitHub repo offers a PKGBUILD.<br />
<br />
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.<br />
<br />
==== HMAC secret extension of FIDO2 protocol ====<br />
<br />
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+].<br />
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].<br />
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 [http://0pointer.net/blog/unlocking-luks2-volumes-with-tpm2-fido2-pkcs11-security-hardware-on-systemd-248.html author's blog post].<br />
<br />
=== KeePass ===<br />
<br />
[[KeePass]] can be configured for YubiKey support; see the [[KeePass#Yubikey|YubiKey section]] for instructions.<br />
<br />
=== SSH keys ===<br />
<br />
==== CCID ====<br />
<br />
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:<br />
* An [https://developers.yubico.com/PIV/Guides/Securing_SSH_with_OpenPGP_or_PIV.html overview of both] possibilities, giving their advantages and disadvantages<br />
* Instructions for [https://developers.yubico.com/PGP/SSH_authentication/index.html PGP authentication]<br />
* Instructions for [https://developers.yubico.com/PIV/Guides/SSH_user_certificates.html PIV authentication through user certificates]<br />
* Instructions for [https://developers.yubico.com/PIV/Guides/SSH_with_PIV_and_PKCS11.html PIV authentication through #PKCS11]<br />
<br />
:{{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.}}<br />
<br />
==== U2F ====<br />
<br />
You may also use the U2F feature of the YubiKey to create hardware-backed SSH keys. See [[U2F#OpenSSH]] for instructions.<br />
<br />
==== PIV ====<br />
<br />
{{aur|yubikey-agent}} stores the SSH key as PIV token. See https://github.com/FiloSottile/yubikey-agent#readme for a setup guide.<br />
<br />
=== Linux user authentication with PAM ===<br />
<br />
[[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.<br />
<br />
There are several modules available which integrate YubiKey-supported protocols into PAM:<br />
* {{Pkg|pam-u2f}} - Supports [[#U2F]] via the FIDO2 standard. If you are not sure which method to use, this one is a good choice.<br />
** [[Universal_2nd_Factor#Authentication_for_Arch_Linux|Arch Wiki Instructions]]<br />
** [https://developers.yubico.com/pam-u2f/ Yubico's official docs], including a list of supported module parameters.<br />
** Man Pages: {{Man|8|pam_u2f}}, {{Man|1|pamu2fcfg}}<br />
* {{Pkg|oath-toolkit}} - Supports [[#OATH]] one-time passwords (either HOTP or TOTP) <br />
** [[pam_oath]]<br />
* {{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.<br />
** [https://developers.yubico.com/yubico-pam/ Yubico's official docs]<br />
** {{Man|8|pam_yubico}} - Take note of the {{ic|mode}} parameter, used to set challenge-response mode.<br />
<br />
{{Warning|Exercise caution when modifying PAM configuration files. Mistakes can render a system completely insecure, or so secure that no authentication is possible.}}<br />
<br />
PAM configuration is beyond the scope of this article, but for a brief overview:<br />
* Create file(s) containing authorized keys, either in users' home directories or centrally.<br />
* Add a line in the appropriate place in the appropriate PAM configuration file which follows this format:<br />
auth [required|sufficient] [module_name].so [module arguments]<br />
* {{ic|auth required}} for multifactor, {{ic|auth sufficient}} for single factor.<br />
* {{ic|module_name}} - Example: {{ic|pam_u2f.so}}. See a list of installed modules: {{ic| $ ls /usr/lib/security }}<br />
* Module configuration arguments are for things like the location of the keyfile, or which method the module should use for authentication.<br />
<br />
==== SSH notes ====<br />
<br />
* Yubico has provided [https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html additional guidance]. It's written for an old version of Ubuntu, but much of it still applies to an updated Arch system.<br />
* 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.<br />
* 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.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
=== Browser/web integration ===<br />
<br />
Many web services are beginning to support FIDO hardware tokens. See the [[U2F]] page 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].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Executing actions on insertion/removal of YubiKey device ===<br />
<br />
For example, you want to perform an action when you pull your YubiKey out of the USB slot, create {{ic|/etc/udev/rules.d/80-yubikey-actions.rules}} and add the following contents:<br />
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"<br />
<br />
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.<br />
<br />
== Maintenance / upgrades ==<br />
<br />
=== Installing the OATH Applet for a YubiKey NEO ===<br />
<br />
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.<br />
{{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)}}<br />
<br />
==== Configure the NEO as a CCID device ====<br />
<br />
# Install {{pkg|yubikey-personalization-gui}} ({{AUR|yubikey-personalization-gui-git}}).<br />
# Add the udev rules and reboot so you can manage the YubiKey without needing to be root<br />
# Run {{ic|ykpersonalize -m82}}, enter {{ic|y}}, and hit enter.<br />
<br />
==== Install the applet ====<br />
<br />
# Install {{AUR|gpshell}}, {{AUR|gppcscconnectionplugin}}, {{AUR|globalplatform}}, and {{Pkg|pcsclite}}.<br />
# [[Start]] {{ic|pcscd.service}}.<br />
# Download the most recent CAP file from the [https://developers.yubico.com/ykneo-oath/Releases/ ykneo-oath] site.<br />
# Download {{ic|gpinstall.txt}} from [https://github.com/Yubico/ykneo-oath/blob/master/gpinstall.txt GitHub].<br />
# Edit the line in gpinstall.txt beginning with {{ic|install -file}} to reflect the path where the CAP file is located.<br />
# Open a terminal and run {{ic| gpshell <location of gpinstall.txt>}}<br />
# Ideally, a bunch of text will scroll by and it ends saying something like<br />
{{ bc | Command --> 80E88013D7C000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A<br />
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C<br />
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44<br />
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A100<br />
Wrapped command --> 84E88013DFC000C400BE00C700CA00CA00B400BE00CE00D200D500D700B000DB00C700DF00BEFFFF00BE00E400AC00AE00AE00DB00E700A<br />
A00EA00ED00ED00ED00BE00EF00F100F400F100F700FA00FF00BE00F700AA01010103010700CA00C400B400AA00F700B400AA00B600C7010C<br />
010C00AA0140012001B0056810B0013005600000056810E0011006B4B44304B44404B44106B44B4405B443400343B002410636810E06B4B44<br />
407326810B004B43103441003334002B102B404B3B403BB4003B440076820A4100221024405B4341008B44600000231066820A15D848CB77<br />
27D0EDA00<br />
Response <-- 009000<br />
Command --> 80E60C002107A000000527210108A00000052721010108A000000527210101010003C901000000<br />
Wrapped command --> 84E60C002907A000000527210108A00000052721010108A000000527210101010003C9010000B4648127914A4C7C00<br />
Response <-- 009000<br />
card_disconnect<br />
release_context}}<br />
# Unplug the NEO and try it with the Yubico Authenticator app<br />
<br />
==== (Optional) Install the Yubico Authenticator desktop client ====<br />
<br />
You can get the desktop version of the Yubico Authenticator by installing {{Pkg|yubioath-desktop}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-desktop}} and insert your YubiKey when prompted.<br />
<br />
== Troubleshooting ==<br />
<br />
Restart, especially if you have completed updates since your YubiKey last worked. Do this even if some functions appear to be functioning.<br />
<br />
=== YubiKey not acting as HID device ===<br />
<br />
{{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.}}<br />
<br />
Add udev rule as described in [https://michaelheap.com/yubikey-on-arch/ this article]:<br />
<br />
{{hc|/etc/udev/rules.d/10-security-key.rules|2=<br />
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="users", ATTRS{idVendor}=="2581", ATTRS{idProduct}=="f1d0"<br />
}}<br />
<br />
Run {{ic|udevadm trigger}} afterwards.<br />
<br />
=== ykman fails to connect to the YubiKey ===<br />
<br />
If the manager fails to connect to the YubiKey, make sure you have started {{ic|pcscd.service}} or {{ic|pcscd.socket}}.<br />
<br />
=== Error: Failed connecting to YubiKey 5 [OTP+FIDO+CCID]. Make sure the application have the required permissions. ===<br />
<br />
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]<br />
<br />
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/support/solutions/articles/15000014892-troubleshooting-gpg-no-such-device-]{{Dead link|2021|05|17|status=404}}<br />
<br />
{{Note|This will cause the gpgagent to re-prompt you to unlock the YubiKey after each time you access the YubiKey through ykman.}}<br />
<br />
For YubiKey NEO and YubiKey 4:<br />
reader-port Yubico Yubikey<br />
or for YubiKey 5<br />
reader-port Yubico Yubi<br />
<br />
=== YubiKey fails to bind within a guest VM ===<br />
<br />
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:<br />
<br />
# dmesg | grep -B1 Yubico | tail -n 2 | head -n 1 | sed -E 's/^\<nowiki>[[^]]</nowiki>+\] usb (<nowiki>[^:]</nowiki>*):.*/\1/'<br />
<br />
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}}).<br />
<br />
$ find /sys/bus/usb/drivers -name "*X-Y.Z*"<br />
<br />
To unbind the device, use the result from the previous command (i.e. {{ic|/sys/bus/usb/drivers/<DRIVER>/X-Y.Z:1.0}}):<br />
<br />
# echo 'X-Y.Z:1.0' > /sys/bus/usb/drivers/<DRIVER>/unbind<br />
<br />
=== Error: [key] could not be locally signed or gpg: No default secret key: No public key ===<br />
<br />
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 archlinux}}. The solution is to remove the offending YubiKey and start over.<br />
<br />
=== YubiKey disappears and reappears in Yubico Authenticator ===<br />
<br />
This happens when the CCID driver is not installed. You may need to [[install]] the {{pkg|ccid}} package.<br />
<br />
=== YubiKey core error: timeout ===<br />
<br />
You are probably using the wrong slot. Try the other one.</div>Simon04https://wiki.archlinux.org/index.php?title=SSH_keys&diff=705576SSH keys2021-12-11T17:14:09Z<p>Simon04: /* FIDO/U2F */ fix <ref></p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[es:SSH keys]]<br />
[[ja:SSH 鍵]]<br />
[[sr:SSH keys]]<br />
[[zh-hans:SSH keys]]<br />
{{Expansion|The intro and ''Background'' section ignore the server perspective.}}<br />
<br />
SSH keys can serve as a means of identifying yourself to an SSH server using [[Wikipedia:Public-key cryptography|public-key cryptography]] and [[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 (see [[RFC:4251#section-9.4.4|RFC 4251 9.4.4]]).<br />
<br />
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.<br />
<br />
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. <br />
<br />
This article assumes you already have a basic understanding of the [[Secure Shell]] protocol and have [[install]]ed the {{Pkg|openssh}} package.<br />
<br />
== Background ==<br />
<br />
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.<br />
<br />
If an SSH server has your 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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Generating an SSH key pair ==<br />
<br />
An SSH key pair can be generated by running the {{ic|ssh-keygen}} command, defaulting to 3072-bit RSA (and SHA256) which the {{man|1|ssh-keygen}} man page says is "''generally considered sufficient''" and should be compatible with virtually all clients and servers:<br />
<br />
{{hc<br />
|$ ssh-keygen<br />
|<nowiki>Generating public/private rsa key pair.<br />
Enter file in which to save the key (/home/<username>/.ssh/id_rsa): <br />
Enter passphrase (empty for no passphrase): <br />
Enter same passphrase again: <br />
Your identification has been saved in /home/<username>/.ssh/id_rsa.<br />
Your public key has been saved in /home/<username>/.ssh/id_rsa.pub.<br />
The key fingerprint is:<br />
SHA256:gGJtSsV8BM+7w018d39Ji57F8iO6c0N2GZq3/RY2NhI username@hostname<br />
The key's randomart image is:<br />
+---[RSA 3072]----+<br />
| ooo. |<br />
| oo+. |<br />
| + +.+ |<br />
| o + + E . |<br />
| . . S . . =.o|<br />
| . + . . B+@o|<br />
| + . oo*=O|<br />
| . ..+=o+|<br />
| o=ooo+|<br />
+----[SHA256]-----+</nowiki>}}<br />
<br />
The [https://www.cs.berkeley.edu/~dawnsong/papers/randomart.pdf randomart image] was [https://www.openssh.com/txt/release-5.1 introduced in OpenSSH 5.1] as an easier means of visually identifying the key fingerprint.<br />
<br />
{{Note|You can use the {{ic|-a}} switch to specify the number of KDF rounds on the password encryption.}}<br />
<br />
You can also add an optional comment field to the public key with the {{ic|-C}} switch, to more easily identify it in places such as {{ic|~/.ssh/known_hosts}}, {{ic|~/.ssh/authorized_keys}} and {{ic|ssh-add -L}} output. For example:<br />
<br />
$ ssh-keygen -C "$(whoami)@$(uname -n)-$(date -I)"<br />
<br />
will add a comment saying which user created the key on which machine and when.<br />
<br />
=== Choosing the authentication key type ===<br />
<br />
OpenSSH supports several signing algorithms (for authentication keys) which can be divided in two groups depending on the mathematical properties they exploit:<br />
<br />
# [[Wikipedia:Digital Signature Algorithm|DSA]] and [[Wikipedia:RSA (cryptosystem)|RSA]], which rely on the [[wikipedia:Integer factorization#Difficulty and complexity|practical difficulty]] of factoring the product of two large prime numbers,<br />
# [[Wikipedia:Elliptic Curve Digital Signature Algorithm|ECDSA]] and [[Wikipedia:Curve25519|Ed25519]], which rely on the elliptic curve [[Wikipedia:Discrete logarithm|discrete logarithm]] problem. ([https://www.certicom.com/content/certicom/en/52-the-elliptic-curve-discrete-logarithm-problem.html example])<br />
<br />
[https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/ Elliptic curve cryptography] (ECC) algorithms are a [[Wikipedia:Elliptic curve cryptography#History|more recent addition]] to public key cryptosystems. One of their main advantages is their ability to provide [[Wikipedia:Elliptic curve cryptography#Rationale|the same level of security with smaller keys]], which makes for less computationally intensive operations (''i.e.'' faster key creation, encryption and decryption) and reduced storage and transmission requirements.<br />
<br />
OpenSSH 7.0 [https://archlinux.org/news/openssh-70p1-deprecates-ssh-dss-keys/ deprecated and disabled support for DSA keys] due to discovered vulnerabilities, therefore the choice of [[Wikipedia:cryptosystem|cryptosystem]] lies within RSA or one of the two types of ECC.<br />
<br />
[[#RSA]] keys will give you the greatest portability, while [[#Ed25519]] will give you the best security but requires recent versions of client & server[https://web.archive.org/web/20191222003107/https://www.gentoo.org/support/news-items/2015-08-13-openssh-weak-keys.html]. [[#ECDSA]] is likely more compatible than Ed25519 (though still less than RSA), but suspicions exist about its security (see below).<br />
<br />
{{Note|These keys are used only to authenticate you; choosing stronger keys will not increase CPU load when transferring data over SSH.<br />
}}<br />
<br />
==== RSA ====<br />
<br />
{{ic|ssh-keygen}} defaults to RSA therefore there is no need to specify it with the {{ic|-t}} option. It provides the best compatibility of all algorithms but requires the key size to be larger to provide sufficient security.<br />
<br />
Minimum key size is 1024 bits, default is 3072 (see {{man|1|ssh-keygen}}) and maximum is 16384.<br />
<br />
If you wish to generate a stronger RSA key pair (''e.g.'' to guard against cutting-edge or unknown attacks and more sophisticated attackers), simply specify the {{ic|-b}} option with a higher bit value than the default:<br />
<br />
$ ssh-keygen -b 4096<br />
<br />
Be aware though that there are diminishing returns in using longer keys.[https://security.stackexchange.com/a/25377][https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096] The GnuPG FAQ reads: "''If you need more security than RSA-2048 offers, the way to go would be to switch to elliptical curve cryptography — not to continue using RSA''."[https://www.gnupg.org/faq/gnupg-faq.html#please_use_ecc]<br />
<br />
On the other hand, the latest iteration of the [https://web.archive.org/web/20160305203915/https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml NSA Fact Sheet Suite B Cryptography] suggests a minimum 3072-bit modulus for RSA while "''[preparing] for the upcoming quantum resistant algorithm transition''".[https://www.keylength.com/en/6/]<br />
<br />
==== ECDSA ====<br />
<br />
The Elliptic Curve Digital Signature Algorithm (ECDSA) was introduced as the preferred algorithm for authentication [https://www.openssh.com/txt/release-5.7 in OpenSSH 5.7]. Some vendors also disable the required implementations due to potential patent issues.<br />
<br />
There are two sorts of concerns with it:<br />
<br />
# ''Political concerns'', the trustworthiness of NIST-produced curves [https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters being questioned] after revelations that the NSA willingly inserts backdoors into softwares, hardware components and published standards were made; well-known cryptographers [https://www.schneier.com/blog/archives/2013/09/the_nsa_is_brea.html#c1675929 have] [https://safecurves.cr.yp.to/rigid.html expressed] [https://www.hyperelliptic.org/tanja/vortraege/20130531.pdf doubts] about how the NIST curves were designed, and voluntary tainting has already [https://www.schneier.com/blog/archives/2007/11/the_strange_sto.html been] [https://www.scientificamerican.com/article/nsa-nist-encryption-scandal/ proved] in the past.<br />
# ''Technical concerns'', about the [https://blog.cr.yp.to/20140323-ecdsa.html difficulty to properly implement the standard] and the [https://www.gossamer-threads.com/lists/openssh/dev/57162#57162 slowness and design flaws] which reduce security in insufficiently precautious implementations. <br />
<br />
Both of those concerns are best summarized in [https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt#n4 libssh curve25519 introduction]. Although the political concerns are still subject to debate, there is a [https://news.ycombinator.com/item?id=7597653 clear consensus] that [[#Ed25519]] is technically superior and should therefore be preferred.<br />
<br />
==== Ed25519 ====<br />
<br />
[https://ed25519.cr.yp.to/ Ed25519] was introduced in [https://www.openssh.com/txt/release-6.5 OpenSSH 6.5] of January 2014: "''Ed25519 is an elliptic curve signature scheme that offers better security than ECDSA and DSA and good performance''". Its main strengths are its speed, its constant-time run time (and resistance against side-channel attacks), and its lack of nebulous hard-coded constants.[https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt] See also [https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/ this blog post] by a Mozilla developer on how it works.<br />
<br />
It is already implemented in [[Wikipedia:Curve25519#Popularity|many applications and libraries]] and is the [https://www.libssh.org/2013/11/03/openssh-introduces-curve25519-sha256libssh-org-key-exchange/ default key exchange algorithm] (which is different from key ''signature'') in OpenSSH.<br />
<br />
Ed25519 key pairs can be generated with:<br />
<br />
$ ssh-keygen -t ed25519<br />
<br />
There is no need to set the key size, as all Ed25519 keys are 256 bits.<br />
<br />
Keep in mind that older SSH clients and servers may not support these keys.<br />
<br />
==== FIDO/U2F ====<br />
<br />
FIDO/[[U2F]] [[Wikipedia:Security Tokens|hardware authenticator]] support was added in [https://www.openssh.com/txt/release-8.2 OpenSSH version 8.2] for both of the elliptic curve signature schemes mentioned above. It allows for a hardware token attached via USB or other means to act a second factor alongside the private key. <br />
<br />
{{Note|Both the client and server must support the {{ic|ed25519-sk}} and {{ic|ecdsa-sk}} key types.}}<br />
<br />
The {{Pkg|libfido2}} is required for hardware token support.<br />
<br />
{{Note|OpenSSH uses a middleware library to communicate with the hardware token and comes with an internal middleware which supports USB tokens. Other middleware may be specified by the {{man|5|sshd_config|SecurityKeyProvider}} directive or the {{ic|SSH_SK_PROVIDER}} environment variable for {{ic|ssh-keygen}} and {{ic|ssh-add}}.}}<br />
<br />
After attaching a compatible FIDO key, a key pair may be generated with:<br />
<br />
$ ssh-keygen -t ed25519-sk<br />
<br />
You will usually be required to enter your PIN and/or tap your token to confirm the generation. Connecting to a server will usually require tapping your token unless the {{ic|-O no-touch-required}} command line option is used during generation and the {{man|8|sshd|no-touch-required}} {{ic|authorized_keys}} option is set on the server.<br />
<br />
{{Note|Not all hardware tokens support this option. If you are using a YubiKey, firmware version 5.2.3 is needed for the ed25519-sk key type.[https://www.yubico.com/blog/whats-new-in-yubikey-firmware-5-2-3/]}}<br />
<br />
An ECDSA-based keypair may also be generated with the {{ic|ecdsa-sk}} keytype, but the relevant concerns in the [[#ECDSA]] section above still apply.<br />
<br />
$ ssh-keygen -t ecdsa-sk<br />
<br />
=== Choosing the key location and passphrase ===<br />
<br />
Upon issuing the {{ic|ssh-keygen}} command, you will be prompted for the desired name and location of your private key. By default, keys are stored in the {{ic|~/.ssh/}} directory and named according to the type of encryption used. You are advised to accept the default name and location in order for later code examples in this article to work properly.<br />
<br />
When prompted for a passphrase, choose something that will be hard to guess if you have the security of your private key in mind. A longer, more random password will generally be stronger and harder to crack should it fall into the wrong hands.<br />
<br />
It is also possible to create your private key without a passphrase. While this can be convenient, you need to be aware of the associated risks. Without a passphrase, your private key will be stored on disk in an unencrypted form. Anyone who gains access to your private key file will then be able to assume your identity on any SSH server to which you connect using key-based authentication. Furthermore, without a passphrase, you must also trust the root user, as he can bypass file permissions and will be able to access your unencrypted private key file at any time.<br />
<br />
{{Note|Previously, the private key password was encoded in an insecure way: only a single round of an MD5 hash. OpenSSH 6.5 and later support a new, more secure format to encode your private key. This format is the default since [https://www.openssh.com/txt/release-7.8 OpenSSH version 7.8]. Ed25519 keys have always used the new encoding format. To upgrade to the new format, simply change the key's passphrase, as described in the next section.}}<br />
<br />
==== Changing the private key's passphrase without changing the key ====<br />
<br />
If the originally chosen SSH key passphrase is undesirable or must be changed, one can use the {{ic|ssh-keygen}} command to change the passphrase without changing the actual key. This can also be used to change the password encoding format to the new standard.<br />
<br />
$ ssh-keygen -f ~/.ssh/id_rsa -p<br />
<br />
==== Managing multiple keys ====<br />
<br />
If you have multiple SSH identities, you can set different keys to be used for different hosts or remote users by using the {{ic|Match}} and {{ic|IdentityFile}} directives in your configuration:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host=SERVER1<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_rsa_IDENTITY1<br />
<br />
Match host=SERVER2,SERVER3<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_ed25519_IDENTITY2<br />
}}<br />
<br />
See {{man|5|ssh_config}} for full description of these options.<br />
<br />
==== Storing SSH keys on hardware tokens ====<br />
<br />
{{Expansion|[https://www.openssh.com/txt/release-8.2 OpenSSH version 8.2] adds support for FIDO2 resident keys, allowing SSH Keys to be stored on the hardware token.}}<br />
<br />
SSH keys can also be stored on a security token like a smart card or a USB token. This has the advantage that the private key is stored securely on the token instead of being stored on disk. When using a security token the sensitive private key is also never present in the RAM of the PC; the cryptographic operations are performed on the token itself. A cryptographic token has the additional advantage that it is not bound to a single computer; it can easily be removed from the computer and carried around to be used on other computers.<br />
<br />
Examples are hardware tokens are described in:<br />
<br />
* [[YubiKey#SSH notes]] Native OpenSSH support for FIDO/U2F keys<br />
* [[YubiKey#SSH keys]]<br />
* [[Trusted Platform Module#Securing SSH keys]]<br />
<br />
== Copying the public key to the remote server ==<br />
<br />
{{Expansion|How to do this if you [[OpenSSH#Force public key authentication|force public key authentication]]?}}<br />
<br />
Once you have generated a key pair, you will need to copy the public key to the remote server so that it will use SSH key authentication. The public key file shares the same name as the private key except that it is appended with a {{ic|.pub}} extension. Note that the private key is not shared and remains on the local machine.<br />
<br />
=== Simple method ===<br />
<br />
{{Note|1=This method might fail if the remote server uses a non-{{ic|sh}} shell such as {{ic|tcsh}} as default and uses OpenSSH older than 6.6.1p1. See [https://bugzilla.redhat.com/show_bug.cgi?id=1045191 this bug report].}}<br />
<br />
If your key file is {{ic|~/.ssh/id_rsa.pub}} you can simply enter the following command.<br />
<br />
$ ssh-copy-id remote-server.org<br />
<br />
If your username differs on remote machine, be sure to prepend the username followed by {{ic|@}} to the server name.<br />
<br />
$ ssh-copy-id username@remote-server.org<br />
<br />
If your public key filename is anything other than the default of {{ic|~/.ssh/id_rsa.pub}} you will get an error stating {{ic|/usr/bin/ssh-copy-id: ERROR: No identities found}}. In this case, you must explicitly provide the location of the public key.<br />
<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub username@remote-server.org<br />
<br />
If the ssh server is listening on a port other than default of 22, be sure to include it within the host argument.<br />
<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 221 username@remote-server.org<br />
<br />
=== Manual method ===<br />
<br />
By default, for OpenSSH, the public key needs to be concatenated with {{ic|~/.ssh/authorized_keys}}. Begin by copying the public key to the remote server.<br />
<br />
$ scp ~/.ssh/id_ecdsa.pub username@remote-server.org:<br />
<br />
The above example copies the public key ({{ic|id_ecdsa.pub}}) to your home directory on the remote server via {{ic|scp}}. Do not forget to include the {{ic|:}} at the end of the server address. Also note that the name of your public key may differ from the example given.<br />
<br />
On the remote server, you will need to create the {{ic|~/.ssh}} directory if it does not yet exist and append your public key to the {{ic|authorized_keys}} file.<br />
<br />
$ ssh username@remote-server.org<br />
username@remote-server.org's password:<br />
$ mkdir ~/.ssh<br />
$ chmod 700 ~/.ssh<br />
$ cat ~/id_ecdsa.pub >> ~/.ssh/authorized_keys<br />
$ rm ~/id_ecdsa.pub<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
The last two commands remove the public key file from the server and set the permissions on the {{ic|authorized_keys}} file such that it is only readable and writable by you, the owner.<br />
<br />
== SSH agents ==<br />
<br />
If your private key is encrypted with a passphrase, this passphrase must be entered every time you attempt to connect to an SSH server using public-key authentication. Each individual invocation of {{ic|ssh}} or {{ic|scp}} will need the passphrase in order to decrypt your private key before authentication can proceed.<br />
<br />
An SSH agent is a program which caches your decrypted private keys and provides them to SSH client programs on your behalf. In this arrangement, you must only provide your passphrase once, when adding your private key to the agent's cache. This facility can be of great convenience when making frequent SSH connections.<br />
<br />
An agent is typically configured to run automatically upon login and persist for the duration of your login session. A variety of agents, front-ends, and configurations exist to achieve this effect. This section provides an overview of a number of different solutions which can be adapted to meet your specific needs.<br />
<br />
=== ssh-agent ===<br />
<br />
{{ic|ssh-agent}} is the default agent included with OpenSSH. It can be used directly or serve as the back-end to a few of the front-end solutions mentioned later in this section. When {{ic|ssh-agent}} is run, it forks to background and prints necessary environment variables. E.g.<br />
<br />
{{hc|$ ssh-agent|2=<br />
SSH_AUTH_SOCK=/tmp/ssh-vEGjCM2147/agent.2147; export SSH_AUTH_SOCK;<br />
SSH_AGENT_PID=2148; export SSH_AGENT_PID;<br />
echo Agent pid 2148;<br />
}}<br />
<br />
To make use of these variables, run the command through the {{ic|eval}} command.<br />
<br />
{{hc|$ eval $(ssh-agent)|<br />
Agent pid 2157<br />
}}<br />
<br />
Once {{ic|ssh-agent}} is running, you will need to add your private key to its cache:<br />
<br />
{{hc|$ ssh-add ~/.ssh/id_ed25519|<br />
Enter passphrase for /home/user/.ssh/id_ed25519:<br />
Identity added: /home/user/.ssh/id_ed25519 (/home/user/.ssh/id_ed25519)<br />
}}<br />
<br />
If your private key is encrypted, {{ic|ssh-add}} will prompt you to enter your passphrase. Once your private key has been successfully added to the agent you will be able to make SSH connections without having to enter your passphrase.<br />
<br />
{{Tip|To make all {{ic|ssh}} clients, including {{ic|git}} store keys in the agent on first use, add the configuration setting {{ic|AddKeysToAgent yes}} to {{ic|~/.ssh/config}}. Other possible values are {{ic|confirm}}, {{ic|ask}} and {{ic|no}} (default).}}<br />
<br />
In order to start the agent automatically and make sure that only one {{ic|ssh-agent}} process runs at a time, add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
if ! pgrep -u "$USER" ssh-agent > /dev/null; then<br />
ssh-agent -t 1h > "$XDG_RUNTIME_DIR/ssh-agent.env"<br />
fi<br />
if [[ ! "$SSH_AUTH_SOCK" ]]; then<br />
source "$XDG_RUNTIME_DIR/ssh-agent.env" >/dev/null<br />
fi<br />
</nowiki>}}<br />
<br />
This will run a {{ic|ssh-agent}} process if there is not one already, and save the output thereof. If there is one running already, we retrieve the cached {{ic|ssh-agent}} output and evaluate it which will set the necessary environment variables. The lifetime of the unlocked keys is set to 1 hour.<br />
<br />
There also exist a number of front-ends to {{ic|ssh-agent}} and alternative agents described later in this section which avoid this problem.<br />
<br />
==== Start ssh-agent with systemd user ====<br />
<br />
It is possible to use the [[systemd/User]] facilities to start the agent. Use this if you would like your ssh agent to run when you are logged in, regardless of whether x is running.<br />
<br />
{{hc|~/.config/systemd/user/ssh-agent.service|2=<br />
[Unit]<br />
Description=SSH key agent<br />
<br />
[Service]<br />
Type=simple<br />
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket<br />
# DISPLAY required for ssh-askpass to work<br />
Environment=DISPLAY=:0<br />
ExecStart=/usr/bin/ssh-agent -D -a $SSH_AUTH_SOCK<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
Then ''export'' the [[environment variable]] {{ic|1=SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"}} in your [[login shell]] initialization file, such as {{ic|~/.bash_profile}} or {{ic|~/.zprofile}}, or in {{ic|~/.pam_environment}}.<br />
<br />
Finally, [[enable]] or [[start]] the service with the {{ic|--user}} flag.<br />
<br />
{{Note|<br />
* If you use GNOME, this environment variable is overridden by default. See [[GNOME/Keyring#Disable keyring daemon components]].<br />
* Make sure to not overwrite an existing {{ic|SSH_AUTH_SOCK}} if you want to be able to use a [[OpenSSH#Agent forwarding|forwarded ssh agent]].<br />
}}<br />
<br />
{{Tip|When starting the agent via systemd as described above, it is possible to automatically enter the passphrase of your default key and add it to the agent. See [https://github.com/capocasa/systemd-user-pam-ssh systemd-user-pam-ssh] for details.}}<br />
<br />
==== ssh-agent as a wrapper program ====<br />
<br />
An alternative way to start ssh-agent (with, say, each X session) is described in [https://upc.lbl.gov/docs/user/sshagent.shtml this ssh-agent tutorial by UC Berkeley Labs]. A basic use case is if you normally begin X with the {{ic|startx}} command, you can instead prefix it with {{ic|ssh-agent}} like so:<br />
<br />
$ ssh-agent startx<br />
<br />
And so you do not even need to think about it you can put an alias in your {{ic|.bash_aliases}} file or equivalent:<br />
<br />
alias startx='ssh-agent startx'<br />
<br />
Doing it this way avoids the problem of having extraneous {{ic|ssh-agent}} instances floating around between login sessions. Exactly one instance will live and die with the entire X session.<br />
<br />
{{Note|As an alternative to calling {{ic|ssh-agent startx}}, you can add {{ic|eval $(ssh-agent)}} to {{ic|~/.xinitrc}}.}}<br />
<br />
See [[#Calling x11-ssh-askpass with ssh-add|the below notes on using x11-ssh-askpass with ssh-add]] for an idea on how to immediately add your key to the agent.<br />
<br />
=== GnuPG Agent ===<br />
<br />
The [[gpg-agent]] has OpenSSH Agent protocol emulation. See [[GnuPG#SSH agent]] for necessary configuration.<br />
<br />
=== Keychain ===<br />
<br />
[[Funtoo:Keychain|Keychain]] is a program designed to help you easily manage your SSH keys with minimal user interaction. It is implemented as a shell script which drives both ''ssh-agent'' and ''ssh-add''. A notable feature of Keychain is that it can maintain a single ''ssh-agent'' process across multiple login sessions. This means that you only need to enter your passphrase once each time your local machine is booted.<br />
<br />
==== Installation ====<br />
<br />
[[Install]] the {{Pkg|keychain}} package.<br />
<br />
==== Configuration ====<br />
<br />
{{Warning|As of 2015-09-26, the {{ic|-Q, --quick}} option has the unexpected side-effect of making ''keychain'' switch to a newly-spawned ''ssh-agent'' upon relogin (at least on systems using [[GNOME]]), forcing you to re-add all the previously registered keys.}}<br />
<br />
Add a line similar to the following to your [[shell]] configuration file, ''e.g.'' if using [[Bash]]:<br />
<br />
{{hc|~/.bashrc|<br />
eval $(keychain --eval --quiet id_ed25519 id_rsa ~/.keys/my_custom_key)<br />
}}<br />
<br />
{{Note|{{ic|~/.bashrc}} is used instead of the upstream suggested {{ic|~/.bash_profile}} because on Arch it is sourced by both login and non-login shells, making it suitable for textual and graphical environments alike. See [[Bash#Invocation]] for more information on the difference between those.}}<br />
<br />
In the above example,<br />
* the {{ic|--eval}} switch outputs lines to be evaluated by the opening {{ic|eval}} command; this sets the necessary environment variables for an SSH client to be able to find your agent.<br />
* {{ic|--quiet}} will limit output to warnings, errors, and user prompts.<br />
<br />
Multiple keys can be specified on the command line, as shown in the example. By default keychain will look for key pairs in the {{ic|~/.ssh/}} directory, but absolute path can be used for keys in non-standard location. You may also use the {{ic|--confhost}} option to inform keychain to look in {{ic|~/.ssh/config}} for {{ic|IdentityFile}} settings defined for particular hosts, and use these paths to locate keys.<br />
<br />
See {{ic|keychain --help}} or {{man|1|keychain}} for details on setting ''keychain'' for other shells.<br />
<br />
To test Keychain, simply open a new terminal emulator or log out and back in your session. It should prompt you for the passphrase of the specified private key(s) (if applicable), either using the program set in {{ic|$SSH_ASKPASS}} or on the terminal.<br />
<br />
Because Keychain reuses the same ''ssh-agent'' process on successive logins, you should not have to enter your passphrase the next time you log in or open a new terminal. You will only be prompted for your passphrase once each time the machine is rebooted.<br />
<br />
==== Tips ====<br />
<br />
* ''keychain'' expects public key files to exist in the same directory as their private counterparts, with a {{ic|.pub}} extension. If the private key is a symlink, the public key can be found alongside the symlink or in the same directory as the symlink target (this capability requires the {{ic|readlink}} command to be available on the system).<br />
<br />
*to disable the graphical prompt and always enter your passphrase on the terminal, use the {{ic|--nogui}} option. This allows to copy-paste long passphrases from a password manager for example.<br />
<br />
*if you do not want to be immediately prompted for unlocking the keys but rather wait until they are needed, use the {{ic|--noask}} option.<br />
<br />
{{Note|Keychain is able to manage [[GPG]] keys in the same fashion. By default it attempts to start ''ssh-agent'' only, but you can modify this behavior using the {{ic|--agents}} option, ''e.g.'' {{ic|--agents ssh,gpg}}. See {{man|1|keychain}}.}}<br />
<br />
=== x11-ssh-askpass ===<br />
<br />
The {{pkg|x11-ssh-askpass}} package provides a graphical dialog for entering your passhrase when running an X session. ''x11-ssh-askpass'' depends only on the {{Pkg|libx11}} and {{Pkg|libxt}} libraries, and the appearance of ''x11-ssh-askpass'' is customizable. While it can be invoked by the ''ssh-add'' program, which will then load your decrypted keys into [[#ssh-agent|ssh-agent]], the following instructions will, instead, configure ''x11-ssh-askpass'' to be invoked by the aforementioned [[#Keychain|Keychain]] script.<br />
<br />
Install the {{Pkg|keychain}} and {{Pkg|x11-ssh-askpass}} packages.<br />
<br />
Edit your {{ic|~/.xinitrc}} file to include the following lines, replacing the name and location of your private key if necessary. Be sure to place these commands '''before''' the line which invokes your window manager.<br />
<br />
{{hc|~/.xinitrc|<br />
keychain ~/.ssh/id_ecdsa<br />
[ -f ~/.keychain/$HOSTNAME-sh ] && . ~/.keychain/$HOSTNAME-sh 2>/dev/null<br />
[ -f ~/.keychain/$HOSTNAME-sh-gpg ] && . ~/.keychain/$HOSTNAME-sh-gpg 2>/dev/null<br />
...<br />
exec openbox-session}}<br />
<br />
In the above example, the first line invokes ''keychain'' and passes the name and location of your private key. If this is not the first time ''keychain'' was invoked, the following two lines load the contents of {{ic|$HOSTNAME-sh}} and {{ic|$HOSTNAME-sh-gpg}}, if they exist. These files store the environment variables of the previous instance of ''keychain''.<br />
<br />
==== Calling x11-ssh-askpass with ssh-add ====<br />
<br />
The ''ssh-add'' manual page specifies that, in addition to needing the {{ic|DISPLAY}} variable defined, you also need {{ic|SSH_ASKPASS}} set to the name of your askpass program (in this case ''x11-ssh-askpass''). It bears keeping in mind that the default Arch Linux installation places the ''x11-ssh-askpass'' binary in {{ic|/usr/lib/ssh/}}, which will not be in most people's {{ic|PATH}}. This is a little annoying, not only when declaring the {{ic|SSH_ASKPASS}} variable, but also when theming. You have to specify the full path everywhere. Both inconveniences can be solved simultaneously by symlinking:<br />
<br />
$ ln -sv /usr/lib/ssh/x11-ssh-askpass ~/bin/ssh-askpass<br />
<br />
This is assuming that {{ic|~/bin}} is in your {{ic|PATH}}. So now in your {{ic|.xinitrc}}, before calling your window manager, one just needs to export the {{ic|SSH_ASKPASS}} environment variable:<br />
<br />
$ export SSH_ASKPASS=ssh-askpass<br />
<br />
and your [[X resources]] will contain something like:<br />
<br />
ssh-askpass*background: #000000<br />
<br />
Doing it this way works well with [[#ssh-agent as a wrapper program|the above method on using ''ssh-agent'' as a wrapper program]]. You start X with {{ic|ssh-agent startx}} and then add ''ssh-add'' to your window manager's list of start-up programs.<br />
<br />
==== Theming ====<br />
<br />
The appearance of the ''x11-ssh-askpass'' dialog can be customized by setting its associated [[X resources]]. Some examples are the .ad files at https://github.com/sigmavirus24/x11-ssh-askpass. See {{man|1|x11-ssh-askpass}} for full details.<br />
<br />
==== Alternative passphrase dialogs ====<br />
<br />
There are other passphrase dialog programs which can be used instead of ''x11-ssh-askpass''. The following list provides some alternative solutions.<br />
<br />
* {{Pkg|ksshaskpass}} uses the [[KDE Wallet]].<br />
* {{Pkg|openssh-askpass}} uses the [[Qt]] library.<br />
* {{Pkg|lxqt-openssh-askpass}}<br />
<br />
=== pam_ssh ===<br />
<br />
The [http://pam-ssh.sourceforge.net/ pam_ssh] project exists to provide a [[Pluggable Authentication Module]] (PAM) for SSH private keys. This module can provide single sign-on behavior for your SSH connections. On login, your SSH private key passphrase can be entered in place of, or in addition to, your traditional system password. Once you have been authenticated, the pam_ssh module spawns ssh-agent to store your decrypted private key for the duration of the session.<br />
<br />
To enable single sign-on behavior at the tty login prompt, install the unofficial {{AUR|pam_ssh}} package. <br />
<br />
{{Note|pam_ssh 2.0 now requires that all private keys used in the authentication process be located under {{ic|~/.ssh/login-keys.d/}}.}}<br />
<br />
Create a symlink to your private key file and place it in {{ic|~/.ssh/login-keys.d/}}. Replace the {{ic|id_rsa}} in the example below with the name of your own private key file.<br />
<br />
$ mkdir ~/.ssh/login-keys.d/<br />
$ cd ~/.ssh/login-keys.d/<br />
$ ln -s ../id_rsa<br />
<br />
Edit the {{ic|/etc/pam.d/login}} configuration file to include the text highlighted in bold in the example below. The order in which these lines appear is significiant and can affect login behavior.<br />
<br />
{{Warning|Misconfiguring PAM can leave the system in a state where all users become locked out. Before making any changes, you should have an understanding of how PAM configuration works as well as a backup means of accessing the PAM configuration files, such as an Arch Live CD, in case you become locked out and need to revert any changes. An IBM developerWorks [https://developer.ibm.com/tutorials/l-pam/ article] is available which explains PAM configuration in further detail.}}<br />
<br />
{{hc|/etc/pam.d/login|2=<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
'''auth optional pam_ssh.so try_first_pass'''<br />
account include system-local-login<br />
session include system-local-login<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
In the above example, login authentication initially proceeds as it normally would, with the user being prompted to enter his user password. The additional {{ic|auth}} authentication rule added to the end of the authentication stack then instructs the pam_ssh module to try to decrypt any private keys found in the {{ic|~/.ssh/login-keys.d}} directory. The {{ic|try_first_pass}} option is passed to the pam_ssh module, instructing it to first try to decrypt any SSH private keys using the previously entered user password. If the user's private key passphrase and user password are the same, this should succeed and the user will not be prompted to enter the same password twice. In the case where the user's private key passphrase user password differ, the pam_ssh module will prompt the user to enter the SSH passphrase after the user password has been entered. The {{ic|optional}} control value ensures that users without an SSH private key are still able to log in. In this way, the use of pam_ssh will be transparent to users without an SSH private key.<br />
<br />
If you use another means of logging in, such as an X11 display manager like [[SLiM]] or [[XDM]] and you would like it to provide similar functionality, you must edit its associated PAM configuration file in a similar fashion. Packages providing support for PAM typically place a default configuration file in the {{ic|/etc/pam.d/}} directory.<br />
<br />
Further details on how to use pam_ssh and a list of its options can be found in the {{man|8|pam_ssh|url=}} man page.<br />
<br />
==== Using a different password to unlock the SSH key ====<br />
<br />
If you want to unlock the SSH keys or not depending on whether you use your key's passphrase or the (different!) login password, you can modify {{ic|/etc/pam.d/system-auth}} to<br />
<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth [success=1 new_authtok_reqd=1 ignore=ignore default=ignore] pam_unix.so try_first_pass nullok'''<br />
'''auth required pam_ssh.so use_first_pass'''<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
session optional pam_permit.so<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
For an explanation, see [https://unix.stackexchange.com/a/239486].<br />
<br />
==== Known issues with pam_ssh ====<br />
<br />
Work on the pam_ssh project is infrequent and the documentation provided is sparse. You should be aware of some of its limitations which are not mentioned in the package itself.<br />
<br />
* Versions of pam_ssh prior to version 2.0 do not support SSH keys employing the newer option of ECDSA (elliptic curve) cryptography. If you are using earlier versions of pam_ssh you must use either RSA or DSA keys.<br />
<br />
* The {{ic|ssh-agent}} process spawned by pam_ssh does not persist between user logins. If you like to keep a [[GNU Screen]] session active between logins you may notice when reattaching to your screen session that it can no longer communicate with ssh-agent. This is because the GNU Screen environment and those of its children will still reference the instance of ssh-agent which existed when GNU Screen was invoked but was subsequently killed in a previous logout. The [[#Keychain|Keychain]] front-end avoids this problem by keeping the ssh-agent process alive between logins.<br />
<br />
=== pam_exec-ssh ===<br />
<br />
As an alternative to [[#pam_ssh|pam_ssh]] you can use {{AUR|pam_exec-ssh}}. It is a shell script that uses pam_exec. Help for configuration can be found [https://github.com/x70b1/pam_exec-ssh upstream].<br />
<br />
=== GNOME Keyring ===<br />
<br />
If you use the [[GNOME]] desktop, the [[GNOME Keyring]] tool can be used as an SSH agent. See the [[GNOME Keyring]] article for further details.<br />
<br />
=== Store SSH keys with Kwallet ===<br />
<br />
For instructions on how to use kwallet to store your SSH keys, see [[KDE Wallet#Using the KDE Wallet to store ssh key passphrases]].<br />
<br />
=== KeePass2 with KeeAgent plugin ===<br />
<br />
[https://lechnology.com/software/keeagent/ KeeAgent] is a plugin for [[KeePass]] that allows SSH keys stored in a KeePass database to be used for SSH authentication by other programs.<br />
<br />
* Supports both PuTTY and OpenSSH private key formats.<br />
* Works with native SSH agent on Linux/Mac and with PuTTY on Windows.<br />
<br />
See [[KeePass#Plugin installation in KeePass]] or [[install]] the {{Pkg|keepass-plugin-keeagent}} package.<br />
<br />
This agent can be used directly, by matching KeeAgent socket: {{ic|KeePass -> Tools -> Options -> KeeAgent -> Agent mode socket file -> %XDG_RUNTIME_DIR%/keeagent.socket}}-<br />
and environment variable:<br />
{{ic|1=export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR"'/keeagent.socket'}}.<br />
<br />
=== KeePassXC ===<br />
<br />
The KeePassXC fork of KeePass [https://keepassxc.org/docs/#faq-ssh-agent-how supports being used as an SSH agent by default]. It is also compatible with KeeAgent's database format.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Key ignored by the server ===<br />
<br />
* If it appears that the SSH server is ignoring your keys, ensure that you have the proper permissions set on all relevant files.<br />
:For the local machine:<br />
<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/''key''<br />
<br />
:For the remote machine:<br />
<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
: For the remote machine, also check that the target user's home directory has the correct permissions (it must ''not'' be writable by the group and others):<br />
<br />
$ chmod go-w /home/''target_user''<br />
<br />
* If that does not solve the problem you may try temporarily setting {{ic|StrictModes}} to {{ic|no}} in {{ic|/etc/ssh/sshd_config}}. If authentication with {{ic|StrictModes off}} is successful, it is likely an issue with file permissions persists.<br />
<br />
* Make sure keys in {{ic|~/.ssh/authorized_keys}} are entered correctly and only use one single line.<br />
* Make sure the remote machine supports the type of keys you are using: some servers do not support ECDSA keys, try using RSA or DSA keys instead, see [[#Generating an SSH key pair]].<br />
* You may want to use debug mode and monitor the output while connecting:<br />
<br />
# /usr/bin/sshd -d<br />
<br />
* If you gave another name to your key, for example {{ic|id_rsa_server}}, you need to connect with the {{ic|-i}} option:<br />
<br />
$ ssh -i id_rsa_server user@server<br />
<br />
== See also ==<br />
<br />
* OpenSSH key management: [[Funtoo:OpenSSH Key Management, Part 1|Part 1]], [[Funtoo:OpenSSH Key Management, Part 2|Part 2]], [[Funtoo:OpenSSH Key Management, Part 3|Part 3]]<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Simon04https://wiki.archlinux.org/index.php?title=Universal_2nd_Factor&diff=705575Universal 2nd Factor2021-12-11T17:13:35Z<p>Simon04: /* OpenSSH */ →SSH keys#FIDO/U2F</p>
<hr />
<div>[[Category:Universal 2nd Factor]]<br />
[[ja:Universal 2nd Factor]]<br />
[[Wikipedia:Universal 2nd Factor|Universal 2nd Factor (U2F)]] is an open standard that strengthens and simplifies two-factor authentication (2FA) using specialized USB or NFC devices based on similar security technology found in smart cards.<br />
<br />
While initially developed by Google and Yubico, with contribution from NXP Semiconductors, the standard is now hosted by the FIDO Alliance.<br />
<br />
For all articles on U2F and U2F-devices see: [[:Category:Universal 2nd Factor]].<br />
<br />
== Authentication for websites ==<br />
<br />
U2F is supported by major sites like Google, Facebook, Twitter, or GitHub. Check out [https://twofactorauth.org/ twofactorauth.org] or [https://www.dongleauth.info/ dongleauth.info] to find other websites and links to setup documentation. For all browsers which support it, likely the only action required is to install {{Pkg|libfido2}}. Yubico offers a [https://demo.yubico.com/ demo page] for testing.<br />
<br />
=== Firefox ===<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<br />
<br />
=== Chromium/Chrome ===<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
== Authentication for Arch Linux ==<br />
<br />
Yubico, the company creating the YubiKey, develops an U2F [[PAM]] module. It can be used to act as a second factor during login or replace the need for a password entirely.<br />
<br />
=== Installing the PAM module ===<br />
<br />
The module is part of the package {{Pkg|pam-u2f}}.<br />
<br />
=== Adding a key ===<br />
<br />
Keys need to be added with the tool {{ic|pamu2fcfg}}:<br />
<br />
$ mkdir ~/.config/Yubico<br />
$ pamu2fcfg -o pam://hostname -i pam://hostname > ~/.config/Yubico/u2f_keys<br />
<br />
Click the button of your U2F key to confirm the key.<br />
<br />
{{Note|If the hostname of your system changes, e.g. because of DHCP in different networks, you would be unable to login. In order to prevent that, it is recommended to specify the abovementioned options and replace {{ic|hostname}} with the actual hostname.}}<br />
<br />
If you own multiple keys, append them with<br />
<br />
$ pamu2fcfg -o pam://hostname -i pam://hostname -n >> ~/.config/Yubico/u2f_keys<br />
<br />
=== Passwordless sudo ===<br />
<br />
{{Warning|Before making any changes to your configuration, start a separate shell with root permissions (e.g. {{ic|sudo -s}}). This way you can revert any changes if something goes wrong.}}<br />
<br />
Open {{ic|/etc/pam.d/sudo}} and add<br />
<br />
auth sufficient pam_u2f.so cue origin=pam://hostname appid=pam://hostname<br />
<br />
as the first line. Be sure to replace the {{ic|hostname}} as mentioned above. Then create a new terminal and type {{ic|sudo ls}}. Your key's LED should flash and after clicking it the command is executed. The option {{ic|cue}} is set to provide indication of what to do, i.e. {{ic|Please touch the device}}.<br />
<br />
=== GDM login ===<br />
<br />
Open {{ic|/etc/pam.d/gdm-password}} and add<br />
<br />
auth required pam_u2f.so nouserok origin=pam://hostname appid=pam://hostname<br />
<br />
after the existing {{ic|auth}} lines. Please note the use of the {{ic|nouserok}} option which allows the rule to fail if the user did not configure a key. This way setups with multiple users where only some of them use a U2F key are supported.<br />
<br />
{{Note|This method will not work with encrypted home partitions because the decryption is not done before the login process completed, so the {{ic|u2f_keys}} file is unavailable. In this case use a central mapping file as explained in the [https://developers.yubico.com/pam-u2f/ official documentation of pam-u2f].}}<br />
<br />
=== Other authentication methods ===<br />
<br />
Enable the PAM module for other services like explained above. For example, to secure the screensaver of [[Cinnamon]], edit {{ic|/etc/pam.d/cinnamon-screensaver}}.<br />
<br />
=== Troubleshooting ===<br />
<br />
If you managed to lock yourself out of the system, boot into recovery mode or from a USB pen drive. Then revert the changes in the PAM config and reboot.<br />
<br />
== OpenSSH ==<br />
<br />
OpenSSH ≥8.2 supports FIDO/U2F hardware tokens natively, see [[SSH keys#FIDO/U2F]].<br />
<br />
== Data-at-rest encryption with LUKS ==<br />
<br />
Since version 248, [[systemd]] can be use to unlock a [[Dm-crypt/Encrypting an entire system|LUKS partition]] using a FIDO2 key.<br />
<br />
First, you will need to setup your {{ic|/etc/crypttab}} file, or customize your {{ic|initramfs}} if you wish to unlock your root partition. The full procedure is similar to the use of a TPM chip for unlocking. See [[Trusted Platform Module#systemd-cryptenroll]].<br />
<br />
To register the key, you will need to use the ''systemd-cryptenroll'' utility. First, run the following command to list your detected keys: <br />
<br />
$ systemd-cryptenroll --fido2-device=list<br />
<br />
Then you can register the key in a LUKS slot, specifying the path to the FIDO2 device, or using the {{ic|auto}} value :<br />
<br />
$ systemd-cryptenroll --fido2-device=/path/to/fido2_device /dev/sdX</div>Simon04https://wiki.archlinux.org/index.php?title=SSH_keys&diff=705574SSH keys2021-12-11T17:13:30Z<p>Simon04: /* FIDO/U2F */ merge from Universal_2nd_Factor#OpenSSH</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[es:SSH keys]]<br />
[[ja:SSH 鍵]]<br />
[[sr:SSH keys]]<br />
[[zh-hans:SSH keys]]<br />
{{Expansion|The intro and ''Background'' section ignore the server perspective.}}<br />
<br />
SSH keys can serve as a means of identifying yourself to an SSH server using [[Wikipedia:Public-key cryptography|public-key cryptography]] and [[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 (see [[RFC:4251#section-9.4.4|RFC 4251 9.4.4]]).<br />
<br />
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.<br />
<br />
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. <br />
<br />
This article assumes you already have a basic understanding of the [[Secure Shell]] protocol and have [[install]]ed the {{Pkg|openssh}} package.<br />
<br />
== Background ==<br />
<br />
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.<br />
<br />
If an SSH server has your 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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Generating an SSH key pair ==<br />
<br />
An SSH key pair can be generated by running the {{ic|ssh-keygen}} command, defaulting to 3072-bit RSA (and SHA256) which the {{man|1|ssh-keygen}} man page says is "''generally considered sufficient''" and should be compatible with virtually all clients and servers:<br />
<br />
{{hc<br />
|$ ssh-keygen<br />
|<nowiki>Generating public/private rsa key pair.<br />
Enter file in which to save the key (/home/<username>/.ssh/id_rsa): <br />
Enter passphrase (empty for no passphrase): <br />
Enter same passphrase again: <br />
Your identification has been saved in /home/<username>/.ssh/id_rsa.<br />
Your public key has been saved in /home/<username>/.ssh/id_rsa.pub.<br />
The key fingerprint is:<br />
SHA256:gGJtSsV8BM+7w018d39Ji57F8iO6c0N2GZq3/RY2NhI username@hostname<br />
The key's randomart image is:<br />
+---[RSA 3072]----+<br />
| ooo. |<br />
| oo+. |<br />
| + +.+ |<br />
| o + + E . |<br />
| . . S . . =.o|<br />
| . + . . B+@o|<br />
| + . oo*=O|<br />
| . ..+=o+|<br />
| o=ooo+|<br />
+----[SHA256]-----+</nowiki>}}<br />
<br />
The [https://www.cs.berkeley.edu/~dawnsong/papers/randomart.pdf randomart image] was [https://www.openssh.com/txt/release-5.1 introduced in OpenSSH 5.1] as an easier means of visually identifying the key fingerprint.<br />
<br />
{{Note|You can use the {{ic|-a}} switch to specify the number of KDF rounds on the password encryption.}}<br />
<br />
You can also add an optional comment field to the public key with the {{ic|-C}} switch, to more easily identify it in places such as {{ic|~/.ssh/known_hosts}}, {{ic|~/.ssh/authorized_keys}} and {{ic|ssh-add -L}} output. For example:<br />
<br />
$ ssh-keygen -C "$(whoami)@$(uname -n)-$(date -I)"<br />
<br />
will add a comment saying which user created the key on which machine and when.<br />
<br />
=== Choosing the authentication key type ===<br />
<br />
OpenSSH supports several signing algorithms (for authentication keys) which can be divided in two groups depending on the mathematical properties they exploit:<br />
<br />
# [[Wikipedia:Digital Signature Algorithm|DSA]] and [[Wikipedia:RSA (cryptosystem)|RSA]], which rely on the [[wikipedia:Integer factorization#Difficulty and complexity|practical difficulty]] of factoring the product of two large prime numbers,<br />
# [[Wikipedia:Elliptic Curve Digital Signature Algorithm|ECDSA]] and [[Wikipedia:Curve25519|Ed25519]], which rely on the elliptic curve [[Wikipedia:Discrete logarithm|discrete logarithm]] problem. ([https://www.certicom.com/content/certicom/en/52-the-elliptic-curve-discrete-logarithm-problem.html example])<br />
<br />
[https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/ Elliptic curve cryptography] (ECC) algorithms are a [[Wikipedia:Elliptic curve cryptography#History|more recent addition]] to public key cryptosystems. One of their main advantages is their ability to provide [[Wikipedia:Elliptic curve cryptography#Rationale|the same level of security with smaller keys]], which makes for less computationally intensive operations (''i.e.'' faster key creation, encryption and decryption) and reduced storage and transmission requirements.<br />
<br />
OpenSSH 7.0 [https://archlinux.org/news/openssh-70p1-deprecates-ssh-dss-keys/ deprecated and disabled support for DSA keys] due to discovered vulnerabilities, therefore the choice of [[Wikipedia:cryptosystem|cryptosystem]] lies within RSA or one of the two types of ECC.<br />
<br />
[[#RSA]] keys will give you the greatest portability, while [[#Ed25519]] will give you the best security but requires recent versions of client & server[https://web.archive.org/web/20191222003107/https://www.gentoo.org/support/news-items/2015-08-13-openssh-weak-keys.html]. [[#ECDSA]] is likely more compatible than Ed25519 (though still less than RSA), but suspicions exist about its security (see below).<br />
<br />
{{Note|These keys are used only to authenticate you; choosing stronger keys will not increase CPU load when transferring data over SSH.<br />
}}<br />
<br />
==== RSA ====<br />
<br />
{{ic|ssh-keygen}} defaults to RSA therefore there is no need to specify it with the {{ic|-t}} option. It provides the best compatibility of all algorithms but requires the key size to be larger to provide sufficient security.<br />
<br />
Minimum key size is 1024 bits, default is 3072 (see {{man|1|ssh-keygen}}) and maximum is 16384.<br />
<br />
If you wish to generate a stronger RSA key pair (''e.g.'' to guard against cutting-edge or unknown attacks and more sophisticated attackers), simply specify the {{ic|-b}} option with a higher bit value than the default:<br />
<br />
$ ssh-keygen -b 4096<br />
<br />
Be aware though that there are diminishing returns in using longer keys.[https://security.stackexchange.com/a/25377][https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096] The GnuPG FAQ reads: "''If you need more security than RSA-2048 offers, the way to go would be to switch to elliptical curve cryptography — not to continue using RSA''."[https://www.gnupg.org/faq/gnupg-faq.html#please_use_ecc]<br />
<br />
On the other hand, the latest iteration of the [https://web.archive.org/web/20160305203915/https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml NSA Fact Sheet Suite B Cryptography] suggests a minimum 3072-bit modulus for RSA while "''[preparing] for the upcoming quantum resistant algorithm transition''".[https://www.keylength.com/en/6/]<br />
<br />
==== ECDSA ====<br />
<br />
The Elliptic Curve Digital Signature Algorithm (ECDSA) was introduced as the preferred algorithm for authentication [https://www.openssh.com/txt/release-5.7 in OpenSSH 5.7]. Some vendors also disable the required implementations due to potential patent issues.<br />
<br />
There are two sorts of concerns with it:<br />
<br />
# ''Political concerns'', the trustworthiness of NIST-produced curves [https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters being questioned] after revelations that the NSA willingly inserts backdoors into softwares, hardware components and published standards were made; well-known cryptographers [https://www.schneier.com/blog/archives/2013/09/the_nsa_is_brea.html#c1675929 have] [https://safecurves.cr.yp.to/rigid.html expressed] [https://www.hyperelliptic.org/tanja/vortraege/20130531.pdf doubts] about how the NIST curves were designed, and voluntary tainting has already [https://www.schneier.com/blog/archives/2007/11/the_strange_sto.html been] [https://www.scientificamerican.com/article/nsa-nist-encryption-scandal/ proved] in the past.<br />
# ''Technical concerns'', about the [https://blog.cr.yp.to/20140323-ecdsa.html difficulty to properly implement the standard] and the [https://www.gossamer-threads.com/lists/openssh/dev/57162#57162 slowness and design flaws] which reduce security in insufficiently precautious implementations. <br />
<br />
Both of those concerns are best summarized in [https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt#n4 libssh curve25519 introduction]. Although the political concerns are still subject to debate, there is a [https://news.ycombinator.com/item?id=7597653 clear consensus] that [[#Ed25519]] is technically superior and should therefore be preferred.<br />
<br />
==== Ed25519 ====<br />
<br />
[https://ed25519.cr.yp.to/ Ed25519] was introduced in [https://www.openssh.com/txt/release-6.5 OpenSSH 6.5] of January 2014: "''Ed25519 is an elliptic curve signature scheme that offers better security than ECDSA and DSA and good performance''". Its main strengths are its speed, its constant-time run time (and resistance against side-channel attacks), and its lack of nebulous hard-coded constants.[https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt] See also [https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/ this blog post] by a Mozilla developer on how it works.<br />
<br />
It is already implemented in [[Wikipedia:Curve25519#Popularity|many applications and libraries]] and is the [https://www.libssh.org/2013/11/03/openssh-introduces-curve25519-sha256libssh-org-key-exchange/ default key exchange algorithm] (which is different from key ''signature'') in OpenSSH.<br />
<br />
Ed25519 key pairs can be generated with:<br />
<br />
$ ssh-keygen -t ed25519<br />
<br />
There is no need to set the key size, as all Ed25519 keys are 256 bits.<br />
<br />
Keep in mind that older SSH clients and servers may not support these keys.<br />
<br />
==== FIDO/U2F ====<br />
<br />
FIDO/[[U2F]] [[Wikipedia:Security Tokens|hardware authenticator]] support was added in [https://www.openssh.com/txt/release-8.2 OpenSSH version 8.2] for both of the elliptic curve signature schemes mentioned above. It allows for a hardware token attached via USB or other means to act a second factor alongside the private key. <br />
<br />
{{Note|Both the client and server must support the {{ic|ed25519-sk}} and {{ic|ecdsa-sk}} key types.}}<br />
<br />
The {{Pkg|libfido2}} is required for hardware token support.<br />
<br />
{{Note|OpenSSH uses a middleware library to communicate with the hardware token and comes with an internal middleware which supports USB tokens. Other middleware may be specified by the {{man|5|sshd_config|SecurityKeyProvider}} directive or the {{ic|SSH_SK_PROVIDER}} environment variable for {{ic|ssh-keygen}} and {{ic|ssh-add}}.}}<br />
<br />
After attaching a compatible FIDO key, a key pair may be generated with:<br />
<br />
$ ssh-keygen -t ed25519-sk<br />
<br />
You will usually be required to enter your PIN and/or tap your token to confirm the generation. Connecting to a server will usually require tapping your token unless the {{ic|-O no-touch-required}} command line option is used during generation and the {{man|8|sshd|no-touch-required}} {{ic|authorized_keys}} option is set on the server.<br />
<br />
{{Note|Not all hardware tokens support this option. If you are using a YubiKey, firmware version 5.2.3 is needed for the ed25519-sk key type.<ref>https://www.yubico.com/blog/whats-new-in-yubikey-firmware-5-2-3/</ref>}}<br />
<br />
An ECDSA-based keypair may also be generated with the {{ic|ecdsa-sk}} keytype, but the relevant concerns in the [[#ECDSA]] section above still apply.<br />
<br />
$ ssh-keygen -t ecdsa-sk<br />
<br />
=== Choosing the key location and passphrase ===<br />
<br />
Upon issuing the {{ic|ssh-keygen}} command, you will be prompted for the desired name and location of your private key. By default, keys are stored in the {{ic|~/.ssh/}} directory and named according to the type of encryption used. You are advised to accept the default name and location in order for later code examples in this article to work properly.<br />
<br />
When prompted for a passphrase, choose something that will be hard to guess if you have the security of your private key in mind. A longer, more random password will generally be stronger and harder to crack should it fall into the wrong hands.<br />
<br />
It is also possible to create your private key without a passphrase. While this can be convenient, you need to be aware of the associated risks. Without a passphrase, your private key will be stored on disk in an unencrypted form. Anyone who gains access to your private key file will then be able to assume your identity on any SSH server to which you connect using key-based authentication. Furthermore, without a passphrase, you must also trust the root user, as he can bypass file permissions and will be able to access your unencrypted private key file at any time.<br />
<br />
{{Note|Previously, the private key password was encoded in an insecure way: only a single round of an MD5 hash. OpenSSH 6.5 and later support a new, more secure format to encode your private key. This format is the default since [https://www.openssh.com/txt/release-7.8 OpenSSH version 7.8]. Ed25519 keys have always used the new encoding format. To upgrade to the new format, simply change the key's passphrase, as described in the next section.}}<br />
<br />
==== Changing the private key's passphrase without changing the key ====<br />
<br />
If the originally chosen SSH key passphrase is undesirable or must be changed, one can use the {{ic|ssh-keygen}} command to change the passphrase without changing the actual key. This can also be used to change the password encoding format to the new standard.<br />
<br />
$ ssh-keygen -f ~/.ssh/id_rsa -p<br />
<br />
==== Managing multiple keys ====<br />
<br />
If you have multiple SSH identities, you can set different keys to be used for different hosts or remote users by using the {{ic|Match}} and {{ic|IdentityFile}} directives in your configuration:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host=SERVER1<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_rsa_IDENTITY1<br />
<br />
Match host=SERVER2,SERVER3<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_ed25519_IDENTITY2<br />
}}<br />
<br />
See {{man|5|ssh_config}} for full description of these options.<br />
<br />
==== Storing SSH keys on hardware tokens ====<br />
<br />
{{Expansion|[https://www.openssh.com/txt/release-8.2 OpenSSH version 8.2] adds support for FIDO2 resident keys, allowing SSH Keys to be stored on the hardware token.}}<br />
<br />
SSH keys can also be stored on a security token like a smart card or a USB token. This has the advantage that the private key is stored securely on the token instead of being stored on disk. When using a security token the sensitive private key is also never present in the RAM of the PC; the cryptographic operations are performed on the token itself. A cryptographic token has the additional advantage that it is not bound to a single computer; it can easily be removed from the computer and carried around to be used on other computers.<br />
<br />
Examples are hardware tokens are described in:<br />
<br />
* [[YubiKey#SSH notes]] Native OpenSSH support for FIDO/U2F keys<br />
* [[YubiKey#SSH keys]]<br />
* [[Trusted Platform Module#Securing SSH keys]]<br />
<br />
== Copying the public key to the remote server ==<br />
<br />
{{Expansion|How to do this if you [[OpenSSH#Force public key authentication|force public key authentication]]?}}<br />
<br />
Once you have generated a key pair, you will need to copy the public key to the remote server so that it will use SSH key authentication. The public key file shares the same name as the private key except that it is appended with a {{ic|.pub}} extension. Note that the private key is not shared and remains on the local machine.<br />
<br />
=== Simple method ===<br />
<br />
{{Note|1=This method might fail if the remote server uses a non-{{ic|sh}} shell such as {{ic|tcsh}} as default and uses OpenSSH older than 6.6.1p1. See [https://bugzilla.redhat.com/show_bug.cgi?id=1045191 this bug report].}}<br />
<br />
If your key file is {{ic|~/.ssh/id_rsa.pub}} you can simply enter the following command.<br />
<br />
$ ssh-copy-id remote-server.org<br />
<br />
If your username differs on remote machine, be sure to prepend the username followed by {{ic|@}} to the server name.<br />
<br />
$ ssh-copy-id username@remote-server.org<br />
<br />
If your public key filename is anything other than the default of {{ic|~/.ssh/id_rsa.pub}} you will get an error stating {{ic|/usr/bin/ssh-copy-id: ERROR: No identities found}}. In this case, you must explicitly provide the location of the public key.<br />
<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub username@remote-server.org<br />
<br />
If the ssh server is listening on a port other than default of 22, be sure to include it within the host argument.<br />
<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 221 username@remote-server.org<br />
<br />
=== Manual method ===<br />
<br />
By default, for OpenSSH, the public key needs to be concatenated with {{ic|~/.ssh/authorized_keys}}. Begin by copying the public key to the remote server.<br />
<br />
$ scp ~/.ssh/id_ecdsa.pub username@remote-server.org:<br />
<br />
The above example copies the public key ({{ic|id_ecdsa.pub}}) to your home directory on the remote server via {{ic|scp}}. Do not forget to include the {{ic|:}} at the end of the server address. Also note that the name of your public key may differ from the example given.<br />
<br />
On the remote server, you will need to create the {{ic|~/.ssh}} directory if it does not yet exist and append your public key to the {{ic|authorized_keys}} file.<br />
<br />
$ ssh username@remote-server.org<br />
username@remote-server.org's password:<br />
$ mkdir ~/.ssh<br />
$ chmod 700 ~/.ssh<br />
$ cat ~/id_ecdsa.pub >> ~/.ssh/authorized_keys<br />
$ rm ~/id_ecdsa.pub<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
The last two commands remove the public key file from the server and set the permissions on the {{ic|authorized_keys}} file such that it is only readable and writable by you, the owner.<br />
<br />
== SSH agents ==<br />
<br />
If your private key is encrypted with a passphrase, this passphrase must be entered every time you attempt to connect to an SSH server using public-key authentication. Each individual invocation of {{ic|ssh}} or {{ic|scp}} will need the passphrase in order to decrypt your private key before authentication can proceed.<br />
<br />
An SSH agent is a program which caches your decrypted private keys and provides them to SSH client programs on your behalf. In this arrangement, you must only provide your passphrase once, when adding your private key to the agent's cache. This facility can be of great convenience when making frequent SSH connections.<br />
<br />
An agent is typically configured to run automatically upon login and persist for the duration of your login session. A variety of agents, front-ends, and configurations exist to achieve this effect. This section provides an overview of a number of different solutions which can be adapted to meet your specific needs.<br />
<br />
=== ssh-agent ===<br />
<br />
{{ic|ssh-agent}} is the default agent included with OpenSSH. It can be used directly or serve as the back-end to a few of the front-end solutions mentioned later in this section. When {{ic|ssh-agent}} is run, it forks to background and prints necessary environment variables. E.g.<br />
<br />
{{hc|$ ssh-agent|2=<br />
SSH_AUTH_SOCK=/tmp/ssh-vEGjCM2147/agent.2147; export SSH_AUTH_SOCK;<br />
SSH_AGENT_PID=2148; export SSH_AGENT_PID;<br />
echo Agent pid 2148;<br />
}}<br />
<br />
To make use of these variables, run the command through the {{ic|eval}} command.<br />
<br />
{{hc|$ eval $(ssh-agent)|<br />
Agent pid 2157<br />
}}<br />
<br />
Once {{ic|ssh-agent}} is running, you will need to add your private key to its cache:<br />
<br />
{{hc|$ ssh-add ~/.ssh/id_ed25519|<br />
Enter passphrase for /home/user/.ssh/id_ed25519:<br />
Identity added: /home/user/.ssh/id_ed25519 (/home/user/.ssh/id_ed25519)<br />
}}<br />
<br />
If your private key is encrypted, {{ic|ssh-add}} will prompt you to enter your passphrase. Once your private key has been successfully added to the agent you will be able to make SSH connections without having to enter your passphrase.<br />
<br />
{{Tip|To make all {{ic|ssh}} clients, including {{ic|git}} store keys in the agent on first use, add the configuration setting {{ic|AddKeysToAgent yes}} to {{ic|~/.ssh/config}}. Other possible values are {{ic|confirm}}, {{ic|ask}} and {{ic|no}} (default).}}<br />
<br />
In order to start the agent automatically and make sure that only one {{ic|ssh-agent}} process runs at a time, add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
if ! pgrep -u "$USER" ssh-agent > /dev/null; then<br />
ssh-agent -t 1h > "$XDG_RUNTIME_DIR/ssh-agent.env"<br />
fi<br />
if [[ ! "$SSH_AUTH_SOCK" ]]; then<br />
source "$XDG_RUNTIME_DIR/ssh-agent.env" >/dev/null<br />
fi<br />
</nowiki>}}<br />
<br />
This will run a {{ic|ssh-agent}} process if there is not one already, and save the output thereof. If there is one running already, we retrieve the cached {{ic|ssh-agent}} output and evaluate it which will set the necessary environment variables. The lifetime of the unlocked keys is set to 1 hour.<br />
<br />
There also exist a number of front-ends to {{ic|ssh-agent}} and alternative agents described later in this section which avoid this problem.<br />
<br />
==== Start ssh-agent with systemd user ====<br />
<br />
It is possible to use the [[systemd/User]] facilities to start the agent. Use this if you would like your ssh agent to run when you are logged in, regardless of whether x is running.<br />
<br />
{{hc|~/.config/systemd/user/ssh-agent.service|2=<br />
[Unit]<br />
Description=SSH key agent<br />
<br />
[Service]<br />
Type=simple<br />
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket<br />
# DISPLAY required for ssh-askpass to work<br />
Environment=DISPLAY=:0<br />
ExecStart=/usr/bin/ssh-agent -D -a $SSH_AUTH_SOCK<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
Then ''export'' the [[environment variable]] {{ic|1=SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"}} in your [[login shell]] initialization file, such as {{ic|~/.bash_profile}} or {{ic|~/.zprofile}}, or in {{ic|~/.pam_environment}}.<br />
<br />
Finally, [[enable]] or [[start]] the service with the {{ic|--user}} flag.<br />
<br />
{{Note|<br />
* If you use GNOME, this environment variable is overridden by default. See [[GNOME/Keyring#Disable keyring daemon components]].<br />
* Make sure to not overwrite an existing {{ic|SSH_AUTH_SOCK}} if you want to be able to use a [[OpenSSH#Agent forwarding|forwarded ssh agent]].<br />
}}<br />
<br />
{{Tip|When starting the agent via systemd as described above, it is possible to automatically enter the passphrase of your default key and add it to the agent. See [https://github.com/capocasa/systemd-user-pam-ssh systemd-user-pam-ssh] for details.}}<br />
<br />
==== ssh-agent as a wrapper program ====<br />
<br />
An alternative way to start ssh-agent (with, say, each X session) is described in [https://upc.lbl.gov/docs/user/sshagent.shtml this ssh-agent tutorial by UC Berkeley Labs]. A basic use case is if you normally begin X with the {{ic|startx}} command, you can instead prefix it with {{ic|ssh-agent}} like so:<br />
<br />
$ ssh-agent startx<br />
<br />
And so you do not even need to think about it you can put an alias in your {{ic|.bash_aliases}} file or equivalent:<br />
<br />
alias startx='ssh-agent startx'<br />
<br />
Doing it this way avoids the problem of having extraneous {{ic|ssh-agent}} instances floating around between login sessions. Exactly one instance will live and die with the entire X session.<br />
<br />
{{Note|As an alternative to calling {{ic|ssh-agent startx}}, you can add {{ic|eval $(ssh-agent)}} to {{ic|~/.xinitrc}}.}}<br />
<br />
See [[#Calling x11-ssh-askpass with ssh-add|the below notes on using x11-ssh-askpass with ssh-add]] for an idea on how to immediately add your key to the agent.<br />
<br />
=== GnuPG Agent ===<br />
<br />
The [[gpg-agent]] has OpenSSH Agent protocol emulation. See [[GnuPG#SSH agent]] for necessary configuration.<br />
<br />
=== Keychain ===<br />
<br />
[[Funtoo:Keychain|Keychain]] is a program designed to help you easily manage your SSH keys with minimal user interaction. It is implemented as a shell script which drives both ''ssh-agent'' and ''ssh-add''. A notable feature of Keychain is that it can maintain a single ''ssh-agent'' process across multiple login sessions. This means that you only need to enter your passphrase once each time your local machine is booted.<br />
<br />
==== Installation ====<br />
<br />
[[Install]] the {{Pkg|keychain}} package.<br />
<br />
==== Configuration ====<br />
<br />
{{Warning|As of 2015-09-26, the {{ic|-Q, --quick}} option has the unexpected side-effect of making ''keychain'' switch to a newly-spawned ''ssh-agent'' upon relogin (at least on systems using [[GNOME]]), forcing you to re-add all the previously registered keys.}}<br />
<br />
Add a line similar to the following to your [[shell]] configuration file, ''e.g.'' if using [[Bash]]:<br />
<br />
{{hc|~/.bashrc|<br />
eval $(keychain --eval --quiet id_ed25519 id_rsa ~/.keys/my_custom_key)<br />
}}<br />
<br />
{{Note|{{ic|~/.bashrc}} is used instead of the upstream suggested {{ic|~/.bash_profile}} because on Arch it is sourced by both login and non-login shells, making it suitable for textual and graphical environments alike. See [[Bash#Invocation]] for more information on the difference between those.}}<br />
<br />
In the above example,<br />
* the {{ic|--eval}} switch outputs lines to be evaluated by the opening {{ic|eval}} command; this sets the necessary environment variables for an SSH client to be able to find your agent.<br />
* {{ic|--quiet}} will limit output to warnings, errors, and user prompts.<br />
<br />
Multiple keys can be specified on the command line, as shown in the example. By default keychain will look for key pairs in the {{ic|~/.ssh/}} directory, but absolute path can be used for keys in non-standard location. You may also use the {{ic|--confhost}} option to inform keychain to look in {{ic|~/.ssh/config}} for {{ic|IdentityFile}} settings defined for particular hosts, and use these paths to locate keys.<br />
<br />
See {{ic|keychain --help}} or {{man|1|keychain}} for details on setting ''keychain'' for other shells.<br />
<br />
To test Keychain, simply open a new terminal emulator or log out and back in your session. It should prompt you for the passphrase of the specified private key(s) (if applicable), either using the program set in {{ic|$SSH_ASKPASS}} or on the terminal.<br />
<br />
Because Keychain reuses the same ''ssh-agent'' process on successive logins, you should not have to enter your passphrase the next time you log in or open a new terminal. You will only be prompted for your passphrase once each time the machine is rebooted.<br />
<br />
==== Tips ====<br />
<br />
* ''keychain'' expects public key files to exist in the same directory as their private counterparts, with a {{ic|.pub}} extension. If the private key is a symlink, the public key can be found alongside the symlink or in the same directory as the symlink target (this capability requires the {{ic|readlink}} command to be available on the system).<br />
<br />
*to disable the graphical prompt and always enter your passphrase on the terminal, use the {{ic|--nogui}} option. This allows to copy-paste long passphrases from a password manager for example.<br />
<br />
*if you do not want to be immediately prompted for unlocking the keys but rather wait until they are needed, use the {{ic|--noask}} option.<br />
<br />
{{Note|Keychain is able to manage [[GPG]] keys in the same fashion. By default it attempts to start ''ssh-agent'' only, but you can modify this behavior using the {{ic|--agents}} option, ''e.g.'' {{ic|--agents ssh,gpg}}. See {{man|1|keychain}}.}}<br />
<br />
=== x11-ssh-askpass ===<br />
<br />
The {{pkg|x11-ssh-askpass}} package provides a graphical dialog for entering your passhrase when running an X session. ''x11-ssh-askpass'' depends only on the {{Pkg|libx11}} and {{Pkg|libxt}} libraries, and the appearance of ''x11-ssh-askpass'' is customizable. While it can be invoked by the ''ssh-add'' program, which will then load your decrypted keys into [[#ssh-agent|ssh-agent]], the following instructions will, instead, configure ''x11-ssh-askpass'' to be invoked by the aforementioned [[#Keychain|Keychain]] script.<br />
<br />
Install the {{Pkg|keychain}} and {{Pkg|x11-ssh-askpass}} packages.<br />
<br />
Edit your {{ic|~/.xinitrc}} file to include the following lines, replacing the name and location of your private key if necessary. Be sure to place these commands '''before''' the line which invokes your window manager.<br />
<br />
{{hc|~/.xinitrc|<br />
keychain ~/.ssh/id_ecdsa<br />
[ -f ~/.keychain/$HOSTNAME-sh ] && . ~/.keychain/$HOSTNAME-sh 2>/dev/null<br />
[ -f ~/.keychain/$HOSTNAME-sh-gpg ] && . ~/.keychain/$HOSTNAME-sh-gpg 2>/dev/null<br />
...<br />
exec openbox-session}}<br />
<br />
In the above example, the first line invokes ''keychain'' and passes the name and location of your private key. If this is not the first time ''keychain'' was invoked, the following two lines load the contents of {{ic|$HOSTNAME-sh}} and {{ic|$HOSTNAME-sh-gpg}}, if they exist. These files store the environment variables of the previous instance of ''keychain''.<br />
<br />
==== Calling x11-ssh-askpass with ssh-add ====<br />
<br />
The ''ssh-add'' manual page specifies that, in addition to needing the {{ic|DISPLAY}} variable defined, you also need {{ic|SSH_ASKPASS}} set to the name of your askpass program (in this case ''x11-ssh-askpass''). It bears keeping in mind that the default Arch Linux installation places the ''x11-ssh-askpass'' binary in {{ic|/usr/lib/ssh/}}, which will not be in most people's {{ic|PATH}}. This is a little annoying, not only when declaring the {{ic|SSH_ASKPASS}} variable, but also when theming. You have to specify the full path everywhere. Both inconveniences can be solved simultaneously by symlinking:<br />
<br />
$ ln -sv /usr/lib/ssh/x11-ssh-askpass ~/bin/ssh-askpass<br />
<br />
This is assuming that {{ic|~/bin}} is in your {{ic|PATH}}. So now in your {{ic|.xinitrc}}, before calling your window manager, one just needs to export the {{ic|SSH_ASKPASS}} environment variable:<br />
<br />
$ export SSH_ASKPASS=ssh-askpass<br />
<br />
and your [[X resources]] will contain something like:<br />
<br />
ssh-askpass*background: #000000<br />
<br />
Doing it this way works well with [[#ssh-agent as a wrapper program|the above method on using ''ssh-agent'' as a wrapper program]]. You start X with {{ic|ssh-agent startx}} and then add ''ssh-add'' to your window manager's list of start-up programs.<br />
<br />
==== Theming ====<br />
<br />
The appearance of the ''x11-ssh-askpass'' dialog can be customized by setting its associated [[X resources]]. Some examples are the .ad files at https://github.com/sigmavirus24/x11-ssh-askpass. See {{man|1|x11-ssh-askpass}} for full details.<br />
<br />
==== Alternative passphrase dialogs ====<br />
<br />
There are other passphrase dialog programs which can be used instead of ''x11-ssh-askpass''. The following list provides some alternative solutions.<br />
<br />
* {{Pkg|ksshaskpass}} uses the [[KDE Wallet]].<br />
* {{Pkg|openssh-askpass}} uses the [[Qt]] library.<br />
* {{Pkg|lxqt-openssh-askpass}}<br />
<br />
=== pam_ssh ===<br />
<br />
The [http://pam-ssh.sourceforge.net/ pam_ssh] project exists to provide a [[Pluggable Authentication Module]] (PAM) for SSH private keys. This module can provide single sign-on behavior for your SSH connections. On login, your SSH private key passphrase can be entered in place of, or in addition to, your traditional system password. Once you have been authenticated, the pam_ssh module spawns ssh-agent to store your decrypted private key for the duration of the session.<br />
<br />
To enable single sign-on behavior at the tty login prompt, install the unofficial {{AUR|pam_ssh}} package. <br />
<br />
{{Note|pam_ssh 2.0 now requires that all private keys used in the authentication process be located under {{ic|~/.ssh/login-keys.d/}}.}}<br />
<br />
Create a symlink to your private key file and place it in {{ic|~/.ssh/login-keys.d/}}. Replace the {{ic|id_rsa}} in the example below with the name of your own private key file.<br />
<br />
$ mkdir ~/.ssh/login-keys.d/<br />
$ cd ~/.ssh/login-keys.d/<br />
$ ln -s ../id_rsa<br />
<br />
Edit the {{ic|/etc/pam.d/login}} configuration file to include the text highlighted in bold in the example below. The order in which these lines appear is significiant and can affect login behavior.<br />
<br />
{{Warning|Misconfiguring PAM can leave the system in a state where all users become locked out. Before making any changes, you should have an understanding of how PAM configuration works as well as a backup means of accessing the PAM configuration files, such as an Arch Live CD, in case you become locked out and need to revert any changes. An IBM developerWorks [https://developer.ibm.com/tutorials/l-pam/ article] is available which explains PAM configuration in further detail.}}<br />
<br />
{{hc|/etc/pam.d/login|2=<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
'''auth optional pam_ssh.so try_first_pass'''<br />
account include system-local-login<br />
session include system-local-login<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
In the above example, login authentication initially proceeds as it normally would, with the user being prompted to enter his user password. The additional {{ic|auth}} authentication rule added to the end of the authentication stack then instructs the pam_ssh module to try to decrypt any private keys found in the {{ic|~/.ssh/login-keys.d}} directory. The {{ic|try_first_pass}} option is passed to the pam_ssh module, instructing it to first try to decrypt any SSH private keys using the previously entered user password. If the user's private key passphrase and user password are the same, this should succeed and the user will not be prompted to enter the same password twice. In the case where the user's private key passphrase user password differ, the pam_ssh module will prompt the user to enter the SSH passphrase after the user password has been entered. The {{ic|optional}} control value ensures that users without an SSH private key are still able to log in. In this way, the use of pam_ssh will be transparent to users without an SSH private key.<br />
<br />
If you use another means of logging in, such as an X11 display manager like [[SLiM]] or [[XDM]] and you would like it to provide similar functionality, you must edit its associated PAM configuration file in a similar fashion. Packages providing support for PAM typically place a default configuration file in the {{ic|/etc/pam.d/}} directory.<br />
<br />
Further details on how to use pam_ssh and a list of its options can be found in the {{man|8|pam_ssh|url=}} man page.<br />
<br />
==== Using a different password to unlock the SSH key ====<br />
<br />
If you want to unlock the SSH keys or not depending on whether you use your key's passphrase or the (different!) login password, you can modify {{ic|/etc/pam.d/system-auth}} to<br />
<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth [success=1 new_authtok_reqd=1 ignore=ignore default=ignore] pam_unix.so try_first_pass nullok'''<br />
'''auth required pam_ssh.so use_first_pass'''<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
session optional pam_permit.so<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
For an explanation, see [https://unix.stackexchange.com/a/239486].<br />
<br />
==== Known issues with pam_ssh ====<br />
<br />
Work on the pam_ssh project is infrequent and the documentation provided is sparse. You should be aware of some of its limitations which are not mentioned in the package itself.<br />
<br />
* Versions of pam_ssh prior to version 2.0 do not support SSH keys employing the newer option of ECDSA (elliptic curve) cryptography. If you are using earlier versions of pam_ssh you must use either RSA or DSA keys.<br />
<br />
* The {{ic|ssh-agent}} process spawned by pam_ssh does not persist between user logins. If you like to keep a [[GNU Screen]] session active between logins you may notice when reattaching to your screen session that it can no longer communicate with ssh-agent. This is because the GNU Screen environment and those of its children will still reference the instance of ssh-agent which existed when GNU Screen was invoked but was subsequently killed in a previous logout. The [[#Keychain|Keychain]] front-end avoids this problem by keeping the ssh-agent process alive between logins.<br />
<br />
=== pam_exec-ssh ===<br />
<br />
As an alternative to [[#pam_ssh|pam_ssh]] you can use {{AUR|pam_exec-ssh}}. It is a shell script that uses pam_exec. Help for configuration can be found [https://github.com/x70b1/pam_exec-ssh upstream].<br />
<br />
=== GNOME Keyring ===<br />
<br />
If you use the [[GNOME]] desktop, the [[GNOME Keyring]] tool can be used as an SSH agent. See the [[GNOME Keyring]] article for further details.<br />
<br />
=== Store SSH keys with Kwallet ===<br />
<br />
For instructions on how to use kwallet to store your SSH keys, see [[KDE Wallet#Using the KDE Wallet to store ssh key passphrases]].<br />
<br />
=== KeePass2 with KeeAgent plugin ===<br />
<br />
[https://lechnology.com/software/keeagent/ KeeAgent] is a plugin for [[KeePass]] that allows SSH keys stored in a KeePass database to be used for SSH authentication by other programs.<br />
<br />
* Supports both PuTTY and OpenSSH private key formats.<br />
* Works with native SSH agent on Linux/Mac and with PuTTY on Windows.<br />
<br />
See [[KeePass#Plugin installation in KeePass]] or [[install]] the {{Pkg|keepass-plugin-keeagent}} package.<br />
<br />
This agent can be used directly, by matching KeeAgent socket: {{ic|KeePass -> Tools -> Options -> KeeAgent -> Agent mode socket file -> %XDG_RUNTIME_DIR%/keeagent.socket}}-<br />
and environment variable:<br />
{{ic|1=export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR"'/keeagent.socket'}}.<br />
<br />
=== KeePassXC ===<br />
<br />
The KeePassXC fork of KeePass [https://keepassxc.org/docs/#faq-ssh-agent-how supports being used as an SSH agent by default]. It is also compatible with KeeAgent's database format.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Key ignored by the server ===<br />
<br />
* If it appears that the SSH server is ignoring your keys, ensure that you have the proper permissions set on all relevant files.<br />
:For the local machine:<br />
<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/''key''<br />
<br />
:For the remote machine:<br />
<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
: For the remote machine, also check that the target user's home directory has the correct permissions (it must ''not'' be writable by the group and others):<br />
<br />
$ chmod go-w /home/''target_user''<br />
<br />
* If that does not solve the problem you may try temporarily setting {{ic|StrictModes}} to {{ic|no}} in {{ic|/etc/ssh/sshd_config}}. If authentication with {{ic|StrictModes off}} is successful, it is likely an issue with file permissions persists.<br />
<br />
* Make sure keys in {{ic|~/.ssh/authorized_keys}} are entered correctly and only use one single line.<br />
* Make sure the remote machine supports the type of keys you are using: some servers do not support ECDSA keys, try using RSA or DSA keys instead, see [[#Generating an SSH key pair]].<br />
* You may want to use debug mode and monitor the output while connecting:<br />
<br />
# /usr/bin/sshd -d<br />
<br />
* If you gave another name to your key, for example {{ic|id_rsa_server}}, you need to connect with the {{ic|-i}} option:<br />
<br />
$ ssh -i id_rsa_server user@server<br />
<br />
== See also ==<br />
<br />
* OpenSSH key management: [[Funtoo:OpenSSH Key Management, Part 1|Part 1]], [[Funtoo:OpenSSH Key Management, Part 2|Part 2]], [[Funtoo:OpenSSH Key Management, Part 3|Part 3]]<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Simon04https://wiki.archlinux.org/index.php?title=Nextcloud&diff=700772Nextcloud2021-11-04T21:28:24Z<p>Simon04: /* Synchronization */ section hierarchy</p>
<hr />
<div>[[Category:File sharing]]<br />
[[Category:Web applications]]<br />
[[ja:Nextcloud]]<br />
[[zh-hans:Nextcloud]]<br />
{{Related articles start}}<br />
{{Related|Apache HTTP Server}}<br />
{{Related|Nginx}}<br />
{{Related|OpenSSL}}<br />
{{Related|WebDAV}}<br />
{{Related articles end}}<br />
<br />
From [[Wikipedia:Nextcloud]]:<br />
<br />
:Nextcloud is a suite of client-server software for creating and using file hosting services. It is functionally similar to Dropbox, although Nextcloud is free and open-source, allowing anyone to install and operate it on a private server. In contrast to proprietary services like Dropbox, the open architecture allows adding additional functionality to the server in form of applications.<br />
<br />
Nextcloud is a fork of ownCloud. For differences between the two, see [[Wikipedia:Nextcloud#Differences from ownCloud]].<br />
<br />
== Prerequisites ==<br />
<br />
Nextcloud requires several components:[https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server]<br />
<br />
* A web server: [[Apache HTTP Server]] or [[nginx]]<br />
* A database: [[MariaDB]]/MySQL, [[PostgreSQL]], [[SQLite]] or [[Oracle Database]]<br />
* [[PHP]] with [[#PHP setup|additional modules]]<br />
<br />
These will be configured in [[#PHP setup]].<br />
<br />
Make sure the required components are installed before proceeding.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|nextcloud}} package.<br />
<br />
== Configuration ==<br />
<br />
The web application is configured in {{ic|/etc/webapps/nextcloud/config/config.php}}.<br />
<br />
{{Note|Nextcloud should store user data in {{ic|/var/lib/nextcloud/data/}}, as that directory is only accessible by root and the application itself. For the installation of apps using the web application {{ic|/var/lib/nextcloud/apps/}} should be used.}}<br />
<br />
=== Data directory ===<br />
<br />
By default nextcloud stores its user data in {{ic|/var/lib/nextcloud/data/}}. This location is configurable:<br />
<br />
{{hc|/etc/webapps/nextcloud/config/config.php|2=<br />
$CONFIG = [<br />
/* [..] */<br />
'datadirectory' => '/var/lib/nextcloud/data',<br />
/* [..] */<br />
]<br />
}}<br />
<br />
{{Note| The {{ic|datadirectory}} needs to be writable by the {{ic|nextcloud}} user.}}<br />
<br />
=== Writable apps directory ===<br />
<br />
The default apps location in {{ic|/usr/share/webapps/nextcloud/apps/}} is not writable to the {{ic|nextcloud}} user, as it is part of the package.<br />
<br />
To be able to install apps from the app store, it is possible to use a separate, writable apps directory. This defaults to {{ic|/var/lib/nextcloud/apps/}} and is accessible via a symlink ({{ic|/usr/share/webapps/nextcloud/wapps}}) in the web application's root directory.<br />
<br />
The directories are configurable:<br />
<br />
{{hc|/etc/webapps/nextcloud/config/config.php|2=<br />
$CONFIG = [<br />
/* [..] */<br />
'apps_paths' => [<br />
[<br />
'path'=> '/usr/share/webapps/nextcloud/apps',<br />
'url' => '/apps',<br />
'writable' => false,<br />
],<br />
[<br />
'path'=> '/var/lib/nextcloud/apps',<br />
'url' => '/wapps',<br />
'writable' => true,<br />
],<br />
],<br />
/* [..] */<br />
]<br />
}}<br />
<br />
{{Note|<br />
* The {{ic|apps_paths}} entry declared as {{ic|writable}} needs to be writable by the {{ic|nextcloud}} user. Additionally a symlink to that directory needs to be created in {{ic|/usr/share/webapps/nextcloud/}}.<br />
* The above syntax uses php's [https://wiki.php.net/rfc/short_list_syntax short array syntax]. The same could be written in the syntax most guides use: <br />
{{hc|/etc/webapps/nextcloud/config/config.php|2=<br />
$CONFIG = (<br />
/* [..] */<br />
'apps_paths' => array (<br />
0 => array (<br />
'path' => '/usr/share/webapps/nextcloud/apps',<br />
'url' => '/apps',<br />
'writable' => false,<br />
),<br />
1 => array (<br />
'path' => '/var/lib/nextcloud/apps',<br />
'url' => '/wapps',<br />
'writable' => true,<br />
),<br />
),<br />
/* [..] */<br />
)<br />
}}<br />
}}<br />
<br />
=== Log directory ===<br />
<br />
By default logs are created in {{ic|/var/log/nextcloud/nextcloud.log}}. This location is configurable:<br />
<br />
{{hc|/etc/webapps/nextcloud/config/config.php|2=<br />
$CONFIG = [<br />
/* [..] */<br />
'logfile' => '/var/log/nextcloud/nextcloud.log',<br />
]<br />
/* [..] */<br />
}}<br />
<br />
=== Database setup ===<br />
<br />
An SQL database must be set up and used for your Nextcloud installation. After setting up the database here,<br />
you will be prompted for its information when you first create an administrator account.<br />
<br />
==== MariaDB ====<br />
<br />
{{Note|Create or convert the database with MySQL 4-byte support in order to use Emojis (textbased smilies) on your Nextcloud server [https://docs.nextcloud.com/server/latest/admin_manual/configuration_database/mysql_4byte_support.html].}}<br />
<br />
If you want to use Emojis, replace the following CREATE DATABASE... with:<br />
{{bc|mysql> CREATE DATABASE '''nextcloud''' DEFAULT CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_general_ci';}}<br />
<br />
It is recommended to set up an own database and user when using [[MariaDB]]:<br />
<br />
{{hc|$ mysql -u root -p|2=<br />
mysql> CREATE DATABASE '''nextcloud''' DEFAULT CHARACTER SET 'utf8' COLLATE 'utf8_unicode_ci';<br />
mysql> GRANT ALL PRIVILEGES ON '''nextcloud'''.* TO ''''nextcloud''''@'localhost' IDENTIFIED BY ''''password'''';<br />
mysql> FLUSH PRIVILEGES;<br />
mysql> \q<br />
}}<br />
<br />
==== PostgreSQL ====<br />
<br />
The following is an example of setting up a [[PostgreSQL]] user and database:<br />
<br />
{{hc|1=[postgres]$ createuser -h localhost -P nextcloud|2=<br />
Enter password for new role:<br />
Enter it again:<br />
}}<br />
<br />
[postgres]$ createdb -O nextcloud nextcloud<br />
<br />
=== PHP setup ===<br />
<br />
{{Tip|For all prerequisite PHP modules, see [https://docs.nextcloud.com/server/latest/admin_manual/installation/source_installation.html#prerequisites-label upstream documentation].}}<br />
<br />
Make sure that {{ic|session.save_path}} is configured. Install [[PHP#gd]] and {{pkg|php-intl}} as additional modules. Configure [[PHP#OPCache|OPcache]] as recommended by [https://docs.nextcloud.com/server/latest/admin_manual/installation/server_tuning.html#enable-php-opcache the documentation].<br />
<br />
Some apps (e.g. ''News'') require the {{ic|iconv}} extension. If you wish to use these apps, uncomment the extension in {{ic|/etc/php/php.ini}}.<br />
<br />
Depending on which database backend will be used:<br />
<br />
* For [[MySQL]], see [[PHP#MySQL/MariaDB]].<br />
* For [[PostgreSQL]], see [[PHP#PostgreSQL]].<br />
* For [[SQLite]], see [[PHP#Sqlite]].<br />
<br />
Performance may be improved through the implementation of [[PHP#Caching|caching]], see [https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/caching_configuration.html Configuring Memory Caching] on the official documentation for details.<br />
<br />
=== Nextcloud setup ===<br />
<br />
{{ic|occ}} is a command-line tool that can be used to control Nextcloud. It is located in {{ic|/usr/share/webapps/nextcloud/occ}} and should be run as the {{ic|nextcloud user}}. A wrapper is provided in {{ic|/usr/bin/occ}} which will run the command using [[sudo]].<br />
<br />
To set up Nextcloud, you can use the {{ic|$ occ maintenance:install}} command. See [https://docs.nextcloud.com/server/stable/admin_manual/configuration_server/occ_command.html#command-line-installation-label Nextcloud documentation] for more details. For example, to set up Nextcloud with [[PostgreSQL]]:<br />
<br />
$ occ maintenance:install --database pgsql --database-name nextcloud --database-host localhost --database-user nextcloud --database-pass=<password> --data-dir /var/lib/nextcloud/data/<br />
<br />
Alternatively, [[#Web server setup|set up Nextcloud on a web server]], then navigate to your Nextcloud instance in a web browser to access an installation wizard. Enter your database details and the location of the [[#Data directory|data directory]].<br />
<br />
=== Configure caching ===<br />
<br />
It is recommended to [https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/caching_configuration.html enable caching]. The Nextcloud documentation provides instructions on [[Redis]], Memcached and [[PHP#APCu|APCu]].<br />
<br />
=== Install notify_push ===<br />
<br />
To lower the impact of desktop and web clients on your server (polling for file activity and other notifications), you may want to install the [https://apps.nextcloud.com/apps/notify_push notify_push app]. You can do so via the web interface or with {{AUR|nextcloud-app-notify_push}}. More information can be found on the initial [https://nextcloud.com/blog/nextcloud-faster-than-ever-introducing-files-high-performance-back-end/ blog post].<br />
<br />
== Hosting ==<br />
<br />
{{Note| Nextcloud needs to be run as its own user and group (i.e. {{ic|nextcloud}}). It is using {{ic|/etc/webapps/nextcloud/}}, {{ic|/var/lib/nextcloud/}}, {{ic|/var/log/nextcloud/}} and {{ic|/run/nextcloud/}} for configurations, state data (data and apps from the app store), logs and (potentially) sockets (respectively)!}}<br />
<br />
As stated above, in order to set up Nextcloud, you must set up the appropriate PHP requirements;<br />
additionally, you must configure a database and a webserver.<br />
<br />
=== Web server setup ===<br />
<br />
{{Warning|It is recommended to use HTTPS instead of plain HTTP, see [[Apache HTTP Server#TLS]] or [[Nginx#TLS]] for examples and implement this in the examples given below.}}<br />
<br />
Depending on which [[web server]] you are using, further setup is required, indicated below.<br />
<br />
==== Apache ====<br />
<br />
If you have not already, install [[Apache HTTP Server]] and install and enable [[Apache HTTP Server#PHP|Apache's PHP module]]<br />
<br />
Copy the Apache configuration file to the configuration directory:<br />
<br />
# cp /usr/share/doc/nextcloud/apache.example.conf /etc/httpd/conf/extra/nextcloud.conf<br />
<br />
Modify the file according to your preferences. By default it includes an alias for {{ic|/nextcloud}} pointing to {{ic|/usr/share/webapps/nextcloud}}.<br />
<br />
And include it in {{ic|/etc/httpd/conf/httpd.conf}}:<br />
<br />
Include conf/extra/nextcloud.conf<br />
<br />
Ensure that the root location of your Nextcloud installation (e.g., {{ic|/usr/share/webapps/nextcloud}}) is accessible by the webserver's user {{ic|http}}.<br />
<br />
Now restart Apache ({{ic|httpd.service}}).<br />
<br />
If nextcloud keeps reporting an internal server error depending on your setup it might be needed to allow apache to access your files using nextcloud user permission. Install {{Pkg|mod_itk}} and add this to your vhost setup: <br />
{{hc|/etc/httpd/conf/extra/nextcloud.conf|output=<nowiki><br />
<IfModule mpm_itk_module><br />
AssignUserId nextcloud nextcloud<br />
</IfModule><br />
</nowiki>}}<br />
{{hc|/etc/httpd/conf/httpd.conf|output=<nowiki><br />
LoadModule mpm_itk_module modules/mpm_itk.so<br />
</nowiki>}}<br />
<br />
{{Note|<br />
Be aware however that {{ic|mpm_itk}} is [http://mpm-itk.sesse.net/ not compatible with threading], so the Apache server cannot use {{ic|mpm_event_module}} nor {{ic|mpm_worker_module}}. You will get an error message such as `mpm-itk cannot use threaded MPMs; please use prefork`. For a discussion of pros and cons of these see [https://serverfault.com/questions/383526/how-do-i-select-which-apache-mpm-to-use this Serverfault question] (mpm_itk is derived from mpm_prefork). {{ic|mod_php}} is not compatible with threaded mpm's either, so unless you are using php-fpm you probably are already "stuck" on {{ic|mpm_prefork_module}}. However, note also that the {{ic|http2_module}} is not compatible with {{ic|mpm_prefork_module}} and hence with {{ic|mpm_itk}}…<br />
}}<br />
<br />
===== WebDAV =====<br />
<br />
Nextcloud comes with its own [[WebDAV]] implementation enabled, which may conflict with the one shipped with Apache. If you have enabled WebDAV in Apache (not enabled by default), disable the modules {{ic|mod_dav}} and {{ic|mod_dav_fs}} in {{ic|/etc/httpd/conf/httpd.conf}}. See [https://forum.owncloud.org/viewtopic.php?f=17&t=7240] for details.<br />
<br />
===== With php-fpm =====<br />
<br />
Set up [[#php-fpm]] if you want to use it as a FastCGI handler with Apache. Then set it as the request handler for PHP files:<br />
<br />
{{hc|/etc/httpd/conf/extra/php-fpm.conf|output=<nowiki><br />
DirectoryIndex index.php index.html<br />
<FilesMatch \.php$><br />
SetHandler "proxy:unix:/run/nextcloud/nextcloud.sock|fcgi://localhost/"<br />
</FilesMatch><br />
</nowiki><br />
}}<br />
<br />
Place {{ic|<FilesMatch>}} section directly in {{ic|<VirtualHost>}} if you use virtual hosts.<br />
<br />
==== php-fpm ====<br />
<br />
{{Pkg|php-fpm}} is PHP's FastCGI implementation. It can be used by web servers that support the protocol.<br />
<br />
Add an additional pool that runs as the {{ic|nextcloud}} user/group:<br />
<br />
{{hc|/etc/php/php-fpm.d/nextcloud.conf|2=<br />
[nextcloud]<br />
user = nextcloud<br />
group = nextcloud<br />
listen = /run/nextcloud/nextcloud.sock<br />
env[PATH] = /usr/local/bin:/usr/bin:/bin<br />
env[TMP] = /tmp<br />
<br />
; should be accessible by your web server<br />
listen.owner = http<br />
listen.group = http<br />
<br />
pm = dynamic<br />
pm.max_children = 15<br />
pm.start_servers = 2<br />
pm.min_spare_servers = 1<br />
pm.max_spare_servers = 3<br />
}}<br />
<br />
The php-fpm service runs with the system mounted as read-only for hardening purposes, so it is necessary to explicitly grant write permissions on the appropriate Nextcloud paths. [[Edit]] {{ic|php-fpm.service}} to create a drop-in file and save it with the following contents:<br />
<br />
{{hc|/etc/systemd/system/php-fpm.service.d/override.conf|2=<br />
[Service]<br />
# Your data directory<br />
ReadWritePaths=/var/lib/nextcloud/data<br />
<br />
# Optional: add if you've set the default apps directory to be writable in config.php<br />
ReadWritePaths=/usr/share/webapps/nextcloud/apps<br />
<br />
# Optional: unnecessary if you've set 'config_is_read_only' => true in your config.php<br />
ReadWritePaths=/usr/share/webapps/nextcloud/config<br />
ReadWritePaths=/etc/webapps/nextcloud/config<br />
<br />
# Optional: add if you want to use Nextcloud's internal update process<br />
# ReadWritePaths=/usr/share/webapps/nextcloud<br />
}}<br />
<br />
[[Enable]] and [[start]] the {{ic|php-fpm}} service.<br />
<br />
==== Nginx ====<br />
<br />
Make sure [[#php-fpm]] has been configured correctly.<br />
<br />
Create a [[Nginx#Server_blocks|server block]] and add the content according to the [https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html Nextcloud documentation].<br />
<br />
Use {{ic|unix:/run/nextcloud/nextcloud.sock}} as {{ic|server}} in the {{ic|upstream php-handler}} block and {{ic|/usr/share/webapps/nextcloud}} as {{ic|root}} location:<br />
{{hc|/etc/nginx/sites-enabled/nextcloud|2=<br />
upstream php-handler {<br />
server unix:/run/nextcloud/nextcloud.sock;<br />
}<br />
<br />
# ...<br />
<br />
server {<br />
listen 443 ssl http2;<br />
listen [::]:443 ssl http2;<br />
# ...<br />
root /usr/share/webapps/nextcloud;<br />
# ...<br />
}<br />
}}<br />
<br />
See [[nginx#FastCGI]] for more information on using FastCGI with nginx.<br />
<br />
==== lighttpd ====<br />
<br />
Enable [[lighttpd#FastCGI]], e.g. by adding {{ic|code=server.modules += ( "mod_fastcgi" )}} to {{ic|/etc/lighttpd/lighttpd.conf}}.<br />
<br />
Create a link to {{ic|/usr/share/webapps/nextcloud}} in your {{ic|/srv/http/}} directory (or configured root).<br />
<br />
== Security Hardening ==<br />
<br />
See the [https://docs.nextcloud.com/server/latest/admin_manual/installation/harden_server.html Nextcloud documentation] and [[Security]]. Nextcloud additionally provides a [https://scan.nextcloud.com/ Security scanner].<br />
<br />
=== uWSGI ===<br />
<br />
You can run Nextcloud in its own process and service by using the [[uWSGI]] application server with {{pkg|uwsgi-plugin-php}}. This allows you to define a [[PHP#Configuration|PHP configuration]] only for this instance of PHP, without the need to edit the global {{ic|php.ini}} and thus keeping your web application configurations compartmentalized. ''uWSGI'' itself has a wealth of features to limit the resource use and to harden the security of the application, and by being a separate process it can run under its own user.<br />
<br />
The only part that differs from [[#Nginx]] is the {{ic|<nowiki>location ~ \.php(?:$|/) {}</nowiki>}} block:<br />
<br />
{{bc|<nowiki><br />
location ~ \.php(?:$|/) {<br />
include uwsgi_params;<br />
uwsgi_modifier1 14;<br />
# Avoid duplicate headers confusing OC checks<br />
uwsgi_hide_header X-Frame-Options;<br />
uwsgi_hide_header X-XSS-Protection;<br />
uwsgi_hide_header X-Content-Type-Options;<br />
uwsgi_hide_header X-Robots-Tag;<br />
uwsgi_pass unix:/run/uwsgi/nextcloud.sock;<br />
}<br />
</nowiki>}}<br />
<br />
Then create a config file for ''uWSGI'':<br />
<br />
{{hc|/etc/uwsgi/nextcloud.ini|<nowiki><br />
[uwsgi]<br />
; load the required plugins<br />
plugins = php<br />
; force the sapi name to 'apache', this will enable the opcode cache <br />
php-sapi-name = apache<br />
<br />
; set master process name and socket<br />
; '%n' refers to the name of this configuration file without extension<br />
procname-master = uwsgi %n<br />
master = true<br />
socket = /run/uwsgi/%n.sock<br />
<br />
; drop privileges<br />
uid = nextcloud<br />
gid = nextcloud<br />
umask = 022<br />
<br />
; run with at least 1 process but increase up to 4 when needed<br />
processes = 4<br />
cheaper = 1<br />
<br />
; reload whenever this config file changes<br />
; %p is the full path of the current config file<br />
touch-reload = %p<br />
<br />
; disable uWSGI request logging<br />
;disable-logging = true<br />
<br />
; enforce a DOCUMENT_ROOT<br />
php-docroot = /usr/share/webapps/%n<br />
; limit allowed extensions<br />
php-allowed-ext = .php<br />
; and search for index.php if required<br />
php-index = index.php<br />
<br />
; set php configuration for this instance of php, no need to edit global php.ini<br />
php-set = date.timezone=Etc/UTC<br />
;php-set = open_basedir=/tmp/:/usr/share/webapps/nextcloud:/etc/webapps/nextcloud:/dev/urandom<br />
php-set = expose_php=false<br />
; avoid security risk of leaving sessions in world-readable /tmp<br />
php-set = session.save_path=/var/lib/nextcloud/data<br />
<br />
; port of php directives set upstream in /usr/share/webapps/nextcloud/.user.ini for use with PHP-FPM<br />
php-set = upload_max_filesize=513M<br />
php-set = post_max_size=513M<br />
php-set = memory_limit=512M<br />
php-set = output_buffering=off<br />
<br />
; load all extensions only in this instance of php, no need to edit global php.ini<br />
;; required core modules<br />
php-set = extension=gd<br />
php-set = extension=iconv<br />
;php-set = extension=zip # enabled by default in global php.ini<br />
<br />
;; database connectors<br />
;; uncomment your selected driver<br />
;php-set = extension=pdo_sqlite<br />
;php-set = extension=pdo_mysql<br />
;php-set = extension=pdo_pgsql<br />
<br />
;; recommended extensions<br />
;php-set = extension=curl # enabled by default in global php.ini<br />
php-set = extension=bz2<br />
php-set = extension=intl<br />
<br />
;; required for specific apps<br />
;php-set = extension=ldap # for LDAP integration<br />
;php-set = extension=ftp # for FTP storage / external user authentication<br />
;php-set = extension=imap # for external user authentication, requires php-imap<br />
<br />
;; recommended for specific apps<br />
;php-set = extension=exif # for image rotation in pictures app, requires exiv2<br />
;php-set = extension=gmp # for SFTP storage<br />
<br />
;; for preview generation<br />
;; provided by packages in AUR<br />
; php-set = extension=imagick<br />
<br />
; opcache<br />
php-set = zend_extension=opcache<br />
<br />
; user cache<br />
; provided by php-acpu, to be enabled **either** here **or** in /etc/php/conf.d/apcu.ini<br />
php-set = extension=apcu<br />
; per https://github.com/krakjoe/apcu/blob/simplify/INSTALL<br />
php-set = apc.ttl=7200<br />
php-set = apc.enable_cli=1<br />
<br />
; web server is already handling URL rewriting, so tell NextCloud not to repeat this<br />
env = front_controller_active=true<br />
<br />
cron2 = minute=-15,unique=1 /usr/bin/php -f /usr/share/webapps/nextcloud/cron.php 1>/dev/null<br />
</nowiki>}}<br />
<br />
{{Note|1=<nowiki/><br />
* Do not forget to set your timezone and uncomment the required database connector in the uWSGI config file<br />
* The [[PHP#Configuration|open_basedir]] directive is optional and commented out. You can uncomment to harden security. Be aware that it may [https://github.com/owncloud/core/search?q=open_basedir&type=Issues occasionally break things].<br />
* Use {{ic|1=php-docroot = /usr/share/webapps}} if placing nextcloud in /nextcloud subdirectory.<br />
}}<br />
<br />
{{Warning|The way the [https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html Nextcloud background job] is currently set up with [https://uwsgi-docs.readthedocs.org/en/latest/Cron.html uWSGI cron] will make use of the default global configuration from {{ic|/etc/php/php.ini}}. This means that none of the specific parameters defined (e.g. required modules) will be enabled, [https://github.com/owncloud/core/issues/12678#issuecomment-66114448 leading to various issues]. One solution is to copy {{ic|/etc/php/php.ini}} to e.g. {{ic|/etc/uwsgi/cron-php.ini}}, make the required modifications there (mirroring {{ic|/etc/uwsgi/nextcloud.ini}} parameters) and referencing it in the cron directive by adding the {{ic|-c /etc/uwsgi/cron-php.ini}} option to ''php'' invocation.}}<br />
<br />
==== Activation ====<br />
<br />
[[uWSGI]] provides a [[Systemd#Using_units|template unit]] that allows to start and enable application using their configuration file name as instance identifier. For example, [[start]]ing {{ic|uwsgi@nextcloud.socket}} would start it on demand referencing the configuration file {{ic|/etc/uwsgi/nextcloud.ini}}. <br />
<br />
To enable the uwsgi service by default at start-up, [[enable]] {{ic|uwsgi@nextcloud.socket}}.<br />
<br />
{{Note|Here we make use of [http://0pointer.de/blog/projects/socket-activation.html systemd socket activation] to prevent unnecessary resources consumption when no connections are made to the instance. If you would rather have it constantly active, simply remove the {{ic|.socket}} part to start and enable the service instead.}}<br />
<br />
See also [[UWSGI#Running uWSGI]].<br />
<br />
== Synchronization ==<br />
<br />
=== Desktop ===<br />
<br />
The official client can be installed with the {{Pkg|nextcloud-client}} package.<br />
Alternative versions are available in the [[AUR]]: {{AUR|nextcloud-client-git}}. Please keep in mind that it is not supported to use the {{Pkg|owncloud-client}} with Nextcloud. Additional packages are needed for some features:<br />
<br />
* '''Auto-login:''' All of them use {{Pkg|qtkeychain-qt5}} to store and retrieve account-specific access tokens. To achieve auto-login when the client starts, one of optional dependencies of ''qtkeychain'' should be installed as well. Moreover, if you choose {{Pkg|libsecret}} as the backend for ''qtkeychain'', a service that provides [https://archlinux.org/packages/?q=org.freedesktop.secrets org.freedesktop.secrets] should be running when the client starts.<br />
* '''File manager integration:''' for {{Pkg|nextcloud-client}}, integration with file managers (e.g., show Nextcloud folders in GTK+ file dialogs) requires another package {{Pkg|nextcloud-client-cloudproviders}}. {{Pkg|nextcloud-client}} already includes cloudproviders supports by default.<br />
<br />
=== Thunderbird ===<br />
<br />
==== Calendar ====<br />
<br />
To access your Nextcloud calendars using Mozilla [[Thunderbird]]'s Lightning calendar you would use the following URL:<br />
<br />
<nowiki>https://ADDRESS/remote.php/caldav/calendars/USERNAME/CALENDARNAME</nowiki><br />
<br />
To access your Nextcloud calendars using CalDAV-compatible programs like Kontact or [[Evolution]], you would use the following URL:<br />
<br />
<nowiki>https://ADDRESS/remote.php/caldav</nowiki><br />
<br />
For details see the [https://docs.nextcloud.com/server/latest/user_manual/en/pim/index.html official documentation].<br />
<br />
==== Contacts ====<br />
<br />
To sync contacts with [[Thunderbird]], see [https://docs.nextcloud.com/server/latest/user_manual/pim/sync_thunderbird.html these instructions]{{Dead link|2021|05|17|status=404}} from the official doc.<br />
<br />
=== Mounting files with davfs2 ===<br />
<br />
If you want to mount your Nextcloud using WebDAV, install {{Pkg|davfs2}} (as described in [[davfs2]]).<br />
<br />
To mount your Nextcloud, use:<br />
<br />
# mount -t davfs https://''your_domain''/nextcloud/remote.php/dav/files/''username''/ /path/to/mount<br />
<br />
You can also create an entry for this in {{ic|/etc/fstab}}<br />
<br />
{{hc|/etc/fstab|<br />
https://''your_domain''/nextcloud/remote.php/dav/files/''username''/ /path/to/mount davfs rw,user,noauto 0 0<br />
}}<br />
<br />
{{Tip|In order to allow automount you can also store your username (and password if you like) in a file as described in [[davfs2#Storing credentials]].}}<br />
<br />
{{Note|If creating/copying files is not possible, while the same operations work on directories, see [[davfs2#Creating/copying files not possible and/or freezes]].}}<br />
<br />
=== Mounting files in GNOME Files (Nautilus) ===<br />
<br />
You can access the files directly in Nautilus ('+ Other Locations') through WebDAV protocol - use the link as shown in your Nextcloud installation Web GUI (typically: https://example.org/remote.php/webdav/{{Dead link|2021|05|17|status=404}}) but replace the protocol name from 'https' to 'davs'. Nautilus will ask for user name and password when trying to connect.<br />
<br />
=== Android ===<br />
<br />
Download the official Nextcloud app from [https://play.google.com/store/apps/details?id=com.nextcloud.client Google Play] or [https://f-droid.org/packages/com.nextcloud.client/ F-Droid].<br />
<br />
To enable contacts and calendar sync (Android 4+):<br />
# download [https://www.davx5.com/ DAVx<sup>5</sup>] ([https://play.google.com/store/apps/details?id=at.bitfire.davdroid Play Store], [https://f-droid.org/app/at.bitfire.davdroid F-Droid])<br />
# Enable mod_rewrite.so in httpd.conf<br />
# create a new DAVdroid account in the ''Account'' settings, and specify your "short" server address and login/password couple, e.g. {{ic|<nowiki>https://cloud.example.com</nowiki>}} (there is no need for the {{ic|<nowiki>/remote.php/{carddav,webdav}</nowiki>}} part if you configured your web server with the proper redirections, as illustrated previously in the article; ''DAVdroid'' will find itself the right URLs)<br />
<br />
=== iOS ===<br />
<br />
Download the official Nextcloud app from the [https://itunes.apple.com/us/app/nextcloud/id1125420102 App Store].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Using the ownCloud console ===<br />
<br />
A useful tool for server administration is {{ic|occ}}, documented [https://docs.nextcloud.com/server/20/admin_manual/configuration_server/occ_command.html here]. You can perform many common server operations with occ, such as managing users and configuring apps.<br />
<br />
{{Tip| A convenience wrapper around {{ic|/usr/share/webapps/nextcloud/occ}} is provided with {{ic|/usr/bin/occ}}, which automatically runs as the default user ({{ic|nextcloud}}), using the default [[PHP]] and PHP configuration file.<br />
The environment variables {{ic|NEXTCLOUD_USER}}, {{ic|NEXTCLOUD_PHP}} and {{ic|NEXTCLOUD_PHP_CONFIG}} can be used to specify a non-default user, PHP executable and PHP configuration file (respectively).}}<br />
<br />
{{Warning| When using {{pkg|php-apcu}} for caching, make sure to set {{ic|1= apc.enable_cli=1}} in {{ic|/etc/php/conf.d/apcu.ini}}, as the {{ic|occ}} command will otherwise run out of memory ({{Bug|69726}}).}}<br />
<br />
=== Pacman hook ===<br />
<br />
To automatically upgrade the Nextcloud database on package update, you can make use of the included [[pacman hook]]:<br />
<br />
# mkdir -vp /etc/pacman.d/hooks<br />
# ln -sv /usr/share/doc/nextcloud/nextcloud.hook /etc/pacman.d/hooks/<br />
<br />
{{Note| The packaged pacman hook implies, that the global {{ic|php.ini}} is used for the application.}}<br />
<br />
=== Running Nextcloud in a subdirectory ===<br />
<br />
By including the default {{ic|nextcloud.conf}} in {{ic|httpd.conf}}, Nextcloud will take control of port 80 and your localhost domain. <br />
<br />
If you would like to have Nextcloud run in a subdirectory, then <br />
<br />
For apache, edit the {{ic|/etc/httpd/conf/extra/nextcloud.conf}} you included and comment out the {{ic|<nowiki><VirtualHost *:80> ... </VirtualHost></nowiki>}} part of the include file.<br />
<br />
For nginx, you can use the following config when using Nextcloud with uwsgi:<br />
<br />
{{hc|head=/etc/nginx/conf.d/nextcloud.conf|output=<nowiki><br />
location = /.well-known/carddav {<br />
return 301 $scheme://$host/nextcloud/remote.php/dav;<br />
}<br />
<br />
location = /.well-known/caldav {<br />
return 301 $scheme://$host/nextcloud/remote.php/dav;<br />
}<br />
<br />
location /.well-known/acme-challenge { }<br />
<br />
location ^~ /nextcloud {<br />
<br />
root /usr/share/webapps;<br />
<br />
# set max upload size<br />
client_max_body_size 512M;<br />
fastcgi_buffers 64 4K;<br />
<br />
# Disable gzip to avoid the removal of the ETag header<br />
gzip off;<br />
<br />
# Uncomment if your server is build with the ngx_pagespeed module<br />
# This module is currently not supported.<br />
#pagespeed off;<br />
<br />
location /nextcloud {<br />
rewrite ^ /nextcloud/index.php$uri;<br />
}<br />
<br />
location ~ ^/nextcloud/(?:build|tests|config|lib|3rdparty|templates|data)/ {<br />
deny all;<br />
}<br />
<br />
location ~ ^/nextcloud/(?:\.|autotest|occ|issue|indie|db_|console) {<br />
deny all;<br />
}<br />
<br />
location ~ ^/nextcloud/(?:updater|ocs-provider)(?:$|/) {<br />
try_files $uri/ =404;<br />
index index.php;<br />
}<br />
<br />
location ~ ^/nextcloud/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) {<br />
include uwsgi_params;<br />
uwsgi_modifier1 14;<br />
# Avoid duplicate headers confusing OC checks<br />
uwsgi_hide_header X-Frame-Options;<br />
uwsgi_hide_header X-XSS-Protection;<br />
uwsgi_hide_header X-Content-Type-Options;<br />
uwsgi_hide_header X-Robots-Tag;<br />
uwsgi_pass unix:/run/uwsgi/owncloud.sock;<br />
}<br />
<br />
# Adding the cache control header for js and css files<br />
# Make sure it is BELOW the PHP block<br />
location ~* \.(?:css|js) {<br />
try_files $uri /nextcloud/index.php$uri$is_args$args;<br />
add_header Cache-Control "public, max-age=7200";<br />
# Add headers to serve security related headers (It is intended<br />
# to have those duplicated to the ones above)<br />
# Before enabling Strict-Transport-Security headers please read<br />
# into this topic first.<br />
# add_header Strict-Transport-Security "max-age=15768000;<br />
# includeSubDomains; preload;";<br />
add_header X-Content-Type-Options nosniff;<br />
add_header X-Frame-Options "SAMEORIGIN";<br />
add_header X-XSS-Protection "1; mode=block";<br />
add_header X-Robots-Tag none;<br />
add_header X-Download-Options noopen;<br />
add_header X-Permitted-Cross-Domain-Policies none;<br />
# Optional: Do not log access to assets<br />
access_log off;<br />
}<br />
<br />
location ~* \.(?:svg|gif|png|html|ttf|woff|ico|jpg|jpeg) {<br />
try_files $uri /nextcloud/index.php$uri$is_args$args;<br />
# Optional: Do not log access to other assets<br />
access_log off;<br />
}<br />
}<br />
</nowiki>}}<br />
<br />
{{Note| Do not forget to configure the {{ic |.well-known}} URLs for service discovery. For more information please see [https://docs.nextcloud.com/server/18/admin_manual/issues/general_troubleshooting.html#service-discovery General troubleshooting and service discovery section of Nextcloud documentation]. }}<br />
<br />
=== Docker ===<br />
<br />
See the [https://hub.docker.com/_/owncloud/ ownCloud] or [https://github.com/nextcloud/docker Nextcloud] repository for [[Docker]].<br />
<br />
=== Upload and share from File Manager ===<br />
<br />
[https://github.com/schiesbn/shareLinkCreator shareLinkCreator] provides the ability to upload a file to<br />
OwnCloud via a supported file manager and receive a link to the uploaded file which can then be emailed or shared in another way.<br />
<br />
=== Defining background jobs ===<br />
<br />
Nextcloud requires scheduled execution of some tasks, and by default it achieves this by using AJAX, however AJAX is the least reliable method, and it is recommended to use [[Cron]] instead. However, Arch Linux ships with {{Pkg|systemd}}, so the preferred way of executing scheduled tasks is a [[systemd timer]].<br />
<br />
[[Start/enable]] {{ic|nextcloud-cron.timer}}.<br />
<br />
Confirm that it is running by running {{ic|systemctl list-timers}}.<br />
<br />
==== AUR package ====<br />
<br />
{{Expansion|Describe what the package actually provides.}}<br />
<br />
Install {{AUR|nextcloud-systemd-timers}}.<br />
<br />
Provided services can be checked with:<br />
$ pacman -Ql nextcloud-systemd-timers<br />
<br />
=== Collabora Online Office integration ===<br />
<br />
{{Expansion|What is the correct {{ic|domain}} (or {{ic|server_name}} in the config) when [[#Running Nextcloud in a subdirectory|Nextcloud runs in a subdirectory]]?}}<br />
<br />
==== Solution with Docker ====<br />
<br />
The first, install a {{Pkg|docker}} package to provide collabora files and setup a Collabora server.<br />
<br />
[[Start/enable]] {{ic|docker.service}}.<br />
<br />
Then, download the official Docker image:<br />
<br />
# docker pull collabora/code<br />
<br />
And, installing a Collabora server. Make sure {{ic|cloud//.example//.com}} is your nextcloud's domain, not a collabora :<br />
<br />
# docker run -t -d -p 127.0.0.1:9980:9980 -e "domain=cloud\\.example\\.com" --restart always --cap-add MKNOD collabora/code<br />
<br />
Also make sure to escape all dots with double backslashes (\), since this string will be evaluated as a regular expression (and your bash 'eats' the first backslash.) If you want to use the docker container with more than one Nextcloud, you will need to use 'domain=cloud\\.example\\.com\|second\\.example\\.com' instead. (All hosts are separated by \|.) When using `localhost` as domain for testing you need to add {{ic|--net host}} to ensure the docker container can access your Nextcloud server. <br />
<br />
If you need to delete or reinstall Collabora server use:<br />
<br />
For recognition CONTAINER_ID of server<br />
<br />
# docker ps<br />
<br />
Stop and delete<br />
<br />
# docker stop CONTAINER_ID<br />
# docker rm CONTAINER_ID<br />
<br />
Futher, follow the instruction of webserver you are using:<br />
<br />
'''Nginx setup example:'''<br />
<br />
Add following to your nextcloud domain config or add new config file in /etc/nginx/conf.d/ directory, (Do not forget to change {{ic|office.example.com}} and {{ic|ssl_certificate}} to the right values. If you are using docker image, change {{ic|http}} to {{ic|https}}.)<br />
<br />
{{hc|/etc/nginx/conf.d/example.conf|<nowiki><br />
upstream office.example.com {<br />
server 127.0.0.1:9980;<br />
}<br />
<br />
server {<br />
listen 443 ssl;<br />
server_name office.example.com;<br />
<br />
ssl_certificate /etc/letsencrypt/live/office.example.com/fullchain.pem;<br />
ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;<br />
<br />
# static files<br />
location ^~ /loleaflet {<br />
proxy_pass http://127.0.0.1:9980;<br />
proxy_set_header Host $host;<br />
}<br />
<br />
# WOPI discovery URL<br />
location ^~ /hosting/discovery {<br />
proxy_pass http://127.0.0.1:9980;<br />
proxy_set_header Host $host;<br />
}<br />
<br />
# Main websocket<br />
location ~ /lool/(.*)/ws$ {<br />
proxy_pass http://127.0.0.1:9980;<br />
proxy_set_header Upgrade $http_upgrade;<br />
proxy_set_header Connection "Upgrade";<br />
proxy_set_header Host $host;<br />
proxy_read_timeout 36000s;<br />
}<br />
<br />
# Admin Console websocket<br />
location ^~ /lool/adminws {<br />
proxy_buffering off;<br />
proxy_pass http://127.0.0.1:9980;<br />
proxy_set_header Upgrade $http_upgrade;<br />
proxy_set_header Connection "Upgrade";<br />
proxy_set_header Host $host;<br />
proxy_read_timeout 36000s;<br />
}<br />
<br />
# download, presentation and image upload<br />
location ~ /lool {<br />
proxy_pass http://127.0.0.1:9980;<br />
proxy_set_header Host $host;<br />
}<br />
<br />
location ^~ /hosting/capabilities {<br />
proxy_pass http://localhost:9980;<br />
proxy_set_header Host $http_host;<br />
}<br />
<br />
}<br />
</nowiki>}}<br />
<br />
Restart a nginx:<br />
<br />
# nginx -s reload<br />
<br />
or [[restart]] {{ic|nginx.service}}.<br />
<br />
'''Apache setup example:'''<br />
<br />
Add following to nextcloud config file. Do not forget to change to the right values<br />
<br />
{{hc|/etc/httpd/conf/extra/nextcloud.conf|<nowiki><br />
<VirtualHost *:443><br />
ServerName office.nextcloud.com:443<br />
<br />
# SSL configuration, you may want to take the easy route instead and use Lets Encrypt!<br />
SSLEngine on<br />
SSLCertificateFile /path/to/signed_certificate<br />
SSLCertificateChainFile /path/to/intermediate_certificate<br />
SSLCertificateKeyFile /path/to/private/key<br />
SSLProtocol all -SSLv2 -SSLv3<br />
SSLCipherSuite ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS<br />
SSLHonorCipherOrder on<br />
<br />
# Encoded slashes need to be allowed<br />
AllowEncodedSlashes NoDecode<br />
<br />
# Container uses a unique non-signed certificate<br />
SSLProxyEngine On<br />
SSLProxyVerify None<br />
SSLProxyCheckPeerCN Off<br />
SSLProxyCheckPeerName Off<br />
<br />
# keep the host<br />
ProxyPreserveHost On<br />
<br />
# static html, js, images, etc. served from loolwsd<br />
# loleaflet is the client part of LibreOffice Online<br />
ProxyPass /loleaflet https://127.0.0.1:9980/loleaflet retry=0<br />
ProxyPassReverse /loleaflet https://127.0.0.1:9980/loleaflet<br />
<br />
# WOPI discovery URL<br />
ProxyPass /hosting/discovery https://127.0.0.1:9980/hosting/discovery retry=0<br />
ProxyPassReverse /hosting/discovery https://127.0.0.1:9980/hosting/discovery<br />
<br />
# Main websocket<br />
ProxyPassMatch "/lool/(.*)/ws$" wss://127.0.0.1:9980/lool/$1/ws nocanon<br />
<br />
# Admin Console websocket<br />
ProxyPass /lool/adminws wss://127.0.0.1:9980/lool/adminws<br />
<br />
# Download as, Fullscreen presentation and Image upload operations<br />
ProxyPass /lool https://127.0.0.1:9980/lool<br />
ProxyPassReverse /lool https://127.0.0.1:9980/lool<br />
</VirtualHost><br />
</nowiki>}}<br />
<br />
After configuring these do restart your apache by [[restart]]ing {{ic|httpd.service}}.<br />
<br />
'''Install the Nextcloud app'''<br />
<br />
Go to the Apps section and choose “Office & Text”, install the “Collabora Online” app. In admin panel select Collabora Online tab and specific the server's domain you have setup before.<br />
<br />
==== Solution without Docker ====<br />
<br />
The {{AUR|collabora-online-server-nodocker}} package provides the Collabora Office (the desktop suite) and the “CODE” (Collabora Online Development Edition) server, which is based on “lool” (LibreOffice OnLine).<br />
<br />
Alter the {{ic|/etc/loolwsd/loolwsd.xml}} file, so that:<br />
<br />
* {{ic|config > server_name}} contains the host and port of the public Nextcloud address, separated by a colon (e.g. {{ic|example.org:443}}),<br />
* {{ic|config > ssl > enable}} is false (i.e. web browser —HTTPS→ proxy —HTTP→ loolwsd),<br />
* {{ic|config > ssl > termination}} is true (I suppose you’ll manage TLS at the proxy level),<br />
* {{ic|config > storage > wopi > host}} reflects the actual hostname (or pattern) of the proxy server (e.g. {{ic|(?:.*\.)?example\.org}}),<br />
* {{ic|config > admin_console > username}} and {{ic|config > admin_console > password}} are set to values of your choice.<br />
<br />
The package's permissions are currently broken, so you must run the following commands to fix it before this package will work:<br />
setcap cap_chown,cap_fowner,cap_sys_chroot,cap_mknod=ep /usr/bin/loolforkit<br />
setcap cap_sys_admin=ep /usr/bin/loolmount<br />
<br />
Then:<br />
<br />
* [[start]] and [[enable]] {{ic|loolwsd.service}};<br />
* configure Nginx by creating a [[Nginx#Server_blocks|server block]] including {{ic|/etc/nginx/snippets/loolwsd.conf}}, and restart it. Example with SSL (change {{ic|office.example.com}} and {{ic|ssl_certificate}} to the right values):<br />
<br />
{{hc|/etc/nginx/conf.d/example.conf|<nowiki><br />
server {<br />
listen 443 ssl;<br />
server_name office.example.com;<br />
<br />
ssl_certificate /etc/letsencrypt/live/office.example.com/fullchain.pem;<br />
ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;<br />
<br />
include snippets/loolwsd.conf;<br />
}<br />
</nowiki>}}<br />
<br />
* in Nextcloud, install the "Collabora Online" app. In the admin panel select the Collabora Online tab and specify the server domain name you have just set up.<br />
<br />
=== Disabling app recommendations ===<br />
<br />
By default, nextcloud reccomends apps to new clients, which can result in a lot of notifications. To disable this, disable the recommendation app using {{ic|occ}}.<br />
<br />
=== Backup calendars and address books with calcardbackup ===<br />
<br />
The {{AUR|calcardbackup}} package can be installed and configured to provide regular backups of the calendar and/or address book databases. Edit {{ic|/etc/calcardbackup/calcardbackup.conf}} to your liking and then [[start]] and [[enable]] {{ic|calcardbackup.timer}}.<br />
<br />
== Troubleshooting ==<br />
<br />
{{Out of date|A lot of references to OwnCloud, are these still valid with Nextcloud?}}<br />
<br />
By default, the logs of the web application are available in {{ic|/var/log/nextcloud/nextcloud.log}}.<br />
<br />
=== Issues with permissions and setup after upgrade to >= 21.0.0 ===<br />
<br />
{{Note| Before nextcloud 21.0.0, the web application was run using the {{ic|http}} user. This is a security concern in regards to cross-application access of this user (it has access to all data of all web applications).}}<br />
<br />
Since version 21.0.0 nextcloud more closely follows the [[web application package guidelines]]. This introduces the separate user {{ic|nextcloud}}, as which the web application is run.<br />
<br />
After an upgrade from nextcloud < 21.0.0 make sure that<br />
<br />
* neither the [[#Data directory|data directory]] nor the [[#Writable apps directory|writable apps directory]] is located below {{ic|/usr/share/webapps/nextcloud/}}, as that directory is owned by {{ic|root}}<br />
* both the [[#Data directory|data directory]] and the [[#Writable apps directory|writable apps directory]], alongside all files beneath them are writable and owned by the {{ic|nextcloud}} user<br />
* the web application configuration file resides in {{ic|/etc/webapps/nextcloud/config/}} and that that directory and its contents are writable and owned by the {{ic|nextcloud}} user<br />
* an application server, such as {{pkg|php-fpm}} or [[UWSGI]] is configured to run the web application as the {{ic|nextcloud}} user and not the {{ic|http}} user<br />
* update the cron job/systemd timer to run with the new user<br />
<br />
=== Issues with MariaDB >= 10.6 ===<br />
<br />
Nextcloud is not compatible with [[MariaDB]] version 10.6 or higher (see {{Bug|71549}}). This is due to MariaDB [https://mariadb.com/kb/en/innodb-compressed-row-format/#read-only forcing read-only for compressed InnoDB tables] and Nextcloud using these kind of tables:<br />
<br />
:From MariaDB 10.6.0, tables that are of the {{ic|COMPRESSED}} row format are read-only by default. This is the first step towards removing write support and deprecating the feature.<br />
<br />
Upstream is aware of this [https://github.com/nextcloud/server/issues/25436 problem] but a [https://github.com/nextcloud/server/issues/25436#issuecomment-883213001 quick fix seems unlikely].<br />
<br />
One easy remedy for this issue is to allow write access to compressed InnoDB tables again by means of MariaDB's system variable [https://mariadb.com/docs/reference/mdb/system-variables/innodb_read_only_compressed/ innodb_read_only_compressed]. Just add the following section to your configuration of MariaDB:<br />
<br />
{{hc|/etc/my.cnf.d/server.cnf|2=<br />
[mariadb-10.6]<br />
innodb_read_only_compressed=OFF<br />
}}<br />
<br />
=== Environment variables not available ===<br />
<br />
Uncomment the line in {{ic|/etc/php/php-fpm.d/www.conf}} as per [https://docs.nextcloud.com/server/latest/admin_manual/installation/source_installation.html#php-fpm-tips-label Nextcloud documentation]:<br />
<br />
env[PATH] = /usr/local/bin:/usr/bin:/bin<br />
<br />
=== Self-signed certificate not accepted ===<br />
<br />
ownCloud uses [[Wikipedia:cURL]] and [[Wikipedia:SabreDAV]] to check if WebDAV is enabled.<br />
If you use SSL/TLS with a self-signed certificate, e.g. as shown in [[LAMP]], and access ownCloud's admin panel, you will see the following error message:<br />
<br />
Your web server is not yet properly setup to allow files synchronization because the WebDAV interface seems to be broken.<br />
<br />
Assuming that you followed the [[LAMP]] tutorial, execute the following steps:<br />
<br />
Create a local directory for non-distribution certificates and copy [[LAMP]]s certificate there. This will prevent {{ic|ca-certificates}}-updates from overwriting it.<br />
<br />
# cp /etc/httpd/conf/server.crt /usr/share/ca-certificates/''WWW.EXAMPLE.COM.crt''<br />
<br />
Add ''WWW.EXAMPLE.COM.crt'' to {{ic|/etc/ca-certificates.conf}}:<br />
<br />
''WWW.EXAMPLE.COM.crt''<br />
<br />
Now, regenerate your certificate store:<br />
<br />
# update-ca-certificates<br />
<br />
Restart the httpd service to activate your certificate.<br />
<br />
=== Self-signed certificate for Android devices ===<br />
<br />
Once you have followed the setup for SSL, as on [[Apache HTTP Server#TLS]] for example, early versions of DAVdroid will<br />
reject the connection because the certificate is not trusted. A certificate can be made as follows on your server:<br />
<br />
# openssl x509 -req -days 365 -in /etc/httpd/conf/server.csr -signkey /etc/httpd/conf/server.key -extfile android.txt -out CA.crt<br />
# openssl x509 -inform PEM -outform DER -in CA.crt -out CA.der.crt <br />
<br />
The file {{ic|android.txt}} should contain the following:<br />
<br />
basicConstraints=CA:true<br />
<br />
Then import {{ic|CA.der.crt}} to your Android device:<br />
<br />
Put the {{ic|CA.der.crt}} file onto the sdcard of your Android device (usually to the internal one, e.g. save from a mail attachment).<br />
It should be in the root directory. Go to ''Settings > Security > Credential storage'' and select ''Install from device storage''.<br />
The {{ic|.crt}} file will be detected and you will be prompted to enter a certificate name. After importing the certificate,<br />
you will find it in ''Settings > Security > Credential storage > Trusted credentials > User''.<br />
<br />
Thanks to: [https://web.archive.org/web/20150323082541/http://www.leftbrainthings.com/2013/10/13/creating-and-importing-self-signed-certificate-to-android-device/]<br />
<br />
Another way is to import the certificate directly from your server via [https://play.google.com/store/apps/details?id=at.bitfire.cadroid CAdroid]{{Dead link|2020|04|01|status=404}} and follow the instructions there.<br />
<br />
=== Cannot write into config directory! ===<br />
<br />
If you have set {{ic|open_basedir}} in your PHP/web server configuration file (e.g. {{ic|/etc/httpd/conf/extra/nextcloud.conf}}), make sure that it includes {{ic|/etc/webapps}}.<br />
<br />
Restart the web server to apply the change.<br />
<br />
You may need to "[[#php-fpm|explicitly grant write permissions on the appropriate Nextcloud paths]]" if you are getting this error after an upgrade from Nextcloud 17 to Nextcloud 18.<br />
<br />
=== Cannot create data directory ===<br />
<br />
If you have set {{ic|open_basedir}} in your PHP/web server configuration file (e.g. {{ic|/etc/httpd/conf/extra/nextcloud.conf}}), make sure that it includes the data directory.<br />
<br />
Restart the web server to apply the change.<br />
<br />
=== CSync failed to find a specific file. ===<br />
<br />
This is most likely a certificate issue. Recreate it, and do not leave the common name empty or you will see the error again.<br />
<br />
# openssl req -new -x509 -nodes -newkey rsa:4096 -keyout server.key -out server.crt<br />
<br />
=== Seeing white page after login ===<br />
<br />
The cause is probably a new app that you installed. To fix that, you can use the occ command as described<br />
[https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/occ_command.html here]. So with<br />
<br />
sudo -u http php /usr/share/webapps/nextcloud/occ app:list<br />
<br />
you can list all apps (if you installed nextcloud in the standard directory), and with <br />
<br />
sudo -u http php /usr/share/webapps/nextcloud/occ app:disable <nameOfExtension><br />
<br />
you can disable the troubling app.<br />
<br />
Alternatively, you can either use [[phpMyAdmin]] to edit the {{ic|oc_appconfig}} table (if you got lucky and the table has an edit option), or do it by hand with mysql:<br />
<br />
mysql -u root -p owncloud<br />
MariaDB [owncloud]> '''delete from''' oc_appconfig '''where''' appid='<nameOfExtension>' '''and''' configkey='enabled' '''and''' configvalue='yes';<br />
MariaDB [owncloud]> '''insert into''' oc_appconfig (appid,configkey,configvalue) '''values''' ('<nameOfExtension>','enabled','no');<br />
<br />
This should delete the relevant configuration from the table and add it again.<br />
<br />
=== GUI sync client fails to connect ===<br />
<br />
If using HTTP basic authentication, make sure to exclude "status.php", which must be publicly accessible. [https://github.com/owncloud/mirall/issues/734]<br />
<br />
=== GUI tray icon disappears, but client still running in the background ===<br />
<br />
After waking up from a suspended state, the Nextcloud client tray icon may disappear from the system tray. A workaround is to delay the startup of the client, as noted [https://github.com/nextcloud/desktop/issues/203#issuecomment-463957811 here]. This can be done with the .desktop file, for example:<br />
<br />
{{hc|.local/share/applications/nextcloud.desktop|<nowiki><br />
...<br />
Exec=bash -c 'sleep 5 && nextcloud'<br />
...<br />
</nowiki>}}<br />
<br />
=== Some files upload, but give an error 'Integrity constraint violation...' ===<br />
<br />
You may see the following error in the ownCloud sync client:<br />
<br />
SQLSTATE[23000]: Integrity constraint violation: ... Duplicate entry '...' for key 'fs_storage_path_hash')...<br />
<br />
This is caused by an issue with the File Locking app, which is often not sufficient to keep conflicts from occurring on some webserver configurations.<br />
A more complete [https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/files_locking_transactional.html Transactional File Locking]<br />
is available that rids these errors, but you must be using the Redis php-caching method. Install {{Pkg|redis}} and {{Pkg|php-redis}}, comment out<br />
your current php-cache mechanism, and then in {{ic|/etc/php/conf.d/redis.ini}} uncomment {{ic|1=extension=redis}}.<br />
Then in {{ic|config.php}} make the following changes:<br />
<br />
'memcache.local' => '\OC\Memcache\Redis',<br />
'filelocking.enabled' => 'true',<br />
'memcache.locking' => '\OC\Memcache\Redis',<br />
'redis' => array(<br />
'host' => 'localhost',<br />
'port' => 6379,<br />
'timeout' => 0.0,<br />
),<br />
<br />
and [[start/enable]] {{ic|redis.service}}.<br />
<br />
Finally, disable the File Locking App, as the Transational File Locking will take care of it (and would conflict).<br />
<br />
If everything is working, you should see 'Transactional File Locking Enabled' under Server Status on the Admin page, and syncs should no longer cause issues.<br />
<br />
=== "Cannot write into apps directory" ===<br />
<br />
As mentioned in the [https://docs.nextcloud.com/server/latest/admin_manual/apps_management.html official admin manual],<br />
either you need an apps directory that is writable by the http user, or you need to set {{ic|appstoreenabled}} to {{ic|false}}. <br />
<br />
If you have set {{ic|open_basedir}} in your PHP/web server configuration file (e.g. {{ic|/etc/httpd/conf/extra/nextcloud.conf}}), it may be necessary to add your ''/path/to/data'' directory to the string on the line starting with {{ic|php_admin_value open_basedir }}:<br />
<br />
{{hc|/etc/httpd/conf/extra/nextcloud.conf|2=<br />
<br />
php_admin_value open_basedir "''/path/to/data/'':/srv/http/:/dev/urandom:/tmp/:/usr/share/pear/:/usr/share/webapps/nextcloud/:/etc/webapps/nextcloud"<br />
}}<br />
<br />
=== Installed apps get blocked because of MIME type error ===<br />
<br />
If you are putting your apps folder outside of the nextcloud installation directory make sure your webserver serves it properly.<br />
<br />
In nginx this is accomplished by adding a location block to the nginx configuration as the folder will not be included in it by default.<br />
<br />
location ~ /apps2/(.*)$ {<br />
alias /var/www/nextcloud/apps/$1;<br />
}<br />
<br />
=== CSS and JS resources blocked due to MIME type error ===<br />
<br />
If you load your Nextcloud web gui and it's missing styles etc. check the browser's console logs for lines like:<br />
<br />
<nowiki>The resource from “https://example.com/core/css/guest.css?v=72c34c37-0” was blocked due to MIME type (“text/plain”) mismatch (X-Content-Type-Options: nosniff).</nowiki><br />
<br />
There are a few possible reasons, possibly you have [https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html#javascript-js-or-css-css-files-not-served-properly not included any mime types] in your {{ic|nginx.conf}} add the following to {{ic|nginx.conf}}<br />
<br />
types_hash_max_size 2048;<br />
types_hash_bucket_size 128;<br />
include mime.types;<br />
<br />
Here we use the {{ic|mime.types}} provided by {{Pkg|mailcap}}, due to the large number of types included we increase the allowed size of the types hash.<br />
<br />
Other possible reasons for these errors are missing permissions on the files. Make sure the files are owned by {{ic|http:http}} and can be read and written to by this user.<br />
<br />
=== Security warnings even though the recommended settings have been included in nginx.conf ===<br />
<br />
At the top of the admin page there might be a warning to set the {{ic|Strict-Transport-Security}}, {{ic|X-Content-Type-Options}},<br />
{{ic|X-Frame-Options}}, {{ic|X-XSS-Protection}} and {{ic|X-Robots-Tag}} according to https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/harden_server.html{{Dead link|2020|04|01|status=404}}<br />
even though they are already set like that.<br />
<br />
A possible cause could be that because owncloud sets those settings, uwsgi passed them along and nginx added them again:<br />
<br />
{{hc|$ curl -I https://domain.tld|<nowiki><br />
...<br />
X-XSS-Protection: 1; mode=block<br />
X-Content-Type-Options: nosniff<br />
X-Frame-Options: Sameorigin<br />
X-Robots-Tag: none<br />
Strict-Transport-Security: max-age=15768000; includeSubDomains; preload;<br />
X-Content-Type-Options: nosniff<br />
X-Frame-Options: SAMEORIGIN<br />
X-XSS-Protection: 1; mode=block<br />
X-Robots-Tag: none<br />
</nowiki>}}<br />
<br />
While the fast_cgi sample config has a parameter to avoid that ( {{ic|fastcgi_param modHeadersAvailable true; #Avoid sending the security headers twice}} ), when using uwsgi and nginx the following modification of the uwsgi part in nginx.conf could help:<br />
<br />
{{hc| /etc/nginx/nginx.conf|<nowiki><br />
...<br />
# pass all .php or .php/path urls to uWSGI<br />
location ~ ^(.+\.php)(.*)$ {<br />
include uwsgi_params;<br />
uwsgi_modifier1 14;<br />
# hode following headers received from uwsgi, because otherwise we would send them twice since we already add them in nginx itself<br />
uwsgi_hide_header X-Frame-Options;<br />
uwsgi_hide_header X-XSS-Protection;<br />
uwsgi_hide_header X-Content-Type-Options;<br />
uwsgi_hide_header X-Robots-Tag;<br />
uwsgi_hide_header X-Frame-Options;<br />
#Uncomment line below if you get connection refused error. Remember to commet out line with "uwsgi_pass 127.0.0.1:3001;" below<br />
uwsgi_pass unix:/run/uwsgi/owncloud.sock;<br />
#uwsgi_pass 127.0.0.1:3001;<br />
}<br />
...<br />
</nowiki>}}<br />
<br />
=== "Reading from keychain failed with error: 'No keychain service available'" ===<br />
<br />
Can be fixed for Gnome by installing the following 2 packages, {{Pkg|libgnome-keyring}} and {{Pkg|gnome-keyring}}.<br />
Or the following for KDE, {{Pkg|libgnome-keyring}} and {{Pkg|qtkeychain-qt5}}.<br />
<br />
=== FolderSync: "Method Not Allowed" ===<br />
<br />
FolderSync needs access to {{ic|/owncloud/remote.php/webdav}}, so you could create another alias for owncloud in your {{ic|/etc/httpd/conf/extra/nextcloud.conf}}<br />
<br />
<IfModule mod_alias.c><br />
Alias /nextcloud /usr/share/webapps/nextcloud/<br />
Alias /owncloud /usr/share/webapps/nextcloud/<br />
</IfModule><br />
<br />
== See also ==<br />
<br />
* [https://docs.nextcloud.com/ Nextcloud Documentation Overview]<br />
* [https://docs.nextcloud.com/server/latest/admin_manual/ Nextcloud Admin Manual]</div>Simon04https://wiki.archlinux.org/index.php?title=Preboot_Execution_Environment&diff=642151Preboot Execution Environment2020-11-22T23:47:21Z<p>Simon04: /* Pixiecore */ "An all-in-one tool for easy netbooting"</p>
<hr />
<div>[[Category:Installation process]]<br />
[[Category:Networking]]<br />
[[Category:Boot process]]<br />
[[de:Preboot eXecution Environment]]<br />
[[es:Preboot Execution Environment]]<br />
[[fr:Install PXE]]<br />
[[ja:PXE]]<br />
[[pt:Preboot Execution Environment]]<br />
[[ru:Preboot Execution Environment]]<br />
[[zh-hans:Preboot Execution Environment]]<br />
{{Related articles start}}<br />
{{Related|Diskless system}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Preboot Execution Environment]]:<br />
:The Preboot eXecution Environment (PXE, most often pronounced as pixie) specification describes a standardized client-server environment that boots a software assembly, retrieved from a network, on PXE-enabled clients. On the client side it requires only a PXE-capable network interface controller (NIC), and uses a small set of industry-standard network protocols such as DHCP and TFTP.<br />
<br />
In this guide, PXE is used to boot the installation media with an appropriate option-rom that supports PXE on the target. This works well when you already have a server set up.<br />
<br />
== Preparation ==<br />
<br />
=== Overview ===<br />
It is useful to give an overview of the PXE boot process in order to understand the [[#Server setup]], the [[#Installation]] on the client side and the Arch Linux files needed.<br />
<br />
The client starts by broadcasting packets asking for a DHCP server and containing specific PXE options. The DHCP server responds with networking information (the IP address assigned to the client) and also provides, by using specific [[Wikipedia:Bootstrap Protocol|bootstrap protocol (BOOTP)]] parameters of the DHCP, additional information like the [[TFTP]] server address, the path of the initial network bootstrap program (NBP) to download or the boot configuration file name.<br />
<br />
The NBP is transferred from the PXE server to the client using TFTP, to be loaded into memory and executed. The kernel and the initramfs are also transferred this way.<br />
<br />
Then the root filesystem is transferred using one of the following protocols: HTTP, NFS or NBD.<br />
<br />
=== Boot from install media ===<br />
<br />
In order to gather the files that will be transferred from the server to the client for booting, get the latest official install media from the [https://www.archlinux.org/download/ download page].<br />
<br />
Next mount the image:<br />
<br />
# mkdir /mnt/archiso<br />
# mount -o loop,ro archlinux-''release_date''-x86_64.iso /mnt/archiso<br />
<br />
where {{ic|''release_date''}} is the release date in the ISO filename like, e.g., {{ic|2020.10.01}}.<br />
<br />
{{note|The Arch ISO currently only supports '''BIOS'''-style PXE booting. See {{Bug|50188}} for more information.}}<br />
<br />
=== Boot from netboot ===<br />
<br />
Arch Linux [[netboot]] images can be used to download the latest Arch Linux release on the fly upon system boot. Download the image compatible with your configuration.<br />
<br />
{{note|The Arch netboot supports both '''BIOS''' and '''UEFI''' booting.}}<br />
<br />
== Pixiecore ==<br />
<br />
A all-in-one solution is provided by [https://github.com/danderson/netboot/tree/master/pixiecore pixiecore]<br />
<br />
# Install {{aur|pixiecore-git}}<br />
# Run {{ic|pixiecore quick arch --dhcp-no-bind}} as root<br />
# Boot via PXE<br />
<br />
== Server setup ==<br />
<br />
You will need to setup a DHCP server, a TFTP server for transferring the NBP and one of the following services for transferring the root filesystem: [[List of applications/Internet#Web servers|HTTP server]], NFS or NBD.<br />
<br />
=== Network ===<br />
<br />
Bring up your wired network adapter, and assign it an address appropriately.<br />
<br />
# ip link set ''eth0'' up<br />
# ip addr add 192.168.0.1/24 dev ''eth0''<br />
<br />
=== DHCP + TFTP ===<br />
<br />
You will need both a DHCP server and a TFTP server to configure networking on the install target and to facilitate the transfer of files between the server and the client.<br />
[[dnsmasq]] does both, and is extremely easy to set up.<br />
<br />
[[Install]] the {{pkg|dnsmasq}} package.<br />
<br />
''dnsmasq'' needs to be configured.<br />
See instructions on how to setup a [[dnsmasq#TFTP server]] and a [[dnsmasq#PXE server]].<br />
<br />
Are provided below some common configuration instructions. ''tftp_root'' is the directory where the Arch ISO is mounted (e.g. {{ic|/mnt/archiso}}) or where the network boot program is located.<br />
<br />
{{hc|# /etc/dnsmasq.conf|2=<br />
# Listen only to the specified interface<br />
interface=''eth0''<br />
<br />
# Don't function as dns server<br />
port=0<br />
<br />
# tftp server setup<br />
enable-tftp<br />
tftp-root=''tftp_root''<br />
<br />
# Log extra information about dhcp transactions (for debug purposes)<br />
log-dhcp<br />
}}<br />
<br />
To enable the DHCP server and give IPv4 addresses within a range, add to the configuration file a line similar to:<br />
dhcp-range=192.168.0.50,192.168.0.150<br />
<br />
Or in case there is already a DHCP-server running on the network and you want to interoperate with it, see [[dnsmasq#Proxy DHCP]].<br />
<br />
Two examples covering different boot style and installation media are provided below.<br />
<br />
Once configured according to your needs, [[start]] {{ic|dnsmasq.service}}.<br />
<br />
==== BIOS boot from install media ====<br />
The path of the initial bootstrap program to be transferred is defined with the {{ic|1=dhcp-boot}} option in the configuration file.<br />
dhcp-boot=/arch/boot/syslinux/lpxelinux.0<br />
In order to send specific [https://www.iana.org/assignments/bootp-dhcp-parameters/bootp-dhcp-parameters.xhtml ''boot''strap ''p''rotocol (BOOTP) parameters], like the configuration file path, the {{ic|1=dhcp-option-force=''flag'',''value''}} line is used.<br />
dhcp-option-force=209,boot/syslinux/archiso.cfg<br />
dhcp-option-force=210,/arch/<br />
<br />
==== UEFI boot from netboot ====<br />
To send a file depending on the architecture, here the netboot image for UEFI-style boot, use:<br />
<br />
pxe-service=BC_EFI, "Boot from network BC EFI", ipxe.efi<br />
pxe-service=X86-64_EFI, "Boot from network X86-64 EFI", ipxe.efi<br />
<br />
If using netboot, the rest of the server setup section which focuses on the Arch ISO does not apply.<br />
<br />
=== Transferring archiso root filesystem ===<br />
<br />
Thanks to {{ic|archiso_pxe_http}}, {{ic|archiso_pxe_nfs}} and {{ic|archiso_pxe_nbd}} initcpio hooks in [[archiso]], it is possible to boot using HTTP, NFS or NBD. Boot time is approximately the same in all three methods, but HTTP method allows you to watch a state of downloading airootfs.sfs in percents.<br />
<br />
==== HTTP ====<br />
<br />
Among all alternatives, ''darkhttpd'' is by far the most trivial to setup (and the lightest-weight).<br />
<br />
First, [[install]] the {{pkg|darkhttpd}} package.<br />
<br />
Then start ''darkhttpd'' using our {{ic|/mnt/archiso}} as the document root:<br />
<br />
{{hc|# darkhttpd /mnt/archiso|<br />
darkhttpd/1.8, copyright (c) 2003-2011 Emil Mikulic.<br />
listening on: <nowiki>http://0.0.0.0:80/</nowiki><br />
}}<br />
<br />
{{Note|It is important that the server is running on port '''80'''. If you start ''darkhttpd'' without root access it will default to '''8080''', the client will still try to access port 80 and the boot will fail.}}<br />
<br />
==== NFS ====<br />
<br />
You will need to set up an [[NFS|NFS server]] with an export at the root of your mounted installation media, which would be {{ic|/mnt/archiso}} if you followed [[#Preparation]]. After setting up the server, add the following line to your {{ic|/etc/exports}} file:<br />
<br />
{{hc|/etc/exports|<br />
/mnt/archiso 192.168.0.0/24(ro,no_subtree_check)<br />
}}<br />
<br />
If the server was already running, re-export the filesystems with {{ic|exportfs -r -a -v}}.<br />
<br />
The default settings in the installer expect to find the NFS at {{ic|/run/archiso/bootmnt}}, so you will need to edit the boot options. To do this, press Tab on the appropriate boot menu choice and edit the {{ic|archiso_nfs_srv}} option accordingly:<br />
<br />
archiso_nfs_srv=${pxeserver}:/mnt/archiso<br />
<br />
Alternatively, you can use {{ic|/run/archiso/bootmnt}} for the entire process.<br />
<br />
After the kernel loads, the Arch bootstrap image will copy the root filesystem via NFS to the booting host. This can take a little while. Once this completes, you should have a running system.<br />
<br />
==== NBD ====<br />
<br />
[[Install]] the {{pkg|nbd}} package and configure it:<br />
<br />
{{hc|/etc/nbd-server/config|2=<br />
[generic]<br />
[archiso]<br />
readonly = true<br />
exportname = /srv/archlinux-''release_date''-x86_64.iso<br />
}}<br />
<br />
where {{ic|''release_date''}} is the release date in the ISO filename like, e.g., {{ic|2020.03.01}}.<br />
<br />
[[Start]] {{ic|nbd.service}}.<br />
<br />
=== Existing PXE server ===<br />
<br />
If you have an existing PXE server with a [[PXELINUX]] system setup (e.g. a combination of DHCP and [[TFTP]]), you can add the following menu items to your {{ic|/tftpboot/pxelinux.cfg/default}} file in order to boot Arch via your preferred method:<br />
<br />
{{bc|1=<br />
LABEL archlinux<br />
MENU LABEL Arch Linux x86_64<br />
LINUX ''/path/to/extracted/Arch/ISO''/arch/boot/x86_64/vmlinuz-linux<br />
INITRD ''/path/to/extracted/Arch/ISO''/arch/boot/intel-ucode.img,''/path/to/extracted/Arch/ISO''/arch/boot/amd-ucode.img,''/path/to/extracted/Arch/ISO''/arch/boot/x86_64/initramfs-linux.img<br />
APPEND archisobasedir=arch archiso_http_srv=''<nowiki>http://httpserver/path/to/extracted/Arch/ISO</nowiki>''/<br />
SYSAPPEND 3<br />
TEXT HELP<br />
Arch Linux 2020.10.01 x86_64<br />
ENDTEXT<br />
}}<br />
<br />
You can replace {{ic|archiso_http_srv}} with {{ic|archiso_nfs_srv}} for NFS or {{ic|archiso_nbd_srv}} for NBD (see usage examples in {{ic|arch/boot/syslinux/archiso_pxe.cfg}} file resided on ArchLinux iso). Whichever method you choose, you must pass {{ic|1=ip=}} parameter to instruct the kernel to bring up the network interface before it attempts to mount the installation medium over the network. Passing {{ic|1=BOOTIF=}} is required when there are several wired interfaces on the client side and/or you want resolv.conf to be already configured inside booted archiso. You can use [https://wiki.syslinux.org/wiki/index.php?title=Config#SYSAPPEND sysappend mask] 3 (which is 1+2) to pass these parameters automatically. For available boot parameters see [https://gitlab.archlinux.org/archlinux/archiso/-/blob/master/docs/README.bootparams README.bootparams].<br />
<br />
== Installation ==<br />
<br />
For this portion you will need to figure out how to tell the client to attempt a PXE boot; in the corner of the screen along with the normal post messages, usually there will be some hint on which key to press to try PXE booting first. On an IBM x3650 {{ic|F12}} brings up a boot menu, the first option of which is ''Network''; on a Dell PE 1950/2950 pressing {{ic|F12}} initiates PXE booting directly.<br />
<br />
=== Boot ===<br />
<br />
Looking at [[journald]] on the PXE server will provide some additional insight to what exactly is going on during the early stages of the PXE boot process:<br />
<br />
{{hc|# journalctl -u dnsmasq.service -f|2=<nowiki><br />
dnsmasq-dhcp[2544]: DHCPDISCOVER(eth1) 00:1a:64:6a:a2:4d <br />
dnsmasq-dhcp[2544]: DHCPOFFER(eth1) 192.168.0.110 00:1a:64:6a:a2:4d <br />
dnsmasq-dhcp[2544]: DHCPREQUEST(eth1) 192.168.0.110 00:1a:64:6a:a2:4d <br />
dnsmasq-dhcp[2544]: DHCPACK(eth1) 192.168.0.110 00:1a:64:6a:a2:4d <br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/pxelinux.0 to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/whichsys.c32 to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso_pxe_choose.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/ifcpu64.c32 to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso_pxe_both_inc.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso_head.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso_pxe32.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso_pxe64.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/archiso_tail.cfg to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/vesamenu.c32 to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/syslinux/splash.png to 192.168.0.110<br />
</nowiki>}}<br />
<br />
After you load {{ic|pxelinux.0}} and {{ic|archiso.cfg}} via TFTP, you will (hopefully) be presented with a [[syslinux]] boot menu with several options, where you can select ''Boot Arch Linux (x86_64) (HTTP)''.<br />
<br />
Next the kernel and initramfs (appropriate for the architecture you selected) will be transferred, again via TFTP:<br />
<br />
{{bc|1=<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/x86_64/vmlinuz to 192.168.0.110<br />
dnsmasq-tftp[2544]: sent /mnt/archiso/arch/boot/x86_64/initramfs-linux.img to 192.168.0.110<br />
}}<br />
<br />
If all goes well, you should then see activity on darkhttpd coming from the PXE-target; at this point the kernel would be loaded on the PXE-target, and in init: <br />
<br />
{{bc|1=<br />
1348347586 192.168.0.110 "GET /arch/aitab" 200 678 "" "curl/7.27.0"<br />
1348347587 192.168.0.110 "GET /arch/x86_64/root-image.fs.sfs" 200 107860206 "" "curl/7.27.0"<br />
1348347588 192.168.0.110 "GET /arch/x86_64/usr-lib-modules.fs.sfs" 200 36819181 "" "curl/7.27.0"<br />
1348347588 192.168.0.110 "GET /arch/any/usr-share.fs.sfs" 200 63693037 "" "curl/7.27.0"<br />
}}<br />
<br />
After the root filesystem is downloaded via HTTP, you will eventually end up at the normal live system root [[zsh]] prompt.<br />
<br />
=== Post-boot ===<br />
<br />
Unless you want all traffic to be routed through your PXE server (which will not work anyway unless you [[#Sharing internet with PXE clients|set it up properly]]), you will want to [[stop]] {{ic|dnsmasq.service}} and get a new lease on the install target, as appropriate for your network layout.<br />
<br />
You can also kill ''darkhttpd''; the target has already downloaded the root filesystem, so it is no longer needed. While you are at it, you can also unmount the installation image:<br />
<br />
# umount /mnt/archiso<br />
<br />
At this point you can follow the [[Installation guide]].<br />
<br />
=== Low memory systems ===<br />
<br />
The {{ic|copytoram}} [[initramfs]] option can be used to control whether the root filesystem should be copied to ram in its entirety in early-boot.<br />
<br />
It highly recommended to leave this option alone, and should only be disabled if entirely necessary (systems with less than ~256MB physical memory). Append {{ic|1=copytoram=n}} to your kernel line if you wish to do so.<br />
<br />
{{Note|As this requires loop-mounting squashfs from a mounted remote filesystem, {{ic|1=copytoram=n}} and {{ic|[[#HTTP|archiso_pxe_http]]}} are mutually exclusive.}}<br />
<br />
=== Sharing internet with PXE clients ===<br />
<br />
If your network for PXE clients is private (for example, 192.168.1.0/24), and you want them to be able to access internet (for example, for packages installation), you should configure masquerade/source nat properly. Your PXE server must have a separate NIC connected to the internet. You can use such command to pass through the internet to clients:<br />
<br />
iptables -t nat -A POSTROUTING -s 192.168.1.0/24 -j MASQUERADE<br />
<br />
To make this rule persistent after reboot, run the following command:<br />
<br />
iptables-save -f /etc/iptables/iptables.rules<br />
<br />
and [[enable]] {{ic|iptables.service}}.<br />
<br />
See [[Simple stateful firewall#Setting up a NAT gateway]] and [[Internet sharing#Enable NAT]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== DHCP interface rename bug ===<br />
<br />
{{Bug|36749}} causes default [https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/ predictable network interface renaming] to fail and then DHCP client to fail because of it. A workaround is to add the kernel boot parameter {{ic|1=net.ifnames=0}} to disable predictable interface names.<br />
<br />
=== VirtualBox cannot boot while real machine can ===<br />
<br />
When using [[VirtualBox]] to test your configuration, the virtual machine may get stucked at:<br />
<br />
Probing EDD (edd=off to disable)... ok<br />
<br />
But PXE booting with real machine works fine. The problem may be because you have set several CPU cores to your client machine, and you set its type as ''Other'' and version as ''Other/Unknown (64 bit)''. So VirtualBox does not know which paravirtualization interface to use by default.<br />
<br />
Adding {{ic|1=loglevel=7}} [[kernel parameter]] lets you see that machine was actually stuck at:<br />
<br />
[ 0.063697] smp: Bringing up secondary CPUs...<br />
[ 0.103768] x86: Booting SMP configuration:<br />
<br />
To resolve this, either use one CPU core, or go to ''Machine > Settings > System > Acceleration'' and set one of the following paravirtualization interface: ''Minimal'', ''Hyper-V'' or ''KVM''.</div>Simon04https://wiki.archlinux.org/index.php?title=HiDPI&diff=641988HiDPI2020-11-21T08:17:10Z<p>Simon04: /* Java applications */ move and update IntelliJ IDEA</p>
<hr />
<div>[[Category:Graphics]]<br />
[[ja:HiDPI]]<br />
[[zh-hans:HiDPI]]<br />
{{Related articles start}}<br />
{{Related|Font configuration}}<br />
{{Related articles end}}<br />
HiDPI (High Dots Per Inch) displays, also known by Apple's "[[wikipedia:Retina Display|Retina Display]]" marketing name, are screens with a high resolution in a relatively small format. They are mostly found in high-end laptops and monitors.<br />
<br />
Not all software behaves well in high-resolution mode yet. Here are listed most common tweaks which make work on a HiDPI screen more pleasant.<br />
<br />
== Desktop environments ==<br />
<br />
=== GNOME ===<br />
To enable HiDPI, navigate to ''Settings > Devices > Displays > Scale'' and choose an appropriate value. Or, use gsettings:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "[{'Gdk/WindowScalingFactor', <2>}]"<br />
$ gsettings set org.gnome.desktop.interface scaling-factor 2<br />
<br />
{{Note|1=GNOME only allows integer scaling numbers to be set. 1 = 100%, 2 = 200%, etc. See [[#Fractional scaling]] below.}}<br />
<br />
==== Fractional scaling ====<br />
<br />
A setting of {{ic|2, 3, etc}}, which is all you can do with {{ic|scaling-factor}}, may not be ideal for certain HiDPI displays and smaller screens (e.g. small tablets). Fractional scaling is possible on both Wayland and Xorg, though the process differs.<br />
<br />
===== Wayland =====<br />
<br />
Enable the experimental fractional scaling feature:<br />
<br />
$ gsettings set org.gnome.mutter experimental-features "['scale-monitor-framebuffer']"<br />
<br />
then open ''Settings > Devices > Displays'' (the new options may only appear after a restart).<br />
<br />
To enable the option for all users, create the following three files with the corresponding content<br />
<br />
{{hc|/etc/dconf/profile/user|<nowiki><br />
user-db:user<br />
system-db:local<br />
</nowiki>}}<br />
<br />
{{hc|/etc/dconf/db/local.d/00-hidpi|<nowiki><br />
[org/gnome/mutter]<br />
experimental-features=['scale-monitor-framebuffer']<br />
</nowiki>}}<br />
<br />
{{hc|/etc/dconf/db/locks/hidpi|<nowiki><br />
/org/gnome/mutter/experimental-features<br />
</nowiki>}}<br />
<br />
Then run {{ic|dconf update}} and restart the machine. This will permanently lock the option.<br />
<br />
===== Xorg =====<br />
<br />
You can achieve any non-integer scale factor by using a combination of GNOME's {{ic|scaling-factor}} and [[xrandr]]. This combination keeps the TTF fonts properly scaled so that they do not become blurry if using {{ic|xrandr}} alone. You specify zoom-in factor with {{ic|gsettings}} and zoom-out factor with [[xrandr]].<br />
<br />
First scale GNOME up to the minimum size which is too big. Usually "2" is already too big, otherwise try "3" etc. Then start scaling down by setting zoom-out factor with [[xrandr]]. First get the relevant output name, the examples below use {{ic|eDP1}}. Start e.g. with zoom-out 1.25 times. If the UI is still too big, increase the scale factor; if it is too small decrease the scale factor.<br />
<br />
$ xrandr --output eDP1 --scale 1.25x1.25<br />
<br />
{{Note|To allow the mouse to reach the whole screen, you may need to use the {{ic|--panning}} option as explained in [[#Side display]].}}<br />
<br />
{{Accuracy|The following was initially added under [[#X Resources]]. Clarify how it integrates with the info there or that above for GNOME.|section=GNOME ignores X settings}}<br />
<br />
GNOME ignores X settings due to its xsettings Plugin in Gnome Settings Daemon, where DPI setting is hard coded.<br />
There is blog entry for [http://blog.drtebi.com/2012/12/changing-dpi-setting-on-gnome-34.html recompiling Gnome Settings Daemon].<br />
In the source documentation there is another way mentioned to set X settings DPI:<br />
<br />
You can use the gsettings, just make sure to read previous setting first and merge it. In just simply set it with this command:<br />
<br />
gsettings set org.gnome.settings-daemon.plugins.xsettings overrides "{'Xft/DPI': <153600>}"<br />
<br />
From README.xsettings<br />
<br />
Noting that variants must be specified in the usual way (wrapped in <>).<br />
<br />
Note also that DPI in the above example is expressed in 1024ths of an inch.<br />
<br />
==== Text Scaling ====<br />
<br />
Alternatively, or in addition to changing the display scaling, you can separately scale text. This can be done by navigating to ''Fonts > Scaling Factor'' in Gnome Tweaks, or using gsettings. Note that the text scaling factor need not be limited to whole integers, for example:<br />
<br />
$ gsettings set org.gnome.desktop.interface text-scaling-factor 1.5<br />
<br />
===== GTK+ vs Gnome Shell elements on Xorg =====<br />
<br />
Adjusting the text scaling as per the above only affects GTK+ elements of the GNOME desktop. This should cover everything on Wayland. However, those on an Xorg session may find that they need to make further adjustments on HiDPI environments, since the GNOME Shell UI (including the top bar, dock, application menus, etc.) relies separately on the [[St]] toolkit. Note that this is a long-standing issue to which a [https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/486 patch] has been merged and available for Gnome Shell 3.35 onward. For older releases, Xorg users can resolve most of the Gnome shell scaling problems by manually editing the shell theme that they are currently using. The relevant CSS files are normally located at {{ic|/usr/share/themes/YOUR-THEME/gnome-shell/gnome-shell.css}}. Users should increase all "font-size" elements in this file in proportion to their display scaling (doubling font sizes for 200% scaling, etc.) For example, the top of an edited CSS file for the [https://github.com/adapta-project/adapta-gtk-theme Adapta] shell theme might look like:<br />
<br />
{{hc|usr/share/themes/Adapta/gnome-shell/gnome-shell.css|2=<br />
stage { font-size: 20pt; font-family: Roboto, Noto Sans, Sans-Serif; color: #263238; }<br />
}}<br />
<br />
Once these changes have been saved, activate them by switching to another theme (for example, using {{pkg|gnome-tweaks}}) and then reverting back again. The top bar, application menus, calendar, and other shell elements should now be correctly scaled.<br />
<br />
In addition to editing the relevant shell theme's CSS file, users on Xorg may also wish to increase the title bar font at the top of open applications. This can be done through the dconf editor ({{ic|org > gnome > desktop > wm > preferences :: titlebar-font}}). Note that the {{ic|title-bar-uses-system-fonts}} option should also be turned off. Alternatively, use gsettings:<br />
<br />
$ gsettings set org.gnome.desktop.wm.preferences titlebar-font 'Cantarell Bold 22' ## Change as needed<br />
$ gsettings set org.gnome.desktop.wm.preferences titlebar-uses-system-font false<br />
<br />
=== KDE Plasma ===<br />
<br />
You can use Plasma's settings to fine tune font, icon, and widget scaling. This solution affects both Qt and GTK applications.<br />
<br />
To adjust font, widget, and icon scaling together:<br />
<br />
# ''System Settings > Display and Monitor > Display Configuration > Scale Display''<br />
# Drag the slider to the desired size<br />
# Restart for the settings to take effect<br />
<br />
To adjust only font scaling:<br />
<br />
# ''System Settings > Fonts''<br />
# Check "Force fonts DPI" and adjust the DPI level to the desired value. This setting should take effect immediately for newly started applications. You will have to logout and login for it to take effect on Plasma desktop.<br />
<br />
To adjust only icon scaling:<br />
<br />
# ''System Settings > Icons > Advanced''<br />
# Choose the desired icon size for each category listed. This should take effect immediately.<br />
<br />
==== Tray icons with fixed size ====<br />
<br />
The tray icons are not scaled with the rest of the desktop, since Plasma ignores the Qt scaling settings by default. To make Plasma respect the Qt settings, set {{ic|PLASMA_USE_QT_SCALING}} to {{ic|1}}.<br />
<br />
=== Xfce ===<br />
<br />
Xfce supports HiDPI scaling which can be enabled using the settings manager:<br />
<br />
# Go to ''Settings Manager > Appearance > Settings > Window Scaling'' and select 2 as the scaling factor.<br />
# Go to ''Settings Manager > Window Manager > Style'' and select {{ic|Default-xhdpi}} theme.<br />
<br />
Alternatively, it is possible to do the same from command line using {{ic|xfconf-query}}:<br />
<br />
xfconf-query -c xsettings -p /Gdk/WindowScalingFactor -s 2<br />
xfconf-query -c xfwm4 -p /general/theme -s Default-xhdpi<br />
<br />
The steps above would set 2x scaled resolution for Xfce and other GTK 3 apps.<br />
<br />
Scaling for Qt 5 apps should be set manually, see [[#Qt 5]].<br />
<br />
=== Cinnamon ===<br />
<br />
Has good support out of the box.<br />
<br />
=== Enlightenment ===<br />
<br />
For E18, go to the E Setting panel. In ''Look > Scaling'', you can control the UI scaling ratios. A ratio of 1.2 seems to work well for the native resolution of the MBPr 15" screen.<br />
<br />
== X Resources ==<br />
<br />
If you are not using a desktop environment such as KDE, Xfce, or other that manipulates the X settings for you, you can set the desired DPI setting manually via the {{ic|Xft.dpi}} variable in [[Xresources]]:<br />
<br />
{{hc|~/.Xresources|2=<br />
Xft.dpi: 192<br />
<br />
! These might also be useful depending on your monitor and personal preference:<br />
Xft.autohint: 0<br />
Xft.lcdfilter: lcddefault<br />
Xft.hintstyle: hintfull<br />
Xft.hinting: 1<br />
Xft.antialias: 1<br />
Xft.rgba: rgb<br />
}}<br />
<br />
For {{ic|Xft.dpi}}, using integer multiples of 96 usually works best, e.g. 192 for 200% scaling.<br />
<br />
Make sure the settings are loaded properly when X starts, for instance in your {{ic|~/.xinitrc}} with {{ic|xrdb -merge ~/.Xresources}} (see [[Xresources]] for more information).<br />
<br />
This will make the font render properly in most toolkits and applications, it will however not affect things such as icon size!<br />
Setting {{ic|Xft.dpi}} at the same time as toolkit scale (e.g. {{ic|GDK_SCALE}}) may cause interface elements to be much larger than intended in some programs like firefox.<br />
<br />
== X Server ==<br />
<br />
{{Accuracy|{{Pkg|libxft}} is a ''font rendering interface library'', the {{ic|Xft.dpi}} setting was not intended to be abused by other applications. On the other hand, the {{ic|xorg.conf}} value should affect everything.}}<br />
<br />
Some programs may still interpret the DPI given by the X server (most interpret X Resources, though, directly or indirectly). Older versions of i3 (before 2017) and Chromium (before 2017) used to do this.<br />
<br />
To verify that the X Server has properly detected the physical dimensions of your monitor, use the ''xdpyinfo'' utility from the {{Pkg|xorg-xdpyinfo}} package:<br />
<br />
{{hc|$ xdpyinfo {{!}} grep -B 2 resolution|<br />
screen #0:<br />
dimensions: 3200x1800 pixels (423x238 millimeters)<br />
resolution: 192x192 dots per inch<br />
}}<br />
<br />
This example uses inaccurate dimensions (423mm x 328mm, even though the Dell XPS 9530 has 346mm x 194mm) to have a clean multiple of 96 dpi, in this case 192 dpi. This tends to work better than using the correct DPI — Pango renders fonts crisper in i3 for example.<br />
<br />
If the DPI displayed by xdpyinfo is not correct, see [[Xorg#Display size and DPI]] for how to fix it.<br />
<br />
== GUI toolkits ==<br />
<br />
=== Qt 5 ===<br />
<br />
Since Qt 5.6, Qt 5 applications can be instructed to honor screen DPI by setting the {{ic|QT_AUTO_SCREEN_SCALE_FACTOR}} environment variable:<br />
<br />
export QT_AUTO_SCREEN_SCALE_FACTOR=1<br />
<br />
If automatic detection of DPI does not produce the desired effect, scaling can be set manually per-screen ({{ic|QT_SCREEN_SCALE_FACTORS}}) or globally ({{ic|QT_SCALE_FACTOR}}). For more details see the [https://blog.qt.io/blog/2016/01/26/high-dpi-support-in-qt-5-6/ Qt blog post] or [https://doc.qt.io/qt-5/highdpi.html Qt developer documentation].<br />
<br />
{{Note|<br />
* If you manually set the screen factor, it is important to set {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} otherwise some applications which explicitly force high DPI enabling get scaled twice.<br />
* {{ic|QT_SCALE_FACTOR}} scales fonts, but {{ic|QT_SCREEN_SCALE_FACTORS}} does not scale fonts.<br />
* If you also set the font DPI manually in ''xrdb'' to support other toolkits, {{ic|QT_SCALE_FACTORS}} will give you huge fonts.<br />
* If you have multiple screens of differing DPI ie: [[#Side display]] you may need to do {{ic|1=QT_SCREEN_SCALE_FACTORS="2;2"}}<br />
}}<br />
<br />
An [https://bugreports.qt.io/browse/QTBUG-53022 alternative] is e.g.:<br />
<br />
QT_FONT_DPI=96 vym<br />
<br />
=== GDK 3 (GTK 3) ===<br />
<br />
{{Note|As stated in the [[#X Resources]] section, if you have xft.dpi set to a larger dpi, it will make other scales larger than usual, including GDK.}} <br />
<br />
Setting the GDK scale will scale the UI, however it will not scale icons. If you are using a minimal window manager where you are setting the dpi via Xft.dpi, GDK should scale perfectly fine with it. In other cases, [https://developer.gnome.org/gtk3/stable/gtk-x11.html do the following]:<br />
<br />
To scale UI elements by an integer factor:<br />
<br />
$ export GDK_SCALE=2<br />
<br />
To undo scaling of text, fractional scale can be used:<br />
<br />
$ export GDK_DPI_SCALE=0.5<br />
<br />
=== GTK 2 ===<br />
<br />
Scaling of UI elements is not supported by the toolkit itself, however it's possible to generate a theme with elements pre-scaled for HiDPI display using {{AUR|themix-full-git}}.<br />
<br />
=== Elementary (EFL) ===<br />
<br />
To scale UI elements by a factor of 1.5:<br />
<br />
export ELM_SCALE=1.5<br />
<br />
For more details see https://phab.enlightenment.org/w/elementary/<br />
<br />
=== GNUstep ===<br />
GNUstep applications that use its gui (AppKit) library accept a {{ic|GSScaleFactor}} property in their defaults (STEP preferences). To define a scaling factor of 1.5 for all apps:<br />
<br />
defaults write NSGlobalDomain GSScaleFactor 1.5<br />
<br />
Some automatic detection was possible back in 2011, but the code responsible for the X11 backend was [https://github.com/gnustep/libs-back/commit/337ce46bba304732d9a7c7495a3dd245a3219660 commented out] thereafter.<br />
<br />
== Boot managers ==<br />
<br />
=== GRUB ===<br />
<br />
==== Lower the framebuffer resolution ====<br />
<br />
Set a lower resolution for the framebuffer as explained in [[GRUB/Tips and tricks#Setting the framebuffer resolution]].<br />
<br />
==== Change GRUB font size ====<br />
<br />
Find a ttf font that you like in {{ic|/usr/share/fonts/}}.<br />
<br />
Convert the font to a format that GRUB can utilize:<br />
<br />
# grub-mkfont -s 30 -o /boot/grubfont.pf2 /usr/share/fonts/FontFamily/FontName.ttf<br />
<br />
{{Note|Change the {{ic|-s 30}} parameter to modify the font size}}<br />
<br />
Edit {{ic|/etc/default/grub}} to set the new font as shown in [[GRUB/Tips and tricks#Background image and bitmap fonts]]:<br />
<br />
GRUB_FONT="/boot/grubfont.pf2"<br />
<br />
{{Note|{{ic|GRUB_THEME}} overrides {{ic|GRUB_FONT}} if it is used.}}<br />
<br />
Finally [[GRUB#Generate the main configuration file|regenerate the main configuration file]].<br />
<br />
=== systemd-boot ===<br />
<br />
Adding the following line and running {{ic|bootctl update}} increases font-size in the [[systemd-boot#Loader_configuration|systemd-boot]] menu:<br />
<br />
{{hc|/boot/loader/loader.conf|2=<br />
console-mode 1<br />
}}<br />
<br />
== Applications ==<br />
<br />
If you are running a Wayland session, but application is running via Xwayland (either because it does not support Wayland natively or because it uses X11 by default), you could still get blurry fonts and interface, even if the application supports HiDPI. See [https://bugs.kde.org/show_bug.cgi?id=389191 this bug report].<br />
<br />
To determine if application is running via Xwayland, you can run [http://dodger-tools.sourceforge.net/cms/index.php?id=100000201 extramaus] and move a mouse over window of application. If red mouse moves, application is running via Xwayland. Alternatively, use {{pkg|xorg-xeyes}} and see if eyes are moving when moving mouse over application.<br />
<br />
=== Atom ===<br />
<br />
Add {{ic|1=--force-device-scale-factor=2}} as a flag to the atom.desktop file:<br />
<br />
{{hc|/usr/share/applications/atom.desktop|2=<br />
Exec=/usr/bin/atom --force-device-scale-factor=2 %F<br />
}}<br />
<br />
=== Browsers ===<br />
<br />
==== Firefox ====<br />
<br />
Firefox should use the [[#GDK 3 (GTK 3)]] settings. However, the suggested {{ic|GDK_SCALE}} suggestion does not consistently scale the entirety of Firefox, and does not work for fractional values (e.g., a factor of 158DPI/96DPI = 1.65 for a 1080p 14" laptop). You may want to use {{ic|GDK_DPI_SCALE}} instead. Another option, which will avoid Firefox-specific settings in many setups is to use the settings in [[#X Resources]] as Firefox should respect the {{ic|Xft.dpi}} value defined there.<br />
<br />
To override those, open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|layout.css.devPixelsPerPx}} to {{ic|2}} (or find the one that suits you better; {{ic|2}} is a good choice for Retina screens), but it also does not consistently scale the entirety of Firefox. <br />
<br />
If Firefox is not scaling fonts, you may want to create {{ic|userChrome.css}} and add appropriate styles to it. More information about {{ic|userChrome.css}} at [http://kb.mozillazine.org/index.php?title=UserChrome.css mozillaZine]. Starting from Firefox 69 the {{ic|userChrome.css}} and {{ic|userContent.css}} files are not loaded by default unless preference is set by the user. Open Firefox advanced preferences page ({{ic|about:config}}) and set parameter {{ic|toolkit.legacyUserProfileCustomizations.stylesheets}} to {{ic|True}}, then restart Firefox to apply the changes.<br />
<br />
{{hc|~/.mozilla/firefox/<em><profile></em>/chrome/userChrome.css|<br />
@namespace url("https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul");<br />
<br />
/* #tabbrowser-tabs, #navigator-toolbox, menuitem, menu, ... */<br />
* {<br />
font-size: 15px !important;<br />
}<br />
<br />
/* exception for badge on adblocker */<br />
.toolbarbutton-badge {<br />
font-size: 8px !important;<br />
}<br />
}}<br />
<br />
{{Warning|The AutoHiDPI extension is not compatible with Firefox Quantum (version 57 and above).}}<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use [https://addons.mozilla.org/en-US/firefox/addon/autohidpi/ AutoHiDPI]{{Dead link|2020|03|29|status=404}} add-on in order to automatically adjust {{ic|layout.css.devPixelsPerPx}} setting for the active screen. Also, since Firefox version 49, it auto-scales based on your screen resolution, making it easier to deal with 2 or more screens. For users of Firefox version 57 and above, the [https://addons.mozilla.org/firefox/addon/ffreszoom/ ffreszoom] add-on will adjust the page zoom if it detects you are using a large monitor (zoom level and threshold are configurable). Modifying the internal CSS DPI setting from an extension is currently unsupported [https://bugzilla.mozilla.org/show_bug.cgi?id=1373607].<br />
<br />
If you use Wayland, see [[Firefox#Wayland]] for instructions to enable the optional Wayland backend on {{pkg|firefox}}. This is also appicable to {{pkg|thunderbird}}.<br />
<br />
==== Chromium / Google Chrome ====<br />
<br />
Chromium should use the [[#GDK 3 (GTK 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--force-device-scale-factor}} flag with a scaling value. This will scale all content and ui, including tab and font size. For example {{ic|1=chromium --force-device-scale-factor=2}}.<br />
<br />
Using this option, a scaling factor of 1 would be normal scaling. Floating point values can be used. To make the change permanent, for Chromium, you can add it to {{ic|~/.config/chromium-flags.conf}}:<br />
<br />
{{hc|~/.config/chromium-flags.conf|2=<br />
--force-device-scale-factor=2<br />
}}<br />
<br />
To make this work for Chrome, add the same option to {{ic|~/.config/chrome-flags.conf}} instead.<br />
<br />
If you use a HiDPI monitor such as Retina display together with another monitor, you can use the [https://chrome.google.com/webstore/detail/resolution-zoom/enjjhajnmggdgofagbokhmifgnaophmh reszoom] extension in order to automatically adjust the zoom level for the active screen.<br />
<br />
See also [[Chromium#Incorrect HiDPI rendering]]. Note that using {{AUR|chromium-ozone}} in Wayland solves the blurry fonts problem, but has other issues. For example, in KDE it does not show the native window title bar.<br />
<br />
==== Opera ====<br />
<br />
Opera should use the [[#GDK 3 (GTK 3)]] settings.<br />
<br />
To override those, use the {{ic|1=--alt-high-dpi-setting=X}} command line option, where X is the desired DPI. For example, with {{ic|1=--alt-high-dpi-setting=144}} Opera will assume that DPI is 144. Newer versions of opera will auto detect the DPI using the font DPI setting (in KDE: the force font DPI setting.)<br />
<br />
=== Gimp 2.10 ===<br />
<br />
To fix toolbar icon sizes, update {{ic|1=Preferences->Interface->Icon Theme->Custom icon size}} to {{ic|1=huge}} or other value.<br />
<br />
If menu fonts are still too small you can update an existing theme by copying it from {{ic|/usr/share/gimp/2.0/themes}} into {{ic|~/.config/GIMP/2.10/themes/}} and changing {{ic|gtk-font-name}} and {{ic|font_name}} in {{ic|gtkrc}} into something bigger like {{ic|1=Sans 30}}. Then select the new theme from ''Preferences > Interface > Theme''. When copying make sure to rename the new directory into something different from the original name (example ''Dark > DarkHighDPI'').<br />
<br />
You can also try using [https://github.com/jedireza/gimp-hidpi gimp-hidpi] (installation instructions are outdated and refer to version 2.8, in Gimp 2.10 the theme should be installed into {{ic|~/.config/GIMP/2.10/themes/}})<br />
<br />
=== Inkscape ===<br />
<br />
To scale the icons to a "usable" size go to ''Preferences > Interface'' and set the icon size to Large or Larger[http://www.inkscapeforum.com/viewtopic.php?t=18684][http://wiki.inkscape.org/wiki/index.php/HiDPI].<br />
<br />
=== Java applications ===<br />
<br />
==== AWT/Swing ====<br />
<br />
Java applications using the ''AWT/Swing'' framework can be scaled by defining the {{ic|sun.java2d.uiScale}} VM property when invoking {{ic|java}}. The value can be an integer percentage value, or a float value. For example,<br />
<br />
java -Dsun.java2d.uiScale=2 -jar some_swing_application.jar<br />
java -Dsun.java2d.uiScale=300% -jar some_swing_application.jar<br />
<br />
Since Java 9 the {{ic|GDK_SCALE}} environment variable is used to scale Swing applications accordingly.<br />
<br />
Note that at this point, Java ''AWT/Swing'' (up to including OpenJDK 13) only effectively supports integer values. A setting of {{ic|1=-Dsun.java2d.uiScale=250%}} or {{ic|1=GDK_SCALE=2.5}} will be treated as if it were set to {{ic|1=-Dsun.java2d.uiScale=2}} resp. {{ic|1=GDK_SCALE=2}}.<br />
<br />
==== JavaFX ====<br />
<br />
Java applications using ''JavaFX'' can be scaled by defining the {{ic|glass.gtk.uiScale}} VM property when invoking {{ic|java}}. The value can be an integer percentage value, an integer DPI value (where {{ic|96dpi}} represents a scale factor of {{ic|100%}}, and for example {{ic|192dpi}} represents a scale factor of {{ic|200%}}), or a float value. For example,<br />
<br />
java -Dglass.gtk.uiScale=200% -jar some_jfx_application.jar<br />
java -Dglass.gtk.uiScale=192dpi -jar some_jfx_application.jar<br />
java -Dglass.gtk.uiScale=2.0 -jar some_jfx_application.jar<br />
<br />
''JavaFX'' perfectly well supports fractions. Using values like {{ic|1=-Dglass.gtk.uiScale=250%}} or {{ic|1=-Dglass.gtk.uiScale=2.5}} will deliver the expected result.<br />
<br />
==== Mixed AWT/Swing and JavaFX ====<br />
<br />
Some Java applications mix ''JavaFX'' and ''AWT/Swing'' (via {{ic|javafx.embed.swing.JFXPanel}}). In that case, the settings for ''AWT/Swing'' will also affect ''JavaFX'', and setting {{ic|-Dglass.gtk.uiScale}} will have no effect.<br />
<br />
==== IntelliJ IDEA ====<br />
<br />
IntelliJ IDEA supports two HiDPI modes (JRE-managed and IDE-managed). The sequence for determining system scale factor is well documented at [https://intellij-support.jetbrains.com/hc/en-us/articles/360007994999-HiDPI-configuration]:<br />
<br />
# Java property – {{ic|-Dsun.java2d.uiScale}}<br />
# {{man|1|gsettings}} – {{ic|ubuntu.user-interface/scale-factor}} or {{ic|org.gnome.desktop.interface/scaling-factor}}<br />
# {{ic|GDK_SCALE}} and {{ic|GDK_DPI_SCALE}}<br />
# [[Xresources]] – {{ic|Xft.dpi}}<br />
# 1.0<br />
<br />
For troubleshooting, consult the "Show HiDPI Info" dialog via [https://www.jetbrains.com/help/idea/searching-everywhere.html search everywhere <kbd>Shift Shift</kbd>].<br />
<br />
=== MATLAB ===<br />
<br />
Recent versions (R2017b) of [[MATLAB]] allow to set the scale factor[https://www.mathworks.com/matlabcentral/answers/406956-does-matlab-support-high-dpi-screens-on-linux]:<br />
<br />
>> s = settings;s.matlab.desktop.DisplayScaleFactor<br />
>> s.matlab.desktop.DisplayScaleFactor.PersonalValue = 2<br />
<br />
The settings take effect after MATLAB is restarted.<br />
<br />
=== Mono applications ===<br />
<br />
According to [https://bugzilla.xamarin.com/show_bug.cgi?id=35870], Mono applications should be scalable like [[#GDK 3 (GTK 3)|GTK 3]] applications. The precise method depends on the GUI library: GtkSharp obviouslys points back to Gtk, while the usual Windows Forms (libgdiplus) simply detects Xft settings.<br />
<br />
=== NetBeans ===<br />
<br />
NetBeans allows the font size of its interface to be controlled using the {{ic|1=--fontsize}} parameter during startup. To make this change permanent edit the {{ic|1=/usr/share/netbeans/etc/netbeans.conf}} file and append the {{ic|1=--fontsize}} parameter to the {{ic|1=netbeans_default_options}} property.[http://wiki.netbeans.org/FaqFontSize]<br />
<br />
The editor fontsize can be controlled from ''Tools > Option > Fonts & Colors''.<br />
<br />
The output window fontsize can be controlled from ''Tools > Options > Miscelaneous > Output''<br />
<br />
=== OBS Studio ===<br />
<br />
Start obs with the environment variable {{ic|1=QT_AUTO_SCREEN_SCALE_FACTOR=0}} to disable [https://doc.qt.io/qt-5/highdpi.html#migrate-existing-applications Qt’s hi-dpi migration mode]. It is partially buggy (preview window can disappear after first start, depending on window position) and prevents OBS Studio from capturing at native resolution.<br />
<br />
The downside of this option is that the UI elements will now be messed up. To mitigate this, install the Yami theme, which works well on hi-dpi displays:<br />
<br />
{{Accuracy|Installation from archive other than the source of the {{Pkg|obs-studio}} package is not supported.}}<br />
<br />
$ wget https://github.com/obsproject/obs-studio/archive/fd256a46837033b9a4632327ece3c572bcb3b9b1.tar.gz -O /tmp/yami.tar.gz<br />
$ cd ~/.config/obs-studio<br />
$ tar xf /tmp/yami.tar.gz --strip-components=3 --wildcards '*/UI/data/themes/Yami*'<br />
<br />
Then, open File → Settings → General → Theme and chose Yami.<br />
<br />
=== Skype ===<br />
<br />
Skype for Linux ({{AUR|skypeforlinux-stable-bin}} package) uses [[#GDK 3 (GTK 3)]].<br />
<br />
=== Slack ===<br />
<br />
Slack ({{AUR|slack-desktop}}), like all [https://electronjs.org/ Electron] apps, can be configured to use a custom scaling value by adding a {{ic|1=--force-device-scale-factor}} flag to the .desktop file. This is normally located at {{ic|/usr/share/applications/}}. The flag should be added to the line beginning with "Exec=". For example:<br />
<br />
{{hc|/usr/share/applications/slack.desktop|2=<br />
Exec=env LD_PRELOAD=/usr/lib/libcurl.so.3 /usr/bin/slack --force-device-scale-factor=1.5 %U<br />
}}<br />
<br />
=== Spotify ===<br />
<br />
You can change scale factor by simple {{ic|Ctrl++}} for zoom in, {{ic|Ctrl+-}} for zoom out and {{ic|Ctrl+0}} for default scale. Scaling setting will be saved in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, you may have to create this file by yourself:<br />
<br />
{{hc|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs|2=<br />
app.browser.zoom-level=100<br />
}}<br />
<br />
Also Spotify can be launched with a custom scaling factor which will be multiplied with setting specified in {{ic|~/.config/spotify/Users/YOUR-SPOTIFY-USER-NAME/prefs}}, for example<br />
<br />
$ spotify --force-device-scale-factor=1.5<br />
<br />
=== Steam ===<br />
<br />
==== Official HiDPI support ====<br />
<br />
* Starting on 25 of January 2018 in the beta program there is actual support for HiDPI and it should be automatically detected.<br />
* ''Steam > Settings > Interface'', check "Enlarge text and icons based on monitor size" (restart required)<br />
* If it not automatically detected use {{ic|1=GDK_SCALE=2}} to set the desired scale factor.<br />
<br />
==== Unofficial ====<br />
<br />
The [https://github.com/MoriTanosuke/HiDPI-Steam-Skin HiDPI-Steam-Skin] can be installed to increase the font size of the interface. While not perfect, it does improve usability. <br />
<br />
{{Note|The README for the HiDPI skin lists several possible locations for where to place the skin. The correct folder out of these can be identified by the presence of a file named {{ic|1=skins_readme.txt}}.}}<br />
<br />
[http://steamcommunity.com/groups/metroskin/discussions/0/517142253861033946/ MetroSkin Unofficial Patch] also helps with HiDPI on Steam with Linux.<br />
<br />
=== Sublime Text 3 ===<br />
<br />
Sublime Text 3 has full support for display scaling. Go to ''Preferences > Settings > User Settings'' and add {{ic|"ui_scale": 2.0}} to your settings.<br />
<br />
=== Thunderbird ===<br />
<br />
See [[#Firefox]]. To access {{ic|about:config}}, go to ''Edit > Preferences > Advanced >Config editor''.<br />
<br />
=== VirtualBox ===<br />
<br />
{{Note|This only applies to KDE with scaling enabled.}}<br />
<br />
VirtualBox also applies the system-wide scaling to the virtual monitor, which reduces the maximum resolution inside VMs by your scaling factor (see [https://www.virtualbox.org/ticket/16604]).<br />
<br />
This can be worked around by calculating the inverse of your scaling factor and manually setting this new scaling factor for the VirtualBox execution, e.g.<br />
<br />
$ QT_SCALE_FACTOR=0.5 VirtualBox --startvm vm-name<br />
<br />
=== Wine applications ===<br />
<br />
Run<br />
<br />
$ winecfg<br />
<br />
and change the "dpi" setting found in the "Graphics" tab. This only affects the font size.<br />
<br />
=== Zathura document viewer ===<br />
<br />
No modifications required for document viewing.<br />
<br />
UI text scaling is specified via [https://pwmt.org/projects/zathura/documentation/ configuration file] (note that "font" is a [https://pwmt.org/projects/girara/options/ girara option]):<br />
<br />
set font "monospace normal 20"<br />
<br />
=== Zoom ===<br />
<br />
Set the {{ic|scaleFactor}} variable in {{ic|~/.config/zoomus.conf}}.<br />
<br />
=== Unsupported applications ===<br />
<br />
{{AUR|run_scaled-git}} can be used to scale applications (which uses {{Pkg|xpra}} internally).<br />
<br />
Another approach is to run the application full screen and without decoration in its own VNC desktop. Then scale the viewer. With Vncdesk ({{AUR|vncdesk-git}} from the [[AUR]]) you can set up a desktop per application, then start server and client with a simple command such as {{ic|vncdesk 2}}.<br />
<br />
[[x11vnc]] has an experimental option {{ic|-appshare}}, which opens one viewer per application window. Perhaps something could be hacked up with that.<br />
<br />
== Multiple displays ==<br />
<br />
The HiDPI setting applies to the whole desktop, so non-HiDPI external displays show everything too large. However, note that setting different scaling factors for different monitors is already supported in [[Wayland]].<br />
<br />
=== Side display ===<br />
<br />
One workaround is to use [[xrandr]]'s scale option. To have a non-HiDPI monitor (on DP1) right of an internal HiDPI display (eDP1), one could run:<br />
<br />
$ xrandr --output eDP-1 --auto --output DP-1 --auto --scale 2x2 --right-of eDP-1<br />
<br />
When extending above the internal display, you may see part of the internal display on the external monitor. In that case, specify the position manually.<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
{{Note|1=Above solution with {{ic|--scale 2x2}} does not work on some Nvidia cards. No solution is currently available. [https://bbs.archlinux.org/viewtopic.php?pid=1670840] A potential workaround exists with configuring {{ic|1=ForceFullCompositionPipeline=On}} on the {{ic|CurrentMetaMode}} via {{ic|nvidia-settings}}. For more info see [https://askubuntu.com/a/979551/763549].}}<br />
<br />
{{Note|If you are using the {{ic|modesetting}} driver you will get mouse flickering. This can be solved by scaling your non-scaled screen by 0.9999x0.9999.}}<br />
<br />
=== Multiple external monitors ===<br />
<br />
There might be some problems in scaling more than one external monitors which have lower dpi than the built-in HiDPI display. In that case, you may want to try downscaling the HiDPI display instead, with e.g.<br />
<br />
$ xrandr --output eDP1 --scale 0.5x0.5 --output DP2 --right-of eDP1 --output HDMI1 --right-of DP2<br />
<br />
In addition, when you downscale the HiDPI display, the font on the HiDPI display will be slightly blurry, but it's a different kind of bluriness compared with the one introduced by upscaling the external displays. You may compare and see which kind of bluriness is less problematic for you.<br />
<br />
=== Mirroring ===<br />
<br />
If all you want is to mirror ("unify") displays, this is easy as well:<br />
<br />
With AxB your native HiDPI resolution (for ex 3200x1800) and CxD your external screen resolution (e.g. 1920x1200)<br />
<br />
$ xrandr --output HDMI --scale [A/C]x[B/D]<br />
<br />
In this example which is QHD (3200/1920 = 1.66 and 1800/1200 = 1.5)<br />
<br />
$ xrandr --output HDMI --scale 1.66x1.5<br />
<br />
For UHD to 1080p (3840/1920=2 2160/1080=2)<br />
<br />
$ xrandr --output HDMI --scale 2x2<br />
<br />
You may adjust the "sharpness" parameter on your monitor settings to adjust the blur level introduced with scaling.<br />
<br />
=== Tools ===<br />
<br />
There are several tools which automate the commands described above.<br />
<br />
* [https://gist.github.com/wvengen/178642bbc8236c1bdb67 This script] extend a non-HiDPI external display above a HiDPI internal display.<br />
* [https://github.com/ashwinvis/xrandr-extend xrandr-extend].<br />
* {{AUR|xlayoutdisplay}} is a CLI front end for xrandr which detects and sets correct DPI: [https://github.com/alex-courtis/xlayoutdisplay README]<br />
<br />
== Linux console ==<br />
<br />
The [[w:Linux console|Linux console]] changes the font to {{ic|TER16x32}} (based on {{ic|ter-i32b}} from {{Pkg|terminus-font}}[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ac8b6f148fc97e9e10b48bd337ef571b1d1136aa]) accordingly based on the resolution of the display. If your monitor is not recognised as HiDPI, the default font can be changed. In that case, specify {{ic|1=fbcon=font:TER16x32}} in the [[kernel command line]].<br />
<br />
=== Fonts outside the kernel ===<br />
<br />
The largest fonts present in the {{Pkg|kbd}} package are {{ic|latarcyrheb-sun32}} and {{ic|solar24x32}}. Other packages like {{Pkg|terminus-font}} contain further alternatives, such as {{ic|ter-132n}} (normal) and {{ic|ter-132b}} (bold). See [[Linux console#Fonts]] for configuration details and [[Linux console#Persistent configuration]] in particular for applying the font setting during the early userspace boot sequence.<br />
<br />
After changing the font, it is often garbled and unreadable when changing to other virtual consoles ({{ic|tty2-6}}). To fix this you can [[Kernel_mode_setting#Forcing_modes_and_EDID|force specific mode]] for KMS, such as {{ic|1=video=2560x1600@60}} (substitute in the native resolution of your HiDPI display), and reboot.<br />
<br />
Users booting though [[UEFI]] may experience the console and [[boot loader]] being constrained to a low resolution despite correct [[KMS]] settings being set. This can be caused by legacy/BIOS boot being enabled in UEFI settings. Disabling legacy boot to bypass the compatibility layer should allow the system to boot at the correct resolution.<br />
<br />
== See also ==<br />
<br />
* [http://www.phoronix.com/scan.php?page=article&item=linux_uhd4k_gpus Ultra HD 4K Linux Graphics Card Testing] (Nov 2013)<br />
* [http://www.eizo.com/library/basics/pixel_density_4k/ Understanding pixel density]<br />
* [http://wok.oblomov.eu/tecnologia/mixed-dpi-x11/ Mixed DPI and the X Window System]</div>Simon04https://wiki.archlinux.org/index.php?title=Domain_name_resolution&diff=639579Domain name resolution2020-10-24T08:45:13Z<p>Simon04: /* Third-party DNS services */ +cloudflared</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[de:Resolv.conf]]<br />
[[es:Domain name resolution]]<br />
[[fr:Resolv.conf]]<br />
[[it:Domain name resolution]]<br />
[[ja:ドメイン名前解決]]<br />
[[pt:Domain name resolution]]<br />
[[zh-hans:Domain name resolution]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|DNS over HTTPS servers}}<br />
{{Related articles end}}<br />
In general, a [[Wikipedia:Domain name|domain name]] represents an IP address and is associated to it in the [[Wikipedia:Domain Name System|Domain Name System]] (DNS).<br />
This article explains how to configure domain name resolution and resolve domain names.<br />
<br />
== Name Service Switch ==<br />
<br />
{{Expansion|Mention {{Pkg|nss-mdns}}, {{AUR|nss-tls-git}} and others.}}<br />
<br />
The [[Wikipedia:Name Service Switch|Name Service Switch]] (NSS) facility is part of the GNU C Library ({{Pkg|glibc}}) and backs the {{man|3|getaddrinfo}} API, used to resolve domain names. NSS allows system databases to be provided by separate services, whose search order can be configured by the administrator in {{man|5|nsswitch.conf}}. The database responsible for domain name resolution is the ''hosts'' database, for which glibc offers the following services:<br />
<br />
* ''file'': reads the {{ic|/etc/hosts}} file, see {{man|5|hosts}}<br />
* ''dns'': the [[#Glibc resolver|glibc resolver]] which reads {{ic|/etc/resolv.conf}}, see {{man|5|resolv.conf}}<br />
<br />
[[Systemd]] provides three NSS services for hostname resolution:<br />
<br />
* {{man|8|nss-resolve}} - a caching DNS stub resolver, described in [[systemd-resolved]]<br />
* {{man|8|nss-myhostname}} - provides hostname resolution without having to edit {{ic|/etc/hosts}}, described in [[Network configuration#Local hostname resolution]]<br />
* {{man|8|nss-mymachines}} - provides hostname resolution for the names of local {{man|8|systemd-machined}} containers <br />
<br />
=== Resolve a domain name using NSS ===<br />
<br />
NSS databases can be queried with {{man|1|getent}}. A domain name can be resolved through NSS using:<br />
<br />
$ getent hosts ''domain_name''<br />
<br />
{{Note|While most programs resolve domain names using NSS, some may read {{ic|/etc/resolv.conf}} and/or {{ic|/etc/hosts}} directly. See [[Network configuration#Local hostname resolution]].}}<br />
<br />
== Glibc resolver ==<br />
<br />
The glibc resolver reads {{ic|/etc/resolv.conf}} for every resolution to determine the nameservers and options to use. <br />
<br />
{{man|5|resolv.conf}} lists nameservers together with some configuration options.<br />
Nameservers listed first are tried first, up to three nameservers may be listed. Lines starting with a number sign ({{ic|#}}) are ignored.<br />
<br />
{{Note|The glibc resolver does not cache queries. To improve query lookup time you can set up a caching resolver. Glibc resolver also can not validate DNSSEC. A DNSSEC capable validator resolver is required for that one. See [[#DNS servers]] for more information.}}<br />
<br />
=== Overwriting of /etc/resolv.conf ===<br />
<br />
[[Network manager]]s tend to overwrite {{ic|/etc/resolv.conf}}, for specifics see the corresponding section:<br />
<br />
* [[dhcpcd#/etc/resolv.conf]]<br />
* [[netctl#resolv.conf]]<br />
* [[NetworkManager#/etc/resolv.conf]]<br />
<br />
To prevent programs from overwriting {{ic|/etc/resolv.conf}}, it is also possible to write-protect it by setting the immutable [[file attribute]]:<br />
<br />
# chattr +i /etc/resolv.conf<br />
<br />
{{Tip|If you want multiple processes to write to {{ic|/etc/resolv.conf}}, you can use [[resolvconf]].}}<br />
<br />
=== Limit lookup time ===<br />
<br />
If you are confronted with a very long hostname lookup (may it be in [[pacman]] or while browsing), it often helps to define a small timeout after which an alternative nameserver is used. To do so, put the following in {{ic|/etc/resolv.conf}}.<br />
<br />
options timeout:1<br />
<br />
=== Hostname lookup delayed with IPv6 ===<br />
<br />
If you experience a 5 second delay when resolving hostnames it might be due to a DNS-server/Firewall misbehaving and only giving one reply to a parallel A and AAAA request.[https://udrepper.livejournal.com/20948.html] You can fix that by setting the following option in {{ic|/etc/resolv.conf}}:<br />
<br />
options single-request<br />
<br />
=== Local domain names ===<br />
<br />
To be able to use the hostname of local machine names without the fully qualified domain name, add a line to {{ic|/etc/resolv.conf}} with the local domain such as:<br />
domain example.org<br />
That way you can refer to local hosts such as {{ic|mainmachine1.example.org}} as simply {{ic|mainmachine1}} when using the ''ssh'' command, but the [[#Lookup utilities|drill]] command still requires the fully qualified domain names in order to perform lookups.<br />
<br />
== Lookup utilities ==<br />
<br />
To query specific DNS servers and DNS/[[DNSSEC]] records you can use dedicated DNS lookup utilities. These tools implement DNS themselves and do not use [[#Name Service Switch|NSS]].<br />
<br />
{{Pkg|ldns}} provides {{man|1|drill}}, which is a tool designed to retrieve information out of the DNS.<br />
<br />
For example, to query a specific nameserver with ''drill'' for the TXT records of a domain:<br />
<br />
$ drill @''nameserver'' TXT ''domain''<br />
<br />
Unless a DNS server is specified, ''drill'' will use the nameservers defined in {{ic|/etc/resolv.conf}}.<br />
<br />
{{Tip|Some DNS servers ship with their own DNS lookup utilities. E.g.<br />
<br />
* {{Pkg|knot}} provides {{man|1|khost}} and {{man|1|kdig}}.<br />
* [[Unbound]] has {{man|1|unbound-host}}.<br />
* [[BIND]] has {{man|1|dig}}, {{man|1|host}}, {{man|1|nslookup}} and a bunch of {{ic|dnssec-}} tools.<br />
<br />
}}<br />
<br />
== Resolver performance ==<br />
<br />
The Glibc resolver does not cache queries. To implement local caching, use [[systemd-resolved]] or set up a local caching [[#DNS servers|DNS server]] and use it as the name server by setting {{ic|127.0.0.1}} and {{ic|::1}} as the name servers in {{ic|/etc/resolv.conf}} or in {{ic|/etc/resolvconf.conf}} if using [[openresolv]].<br />
<br />
{{Tip|<br />
* The ''drill'' or ''dig'' [[#Lookup utilities|lookup utilities]] report the query time.<br />
* A router usually sets its own caching resolver as the network's DNS server thus providing DNS cache for the whole network. <br />
* If it takes too long to switch to the next DNS server you can try [[#Limit lookup time|decreasing the timeout]].}}<br />
<br />
== Privacy and security ==<br />
<br />
The DNS protocol is unencrypted and does not account for confidentiality, integrity or authentication, so if you use an untrusted network or a malicious ISP, your DNS queries can be eavesdropped and the responses [[Wikipedia:Man-in-the-middle attack|manipulated]]. Furthermore, DNS servers can conduct [[Wikipedia:DNS hijacking|DNS hijacking]].<br />
<br />
You need to trust your DNS server to treat your queries confidentially. DNS servers are provided by ISPs and [[#Third-party DNS services|third-parties]]. Alternatively you can run your own [[#DNS servers|recursive name server]], which however takes more effort. If you use a [[DHCP]] client in untrusted networks, be sure to set static name servers to avoid using and being subject to arbitrary DNS servers. To secure your communication with a remote DNS server you can use an encrypted protocol, like [[Wikipedia:DNS over TLS|DNS over TLS]] ([[RFC:7858|RFC 7858]]), [[Wikipedia:DNS over HTTPS|DNS over HTTPS]] ([[RFC:8484|RFC 8484]]), or [[Wikipedia:DNSCrypt|DNSCrypt]], provided that both the upstream server and your [[#DNS servers|resolver]] support the protocol. An alternative can be a dedicated software to encrypt and decrypt the communication, such as [[stunnel]]. To verify that responses are actually from [[Wikipedia:Authoritative name server|authoritative name servers]], you can validate [[DNSSEC]], provided that both the upstream server(s) and your [[#DNS servers|resolver]] support it.<br />
<br />
=== Application-level DNS ===<br />
<br />
Be aware that some client software, such as major web browsers[https://hacks.mozilla.org/2018/05/a-cartoon-intro-to-dns-over-https/#trr-and-doh][https://www.chromium.org/developers/dns-over-https], are starting to implement DNS over HTTPS. While the encryption of queries may often be seen as a bonus, it also means the software sidetracks queries around the system resolver configuration.[https://blog.powerdns.com/2019/09/25/centralised-doh-is-bad-for-privacy-in-2019-and-beyond/]<br />
<br />
[https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https Mozilla has proposed] disabling application-level DNS if the system resolver cannot resolve the domain "[http://use-application-dns.net/ use-application-dns.net]". Currently this check is only implemented in [[Firefox]].<br />
<br />
{{Expansion|Explain why is it necessary or what are the benefits of configuring DNS over HTTPS in web browsers over running a [[#DNS servers|stub resolver]].}}<br />
<br />
==== Configuring DNS over HTTPS in Firefox ====<br />
<br />
In order to configure DNS over HTTPS in [[Firefox]], follow the [https://support.mozilla.org/en-US/kb/firefox-dns-over-https official instructions].<br />
<br />
== Third-party DNS services ==<br />
<br />
{{Note|Before using a third-party DNS service, check its privacy policy for information on how user data is handled. User data has value and can be sold to other parties.}}<br />
<br />
There are various [[Wikipedia:Public recursive name server#List of public DNS service operators|third-party DNS services]] available, some of which also have dedicated software:<br />
<br />
* {{App|cloudflared|A DoH client for Coudflare|https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy|{{AUR|cloudflared}}{{AUR|cloudflared-bin}}}}<br />
* {{App|dingo|A DNS client for Google DNS over HTTPS|https://github.com/pforemski/dingo|{{AUR|dingo-git}}}}<br />
* {{App|opennic-up|Automates the renewal of the DNS servers with the most responsive OpenNIC servers|https://github.com/kewlfft/opennic-up|{{AUR|opennic-up}}}}<br />
<br />
== DNS servers ==<br />
<br />
[[DNS]] servers can be [[Wikipedia:Authoritative name server|authoritative]] and [[Wikipedia:Name server#Recursive query|recursive]]. If they are neither, they are called '''stub resolvers''' and simply forward all queries to another recursive name server. Stub resolvers are typically used to introduce DNS caching on the local host or network. Note that the same can also be achieved with a fully-fledged name server. This section compares the available DNS servers, for a more detailed comparison, refer to [[Wikipedia:Comparison of DNS server software]].<br />
<br />
{{Expansion|Fill in the unknowns.}}<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! rowspan=2 | Name !! rowspan=2 | Package !! colspan=4 | Capabilities !! rowspan=2 | [[resolvconf]] !! colspan=4 | Supported protocols<br />
|-<br />
! [[Wikipedia:Authoritative name server|Authoritative]] !! [[Wikipedia:Name server#Recursive query|Recursive]] !! [[Wikipedia:Name server#Caching name server|Cache]] !! [[Wikipedia:Domain Name System Security Extensions#The lookup procedure|Validates]]<br>[[DNSSEC]] !! [[Wikipedia:Domain Name System|DNS]] !! [[Wikipedia:DNSCrypt|DNSCrypt]] !! [[Wikipedia:DNS over TLS|DNS<br>over TLS]] !! [[Wikipedia:DNS over HTTPS|DNS<br>over HTTPS]]<br />
|-<br />
! [[dnscrypt-proxy]]<br />
| {{Pkg|dnscrypt-proxy}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{Y|Server}} || {{Y|Resolver}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Rescached]]<br />
| {{AUR|rescached-git}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Yes|https://github.com/shuLhan/rescached-go#integration-with-openresolv}} || {{Yes}} || {{No}} || {{No}} || {{Y|Limited}}<sup>1</sup><br />
|-<br />
! [[Stubby]]<br />
| {{Pkg|stubby}} || {{No}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Y|Server}} || {{No}} || {{Y|Resolver}} || {{No}}<br />
|-<br />
!style="white-space: nowrap;"| [[systemd-resolved]]<br />
| {{Pkg|systemd}} || {{No}} || {{No}} || {{Yes}} || {{Yes}} || {{G|[[systemd-resolvconf|Yes]]}} || {{Y|Resolver and [https://github.com/systemd/systemd/issues/4621#issuecomment-260050033 limited server]}} || {{No}} || {{Y|Resolver}} || {{No|https://github.com/systemd/systemd/issues/8639}}<br />
|-<br />
! [[dnsmasq]]<br />
| {{Pkg|dnsmasq}} || {{Y|Partial}}<sup>2</sup> || {{No}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No|http://lists.thekelleys.org.uk/pipermail/dnsmasq-discuss/2018q2/012131.html}} || {{No}}<br />
|-<br />
! [[Unbound]]<br />
| {{Pkg|unbound}} || {{Y|Partial}} || {{Yes}} || {{Yes}}<sup>3</sup> || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{Y|Server}} || {{Yes}} || {{No|1=https://nlnetlabs.nl/bugs-script/show_bug.cgi?id=1200}}<br />
|-<br />
! [[BIND]]<br />
| {{Pkg|bind}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{Y|[[stunnel#DNS over TLS]]}}|| {{No}}<br />
|-<br />
! [[pdnsd]]<br />
| {{Pkg|pdnsd}} || {{Yes}} || {{Yes}} || {{G|Permanent}} || {{No}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Knot Resolver]]<br />
| {{AUR|knot-resolver}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Y|[https://knot-resolver.readthedocs.io/en/stable/modules-http-doh.html Server]}}<br />
|-<br />
! [http://maradns.samiam.org/deadwood/doc/Deadwood.html Deadwood] ([[Wikipedia:MaraDNS|MaraDNS]] recursor)<br />
| {{AUR|maradns}} || {{No}} || {{Yes}} || {{Yes}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Wikipedia:PowerDNS#Recursor|PowerDNS Recursor]]<br />
| {{Pkg|powerdns-recursor}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [https://github.com/pymumu/smartdns SmartDNS]<br />
| {{Pkg|smartdns}} || {{No}} || {{No}} || {{Yes}} || {{No|https://github.com/pymumu/smartdns/issues/19}} || ? || {{Yes}} || {{No}} || {{Y|Resolver}} || {{Y|Resolver}}<br />
|-<br />
! [https://coredns.io/ CoreDNS]<br />
| {{AUR|coredns}} or {{AUR|coredns-bin}} || ? || ? || ? || ? || ? || ? || ? || ? || ?<br />
|}<br />
<br />
# Only forwards using DNS over HTTPS when Rescached itself is queried using DNS over HTTPS.[https://github.com/shuLhan/rescached-go#integration-with-dns-over-https]<br />
# From [[Wikipedia:Comparison of DNS server software#cite_note-masqauth-30|Wikipedia]]: dnsmasq has limited authoritative support, intended for internal network use rather than public Internet use.<br />
# The [[Redis]] backend can be used to provide a persistent cache for Unbound.<br />
<br />
=== Authoritative-only servers ===<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! Name !! Package !! [[DNSSEC]] !! Geographic<br>balancing<br />
|-<br />
! gdnsd<br />
| {{Pkg|gdnsd}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Wikipedia:Knot DNS|Knot DNS]]<br />
| {{Pkg|knot}} || {{Yes}} || {{Yes|https://www.knot-dns.cz/docs/2.7/singlehtml/#geoip-geography-based-responses}}<br />
|-<br />
! [[Wikipedia:MaraDNS|MaraDNS]]<br />
| {{AUR|maradns}} || {{No}} || ?<br />
|-<br />
! [[NSD]]<br />
| {{Pkg|nsd}} || {{No}} || {{No}}<br />
|-<br />
! [[PowerDNS]]<br />
| {{Pkg|powerdns}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
=== Conditional forwarding ===<br />
<br />
It is possible to use specific DNS resolvers when querying specific domain names. This is particularly useful when connecting to a VPN, so that queries to the VPN network are resolved by the VPN's DNS, while queries to the internet will still be resolved by your standard DNS resolver. It can also be used on local networks.<br />
<br />
To implement it, you need to use a [[#DNS servers|local resolver]] because glibc does not support it.<br />
<br />
In a dynamic environment (laptops and to some extents desktops), you need to configure your resolver based on the network(s) you are connected to. The best way to do that is to use [[openresolv]] because it supports [[openresolv#Subscribers|multiple subscribers]]. Some [[network manager]]s support it, either through openresolv, or by configuring the resolver directly. NetworkManager [[NetworkManager#DNS caching and conditional forwarding|supports conditional forwarding without openresolv]].<br />
<br />
{{Note|Although you could use other conditions for forwarding (for example, source IP address), "conditional forwarding" appears to be the name used for the "domain queried" condition.}}<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/x-087-2-resolv.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-handbook/sect.hostname-name-service.en.html#sect.name-resolution Debian Handbook]<br />
* [[RFC:7706]] - Decreasing Access Time to Root Servers by Running One on Loopback<br />
* [http://linux-ip.net/pages/diagrams.html#domain-name-system-overview Domain name system overview] - Diagram about DNS<br />
* [[Alternative DNS services]]</div>Simon04https://wiki.archlinux.org/index.php?title=Flashing_BIOS_from_Linux&diff=639373Flashing BIOS from Linux2020-10-22T07:11:50Z<p>Simon04: /* Using a windows PE */ typo</p>
<hr />
<div>[[Category:Mainboards and BIOS]]<br />
[[ja:Linux から BIOS を書き換える]]<br />
This article aims on providing information on flashing your system BIOS under Linux. Most manufacturers provide a Windows executable or a BIOS executable that can only be run under Windows. However, there are a few utilities that allow you to upgrade your system BIOS under Linux.<br />
<br />
{{Warning|Flashing motherboard BIOS is a dangerous activity that can render your motherboard inoperable! While the author of this article has successfully run this procedure many times, your mileage may vary. Be careful! You may want to consider updating [[microcode]] instead if it is supported by your system.}}<br />
<br />
{{Note|<br />
* HP users may download Windows BIOS updater from HP website, extract *.exe file and locate ISO image for burning to a CD. Using CD, upgrade is possible from BIOS menu using 'Firmware Upgrade' without using below tools. See [https://h30434.www3.hp.com/t5/Notebook-Operating-System-and-Recovery/How-to-update-BIOS-on-Linux/td-p/4869835 this] thread for details.<br />
* For users with Dell computers, Dell recommends Linux users flash their BIOS following information located [https://www.dell.com/support/article/us/en/19/sln171755/updating-the-dell-bios-in-linux-and-ubuntu-environments here] (in short, put the .EXE on a USB stick and use the F12 boot menu to access the firmware's flash utility).<br />
}}<br />
<br />
== fwupd ==<br />
<br />
fwupd is a simple daemon to allow session software to update device firmware on your local machine.<br />
<br />
Large vendors including Dell and Logitech use this way to distribute firmware updates to Linux.<br />
<br />
fwupd only supports flashing BIOS updates in UEFI mode.<br />
<br />
See [[fwupd]] for further information about installation and usage.<br />
<br />
== BiosDisk ==<br />
<br />
[https://github.com/dell/biosdisk BiosDisk] simplifies the process of flashing your system BIOS under Linux.<br />
<br />
{{Note|This is only supported on systems when booted in "Legacy mode". In UEFI mode you will need to use a different method.}}<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{AUR|biosdisk-git}} package.<br />
<br />
=== Usage ===<br />
<br />
To use the biosdisk utility to create a BIOS flash image, first download the latest raw BIOS image for your system from your manufacturer's website. Make sure however, that you always get the BIOS executable and NOT the Windows executable. You then have one of two options: create a ISO or install the image for your bootloader.<br />
<br />
* The mkimage action will create a ISO image on the user's hard drive. Usage is the following:<br />
<br />
# biosdisk mkimage [-o option] [-i destination] /path/to/.exe <br />
<br />
* The install action will create the biosdisk image, copy the image file to /boot, and then update the bootloader with an entry for the image. Then all the user has to do is boot the system and select the image to flash the BIOS; this will load the biosdisk image directly from the hard drive and flash the BIOS.<br />
<br />
# biosdisk install [-o option] [--name=] /path/to/.exe<br />
<br />
== Flashrom ==<br />
<br />
[http://www.flashrom.org/Flashrom Flashrom] is a utility for identifying, reading, writing, verifying and erasing flash chips. It is designed to flash BIOS/EFI/coreboot/firmware/optionROM images on mainboards, network/graphics/storage controller cards, and various programmer devices.<br />
<br />
{{Warning|If you have a laptop/notebook/netbook, please do NOT try flashrom because interactions with the EC on these machines might crash your machine during flashing. flashrom tries to detect if a machine is a laptop, but not all laptops follow the standard, so this is not 100% reliable.[https://www.flashrom.org/Board_Testing_HOWTO]}}<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{pkg|flashrom}} or {{AUR|flashrom-git}} package.<br />
<br />
=== Usage ===<br />
<br />
Find out if your motherboard and chipset (internal) is supported by flashrom at this website. [http://www.flashrom.org/Supported_hardware Supported Hardware]<br />
You can also find out if your hardware is supported by issuing the following command<br />
<br />
# flashrom --programmer internal<br />
<br />
The above command will tell you your motherboard and chipset. You can then find out if yours is supported by issuing this command:<br />
<br />
# flashrom --programmer internal -L | grep CHIPNAMEfrompreviouscommand<br />
<br />
On modern mainboards you probably get more than one rom chip listed. You have to select the chipname you get from the upper command. Then you use the {{ic|-c}} option to select which rom is affected by the command<br />
<br />
# flashrom --programmer internal -c "CHIPNAME" -r backup_CHIPNAME.bin<br />
<br />
Write and verify the new BIOS image (proprietary or Coreboot) on the ROM chip:<br />
<br />
# flashrom --programmer internal internal -c "CHIPNAME" -w newbios.bin<br />
<br />
If you want to flash other flash chips on your mainboard, you will find all options with<br />
<br />
# flashrom<br />
<br />
{{Note|1=With Linux kernel versions greater than 4.4, {{ic|CONFIG_IO_STRICT_DEVMEM}} a new kernel security measure can make flashrom stop working, in that case you can try adding {{ic|1=iomem=relaxed}} to your kernel parameters. [https://www.flashrom.org/FAQ FAQ].}}<br />
<br />
== FreeDOS ==<br />
<br />
[http://www.freedos.org/ FreeDOS] a free DOS-compatible operating system, is up to the challenge, no need for proprietary DOS versions. So, all you need is a bootable floppy disk image with FreeDOS kernel on it.<br />
<br />
=== Unetbootin ===<br />
<br />
By far the easiest way to make a bootable FreeDOS USB Stick is using {{AUR|unetbootin}}.<br />
<br />
You should format a pendrive with FAT16 and flag it as "boot" (you may do this through a GUI with {{Pkg|gparted}} or {{Pkg|partitionmanager}}). Then, after mounting the flash drive, select under distribution '''FreeDOS''' and your mounted stick. The app will automatically download the image for you and copy it to the drive. Finally, you may copy everything you want to flash there (BIOS, firmwares, etc).<br />
<br />
{{Warning|Unetbootin may not function properly on some Lenovo systems. It may be necessary to create the bootable stick on a different device. See [http://reboot.pro/topic/9849-blinking-cursor-at-boot/ here].}}<br />
<br />
=== dosemu ===<br />
<br />
The problem with the official FreeDOS images is the lack of extra space for holding firmware and BIOS update files and programs. The easiest way to create a DOS, bootable FAT drive of arbitrary size under Linux is to [https://wiki.gentoo.org/wiki/Bootable_DOS_USB_stick mount a FAT drive under dosemu then make it bootable with the FreeDOS sys command.]<br />
<br />
For an alternative method, see [[gentoo:BIOS Update#FreeDOS environment|FreeDOS Flash Drive]], also on the Gentoo Wiki.<br />
<br />
=== Pre-built images ===<br />
<br />
Yet another simple solution: [http://myhq.it/sites/myhq.it/files/FreeDOS-1.1-memstick-2-2048M.img.bz2 FreeDOS pre-built bootable USB flash drive image by Christian Taube]. Instructions can be found [https://web.archive.org/web/20160224081331/http://www.chtaube.eu/computers/freedos/bootable-usb/ here].<br />
<br />
=== Using a FreeDOS-provided Disk Image + USB stick on Linux ===<br />
<br />
As of writing (2017-07-11), {{AUR|unetbootin}} doesn't support versions of FreeDOS more recent than 1.0 (current version is 1.2). The following procedure worked to upgrade an Inspiron 17-3737 to the A09 BIOS. (Dell offers this as a possibility [http://www.dell.com/support/article/ca/en/cabsdt1/SLN171755/updating-the-dell-bios-in-linux-and-ubuntu-environments?lang=EN#Creating%20a%20USB%20Bootable%20Storage%20Device on their site])<br />
<br />
Some notes before starting:<br />
<br />
* You can check your current BIOS version with {{pkg|dmidecode}}. You might already be at the latest version.<br />
* Ensure that your hardware vendor has verified this method works (use of FreeDOS to run BIOS update {{ic|.exe}})<br />
* Laptop users should not attempt this without AC power<br />
* This is dangerous, and you assume all risk for following this procedure.<br />
<br />
Procedure:<br />
<br />
# Grab the latest USB installer from the [http://www.freedos.org/download/ FreeDOS Download Page]<br />
#* author note: used the "Full" version on suspicion that it might include more drivers, etc (pure speculation)<br />
# Extract the archive, you get a ''.img'' file<br />
# Determine which of {{ic|/dev/sdX}} is your USB stick (use {{ic|fdisk -l}})<br />
# Write the image directly to the block device:<br />
#* {{ic|1=dd if=FD12FULL.img of=/dev/sdX status=progress}} (where {{ic|X}} is the letter representing your USB stick as a block device, don't write the image to a partition)<br />
# Double-check that the image copying worked:<br />
#* {{ic|fdisk -l}} (you should see a single partition on a DOS disk with the bootable ("boot") flag set)<br />
# Mount the partition, and copy over the ''.exe'' used to update your firmware<br />
#* Stay on the safe side and limit the filename to 8 characters (without extension), upper case<br />
#* Ensure that you verified any checksums provided by your hardware vendor<br />
# Unmount and reboot. Do whatever is needed to boot from the USB drive<br />
<br />
Now you will find yourself in the FreeDOS live installation environment.<br />
<br />
# Select your language<br />
# You will be prompted to install FreeDOS<br />
#* Select "No - Return to DOS"<br />
# You should see a prompt ({{ic|C:\>}})<br />
# Run {{ic|dir /w}} and verify that your firmware upgrade tool is present<br />
# Run the executable<br />
#* author note: in the case of the Dell tool, the machine displayed a spash screen and then rebooted. Upon reboot, it started the firmware upgrade automatically, and ran for about 2 minutes with the fan at full speed)<br />
# Once the process specific to your vendor completes, optionally verify through the BIOS setup screen, as well as by running {{pkg|dmidecode}} when you're back in linux<br />
<br />
=== Using a FreeDOS-provided Disk Image + USB stick with Windows ===<br />
<br />
The author for this procedure encountered several issues related to mounting the FAT partition type of the USB using the previous method on Linux with dd. This procedure seeks to outline a method to flash the BIOS with FreeDOS, a USB stick and Ruckus on Windows 7/8/8.1/10. This procedure was performed on 4 JULY 2019 on a Dell Inspiron 5547 Laptop to upgrade from BIOS A10 to A12.<br />
<br />
Prerequisites:<br />
* Download and install Rufus for Windows. This can be either the full installation or the portable version.<br />
* Download the latest Full USB installer for FreeDOS (v1.2 as of the time of writing). <br />
* Download the latest BIOS update from the vendors' website<br />
* It is assumed that ''dmidecode'' is installed on the system<br />
<br />
Procedure:<br />
# Extract the contents of the ''FD12FULL.zip'' archive, noting the ''.img'' file<br />
# Insert a flash drive and flash the ''FD12FULL.img'' file using Rufus, leaving all default options<br />
#* Detailed use of Rufus is not covered in this guide. Refer to Rufus' manual or documentation for detailed usage<br />
# Once flashed with Rufus, rename the BIOS file with 8 uppercase characters (not including the extension) and copy it over to the flash drive<br />
# Eject the flash drive and plug it into the laptop.<br />
# Perform whatever steps are necessary to boot from the USB with LEGACY BOOT<br />
#* Author note: For my Dell Laptop, I press F12 for boot options and select 'USB Storage Device' under 'Legacy Options'. I have explicitly enabled legacy boot from within my BIOS, but this option may not be present if the system is only configured to boot with UEFI<br />
# You will be presented with the FreeDOS Installation environment<br />
#* Select preferred language<br />
#* Select 'No - Return to DOS' on the next screen<br />
#* Type ''dir'' to view the contents of the USB flash drive<br />
#* To execute the BIOS upgrade file, simply type the filename and press enter<br />
#* Note: My upgrade took <2 minutes with the fans at full speed. The system reboot 3 times total.<br />
# Once the upgrade completes and the system boots back into the OS, issue ''sudo dmidecode | grep -E 'BIOS|Version' '' and validate the BIOS version has been upgraded<br />
<br />
=== Images that are too large for a floppy ===<br />
<br />
If your flash image is too large for a floppy, go to the [http://www.fdos.org/bootdisks/ FreeDos bootdisk website], and download the 10Mb hard-disk image. This image is a full disk image, including partitions, so adding your flash utility will be a little trickier:<br />
<br />
First find the first partition (at time of writing, the first partition starts at block 63; this means that the partitions starts at offset {{ic|1=512 * 63 = 32256}}).<br />
You can either use:<br />
<br />
{{hc|# file -sk ''<image-file>'' {{!}} sed -r 's/.*startsector ([0-9]+).*/\1/'|<br />
'''63'''<br />
}}<br />
<br />
Or:<br />
<br />
{{hc|# fdisk -l ''<image-file>''|2=<br />
…<br />
Units = sectors of 1 * '''512''' = 512 bytes<br />
…<br />
Device Boot Start End Blocks Id System<br />
* '''63''' 19151 9544+ 1 FAT12<br />
}}<br />
<br />
Now you can mount the image:<br />
<br />
# mount -oloop,offset=$((63 * 512)) ''<image-file>'' /mnt<br />
<br />
Then you can copy your flash utility onto the filesystem as normal.<br />
Once you're done:<br />
<br />
# umount /mnt<br />
<br />
The image can now be copied to a USB stick for booting, or booted as a memdisk as per normal instructions.<br />
<br />
=== Usage ===<br />
<br />
The OEM Bootdisk version is recommended, as it only includes {{ic|kernel}} and {{ic|command.com}} thus leaving more space for the flash utility and new BIOS image. Download the [http://www.fdos.org/bootdisks/autogen/FDOEM.144.gz FreeDOS image] and [[decompress]] it.<br />
<br />
Copy your BIOS flash utility and new BIOS image to the mounted floppy disk image. Load the necessary modules:<br />
<br />
# modprobe vfat<br />
# modprobe loop<br />
<br />
{{ic|/proc/fileystems}} shows if the needed file systems are supported. "loop mount" the floppy disk image to a temporary path:<br />
<br />
$ mkdir /tmp/floppy<br />
$ mount -t vfat -o loop FDOEM.144 /tmp/floppy<br />
<br />
If the mount went without errors, copy the BIOS flash utility and new BIOS image to the mounted floppy disk image. You will probably have to unzip the archive you downloaded from your motherboard vendor site, to get to those two files. For example:<br />
<br />
{{hc|# unzip 775Dual-VSTA\(2.60\).zip|<br />
Archive: 775Dual-VSTA(2.60).zip<br />
inflating: 75DVSTA2.60<br />
inflating: ASRflash.exe<br />
}}<br />
<br />
# cp 75DVSTA2.60 ASRflash.exe /tmp/floppy<br />
<br />
Check that the two files were not too big for the floppy:<br />
<br />
{{bc|<br />
Filesystem 1K-blocks Used Available Use% Mounted on<br />
/tmp/FDOEM.144<br />
1424 990 434 70% /tmp/floppy<br />
}}<br />
<br />
Unmount the floppy disk image:<br />
<br />
# umount /tmp/floppy<br />
<br />
The next step is to burn the floppy image to a CD/DVD-RW media, but in a way that it can be booted afterwards. First create a bootable CD image, and then burn it.<br />
<br />
# genisoimage -o bootcd.iso -b FDOEM.144 FDOEM.144<br />
# wodim -v bootcd.iso<br />
<br />
You may alternatively add your image to the [[GRUB]] menu. Install [[syslinux]] and copy {{ic|memdisk}} and your image to {{ic|/boot}}:<br />
<br />
# cp /usr/lib/syslinux/memdisk /boot<br />
# cp FDOEM.144 /boot/flashbios.img<br />
<br />
Now add an entry to {{ic|/boot/grub/menu.lst}}:<br />
<br />
{{hc|/boot/grub/menu.lst|<br />
title Flash BIOS<br />
kernel /memdisk<br />
initrd /flashbios.img<br />
}}<br />
<br />
Or for GRUB2 in {{ic|/boot/grub/grub.cfg}}:<br />
<br />
{{hc|/boot/grub/grub.cfg|<nowiki><br />
menuentry "Flash BIOS" {<br />
linux16 /boot/memdisk<br />
initrd16 /boot/flashbios.img<br />
}<br />
</nowiki>}}<br />
<br />
Or for syslinux in {{ic|/boot/syslinux/syslinux.cfg}}:<br />
<br />
{{hc|/boot/syslinux/syslinux.cfg|<br />
LABEL flashbios<br />
MENU LABEL Flash BIOS<br />
LINUX ../memdisk<br />
INITRD ../fdboot.img<br />
}}<br />
<br />
Finally reboot your machine, making sure the CD drive is first in the boot sequence, and run the BIOS upgrade procedure when the CD boots. If using the GRUB method, choose the new entry on the list, and it should boot into FreeDOS.<br />
<br />
== Bootable optical disk emulation ==<br />
<br />
The script Geteltorito.pl will extract the [[wikipedia:El Torito (CD-ROM standard)|El Torito]] boot image. It has worked with Lenovo laptops like the X1 Carbon, X220, X230, X260, X395, W540, T450, T450s and P50. It may work for other vendors as well.<br />
<br />
=== Installation ===<br />
<br />
Install the {{AUR|geteltorito}} package.<br />
<br />
=== Usage ===<br />
<br />
Get the bios update iso from the vendor support site. Run the ''geteltorito'' image extraction:<br />
<br />
$ geteltorito.pl -o <image>.img <image>.iso<br />
<br />
Copy the image to the usb thumbdrive:<br />
<br />
# dd if=<image>.img of=<destination> bs=512K<br />
<br />
Reboot and boot from the USB drive, follow vendor directions.<br />
<br />
{{Note|If you get the message "Secure Flash Authentication failed!", it means that some security check did not allow the flash to happen. It can help to go to the BIOS options page "Security" > "UEFI BIOS Update Option" and disable "Secure RollBack Prevention" and enable "Flash BIOS Updating by End-Users". You can set them to what you want after flashing.}}<br />
<br />
== Using a Windows PE ==<br />
<br />
If your manufacturer only provides an exe file and you were not successful following the prior advice , you can update your bios creating a Windows PE flash drive and from there flash the bios update as normally.<br />
<br />
=== Usage ===<br />
<br />
Download a ISO [[Windows PE]] to create a bootable drive.<br />
<br />
Boot the usb and go to your manufacturer website and download the respective update, and execute normally.<br />
<br />
{{ Note|This method was tested on an Acer Laptop, you mileage may vary }}</div>Simon04https://wiki.archlinux.org/index.php?title=BIOS_update&diff=639372BIOS update2020-10-22T07:11:18Z<p>Simon04: Redirected page to Flashing BIOS from Linux</p>
<hr />
<div>#REDIRECT [[Flashing BIOS from Linux]]</div>Simon04https://wiki.archlinux.org/index.php?title=Reproducible_builds&diff=639119Reproducible builds2020-10-18T18:47:25Z<p>Simon04: /* Verifying packages with repro and findings issues */ +example</p>
<hr />
<div>[[Category:Package management]]<br />
[[Category:Package development]]<br />
{{Move|Reproducible builds|See [[Help:Style#Title]].}}<br />
<br />
Arch Linux is currently working on making all packages reproducible. This lets users and researchers verify the distributed packages from Arch Linux. For the exact definition of reproducible builds and its benefits take a look at the [https://reproducible-builds.org/ project website].<br />
<br />
== Verification builds ==<br />
<br />
An experimental [[rebuilderd]] instance has been setup on our own infrastructure with a [https://reproducible.archlinux.org status page]. Rebuilderd rebuilds our repository packages and checks if they are bit for bit identical. If they are not reproducible there is either a bug in the tooling, the package is not reproducible or the package has not been build cleanly.<br />
<br />
A list of known issues is located on [[Reproducible Builds/Status]].<br />
<br />
== Helping out ==<br />
<br />
=== Tooling ===<br />
<br />
Help out on fixing bugs and adding features for [https://github.com/archlinux/archlinux-repro repro].<br />
<br />
=== Running a Rebuilder instance ===<br />
<br />
[[Rebuilderd|Setting up rebuilderd]] to build Arch Linux packages helps to independently verify repository packages.<br />
<br />
=== Verifying packages with repro and findings issues ===<br />
<br />
A create way to help out is to find an unreproducible package and figuring out how it can be made reproducible.<br />
<br />
* Download an Arch Linux package or get one from the [[Arch Linux Archive]] <br />
* Run repro on the downloaded package or a package from your pacman cache. Ideally with {{ic|repro -d}} to get diffoscope output. For example, {{ic|repro -d /var/cache/pacman/pkg/curl-7.73.0-1-x86_64.pkg.tar.zst}}<br />
* Investigate if it is an issue with Arch Linux packaging or upstream, issues can be added on the [[Reproducible Builds/Status|status page]]. More information can be found on the [https://reproducible-builds.org/docs/ reproducible builds website].<br />
<br />
=== Work on issues in the tests.reproducible-builds.org infrastructure ===<br />
<br />
Arch users can help contribute to Reproducible Build issues by looking at the [https://tests.reproducible-builds.org/archlinux/archlinux.html continuous reproducing environment]. There are various issues which can be sorted out:<br />
<br />
* FTBS (failed to build from source): reproduce the build failure locally and create a bug report if the package cannot be [[DeveloperWiki:Building in a clean chroot|built from a clean chroot]] ({{ic|extra-x86_64-build}} or {{ic|multilib-build}}).<br />
* Failed to download sources, reproduce the issue ({{ic|makepkg -o -d}}) and create a bug report on the Arch bugtracker.<br />
* Failed to reproduce. Locally you can reproduce packages using {{pkg|reprotest}}. Note that not all variations can be used. For simple time related testing: {{bc|1=$ reprotest --variations '+time' 'sudo extra-x86_64-build' '*.pkg.tar.xz'}}<br />
There might be various reasons for a package to not be reproducible, but before digging in take a look at the upstream repository or the reproducible status in [https://tests.reproducible-builds.org/debian/reproducible.html Debian]<br />
* Failed to run tests, these failures are heavily on the testing environment. Most likely due to to {{ic|1=LANG=C}} being set and Arch not supporting {{ic|1=LANG=C.UTF-8}}.<br />
<br />
If you are interested in the code which runs the continuous reproducing environment, the first build code starts here on [https://salsa.debian.org/qa/jenkins.debian.net/blob/master/bin/reproducible_build_archlinux_pkg.sh#L115 salsa]<br />
<br />
{{Note|The continuous reproducing environment on tests.reproducible-builds.org does NOT reproduce official arch packages. Its purpose is only to fuzz the packages and attempt to trigger as many bugs as possible, so they can be reported upstream.}}<br />
<br />
== Known issues ==<br />
<br />
=== GPG verification ===<br />
<br />
There is a possible rebuild scenario where GPG keys will not verify as the packager was removed from the keyring or revoked as we use the latest keyring and a package in the archive which we need might need be signed by a revoked key we are unable to verify it and the build will fail.<br />
<br />
== Contact ==<br />
<br />
* [ircs://chat.freenode.net/archlinux-projects #archlinux-reproducible] — Main channel for the progress of Reproducible Builds on Arch Linux</div>Simon04https://wiki.archlinux.org/index.php?title=Caddy&diff=634484Caddy2020-09-06T10:59:23Z<p>Simon04: Caddy 2</p>
<hr />
<div>[[Category:Web server]]<br />
[[ja:Caddy]]<br />
[[zh-hans:Caddy]]<br />
[https://caddyserver.com/ Caddy] is a HTTP/2 capable web server with automatic HTTPS.<br />
<br />
== Installation ==<br />
<br />
<!-- Caddy 1 has been removed, see https://github.com/archlinux/svntogit-community/commit/930a812778565b61469ac7145292f0279926b257 --><br />
[[Install]] the {{AUR|caddy2}} package.<br />
<br />
== Configuration ==<br />
<br />
Caddy 2 supports various configuration formats, see [https://caddyserver.com/docs/config-adapters config adapters] (caddyfile, [[nginx]], json, yaml, toml, among others).<br />
<br />
Most commonly, Caddy is configured using a plain text file called [https://caddyserver.com/docs/caddyfile {{ic|Caddyfile}}]. The {{ic|Caddyfile}} starts with (an optional [https://caddyserver.com/docs/caddyfile/options global options block] and) an address of the site to be served, and is followed by a number of directives.<br />
<br />
A simple {{ic|Caddyfile}} hosting the site at {{ic|localhost:2020}}:<br />
<br />
{<br />
http_port 2020<br />
}<br />
<br />
localhost:2020<br />
file_server<br />
<br />
<s>A more comprehensive example that would get you an A+ rating on https://securityheaders.com is https://gist.github.com/Strykar/e5c0e32ef21f3d9f04eab3e42349f9d0</s><br />
<br />
== Usage ==<br />
<br />
$ caddy help<br />
$ caddy help run<br />
<br />
Caddy can be run by any user from the page's directory, and the {{ic|Caddyfile}} should be in the same directory:<br />
<br />
$ caddy run<br />
<br />
Alternatively you may specify a custom {{ic|Caddyfile}}:<br />
<br />
$ caddy run -config ../path/to/Caddyfile<br />
<br />
== See also ==<br />
<br />
* [https://caddyserver.com/ Caddy Official Website]<br />
* [https://caddyserver.com/docs Caddy User Guide]<br />
* [https://caddyserver.com/docs/caddyfile {{ic|Caddyfile}} documentation]</div>Simon04https://wiki.archlinux.org/index.php?title=Locale&diff=628295Locale2020-08-02T09:50:03Z<p>Simon04: +Firefox bug 1429578 for LC_TIME</p>
<hr />
<div>[[Category:Localization]]<br />
[[ar:Locale]]<br />
[[cs:Locale]]<br />
[[de:Locale]]<br />
[[es:Locale]]<br />
[[fr:Locale]]<br />
[[it:Locale]]<br />
[[ja:ロケール]]<br />
[[ko:Locale]]<br />
[[pt:Locale]]<br />
[[ru:Locale]]<br />
[[zh-hans:Locale]]<br />
{{Related articles start}}<br />
{{Related|Environment variables}}<br />
{{Related|Localization}}<br />
{{Related articles end}}<br />
[[w:Locale (computer software)|Locales]] are used by {{Pkg|glibc}} and other locale-aware programs or libraries for rendering text, correctly displaying regional monetary values, time and date formats, alphabetic idiosyncrasies, and other locale-specific standards.<br />
<br />
== Generating locales ==<br />
<br />
Locale names are typically of the form {{ic|language[_territory][.codeset][@modifier]}}, where ''language'' is an [[w:List_of_ISO_639-1_codes|ISO 639 language code]], ''territory'' is an [[w:ISO_3166-1#Current_codes|ISO 3166 country code]], and ''codeset'' is a [[w:Character_encoding|character set]] or encoding identifier like [[w:ISO/IEC_8859-1|ISO-8859-1]] or [[w:UTF-8|UTF-8]]. See {{man|3|setlocale}}.<br />
<br />
For a list of enabled locales, run:<br />
<br />
$ locale -a<br />
<br />
Before a locale can be enabled on the system, it must be generated. This can be achieved by uncommenting applicable entries in {{ic|/etc/locale.gen}}, and running ''locale-gen''. Equivalently, commenting entries disables their respective locales. While making changes, consider any localisations required by other users on the system, as well as specific [[#Variables]].<br />
<br />
For example, uncomment {{ic|en_US.UTF-8 UTF-8}} for American-English:<br />
<br />
{{hc|/etc/locale.gen|<br />
...<br />
#en_SG ISO-8859-1<br />
en_US.UTF-8 UTF-8<br />
#en_US ISO-8859-1<br />
...<br />
}}<br />
<br />
Save the file, and generate the locale:<br />
<br />
# locale-gen<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* {{ic|locale-gen}} also runs with every update of {{Pkg|glibc}}. [https://github.com/archlinux/svntogit-packages/blob/packages/glibc/trunk/glibc.install#L5]<br />
* {{ic|UTF-8}} is recommended over other character sets. [http://utf8everywhere.org/]}}<br />
<br />
== Setting the locale ==<br />
<br />
To display the currently set locale and its related environmental settings, type:<br />
<br />
$ locale<br />
<br />
The locale to be used, chosen among the previously generated ones, is set in {{ic|locale.conf}} files. Each of these files must contain a new-line separated list of [[environment variable]] assignments, having the same format as output by ''locale''.<br />
<br />
To list available locales which have been previously generated, run:<br />
<br />
$ localedef --list-archive<br />
<br />
Alternatively, using {{man|1|localectl}}:<br />
<br />
$ localectl list-locales<br />
<br />
=== Setting the system locale ===<br />
<br />
To set the system locale, write the {{ic|LANG}} variable to {{ic|/etc/locale.conf}}, where {{ic|''en_US.UTF-8''}} belongs to the '''first column''' of an uncommented entry in {{ic|/etc/locale.gen}}:<br />
<br />
{{hc|1=/etc/locale.conf|2=<br />
LANG=''en_US.UTF-8''<br />
}}<br />
<br />
Alternatively, run:<br />
<br />
# localectl set-locale LANG=''en_US.UTF-8''<br />
<br />
See [[#Variables]] and {{man|5|locale.conf}} for details.<br />
<br />
=== Overriding system locale per user session ===<br />
<br />
The system-wide locale can be overridden in each user session by creating or editing {{ic|~/.config/locale.conf}} (or, in general, {{ic|$XDG_CONFIG_HOME/locale.conf}} or {{ic|$HOME/.config/locale.conf}}).<br />
<br />
The precedence of these {{ic|locale.conf}} files is defined in {{ic|/etc/profile.d/locale.sh}}.<br />
<br />
{{Tip|<br />
* This can also allow keeping the logs in {{ic|/var/log}} in English while using the local language in the user environment.<br />
* You can create a {{ic|/etc/skel/.config/locale.conf}} file so that any new users added using ''useradd'' and the {{ic|-m}} option will have {{ic|~/.config/locale.conf}} automatically generated.}}<br />
<br />
=== Make locale changes immediate ===<br />
<br />
Once system and user {{ic|locale.conf}} files have been created or edited, their new values will take effect for new sessions at login. To have the current environment use the new settings unset {{ic|LANG}} and source {{ic|/etc/profile.d/locale.sh}}:<br />
<br />
$ unset LANG<br />
$ source /etc/profile.d/locale.sh<br />
<br />
{{Note|The {{ic|LANG}} variable has to be unset first, otherwise {{ic|locale.sh}} will not update the values from {{ic|locale.conf}}. Only new and changed variables will be updated; variables removed from {{ic|locale.conf}} will still be set in the session.}}<br />
<br />
=== Other uses ===<br />
<br />
Locale variables can also be defined with the standard methods as explained in [[Environment variables]].<br />
<br />
For example, in order to test or debug a particular application during development, it could be launched with something like:<br />
<br />
$ LANG=C ./my_application.sh<br />
<br />
Similarly, to set the locale for all processes run from the current shell (for example, during system installation):<br />
<br />
$ export LANG=C<br />
<br />
== Variables ==<br />
<br />
{{ic|locale.conf}} files support the following environment variables:<br />
<br />
* [[#LANG: default locale|LANG]]<br />
* [[#LANGUAGE: fallback locales|LANGUAGE]]<br />
* {{ic|LC_ADDRESS}}<br />
* [[#LC_COLLATE: collation|LC_COLLATE]]<br />
* {{ic|LC_CTYPE}}<br />
* {{ic|LC_IDENTIFICATION}}<br />
* {{ic|LC_MEASUREMENT}}<br />
* {{ic|LC_MESSAGES}}<br />
* {{ic|LC_MONETARY}}<br />
* {{ic|LC_NAME}}<br />
* {{ic|LC_NUMERIC}}<br />
* {{ic|LC_PAPER}}<br />
* {{ic|LC_TELEPHONE}}<br />
* [[#LC_TIME: date and time format|LC_TIME]]<br />
<br />
Full meaning of the above {{ic|LC_*}} variables can be found on manpage {{man|7|locale}}, whereas details of their definition are described on {{man|5|locale}}.<br />
<br />
=== LANG: default locale ===<br />
<br />
The locale set for this variable will be used for all the {{ic|LC_*}} variables that are not explicitly set.<br />
<br />
=== LANGUAGE: fallback locales ===<br />
<br />
Programs which use {{Pkg|gettext}} for translations respect the {{Ic|LANGUAGE}} option in addition to the usual variables. This allows users to specify a [http://www.gnu.org/software/gettext/manual/gettext.html#The-LANGUAGE-variable list] of locales that will be used in that order. If a translation for the preferred locale is unavailable, another from a similar locale will be used instead of the default. For example, an Australian user might want to fall back to British rather than US spelling:<br />
<br />
{{hc|locale.conf|2=<br />
LANG=en_AU.UTF-8<br />
LANGUAGE=en_AU:en_GB:en<br />
}}<br />
<br />
=== LC_TIME: date and time format ===<br />
<br />
If {{ic|LC_TIME}} is set to {{ic|en_US.UTF-8}}, for example, the date format will be "MM/DD/YYYY". If wanting to use the the ISO 8601 date format of "YYYY-MM-DD" use:<br />
<br />
{{hc|locale.conf|2=<br />
LC_TIME=en_DK.UTF-8<br />
}}<br />
<br />
{{pkg|glibc}} 2.29 fixed a bug, {{ic|en_US.UTF-8}} started showing in 12-hour format, as was intended. If wanting to use 24-hour format, use {{ic|1=LC_TIME=en_GB.UTF-8}}.<br />
<br />
{{Note|1=Programs do not necessarily respect this variable to format the date. For example, {{man|1|date}} uses its own parameters to do so, and [[Firefox]] stopped honouring {{ic|LC_TIME}} with version 57 ([https://bugzilla.mozilla.org/show_bug.cgi?id=1429578 Bug 1429578]).}}<br />
<br />
=== LC_COLLATE: collation ===<br />
<br />
This variable governs the collation rules used for sorting and regular expressions.<br />
<br />
Setting the value to {{ic|C}} can for example make the ''ls'' command sort dotfiles first, followed by uppercase and lowercase filenames:<br />
<br />
{{hc|locale.conf|2=<br />
LC_COLLATE=C<br />
}}<br />
<br />
See also [http://superuser.com/a/448294/175967].<br />
<br />
To get around potential issues, Arch used to set {{ic|1=LC_COLLATE=C}} in {{ic|/etc/profile}}, but this method is now deprecated.<br />
<br />
=== LC_ALL: troubleshooting ===<br />
<br />
The locale set for this variable will always override {{ic|LANG}} and all the other {{ic|LC_*}} variables, whether they are set or not. <br />
<br />
{{ic|LC_ALL}} is the only {{ic|LC_*}} variable which '''cannot''' be set in {{ic|locale.conf}} files: it is meant to be used only for testing or troubleshooting purposes, for example in {{ic|/etc/profile}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== My terminal does not support UTF-8 ===<br />
<br />
The following lists some (not all) terminals that support UTF-8:<br />
<br />
* gnustep-terminal<br />
* konsole<br />
* [[mlterm]]<br />
* [[rxvt-unicode]]<br />
* [[st]]<br />
* [[termite]]<br />
* [[List_of_applications/Utilities#VTE-based|VTE-based terminals]]<br />
* [[xterm]] - Run with the argument {{ic|-u8}} or configure resource {{ic|xterm*utf8: 2}}.<br />
<br />
==== Gnome-terminal or rxvt-unicode ====<br />
<br />
You need to launch these applications from a UTF-8 locale or they will drop UTF-8 support. Enable the {{ic|en_US.UTF-8}} locale (or your local UTF-8 alternative) per the instructions above and set it as the default locale, then reboot.<br />
<br />
=== My system is still using wrong language ===<br />
<br />
It is possible that the environment variables are redefined in other files than {{ic|locale.conf}}, for example {{ic|~/.pam_environment}}. See [[Environment variables#Defining variables]] for details.<br />
<br />
If you are using a desktop environment, such as [[GNOME]], its language settings may be overriding the settings in {{ic|locale.conf}}.<br />
<br />
[[KDE]] Plasma also allows to change the UI's language through the system settings. If the desktop environment is still using the default language after the modification, [https://bbs.archlinux.org/viewtopic.php?pid=1435219#p1435219 deleting the file at] {{ic|~/.config/plasma-localerc}} (previously: {{ic|~/.config/plasma-locale-settings.sh}}) should resolve the issue.<br />
<br />
== See also ==<br />
<br />
* [[Gentoo:Localization/Guide]]<br />
* [http://wikigentoo.ksiezyc.pl/Locales.htm Supposedly 2008, or earlier, Gentoo wiki article]<br />
* [http://demo.icu-project.org/icu-bin/locexp?_=en_US&x=col ICU's interactive collation testing]<br />
* [http://www.openi18n.org/ Free Standards Group Open Internationalisation Initiative]<br />
* [http://pubs.opengroup.org/onlinepubs/007908799/xbd/locale.html ''The Single UNIX Specification'' definition of Locale] by The Open Group<br />
* [https://help.ubuntu.com/community/EnvironmentVariables#Locale_setting_variables Locale environment variables]</div>Simon04https://wiki.archlinux.org/index.php?title=Fzf&diff=612960Fzf2020-05-15T09:57:35Z<p>Simon04: /* Alternatives */ +skim</p>
<hr />
<div>{{lowercase title}}<br />
[[Category:Search]]<br />
[[Category:Commands]]<br />
[[es:Fzf]]<br />
[[ja:Fzf]]<br />
[https://github.com/junegunn/fzf fzf] is a general-purpose command-line fuzzy finder.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|fzf}} package. The development version is {{AUR|fzf-git}}.<br />
<br />
== Configuration ==<br />
<br />
{{Expansion|It should be at least mentioned that shell completer is not the only usecase which requires configuration.}}<br />
<br />
=== Shells ===<br />
<br />
Optional [https://github.com/junegunn/fzf/wiki/Configuring-shell-key-bindings fzf keybindings] and completion are available for various shells:<br />
<br />
* {{ic|<CTRL+T>}} list files+folders in current directory (e.g., {{ic|git commit <CTRL+T>}}, select a few files using {{ic|<TAB>}}, finally {{ic|<Return>}})<br />
* {{ic|<CTRL+R>}} search history of shell commands<br />
* {{ic|<ALT+C>}} fuzzy change directory<br />
<br />
==== [[bash]] ====<br />
<br />
[[Source]] the desired files from your {{ic|.bashrc}}:<br />
<br />
* {{ic|/usr/share/fzf/key-bindings.bash}}<br />
* {{ic|/usr/share/fzf/completion.bash}}<br />
<br />
==== [[zsh]] ====<br />
<br />
Source the desired files from your {{ic|.zshrc}} (after vi-mode, if using that, too):<br />
<br />
* {{ic|/usr/share/fzf/key-bindings.zsh}}<br />
* {{ic|/usr/share/fzf/completion.zsh}}<br />
<br />
==== [[fish]] ====<br />
<br />
For fish, keybindings are in:<br />
<br />
* {{ic|/usr/share/fish/vendor_functions.d/fzf_key_bindings.fish}}<br />
<br />
fish will source this by default but the bindings have to be enabled manually:<br />
<br />
{{hc|~/.config/fish/functions/fish_user_key_bindings.fish|<br />
function fish_user_key_bindings<br />
fzf_key_bindings<br />
end<br />
}}<br />
<br />
fzf completion in fish can be enabled with custom functions:<br />
https://github.com/junegunn/fzf/wiki/Examples-(fish)<br />
<br />
=== Vim ===<br />
<br />
The basic [[Vim]] plugin is already included within the package and installed to Vim's global plugin directory. Thus, you don't need to add anything to your {{ic|.vimrc}} to be able to use it. It only provides the FZF command, though. There is an additional Vim plugin made by the author of fzf that defines some convenience functions, see https://github.com/junegunn/fzf.vim.<br />
<br />
== Arch specific fzf uses ==<br />
<br />
=== Pacman ===<br />
<br />
Try this to fuzzy-search through all available packages, with package info shown in a preview window, and then install selected packages:<br />
<br />
pacman -Slq | fzf -m --preview 'pacman -Si {1}' | xargs -ro sudo pacman -S<br />
<br />
If you want to add package file list in preview - may be a bit slower updating preview window (make sure you run {{ic|pacman -Fy}} at least once before invocation to sync the pacman file database):<br />
<br />
pacman -Slq | fzf -m --preview 'cat <(pacman -Si {1}) <(pacman -Fl {1} | awk "{print \$2}")' | xargs -ro sudo pacman -S<br />
<br />
== Alternatives ==<br />
* {{pkg|skim}} – fuzzy finder written in [[Rust]]</div>Simon04https://wiki.archlinux.org/index.php?title=Fish&diff=611523Fish2020-05-08T13:44:21Z<p>Simon04: Update fishshell.com links, use HTTPS</p>
<hr />
<div>{{lowercase title}}<br />
[[Category:Command shells]]<br />
{{Related articles start}}<br />
{{Related|Command-line shell}}<br />
{{Related articles end}}<br />
[[de:Fish]]<br />
[[ja:Fish]]<br />
[[ru:Fish]]<br />
[[zh-hans:Fish]]<br />
[[fr:Fish]]<br />
<br />
[https://fishshell.com fish], the '''''f'''riendly '''i'''nteractive '''sh'''ell'', is a [[command-line shell|commandline shell]] intended to be interactive and user-friendly.<br />
<br />
''fish'' is intentionally not fully [[Wikipedia:POSIX|POSIX]] compliant, it aims at addressing POSIX inconsistencies (as perceived by the creators) with a simplified or a different syntax. This means that even simple POSIX compliant scripts may require some significant adaptation or even full rewriting to run with fish.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|fish}} package. For the development version, install the {{AUR|fish-git}} package.<br />
<br />
Once installed, simply type {{ic|fish}} to drop into the fish shell.<br />
<br />
Documentation can be found by typing {{ic|help}} from fish; it will be opened in a web browser. It is recommended to read at least the "Syntax overview" section, since fish's syntax is different from many other shells.<br />
<br />
== System integration ==<br />
<br />
One must decide whether fish is going to be the default user's shell, which means that the user falls directly in fish at login, or whether it is used in interactive terminal mode as a child process of the current default shell, here we will assume the latter is [[Bash]]. To elaborate on these two setups:<br />
<br />
* fish used as the '''default shell''': this mode requires some basic understanding of the fish functioning and its scripting language. The user's current initialization scripts and environment variables need to be migrated to the new fish environment. To configure the system in this mode, follow [[#Setting fish as default shell]].<br />
<br />
* fish used as an '''interactive shell only''': this is the less disruptive mode, all the Bash initialization scripts are run as usual and fish runs on top of Bash in interactive mode connected to a terminal. To setup fish in this mode, follow [[#Setting fish as interactive shell only]].<br />
<br />
=== Setting fish as default shell ===<br />
If you decide to set fish as the default user shell, the first step is to set the shell of this particular user to {{ic|/usr/bin/fish}}. This can be done by following the instructions in [[Command-line shell#Changing your default shell]].<br />
<br />
The next step is to port the current needed actions and configuration performed in the various Bash initialization scripts, namely {{ic|/etc/profile}}, {{ic|~/.bash_profile}}, {{ic|/etc/bash.bashrc}} and {{ic|~/.bashrc}}, into the fish framework.<br />
<br />
In particular, the content of the {{ic|$PATH}} environment variable, once directly logged under fish, should be checked and adjusted to one's need. In fish, {{ic|$PATH}} is defined as a ''global environment variable'': it has a ''global'' scope across all functions, it is lost upon reboot and it is an ''environment variable'' which means it is exported to child processes.<br />
The recommended way of adding permanently additional locations to the path is by assigning them to the {{ic|fish_user_paths}} universal variable. This variable is automatically added to {{ic|$PATH}} and is preserved across restarts of the shell. For example by setting:<br />
<br />
$ set -U fish_user_paths ''/first/path'' ''/second/path'' ''/third/one''<br />
<br />
These three locations will be permanently prepended to the path. This is an easy way to complement the path without the need to add any instruction in scripts.<br />
<br />
=== Setting fish as interactive shell only ===<br />
Not setting fish as system wide or user default allows the current Bash scripts to run on startup. It ensures the current user's environment variables are unchanged and are exported to fish which then runs as a Bash child. Below are several ways of running fish in interactive mode without setting it as the default shell.<br />
<br />
==== Modify .bashrc to drop into fish ====<br />
Keep the default shell as Bash and simply add the line {{ic|exec fish}} to the appropriate [[Bash#Configuration files]], such as {{ic|.bashrc}}. This will allow Bash to properly source {{ic|/etc/profile}} and all files in {{ic|/etc/profile.d}}. Because fish replaces the Bash process, exiting fish will also exit the terminal. Compared to the following options, this is the most universal solution, since it works both on a local machine and on a SSH server.<br />
<br />
{{Tip|<br />
* In this setup, use {{ic|bash --norc}} to manually enter Bash without executing the commands from {{ic|~/.bashrc}} which would run {{ic|exec fish}} and drop back into fish.<br />
* To have commands such as {{ic|bash -c 'echo test'}} run the command in Bash instead of starting fish, you can write {{ic|if [ -z "$BASH_EXECUTION_STRING" ]; then exec fish; fi}} instead.<br />
* Drop in to fish only if the parent process is not fish. This allows to quickly enter in to bash by invoking {{ic|bash}} command without losing {{ic|~/.bashrc}} configuration: {{bc|<nowiki>if [[ $(ps --no-header --pid=$PPID --format=cmd) != "fish" ]]<br />
then<br />
exec fish<br />
fi</nowiki>}}}}<br />
<br />
==== Use terminal emulator options ====<br />
<br />
Another option is to open your terminal emulator with a command line option that executes fish. For most terminals this is the {{ic|-e}} switch, so for example, to open gnome-terminal using fish, change your shortcut to use:<br />
<br />
gnome-terminal -e fish<br />
<br />
With terminal emulators that do not support setting the shell, for example {{aur|lilyterm-git}}, it would look like this:<br />
<br />
SHELL=/usr/bin/fish lilyterm<br />
<br />
Also, depending on the terminal, you may be able to set fish as the default shell in either the terminal configuration or the terminal profile.<br />
<br />
==== Use terminal multiplexer options ====<br />
<br />
To set fish as the shell started in [[tmux]], put this into your {{ic|~/.tmux.conf}}:<br />
<br />
set-option -g default-shell "/usr/bin/fish"<br />
<br />
Whenever you run ''tmux'', you will be dropped into fish.<br />
<br />
== Configuration ==<br />
<br />
The configuration file runs at every login and is located at {{ic|~/.config/fish/config.fish}}. Adding commands or functions to the file will execute/define them when opening a terminal, similar to {{ic|.bashrc}}. Note that whenever a variable needs to be preserved, it should be set as ''universal'' rather than defined in the aforementioned configuration file.<br />
<br />
The user's functions are located in the directory {{ic|~/.config/fish/functions}} under the filenames {{ic|''function_name''.fish}}.<br />
<br />
=== Web interface ===<br />
<br />
The fish terminal colors, prompt, functions, variables, history, bindings and abbreviations can be set with the interactive web interface:<br />
<br />
fish_config<br />
<br />
It may fail to start if IPv6 has been disabled. See [https://github.com/fish-shell/fish-shell/issues/3857#issuecomment-281631629] and [[IPv6#Disable IPv6]].<br />
<br />
=== Command completion ===<br />
<br />
fish can generate autocompletions from man pages. Completions are written to {{ic|~/.local/share/fish/generated_completions/}} and can be generated by calling:<br />
<br />
fish_update_completions<br />
<br />
You can also define your own completions in {{ic|~/.config/fish/completions/}}. See {{ic|/usr/share/fish/completions/}} for a few examples.<br />
<br />
Context-aware completions for Arch Linux-specific commands like ''pacman'', ''pacman-key'', ''makepkg'', ''cower'', ''pbget'', ''pacmatic'' are built into fish, since the policy of the fish development is to include all the existent completions in the upstream tarball. The memory management is clever enough to avoid any negative impact on resources.<br />
<br />
==Tips and tricks==<br />
<br />
===Command substitution===<br />
''fish'' does not implement Bash style history substitution (e.g. {{ic|sudo !!}}), and the developers recommend in the [https://fishshell.com/docs/current/faq.html#why-doesn-t-history-substitution-etc-work fish faq] to use the interactive history recall interface instead: the {{ic|Up}} arrow recalls whole past lines and {{ic|Alt+Up}} (or {{ic|Alt+.}}) recalls individual arguments.<br />
<br />
However some workarounds are described in the [https://github.com/fish-shell/fish-shell/wiki/Bash-Style-Command-Substitution-and-Chaining-(!!-!$-&&-%7C%7C) fish wiki]: while not providing complete history substitution, some functions replace {{ic|!!}} with the previous command or {{ic|!$}} with the previous last argument.<br />
<br />
===Command chaining===<br />
Command chaining {{ic|&&}} and {{ic|{{!}}{{!}}}} is not implemented in versions older than 3.0 and the recommended syntax to achieve similar results in ''fish'' is respectively {{ic|; and}} and {{ic|; or}}.<br />
Some keybindings can be set for automatic substitution as described in the [https://github.com/fish-shell/fish-shell/wiki/Bash-Style-Command-Substitution-and-Chaining-(!!-!$-&&-%7C%7C)#getting--and- fish wiki].<br />
<br />
===Disable greeting===<br />
<br />
By default, fish prints a greeting message at startup. To disable it, run once:<br />
<br />
$ set -U fish_greeting<br />
<br />
This clears the universal {{ic|fish_greeting}} variable, shared with all fish instances and which is preserved upon restart of the shell.<br />
<br />
=== Make su launch fish ===<br />
<br />
If ''su'' starts with Bash because Bash is the target user's (''root'' if no username is provided) default shell, one can define a function to redirect it to fish whatever the user's shell:<br />
{{hc|~/.config/fish/functions/su.fish|2=<br />
function su<br />
command su --shell=/usr/bin/fish $argv<br />
end}}<br />
<br />
=== Start X at login ===<br />
<br />
Add the following to the bottom of your {{ic|~/.config/fish/config.fish}}.<br />
<br />
{{bc|1=<nowiki><br />
# Start X at login<br />
if status is-login<br />
if test -z "$DISPLAY" -a "$XDG_VTNR" = 1<br />
exec startx -- -keeptty<br />
end<br />
end<br />
</nowiki>}}<br />
<br />
For those running fish in interactive mode, replace {{ic|status is-login}} with {{ic|status is-interactive}} in the above code.<br />
<br />
=== Use liquidprompt ===<br />
<br />
[https://github.com/nojhan/liquidprompt Liquidprompt] is a popular "full-featured & carefully designed adaptive prompt for Bash & Zsh" and has no plans to make it compatible with fish [https://github.com/nojhan/liquidprompt/pull/230]. The [https://github.com/dolmen/angel-PS1 angel-PS1] project implements its functionality for fish.<br />
<br />
=== Put git status in prompt ===<br />
<br />
If you would like fish to display the branch and dirty status when you are in a git directory, you can define the following {{ic|fish_prompt}} function:<br />
{{hc|~/.config/fish/functions/fish_prompt.fish|<br />
<nowiki>function fish_prompt<br />
set -l last_status $status<br />
<br />
if not set -q __fish_git_prompt_show_informative_status<br />
set -g __fish_git_prompt_show_informative_status 1<br />
end<br />
if not set -q __fish_git_prompt_color_branch<br />
set -g __fish_git_prompt_color_branch brmagenta<br />
end<br />
if not set -q __fish_git_prompt_showupstream<br />
set -g __fish_git_prompt_showupstream "informative"<br />
end<br />
if not set -q __fish_git_prompt_showdirtystate<br />
set -g __fish_git_prompt_showdirtystate "yes"<br />
end<br />
if not set -q __fish_git_prompt_color_stagedstate<br />
set -g __fish_git_prompt_color_stagedstate yellow<br />
end<br />
if not set -q __fish_git_prompt_color_invalidstate<br />
set -g __fish_git_prompt_color_invalidstate red<br />
end<br />
if not set -q __fish_git_prompt_color_cleanstate<br />
set -g __fish_git_prompt_color_cleanstate brgreen<br />
end<br />
<br />
printf '%s%s %s%s%s%s ' (set_color $fish_color_host) (prompt_hostname) (set_color $fish_color_cwd) (prompt_pwd) (set_color normal) (__fish_git_prompt)<br />
<br />
if not test $last_status -eq 0<br />
set_color $fish_color_error<br />
end<br />
echo -n '$ '<br />
set_color normal<br />
end<br />
</nowiki>}}<br />
<br />
However, this is now deprecated, see [https://github.com/fish-shell/fish-shell/blob/master/share/functions/__fish_git_prompt.fish fish-shell git].<br />
Alternatively, the [https://mariuszs.github.io/blog/2013/informative_git_prompt.html Informative Git Prompt] has now been built into fish and can be activated from fish_config if so desired.<br />
<br />
===Color the hostname in the prompt in SSH===<br />
To color the hostname in the prompt dynamically whenever connected through SSH, add the following lines in either the {{ic|fish_prompt}} function or the fish configuration file, here using the red color:<br />
<br />
{{hc|~/.config/fish/functions/fish_prompt.fish|<br />
...<br />
if set -q SSH_TTY<br />
set -g fish_color_host brred<br />
end<br />
...}}<br />
<br />
=== Evaluate ssh-agent ===<br />
<br />
In fish, {{ic|eval (ssh-agent)}} generate errors due to how variables are set. To work around this, use the csh-style option {{ic|-c}}:<br />
<br />
$ eval (ssh-agent -c)<br />
<br />
=== The "command not found" hook ===<br />
<br />
[[pkgfile]] includes a "command not found" hook that will automatically search the official repositories, when entering an unrecognized command. This hook will be run by default if {{Pkg|pkgfile}} is installed.<br />
<br />
=== Remove a process from the list of jobs ===<br />
<br />
''fish'' terminates any jobs put into the background when fish terminates. To keep a job running after fish terminates, first use the {{ic|disown}} builtin. For example, the following starts {{ic|firefox}} in the background and then disowns it:<br />
<br />
$ firefox &<br />
$ disown<br />
<br />
This means firefox will not be closed when the fish process is closed. See {{man|1|disown|url=}} in ''fish'' for more details.<br />
<br />
=== Set a persistent alias ===<br />
<br />
To quickly make a persistent alias, one can simply use the method showed in this example:<br />
$ alias lsl "ls -l"<br />
$ funcsave lsl<br />
Since fish version 3.0, alias support --save(-s) option.<br />
$ alias -s lsl "ls-l"<br />
<br />
This will create the function:<br />
function lsl<br />
ls -l $argv<br />
end<br />
<br />
and will set the alias as a persistent shell function. To see all functions and/or edit them, one can simply use {{ic|fish_config}} and look into the ''Function'' tab in the web configuration page.<br />
<br />
For more detailed information, see [https://fishshell.com/docs/current/cmds/alias.html alias - create a function — fish-shell].<br />
<br />
== See also ==<br />
<br />
* https://fishshell.com/ - Home page<br />
* https://fishshell.com/docs/current/ - Documentation<br />
* https://hyperpolyglot.org/unix-shells - Shell grammar correspondence table ("shell rosetta")<br />
* https://github.com/fish-shell/fish-shell - fish on GitHub</div>Simon04https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=606338XDG Base Directory2020-04-16T20:12:16Z<p>Simon04: /* Hardcoded */ +Ansible</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[Category:Configuration files]]<br />
[[Category:Development]]<br />
[[ja:XDG Base Directory サポート]]<br />
[[pt:XDG Base Directory]]<br />
{{Related articles start}}<br />
{{Related|dotfiles}}<br />
{{Related|XDG user directories}}<br />
{{Related articles end}}<br />
<br />
This article summarizes the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory specification] in [[#Specification]] and tracks software support in [[#Support]].<br />
<br />
== Specification ==<br />
<br />
Please read the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html full specification]. This section will attempt to break down the essence of what it tries to achieve.<br />
<br />
Only {{ic|XDG_RUNTIME_DIR}} is set by default through [https://www.freedesktop.org/software/systemd/man/pam_systemd.html pam_systemd]. It is up to the user to explicitly [[define]] the other variables according to the specification.<br />
<br />
=== User directories ===<br />
<br />
* {{ic|XDG_CONFIG_HOME}}<br />
** Where user-specific configurations should be written (analogous to {{ic|/etc}}).<br />
** Should default to {{ic|$HOME/.config}}.<br />
<br />
* {{ic|XDG_CACHE_HOME}}<br />
** Where user-specific non-essential (cached) data should be written (analogous to {{ic|/var/cache}}).<br />
** Should default to {{ic|$HOME/.cache}}.<br />
<br />
* {{ic|XDG_DATA_HOME}}<br />
** Where user-specific data files should be written (analogous to {{ic|/usr/share}}).<br />
** Should default to {{ic|$HOME/.local/share}}.<br />
<br />
* {{ic|XDG_RUNTIME_DIR}}<br />
** Used for non-essential, user-specific data files such as sockets, named pipes, etc.<br />
** Not required to have a default value; warnings should be issued if not set or equivalents provided.<br />
** Must be owned by the user with an access mode of {{ic|0700}}.<br />
** Filesystem fully featured by standards of OS.<br />
** Must be on the local filesystem.<br />
** May be subject to periodic cleanup.<br />
** Modified every 6 hours or set sticky bit if persistence is desired.<br />
** Can only exist for the duration of the user's login.<br />
** Should not store large files as it may be mounted as a tmpfs.<br />
<br />
=== System directories ===<br />
<br />
* {{ic|XDG_DATA_DIRS}}<br />
** List of directories separated by {{ic|:}} (analogous to {{ic|PATH}}).<br />
** Should default to {{ic|/usr/local/share:/usr/share}}.<br />
<br />
* {{ic|XDG_CONFIG_DIRS}}<br />
** List of directories separated by {{ic|:}} (analogous to {{ic|PATH}}).<br />
** Should default to {{ic|/etc/xdg}}.<br />
<br />
== Support ==<br />
<br />
This section exists to catalog the growing set of software using the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory Specification] introduced in 2003. This is here to demonstrate the viability of this specification by listing commonly found dotfiles and their support status. For those not currently supporting the Base Directory Specification, workarounds will be demonstrated to emulate it instead.<br />
<br />
The workarounds will be limited to anything not involving patching the source, executing code stored in [[environment variables]] or compile-time options. The rationale for this is that configurations should be portable across systems and having compile-time options prevent that.<br />
<br />
Hopefully this will provide a source of information about exactly what certain kinds of dotfiles are and where they come from.<br />
<br />
=== Contributing ===<br />
<br />
When contributing make sure to use the correct section.<br />
<br />
Nothing should require code evaluation (such as [[vim]] and {{ic|VIMINIT}}), patches or compile-time options to gain support and anything which does must be deemed hardcoded. Additionally if the process is too error prone or difficult, such as [https://www.haskell.org/cabal/ Haskell's cabal] or Eclipse, they should also be considered as hardcoded.<br />
<br />
* The first column should be either a link to an internal article, a [[Template:Pkg]] or a [[Template:AUR]].<br />
* The second column is for any legacy files and directories the project had (one per line), this is done so people can find them even if they are no longer read.<br />
* In the third, try to find the commit or version a project switched to XDG Base Directory or any open discussions and include them in the next two columns (two per line).<br />
* The last column should include any appropriate workarounds or solutions. Please verify that your solution is correct and functional.<br />
<br />
=== Supported ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Supported Since<br />
! Discussion<br />
! Notes<br />
|-<br />
| {{AUR|aerc-git}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|antimicro}}{{Broken package link|package not found}}<br />
| {{ic|~/.antimicro}}<br />
| [https://github.com/Antimicro/antimicro/commit/edba864 edba864]<br />
| [https://github.com/Antimicro/antimicro/issues/5]<br />
|<br />
|-<br />
| [[aria2]]<br />
| {{ic|~/.aria2}}<br />
| [https://github.com/tatsuhiro-t/aria2/commit/8bc1d37 8bc1d37]<br />
| [https://github.com/tatsuhiro-t/aria2/issues/27]<br />
|<br />
|-<br />
| {{Pkg|asunder}}<br />
|<br />
{{ic|~/.asunder<br><br />
~/.asunder_album_artist<br><br />
~/.asunder_album_genre<br><br />
~/.asunder_album_title}}<br />
| [https://littlesvr.ca/bugs/show_bug.cgi?id=31 2.9.0]<br />
| [https://littlesvr.ca/bugs/show_bug.cgi?id=52]<br />
| Uses {{ic|XDG_CONFIG_HOME/asunder/asunder}} for {{ic|~/.asunder}} and {{ic|XDG_CACHE_HOME/asunder/asunder_album_...}} for the other 3 files. Legacy paths are not removed after migration, they have to be deleted manually.<br />
|-<br />
| {{Pkg|binwalk}}<br />
| {{ic|~/.binwalk}}<br />
| [https://github.com/ReFirmLabs/binwalk/commit/2051757 2051757]<br />
| [https://github.com/ReFirmLabs/binwalk/issues/216]<br />
| {{ic|$XDG_CONFIG_HOME/binwalk}}<br />
|-<br />
| [[Blender]]<br />
| {{ic|~/.blender}}<br />
| [http://git.blender.org/gitweb/gitweb.cgi/blender.git/commit/4293f47 4293f47]<br />
| [https://developer.blender.org/T28943]<br />
|<br />
|-<br />
| {{Pkg|calcurse}}<br />
| {{ic|~/.calcurse}}<br />
| [https://github.com/lfos/calcurse/commit/04162d 04162d]<br />
| [https://github.com/lfos/calcurse/pull/254] [https://github.com/lfos/calcurse/issues/252]<br />
| {{ic|XDG_CONFIG_HOME/calcurse}}<br />
<br />
{{ic|XDG_DATA_HOME/calcurse}}<br />
<br />
If the legacy path {{ic|~/.calcurse}} is present, it will take precedence.<br />
|-<br />
| {{Pkg|calibre}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|citra-git}}<br />
| {{ic|~/.citra-emu}}<br />
| [https://github.com/citra-emu/citra/commit/f7c3193 f7c3193]<br />
| [https://github.com/citra-emu/citra/pull/575]<br />
|<br />
|-<br />
| [[Composer]]<br />
| {{ic|~/.composer}}<br />
| [https://github.com/composer/composer/releases/tag/1.0.0-beta1 1.0.0-beta1]<br />
| [https://github.com/composer/composer/pull/1407]<br />
|<br />
|-<br />
| {{Pkg|d-feet}}<br />
| {{ic|~/.d-feet}}<br />
| [https://gitlab.gnome.org/GNOME/d-feet/commit/7f6104b 7f6104b]<br />
|<br />
|<br />
|-<br />
| {{Pkg|dconf}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[Dolphin emulator]]<br />
| {{ic|~/.dolphin-emu}}<br />
| [https://github.com/dolphin-emu/dolphin/commit/a498c68 a498c68]<br />
| [https://github.com/dolphin-emu/dolphin/pull/2304]<br />
|<br />
|-<br />
| {{AUR|dr14_tmeter}}<br />
| <br />
| [https://github.com/simon-r/dr14_t.meter/commit/7e777ca 7e777ca]<br />
| [https://github.com/simon-r/dr14_t.meter/pull/30]<br />
| {{ic|XDG_CONFIG_HOME/dr14tmeter/}}<br />
|-<br />
| {{Pkg|dunst}}<br />
|<br />
| [https://github.com/dunst-project/dunst/commit/78b6e2b 78b6e2b]<br />
| [https://github.com/dunst-project/dunst/issues/22]<br />
|<br />
|-<br />
| [[dwb]]<br />
|<br />
|<br />
|<br />
|<br />
<br />
|-<br />
| [[fish]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[fontconfig]]<br />
|<br />
{{ic|~/.fontconfig<br><br />
~/.fonts}}<br />
| [https://cgit.freedesktop.org/fontconfig/commit/?id=8c255fb 8c255fb]<br />
|<br />
| Use {{ic|"$XDG_DATA_HOME"/fonts}} to store fonts instead.<br />
|-<br />
| {{Pkg|fontforge}}<br />
|<br />
{{ic|~/.FontForge<br><br />
~/.PfaEdit}}<br />
| [https://github.com/fontforge/fontforge/commit/e4c2cc7 e4c2cc7]<br />
|<br />
[https://github.com/fontforge/fontforge/issues/847]<br />
[https://github.com/fontforge/fontforge/issues/991]<br />
|<br />
|-<br />
| {{Pkg|freerdp}}<br />
| {{ic|~/.freerdp}}<br />
| [https://github.com/FreeRDP/FreeRDP/commit/edf6e72 edf6e72]<br />
|<br />
|<br />
|-<br />
| [[Gajim]]<br />
| {{ic|~/.gajim}}<br />
| [https://dev.gajim.org/gajim/gajim/commit/3e777ea 3e777ea]<br />
| [https://dev.gajim.org/gajim/gajim/issues/2149]<br />
|<br />
|-<br />
| {{AUR|gconf}}<br />
| {{ic|~/.gconf}}<br />
| [https://gitlab.gnome.org/Archive/gconf/commit/fc28caa fc28caa]<br />
| [https://bugzilla.gnome.org/show_bug.cgi?id=674803]<br />
|<br />
|-<br />
| [[GIMP]]<br />
|<br />
{{ic|~/.gimp-x.y<br><br />
~/.thumbnails}}<br />
|<br />
[https://gitlab.gnome.org/GNOME/gimp/commit/60e0cfe 60e0cfe]<br />
[https://gitlab.gnome.org/GNOME/gimp/commit/483505f 483505f]<br />
|<br />
[https://bugzilla.gnome.org/show_bug.cgi?id=166643]<br />
[https://bugzilla.gnome.org/show_bug.cgi?id=646644]<br />
|<br />
|-<br />
| [[Git]]<br />
| {{ic|~/.gitconfig}}<br />
| [https://github.com/git/git/commit/0d94427 0d94427]<br />
|<br />
|<br />
|-<br />
| [https://github.com/google/gops gops]<br />
| <br />
| [https://github.com/google/gops/commit/71c4255 71c4255]<br />
| <br />
|<br />
|-<br />
| [[GStreamer]]<br />
| {{ic|~/.gstreamer-0.10}}<br />
| [https://cgit.freedesktop.org/gstreamer/gstreamer/commit/?id=4e36f93 4e36f93]<br />
| [https://bugzilla.gnome.org/show_bug.cgi?id=518597]<br />
|<br />
|-<br />
| [[GTK]] 3<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|htop}}<br />
| {{ic|~/.htoprc}}<br />
| [https://github.com/hishamhm/htop/commit/93233a6 93233a6]<br />
|<br />
|<br />
|-<br />
| [[i3]]<br />
| {{ic|~/.i3}}<br />
| [http://code.stapelberg.de/git/i3/commit/?id=7c130fb 7c130fb]<br />
|<br />
|<br />
|-<br />
| {{Pkg|i3status}}<br />
| {{ic|~/.i3status.conf}}<br />
| [http://code.stapelberg.de/git/i3status/commit/?id=c3f7fc4 c3f7fc4]<br />
|<br />
|<br />
|-<br />
| {{Pkg|imagemagick}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[Inkscape]]<br />
| {{ic|~/.inkscape}}<br />
| [http://wiki.inkscape.org/wiki/index.php/Release_notes/0.47#Preferences 0.47]<br />
| [https://bugs.launchpad.net/inkscape/+bug/199720]<br />
|<br />
|-<br />
| [https://iwd.wiki.kernel.org/ iwd] / iwctl<br />
| {{ic|~/.iwctl_history}}<br />
| [https://git.kernel.org/pub/scm/network/wireless/iwd.git/commit/?id=d3e00d7f d3e00d7f]<br />
|<br />
|<br />
|-<br />
| {{Pkg|intellij-idea-community-edition}}<br />
| {{ic|~/.IntelliJIdea*}}<br />
| [https://confluence.jetbrains.com/display/IDEADEV/IntelliJ%2BIDEA%2B2020.1%2B%28201.6668.121%2Bbuild%29%2BRelease%2BNotes 2020.1]<br />
| [https://youtrack.jetbrains.com/issue/IDEA-22407]<br />
|<br />
|-<br />
| {{Pkg|josm}}<br />
| {{ic|~/.josm}}<br />
| [https://josm.openstreetmap.de/changeset/11162/josm 11162]<br />
| [https://josm.openstreetmap.de/ticket/6664]<br />
|<br />
|-<br />
| [[Kakoune]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| latexmk (in {{Pkg|texlive-core}})<br />
| {{ic|~/.latexmkrc}}<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|lftp}}<br />
| {{ic|~/.lftp}}<br />
| [https://github.com/lavv17/lftp/commit/21dc400 21dc400]<br />
| [https://www.mail-archive.com/lftp@uniyar.ac.ru/msg04301.html]<br />
|<br />
|-<br />
| {{AUR|lgogdownloader}}<br />
| {{ic|~/.gogdownloader}}<br />
| [https://github.com/Sude-/lgogdownloader/commit/d430af6 d430af6]<br />
| [https://github.com/Sude-/lgogdownloader/issues/4]<br />
|<br />
|-<br />
| [[LibreOffice]]<br />
|<br />
|<br />
[https://cgit.freedesktop.org/libreoffice/ure/commit/?id=a6f56f7 a6f56f7]<br />
[https://cgit.freedesktop.org/libreoffice/bootstrap/commit/?id=25bd2ee 25bd2ee]<br />
| [https://bugs.documentfoundation.org/show_bug.cgi?id=32263]<br />
|<br />
|-<br />
| [[Streamlink]]<br />
| {{ic|~/.livestreamerrc}}<br />
| [https://github.com/chrippa/livestreamer/commit/ea80591 ea80591]<br />
| [https://github.com/chrippa/livestreamer/pull/106]<br />
|<br />
|-<br />
| [[llpp]]<br />
|<br />
| [http://repo.or.cz/w/llpp.git/commit/3ab86f0 3ab86f0]<br />
|<br />
| Currently ''llpp'' places the configuration directly under {{ic|XDG_CONFIG_HOME}} instead of creating a directory.<br />
|-<br />
| [[mc]]<br />
| {{ic|~/.mc}}<br />
|<br />
[https://github.com/MidnightCommander/mc/commit/1b99570 1b99570]<br />
[https://github.com/MidnightCommander/mc/commit/0b71156 0b71156]<br />
[https://github.com/MidnightCommander/mc/commit/ce401d7 ce401d7]<br />
| [https://www.midnight-commander.org/ticket/1851]<br />
|<br />
|-<br />
| [[Mercurial]]<br />
| {{ic|~/.hgrc}}<br />
|<br />
[https://www.mercurial-scm.org/repo/hg/rev/3540200 3540200]<br />
[https://www.mercurial-scm.org/wiki/Release4.2 4.2]<br />
|<br />
| {{ic|XDG_CONFIG_HOME/hg/hgrc}}.<br />
|-<br />
| [[msmtp]]<br />
| {{ic|~/.msmtprc}}<br />
|<br />
[https://github.com/marlam/msmtp-mirror/commit/af2f409 af2f409]<br />
v1.6.7+<br />
|<br />
| {{ic| XDG_CONFIG_HOME/msmtp/config}}.<br />
|-<br />
| {{Pkg|mesa}}<br />
|<br />
| [https://cgit.freedesktop.org/mesa/mesa/commit/?id=87ab26b 87ab26b]<br />
|<br />
| {{ic|XDG_CACHE_HOME/mesa}}<br />
|-<br />
| {{Pkg|milkytracker}}<br />
| {{ic|~/.milkytracker_config}}<br />
| [https://github.com/Deltafire/MilkyTracker/commit/eb487c5 eb487c5]<br />
| [https://github.com/Deltafire/MilkyTracker/issues/12]<br />
|<br />
|-<br />
| [[mpd]]<br />
| {{ic|~/.mpdconf}}<br />
| [https://github.com/MusicPlayerDaemon/MPD/commit/87b7328 87b7328]<br />
|<br />
|<br />
|-<br />
| [[mpv]]<br />
| {{ic|~/.mpv}}<br />
| [https://github.com/mpv-player/mpv/commit/cb250d4 cb250d4]<br />
| [https://github.com/mpv-player/mpv/pull/864]<br />
|<br />
|-<br />
| [[mutt]]<br />
| {{ic|~/.mutt}}<br />
| [https://gitlab.com/muttmua/mutt/commit/b17cd67 b17cd67]<br />
| [https://gitlab.com/muttmua/trac-tickets/raw/master/tickets/closed/3207-Conform_to_XDG_Base_Directory_Specification.txt]<br />
|<br />
|-<br />
| {{Pkg|mypaint}}<br />
| {{ic|~/.mypaint}}<br />
| [https://github.com/mypaint/mypaint/commit/cf723b7 cf723b7]<br />
|<br />
|<br />
|-<br />
| [[nano]]<br />
|<br />
{{ic|~/.nano/<br><br />
~/.nanorc}}<br />
| [http://git.savannah.gnu.org/cgit/nano.git/commit/?id=c16e79b c16e79b]<br />
| [https://savannah.gnu.org/patch/?8523]<br />
|<br />
|-<br />
| [[ncmpcpp]]<br />
| {{ic|~/.ncmpcpp}}<br />
|<br />
[https://github.com/arybczak/ncmpcpp/commit/38d9f81 38d9f81]<br />
[https://github.com/arybczak/ncmpcpp/commit/27cd86e 27cd86e]<br />
|<br />
[https://github.com/arybczak/ncmpcpp/issues/79]<br />
[https://github.com/arybczak/ncmpcpp/issues/110]<br />
| {{ic|ncmpcpp_directory}} should be set to avoid an {{ic|error.log}} file in {{ic|~/.ncmpcpp}}.<br />
|-<br />
| [[Neovim]]<br />
|<br />
{{ic|~/.nvim<br><br />
~/.nvimlog<br><br />
~/.nviminfo}}<br />
| [https://github.com/neovim/neovim/commit/1ca5646 1ca5646]<br />
|<br />
[https://github.com/neovim/neovim/issues/78]<br />
[https://github.com/neovim/neovim/pull/3198]<br />
|<br />
|-<br />
| [[newsbeuter]]<br />
| {{ic|~/.newsbeuter}}<br />
| [https://github.com/akrennmair/newsbeuter/commit/3c57824 3c57824]<br />
| [https://github.com/akrennmair/newsbeuter/pull/39]<br />
| It is required to create both directories [http://newsbeuter.org/doc/newsbeuter.html#_xdg_base_directory_support]:<br />
<br />
{{ic|1=$ mkdir -p "$XDG_DATA_HOME"/newsbeuter "$XDG_CONFIG_HOME"/newsbeuter}}<br />
|-<br />
| [https://github.com/nodejs/node-gyp node-gyp]<br />
| {{ic|~/.node-gyp}}<br />
| [https://github.com/nodejs/node-gyp/commit/2b5ce52a 2b5ce52a]<br />
| [https://github.com/nodejs/node-gyp/pull/1570]<br />
| Only available on master as of 2018-12-04.<br />
|-<br />
| {{AUR|np2kai-git}}<br />
|<br />
{{ic|~/.config/np2kai<br><br />
~/.config/xnp2kai}}<br />
| [https://github.com/AZO234/NP2kai/commit/56a1cc2 56a1cc2]<br />
| [https://github.com/AZO234/NP2kai/pull/50]<br />
|<br />
|-<br />
| {{AUR|nteract-bin}}<br />
|<br />
| [https://github.com/nteract/nteract/commit/4593e72 4593e72]<br />
| [https://github.com/nteract/nteract/issues/180] [https://github.com/nteract/nteract/pull/3870]<br />
| [https://github.com/nteract/nteract/issues/4517 does not recognize workarounds for ipython/jupyter]<br />
|-<br />
| [[OfflineIMAP]]<br />
| {{ic|~/.offlineimaprc}}<br />
| [https://github.com/OfflineIMAP/offlineimap/commit/5150de5 5150de5]<br />
| [https://github.com/OfflineIMAP/offlineimap/issues/32]<br />
|<br />
|-<br />
| {{AUR|opentyrian}}<br />
| {{ic|~/.opentyrian}}<br />
| [https://bitbucket.org/opentyrian/opentyrian/commits/8d45ff2 8d45ff2]<br />
| [https://web.archive.org/web/20140815181350/http://code.google.com/p/opentyrian/issues/detail?id=125]<br />
|<br />
|-<br />
| {{Pkg|pandoc}}<br />
| {{ic|~/.pandoc/}}<br />
| [https://github.com/jgm/pandoc/commit/0bed0ab5a308f5e72a01fa9bee76488556288862 0bed0ab]<br />
| [https://github.com/jgm/pandoc/issues/3582]<br />
|<br />
|-<br />
| {{Pkg|pcsx2}}<br />
| {{ic|~/.pcsx2}}<br />
|<br />
[https://github.com/PCSX2/pcsx2/commit/87f1e8f 87f1e8f]<br />
[https://github.com/PCSX2/pcsx2/commit/a9020c6 a9020c6]<br />
[https://github.com/PCSX2/pcsx2/commit/3b22f0f 3b22f0f]<br />
[https://github.com/PCSX2/pcsx2/commit/0a012ae 0a012ae]<br />
| [https://github.com/PCSX2/pcsx2/issues/352] [https://github.com/PCSX2/pcsx2/issues/381]<br />
|<br />
|-<br />
| [http://pryrepl.org/ Pry]<br />
| {{ic|~/.pryrc<br>~/.pry_history}}<br />
|<br />
[https://github.com/pry/pry/commit/a0be0cc7b2070edff61c0c7f10fa37fce9b730bd a0be0cc7]<br />
[https://github.com/pry/pry/commit/15e1fc929ed84c161abc5afc9be73488a41df397 15e1fc92]<br />
[https://github.com/pry/pry/commit/e9d1be0e17b294318dbb2f70f74a50486cfa044c e9d1be0e]<br />
| [https://github.com/pry/pry/issues/1316]<br />
|<br />
|-<br />
| {{Pkg|python-pip}}<br />
| {{ic|~/.pip}}<br />
| [https://github.com/pypa/pip/blob/548a9136525815dff41acd845c558a0b36eb1c5f/NEWS.rst#60-2014-12-22 6.0]<br />
| [https://github.com/pypa/pip/issues/1733]<br />
|<br />
|-<br />
| {{AUR|powershell}}<br />
|<br />
| [https://docs.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-core-60#filesystem 6.0]<br />
|<br />
|<br />
|-<br />
| {{Pkg|ppsspp}}<br />
| {{ic|~/.ppsspp}}<br />
| [https://github.com/hrydgard/ppsspp/commit/132fe47 132fe47]<br />
| [https://github.com/hrydgard/ppsspp/issues/4623]<br />
|<br />
|-<br />
| {{Pkg|procps-ng}}<br />
| {{ic|~/.toprc}}<br />
| [https://gitlab.com/procps-ng/procps/commit/af53e17 af53e17]<br />
|<br />
[https://gitlab.com/procps-ng/procps/merge_requests/38]<br />
[https://bugzilla.redhat.com/show_bug.cgi?id=1155265]<br />
|<br />
|-<br />
| {{AUR|orbment-git}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[pacman]]<br />
| {{ic|~/.makepkg.conf}}<br />
| [https://projects.archlinux.org/pacman.git/commit/?id=80eca94 80eca94]<br />
| [https://mailman.archlinux.org/pipermail/pacman-dev/2014-July/019178.html]<br />
|<br />
|-<br />
| {{AUR|panda3d}}<br />
| {{ic|~/.panda3d}}<br />
| [https://github.com/panda3d/panda3d/commit/2b537d2 2b537d2]<br />
|<br />
|<br />
|-<br />
| {{AUR|poezio}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[PulseAudio]]<br />
|<br />
{{ic|~/.pulse<br><br />
~/.pulse-cookie}}<br />
|<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=59a8618 59a8618]<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=87ae830 87ae830]<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=9ab510a 9ab510a]<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=4c195bc 4c195bc]<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=845607]<br />
|<br />
|-<br />
| {{AUR|pyroom}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|quodlibet}}<br />
| {{ic|~/.quodlibet}}<br />
| 3.10.0<br />
| [https://github.com/quodlibet/quodlibet/issues/138]<br />
|<br />
|-<br />
| [[qutebrowser]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[qtile]]<br />
|<br />
|<br />
[https://github.com/qtile/qtile/commit/fd8686e fd8686e]<br />
[https://github.com/qtile/qtile/commit/66d704b 66d704b]<br />
[https://github.com/qtile/qtile/commit/51cff01 51cff01]<br />
| [https://github.com/qtile/qtile/pull/835]<br />
| Some optional bar widgets can create files and directories in non-compliant paths, but most often these are still configurable.<br />
|-<br />
| {{Pkg|rclone}}<br />
| {{ic|~/.rclone.conf}}<br />
| [https://github.com/ncw/rclone/commit/9d36258 9d36258]<br />
| [https://github.com/ncw/rclone/issues/868]<br />
|<br />
|-<br />
| {{Pkg|retroarch}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|rr}}<br />
| {{ic|~/.rr}}<br />
| [https://github.com/mozilla/rr/commit/02e7d41 02e7d41]<br />
| [https://github.com/mozilla/rr/issues/1455]<br />
|<br />
|-<br />
| [https://rspec.info RSpec]<br />
| {{ic|~/.rspec}}<br />
| [https://github.com/rspec/rspec-core/commit/5e395e2016f1da19475e6db2817eb26dae828c4c 5e395e2]<br />
| [https://github.com/rspec/rspec-core/issues/1773]<br />
|<br />
|-<br />
| [[rTorrent]]<br />
| {{ic|~/.rtorrent.rc}}<br />
| [https://github.com/rakshasa/rtorrent/commit/6a8d332 6a8d332]<br />
|<br />
|<br />
|-<br />
| [https://www.rubocop.org RuboCop]<br />
| {{ic|~/.rubocop.yml}}<br />
| [https://github.com/rubocop-hq/rubocop/commit/6fe5956c177ca369cfaa70bdf748b70020a56bf4 6fe5956]<br />
| [https://github.com/rubocop-hq/rubocop/issues/6662]<br />
|<br />
|-<br />
| {{AUR|skypeforlinux-stable-bin}}<br />
| {{ic|~/.Skype}}<br />
| 8.0<br />
|<br />
|<br />
|-<br />
| {{Pkg|snes9x}}<br />
| {{ic|~/.snes9x}}<br />
| [https://github.com/snes9xgit/snes9x/commit/93b5f11 93b5f11]<br />
| [https://github.com/snes9xgit/snes9x/issues/194]<br />
| By default, the configuration file is left blank with intention that the user will fill it at their will (through the gui or manually).<br />
|-<br />
| {{AUR|sublime-text-dev}}<br />
|<br />
|<br />
|<br />
| Cache is placed in {{ic|$XDG_CONFIG_HOME/sublime-text-3/Cache}} instead of expected {{ic|$XDG_CACHE_HOME/sublime-text-3}}.<br />
|-<br />
| [[surfraw]]<br />
|<br />
{{ic|~/.surfraw.conf<br><br />
~/.surfraw.bookmarks}}<br />
|<br />
[https://gitlab.com/surfraw/Surfraw/commit/3e4591d 3e4591d]<br />
[https://gitlab.com/surfraw/Surfraw/commit/bd8c427 bd8c427]<br />
[https://gitlab.com/surfraw/Surfraw/commit/f57fc71 f57fc71]<br />
|<br />
|<br />
|-<br />
| [[sway]]<br />
| {{ic|~/.sway/config}}<br />
| [https://github.com/SirCmpwn/sway/commit/614393c 614393c]<br />
| [https://github.com/SirCmpwn/sway/issues/5]<br />
|<br />
|-<br />
| [[systemd]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|teeworlds}}<br />
| {{ic|~/.teeworlds}}<br />
| [https://github.com/teeworlds/teeworlds/commit/d2e39d2f50684151490da446156622e69dd84a48]<br />
|<br />
| <br />
|-<br />
| [[termite]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|tig}}<br />
| {{ic|~/.tigrc}}, {{ic|~/.tig_history}}<br />
| [https://github.com/jonas/tig/blob/master/NEWS.adoc#tig-22 2.2]<br />
| [https://github.com/jonas/tig/issues/513]<br />
| {{ic|~/.local/share/tig}} directory must exist, writes to {{ic|~/.tig_history}} otherwise.<br />
|-<br />
| {{AUR|tmuxinator}}<br />
| {{ic|~/.tmuxinator}}<br />
| [https://github.com/tmuxinator/tmuxinator/pull/511/commits/2636923 2636923]<br />
| [https://github.com/tmuxinator/tmuxinator/pull/511]<br />
|<br />
|-<br />
| [[Transmission]]<br />
| {{ic|~/.transmission}}<br />
| [https://github.com/transmission/transmission/commit/b71a298 b71a298]<br />
|<br />
|<br />
|-<br />
| {{Pkg|util-linux}}<br />
|<br />
| [https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git/commit/?id=570b321 570b321]<br />
|<br />
|<br />
|-<br />
| [[Uzbl]]<br />
|<br />
| [https://github.com/uzbl/uzbl/commit/c6fd63a c6fd63a]<br />
| [https://github.com/uzbl/uzbl/pull/150]<br />
|<br />
|-<br />
| {{Pkg|vimb}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[VirtualBox]]<br />
| {{ic|~/.VirtualBox}}<br />
| [https://www.virtualbox.org/ticket/5099?action=diff&version=7 4.3]<br />
| [https://www.virtualbox.org/ticket/5099]<br />
|<br />
|-<br />
| {{Pkg|vis}}<br />
| {{ic|~/.vis}}<br />
|<br />
[https://github.com/martanne/vis/commit/68a25c7 68a25c7]<br />
[https://github.com/martanne/vis/commit/d138908 d138908]<br />
| [https://github.com/martanne/vis/pull/303]<br />
|<br />
|-<br />
| [[VLC]]<br />
| {{ic|~/.vlcrc}}<br />
| [http://git.videolan.org/?p=vlc.git;a=commit;h=16f32e1 16f32e1]<br />
| [https://trac.videolan.org/vlc/ticket/1267]<br />
|<br />
|-<br />
| {{Pkg|warsow}}<br />
| {{ic|~/.warsow-2.x}}<br />
| [https://github.com/Qfusion/qfusion/commit/98ece3f 98ece3f]<br />
| [https://github.com/Qfusion/qfusion/issues/298]<br />
|<br />
|-<br />
| [[Wireshark]]<br />
| {{ic|~/.wireshark}}<br />
| [https://code.wireshark.org/review/gitweb?p=wireshark.git;a=commit;h=b0b53fa b0b53fa]<br />
|<br />
|<br />
|-<br />
| {{AUR|xsettingsd-git}}<br />
| {{ic|~/.xsettingsd}}<br />
| [https://github.com/derat/xsettingsd/commit/b4999f5 b4999f5]<br />
|<br />
|<br />
|-<br />
| [[xmonad]]<br />
| {{ic|~/.xmonad}}<br />
| [https://github.com/xmonad/xmonad/commit/40fc10b 40fc10b]<br />
|<br />
[https://github.com/xmonad/xmonad/issues/61]<br />
[https://code.google.com/p/xmonad/issues/detail?id=484]<br />
| Alternatively the environments {{ic|XMONAD_CONFIG_HOME}}, {{ic|XMONAD_DATA_HOME}}, and {{ic|XMONAD_CACHE_HOME}} are also available.<br />
|-<br />
| {{Pkg|xsel}}<br />
| {{ic|~/.xsel.log}}<br />
| [https://github.com/kfish/xsel/commit/ee7b481 ee7b481]<br />
| [https://github.com/kfish/xsel/issues/10]<br />
|<br />
|-<br />
| {{Pkg|yarn}}<br />
|<br />
{{ic|~/.yarnrc<br><br />
~/.yarn/<br><br />
~/.yarncache/<br><br />
~/.yarn-config/}}<br />
| [https://github.com/yarnpkg/yarn/commit/2d454b5 2d454b5]<br />
| [https://github.com/yarnpkg/yarn/pull/5336]<br />
|<br />
|}<br />
<br />
=== Partial ===<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Supported Since<br />
! Discussion<br />
! Notes<br />
|-<br />
| {{Pkg|abook}}<br />
| {{ic|~/.abook}}<br />
|<br />
|<br />
| {{ic|1=$ abook --config "$XDG_CONFIG_HOME"/abook/abookrc --datafile "$XDG_DATA_HOME"/abook/addressbook}}<br />
|-<br />
| {{Pkg|ack}}<br />
| {{ic|~/.ackrc}}<br />
|<br />
| [https://github.com/beyondgrep/ack2/issues/516]<br />
| {{ic|1=$ export ACKRC="$XDG_CONFIG_HOME/ack/ackrc"}}<br />
|-<br />
| [[Anki]]<br />
|<br />
{{ic|~/Anki<br><br />
~/Documents/Anki}}<br />
|<br />
| [https://github.com/dae/anki/pull/49] [https://github.com/dae/anki/pull/58]<br />
| {{ic|1=$ anki -b "$XDG_DATA_HOME"/Anki}}<br />
|-<br />
| [[aspell]]<br />
| {{ic|~/.aspell.conf}}<br />
|<br />
|<br />
| {{ic|1=$ export ASPELL_CONF="per-conf $XDG_CONFIG_HOME/aspell/aspell.conf; personal $XDG_CONFIG_HOME/aspell/en.pws; repl $XDG_CONFIG_HOME/aspell/en.prepl"}}<br />
|-<br />
| [[Atom]]<br />
| {{ic|~/.atom}}<br />
|<br />
| [https://github.com/atom/atom/issues/8281]<br />
| {{ic|1=$ export ATOM_HOME="$XDG_DATA_HOME"/atom}}<br />
|-<br />
| {{Pkg|aws-cli}}<br />
| {{ic|~/.aws}}<br />
| [https://github.com/aws/aws-cli/commit/fc5961ea2cc0b5976ac9f777e20e4236fd7540f5 1.7.45]<br />
| [https://github.com/aws/aws-cli/issues/2433]<br />
|<br />
{{ic|1=$ export AWS_SHARED_CREDENTIALS_FILE="$XDG_CONFIG_HOME"/aws/credentials<br><br />
$ export AWS_CONFIG_FILE="$XDG_CONFIG_HOME"/aws/config}}<br />
|-<br />
| {{Pkg|bash-completion}}<br />
| {{ic|~/.bash_completion}}<br />
|<br />
| <br />
| {{ic|1=$ export BASH_COMPLETION_USER_FILE="$XDG_CONFIG_HOME"/bash-completion/bash_completion}}<br />
|-<br />
| [[bazaar]]<br />
|<br />
{{ic|~/.bazaar<br><br />
~/.bzr.log}}<br />
| [https://bugs.launchpad.net/bzr/+bug/195397/comments/15 2.3.0]<br />
| [https://bugs.launchpad.net/bzr/+bug/195397]<br />
| Discussion in upstream bug states that bazaar will use {{ic|~/.config/bazaar}} if it exists. The logfile {{ic|~/.bzr.log}} might still be written.<br />
|-<br />
| {{Aur|buchhaltung-git}}<br />
|<br />
{{ic|~/.buchhaltung}}<br />
| <br />
| [https://github.com/johannesgerer/buchhaltung/issues/44]<br />
| {{ic|1=$ export BUCHHALTUNG="$XDG_CONFIG_HOME"/buchhaltung}}<br />
|-<br />
| [[Ruby#Bundler]]<br />
| {{ic|~/.bundle}}<br />
|<br />
| [https://github.com/bundler/bundler/pull/6024] [https://github.com/bundler/bundler/issues/4333]<br />
| {{ic|1=$ export BUNDLE_USER_CONFIG="$XDG_CONFIG_HOME"/bundle BUNDLE_USER_CACHE="$XDG_CACHE_HOME"/bundle BUNDLE_USER_PLUGIN="$XDG_DATA_HOME"/bundle}}<br />
|-<br />
| [[Rust#Cargo]]<br />
| {{ic|~/.cargo}}<br />
|<br />
| [https://github.com/rust-lang/cargo/issues/1734] [https://github.com/rust-lang/rfcs/pull/1615] [https://github.com/rust-lang/cargo/pull/5183] [https://github.com/rust-lang/cargo/pull/148]<br />
| {{ic|1=$ export CARGO_HOME="$XDG_DATA_HOME"/cargo}}<br />
|-<br />
| [[ccache]]<br />
| {{ic|~/.ccache}}<br />
|<br />
|<br />
| {{ic|1=$ export CCACHE_CONFIGPATH="$XDG_CONFIG_HOME"/ccache.config}}<br><br />
{{ic|1=$ export CCACHE_DIR="$XDG_CACHE_HOME"/ccache}}<br />
|-<br />
| {{AUR|chez-scheme}}<br />
| {{ic|~/.chezscheme_history}}<br />
|<br />
|<br />
| {{ic|1=$ petite --eehistory "$XDG_DATA_HOME"/chezscheme/history}}<br />
|-<br />
| [[Chromium]]<br />
| {{ic|~/.chromium<br><br />
~/.pki}}<br />
| [https://src.chromium.org/viewvc/chrome?revision=23057&view=revision 23057]<br />
|<br />
[https://groups.google.com/forum/#!topic/chromium-dev/QekVQxF3nho]<br />
[https://code.google.com/p/chromium/issues/detail?id=16976]<br />
[https://bugs.chromium.org/p/chromium/issues/detail?id=1038587]<br />
|<br />
|-<br />
| [[conky]]<br />
| {{ic|~/.conkyrc}}<br />
| [https://github.com/brndnmtthws/conky/commit/00481ee9a97025e8e2acd7303d080af1948f7980 00481ee]<br />
| [https://github.com/brndnmtthws/conky/issues/144]<br />
| {{ic|1=$ conky --config="$XDG_CONFIG_HOME"/conky/conkyrc}}<br />
|-<br />
| [[coreutils]]<br />
| {{ic|~/.dircolors}}<br />
|<br />
|<br />
| {{ic|1=$ eval $(dircolors "$XDG_CONFIG_HOME"/dircolors)}}<br />
|-<br />
| [http://www.dungeoncrawl.org/ crawl]<br />
| {{ic|~/.crawl}}<br />
|<br />
|<br />
| The trailing slash is required:<br />
<br />
{{ic|1=$ export CRAWL_DIR="$XDG_DATA_HOME"/crawl/}}<br />
|-<br />
| {{Pkg|clusterssh}}<br />
| {{ic|~/.clusterssh/}}<br />
|<br />
|<br />
| {{ic|1=$ alias cssh="cssh --config-file '$XDG_CONFIG_HOME/clusterssh/config'" }}<br />
{{hc|$XDG_CONFIG_HOME/clusterssh/config|2=<br />
extra_cluster_file=$HOME/.config/clusterssh/clusters<br />
extra_tag_file=$HOMe/.config/clusterssh/tags<br />
}}<br />
Despite this, clusterssh will still create {{ic|~/.clusterssh/}}.<br />
|-<br />
| [[CUDA]]<br />
| {{ic|~/.nv}}<br />
|<br />
|<br />
| {{ic|1=$ export CUDA_CACHE_PATH="$XDG_CACHE_HOME"/nv}}<br />
|-<br />
| [[dict]]<br />
| {{ic|~/.dictrc}}<br />
|<br />
|<br />
| {{ic|1=$ dict -c "$XDG_CONFIG_HOME"/dict/dictrc}}<br />
|-<br />
| [[Docker]]<br />
| {{ic|~/.docker}}<br />
|<br />
|<br />
| {{ic|1=$ export DOCKER_CONFIG="$XDG_CONFIG_HOME"/docker}}<br />
|-<br />
| {{Pkg|docker-machine}}<br />
| {{ic|~/.docker/machine}}<br />
|<br />
|<br />
| {{ic|1=$ export MACHINE_STORAGE_PATH="$XDG_DATA_HOME"/docker-machine}}<br />
|-<br />
| [[DOSBox]]<br />
| {{ic|~/.dosbox/dosbox-0.74-2.conf}}<br />
|<br />
| [https://www.vogons.org/viewtopic.php?t=29599]<br />
| {{ic|1=$ dosbox -conf "$XDG_CONFIG_HOME"/dosbox/dosbox.conf}}<br />
|-<br />
| [https://electrum.org Electrum Bitcoin Wallet]<br />
| {{ic|~/.electrum}}<br />
| [https://github.com/spesmilo/electrum/commit/c121230 c121230]<br />
| <br />
| {{ic|1=$ export ELECTRUMDIR="$XDG_DATA_HOME/electrum"}}<br />
|-<br />
| [[ELinks]]<br />
| {{ic|~/.elinks}}<br />
|<br />
|<br />
| {{ic|1=$ export ELINKS_CONFDIR="$XDG_CONFIG_HOME"/elinks}}<br />
|-<br />
| {{Pkg|elixir}}<br />
| {{ic|~/.mix}}<br />
| [https://github.com/elixir-lang/elixir/commit/afaf889 afaf889]<br />
| [https://github.com/elixir-lang/elixir/issues/8818] [https://github.com/elixir-lang/elixir/pull/9937]<br />
| Elixir do not fully conform to XDG specs, it will use XDG only if the environment variables are present, otherwise it will by default use legacy path.<br />
|-<br />
| [[Emacs]]<br />
|<br />
{{ic|~/.emacs<br><br />
~/.emacs.d/}}<br />
| [https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=4118297ae2fab4886b20d193ba511a229637aea3]<br />
| <br />
| Not in 26.3 or older. Workaround for older versions: It's possible to set {{ic|HOME}}, but it has unexpected side effects. So far the most promising approach is modifying another Emacs environment variable to alter the load path and author your own site file which can manually load up your init file, but it changes the load process significantly.<br />
|-<br />
| {{Pkg|emscripten}}<br />
|<br />
{{ic|~/.emscripten<br><br />
~/.emscripten_sanity<br><br />
~/.emscripten_ports<br><br />
~/.emscripten_cache__last_clear}}<br />
|<br />
| [https://github.com/kripken/emscripten/issues/3624]<br />
|<br />
{{ic|1=$ export EM_CONFIG="$XDG_CONFIG_HOME"/emscripten/config<br><br />
$ export EM_CACHE="$XDG_CACHE_HOME"/emscripten/cache<br><br />
$ export EM_PORTS="$XDG_DATA_HOME"/emscripten/cache<br><br />
$ emcc --em-config "$XDG_CONFIG_HOME"/emscripten/config --em-cache "$XDG_CACHE_HOME"/emscripten/cache}}<br />
|-<br />
| {{AUR|freecad}}<br />
| {{ic|~/.FreeCAD}}<br />
|<br />
| [https://www.freecadweb.org/tracker/view.php?id=2956]<br />
| {{ic|1=$ freecad -u "$XDG_CONFIG_HOME"/FreeCAD/user.cfg -s "$XDG_CONFIG_HOME"/FreeCAD/system.cfg}}<br />
<br />
Despite these options, {{AUR|freecad}} will still create the file {{ic|.FreeCAD/cookie}} as the web module has it [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Web/Gui/CookieJar.cpp#L55 hard coded]<br />
|-<br />
| [[GDB]]<br />
| {{ic|~/.gdbinit}}<br />
|<br />
|<br />
| {{ic|1=$ gdb -nh -x "$XDG_CONFIG_HOME"/gdb/init}}<br />
|-<br />
| {{AUR|get_iplayer}}<br />
| {{ic|~/.get_iplayer}}<br />
|<br />
|<br />
| {{ic|1=$ export GETIPLAYERUSERPREFS="$XDG_DATA_HOME"/get_iplayer}}<br />
|-<br />
| [[getmail]]<br />
| {{ic|~/.getmail/getmailrc}}<br />
|<br />
|<br />
| {{ic|1=$ getmail --rcfile="$XDG_CONFIG_HOME/getmail/getmailrc" --getmaildir="$XDG_DATA_HOME/getmail"}}<br />
|-<br />
| {{AUR|gliv}}<br />
| {{ic|~/.glivrc}}<br />
|<br />
|<br />
| {{ic|1=$ gliv --glivrc="$XDG_CONFIG_HOME"/gliv/glivrc}}<br />
|-<br />
| [[GnuPG]]<br />
| {{ic|~/.gnupg}}<br />
|<br />
| [https://bugs.gnupg.org/gnupg/issue1456] [https://bugs.gnupg.org/gnupg/issue1018]<br />
|<br />
{{ic|1=$ export GNUPGHOME="$XDG_DATA_HOME"/gnupg<br><br />
$ gpg2 --homedir "$XDG_DATA_HOME"/gnupg}}<br />
|-<br />
| [[Go]]<br />
| {{ic|~/go}}<br />
| [https://github.com/golang/go/commit/ca8a055f5cc7c1dfa0eb542c60071c7a24350f76]<br />
|<br />
|<br />
{{ic|1=$ export GOPATH="$XDG_DATA_HOME"/go}}<br />
|-<br />
| [[Google Earth]]<br />
| {{ic|~/.googleearth}}<br />
|<br />
|<br />
| Some paths can be changed with the {{ic|KMLPath}} and {{ic|CachePath}} options in {{ic|~/.config/Google/GoogleEarthPlus.conf}}<br />
|-<br />
| {{Pkg|gopass}}<br />
| {{ic|~/.password-store}}<br />
|<br />
|<br />
| Override settings in {{ic|~/.config/gopass/config.yml}}:<br />
{{hc|~/.config/gopass/config.yml|<br />
root:<br />
path: gpgcli-gitcli-fs+file:///home/<userid>/.config/password-store<br />
}}<br />
|-<br />
| [https://sourceforge.net/projects/gqclient GQ LDAP client]<br />
|<br />
{{ic|~/.gq<br><br />
~/.gq-state}}<br />
| [https://sourceforge.net/p/gqclient/mailman/message/2053978 1.51]<br />
|<br />
|<br />
{{ic|1=$ export GQRC="$XDG_CONFIG_HOME"/gqrc<br><br />
$ export GQSTATE="$XDG_DATA_HOME"/gq/gq-state<br><br />
$ mkdir -p "$(dirname "$GQSTATE")"}}<br />
|-<br />
| [[Gradle]]<br />
| {{ic|~/.gradle}}<br />
|<br />
| [https://discuss.gradle.org/t/be-a-nice-freedesktop-citizen-move-the-gradle-to-the-appropriate-location-in-linux/2199]<br />
| {{ic|1=$ export GRADLE_USER_HOME="$XDG_DATA_HOME"/gradle}}<br />
|-<br />
| [[GTK]] 1<br />
| {{ic|~/.gtkrc}}<br />
|<br />
|<br />
| {{ic|1=$ export GTK_RC_FILES="$XDG_CONFIG_HOME"/gtk-1.0/gtkrc}}<br />
|-<br />
| [[GTK]] 2<br />
| {{ic|~/.gtkrc-2.0}}<br />
|<br />
|<br />
| {{ic|1=$ export GTK2_RC_FILES="$XDG_CONFIG_HOME"/gtk-2.0/gtkrc}}<br />
|-<br />
| {{Pkg|hledger}}<br />
| {{ic|~/.hledger.journal}}<br />
|<br />
| [https://github.com/simonmichael/hledger/issues/1081]<br />
| {{ic|1=$ export LEDGER_FILE="$XDG_DATA_HOME"/hledger.journal}}<br />
|-<br />
| {{AUR|imapfilter}}<br />
| {{ic|~/.imapfilter}}<br />
| <br />
| <br />
| {{ic|1=$ export IMAPFILTER_HOME="$XDG_CONFIG_HOME/imapfilter"}}<br />
|-<br />
| {{Pkg|httpie}}<br />
| {{ic|~/.httpie}}<br />
|<br />
| [https://github.com/jakubroztocil/httpie/issues/145]<br />
| {{ic|1=$ export HTTPIE_CONFIG_DIR="$XDG_CONFIG_HOME"/httpie}}<br />
|-<br />
| [http://ipython.org ipython]/[[jupyter]]<br />
| {{ic|~/.ipython}}<br />
|<br />
| [https://github.com/ipython/ipython/pull/4457 won't fix]<br />
|<br />
{{ic|1=$ export IPYTHONDIR="$XDG_CONFIG_HOME"/jupyter<br><br />
$ export JUPYTER_CONFIG_DIR="$XDG_CONFIG_HOME"/jupyter}}<br />
|-<br />
| [https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html irb]<br />
| {{ic|~/.irbrc}}<br />
|<br />
|<br />
| {{hc|1=~/.profile|2=$ export IRBRC="$XDG_CONFIG_HOME"/irb/irbrc}}<br />
{{hc|1="$XDG_CONFIG_HOME"/irb/irbrc|2=IRB.conf[:SAVE_HISTORY] {{!}}{{!}}= 1000<br />
IRB.conf[:HISTORY_FILE] {{!}}{{!}}= File.join(ENV["XDG_DATA_HOME"], "irb", "history")}}<br />
|-<br />
| [[irssi]]<br />
| {{ic|~/.irssi}}<br />
|<br />
| [https://github.com/irssi/irssi/pull/511]<br />
| {{ic|1=$ irssi --config="$XDG_CONFIG_HOME"/irssi/config --home="$XDG_DATA_HOME"/irssi}}<br />
|-<br />
| [[isync]]<br />
| {{ic|~/.mbsyncrc}}<br />
|<br />
|<br />
| {{ic|1=$ mbsync -c "$XDG_CONFIG_HOME"/isync/mbsyncrc}}<br />
|-<br />
| [[Java#OpenJDK]]<br />
| {{ic|~/.java/.userPrefs}}<br />
|<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=1154277]<br />
| {{ic|1=$ export _JAVA_OPTIONS=-Djava.util.prefs.userRoot="$XDG_CONFIG_HOME"/java}}<br />
|-<br />
| [[KDE]]<br />
| {{ic|~/.kde}}<br />
|<br />
| [https://userbase.kde.org/KDE_System_Administration/KDE_Filesystem_Hierarchy#KDEHOME]<br />
| {{ic|1=$ export KDEHOME="$XDG_CONFIG_HOME"/kde}}<br />
|-<br />
| [[ledger]]<br />
| {{ic|~/.ledgerrc}}, {{ic|~/.pricedb}}<br />
|<br />
| [https://github.com/ledger/ledger/issues/1820]<br />
| {{ic|1=$ ledger --init-file "$XDG_CONFIG_HOME"/ledgerrc}}<br />
|-<br />
| [[Core utilities|less]]<br />
| {{ic|~/.lesshst}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ mkdir -p "$XDG_CACHE_HOME"/less<br><br />
$ export LESSKEY="$XDG_CONFIG_HOME"/less/lesskey<br><br />
$ export LESSHISTFILE="$XDG_CACHE_HOME"/less/history}}<br />
<br />
{{ic|1=$ export LESSHISTFILE=-}} can be used to disable this feature.<br />
|-<br />
| {{Pkg|libdvdcss}}<br />
| {{ic|~/.dvdcss}}<br />
|<br />
| [https://mailman.videolan.org/pipermail/libdvdcss-devel/2014-August/001022.html]<br />
| {{ic|1=$ export DVDCSS_CACHE="$XDG_DATA_HOME"/dvdcss}}<br />
|-<br />
| {{Pkg|libice}}<br />
| {{ic|~/.ICEauthority}}<br />
|<br />
| [https://gitlab.freedesktop.org/xorg/lib/libice/issues/2]<br />
| {{ic|1=$ export ICEAUTHORITY="$XDG_CACHE_HOME"/ICEauthority}}<br />
Make sure {{ic|XDG_CACHE_HOME}} is set beforehand to directory user running [[Xorg]] has write access to.<br />
<br />
'''Do not''' use {{ic|XDG_RUNTIME_DIR}} as it is available '''after''' login. Display managers that launch [[Xorg]] (like [[GDM]]) will repeatedly fail otherwise.<br />
|-<br />
| [[Xorg|libx11]]<br />
|<br />
{{ic|~/.XCompose<br><br />
~/.compose-cache}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export XCOMPOSEFILE="$XDG_CONFIG_HOME"/X11/xcompose<br><br />
$ export XCOMPOSECACHE="$XDG_CACHE_HOME"/X11/xcompose}}<br />
|-<br />
| {{Pkg|ltrace}}<br />
| {{ic|~/.ltrace.conf}}<br />
|<br />
|<br />
| {{ic|1=$ ltrace -F "$XDG_CONFIG_HOME"/ltrace/ltrace.conf}}<br />
|-<br />
| {{Pkg|maven}}<br />
| {{ic|~/.m2}}<br />
|<br />
| [https://issues.apache.org/jira/browse/MNG-6603]<br />
| {{ic|1=$ mvn -gs "$XDG_CONFIG_HOME"/maven/settings.xml}}<br />
{{hc|[http://maven.apache.org/settings.html settings.xml]|<nowiki><settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0<br />
https://maven.apache.org/xsd/settings-1.0.0.xsd"><br />
...<br />
<localRepository>${env.XDG_CACHE_HOME}/maven/repository</localRepository><br />
...<br />
</settings></nowiki>}}<br />
|-<br />
| [[Mathematica]]<br />
| {{ic|~/.Mathematica}}<br />
|<br />
|<br />
| {{ic|1=$ export MATHEMATICA_USERBASE="$XDG_CONFIG_HOME"/mathematica}}<br />
|-<br />
| {{Pkg|mednafen}}<br />
| {{ic|~/.mednafen}}<br />
|<br />
|<br />
| {{ic|1=$ export MEDNAFEN_HOME="$XDG_CONFIG_HOME"/mednafen}}<br />
|-<br />
| {{Pkg|mitmproxy}}<br />
| {{ic|~/.mitmproxy}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ alias mitmproxy="mitmproxy --set confdir=$XDG_CONFIG_HOME/mitmproxy"<br><br />
$ alias mitmweb="mitmweb --set confdir=$XDG_CONFIG_HOME/mitmproxy"}}<br />
|-<br />
| [[MOC]]<br />
| {{ic|~/.moc}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ mocp -M "$XDG_CONFIG_HOME"/moc<br><br />
$ mocp -O MOCDir="$XDG_CONFIG_HOME"/moc}}<br />
|-<br />
| {{Pkg|monero}}<br />
| {{ic|~/.bitmonero}}<br />
|<br />
|<br />
| {{ic|1=$ monerod --data-dir "$XDG_DATA_HOME"/bitmonero}}<br />
|-<br />
| {{Pkg|most}}<br />
| {{ic|~/.mostrc}}<br />
|<br />
|<br />
| {{ic|1=$ export MOST_INITFILE="$XDG_CONFIG_HOME"/mostrc}}<br />
|-<br />
| [[MPlayer]]<br />
| {{ic|~/.mplayer}}<br />
|<br />
|<br />
| {{ic|1=$ export MPLAYER_HOME="$XDG_CONFIG_HOME"/mplayer}}<br />
|-<br />
| [[MySQL]]<br />
| {{ic|~/.mysql_history}}<br />
|<br />
|<br />
| {{ic|1=$ export MYSQL_HISTFILE="$XDG_DATA_HOME"/mysql_history}}<br />
|-<br />
| {{Pkg|ncurses}}<br />
| {{ic|~/.terminfo}}<br />
|<br />
|<br />
| Precludes system path searching:<br />
<br />
{{ic|1=$ export TERMINFO="$XDG_DATA_HOME"/terminfo<br><br />
$ export TERMINFO_DIRS="$XDG_DATA_HOME"/terminfo:/usr/share/terminfo}}<br />
|-<br />
| {{Pkg|ncmpc}}<br />
| {{ic|~/.ncmpc}}<br />
|<br />
|<br />
| {{ic|ncmpc -f "$XDG_CONFIG_HOME"/ncmpc/config}}<br />
|-<br />
| [[Netbeans]]<br />
| {{ic|~/.netbeans}}<br />
|<br />
| [https://netbeans.org/bugzilla/show_bug.cgi?id=215961]<br />
| {{ic|1=$ netbeans --userdir "${XDG_CONFIG_HOME}"/netbeans}}<br />
|-<br />
| [[Node.js]]<br />
| {{ic|~/.node_repl_history}}<br />
|<br />
|<br />
| {{ic|1=$ export NODE_REPL_HISTORY="$XDG_DATA_HOME"/node_repl_history}} [https://nodejs.org/api/repl.html#repl_environment_variable_options]<br />
|-<br />
| [[notmuch]]<br />
| {{ic|~/.notmuch-config}}<br />
|<br />
| [http://notmuchmail.org/pipermail/notmuch/2011/007007.html]<br />
|<br />
{{ic|1=$ export NOTMUCH_CONFIG="$XDG_CONFIG_HOME"/notmuch/notmuchrc<br><br />
$ export NMBGIT="$XDG_DATA_HOME"/notmuch/nmbug}}<br />
|-<br />
| {{Pkg|npm}}<br />
|<br />
{{ic|~/.npm<br><br />
~/.npmrc}}<br />
|<br />
| [https://github.com/npm/cli/issues/654]<br />
| {{ic|1=$ export NPM_CONFIG_USERCONFIG=$XDG_CONFIG_HOME/npm/npmrc}}<br />
{{hc|npmrc|<nowiki><br />
prefix=${XDG_DATA_HOME}/npm<br />
cache=${XDG_CACHE_HOME}/npm<br />
tmp=${XDG_RUNTIME_DIR}/npm<br />
init-module=${XDG_CONFIG_HOME}/npm/config/npm-init.js<br />
</nowiki>}}<br />
{{ic|prefix}} is unnecessary (and unsupported) if Node.js is installed by {{AUR|nvm}}.<br />
|-<br />
| {{Pkg|nuget}}<br />
| {{ic|~/.nuget/packages}}<br />
|<br />
| [https://docs.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders]<br />
| {{ic|1=$ export NUGET_PACKAGES="$XDG_CACHE_HOME"/NuGetPackages}}<br />
|-<br />
| [[NVIDIA]]<br />
| {{ic|~/.nv}}<br />
|<br />
|<br />
| Uses {{ic|XDG_CACHE_HOME}} if set, otherwise improperly falls back to {{ic|~/.nv}} instead of {{ic|~/.cache}}.<br />
|-<br />
| {{Pkg|nvidia-settings}}<br />
| {{ic|~/.nvidia-settings-rc}}<br />
|<br />
|<br />
| {{ic|1=$ nvidia-settings --config="$XDG_CONFIG_HOME"/nvidia/settings}}<br />
|-<br />
| {{AUR|nvm}}<br />
| {{ic|~/.nvm}}<br />
|<br />
|<br />
| {{ic|1=$ export NVM_DIR="$XDG_DATA_HOME"/nvm}}<br />
|-<br />
| [[Octave]]<br />
|<br />
{{ic|~/octave<br><br />
~/.octave_packages<br><br />
~/.octave_hist}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export OCTAVE_HISTFILE="$XDG_CACHE_HOME/octave-hsts"<br><br />
$ export OCTAVE_SITE_INITFILE="$XDG_CONFIG_HOME/octave/octaverc"}}<br />
<br />
{{hc|$XDG_CONFIG_HOME/octave/octaverc|<nowiki><br />
source /usr/share/octave/site/m/startup/octaverc;<br />
pkg prefix ~/.local/share/octave/packages ~/.local/share/octave/packages;<br />
pkg local_list /home/<your username>/.local/share/octave/octave_packages;<br />
</nowiki>}}<br />
The {{ic|local_list}} option must be given an absolute path.<br />
|-<br />
| {{Pkg|openscad}}<br />
| {{ic|~/.OpenSCAD}}<br />
| [https://github.com/openscad/openscad/commit/7c3077b0f 7c3077b0f]<br />
| [https://github.com/openscad/openscad/issues/125]<br />
| Does not fully honour XDG Base Directory Specification, see [https://github.com/openscad/openscad/issues/373]<br />
<br />
Currently it [https://github.com/openscad/openscad/blob/master/src/PlatformUtils-posix.cc#L20 hard-codes] {{ic|~/.local/share}}.<br />
|-<br />
| [[OpenSSL]]<br />
| {{ic|~/.rnd}}<br />
|<br />
|<br />
| Seeding file {{ic|.rnd}}'s location can be set with {{ic|RANDFILE}} environment variable per [https://www.openssl.org/docs/faq.html FAQ].<br />
|-<br />
| {{Pkg|parallel}}<br />
| {{ic|~/.parallel}}<br />
| [https://git.savannah.gnu.org/cgit/parallel.git/commit/?id=685018f532f4e2d24b84eb28d5de3d759f0d1af1 20170422]<br />
|<br />
| {{ic|1=$ export PARALLEL_HOME="$XDG_CONFIG_HOME"/parallel}}<br />
|-<br />
| [[Pass]]<br />
| {{ic|~/.password-store}}<br />
|<br />
|<br />
| {{ic|1=$ export PASSWORD_STORE_DIR="$XDG_DATA_HOME"/pass}}<br />
|-<br />
| [[Pidgin]]<br />
| {{ic|~/.purple}}<br />
|<br />
| [https://developer.pidgin.im/ticket/4911]<br />
| {{ic|1=$ pidgin --config="$XDG_DATA_HOME"/purple}}<br />
|-<br />
| [[PostgreSQL]]<br />
|<br />
{{ic|~/.psqlrc<br><br />
~/.psql_history<br><br />
~/.pgpass<br><br />
~/.pg_service.conf}}<br />
| 9.2<br />
| [https://www.postgresql.org/docs/current/static/app-psql.html] [https://www.postgresql.org/docs/current/static/libpq-envars.html]<br />
|<br />
{{ic|1=$ export PSQLRC="$XDG_CONFIG_HOME/pg/psqlrc"<br><br />
$ export PSQL_HISTORY="$XDG_CACHE_HOME/pg/psql_history"<br><br />
$ export PGPASSFILE="$XDG_CONFIG_HOME/pg/pgpass"<br><br />
$ export PGSERVICEFILE="$XDG_CONFIG_HOME/pg/pg_service.conf"}}<br />
<br />
It is required to create both directories: {{ic|1=$ mkdir "$XDG_CONFIG_HOME/pg" && mkdir "$XDG_CACHE_HOME/pg"}}<br />
|-<br />
| [[PulseAudio]]<br />
| {{ic|~/.esd_auth}}<br />
|<br />
|<br />
| Very likely generated by the {{ic|module-esound-protocol-unix.so}} module. It can be configured to use a different location but it makes much more sense to just comment out this module in {{ic|/etc/pulse/default.pa}} or {{ic|"$XDG_CONFIG_HOME"/pulse/default.pa}}.<br />
|-<br />
| {{aur|python-azure-cli}}<br />
| {{ic|~/.azure}}<br />
|<br />
|<br />
| {{ic|1=$ export AZURE_CONFIG_DIR=$XDG_DATA_HOME/azure}}<br />
|-<br />
| {{AUR|python-grip}}<br />
| {{ic|~/.grip}}<br />
|<br />
| <br />
| {{ic|1=$ export GRIPHOME="$XDG_CONFIG_HOME/grip"}}<br />
|-<br />
| {{Pkg|python-setuptools}}<br />
| {{ic|~/.python-eggs}}<br />
|<br />
|<br />
| {{ic|1=$ export PYTHON_EGG_CACHE="$XDG_CACHE_HOME"/python-eggs}}<br />
|-<br />
| {{Pkg|python-pylint}}<br />
| {{ic|~/.pylint.d}}<br />
|<br />
| [https://github.com/PyCQA/pylint/issues/1364 won't fix]<br />
| {{ic|1=$ export PYLINTHOME="$XDG_CACHE_HOME"/pylint}}<br />
|-<br />
| {{Pkg|racket}}<br />
| {{ic|~/.racketrc<br><br />
~/.racket}}<br />
|<br />
| [https://github.com/racket/racket/issues/2740]<br />
| {{ic|1=$ export PLTUSERHOME="$XDG_DATA_HOME"/racket}}<br />
|-<br />
| [[readline]]<br />
| {{ic|~/.inputrc}}<br />
|<br />
|<br />
| {{ic|1=$ export INPUTRC="$XDG_CONFIG_HOME"/readline/inputrc}}<br />
|-<br />
| {{Pkg|rlwrap}}<br />
| {{ic|~/.*_history}}<br />
|<br />
| [https://github.com/hanslub42/rlwrap/issues/25]<br />
| {{ic|1=$ export RLWRAP_HOME="$XDG_DATA_HOME"/rlwrap}}<br />
|-<br />
| [[Ruby#RubyGems]]<br />
| {{ic|~/.gem}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export GEM_HOME="$XDG_DATA_HOME"/gem<br><br />
$ export GEM_SPEC_CACHE="$XDG_CACHE_HOME"/gem}}<br />
<br />
Make sure to remove {{ic|gem: --user-install}} from {{ic|/etc/gemrc}}<br />
|-<br />
| [[Rust#Rustup]]<br />
| {{ic|~/.rustup}}<br />
|<br />
| [https://github.com/rust-lang-nursery/rustup.rs/issues/247]<br />
| {{ic|1=$ export RUSTUP_HOME="$XDG_DATA_HOME"/rustup}}<br />
|-<br />
| {{Pkg|sbt}}<br />
| {{ic|~/.sbt}}<br />
{{ic|~/.ivy2}}<br />
|<br />
| [https://github.com/sbt/sbt/issues/3681]<br />
| {{ic|1=$ sbt -ivy "$XDG_DATA_HOME"/ivy2 -sbt-dir "$XDG_DATA_HOME"/sbt}} (beware [https://github.com/sbt/sbt/issues/3598])<br />
|-<br />
| [[GNU Screen]]<br />
| {{ic|~/.screenrc}}<br />
|<br />
|<br />
| {{ic|1=$ export SCREENRC="$XDG_CONFIG_HOME"/screen/screenrc}}<br />
|-<br />
| [[Haskell#Stack]]<br />
| {{ic|~/.stack}}<br />
|<br />
| [https://github.com/commercialhaskell/stack/issues/342]<br />
| {{ic|1=$ export STACK_ROOT="$XDG_DATA_HOME"/stack}}<br />
|-<br />
| [[subversion]]<br />
| {{ic|~/.subversion}}<br />
|<br />
| [https://issues.apache.org/jira/browse/SVN-4599] [https://mail-archives.apache.org/mod_mbox/subversion-users/201204.mbox/%3c4F8FBCC6.4080205@ritsuka.org%3e][http://mail-archives.apache.org/mod_mbox/subversion-dev/201509.mbox/%3c20150917222954.GA20331@teapot%3e]<br />
| {{ic|1=$ svn --config-dir "$XDG_CONFIG_HOME"/subversion}}<br />
|-<br />
| {{Pkg|task}}<br />
|<br />
{{ic|~/.task<br><br />
~/.taskrc}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export TASKDATA="$XDG_DATA_HOME"/task<br><br />
$ export TASKRC="$XDG_CONFIG_HOME"/task/taskrc}}<br />
|-<br />
| {{AUR|tiptop}}<br />
| {{ic|~/.tiptoprc}}<br />
|<br />
|<br />
| This will still expect the {{ic|.tiptoprc}} file.<br />
{{ic|$ tiptop -W "$XDG_CONFIG_HOME"/tiptop}}<br />
|-<br />
| [[tmux]]<br />
| {{ic|~/.tmux.conf}}<br />
|<br />
| [https://github.com/tmux/tmux/issues/142]<br />
| {{ic|1=$ tmux -f "$XDG_CONFIG_HOME"/tmux/tmux.conf}}<br />
<br />
{{ic|1=$ export TMUX_TMPDIR="$XDG_RUNTIME_DIR"}}<br />
|-<br />
| {{Pkg|uncrustify}}<br />
| {{ic|~/.uncrustify.cfg}}<br />
|<br />
|<br />
| {{ic|1=$ export UNCRUSTIFY_CONFIG="$XDG_CONFIG_HOME"/uncrustify/uncrustify.cfg}}<br />
|-<br />
| [[Unison]]<br />
| {{ic|~/.unison}}<br />
|<br />
|<br />
| {{ic|1=$ export UNISON="$XDG_DATA_HOME"/unison}}<br />
|-<br />
| [[Rxvt-unicode/Tips_and_tricks#Daemon-client|urxvtd]]<br />
| {{ic|~/.urxvt/urxvtd-hostname}}<br />
|<br />
|<br />
| {{ic|1=$ export RXVT_SOCKET="$XDG_RUNTIME_DIR"/urxvtd}}<br />
|-<br />
| [[Vagrant]]<br />
|<br />
{{ic|~/.vagrant.d<br><br />
~/.vagrant.d/aliases}}<br />
|<br />
| [https://www.vagrantup.com/docs/other/environmental-variables.html]<br />
|<br />
{{ic|1=$ export VAGRANT_HOME="$XDG_DATA_HOME"/vagrant<br><br />
$ export VAGRANT_ALIAS_FILE="$XDG_DATA_HOME"/vagrant/aliases}}<br />
|-<br />
| [[Visual Studio Code]]<br />
| {{ic|~/.vscode-oss/argv.json}}<br />
|<br />
| [https://github.com/Microsoft/vscode/issues/3884]<br />
| <br />
|-<br />
| [[AUR|WakaTime]]<br />
| <br />
{{ic|~/.wakatime.cfg<br><br />
~/.wakatime.data<br><br />
~/.wakatime.db<br><br />
~/.wakatime.log}}<br />
|<br />
|<br />
| {{ic|1=$ export WAKATIME_HOME="$XDG_CONFIG_HOME/wakatime"}}<br />
<br />
The directory needs to be created manually:<br><br />
{{ic|1=$ mkdir "$XDG_CONFIG_HOME/wakatime"}}<br />
|-<br />
| [[WeeChat]]<br />
| {{ic|~/.weechat}}<br />
|<br />
| [http://savannah.nongnu.org/task/?10934] [https://github.com/ipython/ipython/pull/4457]<br />
|<br />
{{ic|1=$ export WEECHAT_HOME="$XDG_CONFIG_HOME"/weechat<br><br />
$ weechat -d "$XDG_CONFIG_HOME"/weechat}}<br />
|-<br />
| [[wget]]<br />
|<br />
{{ic|~/.wgetrc<br><br />
~/.wget-hsts}}<br />
|<br />
|<br />
| <br />
{{ic|1=$ export WGETRC="$XDG_CONFIG_HOME/wgetrc"<br><br />
and add the following as an alias for wget:<br><br />
$ wget --hsts-file="$XDG_CACHE_HOME/wget-hsts"<br><br />
or set the hsts-file variable with an absolute path as wgetrc does not support environment variables:<br><br />
$ echo hsts-file \= "$XDG_CACHE_HOME"/wget-hsts >> "$XDG_CONFIG_HOME/wgetrc"}}<br />
|-<br />
| [[wine]]<br />
| {{ic|~/.wine}}<br />
|<br />
| [https://bugs.winehq.org/show_bug.cgi?id=20888]<br />
| [[Wine#Winetricks|Winetricks]] uses XDG-alike location below for [[Wine#WINEPREFIX|WINEPREFIX]] management:<br />
{{ic|1=$ mkdir -p "$XDG_DATA_HOME"/wineprefixes<br><br />
$ export WINEPREFIX="$XDG_DATA_HOME"/wineprefixes/default}}<br />
|-<br />
| [[xbindkeys]]<br />
| {{ic|~/.xbindkeysrc}}<br />
|<br />
|<br />
| {{ic|1=$ xbindkeys -f "$XDG_CONFIG_HOME"/xbindkeys/config}}<br />
|-<br />
| {{Pkg|xorg-xauth}}<br />
| {{ic|~/.Xauthority}}<br />
|<br />
|<br />
| {{ic|1=$ export XAUTHORITY="$XDG_RUNTIME_DIR"/Xauthority}}<br />
<br />
Note that [[LightDM]] does not allow you to change this variable. If you change it nonetheless, you will not be able to login. Use [[startx]] instead or [https://askubuntu.com/a/961459 configure LightDM]. According to [https://unix.stackexchange.com/a/175331] [[SLiM]] has {{ic|~/.Xauthority}} hardcoded.<br />
|-<br />
| [[xinit]]<br />
|<br />
{{ic|~/.xinitrc<br><br />
~/.xserverrc}}<br />
|<br />
| [https://gitlab.freedesktop.org/xorg/app/xinit/issues/14]<br />
|<br />
{{ic|1=$ export XINITRC="$XDG_CONFIG_HOME"/X11/xinitrc<br><br />
$ export XSERVERRC="$XDG_CONFIG_HOME"/X11/xserverrc}}<br />
<br />
Note that these variables are respected by ''xinit'', but not by ''startx''. Instead, specify the filename as an argument:<br />
<br />
{{ic|1=$ startx "$XDG_CONFIG_HOME/X11/xinitrc" -- "$XDG_CONFIG_HOME/X11/xserverrc" vt1}}<br />
|-<br />
| {{Pkg|xorg-xrdb}}<br />
|<br />
{{ic|~/.Xresources<br><br />
~/.Xdefaults}}<br />
|<br />
|<br />
| Ultimately you [https://superuser.com/questions/243914/xresources-or-xdefaults should be] using {{ic|Xresources}} and since these resources are loaded via {{ic|xrdb}} you can specify a path such as {{ic|1=$ xrdb -load ~/.config/X11/xresources}}.<br />
|-<br />
| {{Pkg|z}}<br />
|<br />
{{ic|~/.z}}<br />
|<br />
| [https://github.com/rupa/z/issues/267]<br />
| {{ic|1=$ export _Z_DATA="$XDG_DATA_HOME/z"}}<br />
|-<br />
|}<br />
<br />
=== Hardcoded ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Discussion<br />
! Notes<br />
|-<br />
| [[adb]]<br />
| {{ic|~/.android/}}<br />
| [https://developer.android.com/studio/command-line/variables.html#android_sdk_root]<br />
| {{ic|1=$ export ANDROID_SDK_HOME="$XDG_CONFIG_HOME"/android}}<br />
|-<br />
| [[Ansible]]<br />
| {{ic|~/.ansible}}<br />
| [https://github.com/ansible/ansible/issues/52354]<br />
|<br />
<br />
|-<br />
| [[AMule]]<br />
| {{ic|~/.aMule}}<br />
|<br />
|<br />
|-<br />
| [https://developer.android.com/studio/index.html Android Studio]<br />
|<br />
{{ic|~/.AndroidStudio2.3<br><br />
~/.android/<br><br />
~/.java/}}<br />
|<br />
|<br />
|-<br />
| [https://osdn.net/projects/anthy/ anthy]<br />
| {{ic|~/.anthy}}<br />
| [https://osdn.net/ticket/browse.php?group_id=14&tid=28397]<br />
|<br />
|-<br />
| [https://directory.apache.org/studio/ Apache Directory Studio]<br />
| {{ic|~/.ApacheDirectoryStudio}}<br />
|<br />
|<br />
|-<br />
| [https://christian.amsuess.com/tools/arandr/ ARandR]<br />
| {{ic|~/.screenlayout}}<br />
|<br />
|<br />
|-<br />
| [[Arduino]]<br />
|<br />
{{ic|~/.arduino15<br><br />
~/.jssc}} <br />
| [https://github.com/arduino/Arduino/issues/3915 won't fix]<br />
|<br />
|-<br />
| [https://www.audacityteam.org/ Audacity]<br />
| {{ic|~/.audacity-data/}}<br />
|<br />
|<br />
|-<br />
| [http://fixounet.free.fr/avidemux/ Avidemux]<br />
| {{ic|~/.avidemux6}}<br />
|<br />
|<br />
|-<br />
| [[Bash]]<br />
|<br />
{{ic|~/.bashrc<br><br />
~/.bash_history<br><br />
~/.bash_profile<br><br />
~/.bash_login<br><br />
~/.bash_logout}}<br />
| [http://savannah.gnu.org/support/?108134 won't fix]<br />
| {{ic|1=$ export HISTFILE="$XDG_DATA_HOME"/bash/history}}<br />
A specified {{ic|bashrc}} can be sourced from {{ic|/etc/bash.bashrc}}.<br />
<br />
Specify {{ic|--init-file <file>}} as an alternative to {{ic|~/.bashrc}} for interactive shells.<br />
|-<br />
| [https://www.haskell.org/cabal/ cabal]<br />
| {{ic|~/.cabal/}}<br />
| [https://github.com/haskell/cabal/issues/680]<br />
| See discussion for potential workarounds. It is not very easy or straightforward but may be possible to emulate Base Directory compliance.<br />
|-<br />
| {{AUR|chatty}}<br />
| {{ic|~/.chatty/}}<br />
| [https://github.com/chatty/chatty/issues/273]<br />
|<br />
|-<br />
| {{Pkg|cmake}}<br />
| {{ic|~/.cmake/}}<br />
|<br />
| Used for the user package registry {{ic|~/.cmake/packages/<package>}}, detailed in {{man|7|cmake-packages|User Package Registry}} and [https://gitlab.kitware.com/cmake/community/wikis/doc/tutorials/Package-Registry the Package registry wiki page]. Looks like it's hardcoded, for example in [https://gitlab.kitware.com/cmake/cmake/blob/v3.12.1/Source/cmFindPackageCommand.cxx#L1221 cmFindPackageCommand.cxx].<br />
|-<br />
| [[Cinnamon]]<br />
| {{ic|~/.cinnamon/}}<br />
| [https://github.com/linuxmint/Cinnamon/issues/7807]<br />
|<br />
|-<br />
| {{AUR|cryptomator}}<br />
| {{ic|~/.Cryptomator}}<br />
| [https://github.com/cryptomator/cryptomator/issues/710]<br />
|<br />
|-<br />
| [[CUPS]]<br />
| {{ic|~/.cups/}}<br />
| [https://github.com/apple/cups/issues/4243 won't fix]<br />
|<br />
|-<br />
| [[darcs]]<br />
| {{ic|~/.darcs/}}<br />
| [http://bugs.darcs.net/issue2453]<br />
|<br />
|-<br />
| [[dbus]]<br />
| {{ic|~/.dbus/}}<br />
| [https://gitlab.freedesktop.org/dbus/dbus/issues/46]<br />
| This should be avoidable with kdbus [citation needed].<br />
|-<br />
| {{Pkg|devede}}<br />
| {{ic|~/.devedeng}}<br />
|<br />
| Hardcoded [https://gitlab.com/rastersoft/devedeng/blob/f0893b3ff7b14723bd148db35bdfe2d284156d19/src/devedeng/configuration_data.py#L111 here]<br />
|-<br />
| [https://wiki.gnome.org/Apps/Dia Dia]<br />
| {{ic|~/.dia/}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|dotnet-sdk}}<br />
| {{ic|~/.dotnet/}}<br />
| [https://github.com/dotnet/cli/issues/7569]<br />
|<br />
|-<br />
| [[Eclipse]]<br />
| {{ic|~/.eclipse/}}<br />
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=200809]<br />
| Option {{ic|1=-Dosgi.configuration.area=@user.home/.config/..}} overrides but must be added to {{ic|"$ECLIPSE_HOME"/eclipse.ini"}} rather than command line which means you must have write access to {{ic|$ECLIPSE_HOME}}. (Arch Linux hard-codes {{ic|$ECLIPSE_HOME}} in {{ic|/usr/bin/eclipse}})<br />
|-<br />
| [http://www.fetchmail.info/ Fetchmail]<br />
| {{ic|~/.fetchmailrc}}<br />
|<br />
|<br />
|-<br />
| [[Firefox]]<br />
| {{ic|~/.mozilla/}}<br />
| [https://bugzil.la/259356]<br />
|<br />
|-<br />
| [[Flatpak]]<br />
| {{ic|~/.var/}}<br />
| [https://github.com/flatpak/flatpak/issues/46] [https://github.com/flatpak/flatpak.github.io/issues/191] [https://github.com/flatpak/flatpak/issues/1651 won't fix]<br />
|<br />
|-<br />
| {{Pkg|fltk}}<br />
| {{ic|~/.fltk/}}<br />
| [https://www.fltk.org/str.php?L3370+P0+S0+C0+I0+E0+V%25+Qxdg]<br />
|<br />
|-<br />
| [https://www.haskell.org/ghc/ GHC]<br />
| {{ic|~/.ghc}}<br />
| [https://ghc.haskell.org/trac/ghc/ticket/6077]<br />
|<br />
|-<br />
| {{Pkg|ghidra}}<br />
|<br />
| [https://github.com/NationalSecurityAgency/ghidra/issues/908]<br />
|<br />
|-<br />
| [[Goldendict]]<br />
| {{ic|~/.goldendict/}}<br />
| [https://github.com/goldendict/goldendict/issues/151]<br />
|<br />
|-<br />
| {{Pkg|gramps}}<br />
| {{ic|~/.gramps/}}<br />
| [https://gramps-project.org/bugs/view.php?id=8025]<br />
| <br />
|-<br />
| {{Pkg|grsync}}<br />
| {{ic|~/.grsync/}}<br />
| [https://sourceforge.net/p/grsync/feature-requests/15/]<br />
|<br />
|-<br />
| [http://recordmydesktop.sourceforge.net/about.php gtk-recordMyDesktop]<br />
| {{ic|~/.gtk-recordmydesktop}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|hplip}}<br />
| {{ic|~/.hplip/}}<br />
| [https://bugs.launchpad.net/hplip/+bug/307152]<br />
|<br />
|-<br />
| [http://www.idris-lang.org/ idris]<br />
| {{ic|~/.idris}}<br />
| [https://github.com/idris-lang/Idris-dev/pull/3456]<br />
|<br />
|-<br />
| [[Java]] OpenJDK<br />
| {{ic|~/.java/fonts}}<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=1154277]<br />
|<br />
|-<br />
| [[Java]] OpenJFX<br />
| {{ic|~/.java/webview}}<br />
|<br />
|<br />
|-<br />
| [http://julialang.org/ julia]<br />
|<br />
{{ic|~/.juliarc.jl<br><br />
~/.julia_history}}<br />
| [https://github.com/JuliaLang/julia/issues/4630] [https://github.com/JuliaLang/julia/issues/10016]<br />
|<br />
|-<br />
| [http://www.linux-pam.org/ Linux PAM]<br />
| {{ic|~/.pam_environment}}<br />
| [https://github.com/linux-pam/linux-pam/issues/7]<br />
| Hardcoded in [https://github.com/linux-pam/linux-pam/blob/master/modules/pam_env/pam_env.c modules/pam_env/pam_env.c]<br />
|-<br />
| [http://lldb.llvm.org/ lldb]<br />
|<br />
{{ic|~/.lldb<br><br />
~/.lldbinit}}<br />
|<br />
|<br />
|-<br />
| [http://www.mathomatic.org/ mathomatic]<br />
|<br />
{{ic|~/.mathomaticrc<br><br />
~/.matho_history}}<br />
|<br />
| History can be moved by using {{ic|rlwrap mathomatic -r}} with the {{ic|RLWRAP_HOME}} environment set appropriately.<br />
|-<br />
| [[Minecraft]]<br />
| {{ic|~/.minecraft/}}<br />
| [https://bugs.mojang.com/browse/MCL-2563]<br />
|<br />
|-<br />
| [[Minetest]]<br />
| {{ic|~/.minetest/}}<br />
| [https://github.com/minetest/minetest/issues/864 won't fix] [https://github.com/minetest/minetest/issues/8151]<br />
|<br />
|-<br />
| [https://www.mongodb.org/ mongodb]<br />
|<br />
{{ic|~/.mongorc.js<br><br />
~/.dbshell}}<br />
| [https://jira.mongodb.org/browse/DOCS-5652?jql=text%20~%20%22.mongorc.js%22]<br />
| [https://stackoverflow.com/questions/22348604/the-mongorc-js-is-not-found-but-there-is-one/22349050#22349050 This Stack Overflow thread] suggests a partial workaround using command-line switch {{ic|--norc}}.<br />
|-<br />
| [http://0ldsk00l.ca/nestopia/ Nestopia UE]<br />
| {{ic|~/.nestopia/}}<br />
| [https://github.com/0ldsk00l/nestopia/pull/292 won't fix]<br />
|<br />
|-<br />
|<br />
| {{ic|~/.netrc}}<br />
|<br />
| Like {{ic|~/.ssh}}, many programs expect this file to be here. These include projects like curl ({{ic|CURLOPT_NETRC_FILE}}), ftp ({{ic|NETRC}}), s-nail ({{ic|NETRC}}), etc. While some of them offer alternative configurable locations, many do not such as w3m, wget and lftp.<br />
|-<br />
| [[Networkmanager-openvpn]]<br />
| {{ic|~/.cert/nm-openvpn}}<br />
| [https://gitlab.gnome.org/GNOME/NetworkManager-openvpn/issues/35]<br />
|<br />
|-<br />
| [https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS NSS]<br />
| {{ic|~/.pki}}<br />
| [https://bugzilla.mozilla.org/show_bug.cgi?id=818686]<br />
|<br />
|-<br />
| [[OpenSSH]]<br />
| {{ic|~/.ssh}}<br />
| [https://bugzilla.mindrot.org/show_bug.cgi?id=2050 won't fix]<br />
| Assumed to be present by many ssh daemons and clients such as DropBear and OpenSSH.<br />
|-<br />
| [https://www.palemoon.org/ palemoon]<br />
| {{ic|~/.moonchild productions}}<br />
| [https://forum.palemoon.org/viewtopic.php?f=5&t=9639]<br />
|<br />
|-<br />
| {{AUR|parsec-bin}}<br />
| {{ic|~/.parsec}}<br />
|<br />
|<br />
|-<br />
| {{AUR|pcsxr}}<br />
| {{ic|~/.pcsxr}}<br />
|<br />
| A {{ic|-cfg}} flag exists, but can only be set relative to {{ic|~/.pcsxr}}.<br />
|-<br />
| [https://perf.wiki.kernel.org/index.php/Main_Page perf]<br />
| {{ic|~/.debug}}<br />
|<br />
| Hardcoded in [https://github.com/torvalds/linux/blob/master/tools/perf/util/config.c#L29 tools/perf/util/config.c:29].<br />
|-<br />
| [[perl]]<br />
| {{ic|~/.cpan}}<br />
|<br />
| Perl5's [https://github.com/andk/cpanpm CPAN] expects {{ic|~/.cpan}}.<br />
|-<br />
| various [[shell]]s and [[display manager]]s<br />
| {{ic|~/.profile}}<br />
|<br />
|<br />
|-<br />
| [[python]]<br />
| {{ic|~/.python_history}}<br />
|<br />
| All history from interactive sessions is saved to {{ic|~/.python_history}} by default since [https://bugs.python.org/issue5845 version 3.4], custom path can still be set the same way as in older versions (see [https://docs.python.org/3/library/readline.html?highlight=readline#example this example]).<br />
|-<br />
| {{Pkg|python-poetry}}<br />
| {{ic|~/.poetry}}<br />
| [https://github.com/python-poetry/poetry/issues/2148]<br />
| {{ic|POETRY_HOME}} can be used but it does not separate data and config.<br />
|-<br />
| [https://doc.qt.io/qt-5/qtdesigner-manual.html Qt Designer]<br />
| {{ic|~/.designer}}<br />
|<br />
|<br />
|-<br />
| [http://rednotebook.sourceforge.net/ RedNotebook]<br />
| {{ic|~/.rednotebook}}<br />
|<br />
|<br />
|-<br />
| [https://remarkableapp.github.io/linux.html Remarkable]<br />
| {{ic|~/.remarkable}}<br />
|<br />
|<br />
|-<br />
| [https://www.renpy.org/ Ren'Py]<br />
| {{ic|~/.renpy}}<br />
| [https://github.com/renpy/renpy/issues/1377#issuecomment-370118555 won't fix]<br />
|<br />
|-<br />
| [[SANE]]<br />
| {{ic|~/.sane/}}<br />
|<br />
| {{ic|scanimage}} creates a {{ic|.cal}} file there<br />
|-<br />
| {{Pkg|scribus}}<br />
| {{ic|~/.scribus}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|sdcv}}<br />
| {{ic|~/.stardict/}}<br />
| [https://github.com/Dushistov/sdcv/issues/51]<br />
| Only workaround is modifying {{ic|HOME}}<br />
|-<br />
| [http://www.seamonkey-project.org/ SeaMonkey]<br />
| {{ic|~/.mozilla/}}<br />
| [https://bugzil.la/726939]<br />
|<br />
|-<br />
| {{Pkg|simplescreenrecorder}}<br />
| {{ic|~/.ssr/}}<br />
| [https://github.com/MaartenBaert/ssr/issues/407]<br />
| Author seems against this feature.<br />
|-<br />
| [https://www.gnu.org/software/solfege/solfege.html Solfege]<br />
|<br />
{{ic|~/.solfege<br><br />
~/.solfegerc<br><br />
~/lessonfiles}}<br />
| [https://savannah.gnu.org/bugs/index.php?50251]<br />
|<br />
|-<br />
| [https://spacemacs.org/ spacemacs]<br />
|<br />
{{ic|~/.spacemacs<br><br />
~/.spacemacs.d}}<br />
| [https://github.com/syl20bnr/spacemacs/issues/3589]<br />
|<br />
|-<br />
| [https://spamassassin.apache.org/ SpamAssassin]<br />
| {{ic|~/.spamassassin}}<br />
|<br />
|<br />
|-<br />
| [[spectrwm]]<br />
| {{ic|~/.spectrwm}}<br />
|<br />
|<br />
|-<br />
| [[SQLite]]<br />
|<br />
{{ic|~/.sqlite_history<br><br />
~/.sqliterc}}<br />
| [https://www.sqlite.org/src/info/696e82f7c82d1720]<br />
| {{ic|1=$ export SQLITE_HISTORY=$XDG_DATA_HOME/sqlite_history<br><br />
$ sqlite3 -init "$XDG_CONFIG_HOME"/sqlite3/sqliterc}}<br />
|-<br />
| [[Steam]]<br />
|<br />
{{ic|~/.steam<br><br />
~/.steampath<br><br />
~/.steampid}}<br />
| [https://github.com/ValveSoftware/steam-for-linux/issues/1890]<br />
| Many game engines (Unity 3D, Unreal) follow the specification, but then individual game publishers hardcode the paths in [https://www.ctrl.blog/entry/flatpak-steamcloud-xdg Steam Auto-Cloud] causing game-saves to sync to the wrong directory.<br />
|-<br />
| [[TeamSpeak]]<br />
| {{ic|~/.ts3client}}<br />
|<br />
|<br />
|-<br />
| {{pkg|texinfo}}<br />
| {{ic|~/.infokey}}<br />
|<br />
| {{ic|$ info --init-file "$XDG_CONFIG_HOME/infokey"}}<br />
|-<br />
| [http://www.texmacs.org/ TeXmacs]<br />
| {{ic|~/.TeXmacs}}<br />
|<br />
|<br />
|-<br />
| [[Thunderbird]]<br />
| {{ic|~/.thunderbird/}}<br />
| [https://bugzil.la/735285]<br />
|<br />
|-<br />
| [https://git.archlinux.org/users/remy/texlive-localmanager.git/ tllocalmgr]<br />
| {{ic|~/.texlive}}<br />
|<br />
|<br />
|-<br />
| {{AUR|vale}}<br />
| {{ic|~/.vale.ini}}<br />
| [https://github.com/errata-ai/vale/issues/152 won't fix]<br />
| {{ic|$ vale --config "$XDG_CONFIG_HOME/vale/config.ini"}}<br />
|-<br />
| [[vim]]<br />
|<br />
{{ic|~/.vim<br><br />
~/.vimrc<br><br />
~/.viminfo}}<br />
| [https://github.com/vim/vim/issues/2034]<br />
| Since [https://github.com/vim/vim/commit/6a459902592e2a4ba68 7.3.1178] vim will search for {{ic|~/.vim/vimrc}} if {{ic|~/.vimrc}} is not found.<br />
<br />
{{ic|1=<nowiki>$ mkdir -p "$XDG_DATA_HOME"/vim/{undo,swap,backup}</nowiki>}}<br />
<br />
{{hc|"$XDG_CONFIG_HOME"/vim/vimrc|<br />
set undodir&#61;$XDG_DATA_HOME/vim/undo<br />
set directory&#61;$XDG_DATA_HOME/vim/swap<br />
set backupdir&#61;$XDG_DATA_HOME/vim/backup<br />
set viewdir&#61;$XDG_DATA_HOME/vim/view<br />
set viminfo+&#61;'1000,n$XDG_DATA_HOME/vim/viminfo<br />
set runtimepath&#61;$XDG_CONFIG_HOME/vim,$VIMRUNTIME,$XDG_CONFIG_HOME/vim/after<br />
}}<br />
<br />
{{hc|~/.profile|<br />
export VIMINIT&#61;":source $XDG_CONFIG_HOME"/vim/vimrc<br />
}}<br />
<br />
* https://tlvince.com/vim-respect-xdg<br />
|-<br />
| [http://www.vimperator.org/ vimperator]<br />
| {{ic|~/.vimperatorrc}}<br />
| [http://www.mozdev.org/pipermail/vimperator/2009-October/004848.html]<br />
| {{ic|1=$ export VIMPERATOR_INIT=":source $XDG_CONFIG_HOME/vimperator/vimperatorrc"}}<br />
<br />
{{ic|1=$ export VIMPERATOR_RUNTIME="$XDG_CONFIG_HOME"/vimperator}}<br />
|-<br />
| {{Pkg|w3m}}<br />
| {{ic|~/.w3m}}<br />
| [https://sourceforge.net/p/w3m/feature-requests/31/]<br />
|<br />
|-<br />
| [https://w1.fi/ wpa_cli]<br />
| {{ic|~/.wpa_cli_history}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|xdg-utils}}<br />
| {{ic|~/.gnome}}<br />
| [https://bugs.freedesktop.org/show_bug.cgi?id=90775]<br />
| For some reason the script {{ic|xdg-desktop-menu}} hard-codes {{ic|gnome_user_dir&#61;"$HOME/.gnome/apps"}}. This is used by [[chromium]] among others.<br />
|-<br />
| [https://opensource.conformal.com/wiki/xombrero xombrero]{{Dead link|2020|02|26}}<br />
| {{ic|~/.xombrero}}<br />
| [https://github.com/conformal/xombrero/issues/74]{{Dead link|2020|02|26}}<br />
|<br />
|-<br />
| {{Pkg|xournalpp}}<br />
| {{ic|~/.xournalpp}}<br />
| [https://github.com/xournalpp/xournalpp/issues/1101]<br />
|<br />
|-<br />
| {{Pkg|xpdf}}<br />
| {{ic|~/.xpdfrc}}<br />
| <br />
|<br />
|-<br />
| [https://yardoc.org YARD]<br />
| {{ic|~/.yard}}<br />
| [https://github.com/lsegal/yard/issues/1230]<br />
| Would accept Pull Request if anyone want to implement it.<br />
|-<br />
| [https://nmap.org/zenmap/ zenmap] {{Pkg|nmap}}<br />
| {{ic|~/.zenmap}}<br />
| [http://seclists.org/nmap-dev/2012/q2/163] [https://github.com/nmap/nmap/issues/590]<br />
|<br />
|-<br />
| [[zsh]]<br />
|<br />
{{ic|~/.zshrc<br><br />
~/.zprofile<br><br />
~/.zshenv<br><br />
~/.zlogin<br><br />
~/.zlogout<br><br />
~/.histfile<br><br />
~/.zcompdump}}<br />
| [http://www.zsh.org/mla/workers/2013/msg00692.html]<br />
| Consider exporting {{ic|1=ZDOTDIR=$HOME/.config/zsh}} in {{ic|~/.zshenv}} (this is hardcoded due to the bootstrap problem). You could also add this to {{ic|/etc/zsh/zshenv}} and avoid the need for any dotfiles in your {{ic|HOME}}. Doing this however requires root privilege which may not be viable and is system-wide.<br />
<br />
{{ic|1=$ export HISTFILE="$XDG_DATA_HOME"/zsh/history}}<br />
<br />
{{ic| $ compinit -d $XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION}} [https://unix.stackexchange.com/questions/391641/separate-path-for-zcompdump-files] /!\ The folder needs to exist<br />
<br />
|}<br />
<br />
== Libraries ==<br />
<br />
; C<br />
: [https://github.com/Cloudef/chck/tree/master/chck/xdg C99: Cloudef's simple implementation].<br />
<br />
; JVM: Java, Kotlin, Clojure, Scala, ...<br />
: [https://github.com/soc/directories-jvm directories-jvm]<br />
<br />
; Go<br />
: [https://github.com/ProtonMail/go-appdir go-appdir]<br />
<br />
; Haskell<br />
: Officially in [https://hackage.haskell.org/package/directory directory] since 1.2.3.0 [https://github.com/haskell/directory/commit/ab9d0810ce ab9d0810ce].<br />
: [https://hackage.haskell.org/package/xdg-basedir xdg-basedir]<br />
<br />
; Perl<br />
: [http://search.cpan.org/dist/File-BaseDir/lib/File/BaseDir.pm File-BaseDir]<br />
: [https://github.com/Aerdan/perl-file-xdg perl-file-xdg]{{Dead link|2020|02|26}}<br />
<br />
; Ruby<br />
: [https://github.com/rubyworks/xdg rubyworks/xdg]<br />
<br />
; Rust<br />
: [https://github.com/soc/directories-rs directories-rs]<br />
: [https://github.com/whitequark/rust-xdg rust-xdg]<br />
<br />
; Python<br />
: [https://freedesktop.org/wiki/Software/pyxdg/ pyxdg]<br />
<br />
; Vala<br />
: Builtin support via [http://valadoc.org/#!api=glib-2.0/GLib.Environment GLib.Environment].<br />
: See {{ic|get_user_cache_dir}}, {{ic|get_user_data_dir}}, {{ic|get_user_config_dir}}, etc.<br />
<br />
==See also==<br />
<br />
* [https://wiki.gnome.org/Initiatives/GnomeGoals/XDGConfigFolders GNOME Goal: XDG Base Directory Specification Usage]<br />
* [https://web.archive.org/web/20180827160401/plus.google.com/+RobPikeTheHuman/posts/R58WgWwN9jp Rob Pike: "Dotfiles" being hidden is a UNIXv2 mistake].<br />
* {{man|1|systemd-path}}<br />
* {{man|7|file-hierarchy}}<br />
* [https://github.com/grawity/dotfiles/blob/master/.dotfiles.notes Grawity's notes on dotfiles].<br />
* [https://github.com/grawity/dotfiles/blob/master/.environ.notes Grawity's notes on environment variables].<br />
* [https://ploum.net/207-modify-your-application-to-use-xdg-folders/ ploum.net: Modify Your Application to use XDG Folders].<br />
* The [https://pcgamingwiki.com/wiki/Home PCGamingWiki] attempts to document whether or not Linux PC games follow the XDG Base Directory Specification.</div>Simon04https://wiki.archlinux.org/index.php?title=XDG_Base_Directory&diff=606336XDG Base Directory2020-04-16T19:58:09Z<p>Simon04: /* Supported */ +josm</p>
<hr />
<div>[[Category:Freedesktop.org]]<br />
[[Category:Configuration files]]<br />
[[Category:Development]]<br />
[[ja:XDG Base Directory サポート]]<br />
[[pt:XDG Base Directory]]<br />
{{Related articles start}}<br />
{{Related|dotfiles}}<br />
{{Related|XDG user directories}}<br />
{{Related articles end}}<br />
<br />
This article summarizes the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory specification] in [[#Specification]] and tracks software support in [[#Support]].<br />
<br />
== Specification ==<br />
<br />
Please read the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html full specification]. This section will attempt to break down the essence of what it tries to achieve.<br />
<br />
Only {{ic|XDG_RUNTIME_DIR}} is set by default through [https://www.freedesktop.org/software/systemd/man/pam_systemd.html pam_systemd]. It is up to the user to explicitly [[define]] the other variables according to the specification.<br />
<br />
=== User directories ===<br />
<br />
* {{ic|XDG_CONFIG_HOME}}<br />
** Where user-specific configurations should be written (analogous to {{ic|/etc}}).<br />
** Should default to {{ic|$HOME/.config}}.<br />
<br />
* {{ic|XDG_CACHE_HOME}}<br />
** Where user-specific non-essential (cached) data should be written (analogous to {{ic|/var/cache}}).<br />
** Should default to {{ic|$HOME/.cache}}.<br />
<br />
* {{ic|XDG_DATA_HOME}}<br />
** Where user-specific data files should be written (analogous to {{ic|/usr/share}}).<br />
** Should default to {{ic|$HOME/.local/share}}.<br />
<br />
* {{ic|XDG_RUNTIME_DIR}}<br />
** Used for non-essential, user-specific data files such as sockets, named pipes, etc.<br />
** Not required to have a default value; warnings should be issued if not set or equivalents provided.<br />
** Must be owned by the user with an access mode of {{ic|0700}}.<br />
** Filesystem fully featured by standards of OS.<br />
** Must be on the local filesystem.<br />
** May be subject to periodic cleanup.<br />
** Modified every 6 hours or set sticky bit if persistence is desired.<br />
** Can only exist for the duration of the user's login.<br />
** Should not store large files as it may be mounted as a tmpfs.<br />
<br />
=== System directories ===<br />
<br />
* {{ic|XDG_DATA_DIRS}}<br />
** List of directories separated by {{ic|:}} (analogous to {{ic|PATH}}).<br />
** Should default to {{ic|/usr/local/share:/usr/share}}.<br />
<br />
* {{ic|XDG_CONFIG_DIRS}}<br />
** List of directories separated by {{ic|:}} (analogous to {{ic|PATH}}).<br />
** Should default to {{ic|/etc/xdg}}.<br />
<br />
== Support ==<br />
<br />
This section exists to catalog the growing set of software using the [https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html XDG Base Directory Specification] introduced in 2003. This is here to demonstrate the viability of this specification by listing commonly found dotfiles and their support status. For those not currently supporting the Base Directory Specification, workarounds will be demonstrated to emulate it instead.<br />
<br />
The workarounds will be limited to anything not involving patching the source, executing code stored in [[environment variables]] or compile-time options. The rationale for this is that configurations should be portable across systems and having compile-time options prevent that.<br />
<br />
Hopefully this will provide a source of information about exactly what certain kinds of dotfiles are and where they come from.<br />
<br />
=== Contributing ===<br />
<br />
When contributing make sure to use the correct section.<br />
<br />
Nothing should require code evaluation (such as [[vim]] and {{ic|VIMINIT}}), patches or compile-time options to gain support and anything which does must be deemed hardcoded. Additionally if the process is too error prone or difficult, such as [https://www.haskell.org/cabal/ Haskell's cabal] or Eclipse, they should also be considered as hardcoded.<br />
<br />
* The first column should be either a link to an internal article, a [[Template:Pkg]] or a [[Template:AUR]].<br />
* The second column is for any legacy files and directories the project had (one per line), this is done so people can find them even if they are no longer read.<br />
* In the third, try to find the commit or version a project switched to XDG Base Directory or any open discussions and include them in the next two columns (two per line).<br />
* The last column should include any appropriate workarounds or solutions. Please verify that your solution is correct and functional.<br />
<br />
=== Supported ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Supported Since<br />
! Discussion<br />
! Notes<br />
|-<br />
| {{AUR|aerc-git}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|antimicro}}{{Broken package link|package not found}}<br />
| {{ic|~/.antimicro}}<br />
| [https://github.com/Antimicro/antimicro/commit/edba864 edba864]<br />
| [https://github.com/Antimicro/antimicro/issues/5]<br />
|<br />
|-<br />
| [[aria2]]<br />
| {{ic|~/.aria2}}<br />
| [https://github.com/tatsuhiro-t/aria2/commit/8bc1d37 8bc1d37]<br />
| [https://github.com/tatsuhiro-t/aria2/issues/27]<br />
|<br />
|-<br />
| {{Pkg|asunder}}<br />
|<br />
{{ic|~/.asunder<br><br />
~/.asunder_album_artist<br><br />
~/.asunder_album_genre<br><br />
~/.asunder_album_title}}<br />
| [https://littlesvr.ca/bugs/show_bug.cgi?id=31 2.9.0]<br />
| [https://littlesvr.ca/bugs/show_bug.cgi?id=52]<br />
| Uses {{ic|XDG_CONFIG_HOME/asunder/asunder}} for {{ic|~/.asunder}} and {{ic|XDG_CACHE_HOME/asunder/asunder_album_...}} for the other 3 files. Legacy paths are not removed after migration, they have to be deleted manually.<br />
|-<br />
| {{Pkg|binwalk}}<br />
| {{ic|~/.binwalk}}<br />
| [https://github.com/ReFirmLabs/binwalk/commit/2051757 2051757]<br />
| [https://github.com/ReFirmLabs/binwalk/issues/216]<br />
| {{ic|$XDG_CONFIG_HOME/binwalk}}<br />
|-<br />
| [[Blender]]<br />
| {{ic|~/.blender}}<br />
| [http://git.blender.org/gitweb/gitweb.cgi/blender.git/commit/4293f47 4293f47]<br />
| [https://developer.blender.org/T28943]<br />
|<br />
|-<br />
| {{Pkg|calcurse}}<br />
| {{ic|~/.calcurse}}<br />
| [https://github.com/lfos/calcurse/commit/04162d 04162d]<br />
| [https://github.com/lfos/calcurse/pull/254] [https://github.com/lfos/calcurse/issues/252]<br />
| {{ic|XDG_CONFIG_HOME/calcurse}}<br />
<br />
{{ic|XDG_DATA_HOME/calcurse}}<br />
<br />
If the legacy path {{ic|~/.calcurse}} is present, it will take precedence.<br />
|-<br />
| {{Pkg|calibre}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|citra-git}}<br />
| {{ic|~/.citra-emu}}<br />
| [https://github.com/citra-emu/citra/commit/f7c3193 f7c3193]<br />
| [https://github.com/citra-emu/citra/pull/575]<br />
|<br />
|-<br />
| [[Composer]]<br />
| {{ic|~/.composer}}<br />
| [https://github.com/composer/composer/releases/tag/1.0.0-beta1 1.0.0-beta1]<br />
| [https://github.com/composer/composer/pull/1407]<br />
|<br />
|-<br />
| {{Pkg|d-feet}}<br />
| {{ic|~/.d-feet}}<br />
| [https://gitlab.gnome.org/GNOME/d-feet/commit/7f6104b 7f6104b]<br />
|<br />
|<br />
|-<br />
| {{Pkg|dconf}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[Dolphin emulator]]<br />
| {{ic|~/.dolphin-emu}}<br />
| [https://github.com/dolphin-emu/dolphin/commit/a498c68 a498c68]<br />
| [https://github.com/dolphin-emu/dolphin/pull/2304]<br />
|<br />
|-<br />
| {{AUR|dr14_tmeter}}<br />
| <br />
| [https://github.com/simon-r/dr14_t.meter/commit/7e777ca 7e777ca]<br />
| [https://github.com/simon-r/dr14_t.meter/pull/30]<br />
| {{ic|XDG_CONFIG_HOME/dr14tmeter/}}<br />
|-<br />
| {{Pkg|dunst}}<br />
|<br />
| [https://github.com/dunst-project/dunst/commit/78b6e2b 78b6e2b]<br />
| [https://github.com/dunst-project/dunst/issues/22]<br />
|<br />
|-<br />
| [[dwb]]<br />
|<br />
|<br />
|<br />
|<br />
<br />
|-<br />
| [[fish]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[fontconfig]]<br />
|<br />
{{ic|~/.fontconfig<br><br />
~/.fonts}}<br />
| [https://cgit.freedesktop.org/fontconfig/commit/?id=8c255fb 8c255fb]<br />
|<br />
| Use {{ic|"$XDG_DATA_HOME"/fonts}} to store fonts instead.<br />
|-<br />
| {{Pkg|fontforge}}<br />
|<br />
{{ic|~/.FontForge<br><br />
~/.PfaEdit}}<br />
| [https://github.com/fontforge/fontforge/commit/e4c2cc7 e4c2cc7]<br />
|<br />
[https://github.com/fontforge/fontforge/issues/847]<br />
[https://github.com/fontforge/fontforge/issues/991]<br />
|<br />
|-<br />
| {{Pkg|freerdp}}<br />
| {{ic|~/.freerdp}}<br />
| [https://github.com/FreeRDP/FreeRDP/commit/edf6e72 edf6e72]<br />
|<br />
|<br />
|-<br />
| [[Gajim]]<br />
| {{ic|~/.gajim}}<br />
| [https://dev.gajim.org/gajim/gajim/commit/3e777ea 3e777ea]<br />
| [https://dev.gajim.org/gajim/gajim/issues/2149]<br />
|<br />
|-<br />
| {{AUR|gconf}}<br />
| {{ic|~/.gconf}}<br />
| [https://gitlab.gnome.org/Archive/gconf/commit/fc28caa fc28caa]<br />
| [https://bugzilla.gnome.org/show_bug.cgi?id=674803]<br />
|<br />
|-<br />
| [[GIMP]]<br />
|<br />
{{ic|~/.gimp-x.y<br><br />
~/.thumbnails}}<br />
|<br />
[https://gitlab.gnome.org/GNOME/gimp/commit/60e0cfe 60e0cfe]<br />
[https://gitlab.gnome.org/GNOME/gimp/commit/483505f 483505f]<br />
|<br />
[https://bugzilla.gnome.org/show_bug.cgi?id=166643]<br />
[https://bugzilla.gnome.org/show_bug.cgi?id=646644]<br />
|<br />
|-<br />
| [[Git]]<br />
| {{ic|~/.gitconfig}}<br />
| [https://github.com/git/git/commit/0d94427 0d94427]<br />
|<br />
|<br />
|-<br />
| [https://github.com/google/gops gops]<br />
| <br />
| [https://github.com/google/gops/commit/71c4255 71c4255]<br />
| <br />
|<br />
|-<br />
| [[GStreamer]]<br />
| {{ic|~/.gstreamer-0.10}}<br />
| [https://cgit.freedesktop.org/gstreamer/gstreamer/commit/?id=4e36f93 4e36f93]<br />
| [https://bugzilla.gnome.org/show_bug.cgi?id=518597]<br />
|<br />
|-<br />
| [[GTK]] 3<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|htop}}<br />
| {{ic|~/.htoprc}}<br />
| [https://github.com/hishamhm/htop/commit/93233a6 93233a6]<br />
|<br />
|<br />
|-<br />
| [[i3]]<br />
| {{ic|~/.i3}}<br />
| [http://code.stapelberg.de/git/i3/commit/?id=7c130fb 7c130fb]<br />
|<br />
|<br />
|-<br />
| {{Pkg|i3status}}<br />
| {{ic|~/.i3status.conf}}<br />
| [http://code.stapelberg.de/git/i3status/commit/?id=c3f7fc4 c3f7fc4]<br />
|<br />
|<br />
|-<br />
| {{Pkg|imagemagick}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[Inkscape]]<br />
| {{ic|~/.inkscape}}<br />
| [http://wiki.inkscape.org/wiki/index.php/Release_notes/0.47#Preferences 0.47]<br />
| [https://bugs.launchpad.net/inkscape/+bug/199720]<br />
|<br />
|-<br />
| [https://iwd.wiki.kernel.org/ iwd] / iwctl<br />
| {{ic|~/.iwctl_history}}<br />
| [https://git.kernel.org/pub/scm/network/wireless/iwd.git/commit/?id=d3e00d7f d3e00d7f]<br />
|<br />
|<br />
|-<br />
| {{Pkg|intellij-idea-community-edition}}<br />
| {{ic|~/.IntelliJIdea*}}<br />
| [https://confluence.jetbrains.com/display/IDEADEV/IntelliJ%2BIDEA%2B2020.1%2B%28201.6668.121%2Bbuild%29%2BRelease%2BNotes 2020.1]<br />
| [https://youtrack.jetbrains.com/issue/IDEA-22407]<br />
|<br />
|-<br />
| {{Pkg|josm}}<br />
| {{ic|~/.josm}}<br />
| [https://josm.openstreetmap.de/changeset/11162/josm 11162]<br />
| [https://josm.openstreetmap.de/ticket/6664]<br />
|<br />
|-<br />
| [[Kakoune]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| latexmk (in {{Pkg|texlive-core}})<br />
| {{ic|~/.latexmkrc}}<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|lftp}}<br />
| {{ic|~/.lftp}}<br />
| [https://github.com/lavv17/lftp/commit/21dc400 21dc400]<br />
| [https://www.mail-archive.com/lftp@uniyar.ac.ru/msg04301.html]<br />
|<br />
|-<br />
| {{AUR|lgogdownloader}}<br />
| {{ic|~/.gogdownloader}}<br />
| [https://github.com/Sude-/lgogdownloader/commit/d430af6 d430af6]<br />
| [https://github.com/Sude-/lgogdownloader/issues/4]<br />
|<br />
|-<br />
| [[LibreOffice]]<br />
|<br />
|<br />
[https://cgit.freedesktop.org/libreoffice/ure/commit/?id=a6f56f7 a6f56f7]<br />
[https://cgit.freedesktop.org/libreoffice/bootstrap/commit/?id=25bd2ee 25bd2ee]<br />
| [https://bugs.documentfoundation.org/show_bug.cgi?id=32263]<br />
|<br />
|-<br />
| [[Streamlink]]<br />
| {{ic|~/.livestreamerrc}}<br />
| [https://github.com/chrippa/livestreamer/commit/ea80591 ea80591]<br />
| [https://github.com/chrippa/livestreamer/pull/106]<br />
|<br />
|-<br />
| [[llpp]]<br />
|<br />
| [http://repo.or.cz/w/llpp.git/commit/3ab86f0 3ab86f0]<br />
|<br />
| Currently ''llpp'' places the configuration directly under {{ic|XDG_CONFIG_HOME}} instead of creating a directory.<br />
|-<br />
| [[mc]]<br />
| {{ic|~/.mc}}<br />
|<br />
[https://github.com/MidnightCommander/mc/commit/1b99570 1b99570]<br />
[https://github.com/MidnightCommander/mc/commit/0b71156 0b71156]<br />
[https://github.com/MidnightCommander/mc/commit/ce401d7 ce401d7]<br />
| [https://www.midnight-commander.org/ticket/1851]<br />
|<br />
|-<br />
| [[Mercurial]]<br />
| {{ic|~/.hgrc}}<br />
|<br />
[https://www.mercurial-scm.org/repo/hg/rev/3540200 3540200]<br />
[https://www.mercurial-scm.org/wiki/Release4.2 4.2]<br />
|<br />
| {{ic|XDG_CONFIG_HOME/hg/hgrc}}.<br />
|-<br />
| [[msmtp]]<br />
| {{ic|~/.msmtprc}}<br />
|<br />
[https://github.com/marlam/msmtp-mirror/commit/af2f409 af2f409]<br />
v1.6.7+<br />
|<br />
| {{ic| XDG_CONFIG_HOME/msmtp/config}}.<br />
|-<br />
| {{Pkg|mesa}}<br />
|<br />
| [https://cgit.freedesktop.org/mesa/mesa/commit/?id=87ab26b 87ab26b]<br />
|<br />
| {{ic|XDG_CACHE_HOME/mesa}}<br />
|-<br />
| {{Pkg|milkytracker}}<br />
| {{ic|~/.milkytracker_config}}<br />
| [https://github.com/Deltafire/MilkyTracker/commit/eb487c5 eb487c5]<br />
| [https://github.com/Deltafire/MilkyTracker/issues/12]<br />
|<br />
|-<br />
| [[mpd]]<br />
| {{ic|~/.mpdconf}}<br />
| [https://github.com/MusicPlayerDaemon/MPD/commit/87b7328 87b7328]<br />
|<br />
|<br />
|-<br />
| [[mpv]]<br />
| {{ic|~/.mpv}}<br />
| [https://github.com/mpv-player/mpv/commit/cb250d4 cb250d4]<br />
| [https://github.com/mpv-player/mpv/pull/864]<br />
|<br />
|-<br />
| [[mutt]]<br />
| {{ic|~/.mutt}}<br />
| [https://gitlab.com/muttmua/mutt/commit/b17cd67 b17cd67]<br />
| [https://gitlab.com/muttmua/trac-tickets/raw/master/tickets/closed/3207-Conform_to_XDG_Base_Directory_Specification.txt]<br />
|<br />
|-<br />
| {{Pkg|mypaint}}<br />
| {{ic|~/.mypaint}}<br />
| [https://github.com/mypaint/mypaint/commit/cf723b7 cf723b7]<br />
|<br />
|<br />
|-<br />
| [[nano]]<br />
|<br />
{{ic|~/.nano/<br><br />
~/.nanorc}}<br />
| [http://git.savannah.gnu.org/cgit/nano.git/commit/?id=c16e79b c16e79b]<br />
| [https://savannah.gnu.org/patch/?8523]<br />
|<br />
|-<br />
| [[ncmpcpp]]<br />
| {{ic|~/.ncmpcpp}}<br />
|<br />
[https://github.com/arybczak/ncmpcpp/commit/38d9f81 38d9f81]<br />
[https://github.com/arybczak/ncmpcpp/commit/27cd86e 27cd86e]<br />
|<br />
[https://github.com/arybczak/ncmpcpp/issues/79]<br />
[https://github.com/arybczak/ncmpcpp/issues/110]<br />
| {{ic|ncmpcpp_directory}} should be set to avoid an {{ic|error.log}} file in {{ic|~/.ncmpcpp}}.<br />
|-<br />
| [[Neovim]]<br />
|<br />
{{ic|~/.nvim<br><br />
~/.nvimlog<br><br />
~/.nviminfo}}<br />
| [https://github.com/neovim/neovim/commit/1ca5646 1ca5646]<br />
|<br />
[https://github.com/neovim/neovim/issues/78]<br />
[https://github.com/neovim/neovim/pull/3198]<br />
|<br />
|-<br />
| [[newsbeuter]]<br />
| {{ic|~/.newsbeuter}}<br />
| [https://github.com/akrennmair/newsbeuter/commit/3c57824 3c57824]<br />
| [https://github.com/akrennmair/newsbeuter/pull/39]<br />
| It is required to create both directories [http://newsbeuter.org/doc/newsbeuter.html#_xdg_base_directory_support]:<br />
<br />
{{ic|1=$ mkdir -p "$XDG_DATA_HOME"/newsbeuter "$XDG_CONFIG_HOME"/newsbeuter}}<br />
|-<br />
| [https://github.com/nodejs/node-gyp node-gyp]<br />
| {{ic|~/.node-gyp}}<br />
| [https://github.com/nodejs/node-gyp/commit/2b5ce52a 2b5ce52a]<br />
| [https://github.com/nodejs/node-gyp/pull/1570]<br />
| Only available on master as of 2018-12-04.<br />
|-<br />
| {{AUR|np2kai-git}}<br />
|<br />
{{ic|~/.config/np2kai<br><br />
~/.config/xnp2kai}}<br />
| [https://github.com/AZO234/NP2kai/commit/56a1cc2 56a1cc2]<br />
| [https://github.com/AZO234/NP2kai/pull/50]<br />
|<br />
|-<br />
| {{AUR|nteract-bin}}<br />
|<br />
| [https://github.com/nteract/nteract/commit/4593e72 4593e72]<br />
| [https://github.com/nteract/nteract/issues/180] [https://github.com/nteract/nteract/pull/3870]<br />
| [https://github.com/nteract/nteract/issues/4517 does not recognize workarounds for ipython/jupyter]<br />
|-<br />
| [[OfflineIMAP]]<br />
| {{ic|~/.offlineimaprc}}<br />
| [https://github.com/OfflineIMAP/offlineimap/commit/5150de5 5150de5]<br />
| [https://github.com/OfflineIMAP/offlineimap/issues/32]<br />
|<br />
|-<br />
| {{AUR|opentyrian}}<br />
| {{ic|~/.opentyrian}}<br />
| [https://bitbucket.org/opentyrian/opentyrian/commits/8d45ff2 8d45ff2]<br />
| [https://web.archive.org/web/20140815181350/http://code.google.com/p/opentyrian/issues/detail?id=125]<br />
|<br />
|-<br />
| {{Pkg|pandoc}}<br />
| {{ic|~/.pandoc/}}<br />
| [https://github.com/jgm/pandoc/commit/0bed0ab5a308f5e72a01fa9bee76488556288862 0bed0ab]<br />
| [https://github.com/jgm/pandoc/issues/3582]<br />
|<br />
|-<br />
| {{Pkg|pcsx2}}<br />
| {{ic|~/.pcsx2}}<br />
|<br />
[https://github.com/PCSX2/pcsx2/commit/87f1e8f 87f1e8f]<br />
[https://github.com/PCSX2/pcsx2/commit/a9020c6 a9020c6]<br />
[https://github.com/PCSX2/pcsx2/commit/3b22f0f 3b22f0f]<br />
[https://github.com/PCSX2/pcsx2/commit/0a012ae 0a012ae]<br />
| [https://github.com/PCSX2/pcsx2/issues/352] [https://github.com/PCSX2/pcsx2/issues/381]<br />
|<br />
|-<br />
| [http://pryrepl.org/ Pry]<br />
| {{ic|~/.pryrc<br>~/.pry_history}}<br />
|<br />
[https://github.com/pry/pry/commit/a0be0cc7b2070edff61c0c7f10fa37fce9b730bd a0be0cc7]<br />
[https://github.com/pry/pry/commit/15e1fc929ed84c161abc5afc9be73488a41df397 15e1fc92]<br />
[https://github.com/pry/pry/commit/e9d1be0e17b294318dbb2f70f74a50486cfa044c e9d1be0e]<br />
| [https://github.com/pry/pry/issues/1316]<br />
|<br />
|-<br />
| {{Pkg|python-pip}}<br />
| {{ic|~/.pip}}<br />
| [https://github.com/pypa/pip/blob/548a9136525815dff41acd845c558a0b36eb1c5f/NEWS.rst#60-2014-12-22 6.0]<br />
| [https://github.com/pypa/pip/issues/1733]<br />
|<br />
|-<br />
| {{AUR|powershell}}<br />
|<br />
| [https://docs.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-core-60#filesystem 6.0]<br />
|<br />
|<br />
|-<br />
| {{Pkg|ppsspp}}<br />
| {{ic|~/.ppsspp}}<br />
| [https://github.com/hrydgard/ppsspp/commit/132fe47 132fe47]<br />
| [https://github.com/hrydgard/ppsspp/issues/4623]<br />
|<br />
|-<br />
| {{Pkg|procps-ng}}<br />
| {{ic|~/.toprc}}<br />
| [https://gitlab.com/procps-ng/procps/commit/af53e17 af53e17]<br />
|<br />
[https://gitlab.com/procps-ng/procps/merge_requests/38]<br />
[https://bugzilla.redhat.com/show_bug.cgi?id=1155265]<br />
|<br />
|-<br />
| {{AUR|orbment-git}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[pacman]]<br />
| {{ic|~/.makepkg.conf}}<br />
| [https://projects.archlinux.org/pacman.git/commit/?id=80eca94 80eca94]<br />
| [https://mailman.archlinux.org/pipermail/pacman-dev/2014-July/019178.html]<br />
|<br />
|-<br />
| {{AUR|panda3d}}<br />
| {{ic|~/.panda3d}}<br />
| [https://github.com/panda3d/panda3d/commit/2b537d2 2b537d2]<br />
|<br />
|<br />
|-<br />
| {{AUR|poezio}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[PulseAudio]]<br />
|<br />
{{ic|~/.pulse<br><br />
~/.pulse-cookie}}<br />
|<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=59a8618 59a8618]<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=87ae830 87ae830]<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=9ab510a 9ab510a]<br />
[https://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=4c195bc 4c195bc]<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=845607]<br />
|<br />
|-<br />
| {{AUR|pyroom}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|quodlibet}}<br />
| {{ic|~/.quodlibet}}<br />
| 3.10.0<br />
| [https://github.com/quodlibet/quodlibet/issues/138]<br />
|<br />
|-<br />
| [[qutebrowser]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[qtile]]<br />
|<br />
|<br />
[https://github.com/qtile/qtile/commit/fd8686e fd8686e]<br />
[https://github.com/qtile/qtile/commit/66d704b 66d704b]<br />
[https://github.com/qtile/qtile/commit/51cff01 51cff01]<br />
| [https://github.com/qtile/qtile/pull/835]<br />
| Some optional bar widgets can create files and directories in non-compliant paths, but most often these are still configurable.<br />
|-<br />
| {{Pkg|rclone}}<br />
| {{ic|~/.rclone.conf}}<br />
| [https://github.com/ncw/rclone/commit/9d36258 9d36258]<br />
| [https://github.com/ncw/rclone/issues/868]<br />
|<br />
|-<br />
| {{Pkg|retroarch}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{AUR|rr}}<br />
| {{ic|~/.rr}}<br />
| [https://github.com/mozilla/rr/commit/02e7d41 02e7d41]<br />
| [https://github.com/mozilla/rr/issues/1455]<br />
|<br />
|-<br />
| [https://rspec.info RSpec]<br />
| {{ic|~/.rspec}}<br />
| [https://github.com/rspec/rspec-core/commit/5e395e2016f1da19475e6db2817eb26dae828c4c 5e395e2]<br />
| [https://github.com/rspec/rspec-core/issues/1773]<br />
|<br />
|-<br />
| [[rTorrent]]<br />
| {{ic|~/.rtorrent.rc}}<br />
| [https://github.com/rakshasa/rtorrent/commit/6a8d332 6a8d332]<br />
|<br />
|<br />
|-<br />
| [https://www.rubocop.org RuboCop]<br />
| {{ic|~/.rubocop.yml}}<br />
| [https://github.com/rubocop-hq/rubocop/commit/6fe5956c177ca369cfaa70bdf748b70020a56bf4 6fe5956]<br />
| [https://github.com/rubocop-hq/rubocop/issues/6662]<br />
|<br />
|-<br />
| {{AUR|skypeforlinux-stable-bin}}<br />
| {{ic|~/.Skype}}<br />
| 8.0<br />
|<br />
|<br />
|-<br />
| {{Pkg|snes9x}}<br />
| {{ic|~/.snes9x}}<br />
| [https://github.com/snes9xgit/snes9x/commit/93b5f11 93b5f11]<br />
| [https://github.com/snes9xgit/snes9x/issues/194]<br />
| By default, the configuration file is left blank with intention that the user will fill it at their will (through the gui or manually).<br />
|-<br />
| {{AUR|sublime-text-dev}}<br />
|<br />
|<br />
|<br />
| Cache is placed in {{ic|$XDG_CONFIG_HOME/sublime-text-3/Cache}} instead of expected {{ic|$XDG_CACHE_HOME/sublime-text-3}}.<br />
|-<br />
| [[surfraw]]<br />
|<br />
{{ic|~/.surfraw.conf<br><br />
~/.surfraw.bookmarks}}<br />
|<br />
[https://gitlab.com/surfraw/Surfraw/commit/3e4591d 3e4591d]<br />
[https://gitlab.com/surfraw/Surfraw/commit/bd8c427 bd8c427]<br />
[https://gitlab.com/surfraw/Surfraw/commit/f57fc71 f57fc71]<br />
|<br />
|<br />
|-<br />
| [[sway]]<br />
| {{ic|~/.sway/config}}<br />
| [https://github.com/SirCmpwn/sway/commit/614393c 614393c]<br />
| [https://github.com/SirCmpwn/sway/issues/5]<br />
|<br />
|-<br />
| [[systemd]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|teeworlds}}<br />
| {{ic|~/.teeworlds}}<br />
| [https://github.com/teeworlds/teeworlds/commit/d2e39d2f50684151490da446156622e69dd84a48]<br />
|<br />
| <br />
|-<br />
| [[termite]]<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| {{Pkg|tig}}<br />
| {{ic|~/.tigrc}}, {{ic|~/.tig_history}}<br />
| [https://github.com/jonas/tig/blob/master/NEWS.adoc#tig-22 2.2]<br />
| [https://github.com/jonas/tig/issues/513]<br />
| {{ic|~/.local/share/tig}} directory must exist, writes to {{ic|~/.tig_history}} otherwise.<br />
|-<br />
| {{AUR|tmuxinator}}<br />
| {{ic|~/.tmuxinator}}<br />
| [https://github.com/tmuxinator/tmuxinator/pull/511/commits/2636923 2636923]<br />
| [https://github.com/tmuxinator/tmuxinator/pull/511]<br />
|<br />
|-<br />
| [[Transmission]]<br />
| {{ic|~/.transmission}}<br />
| [https://github.com/transmission/transmission/commit/b71a298 b71a298]<br />
|<br />
|<br />
|-<br />
| {{Pkg|util-linux}}<br />
|<br />
| [https://git.kernel.org/pub/scm/utils/util-linux/util-linux.git/commit/?id=570b321 570b321]<br />
|<br />
|<br />
|-<br />
| [[Uzbl]]<br />
|<br />
| [https://github.com/uzbl/uzbl/commit/c6fd63a c6fd63a]<br />
| [https://github.com/uzbl/uzbl/pull/150]<br />
|<br />
|-<br />
| {{Pkg|vimb}}<br />
|<br />
|<br />
|<br />
|<br />
|-<br />
| [[VirtualBox]]<br />
| {{ic|~/.VirtualBox}}<br />
| [https://www.virtualbox.org/ticket/5099?action=diff&version=7 4.3]<br />
| [https://www.virtualbox.org/ticket/5099]<br />
|<br />
|-<br />
| {{Pkg|vis}}<br />
| {{ic|~/.vis}}<br />
|<br />
[https://github.com/martanne/vis/commit/68a25c7 68a25c7]<br />
[https://github.com/martanne/vis/commit/d138908 d138908]<br />
| [https://github.com/martanne/vis/pull/303]<br />
|<br />
|-<br />
| [[VLC]]<br />
| {{ic|~/.vlcrc}}<br />
| [http://git.videolan.org/?p=vlc.git;a=commit;h=16f32e1 16f32e1]<br />
| [https://trac.videolan.org/vlc/ticket/1267]<br />
|<br />
|-<br />
| {{Pkg|warsow}}<br />
| {{ic|~/.warsow-2.x}}<br />
| [https://github.com/Qfusion/qfusion/commit/98ece3f 98ece3f]<br />
| [https://github.com/Qfusion/qfusion/issues/298]<br />
|<br />
|-<br />
| [[Wireshark]]<br />
| {{ic|~/.wireshark}}<br />
| [https://code.wireshark.org/review/gitweb?p=wireshark.git;a=commit;h=b0b53fa b0b53fa]<br />
|<br />
|<br />
|-<br />
| {{AUR|xsettingsd-git}}<br />
| {{ic|~/.xsettingsd}}<br />
| [https://github.com/derat/xsettingsd/commit/b4999f5 b4999f5]<br />
|<br />
|<br />
|-<br />
| [[xmonad]]<br />
| {{ic|~/.xmonad}}<br />
| [https://github.com/xmonad/xmonad/commit/40fc10b 40fc10b]<br />
|<br />
[https://github.com/xmonad/xmonad/issues/61]<br />
[https://code.google.com/p/xmonad/issues/detail?id=484]<br />
| Alternatively the environments {{ic|XMONAD_CONFIG_HOME}}, {{ic|XMONAD_DATA_HOME}}, and {{ic|XMONAD_CACHE_HOME}} are also available.<br />
|-<br />
| {{Pkg|xsel}}<br />
| {{ic|~/.xsel.log}}<br />
| [https://github.com/kfish/xsel/commit/ee7b481 ee7b481]<br />
| [https://github.com/kfish/xsel/issues/10]<br />
|<br />
|-<br />
| {{Pkg|yarn}}<br />
|<br />
{{ic|~/.yarnrc<br><br />
~/.yarn/<br><br />
~/.yarncache/<br><br />
~/.yarn-config/}}<br />
| [https://github.com/yarnpkg/yarn/commit/2d454b5 2d454b5]<br />
| [https://github.com/yarnpkg/yarn/pull/5336]<br />
|<br />
|}<br />
<br />
=== Partial ===<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Supported Since<br />
! Discussion<br />
! Notes<br />
|-<br />
| {{Pkg|abook}}<br />
| {{ic|~/.abook}}<br />
|<br />
|<br />
| {{ic|1=$ abook --config "$XDG_CONFIG_HOME"/abook/abookrc --datafile "$XDG_DATA_HOME"/abook/addressbook}}<br />
|-<br />
| {{Pkg|ack}}<br />
| {{ic|~/.ackrc}}<br />
|<br />
| [https://github.com/beyondgrep/ack2/issues/516]<br />
| {{ic|1=$ export ACKRC="$XDG_CONFIG_HOME/ack/ackrc"}}<br />
|-<br />
| [[Anki]]<br />
|<br />
{{ic|~/Anki<br><br />
~/Documents/Anki}}<br />
|<br />
| [https://github.com/dae/anki/pull/49] [https://github.com/dae/anki/pull/58]<br />
| {{ic|1=$ anki -b "$XDG_DATA_HOME"/Anki}}<br />
|-<br />
| [[aspell]]<br />
| {{ic|~/.aspell.conf}}<br />
|<br />
|<br />
| {{ic|1=$ export ASPELL_CONF="per-conf $XDG_CONFIG_HOME/aspell/aspell.conf; personal $XDG_CONFIG_HOME/aspell/en.pws; repl $XDG_CONFIG_HOME/aspell/en.prepl"}}<br />
|-<br />
| [[Atom]]<br />
| {{ic|~/.atom}}<br />
|<br />
| [https://github.com/atom/atom/issues/8281]<br />
| {{ic|1=$ export ATOM_HOME="$XDG_DATA_HOME"/atom}}<br />
|-<br />
| {{Pkg|aws-cli}}<br />
| {{ic|~/.aws}}<br />
| [https://github.com/aws/aws-cli/commit/fc5961ea2cc0b5976ac9f777e20e4236fd7540f5 1.7.45]<br />
| [https://github.com/aws/aws-cli/issues/2433]<br />
|<br />
{{ic|1=$ export AWS_SHARED_CREDENTIALS_FILE="$XDG_CONFIG_HOME"/aws/credentials<br><br />
$ export AWS_CONFIG_FILE="$XDG_CONFIG_HOME"/aws/config}}<br />
|-<br />
| {{Pkg|bash-completion}}<br />
| {{ic|~/.bash_completion}}<br />
|<br />
| <br />
| {{ic|1=$ export BASH_COMPLETION_USER_FILE="$XDG_CONFIG_HOME"/bash-completion/bash_completion}}<br />
|-<br />
| [[bazaar]]<br />
|<br />
{{ic|~/.bazaar<br><br />
~/.bzr.log}}<br />
| [https://bugs.launchpad.net/bzr/+bug/195397/comments/15 2.3.0]<br />
| [https://bugs.launchpad.net/bzr/+bug/195397]<br />
| Discussion in upstream bug states that bazaar will use {{ic|~/.config/bazaar}} if it exists. The logfile {{ic|~/.bzr.log}} might still be written.<br />
|-<br />
| {{Aur|buchhaltung-git}}<br />
|<br />
{{ic|~/.buchhaltung}}<br />
| <br />
| [https://github.com/johannesgerer/buchhaltung/issues/44]<br />
| {{ic|1=$ export BUCHHALTUNG="$XDG_CONFIG_HOME"/buchhaltung}}<br />
|-<br />
| [[Ruby#Bundler]]<br />
| {{ic|~/.bundle}}<br />
|<br />
| [https://github.com/bundler/bundler/pull/6024] [https://github.com/bundler/bundler/issues/4333]<br />
| {{ic|1=$ export BUNDLE_USER_CONFIG="$XDG_CONFIG_HOME"/bundle BUNDLE_USER_CACHE="$XDG_CACHE_HOME"/bundle BUNDLE_USER_PLUGIN="$XDG_DATA_HOME"/bundle}}<br />
|-<br />
| [[Rust#Cargo]]<br />
| {{ic|~/.cargo}}<br />
|<br />
| [https://github.com/rust-lang/cargo/issues/1734] [https://github.com/rust-lang/rfcs/pull/1615] [https://github.com/rust-lang/cargo/pull/5183] [https://github.com/rust-lang/cargo/pull/148]<br />
| {{ic|1=$ export CARGO_HOME="$XDG_DATA_HOME"/cargo}}<br />
|-<br />
| [[ccache]]<br />
| {{ic|~/.ccache}}<br />
|<br />
|<br />
| {{ic|1=$ export CCACHE_CONFIGPATH="$XDG_CONFIG_HOME"/ccache.config}}<br><br />
{{ic|1=$ export CCACHE_DIR="$XDG_CACHE_HOME"/ccache}}<br />
|-<br />
| {{AUR|chez-scheme}}<br />
| {{ic|~/.chezscheme_history}}<br />
|<br />
|<br />
| {{ic|1=$ petite --eehistory "$XDG_DATA_HOME"/chezscheme/history}}<br />
|-<br />
| [[Chromium]]<br />
| {{ic|~/.chromium<br><br />
~/.pki}}<br />
| [https://src.chromium.org/viewvc/chrome?revision=23057&view=revision 23057]<br />
|<br />
[https://groups.google.com/forum/#!topic/chromium-dev/QekVQxF3nho]<br />
[https://code.google.com/p/chromium/issues/detail?id=16976]<br />
[https://bugs.chromium.org/p/chromium/issues/detail?id=1038587]<br />
|<br />
|-<br />
| [[conky]]<br />
| {{ic|~/.conkyrc}}<br />
| [https://github.com/brndnmtthws/conky/commit/00481ee9a97025e8e2acd7303d080af1948f7980 00481ee]<br />
| [https://github.com/brndnmtthws/conky/issues/144]<br />
| {{ic|1=$ conky --config="$XDG_CONFIG_HOME"/conky/conkyrc}}<br />
|-<br />
| [[coreutils]]<br />
| {{ic|~/.dircolors}}<br />
|<br />
|<br />
| {{ic|1=$ eval $(dircolors "$XDG_CONFIG_HOME"/dircolors)}}<br />
|-<br />
| [http://www.dungeoncrawl.org/ crawl]<br />
| {{ic|~/.crawl}}<br />
|<br />
|<br />
| The trailing slash is required:<br />
<br />
{{ic|1=$ export CRAWL_DIR="$XDG_DATA_HOME"/crawl/}}<br />
|-<br />
| {{Pkg|clusterssh}}<br />
| {{ic|~/.clusterssh/}}<br />
|<br />
|<br />
| {{ic|1=$ alias cssh="cssh --config-file '$XDG_CONFIG_HOME/clusterssh/config'" }}<br />
{{hc|$XDG_CONFIG_HOME/clusterssh/config|2=<br />
extra_cluster_file=$HOME/.config/clusterssh/clusters<br />
extra_tag_file=$HOMe/.config/clusterssh/tags<br />
}}<br />
Despite this, clusterssh will still create {{ic|~/.clusterssh/}}.<br />
|-<br />
| [[CUDA]]<br />
| {{ic|~/.nv}}<br />
|<br />
|<br />
| {{ic|1=$ export CUDA_CACHE_PATH="$XDG_CACHE_HOME"/nv}}<br />
|-<br />
| [[dict]]<br />
| {{ic|~/.dictrc}}<br />
|<br />
|<br />
| {{ic|1=$ dict -c "$XDG_CONFIG_HOME"/dict/dictrc}}<br />
|-<br />
| [[Docker]]<br />
| {{ic|~/.docker}}<br />
|<br />
|<br />
| {{ic|1=$ export DOCKER_CONFIG="$XDG_CONFIG_HOME"/docker}}<br />
|-<br />
| {{Pkg|docker-machine}}<br />
| {{ic|~/.docker/machine}}<br />
|<br />
|<br />
| {{ic|1=$ export MACHINE_STORAGE_PATH="$XDG_DATA_HOME"/docker-machine}}<br />
|-<br />
| [[DOSBox]]<br />
| {{ic|~/.dosbox/dosbox-0.74-2.conf}}<br />
|<br />
| [https://www.vogons.org/viewtopic.php?t=29599]<br />
| {{ic|1=$ dosbox -conf "$XDG_CONFIG_HOME"/dosbox/dosbox.conf}}<br />
|-<br />
| [https://electrum.org Electrum Bitcoin Wallet]<br />
| {{ic|~/.electrum}}<br />
| [https://github.com/spesmilo/electrum/commit/c121230 c121230]<br />
| <br />
| {{ic|1=$ export ELECTRUMDIR="$XDG_DATA_HOME/electrum"}}<br />
|-<br />
| [[ELinks]]<br />
| {{ic|~/.elinks}}<br />
|<br />
|<br />
| {{ic|1=$ export ELINKS_CONFDIR="$XDG_CONFIG_HOME"/elinks}}<br />
|-<br />
| {{Pkg|elixir}}<br />
| {{ic|~/.mix}}<br />
| [https://github.com/elixir-lang/elixir/commit/afaf889 afaf889]<br />
| [https://github.com/elixir-lang/elixir/issues/8818] [https://github.com/elixir-lang/elixir/pull/9937]<br />
| Elixir do not fully conform to XDG specs, it will use XDG only if the environment variables are present, otherwise it will by default use legacy path.<br />
|-<br />
| [[Emacs]]<br />
|<br />
{{ic|~/.emacs<br><br />
~/.emacs.d/}}<br />
| [https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=4118297ae2fab4886b20d193ba511a229637aea3]<br />
| <br />
| Not in 26.3 or older. Workaround for older versions: It's possible to set {{ic|HOME}}, but it has unexpected side effects. So far the most promising approach is modifying another Emacs environment variable to alter the load path and author your own site file which can manually load up your init file, but it changes the load process significantly.<br />
|-<br />
| {{Pkg|emscripten}}<br />
|<br />
{{ic|~/.emscripten<br><br />
~/.emscripten_sanity<br><br />
~/.emscripten_ports<br><br />
~/.emscripten_cache__last_clear}}<br />
|<br />
| [https://github.com/kripken/emscripten/issues/3624]<br />
|<br />
{{ic|1=$ export EM_CONFIG="$XDG_CONFIG_HOME"/emscripten/config<br><br />
$ export EM_CACHE="$XDG_CACHE_HOME"/emscripten/cache<br><br />
$ export EM_PORTS="$XDG_DATA_HOME"/emscripten/cache<br><br />
$ emcc --em-config "$XDG_CONFIG_HOME"/emscripten/config --em-cache "$XDG_CACHE_HOME"/emscripten/cache}}<br />
|-<br />
| {{AUR|freecad}}<br />
| {{ic|~/.FreeCAD}}<br />
|<br />
| [https://www.freecadweb.org/tracker/view.php?id=2956]<br />
| {{ic|1=$ freecad -u "$XDG_CONFIG_HOME"/FreeCAD/user.cfg -s "$XDG_CONFIG_HOME"/FreeCAD/system.cfg}}<br />
<br />
Despite these options, {{AUR|freecad}} will still create the file {{ic|.FreeCAD/cookie}} as the web module has it [https://github.com/FreeCAD/FreeCAD/blob/master/src/Mod/Web/Gui/CookieJar.cpp#L55 hard coded]<br />
|-<br />
| [[GDB]]<br />
| {{ic|~/.gdbinit}}<br />
|<br />
|<br />
| {{ic|1=$ gdb -nh -x "$XDG_CONFIG_HOME"/gdb/init}}<br />
|-<br />
| {{AUR|get_iplayer}}<br />
| {{ic|~/.get_iplayer}}<br />
|<br />
|<br />
| {{ic|1=$ export GETIPLAYERUSERPREFS="$XDG_DATA_HOME"/get_iplayer}}<br />
|-<br />
| [[getmail]]<br />
| {{ic|~/.getmail/getmailrc}}<br />
|<br />
|<br />
| {{ic|1=$ getmail --rcfile="$XDG_CONFIG_HOME/getmail/getmailrc" --getmaildir="$XDG_DATA_HOME/getmail"}}<br />
|-<br />
| {{AUR|gliv}}<br />
| {{ic|~/.glivrc}}<br />
|<br />
|<br />
| {{ic|1=$ gliv --glivrc="$XDG_CONFIG_HOME"/gliv/glivrc}}<br />
|-<br />
| [[GnuPG]]<br />
| {{ic|~/.gnupg}}<br />
|<br />
| [https://bugs.gnupg.org/gnupg/issue1456] [https://bugs.gnupg.org/gnupg/issue1018]<br />
|<br />
{{ic|1=$ export GNUPGHOME="$XDG_DATA_HOME"/gnupg<br><br />
$ gpg2 --homedir "$XDG_DATA_HOME"/gnupg}}<br />
|-<br />
| [[Go]]<br />
| {{ic|~/go}}<br />
| [https://github.com/golang/go/commit/ca8a055f5cc7c1dfa0eb542c60071c7a24350f76]<br />
|<br />
|<br />
{{ic|1=$ export GOPATH="$XDG_DATA_HOME"/go}}<br />
|-<br />
| [[Google Earth]]<br />
| {{ic|~/.googleearth}}<br />
|<br />
|<br />
| Some paths can be changed with the {{ic|KMLPath}} and {{ic|CachePath}} options in {{ic|~/.config/Google/GoogleEarthPlus.conf}}<br />
|-<br />
| {{Pkg|gopass}}<br />
| {{ic|~/.password-store}}<br />
|<br />
|<br />
| Override settings in {{ic|~/.config/gopass/config.yml}}:<br />
{{hc|~/.config/gopass/config.yml|<br />
root:<br />
path: gpgcli-gitcli-fs+file:///home/<userid>/.config/password-store<br />
}}<br />
|-<br />
| [https://sourceforge.net/projects/gqclient GQ LDAP client]<br />
|<br />
{{ic|~/.gq<br><br />
~/.gq-state}}<br />
| [https://sourceforge.net/p/gqclient/mailman/message/2053978 1.51]<br />
|<br />
|<br />
{{ic|1=$ export GQRC="$XDG_CONFIG_HOME"/gqrc<br><br />
$ export GQSTATE="$XDG_DATA_HOME"/gq/gq-state<br><br />
$ mkdir -p "$(dirname "$GQSTATE")"}}<br />
|-<br />
| [[Gradle]]<br />
| {{ic|~/.gradle}}<br />
|<br />
| [https://discuss.gradle.org/t/be-a-nice-freedesktop-citizen-move-the-gradle-to-the-appropriate-location-in-linux/2199]<br />
| {{ic|1=$ export GRADLE_USER_HOME="$XDG_DATA_HOME"/gradle}}<br />
|-<br />
| [[GTK]] 1<br />
| {{ic|~/.gtkrc}}<br />
|<br />
|<br />
| {{ic|1=$ export GTK_RC_FILES="$XDG_CONFIG_HOME"/gtk-1.0/gtkrc}}<br />
|-<br />
| [[GTK]] 2<br />
| {{ic|~/.gtkrc-2.0}}<br />
|<br />
|<br />
| {{ic|1=$ export GTK2_RC_FILES="$XDG_CONFIG_HOME"/gtk-2.0/gtkrc}}<br />
|-<br />
| {{Pkg|hledger}}<br />
| {{ic|~/.hledger.journal}}<br />
|<br />
| [https://github.com/simonmichael/hledger/issues/1081]<br />
| {{ic|1=$ export LEDGER_FILE="$XDG_DATA_HOME"/hledger.journal}}<br />
|-<br />
| {{AUR|imapfilter}}<br />
| {{ic|~/.imapfilter}}<br />
| <br />
| <br />
| {{ic|1=$ export IMAPFILTER_HOME="$XDG_CONFIG_HOME/imapfilter"}}<br />
|-<br />
| {{Pkg|httpie}}<br />
| {{ic|~/.httpie}}<br />
|<br />
| [https://github.com/jakubroztocil/httpie/issues/145]<br />
| {{ic|1=$ export HTTPIE_CONFIG_DIR="$XDG_CONFIG_HOME"/httpie}}<br />
|-<br />
| [http://ipython.org ipython]/[[jupyter]]<br />
| {{ic|~/.ipython}}<br />
|<br />
| [https://github.com/ipython/ipython/pull/4457 won't fix]<br />
|<br />
{{ic|1=$ export IPYTHONDIR="$XDG_CONFIG_HOME"/jupyter<br><br />
$ export JUPYTER_CONFIG_DIR="$XDG_CONFIG_HOME"/jupyter}}<br />
|-<br />
| [https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html irb]<br />
| {{ic|~/.irbrc}}<br />
|<br />
|<br />
| {{hc|1=~/.profile|2=$ export IRBRC="$XDG_CONFIG_HOME"/irb/irbrc}}<br />
{{hc|1="$XDG_CONFIG_HOME"/irb/irbrc|2=IRB.conf[:SAVE_HISTORY] {{!}}{{!}}= 1000<br />
IRB.conf[:HISTORY_FILE] {{!}}{{!}}= File.join(ENV["XDG_DATA_HOME"], "irb", "history")}}<br />
|-<br />
| [[irssi]]<br />
| {{ic|~/.irssi}}<br />
|<br />
| [https://github.com/irssi/irssi/pull/511]<br />
| {{ic|1=$ irssi --config="$XDG_CONFIG_HOME"/irssi/config --home="$XDG_DATA_HOME"/irssi}}<br />
|-<br />
| [[isync]]<br />
| {{ic|~/.mbsyncrc}}<br />
|<br />
|<br />
| {{ic|1=$ mbsync -c "$XDG_CONFIG_HOME"/isync/mbsyncrc}}<br />
|-<br />
| [[Java#OpenJDK]]<br />
| {{ic|~/.java/.userPrefs}}<br />
|<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=1154277]<br />
| {{ic|1=$ export _JAVA_OPTIONS=-Djava.util.prefs.userRoot="$XDG_CONFIG_HOME"/java}}<br />
|-<br />
| [[KDE]]<br />
| {{ic|~/.kde}}<br />
|<br />
| [https://userbase.kde.org/KDE_System_Administration/KDE_Filesystem_Hierarchy#KDEHOME]<br />
| {{ic|1=$ export KDEHOME="$XDG_CONFIG_HOME"/kde}}<br />
|-<br />
| [[ledger]]<br />
| {{ic|~/.ledgerrc}}, {{ic|~/.pricedb}}<br />
|<br />
| [https://github.com/ledger/ledger/issues/1820]<br />
| {{ic|1=$ ledger --init-file "$XDG_CONFIG_HOME"/ledgerrc}}<br />
|-<br />
| [[Core utilities|less]]<br />
| {{ic|~/.lesshst}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ mkdir -p "$XDG_CACHE_HOME"/less<br><br />
$ export LESSKEY="$XDG_CONFIG_HOME"/less/lesskey<br><br />
$ export LESSHISTFILE="$XDG_CACHE_HOME"/less/history}}<br />
<br />
{{ic|1=$ export LESSHISTFILE=-}} can be used to disable this feature.<br />
|-<br />
| {{Pkg|libdvdcss}}<br />
| {{ic|~/.dvdcss}}<br />
|<br />
| [https://mailman.videolan.org/pipermail/libdvdcss-devel/2014-August/001022.html]<br />
| {{ic|1=$ export DVDCSS_CACHE="$XDG_DATA_HOME"/dvdcss}}<br />
|-<br />
| {{Pkg|libice}}<br />
| {{ic|~/.ICEauthority}}<br />
|<br />
| [https://gitlab.freedesktop.org/xorg/lib/libice/issues/2]<br />
| {{ic|1=$ export ICEAUTHORITY="$XDG_CACHE_HOME"/ICEauthority}}<br />
Make sure {{ic|XDG_CACHE_HOME}} is set beforehand to directory user running [[Xorg]] has write access to.<br />
<br />
'''Do not''' use {{ic|XDG_RUNTIME_DIR}} as it is available '''after''' login. Display managers that launch [[Xorg]] (like [[GDM]]) will repeatedly fail otherwise.<br />
|-<br />
| [[Xorg|libx11]]<br />
|<br />
{{ic|~/.XCompose<br><br />
~/.compose-cache}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export XCOMPOSEFILE="$XDG_CONFIG_HOME"/X11/xcompose<br><br />
$ export XCOMPOSECACHE="$XDG_CACHE_HOME"/X11/xcompose}}<br />
|-<br />
| {{Pkg|ltrace}}<br />
| {{ic|~/.ltrace.conf}}<br />
|<br />
|<br />
| {{ic|1=$ ltrace -F "$XDG_CONFIG_HOME"/ltrace/ltrace.conf}}<br />
|-<br />
| {{Pkg|maven}}<br />
| {{ic|~/.m2}}<br />
|<br />
| [https://issues.apache.org/jira/browse/MNG-6603]<br />
| {{ic|1=$ mvn -gs "$XDG_CONFIG_HOME"/maven/settings.xml}}<br />
{{hc|[http://maven.apache.org/settings.html settings.xml]|<nowiki><settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0<br />
https://maven.apache.org/xsd/settings-1.0.0.xsd"><br />
...<br />
<localRepository>${env.XDG_CACHE_HOME}/maven/repository</localRepository><br />
...<br />
</settings></nowiki>}}<br />
|-<br />
| [[Mathematica]]<br />
| {{ic|~/.Mathematica}}<br />
|<br />
|<br />
| {{ic|1=$ export MATHEMATICA_USERBASE="$XDG_CONFIG_HOME"/mathematica}}<br />
|-<br />
| {{Pkg|mednafen}}<br />
| {{ic|~/.mednafen}}<br />
|<br />
|<br />
| {{ic|1=$ export MEDNAFEN_HOME="$XDG_CONFIG_HOME"/mednafen}}<br />
|-<br />
| {{Pkg|mitmproxy}}<br />
| {{ic|~/.mitmproxy}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ alias mitmproxy="mitmproxy --set confdir=$XDG_CONFIG_HOME/mitmproxy"<br><br />
$ alias mitmweb="mitmweb --set confdir=$XDG_CONFIG_HOME/mitmproxy"}}<br />
|-<br />
| [[MOC]]<br />
| {{ic|~/.moc}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ mocp -M "$XDG_CONFIG_HOME"/moc<br><br />
$ mocp -O MOCDir="$XDG_CONFIG_HOME"/moc}}<br />
|-<br />
| {{Pkg|monero}}<br />
| {{ic|~/.bitmonero}}<br />
|<br />
|<br />
| {{ic|1=$ monerod --data-dir "$XDG_DATA_HOME"/bitmonero}}<br />
|-<br />
| {{Pkg|most}}<br />
| {{ic|~/.mostrc}}<br />
|<br />
|<br />
| {{ic|1=$ export MOST_INITFILE="$XDG_CONFIG_HOME"/mostrc}}<br />
|-<br />
| [[MPlayer]]<br />
| {{ic|~/.mplayer}}<br />
|<br />
|<br />
| {{ic|1=$ export MPLAYER_HOME="$XDG_CONFIG_HOME"/mplayer}}<br />
|-<br />
| [[MySQL]]<br />
| {{ic|~/.mysql_history}}<br />
|<br />
|<br />
| {{ic|1=$ export MYSQL_HISTFILE="$XDG_DATA_HOME"/mysql_history}}<br />
|-<br />
| {{Pkg|ncurses}}<br />
| {{ic|~/.terminfo}}<br />
|<br />
|<br />
| Precludes system path searching:<br />
<br />
{{ic|1=$ export TERMINFO="$XDG_DATA_HOME"/terminfo<br><br />
$ export TERMINFO_DIRS="$XDG_DATA_HOME"/terminfo:/usr/share/terminfo}}<br />
|-<br />
| {{Pkg|ncmpc}}<br />
| {{ic|~/.ncmpc}}<br />
|<br />
|<br />
| {{ic|ncmpc -f "$XDG_CONFIG_HOME"/ncmpc/config}}<br />
|-<br />
| [[Netbeans]]<br />
| {{ic|~/.netbeans}}<br />
|<br />
| [https://netbeans.org/bugzilla/show_bug.cgi?id=215961]<br />
| {{ic|1=$ netbeans --userdir "${XDG_CONFIG_HOME}"/netbeans}}<br />
|-<br />
| [[Node.js]]<br />
| {{ic|~/.node_repl_history}}<br />
|<br />
|<br />
| {{ic|1=$ export NODE_REPL_HISTORY="$XDG_DATA_HOME"/node_repl_history}} [https://nodejs.org/api/repl.html#repl_environment_variable_options]<br />
|-<br />
| [[notmuch]]<br />
| {{ic|~/.notmuch-config}}<br />
|<br />
| [http://notmuchmail.org/pipermail/notmuch/2011/007007.html]<br />
|<br />
{{ic|1=$ export NOTMUCH_CONFIG="$XDG_CONFIG_HOME"/notmuch/notmuchrc<br><br />
$ export NMBGIT="$XDG_DATA_HOME"/notmuch/nmbug}}<br />
|-<br />
| {{Pkg|npm}}<br />
|<br />
{{ic|~/.npm<br><br />
~/.npmrc}}<br />
|<br />
| [https://github.com/npm/cli/issues/654]<br />
| {{ic|1=$ export NPM_CONFIG_USERCONFIG=$XDG_CONFIG_HOME/npm/npmrc}}<br />
{{hc|npmrc|<nowiki><br />
prefix=${XDG_DATA_HOME}/npm<br />
cache=${XDG_CACHE_HOME}/npm<br />
tmp=${XDG_RUNTIME_DIR}/npm<br />
init-module=${XDG_CONFIG_HOME}/npm/config/npm-init.js<br />
</nowiki>}}<br />
{{ic|prefix}} is unnecessary (and unsupported) if Node.js is installed by {{AUR|nvm}}.<br />
|-<br />
| {{Pkg|nuget}}<br />
| {{ic|~/.nuget/packages}}<br />
|<br />
| [https://docs.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders]<br />
| {{ic|1=$ export NUGET_PACKAGES="$XDG_CACHE_HOME"/NuGetPackages}}<br />
|-<br />
| [[NVIDIA]]<br />
| {{ic|~/.nv}}<br />
|<br />
|<br />
| Uses {{ic|XDG_CACHE_HOME}} if set, otherwise improperly falls back to {{ic|~/.nv}} instead of {{ic|~/.cache}}.<br />
|-<br />
| {{Pkg|nvidia-settings}}<br />
| {{ic|~/.nvidia-settings-rc}}<br />
|<br />
|<br />
| {{ic|1=$ nvidia-settings --config="$XDG_CONFIG_HOME"/nvidia/settings}}<br />
|-<br />
| {{AUR|nvm}}<br />
| {{ic|~/.nvm}}<br />
|<br />
|<br />
| {{ic|1=$ export NVM_DIR="$XDG_DATA_HOME"/nvm}}<br />
|-<br />
| [[Octave]]<br />
|<br />
{{ic|~/octave<br><br />
~/.octave_packages<br><br />
~/.octave_hist}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export OCTAVE_HISTFILE="$XDG_CACHE_HOME/octave-hsts"<br><br />
$ export OCTAVE_SITE_INITFILE="$XDG_CONFIG_HOME/octave/octaverc"}}<br />
<br />
{{hc|$XDG_CONFIG_HOME/octave/octaverc|<nowiki><br />
source /usr/share/octave/site/m/startup/octaverc;<br />
pkg prefix ~/.local/share/octave/packages ~/.local/share/octave/packages;<br />
pkg local_list /home/<your username>/.local/share/octave/octave_packages;<br />
</nowiki>}}<br />
The {{ic|local_list}} option must be given an absolute path.<br />
|-<br />
| {{Pkg|openscad}}<br />
| {{ic|~/.OpenSCAD}}<br />
| [https://github.com/openscad/openscad/commit/7c3077b0f 7c3077b0f]<br />
| [https://github.com/openscad/openscad/issues/125]<br />
| Does not fully honour XDG Base Directory Specification, see [https://github.com/openscad/openscad/issues/373]<br />
<br />
Currently it [https://github.com/openscad/openscad/blob/master/src/PlatformUtils-posix.cc#L20 hard-codes] {{ic|~/.local/share}}.<br />
|-<br />
| [[OpenSSL]]<br />
| {{ic|~/.rnd}}<br />
|<br />
|<br />
| Seeding file {{ic|.rnd}}'s location can be set with {{ic|RANDFILE}} environment variable per [https://www.openssl.org/docs/faq.html FAQ].<br />
|-<br />
| {{Pkg|parallel}}<br />
| {{ic|~/.parallel}}<br />
| [https://git.savannah.gnu.org/cgit/parallel.git/commit/?id=685018f532f4e2d24b84eb28d5de3d759f0d1af1 20170422]<br />
|<br />
| {{ic|1=$ export PARALLEL_HOME="$XDG_CONFIG_HOME"/parallel}}<br />
|-<br />
| [[Pass]]<br />
| {{ic|~/.password-store}}<br />
|<br />
|<br />
| {{ic|1=$ export PASSWORD_STORE_DIR="$XDG_DATA_HOME"/pass}}<br />
|-<br />
| [[Pidgin]]<br />
| {{ic|~/.purple}}<br />
|<br />
| [https://developer.pidgin.im/ticket/4911]<br />
| {{ic|1=$ pidgin --config="$XDG_DATA_HOME"/purple}}<br />
|-<br />
| [[PostgreSQL]]<br />
|<br />
{{ic|~/.psqlrc<br><br />
~/.psql_history<br><br />
~/.pgpass<br><br />
~/.pg_service.conf}}<br />
| 9.2<br />
| [https://www.postgresql.org/docs/current/static/app-psql.html] [https://www.postgresql.org/docs/current/static/libpq-envars.html]<br />
|<br />
{{ic|1=$ export PSQLRC="$XDG_CONFIG_HOME/pg/psqlrc"<br><br />
$ export PSQL_HISTORY="$XDG_CACHE_HOME/pg/psql_history"<br><br />
$ export PGPASSFILE="$XDG_CONFIG_HOME/pg/pgpass"<br><br />
$ export PGSERVICEFILE="$XDG_CONFIG_HOME/pg/pg_service.conf"}}<br />
<br />
It is required to create both directories: {{ic|1=$ mkdir "$XDG_CONFIG_HOME/pg" && mkdir "$XDG_CACHE_HOME/pg"}}<br />
|-<br />
| [[PulseAudio]]<br />
| {{ic|~/.esd_auth}}<br />
|<br />
|<br />
| Very likely generated by the {{ic|module-esound-protocol-unix.so}} module. It can be configured to use a different location but it makes much more sense to just comment out this module in {{ic|/etc/pulse/default.pa}} or {{ic|"$XDG_CONFIG_HOME"/pulse/default.pa}}.<br />
|-<br />
| {{aur|python-azure-cli}}<br />
| {{ic|~/.azure}}<br />
|<br />
|<br />
| {{ic|1=$ export AZURE_CONFIG_DIR=$XDG_DATA_HOME/azure}}<br />
|-<br />
| {{AUR|python-grip}}<br />
| {{ic|~/.grip}}<br />
|<br />
| <br />
| {{ic|1=$ export GRIPHOME="$XDG_CONFIG_HOME/grip"}}<br />
|-<br />
| {{Pkg|python-setuptools}}<br />
| {{ic|~/.python-eggs}}<br />
|<br />
|<br />
| {{ic|1=$ export PYTHON_EGG_CACHE="$XDG_CACHE_HOME"/python-eggs}}<br />
|-<br />
| {{Pkg|python-pylint}}<br />
| {{ic|~/.pylint.d}}<br />
|<br />
| [https://github.com/PyCQA/pylint/issues/1364 won't fix]<br />
| {{ic|1=$ export PYLINTHOME="$XDG_CACHE_HOME"/pylint}}<br />
|-<br />
| {{Pkg|racket}}<br />
| {{ic|~/.racketrc<br><br />
~/.racket}}<br />
|<br />
| [https://github.com/racket/racket/issues/2740]<br />
| {{ic|1=$ export PLTUSERHOME="$XDG_DATA_HOME"/racket}}<br />
|-<br />
| [[readline]]<br />
| {{ic|~/.inputrc}}<br />
|<br />
|<br />
| {{ic|1=$ export INPUTRC="$XDG_CONFIG_HOME"/readline/inputrc}}<br />
|-<br />
| {{Pkg|rlwrap}}<br />
| {{ic|~/.*_history}}<br />
|<br />
| [https://github.com/hanslub42/rlwrap/issues/25]<br />
| {{ic|1=$ export RLWRAP_HOME="$XDG_DATA_HOME"/rlwrap}}<br />
|-<br />
| [[Ruby#RubyGems]]<br />
| {{ic|~/.gem}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export GEM_HOME="$XDG_DATA_HOME"/gem<br><br />
$ export GEM_SPEC_CACHE="$XDG_CACHE_HOME"/gem}}<br />
<br />
Make sure to remove {{ic|gem: --user-install}} from {{ic|/etc/gemrc}}<br />
|-<br />
| [[Rust#Rustup]]<br />
| {{ic|~/.rustup}}<br />
|<br />
| [https://github.com/rust-lang-nursery/rustup.rs/issues/247]<br />
| {{ic|1=$ export RUSTUP_HOME="$XDG_DATA_HOME"/rustup}}<br />
|-<br />
| {{Pkg|sbt}}<br />
| {{ic|~/.sbt}}<br />
{{ic|~/.ivy2}}<br />
|<br />
| [https://github.com/sbt/sbt/issues/3681]<br />
| {{ic|1=$ sbt -ivy "$XDG_DATA_HOME"/ivy2 -sbt-dir "$XDG_DATA_HOME"/sbt}} (beware [https://github.com/sbt/sbt/issues/3598])<br />
|-<br />
| [[GNU Screen]]<br />
| {{ic|~/.screenrc}}<br />
|<br />
|<br />
| {{ic|1=$ export SCREENRC="$XDG_CONFIG_HOME"/screen/screenrc}}<br />
|-<br />
| [[Haskell#Stack]]<br />
| {{ic|~/.stack}}<br />
|<br />
| [https://github.com/commercialhaskell/stack/issues/342]<br />
| {{ic|1=$ export STACK_ROOT="$XDG_DATA_HOME"/stack}}<br />
|-<br />
| [[subversion]]<br />
| {{ic|~/.subversion}}<br />
|<br />
| [https://issues.apache.org/jira/browse/SVN-4599] [https://mail-archives.apache.org/mod_mbox/subversion-users/201204.mbox/%3c4F8FBCC6.4080205@ritsuka.org%3e][http://mail-archives.apache.org/mod_mbox/subversion-dev/201509.mbox/%3c20150917222954.GA20331@teapot%3e]<br />
| {{ic|1=$ svn --config-dir "$XDG_CONFIG_HOME"/subversion}}<br />
|-<br />
| {{Pkg|task}}<br />
|<br />
{{ic|~/.task<br><br />
~/.taskrc}}<br />
|<br />
|<br />
|<br />
{{ic|1=$ export TASKDATA="$XDG_DATA_HOME"/task<br><br />
$ export TASKRC="$XDG_CONFIG_HOME"/task/taskrc}}<br />
|-<br />
| {{AUR|tiptop}}<br />
| {{ic|~/.tiptoprc}}<br />
|<br />
|<br />
| This will still expect the {{ic|.tiptoprc}} file.<br />
{{ic|$ tiptop -W "$XDG_CONFIG_HOME"/tiptop}}<br />
|-<br />
| [[tmux]]<br />
| {{ic|~/.tmux.conf}}<br />
|<br />
| [https://github.com/tmux/tmux/issues/142]<br />
| {{ic|1=$ tmux -f "$XDG_CONFIG_HOME"/tmux/tmux.conf}}<br />
<br />
{{ic|1=$ export TMUX_TMPDIR="$XDG_RUNTIME_DIR"}}<br />
|-<br />
| {{Pkg|uncrustify}}<br />
| {{ic|~/.uncrustify.cfg}}<br />
|<br />
|<br />
| {{ic|1=$ export UNCRUSTIFY_CONFIG="$XDG_CONFIG_HOME"/uncrustify/uncrustify.cfg}}<br />
|-<br />
| [[Unison]]<br />
| {{ic|~/.unison}}<br />
|<br />
|<br />
| {{ic|1=$ export UNISON="$XDG_DATA_HOME"/unison}}<br />
|-<br />
| [[Rxvt-unicode/Tips_and_tricks#Daemon-client|urxvtd]]<br />
| {{ic|~/.urxvt/urxvtd-hostname}}<br />
|<br />
|<br />
| {{ic|1=$ export RXVT_SOCKET="$XDG_RUNTIME_DIR"/urxvtd}}<br />
|-<br />
| [[Vagrant]]<br />
|<br />
{{ic|~/.vagrant.d<br><br />
~/.vagrant.d/aliases}}<br />
|<br />
| [https://www.vagrantup.com/docs/other/environmental-variables.html]<br />
|<br />
{{ic|1=$ export VAGRANT_HOME="$XDG_DATA_HOME"/vagrant<br><br />
$ export VAGRANT_ALIAS_FILE="$XDG_DATA_HOME"/vagrant/aliases}}<br />
|-<br />
| [[Visual Studio Code]]<br />
| {{ic|~/.vscode-oss/argv.json}}<br />
|<br />
| [https://github.com/Microsoft/vscode/issues/3884]<br />
| <br />
|-<br />
| [[AUR|WakaTime]]<br />
| <br />
{{ic|~/.wakatime.cfg<br><br />
~/.wakatime.data<br><br />
~/.wakatime.db<br><br />
~/.wakatime.log}}<br />
|<br />
|<br />
| {{ic|1=$ export WAKATIME_HOME="$XDG_CONFIG_HOME/wakatime"}}<br />
<br />
The directory needs to be created manually:<br><br />
{{ic|1=$ mkdir "$XDG_CONFIG_HOME/wakatime"}}<br />
|-<br />
| [[WeeChat]]<br />
| {{ic|~/.weechat}}<br />
|<br />
| [http://savannah.nongnu.org/task/?10934] [https://github.com/ipython/ipython/pull/4457]<br />
|<br />
{{ic|1=$ export WEECHAT_HOME="$XDG_CONFIG_HOME"/weechat<br><br />
$ weechat -d "$XDG_CONFIG_HOME"/weechat}}<br />
|-<br />
| [[wget]]<br />
|<br />
{{ic|~/.wgetrc<br><br />
~/.wget-hsts}}<br />
|<br />
|<br />
| <br />
{{ic|1=$ export WGETRC="$XDG_CONFIG_HOME/wgetrc"<br><br />
and add the following as an alias for wget:<br><br />
$ wget --hsts-file="$XDG_CACHE_HOME/wget-hsts"<br><br />
or set the hsts-file variable with an absolute path as wgetrc does not support environment variables:<br><br />
$ echo hsts-file \= "$XDG_CACHE_HOME"/wget-hsts >> "$XDG_CONFIG_HOME/wgetrc"}}<br />
|-<br />
| [[wine]]<br />
| {{ic|~/.wine}}<br />
|<br />
| [https://bugs.winehq.org/show_bug.cgi?id=20888]<br />
| [[Wine#Winetricks|Winetricks]] uses XDG-alike location below for [[Wine#WINEPREFIX|WINEPREFIX]] management:<br />
{{ic|1=$ mkdir -p "$XDG_DATA_HOME"/wineprefixes<br><br />
$ export WINEPREFIX="$XDG_DATA_HOME"/wineprefixes/default}}<br />
|-<br />
| [[xbindkeys]]<br />
| {{ic|~/.xbindkeysrc}}<br />
|<br />
|<br />
| {{ic|1=$ xbindkeys -f "$XDG_CONFIG_HOME"/xbindkeys/config}}<br />
|-<br />
| {{Pkg|xorg-xauth}}<br />
| {{ic|~/.Xauthority}}<br />
|<br />
|<br />
| {{ic|1=$ export XAUTHORITY="$XDG_RUNTIME_DIR"/Xauthority}}<br />
<br />
Note that [[LightDM]] does not allow you to change this variable. If you change it nonetheless, you will not be able to login. Use [[startx]] instead or [https://askubuntu.com/a/961459 configure LightDM]. According to [https://unix.stackexchange.com/a/175331] [[SLiM]] has {{ic|~/.Xauthority}} hardcoded.<br />
|-<br />
| [[xinit]]<br />
|<br />
{{ic|~/.xinitrc<br><br />
~/.xserverrc}}<br />
|<br />
| [https://gitlab.freedesktop.org/xorg/app/xinit/issues/14]<br />
|<br />
{{ic|1=$ export XINITRC="$XDG_CONFIG_HOME"/X11/xinitrc<br><br />
$ export XSERVERRC="$XDG_CONFIG_HOME"/X11/xserverrc}}<br />
<br />
Note that these variables are respected by ''xinit'', but not by ''startx''. Instead, specify the filename as an argument:<br />
<br />
{{ic|1=$ startx "$XDG_CONFIG_HOME/X11/xinitrc" -- "$XDG_CONFIG_HOME/X11/xserverrc" vt1}}<br />
|-<br />
| {{Pkg|xorg-xrdb}}<br />
|<br />
{{ic|~/.Xresources<br><br />
~/.Xdefaults}}<br />
|<br />
|<br />
| Ultimately you [https://superuser.com/questions/243914/xresources-or-xdefaults should be] using {{ic|Xresources}} and since these resources are loaded via {{ic|xrdb}} you can specify a path such as {{ic|1=$ xrdb -load ~/.config/X11/xresources}}.<br />
|-<br />
| {{Pkg|z}}<br />
|<br />
{{ic|~/.z}}<br />
|<br />
| [https://github.com/rupa/z/issues/267]<br />
| {{ic|1=$ export _Z_DATA="$XDG_DATA_HOME/z"}}<br />
|-<br />
|}<br />
<br />
=== Hardcoded ===<br />
<br />
{| class="wikitable sortable" style="width: 100%"<br />
! Application<br />
! Legacy Path<br />
! Discussion<br />
! Notes<br />
|-<br />
| [[adb]]<br />
| {{ic|~/.android/}}<br />
| [https://developer.android.com/studio/command-line/variables.html#android_sdk_root]<br />
| {{ic|1=$ export ANDROID_SDK_HOME="$XDG_CONFIG_HOME"/android}}<br />
|-<br />
| [[AMule]]<br />
| {{ic|~/.aMule}}<br />
|<br />
|<br />
|-<br />
| [https://developer.android.com/studio/index.html Android Studio]<br />
|<br />
{{ic|~/.AndroidStudio2.3<br><br />
~/.android/<br><br />
~/.java/}}<br />
|<br />
|<br />
|-<br />
| [https://osdn.net/projects/anthy/ anthy]<br />
| {{ic|~/.anthy}}<br />
| [https://osdn.net/ticket/browse.php?group_id=14&tid=28397]<br />
|<br />
|-<br />
| [https://directory.apache.org/studio/ Apache Directory Studio]<br />
| {{ic|~/.ApacheDirectoryStudio}}<br />
|<br />
|<br />
|-<br />
| [https://christian.amsuess.com/tools/arandr/ ARandR]<br />
| {{ic|~/.screenlayout}}<br />
|<br />
|<br />
|-<br />
| [[Arduino]]<br />
|<br />
{{ic|~/.arduino15<br><br />
~/.jssc}} <br />
| [https://github.com/arduino/Arduino/issues/3915 won't fix]<br />
|<br />
|-<br />
| [https://www.audacityteam.org/ Audacity]<br />
| {{ic|~/.audacity-data/}}<br />
|<br />
|<br />
|-<br />
| [http://fixounet.free.fr/avidemux/ Avidemux]<br />
| {{ic|~/.avidemux6}}<br />
|<br />
|<br />
|-<br />
| [[Bash]]<br />
|<br />
{{ic|~/.bashrc<br><br />
~/.bash_history<br><br />
~/.bash_profile<br><br />
~/.bash_login<br><br />
~/.bash_logout}}<br />
| [http://savannah.gnu.org/support/?108134 won't fix]<br />
| {{ic|1=$ export HISTFILE="$XDG_DATA_HOME"/bash/history}}<br />
A specified {{ic|bashrc}} can be sourced from {{ic|/etc/bash.bashrc}}.<br />
<br />
Specify {{ic|--init-file <file>}} as an alternative to {{ic|~/.bashrc}} for interactive shells.<br />
|-<br />
| [https://www.haskell.org/cabal/ cabal]<br />
| {{ic|~/.cabal/}}<br />
| [https://github.com/haskell/cabal/issues/680]<br />
| See discussion for potential workarounds. It is not very easy or straightforward but may be possible to emulate Base Directory compliance.<br />
|-<br />
| {{AUR|chatty}}<br />
| {{ic|~/.chatty/}}<br />
| [https://github.com/chatty/chatty/issues/273]<br />
|<br />
|-<br />
| {{Pkg|cmake}}<br />
| {{ic|~/.cmake/}}<br />
|<br />
| Used for the user package registry {{ic|~/.cmake/packages/<package>}}, detailed in {{man|7|cmake-packages|User Package Registry}} and [https://gitlab.kitware.com/cmake/community/wikis/doc/tutorials/Package-Registry the Package registry wiki page]. Looks like it's hardcoded, for example in [https://gitlab.kitware.com/cmake/cmake/blob/v3.12.1/Source/cmFindPackageCommand.cxx#L1221 cmFindPackageCommand.cxx].<br />
|-<br />
| [[Cinnamon]]<br />
| {{ic|~/.cinnamon/}}<br />
| [https://github.com/linuxmint/Cinnamon/issues/7807]<br />
|<br />
|-<br />
| {{AUR|cryptomator}}<br />
| {{ic|~/.Cryptomator}}<br />
| [https://github.com/cryptomator/cryptomator/issues/710]<br />
|<br />
|-<br />
| [[CUPS]]<br />
| {{ic|~/.cups/}}<br />
| [https://github.com/apple/cups/issues/4243 won't fix]<br />
|<br />
|-<br />
| [[darcs]]<br />
| {{ic|~/.darcs/}}<br />
| [http://bugs.darcs.net/issue2453]<br />
|<br />
|-<br />
| [[dbus]]<br />
| {{ic|~/.dbus/}}<br />
| [https://gitlab.freedesktop.org/dbus/dbus/issues/46]<br />
| This should be avoidable with kdbus [citation needed].<br />
|-<br />
| {{Pkg|devede}}<br />
| {{ic|~/.devedeng}}<br />
|<br />
| Hardcoded [https://gitlab.com/rastersoft/devedeng/blob/f0893b3ff7b14723bd148db35bdfe2d284156d19/src/devedeng/configuration_data.py#L111 here]<br />
|-<br />
| [https://wiki.gnome.org/Apps/Dia Dia]<br />
| {{ic|~/.dia/}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|dotnet-sdk}}<br />
| {{ic|~/.dotnet/}}<br />
| [https://github.com/dotnet/cli/issues/7569]<br />
|<br />
|-<br />
| [[Eclipse]]<br />
| {{ic|~/.eclipse/}}<br />
| [https://bugs.eclipse.org/bugs/show_bug.cgi?id=200809]<br />
| Option {{ic|1=-Dosgi.configuration.area=@user.home/.config/..}} overrides but must be added to {{ic|"$ECLIPSE_HOME"/eclipse.ini"}} rather than command line which means you must have write access to {{ic|$ECLIPSE_HOME}}. (Arch Linux hard-codes {{ic|$ECLIPSE_HOME}} in {{ic|/usr/bin/eclipse}})<br />
|-<br />
| [http://www.fetchmail.info/ Fetchmail]<br />
| {{ic|~/.fetchmailrc}}<br />
|<br />
|<br />
|-<br />
| [[Firefox]]<br />
| {{ic|~/.mozilla/}}<br />
| [https://bugzil.la/259356]<br />
|<br />
|-<br />
| [[Flatpak]]<br />
| {{ic|~/.var/}}<br />
| [https://github.com/flatpak/flatpak/issues/46] [https://github.com/flatpak/flatpak.github.io/issues/191] [https://github.com/flatpak/flatpak/issues/1651 won't fix]<br />
|<br />
|-<br />
| {{Pkg|fltk}}<br />
| {{ic|~/.fltk/}}<br />
| [https://www.fltk.org/str.php?L3370+P0+S0+C0+I0+E0+V%25+Qxdg]<br />
|<br />
|-<br />
| [https://www.haskell.org/ghc/ GHC]<br />
| {{ic|~/.ghc}}<br />
| [https://ghc.haskell.org/trac/ghc/ticket/6077]<br />
|<br />
|-<br />
| {{Pkg|ghidra}}<br />
|<br />
| [https://github.com/NationalSecurityAgency/ghidra/issues/908]<br />
|<br />
|-<br />
| [[Goldendict]]<br />
| {{ic|~/.goldendict/}}<br />
| [https://github.com/goldendict/goldendict/issues/151]<br />
|<br />
|-<br />
| {{Pkg|gramps}}<br />
| {{ic|~/.gramps/}}<br />
| [https://gramps-project.org/bugs/view.php?id=8025]<br />
| <br />
|-<br />
| {{Pkg|grsync}}<br />
| {{ic|~/.grsync/}}<br />
| [https://sourceforge.net/p/grsync/feature-requests/15/]<br />
|<br />
|-<br />
| [http://recordmydesktop.sourceforge.net/about.php gtk-recordMyDesktop]<br />
| {{ic|~/.gtk-recordmydesktop}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|hplip}}<br />
| {{ic|~/.hplip/}}<br />
| [https://bugs.launchpad.net/hplip/+bug/307152]<br />
|<br />
|-<br />
| [http://www.idris-lang.org/ idris]<br />
| {{ic|~/.idris}}<br />
| [https://github.com/idris-lang/Idris-dev/pull/3456]<br />
|<br />
|-<br />
| [[Java]] OpenJDK<br />
| {{ic|~/.java/fonts}}<br />
| [https://bugzilla.redhat.com/show_bug.cgi?id=1154277]<br />
|<br />
|-<br />
| [[Java]] OpenJFX<br />
| {{ic|~/.java/webview}}<br />
|<br />
|<br />
|-<br />
| [http://julialang.org/ julia]<br />
|<br />
{{ic|~/.juliarc.jl<br><br />
~/.julia_history}}<br />
| [https://github.com/JuliaLang/julia/issues/4630] [https://github.com/JuliaLang/julia/issues/10016]<br />
|<br />
|-<br />
| [http://www.linux-pam.org/ Linux PAM]<br />
| {{ic|~/.pam_environment}}<br />
| [https://github.com/linux-pam/linux-pam/issues/7]<br />
| Hardcoded in [https://github.com/linux-pam/linux-pam/blob/master/modules/pam_env/pam_env.c modules/pam_env/pam_env.c]<br />
|-<br />
| [http://lldb.llvm.org/ lldb]<br />
|<br />
{{ic|~/.lldb<br><br />
~/.lldbinit}}<br />
|<br />
|<br />
|-<br />
| [http://www.mathomatic.org/ mathomatic]<br />
|<br />
{{ic|~/.mathomaticrc<br><br />
~/.matho_history}}<br />
|<br />
| History can be moved by using {{ic|rlwrap mathomatic -r}} with the {{ic|RLWRAP_HOME}} environment set appropriately.<br />
|-<br />
| [[Minecraft]]<br />
| {{ic|~/.minecraft/}}<br />
| [https://bugs.mojang.com/browse/MCL-2563]<br />
|<br />
|-<br />
| [[Minetest]]<br />
| {{ic|~/.minetest/}}<br />
| [https://github.com/minetest/minetest/issues/864 won't fix] [https://github.com/minetest/minetest/issues/8151]<br />
|<br />
|-<br />
| [https://www.mongodb.org/ mongodb]<br />
|<br />
{{ic|~/.mongorc.js<br><br />
~/.dbshell}}<br />
| [https://jira.mongodb.org/browse/DOCS-5652?jql=text%20~%20%22.mongorc.js%22]<br />
| [https://stackoverflow.com/questions/22348604/the-mongorc-js-is-not-found-but-there-is-one/22349050#22349050 This Stack Overflow thread] suggests a partial workaround using command-line switch {{ic|--norc}}.<br />
|-<br />
| [http://0ldsk00l.ca/nestopia/ Nestopia UE]<br />
| {{ic|~/.nestopia/}}<br />
| [https://github.com/0ldsk00l/nestopia/pull/292 won't fix]<br />
|<br />
|-<br />
|<br />
| {{ic|~/.netrc}}<br />
|<br />
| Like {{ic|~/.ssh}}, many programs expect this file to be here. These include projects like curl ({{ic|CURLOPT_NETRC_FILE}}), ftp ({{ic|NETRC}}), s-nail ({{ic|NETRC}}), etc. While some of them offer alternative configurable locations, many do not such as w3m, wget and lftp.<br />
|-<br />
| [[Networkmanager-openvpn]]<br />
| {{ic|~/.cert/nm-openvpn}}<br />
| [https://gitlab.gnome.org/GNOME/NetworkManager-openvpn/issues/35]<br />
|<br />
|-<br />
| [https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS NSS]<br />
| {{ic|~/.pki}}<br />
| [https://bugzilla.mozilla.org/show_bug.cgi?id=818686]<br />
|<br />
|-<br />
| [[OpenSSH]]<br />
| {{ic|~/.ssh}}<br />
| [https://bugzilla.mindrot.org/show_bug.cgi?id=2050 won't fix]<br />
| Assumed to be present by many ssh daemons and clients such as DropBear and OpenSSH.<br />
|-<br />
| [https://www.palemoon.org/ palemoon]<br />
| {{ic|~/.moonchild productions}}<br />
| [https://forum.palemoon.org/viewtopic.php?f=5&t=9639]<br />
|<br />
|-<br />
| {{AUR|parsec-bin}}<br />
| {{ic|~/.parsec}}<br />
|<br />
|<br />
|-<br />
| {{AUR|pcsxr}}<br />
| {{ic|~/.pcsxr}}<br />
|<br />
| A {{ic|-cfg}} flag exists, but can only be set relative to {{ic|~/.pcsxr}}.<br />
|-<br />
| [https://perf.wiki.kernel.org/index.php/Main_Page perf]<br />
| {{ic|~/.debug}}<br />
|<br />
| Hardcoded in [https://github.com/torvalds/linux/blob/master/tools/perf/util/config.c#L29 tools/perf/util/config.c:29].<br />
|-<br />
| [[perl]]<br />
| {{ic|~/.cpan}}<br />
|<br />
| Perl5's [https://github.com/andk/cpanpm CPAN] expects {{ic|~/.cpan}}.<br />
|-<br />
| various [[shell]]s and [[display manager]]s<br />
| {{ic|~/.profile}}<br />
|<br />
|<br />
|-<br />
| [[python]]<br />
| {{ic|~/.python_history}}<br />
|<br />
| All history from interactive sessions is saved to {{ic|~/.python_history}} by default since [https://bugs.python.org/issue5845 version 3.4], custom path can still be set the same way as in older versions (see [https://docs.python.org/3/library/readline.html?highlight=readline#example this example]).<br />
|-<br />
| {{Pkg|python-poetry}}<br />
| {{ic|~/.poetry}}<br />
| [https://github.com/python-poetry/poetry/issues/2148]<br />
| {{ic|POETRY_HOME}} can be used but it does not separate data and config.<br />
|-<br />
| [https://doc.qt.io/qt-5/qtdesigner-manual.html Qt Designer]<br />
| {{ic|~/.designer}}<br />
|<br />
|<br />
|-<br />
| [http://rednotebook.sourceforge.net/ RedNotebook]<br />
| {{ic|~/.rednotebook}}<br />
|<br />
|<br />
|-<br />
| [https://remarkableapp.github.io/linux.html Remarkable]<br />
| {{ic|~/.remarkable}}<br />
|<br />
|<br />
|-<br />
| [https://www.renpy.org/ Ren'Py]<br />
| {{ic|~/.renpy}}<br />
| [https://github.com/renpy/renpy/issues/1377#issuecomment-370118555 won't fix]<br />
|<br />
|-<br />
| [[SANE]]<br />
| {{ic|~/.sane/}}<br />
|<br />
| {{ic|scanimage}} creates a {{ic|.cal}} file there<br />
|-<br />
| {{Pkg|scribus}}<br />
| {{ic|~/.scribus}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|sdcv}}<br />
| {{ic|~/.stardict/}}<br />
| [https://github.com/Dushistov/sdcv/issues/51]<br />
| Only workaround is modifying {{ic|HOME}}<br />
|-<br />
| [http://www.seamonkey-project.org/ SeaMonkey]<br />
| {{ic|~/.mozilla/}}<br />
| [https://bugzil.la/726939]<br />
|<br />
|-<br />
| {{Pkg|simplescreenrecorder}}<br />
| {{ic|~/.ssr/}}<br />
| [https://github.com/MaartenBaert/ssr/issues/407]<br />
| Author seems against this feature.<br />
|-<br />
| [https://www.gnu.org/software/solfege/solfege.html Solfege]<br />
|<br />
{{ic|~/.solfege<br><br />
~/.solfegerc<br><br />
~/lessonfiles}}<br />
| [https://savannah.gnu.org/bugs/index.php?50251]<br />
|<br />
|-<br />
| [https://spacemacs.org/ spacemacs]<br />
|<br />
{{ic|~/.spacemacs<br><br />
~/.spacemacs.d}}<br />
| [https://github.com/syl20bnr/spacemacs/issues/3589]<br />
|<br />
|-<br />
| [https://spamassassin.apache.org/ SpamAssassin]<br />
| {{ic|~/.spamassassin}}<br />
|<br />
|<br />
|-<br />
| [[spectrwm]]<br />
| {{ic|~/.spectrwm}}<br />
|<br />
|<br />
|-<br />
| [[SQLite]]<br />
|<br />
{{ic|~/.sqlite_history<br><br />
~/.sqliterc}}<br />
| [https://www.sqlite.org/src/info/696e82f7c82d1720]<br />
| {{ic|1=$ export SQLITE_HISTORY=$XDG_DATA_HOME/sqlite_history<br><br />
$ sqlite3 -init "$XDG_CONFIG_HOME"/sqlite3/sqliterc}}<br />
|-<br />
| [[Steam]]<br />
|<br />
{{ic|~/.steam<br><br />
~/.steampath<br><br />
~/.steampid}}<br />
| [https://github.com/ValveSoftware/steam-for-linux/issues/1890]<br />
| Many game engines (Unity 3D, Unreal) follow the specification, but then individual game publishers hardcode the paths in [https://www.ctrl.blog/entry/flatpak-steamcloud-xdg Steam Auto-Cloud] causing game-saves to sync to the wrong directory.<br />
|-<br />
| [[TeamSpeak]]<br />
| {{ic|~/.ts3client}}<br />
|<br />
|<br />
|-<br />
| {{pkg|texinfo}}<br />
| {{ic|~/.infokey}}<br />
|<br />
| {{ic|$ info --init-file "$XDG_CONFIG_HOME/infokey"}}<br />
|-<br />
| [http://www.texmacs.org/ TeXmacs]<br />
| {{ic|~/.TeXmacs}}<br />
|<br />
|<br />
|-<br />
| [[Thunderbird]]<br />
| {{ic|~/.thunderbird/}}<br />
| [https://bugzil.la/735285]<br />
|<br />
|-<br />
| [https://git.archlinux.org/users/remy/texlive-localmanager.git/ tllocalmgr]<br />
| {{ic|~/.texlive}}<br />
|<br />
|<br />
|-<br />
| {{AUR|vale}}<br />
| {{ic|~/.vale.ini}}<br />
| [https://github.com/errata-ai/vale/issues/152 won't fix]<br />
| {{ic|$ vale --config "$XDG_CONFIG_HOME/vale/config.ini"}}<br />
|-<br />
| [[vim]]<br />
|<br />
{{ic|~/.vim<br><br />
~/.vimrc<br><br />
~/.viminfo}}<br />
| [https://github.com/vim/vim/issues/2034]<br />
| Since [https://github.com/vim/vim/commit/6a459902592e2a4ba68 7.3.1178] vim will search for {{ic|~/.vim/vimrc}} if {{ic|~/.vimrc}} is not found.<br />
<br />
{{ic|1=<nowiki>$ mkdir -p "$XDG_DATA_HOME"/vim/{undo,swap,backup}</nowiki>}}<br />
<br />
{{hc|"$XDG_CONFIG_HOME"/vim/vimrc|<br />
set undodir&#61;$XDG_DATA_HOME/vim/undo<br />
set directory&#61;$XDG_DATA_HOME/vim/swap<br />
set backupdir&#61;$XDG_DATA_HOME/vim/backup<br />
set viewdir&#61;$XDG_DATA_HOME/vim/view<br />
set viminfo+&#61;'1000,n$XDG_DATA_HOME/vim/viminfo<br />
set runtimepath&#61;$XDG_CONFIG_HOME/vim,$VIMRUNTIME,$XDG_CONFIG_HOME/vim/after<br />
}}<br />
<br />
{{hc|~/.profile|<br />
export VIMINIT&#61;":source $XDG_CONFIG_HOME"/vim/vimrc<br />
}}<br />
<br />
* https://tlvince.com/vim-respect-xdg<br />
|-<br />
| [http://www.vimperator.org/ vimperator]<br />
| {{ic|~/.vimperatorrc}}<br />
| [http://www.mozdev.org/pipermail/vimperator/2009-October/004848.html]<br />
| {{ic|1=$ export VIMPERATOR_INIT=":source $XDG_CONFIG_HOME/vimperator/vimperatorrc"}}<br />
<br />
{{ic|1=$ export VIMPERATOR_RUNTIME="$XDG_CONFIG_HOME"/vimperator}}<br />
|-<br />
| {{Pkg|w3m}}<br />
| {{ic|~/.w3m}}<br />
| [https://sourceforge.net/p/w3m/feature-requests/31/]<br />
|<br />
|-<br />
| [https://w1.fi/ wpa_cli]<br />
| {{ic|~/.wpa_cli_history}}<br />
|<br />
|<br />
|-<br />
| {{Pkg|xdg-utils}}<br />
| {{ic|~/.gnome}}<br />
| [https://bugs.freedesktop.org/show_bug.cgi?id=90775]<br />
| For some reason the script {{ic|xdg-desktop-menu}} hard-codes {{ic|gnome_user_dir&#61;"$HOME/.gnome/apps"}}. This is used by [[chromium]] among others.<br />
|-<br />
| [https://opensource.conformal.com/wiki/xombrero xombrero]{{Dead link|2020|02|26}}<br />
| {{ic|~/.xombrero}}<br />
| [https://github.com/conformal/xombrero/issues/74]{{Dead link|2020|02|26}}<br />
|<br />
|-<br />
| {{Pkg|xournalpp}}<br />
| {{ic|~/.xournalpp}}<br />
| [https://github.com/xournalpp/xournalpp/issues/1101]<br />
|<br />
|-<br />
| {{Pkg|xpdf}}<br />
| {{ic|~/.xpdfrc}}<br />
| <br />
|<br />
|-<br />
| [https://yardoc.org YARD]<br />
| {{ic|~/.yard}}<br />
| [https://github.com/lsegal/yard/issues/1230]<br />
| Would accept Pull Request if anyone want to implement it.<br />
|-<br />
| [https://nmap.org/zenmap/ zenmap] {{Pkg|nmap}}<br />
| {{ic|~/.zenmap}}<br />
| [http://seclists.org/nmap-dev/2012/q2/163] [https://github.com/nmap/nmap/issues/590]<br />
|<br />
|-<br />
| [[zsh]]<br />
|<br />
{{ic|~/.zshrc<br><br />
~/.zprofile<br><br />
~/.zshenv<br><br />
~/.zlogin<br><br />
~/.zlogout<br><br />
~/.histfile<br><br />
~/.zcompdump}}<br />
| [http://www.zsh.org/mla/workers/2013/msg00692.html]<br />
| Consider exporting {{ic|1=ZDOTDIR=$HOME/.config/zsh}} in {{ic|~/.zshenv}} (this is hardcoded due to the bootstrap problem). You could also add this to {{ic|/etc/zsh/zshenv}} and avoid the need for any dotfiles in your {{ic|HOME}}. Doing this however requires root privilege which may not be viable and is system-wide.<br />
<br />
{{ic|1=$ export HISTFILE="$XDG_DATA_HOME"/zsh/history}}<br />
<br />
{{ic| $ compinit -d $XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION}} [https://unix.stackexchange.com/questions/391641/separate-path-for-zcompdump-files] /!\ The folder needs to exist<br />
<br />
|}<br />
<br />
== Libraries ==<br />
<br />
; C<br />
: [https://github.com/Cloudef/chck/tree/master/chck/xdg C99: Cloudef's simple implementation].<br />
<br />
; JVM: Java, Kotlin, Clojure, Scala, ...<br />
: [https://github.com/soc/directories-jvm directories-jvm]<br />
<br />
; Go<br />
: [https://github.com/ProtonMail/go-appdir go-appdir]<br />
<br />
; Haskell<br />
: Officially in [https://hackage.haskell.org/package/directory directory] since 1.2.3.0 [https://github.com/haskell/directory/commit/ab9d0810ce ab9d0810ce].<br />
: [https://hackage.haskell.org/package/xdg-basedir xdg-basedir]<br />
<br />
; Perl<br />
: [http://search.cpan.org/dist/File-BaseDir/lib/File/BaseDir.pm File-BaseDir]<br />
: [https://github.com/Aerdan/perl-file-xdg perl-file-xdg]{{Dead link|2020|02|26}}<br />
<br />
; Ruby<br />
: [https://github.com/rubyworks/xdg rubyworks/xdg]<br />
<br />
; Rust<br />
: [https://github.com/soc/directories-rs directories-rs]<br />
: [https://github.com/whitequark/rust-xdg rust-xdg]<br />
<br />
; Python<br />
: [https://freedesktop.org/wiki/Software/pyxdg/ pyxdg]<br />
<br />
; Vala<br />
: Builtin support via [http://valadoc.org/#!api=glib-2.0/GLib.Environment GLib.Environment].<br />
: See {{ic|get_user_cache_dir}}, {{ic|get_user_data_dir}}, {{ic|get_user_config_dir}}, etc.<br />
<br />
==See also==<br />
<br />
* [https://wiki.gnome.org/Initiatives/GnomeGoals/XDGConfigFolders GNOME Goal: XDG Base Directory Specification Usage]<br />
* [https://web.archive.org/web/20180827160401/plus.google.com/+RobPikeTheHuman/posts/R58WgWwN9jp Rob Pike: "Dotfiles" being hidden is a UNIXv2 mistake].<br />
* {{man|1|systemd-path}}<br />
* {{man|7|file-hierarchy}}<br />
* [https://github.com/grawity/dotfiles/blob/master/.dotfiles.notes Grawity's notes on dotfiles].<br />
* [https://github.com/grawity/dotfiles/blob/master/.environ.notes Grawity's notes on environment variables].<br />
* [https://ploum.net/207-modify-your-application-to-use-xdg-folders/ ploum.net: Modify Your Application to use XDG Folders].<br />
* The [https://pcgamingwiki.com/wiki/Home PCGamingWiki] attempts to document whether or not Linux PC games follow the XDG Base Directory Specification.</div>Simon04https://wiki.archlinux.org/index.php?title=Node.js_package_guidelines&diff=602316Node.js package guidelines2020-03-22T07:12:54Z<p>Simon04: fix trailing whitespace</p>
<hr />
<div>[[Category:Arch package guidelines]]<br />
[[ja:Node.js パッケージガイドライン]]<br />
[[pt:Node.js package guidelines]]<br />
{{Package guidelines}}<br />
<br />
This document covers standards and guidelines on writing [[PKGBUILD]]s for [[Node.js]] packages.<br />
<br />
== Package naming ==<br />
<br />
Package names for Node.js libraries should start with a {{ic|nodejs-}} prefix. For standalone applications, just use the program name.<br />
<br />
== Using npm ==<br />
<br />
When installing with {{Pkg|npm}}, add it as a build dependency:<br />
<br />
makedepends=('npm')<br />
<br />
There is also usually no need to extract the tarball:<br />
<br />
noextract=("${pkgname}-${pkgver}.tgz")<br />
<br />
This is a minimal {{ic|package}} function:<br />
<br />
{{bc|<nowiki><br />
package() {<br />
npm install -g --user root --prefix "${pkgdir}/usr" "${srcdir}/${pkgname}-${pkgver}.tgz"<br />
<br />
# Non-deterministic race in npm gives 777 permissions to random directories.<br />
# See https://github.com/npm/npm/issues/9359 for details.<br />
find "${pkgdir}/usr" -type d -exec chmod 755 {} +<br />
<br />
# npm gives ownership of ALL FILES to build user<br />
# https://bugs.archlinux.org/task/63396<br />
chown -R root:root "${pkgdir}"<br />
}<br />
</nowiki>}}<br />
<br />
=== Setting temporary cache ===<br />
<br />
When npm processes {{ic|package.json}} in order to build a package it downloads dependencies to its default cache folder at {{ic|$HOME/.npm}}. To avoid littering user's home folder we can temporarily set a different cache folder with {{ic|--cache}} flag:<br />
<br />
Download dependencies to {{ic|${srcdir}/npm-cache}} and install them in package directory<br />
<br />
npm install --cache "${srcdir}/npm-cache" <br />
<br />
Continue with packaging as usual<br />
<br />
npm run packager<br />
<br />
=== Package contains reference to $srcdir/$pkgdir ===<br />
<br />
npm unfortunately creates references to the source dir and the pkg dir. This is [https://github.com/npm/npm/issues/12110 a known issue in NPM], and actually considered a feature. However, you may remove those references manually since they are not used in any way.<br />
<br />
All dependencies will contain a reference to {{ic|$pkgdir}}, in the {{ic|_where}} attribute. You can usually remove those attributes with some ''sed'' magic as follows:<br />
<br />
find "$pkgdir" -name package.json -print0 | xargs -r -0 sed -i '/_where/d'<br />
<br />
Your main package will have some other references too. The easiest way to remove those is to remove all underscored properties, but that is not as easy with ''sed''. Instead, you can use {{Pkg|jq}} for similar results as follows:<br />
<br />
{{bc|<nowiki><br />
local tmppackage="$(mktemp)"<br />
local pkgjson="$pkgdir/usr/lib/node_modules/$pkgname/package.json"<br />
jq '.|=with_entries(select(.key|test("_.+")|not))' "$pkgjson" > "$tmppackage"<br />
mv "$tmppackage" "$pkgjson"<br />
chmod 644 "$pkgjson"<br />
</nowiki>}}<br />
<br />
An example of both techniques can be seen in {{AUR|bower-away}}.</div>Simon04https://wiki.archlinux.org/index.php?title=WireGuard&diff=600809WireGuard2020-03-09T08:26:41Z<p>Simon04: /* Testing the tunnel */ netcat</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPSec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it plans to be cross-platform and widely deployable.<br />
<br />
{{Warning|WireGuard has not undergone proper degrees of security auditing and the protocol is still subject to change [https://www.wireguard.com/#work-in-progress].}}<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|wireguard-tools}} and one or more of the appropriate kernel module:<br />
* {{Pkg|wireguard-arch}} for the default {{Pkg|linux}} kernel.<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other [[kernel]]s.<br />
<br />
{{Note|1=WireGuard has been merged in Linux 5.6. [https://lists.zx2c4.com/pipermail/wireguard/2020-January/004906.html]}}<br />
<br />
{{Tip|[[systemd-networkd]] and [[NetworkManager]] both have native support for setting up WireGuard interfaces, they only require the kernel module.<br />
<br />
* For details on systemd-networkd, see [[#Using systemd-networkd]].<br />
* For NetworkManager, read the [https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager blog post].<br />
}}<br />
<br />
== Usage ==<br />
<br />
The below commands demonstrate how to setup a basic tunnel between two peers with the following settings:<br />
<br />
{{Expansion|Add Peer C to better demonstrate routing and PSK, and add IPv6.}}<br />
<br />
{| class="wikitable"<br />
! <br />
! Peer A<br />
! Peer B<br />
|-<br />
! External IP address<br />
| 198.51.100.101<br />
| 203.0.113.102<br />
|-<br />
! Internal IP address<br />
| 10.0.0.1/24<br />
| 10.0.0.2/24<br />
|-<br />
! WireGuard listening port<br />
| UDP/51871<br />
| UDP/51902<br />
|}<br />
<br />
The external addresses should already exist. For example, peer A should be able to ping peer B via {{ic|ping 203.0.113.102}}, and vice versa. The internal addresses will be new addresses created by the {{man|8|ip}} commands below and will be shared internally within the new WireGuard network using {{man|8|wg}}. The {{ic|/24}} in the IP addresses is the [[wikipedia:Classless_Inter-Domain_Routing#CIDR_notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
To create a ''private key'':<br />
<br />
$ umask 077<br />
$ wg genkey > privatekey<br />
<br />
To create a ''public key'':<br />
<br />
$ wg pubkey < privatekey > publickey<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ umask 077; wg genkey | tee privatekey | wg pubkey > publickey<br />
<br />
One can also generate a preshared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance.<br />
<br />
{{Expansion|A pre-shared key should be created for each peer pair. E.g. with peers A, B and C, there should be three pre-shared keys, {{ic|peer_A-peer_B-psk}} for the connection between Peer A and Peer B, {{ic|peer_A-peer_C-psk}} for the connection between Peer A and Peer C and {{ic|peer_B-peer_C-psk}} for the connection between Peer B and Peer C.}}<br />
<br />
# wg genpsk > preshared<br />
<br />
=== Peer A setup ===<br />
<br />
This peer will listen on UDP port 51871 and will accept connection from peer B by linking its public key with both its inner and outer IPs addresses.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ./privatekey<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' persistent-keepalive 25 allowed-ips 10.0.0.2/32 endpoint 203.0.113.102:51902<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_B_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}. The keyword {{ic|allowed-ips}} is a list of addresses that peer A will be able to send traffic to; {{ic|allowed-ips 0.0.0.0/0}} would allow sending traffic to any IPv4 address, {{ic|::/0}} allows sending traffic to any IPv6 address.<br />
<br />
=== Peer B setup ===<br />
<br />
As with peer A, whereas the wireguard daemon is listening on the UDP port 51902 and accept connection from peer A only.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ./privatekey<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' persistent-keepalive 25 allowed-ips 10.0.0.1/32 endpoint 198.51.100.101:51871<br />
# ip link set wg0 up<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameter will give a quick overview of the current configuration.<br />
<br />
As an example, when Peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32<br />
}}<br />
<br />
At this point one could reach the end of the tunnel:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
=== Persistent configuration ===<br />
<br />
The configuration can be saved by utilizing {{ic|showconf}}:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
# wg setconf wg0 /etc/wireguard/wg0.conf<br />
<br />
=== Example peer configuration ===<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
PrivateKey = ''CLIENT_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
AllowedIPs = 10.0.0.0/24, 10.123.45.0/24, 1234:4567:89ab::/48<br />
Endpoint = ''SERVER_ENDPOINT'':51871<br />
PersistentKeepalive = 25<br />
}}<br />
<br />
=== Example configuration for systemd-networkd ===<br />
<br />
See [[#Using systemd-networkd]].<br />
<br />
== Specific use-case: VPN server ==<br />
{{Note|Usage of the terms "server" and "client" are used here specifically for newcomers to WireGuard and for current users of OpenVPN to help familiarize with the construction of configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The server runs on Linux and the clients can run any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may want to use [[#Using systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server have the public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# note - substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receive traffic via NAT, this iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} have mask "/24" and the clients on {{ic|AllowedIPs}} "/32". The client only use their IP and the server only send back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
Endpoint = my.ddns.example.com:51820<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/24<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
Endpoint = my.ddns.example.com:51820<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use [[netcat]] to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}} <br />
<br />
== Tips and tricks ==<br />
<br />
=== Using systemd-networkd ===<br />
<br />
[[systemd-networkd]] has native support for WireGuard protocols and therefore does not require the {{Pkg|wireguard-tools}} package.<br />
<br />
In order to prevent leak of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
==== Server ====<br />
<br />
{{hc|/etc/systemd/network/99-server.netdev|2=<br />
[NetDev]<br />
Name = wg0<br />
Kind = wireguard<br />
Description = WireGuard<br />
<br />
[WireGuard]<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey = PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[WireGuardPeer]<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-server.network|2=<br />
[Match]<br />
Name = wg0<br />
<br />
[Network]<br />
Address = 10.200.200.1/32<br />
<br />
[Route]<br />
Gateway = 10.200.200.1<br />
Destination = 10.200.200.0/24<br />
}}<br />
<br />
==== Client foo ====<br />
<br />
{{hc|/etc/systemd/network/99-client.netdev|2=<br />
[NetDev]<br />
Name = wg0<br />
Kind = wireguard<br />
Description = WireGuard<br />
<br />
[WireGuard]<br />
PrivateKey = ''FOO_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.0.0/24<br />
Endpoint = my.ddns.example.com:51820<br />
PersistentKeepalive = 25<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-client.network|2=<br />
[Match]<br />
Name = wg0<br />
<br />
[Network]<br />
Address = 10.200.200.2/32<br />
<br />
[Route]<br />
Gateway = 10.200.200.1<br />
Destination = 10.200.200.0/24<br />
GatewayOnlink=true<br />
}}<br />
<br />
==== Client bar ====<br />
<br />
{{hc|/etc/systemd/network/99-client.netdev|2=<br />
[NetDev]<br />
Name = wg0<br />
Kind = wireguard<br />
Description = WireGuard<br />
<br />
[WireGuard]<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.0.0/24<br />
Endpoint = my.ddns.example.com:51820<br />
PersistentKeepalive = 25<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-client.network|2=<br />
[Match]<br />
Name = wg0<br />
<br />
[Network]<br />
Address = 10.200.200.3/32<br />
<br />
[Route]<br />
Gateway = 10.200.200.1<br />
Destination = 10.200.200.0/24<br />
GatewayOnLink=true<br />
}}<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, ..., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 < client.conf<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Simon04https://wiki.archlinux.org/index.php?title=WireGuard&diff=600808WireGuard2020-03-09T08:06:57Z<p>Simon04: /* Key generation */ umask 077 (according to official docs, to avoid warning)</p>
<hr />
<div>[[Category:Virtual Private Network]]<br />
[[ja:WireGuard]]<br />
[[zh-hans:WireGuard]]<br />
From the [https://www.wireguard.com/ WireGuard] project homepage: <br />
:WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It aims to be faster, simpler, leaner, and more useful than IPSec, while avoiding the massive headache. It intends to be considerably more performant than OpenVPN. WireGuard is designed as a general purpose VPN for running on embedded interfaces and super computers alike, fit for many different circumstances. Initially released for the Linux kernel, it plans to be cross-platform and widely deployable.<br />
<br />
{{Warning|WireGuard has not undergone proper degrees of security auditing and the protocol is still subject to change [https://www.wireguard.com/#work-in-progress].}}<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|wireguard-tools}} and one or more of the appropriate kernel module:<br />
* {{Pkg|wireguard-arch}} for the default {{Pkg|linux}} kernel.<br />
* {{Pkg|wireguard-lts}} for the LTS {{Pkg|linux-lts}} kernel.<br />
* {{Pkg|wireguard-dkms}} for the DKMS variant for other [[kernel]]s.<br />
<br />
{{Note|1=WireGuard has been merged in Linux 5.6. [https://lists.zx2c4.com/pipermail/wireguard/2020-January/004906.html]}}<br />
<br />
{{Tip|[[systemd-networkd]] and [[NetworkManager]] both have native support for setting up WireGuard interfaces, they only require the kernel module.<br />
<br />
* For details on systemd-networkd, see [[#Using systemd-networkd]].<br />
* For NetworkManager, read the [https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager blog post].<br />
}}<br />
<br />
== Usage ==<br />
<br />
The below commands demonstrate how to setup a basic tunnel between two peers with the following settings:<br />
<br />
{{Expansion|Add Peer C to better demonstrate routing and PSK, and add IPv6.}}<br />
<br />
{| class="wikitable"<br />
! <br />
! Peer A<br />
! Peer B<br />
|-<br />
! External IP address<br />
| 198.51.100.101<br />
| 203.0.113.102<br />
|-<br />
! Internal IP address<br />
| 10.0.0.1/24<br />
| 10.0.0.2/24<br />
|-<br />
! WireGuard listening port<br />
| UDP/51871<br />
| UDP/51902<br />
|}<br />
<br />
The external addresses should already exist. For example, peer A should be able to ping peer B via {{ic|ping 203.0.113.102}}, and vice versa. The internal addresses will be new addresses created by the {{man|8|ip}} commands below and will be shared internally within the new WireGuard network using {{man|8|wg}}. The {{ic|/24}} in the IP addresses is the [[wikipedia:Classless_Inter-Domain_Routing#CIDR_notation|CIDR]].<br />
<br />
=== Key generation ===<br />
<br />
To create a ''private key'':<br />
<br />
$ umask 077<br />
$ wg genkey > privatekey<br />
<br />
To create a ''public key'':<br />
<br />
$ wg pubkey < privatekey > publickey<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ umask 077; wg genkey | tee privatekey | wg pubkey > publickey<br />
<br />
One can also generate a preshared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance.<br />
<br />
{{Expansion|A pre-shared key should be created for each peer pair. E.g. with peers A, B and C, there should be three pre-shared keys, {{ic|peer_A-peer_B-psk}} for the connection between Peer A and Peer B, {{ic|peer_A-peer_C-psk}} for the connection between Peer A and Peer C and {{ic|peer_B-peer_C-psk}} for the connection between Peer B and Peer C.}}<br />
<br />
# wg genpsk > preshared<br />
<br />
=== Peer A setup ===<br />
<br />
This peer will listen on UDP port 51871 and will accept connection from peer B by linking its public key with both its inner and outer IPs addresses.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ./privatekey<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' persistent-keepalive 25 allowed-ips 10.0.0.2/32 endpoint 203.0.113.102:51902<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_B_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}. The keyword {{ic|allowed-ips}} is a list of addresses that peer A will be able to send traffic to; {{ic|allowed-ips 0.0.0.0/0}} would allow sending traffic to any IPv4 address, {{ic|::/0}} allows sending traffic to any IPv6 address.<br />
<br />
=== Peer B setup ===<br />
<br />
As with peer A, whereas the wireguard daemon is listening on the UDP port 51902 and accept connection from peer A only.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ./privatekey<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' persistent-keepalive 25 allowed-ips 10.0.0.1/32 endpoint 198.51.100.101:51871<br />
# ip link set wg0 up<br />
<br />
=== Basic checkups ===<br />
<br />
Invoking the {{man|8|wg}} command without parameter will give a quick overview of the current configuration.<br />
<br />
As an example, when Peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32<br />
}}<br />
<br />
At this point one could reach the end of the tunnel:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
=== Persistent configuration ===<br />
<br />
The configuration can be saved by utilizing {{ic|showconf}}:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
# wg setconf wg0 /etc/wireguard/wg0.conf<br />
<br />
=== Example peer configuration ===<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
PrivateKey = ''CLIENT_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
AllowedIPs = 10.0.0.0/24, 10.123.45.0/24, 1234:4567:89ab::/48<br />
Endpoint = ''SERVER_ENDPOINT'':51871<br />
PersistentKeepalive = 25<br />
}}<br />
<br />
=== Example configuration for systemd-networkd ===<br />
<br />
See [[#Using systemd-networkd]].<br />
<br />
== Specific use-case: VPN server ==<br />
{{Note|Usage of the terms "server" and "client" are used here specifically for newcomers to WireGuard and for current users of OpenVPN to help familiarize with the construction of configuration files. WireGuard documentation simply refers to both of these concepts as "peers."}}<br />
<br />
The purpose of this section is to setup a WireGuard "server" and generic "clients" to enable access to the server/network resources through an encrypted and secured tunnel like [[OpenVPN]] and others. The server runs on Linux and the clients can run any number of platforms (the WireGuard Project offers apps on both iOS and Android platforms in addition to Linux, Windows and MacOS). See the official project [https://www.wireguard.com/install/ install link] for more.<br />
<br />
{{Tip|Instead of using {{pkg|wireguard-tools}} for server/client configuration, one may want to use [[#Using systemd-networkd|systemd-networkd]] native WireGuard support.}}<br />
<br />
=== Server ===<br />
<br />
On the peer that will act as the "server", first enable IPv4 forwarding using [[sysctl]]:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, add {{ic|1=net.ipv4.ip_forward = 1}} to {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
A properly configured [[firewall]] is ''HIGHLY recommended'' for any Internet-facing device.<br />
<br />
If the server have the public IP configured, be sure to:<br />
<br />
* Allow UDP traffic on the specified port(s) on which WireGuard will be running (for example allowing traffic on 51820/udp).<br />
* Setup the forwarding policy for the firewall if it is not included in the WireGuard config for the interface itself {{ic|/etc/wireguard/wg0.conf}}. The example below should have the iptables rules and work as-is.<br />
<br />
If the server is behind NAT, be sure to forward the specified port(s) on which WireGuard will be running (for example, 51820/UDP) from the router to the WireGuard server.<br />
<br />
=== Key generation ===<br />
<br />
Generate key pairs for the server and for each client as explained in [[#Key generation]].<br />
<br />
=== Server config ===<br />
<br />
Create the "server" config file:<br />
<br />
{{hc|/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.200.200.1/24<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
# note - substitute ''eth0'' in the following lines to match the Internet-facing interface<br />
# if the server is behind a router and receive traffic via NAT, this iptables rules are not needed<br />
PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE<br />
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE<br />
<br />
[Peer]<br />
# foo<br />
PublicKey = ''PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[Peer]<br />
# bar<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
Additional peers ("clients") can be listed in the same format as needed. Each peer requires the {{ic|PublicKey}} to be set. However, specifying {{ic|PresharedKey}} is optional.<br />
<br />
Notice that the {{ic|Address}} have mask "/24" and the clients on {{ic|AllowedIPs}} "/32". The client only use their IP and the server only send back their respective address.<br />
<br />
The interface can be managed manually using {{man|8|wg-quick}} or using a [[systemd]] service managed via {{man|1|systemctl}}.<br />
<br />
The interface may be brought up using {{ic|wg-quick up wg0}} respectively by [[start|starting]] and potentially [[enable|enabling]] the interface via {{ic|wg-quick@''interface''.service}}, e.g. {{ic|wg-quick@wg0.service}}. To close the interface use {{ic|wg-quick down wg0}} respectively [[stop]] {{ic|wg-quick@''interface''.service}}.<br />
<br />
=== Client config ===<br />
<br />
Create the corresponding "client" config file(s):<br />
<br />
{{hc|foo.conf|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
Endpoint = my.ddns.example.com:51820<br />
}}<br />
<br />
{{hc|bar.conf|2=<br />
[Interface]<br />
Address = 10.200.200.3/24<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
<br />
[Peer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED KEY''<br />
AllowedIPs = 0.0.0.0/0, ::/0<br />
Endpoint = my.ddns.example.com:51820<br />
}}<br />
<br />
Using the catch-all {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}} will forward all IPv4 ({{ic|0.0.0.0/0}}) and IPv6 ({{ic|::/0}}) traffic over the VPN.<br />
<br />
{{Note|Users of [[NetworkManager]], may need to [[enable]] the {{ic|NetworkManager-wait-online.service}} and users of [[systemd-networkd]] may need to [[enable]] the {{ic|systemd-networkd-wait-online.service}} to wait until devices are network ready before attempting wireguard connection.}}<br />
<br />
== Testing the tunnel ==<br />
<br />
Once a tunnel has been established, one can use {{Pkg|gnu-netcat}} to send traffic through it to test out throughput, CPU usage, etc.<br />
On one side of the tunnel, run {{ic|nc}} in listen mode and on the other side, pipe some data from {{ic|/dev/zero}} into {{ic|nc}} in sending mode.<br />
<br />
In the example below, port 2222 is used for the traffic (be sure to allow traffic on port 2222 if using a firewall).<br />
<br />
On one side of the tunnel listen for traffic:<br />
<br />
$ nc -vvlnp 2222<br />
<br />
On the other side of the tunnel, send some traffic:<br />
<br />
$ dd if=/dev/zero bs=1024K count=1024 | nc -v 10.0.0.203 2222<br />
<br />
Status can be monitored using {{ic|wg}} directly.<br />
<br />
{{hc|# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51820<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
preshared key: (hidden)<br />
endpoint: 192.168.1.216:53207<br />
allowed ips: 10.0.0.0/0<br />
latest handshake: 1 minutes, 17 seconds ago<br />
transfer: 56.43 GiB received, 1.06 TiB sent<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Routes are periodically reset ===<br />
<br />
Users of [[NetworkManager]] should make sure that it [[NetworkManager#Ignore specific devices|is not managing]] the WireGuard interface(s). For example, create the following configuration file:<br />
<br />
{{hc|/etc/NetworkManager/conf.d/unmanaged.conf|2=<br />
[keyfile]<br />
unmanaged-devices=interface-name:wg*<br />
}}<br />
<br />
=== Broken DNS resolution ===<br />
<br />
When tunneling all traffic through a WireGuard interface, the connection can become seemingly lost after a while or upon new connection. This could be caused by a [[network manager]] or [[DHCP]] client overwriting {{ic|/etc/resolv.conf}}.<br />
<br />
By default ''wg-quick'' uses ''resolvconf'' to register new [[DNS]] entries (from the {{ic|DNS}} keyword in the configuration file). This will cause issues with [[network manager]]s and [[DHCP]] clients that do not use ''resolvconf'', as they will overwrite {{ic|/etc/resolv.conf}} thus removing the DNS servers added by wg-quick.<br />
<br />
The solution is to use networking software that supports [[resolvconf]].<br />
<br />
{{Note|Users of [[systemd-resolved]] should make sure that {{Pkg|systemd-resolvconf}} is [[install]]ed.}}<br />
<br />
Users of [[NetworkManager]] should know that it does not use resolvconf by default. It is recommended to use [[systemd-resolved]]. If this is undesirable, [[install]] {{Pkg|openresolv}} and configure NetworkManager to use it: [[NetworkManager#Use openresolv]].<br />
<br />
=== Low MTU ===<br />
<br />
Due to too low MTU (lower than 1280), wg-quick may have failed to create the WireGuard interface. This can be solved by setting the MTU value in WireGuard configuration in Interface section on client.<br />
{{hc|/foo.config|2=<br />
[Interface]<br />
Address = 10.200.200.2/24<br />
MTU = 1500<br />
PrivateKey = ''PEER_FOO_PRIVATE_KEY''<br />
DNS = 10.200.200.1<br />
}} <br />
<br />
== Tips and tricks ==<br />
<br />
=== Using systemd-networkd ===<br />
<br />
[[systemd-networkd]] has native support for WireGuard protocols and therefore does not require the {{Pkg|wireguard-tools}} package.<br />
<br />
In order to prevent leak of private keys, it is recommended to set the permissions of the ''.netdev'' file:<br />
<br />
# chown root:systemd-network /etc/systemd/network/99-*.netdev<br />
# chmod 0640 /etc/systemd/network/99-*.netdev<br />
<br />
==== Server ====<br />
<br />
{{hc|/etc/systemd/network/99-server.netdev|2=<br />
[NetDev]<br />
Name = wg0<br />
Kind = wireguard<br />
Description = WireGuard<br />
<br />
[WireGuard]<br />
ListenPort = 51820<br />
PrivateKey = ''SERVER_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey = PEER_FOO_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.2/32<br />
<br />
[WireGuardPeer]<br />
PublicKey = ''PEER_BAR_PUBLIC_KEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.200.3/32<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-server.network|2=<br />
[Match]<br />
Name = wg0<br />
<br />
[Network]<br />
Address = 10.200.200.1/32<br />
<br />
[Route]<br />
Gateway = 10.200.200.1<br />
Destination = 10.200.200.0/24<br />
}}<br />
<br />
==== Client foo ====<br />
<br />
{{hc|/etc/systemd/network/99-client.netdev|2=<br />
[NetDev]<br />
Name = wg0<br />
Kind = wireguard<br />
Description = WireGuard<br />
<br />
[WireGuard]<br />
PrivateKey = ''FOO_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.0.0/24<br />
Endpoint = my.ddns.example.com:51820<br />
PersistentKeepalive = 25<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-client.network|2=<br />
[Match]<br />
Name = wg0<br />
<br />
[Network]<br />
Address = 10.200.200.2/32<br />
<br />
[Route]<br />
Gateway = 10.200.200.1<br />
Destination = 10.200.200.0/24<br />
GatewayOnlink=true<br />
}}<br />
<br />
==== Client bar ====<br />
<br />
{{hc|/etc/systemd/network/99-client.netdev|2=<br />
[NetDev]<br />
Name = wg0<br />
Kind = wireguard<br />
Description = WireGuard<br />
<br />
[WireGuard]<br />
PrivateKey = ''PEER_BAR_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey = ''SERVER_PUBLICKEY''<br />
PresharedKey = ''PRE-SHARED_KEY''<br />
AllowedIPs = 10.200.0.0/24<br />
Endpoint = my.ddns.example.com:51820<br />
PersistentKeepalive = 25<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-client.network|2=<br />
[Match]<br />
Name = wg0<br />
<br />
[Network]<br />
Address = 10.200.200.3/32<br />
<br />
[Route]<br />
Gateway = 10.200.200.1<br />
Destination = 10.200.200.0/24<br />
GatewayOnLink=true<br />
}}<br />
<br />
=== Store private keys in encrypted form ===<br />
<br />
It may be desirable to store private keys in encrypted form, such as through use of {{pkg|pass}}. Just replace the PrivateKey line under [Interface] in the configuration file with:<br />
<br />
PostUp = wg set %i private-key <(su user -c "export PASSWORD_STORE_DIR=/path/to/your/store/; pass WireGuard/private-keys/%i")<br />
<br />
where ''user'' is the Linux username of interest. See the {{man|8|wg-quick}} man page for more details.<br />
<br />
=== Endpoint with changing IP ===<br />
<br />
After resolving a server's domain, WireGuard [https://lists.zx2c4.com/pipermail/wireguard/2017-November/002028.html will not check for changes in DNS again].<br />
<br />
If the WireGuard server is frequently changing its IP-address due DHCP, Dyndns, IPv6, ..., any WireGuard client is going to lose its connection, until its endpoint is updated via something like {{ic|wg set "$INTERFACE" peer "$PUBLIC_KEY" endpoint "$ENDPOINT"}}.<br />
<br />
Also be aware, if the endpoint is ever going to change its address (for example when moving to a new provider/datacenter), just updating DNS will not be enough, so periodically running reresolve-dns might make sense on any DNS-based setup.<br />
<br />
Luckily, {{Pkg|wireguard-tools}} provides an example script {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh}}, that parses WG configuration files and automatically resets the endpoint address.<br />
<br />
One needs to run the {{ic|/usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh /etc/wireguard/wg.conf}} periodically to recover from an endpoint that has changed its IP.<br />
<br />
One way of doing so is by updating all WireGuard endpoints once every thirty seconds[https://git.zx2c4.com/WireGuard/tree/contrib/examples/reresolve-dns/README] via a systemd timer:<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.timer|2=<br />
[Unit]<br />
Description=Periodically reresolve DNS of all WireGuard endpoints<br />
<br />
[Timer]<br />
OnCalendar=*:*:0/30<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
{{hc|/etc/systemd/system/wireguard_reresolve-dns.service|2=<br />
[Unit]<br />
Description=Reresolve DNS of all WireGuard endpoints<br />
Wants=network-online.target<br />
After=network-online.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/bin/sh -c 'for i in /etc/wireguard/*.conf; do /usr/share/wireguard-tools/examples/reresolve-dns/reresolve-dns.sh "$i"; done'<br />
}}<br />
<br />
Afterwards [[enable]] and [[start]] {{ic|wireguard_reresolve-dns.timer}}<br />
<br />
=== Generate QR code ===<br />
<br />
If the client is a mobile device such as a phone, {{Pkg|qrencode}} can be used to generate client's configuration QR code and display it in terminal:<br />
<br />
$ qrencode -t ansiutf8 < client.conf<br />
<br />
=== Enable debug logs ===<br />
<br />
When using the Linux kernel module on a kernel that supports dynamic debugging, debugging information can be written into the kernel ring buffer (viewable with [[dmesg]] and [[journalctl]]) by running:<br />
<br />
# modprobe wireguard <br />
# echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:WireGuard]]<br />
* [https://www.wireguard.com/presentations/ Presentations by Jason Donenfeld].<br />
* [https://lists.zx2c4.com/mailman/listinfo/wireguard Mailing list]<br />
* [https://docs.sweeting.me/s/wireguard Unofficial WireGuard Documentation]<br />
* [[Debian:Wireguard]]</div>Simon04https://wiki.archlinux.org/index.php?title=Talk:DNS_over_HTTPS&diff=598282Talk:DNS over HTTPS2020-02-21T18:19:04Z<p>Simon04: /* Structure */ re; done</p>
<hr />
<div>== Structure ==<br />
There is quite a bit more to this topic than what is on this page. Perhaps this should just be a landing page for general the general topic with links to a new page specifically for CoreDNS, and a separate Client configuration page for Firefox and Chromium. Additionally, links and page data should be added for both dns-over-https and dns-proxy. I'll get around to writing pages for both proxy implementations at some point soon -- still testing both in more complex environments. [[User:DJ L|DJ L]] ([[User talk:DJ L|talk]])<br />
:Hi [[User:DJ L]], thanks for your efforts in documenting DNS over HTTPS. I like your idea of linking to specific DNS server wiki pages (such as [[Unbound#Forwarding_using_DNS_over_TLS]]). However, I'm no fan of splitting the page [[DNS over HTTPS]] itself to various sub-pages (browser 1, …, browser n) since I find it difficult to get a total view of the existing documentation and I find myself navigating forward/backward between pages each only containing one paragraph/section. Having said that, and since the page [[DNS over HTTPS servers]] focuses on doh-proxy plus corresponding web server proxies, could you rename [[DNS over HTTPS servers]] to [[doh-proxy]] for a total documentation to implement doh-proxy? For the other servers, I'd like to keep using [[DNS over HTTPS]] for their documentation (links). Thanks! –[[User:Simon04|Simon04]] ([[User talk:Simon04|talk]]) 21:52, 6 January 2020 (UTC)<br />
<br />
::I don't see any benefit of this page compared to [[Domain name resolution]], which deals with the topic in general. There is a comprehensive table in [[Domain name resolution#DNS servers]] where users can make a very good picture of the available programs. All configuration details then belong to separate pages, which should be done even for ''cloudflared'' and ''CoreDNS'' if relevant upstream documentations are not enough (I think they are). When done, this page should be redirected to [[Domain name resolution#Privacy and security]].<br />
::As for [[DNS over HTTPS servers]], that is different because setting up web server proxies is needed. Whether the info should be kept on one page or split to multiple pages can be decided later, when there is the actual content.<br />
::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:21, 12 January 2020 (UTC)<br />
<br />
:::Sorry I haven't gotten back to this yet, got a little busy lately (car died, studying, etc.). There is definitely benefit to the existing issue IMO, the search term as well as the content, but I agree that it can fit into the existing docu. Maybe that should be done, but I do like the idea of having a redirect from the [[DNS over HTTPS]] page at very least, and there is some useful info that should be transferred (specifically the client config, and obviously the servers page). I'm really not prepared to weigh in on this other than to say that both make sense in different contexts. This will be the search term that users will use (possibly also "DoH" and "DoT"). As to the naming, I do plan to add the dns-over-https proxy, but I have reservations with the doh-proxy package (not the Python one that I packaged) because I find rust/cargo a bit too heavy for my servers (where I don't otherwise need it). Maybe I'll build a VM for it if the package author doesn't want to contribute to the wiki. If not before, I'll contact the author of the package sometime next week and see if he's interested. Just remember that the ultimate goal is to make it easy for the users, and link hopping should be considered.[[User:DJ L|DJ L]] ([[User talk:DJ L|talk]]) 20:51, 12 January 2020 (UTC)<br />
<br />
::::Most people use DNS as clients, so setting up DNS servers with any particular feature (such as encryption protocols) should be clearly separated. There is already a very good client page, [[Domain name resolution]], and I don't see reasons to have another client page specifically for DNS over HTTPS. Anyway, I've marked my concerns with various flags on these two DNS over HTTPS pages. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:56, 12 January 2020 (UTC)<br />
<br />
:::::I addressed the DoH servers page style concerns quick. That still leaves my To Do list for that page and what to do with this page. After reviewing the referenced DNS related pages, I agree with [[User:Lahwaacz|Lahwaacz]] that the client configuration section of this page deserves an extension in [[Domain name resolution#Privacy and security]]. I still haven't formed an opinion on the comment that the '''cloudflared''' and '''coreDNS''' configurations should be excluded, however. It is valuable, and quite a simple addition inline (nor do I know how valuable my opinion is in this regard :-)). The links to Wikipedia and the RFC have been added (inline) to [[Domain name resolution#Privacy and security]]. Thoughts? -- [[User:DJ L|DJ L]] ([[User talk:DJ L|talk]]) 01:46, 13 January 2020 (UTC)<br />
<br />
::::::Hi [[User:Lahwaacz|Lahwaacz]], thanks for your review and suggestions. I've moved the contents, [[Special:Diff/598277]], [[Special:Diff/598279]], and replaced the page with a redirect to [[Domain name resolution#Privacy and security]] via [[Special:Diff/598281]]. –[[User:Simon04|Simon04]] ([[User talk:Simon04|talk]]) 18:19, 21 February 2020 (UTC)</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_HTTPS&diff=598281DNS over HTTPS2020-02-21T18:14:28Z<p>Simon04: Redirect to Domain name resolution#Privacy and security as per Talk:DNS over HTTPS</p>
<hr />
<div>#REDIRECT [[Domain name resolution#Privacy and security]]</div>Simon04https://wiki.archlinux.org/index.php?title=Cloudflared&diff=598280Cloudflared2020-02-21T18:13:37Z<p>Simon04: Category:Domain Name System</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/ Cloudflared] may be used to run a local [[DNS over HTTPS]] server (DoH), i.e., a stub resolver.<br />
<br />
== Installation ==<br />
[[Install]] the {{AUR|cloudflared-bin}} package.<br />
<br />
== Configuration ==<br />
Create the following file: {{hc|/etc/cloudflared/cloudflared.yml|<nowiki><br />
proxy-dns: true<br />
proxy-dns-upstream:<br />
- https://1.0.0.1/dns-query<br />
- https://1.1.1.1/dns-query<br />
- https://2606:4700:4700::1111/dns-query<br />
- https://2606:4700:4700::1001/dns-query<br />
</nowiki>}}<br />
<br />
== Usage ==<br />
[[Start]] and [[enable]] {{ic|cloudflared@cloudflared.service}}<br />
Afterwards, use {{ic|127.0.0.1}} as a DNS server.<br />
<br />
To check whether your browser is using __Cloudflare DoH__, visit https://1.1.1.1/help.<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== See also ==<br />
[https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/ Running a DNS over HTTPS Client - Cloudflare Resolver]</div>Simon04https://wiki.archlinux.org/index.php?title=Domain_name_resolution&diff=598279Domain name resolution2020-02-21T18:12:41Z<p>Simon04: /* Privacy and security */ +Firefox+Chrome configuration</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[de:Resolv.conf]]<br />
[[es:Domain name resolution]]<br />
[[fr:Resolv.conf]]<br />
[[it:Resolv.conf]]<br />
[[ja:Resolv.conf]]<br />
[[pt:Domain name resolution]]<br />
[[zh-hans:Domain name resolution]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|DNS over HTTPS}}<br />
{{Related articles end}}<br />
In general, a [[Wikipedia:Domain name|domain name]] represents an IP address and is associated to it in the [[Wikipedia:Domain Name System|Domain Name System]] (DNS).<br />
This article explains how to configure domain name resolution and resolve domain names.<br />
<br />
== Name Service Switch ==<br />
<br />
{{Expansion|Mention {{Pkg|nss-mdns}}, {{AUR|nss-tls-git}} and others.}}<br />
<br />
The [[Wikipedia:Name Service Switch|Name Service Switch]] (NSS) facility is part of the GNU C Library ({{Pkg|glibc}}) and backs the {{man|3|getaddrinfo}} API, used to resolve domain names. NSS allows system databases to be provided by separate services, whose search order can be configured by the administrator in {{man|5|nsswitch.conf}}. The database responsible for domain name resolution is the ''hosts'' database, for which glibc offers the following services:<br />
<br />
* ''file'': reads the {{ic|/etc/hosts}} file, see {{man|5|hosts}}<br />
* ''dns'': the [[#Glibc resolver|glibc resolver]] which reads {{ic|/etc/resolv.conf}}, see {{man|5|resolv.conf}}<br />
<br />
[[Systemd]] provides three NSS services for hostname resolution:<br />
<br />
* {{man|8|nss-resolve}} - a caching DNS stub resolver, described in [[systemd-resolved]]<br />
* {{man|8|nss-myhostname}} - provides hostname resolution without having to edit {{ic|/etc/hosts}}, described in [[Network configuration#Local hostname resolution]]<br />
* {{man|8|nss-mymachines}} - provides hostname resolution for the names of local {{man|8|systemd-machined}} containers <br />
<br />
=== Resolve a domain name using NSS ===<br />
<br />
NSS databases can be queried with {{man|1|getent}}. A domain name can be resolved through NSS using:<br />
<br />
$ getent hosts ''domain_name''<br />
<br />
{{Note|While most programs resolve domain names using NSS, some may read {{ic|/etc/resolv.conf}} and/or {{ic|/etc/hosts}} directly. See [[Network configuration#Local hostname resolution]].}}<br />
<br />
== Glibc resolver ==<br />
<br />
The glibc resolver reads {{ic|/etc/resolv.conf}} for every resolution to determine the nameservers and options to use. <br />
<br />
{{man|5|resolv.conf}} lists nameservers together with some configuration options.<br />
Nameservers listed first are tried first, up to three nameservers may be listed. Lines starting with a number sign ({{ic|#}}) are ignored.<br />
<br />
{{Note|The glibc resolver does not cache queries. To improve query lookup time you can set up a caching resolver. Glibc resolver also can not validate DNSSEC. A DNSSEC capable validator resolver is required for that one. See [[#DNS servers]] for more information.}}<br />
<br />
=== Overwriting of /etc/resolv.conf ===<br />
<br />
[[Network manager]]s tend to overwrite {{ic|/etc/resolv.conf}}, for specifics see the corresponding section:<br />
<br />
* [[dhcpcd#/etc/resolv.conf]]<br />
* [[netctl#resolv.conf]]<br />
* [[NetworkManager#/etc/resolv.conf]]<br />
<br />
To prevent programs from overwriting {{ic|/etc/resolv.conf}}, it is also possible to write-protect it by setting the immutable [[file attribute]]:<br />
<br />
# chattr +i /etc/resolv.conf<br />
<br />
{{Tip|If you want multiple processes to write to {{ic|/etc/resolv.conf}}, you can use [[resolvconf]].}}<br />
<br />
=== Limit lookup time ===<br />
<br />
If you are confronted with a very long hostname lookup (may it be in [[pacman]] or while browsing), it often helps to define a small timeout after which an alternative nameserver is used. To do so, put the following in {{ic|/etc/resolv.conf}}.<br />
<br />
options timeout:1<br />
<br />
=== Hostname lookup delayed with IPv6 ===<br />
<br />
If you experience a 5 second delay when resolving hostnames it might be due to a DNS-server/Firewall misbehaving and only giving one reply to a parallel A and AAAA request.[https://udrepper.livejournal.com/20948.html] You can fix that by setting the following option in {{ic|/etc/resolv.conf}}:<br />
<br />
options single-request<br />
<br />
=== Local domain names ===<br />
<br />
To be able to use the hostname of local machine names without the fully qualified domain name, add a line to {{ic|/etc/resolv.conf}} with the local domain such as:<br />
domain example.org<br />
That way you can refer to local hosts such as {{ic|mainmachine1.example.org}} as simply {{ic|mainmachine1}} when using the ''ssh'' command, but the [[#Lookup utilities|drill]] command still requires the fully qualified domain names in order to perform lookups.<br />
<br />
== Lookup utilities ==<br />
<br />
To query specific DNS servers and DNS/[[DNSSEC]] records you can use dedicated DNS lookup utilities. These tools implement DNS themselves and do not use [[#Name Service Switch|NSS]].<br />
<br />
* {{Pkg|ldns}} provides {{man|1|drill}}, which is a tool designed to retrieve information out of the DNS.<br />
<br />
For example, to query a specific nameserver with ''drill'' for the TXT records of a domain:<br />
<br />
$ drill @''nameserver'' TXT ''domain''<br />
<br />
Unless a DNS server is specified, ''drill'' will use the nameservers defined in {{ic|/etc/resolv.conf}}.<br />
<br />
* {{Pkg|bind-tools}} provides {{man|1|dig}}, {{man|1|host}}, {{man|1|nslookup}} and a bunch of {{ic|dnssec-}} tools.<br />
<br />
{{Tip|Some DNS servers ship with their own DNS lookup utilities. E.g. {{Pkg|knot}} has {{man|1|khost}} and {{man|1|kdig}}, [[Unbound]]—{{man|1|unbound-host}}.}}<br />
<br />
== Resolver performance ==<br />
<br />
The Glibc resolver does not cache queries. To implement local caching, use [[systemd-resolved]] or set up a local caching [[#DNS servers|DNS server]] and use it as the name server by setting {{ic|127.0.0.1}} and {{ic|::1}} as the name servers in {{ic|/etc/resolv.conf}} or in {{ic|/etc/resolvconf.conf}} if using [[openresolv]].<br />
<br />
{{Tip|<br />
* The ''drill'' or ''dig'' [[#Lookup utilities|lookup utilities]] report the query time.<br />
* A router usually sets its own caching resolver as the network's DNS server thus providing DNS cache for the whole network. <br />
* If it takes too long to switch to the next DNS server you can try [[#Limit lookup time|decreasing the timeout]].}}<br />
<br />
== Privacy and security ==<br />
<br />
The DNS protocol is unencrypted and does not account for confidentiality, integrity or authentication, so if you use an untrusted network or a malicious ISP, your DNS queries can be eavesdropped and the responses [[Wikipedia:Man-in-the-middle attack|manipulated]]. Furthermore, DNS servers can conduct [[Wikipedia:DNS hijacking|DNS hijacking]].<br />
<br />
You need to trust your DNS server to treat your queries confidentially. DNS servers are provided by ISPs and [[#Third-party DNS services|third-parties]]. Alternatively you can run your own [[#DNS servers|recursive name server]], which however takes more effort. If you use a [[DHCP]] client in untrusted networks, be sure to set static name servers to avoid using and being subject to arbitrary DNS servers. To secure your communication with a remote DNS server you can use an encrypted protocol, like [[Wikipedia:DNS over TLS|DNS over TLS]] ([[RFC:7858|RFC 7858]]), [[Wikipedia:DNS over HTTPS|DNS over HTTPS]] ([[RFC:8484|RFC 8484]]), or [[Wikipedia:DNSCrypt|DNSCrypt]], provided that both the upstream server and your [[#DNS servers|resolver]] support the protocol. To verify that responses are actually from [[Wikipedia:Authoritative name server|authoritative name servers]], you can validate [[DNSSEC]], provided that both the upstream server(s) and your [[#DNS servers|resolver]] support it.<br />
<br />
Be aware that client software, such as major web browsers, may also (start to) implement some of the encrypted DNS protocols. While the encryption of queries may often be seen as a bonus, it also means the software sidetracks queries around the system resolver configuration.[https://hacks.mozilla.org/2018/05/a-cartoon-intro-to-dns-over-https/#trr-and-doh] [https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https Mozilla has proposed] disabling application-level DNS if the system resolver cannot resolve the domain "[http://use-application-dns.net/ use-application-dns.net]". Currently this check is only implemented in [[Firefox]]. Google has elected to upgrade to DNS over HTTPS in [[Chromium]] version 79+ if the system's used DNS service provider supports the protocol. More information about Google's plans for DoH can be obtained at [https://www.chromium.org/developers/dns-over-https DNS over HTTPS (aka DoH)] and [https://groups.google.com/a/chromium.org/forum/#!msg/net-dev/lIm9esAFjQ0/vJ93oMbAAgAJ DNS over HTTPS same-provider auto-upgrade in Chrome: heads-up about our post-experiment plan].<br />
<br />
=== Configuring DNS over HTTPS in Firefox ===<br />
<br />
In order to configure DNS over HTTPS in [[Firefox]] (based on [https://support.mozilla.org/en-US/kb/firefox-dns-over-https]):<br />
<br />
# open Network Settings in Preferences<br />
# click Settings<br />
# check Enable DNS over HTTPS<br />
<br />
=== Configuring DNS over HTTPS in Google Chrome ===<br />
<br />
[[Chrome]] 78 includes an experimental support for DoH which can be configured via <code>chrome://flags/#dns-over-https</code>. [https://winaero.com/blog/chrome-78-is-out-with-shared-clipboard-and-more/]<br />
<br />
== Third-party DNS services ==<br />
<br />
{{Note|Before using a third-party DNS service, check its privacy policy for information on how user data is handled. User data has value and can be sold to other parties.}}<br />
<br />
There are various [[Wikipedia:Public recursive name server#List of public DNS service operators|third-party DNS services]] available, some of which also have dedicated software:<br />
<br />
* {{App|dingo|A DNS client for Google DNS over HTTPS|https://github.com/pforemski/dingo|{{AUR|dingo-git}}}}<br />
* {{App|opennic-up|Automates the renewal of the DNS servers with the most responsive OpenNIC servers|https://github.com/kewlfft/opennic-up|{{AUR|opennic-up}}}}<br />
<br />
== DNS servers ==<br />
<br />
[[DNS]] servers can be [[Wikipedia:Authoritative name server|authoritative]] and [[Wikipedia:Name server#Recursive query|recursive]]. If they are neither, they are called '''stub resolvers''' and simply forward all queries to another recursive name server. Stub resolvers are typically used to introduce DNS caching on the local host or network. Note that the same can also be achieved with a fully-fledged name server. This section compares the available DNS servers, for a more detailed comparison, refer to [[Wikipedia:Comparison of DNS server software]].<br />
<br />
{{Expansion|Fill in the unknowns.}}<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! rowspan=2 | Name !! rowspan=2 | Package !! colspan=4 | Capabilities !! rowspan=2 | [[resolvconf]] !! colspan=4 | Supported protocols<br />
|-<br />
! [[Wikipedia:Authoritative name server|Authoritative]] !! [[Wikipedia:Name server#Recursive query|Recursive]] !! [[Wikipedia:Name server#Caching name server|Cache]] !! [[Wikipedia:Domain Name System Security Extensions#The lookup procedure|Validates]]<br>[[DNSSEC]] !! [[Wikipedia:Domain Name System|DNS]] !! [[Wikipedia:DNSCrypt|DNSCrypt]] !! [[Wikipedia:DNS over TLS|DNS<br>over TLS]] !! [[Wikipedia:DNS over HTTPS|DNS<br>over HTTPS]]<br />
|-<br />
! [[dnscrypt-proxy]]<br />
| {{Pkg|dnscrypt-proxy}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{Y|Server}} || {{Y|Resolver}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Rescached]]<br />
| {{AUR|rescached-git}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Yes|https://github.com/shuLhan/rescached-go#integration-with-openresolv}} || {{Yes}} || {{No}} || {{No}} || {{Y|Limited}}<sup>1</sup><br />
|-<br />
! [[Stubby]]<br />
| {{Pkg|stubby}} || {{No}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Y|Server}} || {{No}} || {{Y|Resolver}} || {{No}}<br />
|-<br />
!style="white-space: nowrap;"| [[systemd-resolved]]<br />
| {{Pkg|systemd}} || {{No}} || {{No}} || {{Yes}} || {{Yes}} || {{G|[[systemd-resolvconf|Yes]]}} || {{Y|Resolver and [https://github.com/systemd/systemd/issues/4621#issuecomment-260050033 limited server]}} || {{No}} || {{Y|Insecure resolver}}<sup>2</sup> || {{No|https://github.com/systemd/systemd/issues/8639}}<br />
|-<br />
! [[dnsmasq]]<br />
| {{Pkg|dnsmasq}} || {{Y|Partial}}<sup>3</sup> || {{No}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No|http://lists.thekelleys.org.uk/pipermail/dnsmasq-discuss/2018q2/012131.html}} || {{No}}<br />
|-<br />
! [[BIND]]<br />
| {{Pkg|bind}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{Y|[[stunnel#DNS over TLS]]}}|| {{No}}<br />
|-<br />
! [[Knot Resolver]]<br />
| {{AUR|knot-resolver}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Y|[https://knot-resolver.readthedocs.io/en/stable/modules-http-doh.html Server]}}<br />
|-<br />
! [[Wikipedia:MaraDNS|MaraDNS]]<br />
| {{AUR|maradns}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[pdnsd]]<br />
| {{Pkg|pdnsd}} || {{Yes}} || {{Yes}} || {{G|Permanent}} || {{No}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Wikipedia:PowerDNS#Recursor|PowerDNS Recursor]]<br />
| {{Pkg|powerdns-recursor}} || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Unbound]]<br />
| {{Pkg|unbound}} || {{Y|Partial}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{Y|Server}} || {{Yes}} || {{No|1=https://nlnetlabs.nl/bugs-script/show_bug.cgi?id=1200}}<br />
|-<br />
! [https://maradns.samiam.org/deadwood/ Deadwood]<br />
| {{AUR|deadwood}} || ? || ? || ? || ? || ? || ? || ? || ? || ?<br />
|-<br />
! [https://coredns.io/ CoreDNS]<br />
| {{AUR|coredns}} or {{AUR|coredns-bin}} || ? || ? || ? || ? || ? || ? || ? || ? || ?<br />
|}<br />
<br />
# Only forwards using DNS over HTTPS when Rescached itself is queried using DNS over HTTPS.[https://github.com/shuLhan/rescached-go#integration-with-dns-over-https]<br />
# From {{man|5|resolved.conf}}: ''Note as the resolver is not capable of authenticating the server, it is vulnerable for "man-in-the-middle" attacks.''[https://github.com/systemd/systemd/issues/9397]<br />
# From [[Wikipedia:Comparison of DNS server software#cite_note-masqauth-28|Wikipedia]]: dnsmasq has limited authoritative support, intended for internal network use rather than public Internet use.<br />
<br />
=== Authoritative-only servers ===<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! Name !! Package !! [[DNSSEC]] !! Geographic<br>balancing<br />
|-<br />
! gdnsd<br />
| {{Pkg|gdnsd}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Wikipedia:Knot DNS|Knot DNS]]<br />
| {{Pkg|knot}} || {{Yes}} || {{Yes|https://www.knot-dns.cz/docs/2.7/singlehtml/#geoip-geography-based-responses}}<br />
|-<br />
! [[NSD]]<br />
| {{Pkg|nsd}} || {{No}} || {{No}}<br />
|-<br />
! [[PowerDNS]]<br />
| {{Pkg|powerdns}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
=== Conditional forwarding ===<br />
<br />
{{Remove|Pointless section, there is no software list or instructions.|section=Template remove of Conditional forwarding}}<br />
<br />
It is possible to use specific DNS resolvers when querying specific domain names. This is particularly useful when connecting to a VPN, so that queries to the VPN network are resolved by the VPN's DNS, while queries to the internet will still be resolved by your standard DNS resolver. It can also be used on local networks.<br />
<br />
To implement it, you need to use a [[#DNS servers|local resolver]] because glibc does not support it.<br />
<br />
In a dynamic environment (laptops and to some extents desktops), you need to configure your resolver based on the network(s) you are connected to. The best way to do that is to use [[openresolv]] because it supports [[openresolv#Subscribers|multiple subscribers]]. Some [[network manager]]s support it, either through openresolv, or by configuring the resolver directly.<br />
<br />
==== Software combination support ====<br />
<br />
===== openresolv user support =====<br />
<br />
{{Merge|openresolv#Users|There already is a list of software that supports ''resolvconf''.}}<br />
<br />
{| class="wikitable sortable"<br />
|+ DHCP Clients<br />
! Software !! Support ?<br />
|-<br />
| [[dhcpcd]] || Unknown<br />
|-<br />
| [[iwd]] || Unknown<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Network managers<br />
! Software !! Support ?<br />
|-<br />
| [[NetworkManager]] || {{Y|Partial}}<br />
|-<br />
| [[netctl]] || Unknown<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ VPN Clients<br />
! Software !! Support ?<br />
|-<br />
| [[OpenConnect]] || Unknown<br />
|-<br />
| [[OpenVPN]] || Unknown<br />
|-<br />
| [[strongSwan]] || Unknown<br />
|-<br />
| [[WireGuard]] || Unknown<br />
|}<br />
<br />
===== openresolv subscriber support =====<br />
<br />
{{Merge|openresolv#Subscribers|Duplicates existing content.}}<br />
<br />
{| class="wikitable sortable"<br />
! Software !! Support ?<br />
|-<br />
| [[BIND]] || Unknown<br />
|-<br />
| [[dnsmasq]] || {{Yes}}<br />
|-<br />
| [[pdnsd]] || Unknown<br />
|-<br />
| {{Pkg|powerdns-recursor}} || Unknown<br />
|-<br />
| [[Unbound]] || Unknown<br />
|}<br />
<br />
===== Other solutions =====<br />
<br />
NetworkManager [[NetworkManager#DNS caching and conditional forwarding|supports conditional forwarding without openresolv]].<br />
<br />
{{Note|Although you could use other conditions for forwarding (for example, source IP address), "conditional forwarding" appears to be the name used for the "domain queried" condition.}}<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/x-087-2-resolv.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-handbook/sect.hostname-name-service.en.html#sect.name-resolution Debian Handbook]<br />
* [[RFC:7706]] - Decreasing Access Time to Root Servers by Running One on Loopback<br />
* [http://linux-ip.net/pages/diagrams.html#domain-name-system-overview Domain name system overview] - Diagram about DNS<br />
* [[Alternative DNS services]]</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_HTTPS&diff=598278DNS over HTTPS2020-02-21T18:09:19Z<p>Simon04: /* cloudflared */ → cloudflared</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[Category:Transport Layer Security]]<br />
[[ja:DNS over HTTPS]]<br />
{{Related articles start}}<br />
{{Related|DNS over HTTPS servers}}<br />
{{Related articles end}}<br />
<br />
{{Redirect|Domain name resolution#Privacy and security|The main page provides much better context. The following content needs to be moved to separate pages before redirecting.}}<br />
<br />
'''DNS over HTTPS''' (DNS Queries over HTTPS; '''DoH''') wraps [[DNS]] queries in HTTPS. Therefore, privacy and integrity of the DNS response is guaranteed, and the system is protected agains man-in-the-middle attacks.<br />
<br />
== Publicly available servers ==<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== Client Configuration ==<br />
<br />
{{Expansion|Explain why this is necessary or what are the benefits over running a [[Domain name resolution#DNS servers|stub resolver]].}}<br />
<br />
To check whether your browser is using Cloudflare DoH, visit https://1.1.1.1/help.<br />
<br />
=== Firefox ===<br />
<br />
Based on [https://support.mozilla.org/en-US/kb/firefox-dns-over-https]:<br />
<br />
# open Network Settings in Preferences<br />
# click Settings<br />
# check Enable DNS over HTTPS<br />
<br />
=== Google Chrome ===<br />
<br />
[[Chrome]] 78 includes an experimental support for DoH which can be configured via <code>chrome://flags/#dns-over-https</code>. [https://winaero.com/blog/chrome-78-is-out-with-shared-clipboard-and-more/]<br />
<br />
== Local DNS server ==<br />
<br />
{{Merge|Domain name resolution#DNS servers|Configurations are trivial and described upstream. If more details are needed, they should go to separate pages (e.g. [[cloudflared]] or [[CoreDNS]]).}}<br />
<br />
You may want to run a [[Domain name resolution#DNS servers|local DNS server]] and configure it to use DoH.<br />
<br />
=== cloudflared ===<br />
→ [[cloudflared]]<br />
<br />
== See also ==<br />
* [[wikipedia:DNS over HTTPS]]<br />
* [https://tools.ietf.org/html/rfc8484 RFC 8484 - DNS Queries over HTTPS (DoH)]</div>Simon04https://wiki.archlinux.org/index.php?title=Cloudflared&diff=598277Cloudflared2020-02-21T18:08:58Z<p>Simon04: Created page with "[https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/ Cloudflared] may be used to run a local DNS over HTTPS server (DoH), i.e., a stub resolver. =..."</p>
<hr />
<div>[https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/ Cloudflared] may be used to run a local [[DNS over HTTPS]] server (DoH), i.e., a stub resolver.<br />
<br />
== Installation ==<br />
[[Install]] the {{AUR|cloudflared-bin}} package.<br />
<br />
== Configuration ==<br />
Create the following file: {{hc|/etc/cloudflared/cloudflared.yml|<nowiki><br />
proxy-dns: true<br />
proxy-dns-upstream:<br />
- https://1.0.0.1/dns-query<br />
- https://1.1.1.1/dns-query<br />
- https://2606:4700:4700::1111/dns-query<br />
- https://2606:4700:4700::1001/dns-query<br />
</nowiki>}}<br />
<br />
== Usage ==<br />
[[Start]] and [[enable]] {{ic|cloudflared@cloudflared.service}}<br />
Afterwards, use {{ic|127.0.0.1}} as a DNS server.<br />
<br />
To check whether your browser is using __Cloudflare DoH__, visit https://1.1.1.1/help.<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== See also ==<br />
[https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/ Running a DNS over HTTPS Client - Cloudflare Resolver]</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_HTTPS&diff=594155DNS over HTTPS2020-01-06T22:15:15Z<p>Simon04: /* Local DNS server */ +dnscrypt-proxy</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[Category:Transport Layer Security]]<br />
[[ja:DNS over HTTPS]]<br />
{{Related articles start}}<br />
{{Related|DNS over HTTPS servers}}<br />
{{Related articles end}}<br />
'''DNS over HTTPS''' (DNS Queries over HTTPS; '''DoH''') wraps [[DNS]] queries in [[TLS|HTTPS]]. Therefore, privacy and integrity of the DNS response is guaranteed, and the system is protected agains man-in-the-middle attacks.<br />
<br />
== Publicly available servers ==<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== Client Configuration ==<br />
<br />
To check whether your browser is using Cloudflare DoH, visit https://1.1.1.1/help.<br />
<br />
=== [[Firefox]] ===<br />
<br />
Based on [https://support.mozilla.org/en-US/kb/firefox-dns-over-https]:<br />
<br />
# open Network Settings in Preferences<br />
# click Settings<br />
# check Enable DNS over HTTPS<br />
<br />
=== [[Google Chrome]] ===<br />
<br />
Chrome 78 includes an experimental support for DoH which can be configured via <code>chrome://flags/#dns-over-https</code>. [https://winaero.com/blog/chrome-78-is-out-with-shared-clipboard-and-more/]<br />
<br />
== Local [[DNS#DNS servers|DNS server]] ==<br />
<br />
You may want to run a local DNS server and configure it to use DoH.<br />
<br />
=== cloudflared ===<br />
<br />
1. Install {{AUR|cloudflared-bin}}<br />
2. Create the following file: {{hc|/etc/cloudflared/cloudflared.yml|<nowiki><br />
proxy-dns: true<br />
proxy-dns-upstream:<br />
- https://1.0.0.1/dns-query<br />
- https://1.1.1.1/dns-query<br />
- https://2606:4700:4700::1111/dns-query<br />
- https://2606:4700:4700::1001/dns-query<br />
proxy-dns-port: 5053<br />
proxy-dns-address: 0.0.0.0<br />
</nowiki>}}<br />
3. [[Start]] and [[enable]] {{ic|cloudflared@cloudflared.service}}<br />
<br />
4. Use {{ic|127.0.0.1#5053}} as a DNS server<br />
<br />
Upstream documentation: https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/<br />
<br />
=== CoreDNS ===<br />
<br />
1. Install {{AUR|coredns}} or {{AUR|coredns-bin}}<br />
2. Configure CoreDNS to use Cloudflare, see [https://coredns.io/plugins/forward/] for details. {{hc|/etc/coredns/Corefile|2=<br />
. {<br />
forward . tls://1.1.1.1 tls://1.0.0.1 {<br />
tls_servername cloudflare-dns.com<br />
health_check 5s<br />
}<br />
cache 30<br />
}<br />
}}<br />
3. [[Start]] and [[enable]] <code>coredns.service</code><br />
4. Use CoreDNS as nameserver. {{hc|/etc/resolv.conf|2=<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
=== dnscrypt-proxy ===<br />
→ [[dnscrypt-proxy]]<br />
<br />
=== Unbound ===<br />
→ [[Unbound#Forwarding_using_DNS_over_TLS]]<br />
<br />
== See also ==<br />
* [[wikipedia:DNS over HTTPS]]<br />
* [https://tools.ietf.org/html/rfc8484 RFC 8484 - DNS Queries over HTTPS (DoH)]<br />
* DNS over TLS (DoT) from [https://tools.ietf.org/html/rfc7858 RFC 7858] provides similar protections.</div>Simon04https://wiki.archlinux.org/index.php?title=Dnscrypt-proxy&diff=594154Dnscrypt-proxy2020-01-06T22:14:49Z<p>Simon04: DNS over HTTPS</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Domain Name System]]<br />
[[Category:Encryption]]<br />
[[es:Dnscrypt-proxy]]<br />
[[ja:DNSCrypt]]<br />
[[pt:Dnscrypt-proxy]]<br />
[[zh-hans:Dnscrypt-proxy]]<br />
{{Related articles start}}<br />
{{Related|Domain name resolution}}<br />
{{Related articles end}}<br />
<br />
{{Expansion|What is the difference to {{Pkg|dnscrypt-wrapper}}?}}<br />
<br />
[https://github.com/jedisct1/dnscrypt-proxy dnscrypt-proxy] is a DNS proxy with support for the encrypted DNS protocols [[DNS over HTTPS]] and [https://dnscrypt.info/ DNSCrypt], which can be used to prevent man-in-the-middle attacks and eavesdropping. ''dnscrypt-proxy'' is also compatible with [[DNSSEC]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|dnscrypt-proxy}} package.<br />
<br />
== Configuration ==<br />
<br />
=== Startup ===<br />
<br />
The service can be started in two mutually exclusive ways (i.e. only one of the two may be enabled):<br />
<br />
* With the {{ic|.service}} file.<br />
<br />
{{Note|The {{ic|listen_addresses}} option must be configured (e.g. {{ic|1=listen_addresses = ['127.0.0.1:53', '[::1]:53']}}) in the configuration file when using the {{ic|.service}} file.}}<br />
<br />
* Through the {{ic|.socket}} activation. <br />
<br />
{{Note|When using socket activation the {{ic|listen_addresses}} option must be set to empty (i.e. {{ic|1=listen_addresses = [ ]}}) in the configuration file, since systemd is taking care of the socket configuration.}}<br />
<br />
=== Select resolver ===<br />
<br />
By leaving {{ic|server_names}} commented out in the configuration file {{ic|/etc/dnscrypt-proxy/dnscrypt-proxy.toml}}, ''dnscrypt-proxy'' will choose the fastest server from the sources already configured under {{ic|[sources]}} [https://github.com/jedisct1/dnscrypt-proxy/wiki/Configuration#an-example-static-server-entry]. The lists will be downloaded, verified, and automatically updated [https://github.com/jedisct1/dnscrypt-proxy/wiki/Configuration-Sources#what-is-the-point-of-these-lists]. Thus, configuring a specific set of servers is optional.<br />
<br />
To manually set which server is used, edit {{ic|/etc/dnscrypt-proxy/dnscrypt-proxy.toml}} and uncomment the {{ic|server_names}} variable, selecting one or more of the servers. For example, to use Cloudflare's servers:<br />
<br />
server_names = ['cloudflare', 'cloudflare-ipv6']<br />
<br />
A full list of resolvers is located at the [https://download.dnscrypt.info/resolvers-list/v2/public-resolvers.md upstream page] or [https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v2/public-resolvers.md Github]. If ''dnscrypt-proxy'' has run successfully on the system before, {{ic|/var/cache/dnscrypt-proxy/public-resolvers.md}} will also contain a list. Look at the description for servers note which validate [[DNSSEC]], do not log, and are uncensored. These requirements can be configured globally with the {{ic|require_dnssec}}, {{ic|require_nolog}}, {{ic|require_nofilter}} options.<br />
<br />
=== Disable any services bound to port 53 ===<br />
<br />
{{Tip|If using [[#Unbound]] as your local DNS cache this section can be ignored, as ''unbound'' runs on port 53 by default.}}<br />
<br />
To see if any programs are using port 53, run:<br />
<br />
$ ss -lp 'sport = :domain'<br />
<br />
{{Accuracy|systemd-resolved listens on 127.0.0.53:53, it should not affect dnscrypt-proxy that listens on 127.0.0.1:53.}}<br />
<br />
If the output contains more than the first line of column names, you need to disable whatever service is using port 53. One common culprit is {{ic|systemd-resolved.service}}([[NetworkManager#Unit dbus-org.freedesktop.resolve1.service not found]]), but other network managers may have analogous components. You are ready to proceed once the above command outputs nothing more than the following line:<br />
<br />
Netid State Recv-Q Send-Q Local Address:Port Peer Address:Port<br />
<br />
=== Modify resolv.conf ===<br />
<br />
{{Expansion|Explain what the options mean.}}<br />
<br />
Modify the [[resolv.conf]] file and replace the current set of resolver addresses with the address for ''localhost'' and options [https://github.com/jedisct1/dnscrypt-proxy/wiki/Installation-linux#step-4-change-the-system-dns-settings]:<br />
<br />
nameserver ::1<br />
nameserver 127.0.0.1<br />
options edns0 single-request-reopen<br />
<br />
Other programs may overwrite this setting; see [[resolv.conf#Overwriting of /etc/resolv.conf]] for details.<br />
<br />
=== Start systemd service ===<br />
<br />
Finally, [[start/enable]] the {{ic|dnscrypt-proxy.service}} unit or {{ic|dnscrypt-proxy.socket}}, depending on which method you chose above.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Local DNS cache configuration ===<br />
<br />
{{Tip|''dnscrypt-proxy'' can cache entries without relying on another program. This feature is enabled by default with the line {{ic|1=cache = true}} in your ''dnscrypt-proxy'' configuration file}}<br />
<br />
It is recommended to run ''dnscrypt-proxy'' as a forwarder for a local DNS cache if not using ''dnscrypt-proxy's'' cache feature; otherwise, every single query will make a round-trip to the upstream resolver. Any local DNS caching program should work. In addition to setting up ''dnscrypt-proxy'', you must setup your local DNS cache program. <br />
<br />
==== Change port ====<br />
<br />
In order to forward queries from a local DNS cache, ''dnscrypt-proxy'' should listen on a port different from the default {{ic|53}}, since the DNS cache itself needs to listen on {{ic|53}} and query ''dnscrypt-proxy'' on a different port. Port number {{ic|53000}} is used as an example in this section. In this example, the port number is larger than 1024 so ''dnscrypt-proxy'' is not required to be run by root.<br />
<br />
There are two methods for changing the default port:<br />
<br />
'''Socket method'''<br />
<br />
[[Edit]] {{ic|dnscrypt-proxy.socket}} with the following contents:<br />
<br />
[Socket]<br />
ListenStream=<br />
ListenDatagram=<br />
ListenStream=127.0.0.1:53000<br />
ListenStream=[::1]:53000<br />
ListenDatagram=127.0.0.1:53000<br />
ListenDatagram=[::1]:53000<br />
<br />
When queries are forwarded from the local DNS cache to {{ic|53000}}, {{ic|dnscrypt-proxy.socket}} will start {{ic|dnscrypt-proxy.service}}.<br />
<br />
'''Service method'''<br />
<br />
Edit the {{ic|listen_addresses}} option in {{ic|/etc/dnscrypt-proxy/dnscrypt-proxy.toml}} with the following:<br />
<br />
listen_addresses = ['127.0.0.1:53000', '[::1]:53000']<br />
<br />
==== Example local DNS cache configurations ====<br />
<br />
The following configurations should work with ''dnscrypt-proxy'' and assume that it is listening on port {{ic|53000}}.<br />
<br />
===== Unbound =====<br />
<br />
Configure [[Unbound]] to your liking (in particular, see [[Unbound#Local DNS server]]) and add the following lines to the end of the {{ic|server}} section in {{ic|/etc/unbound/unbound.conf}}:<br />
<br />
do-not-query-localhost: no<br />
forward-zone:<br />
name: "."<br />
forward-addr: ::1@53000<br />
forward-addr: 127.0.0.1@53000<br />
<br />
{{Tip|If you are setting up a server, add {{ic|interface: 0.0.0.0@53}} and {{ic|access-control: ''your-network''/''subnet-mask'' allow}} inside the {{ic|server:}} section so that the other computers can connect to the server. A client must be configured with {{ic|nameserver ''address-of-your-server''}} in {{ic|/etc/resolv.conf}}.}}<br />
<br />
[[Restart]] {{ic|unbound.service}} to apply the changes.<br />
<br />
===== dnsmasq =====<br />
<br />
Configure dnsmasq as a [[dnsmasq#DNS server|local DNS cache]]. The basic configuration to work with ''dnscrypt-proxy'':<br />
<br />
{{hc|/etc/dnsmasq.conf|2=<br />
no-resolv<br />
server=::1#53000<br />
server=127.0.0.1#53000<br />
listen-address=::1,127.0.0.1<br />
}}<br />
<br />
If you configured ''dnscrypt-proxy'' to use a resolver with enabled [[DNSSEC]] validation, make sure to enable it also in dnsmasq:<br />
<br />
{{hc|/etc/dnsmasq.conf|2=<br />
conf-file=/usr/share/dnsmasq/trust-anchors.conf<br />
dnssec<br />
}}<br />
<br />
Restart {{ic|dnsmasq.service}} to apply the changes.<br />
<br />
===== pdnsd =====<br />
<br />
Install [[pdnsd]]. A basic configuration to work with ''dnscrypt-proxy'' is:<br />
<br />
{{hc|/etc/pdnsd.conf|2=<br />
global {<br />
perm_cache = 1024;<br />
cache_dir = "/var/cache/pdnsd";<br />
run_as = "pdnsd";<br />
server_ip = 127.0.0.1;<br />
status_ctl = on;<br />
query_method = udp_tcp;<br />
min_ttl = 15m; # Retain cached entries at least 15 minutes.<br />
max_ttl = 1w; # One week.<br />
timeout = 10; # Global timeout option (10 seconds).<br />
neg_domain_pol = on;<br />
udpbufsize = 1024; # Upper limit on the size of UDP messages.<br />
}<br />
<br />
server {<br />
label = "dnscrypt-proxy";<br />
ip = 127.0.0.1;<br />
port = 53000;<br />
timeout = 4;<br />
proxy_only = on;<br />
}<br />
<br />
source {<br />
owner = localhost;<br />
file = "/etc/hosts";<br />
}<br />
}}<br />
<br />
Restart {{ic|pdnsd.service}} to apply the changes.<br />
<br />
=== Sandboxing ===<br />
<br />
[[Edit]] {{ic|dnscrypt-proxy.service}} to include the following lines:<br />
<br />
[Service]<br />
CapabilityBoundingSet=CAP_IPC_LOCK CAP_SETGID CAP_SETUID CAP_NET_BIND_SERVICE<br />
ProtectSystem=strict<br />
ProtectHome=true<br />
ProtectKernelTunables=true<br />
ProtectKernelModules=true<br />
ProtectControlGroups=true<br />
PrivateTmp=true<br />
PrivateDevices=true<br />
MemoryDenyWriteExecute=true<br />
NoNewPrivileges=true<br />
RestrictRealtime=true<br />
RestrictAddressFamilies=AF_INET AF_INET6<br />
SystemCallArchitectures=native<br />
SystemCallFilter=~@clock @cpu-emulation @debug @keyring @ipc @module @mount @obsolete @raw-io<br />
<br />
See {{man|5|systemd.exec}} and [[Systemd#Sandboxing application environments]] for more information. Additionally see [https://github.com/jedisct1/dnscrypt-proxy/pull/601#issuecomment-284171727 upstream comments]{{Dead link|2018|01|08}}.<br />
<br />
=== Enable EDNS0 ===<br />
<br />
{{Expansion|Name the advantages/motivation for enabling this.}}<br />
<br />
[[Wikipedia:Extension mechanisms for DNS|Extension Mechanisms for DNS]] that, among other things, allows a client to specify how large a reply over UDP can be.<br />
<br />
Add the following line to your {{ic|/etc/resolv.conf}}:<br />
<br />
options edns0<br />
<br />
{{Out of date|dnscrypt-proxy v2 uses different configuration file.}}<br />
<br />
You may also wish to append the following to {{ic|/etc/dnscrypt-proxy.conf}}:<br />
<br />
EDNSPayloadSize ''<bytes>''<br />
<br />
Where ''<bytes>'' is a number, the default size being '''1252''', with values up to '''4096''' bytes being purportedly safe. A value below or equal to '''512''' bytes will disable this mechanism, unless a client sends a packet with an OPT section providing a payload size.<br />
<br />
==== Test EDNS0 ====<br />
<br />
Make use of the [https://www.dns-oarc.net/oarc/services/replysizetest DNS Reply Size Test Server], use the ''drill'' command line tool to issue a TXT query for the name ''rs.dns-oarc.net'':<br />
<br />
$ drill rs.dns-oarc.net TXT<br />
<br />
With '''EDNS0''' supported, the "answer section" of the output should look similar to this:<br />
<br />
rst.x3827.rs.dns-oarc.net.<br />
rst.x4049.x3827.rs.dns-oarc.net.<br />
rst.x4055.x4049.x3827.rs.dns-oarc.net.<br />
"2a00:d880:3:1::a6c1:2e89 DNS reply size limit is at least 4055 bytes"<br />
"2a00:d880:3:1::a6c1:2e89 sent EDNS buffer size 4096"</div>Simon04https://wiki.archlinux.org/index.php?title=Unbound&diff=594153Unbound2020-01-06T21:56:30Z<p>Simon04: /* Forwarding using DNS over TLS */ DNS over TLS</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[ja:Unbound]]<br />
[[zh-hans:Unbound]]<br />
{{Related articles start}}<br />
{{Related|Domain name resolution}}<br />
{{Related articles end}}<br />
<br />
[https://unbound.net/ Unbound] is a validating, recursive, and caching DNS resolver. According to [[Wikipedia:Unbound (DNS Server)|Wikipedia]]:<br />
:Unbound has supplanted the Berkeley Internet Name Domain ([[BIND]]) as the default, base-system name server in several open source projects, where it is perceived as smaller, more modern, and more secure for most applications.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|unbound}} package.<br />
<br />
Additionally, the {{Pkg|expat}} package is required for [[#DNSSEC validation]].<br />
<br />
== Configuration ==<br />
<br />
A default configuration is already included at {{ic|/etc/unbound/unbound.conf}}. The following sections highlight different settings for the configuration file. See {{man|5|unbound.conf}} for other settings and more details.<br />
<br />
Unless otherwise specified, any options listed in this section are to be placed under the {{ic|server}} section in the configuration like so:<br />
<br />
{{hc|/etc/unbound/unbound.conf|<br />
server:<br />
...<br />
''setting'': ''value''<br />
...<br />
}}<br />
<br />
=== Local DNS server ===<br />
<br />
If you want to use ''unbound'' as your local DNS server, set your nameserver to the loopback addresses {{ic|::1}} and {{ic|127.0.0.1}} in {{ic|/etc/resolv.conf}}:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver ::1<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
Make sure to protect {{ic|/etc/resolv.conf}} from modification as described in [[Domain name resolution#Overwriting of /etc/resolv.conf]].<br />
<br />
{{Tip|A simple way to do this is to install [[openresolv]] and add {{ic|1=name_servers="::1 127.0.0.1"}} to {{ic|/etc/resolvconf.conf}}. Then run {{ic|resolvconf -u}} to generate {{ic|/etc/resolv.conf}}.}}<br />
<br />
See [[Domain name resolution#Lookup utilities]] on how to test your settings.<br />
<br />
Check specifically that the server being used is {{ic|::1}} or {{ic|127.0.0.1}} after making permanent changes to [[resolv.conf]].<br />
<br />
You can now setup ''unbound'' such that it is [[#Forwarding queries]], perhaps all queries, to the DNS servers of your choice.<br />
<br />
=== Root hints ===<br />
<br />
For recursively querying a host that is not cached as an address, the resolver needs to start at the top of the server tree and query the root servers, to know where to go for the top level domain for the address being queried. Unbound comes with default builtin hints. Therefore, if the package is updated regularly, no manual intervention is required. Otherwise, it is good practice to use a root-hints file since the builtin hints may become outdated. <br />
<br />
First point ''unbound'' to the {{ic|root.hints}} file:<br />
<br />
root-hints: root.hints<br />
<br />
Then, put a ''root hints'' file into the ''unbound'' configuration directory. The simplest way to do this is to run the command:<br />
<br />
{{bc|<nowiki># curl --output /etc/unbound/root.hints https://www.internic.net/domain/named.cache</nowiki>}}<br />
<br />
When actually using this file, and not the builtin hints, it is a good idea to update {{ic|root.hints}} every six months or so in order to make sure the list of root servers is up to date. This can be done manually or by using [[Systemd/Timers]]. See [[#Roothints systemd timer]] for an example.<br />
<br />
=== DNSSEC validation ===<br />
<br />
To use [[DNSSEC]] validation, the following setting for the server trust anchor should be under {{ic|server:}}:<br />
<br />
{{hc|/etc/unbound/unbound.conf|<br />
trust-anchor-file: trusted-key.key}}<br />
<br />
This setting is done by default[https://git.archlinux.org/svntogit/community.git/commit/trunk/conf?h=packages/unbound&id=79f1ebebd72b53d3b597f6dc48b84f3d76dd9a0c]. {{ic|/etc/unbound/trusted-key.key}} is copied from {{ic|/etc/trusted-key.key}}, which is provided by the {{Pkg|dnssec-anchors}} dependency, whose [[PKGBUILD]] generates the file with {{man|8|unbound-anchor}}.<br />
<br />
DNSSEC validation will only be done if the DNS server being queried supports it. If general [[#Forwarding queries]] have been set to DNS servers that do not support DNSSEC, their answers, whatever they are, should be considered insecure since no DNSSEC validation could be preformed.<br />
<br />
{{Note|Including DNSSEC checking significantly increases DNS lookup times for initial lookups before the address is cached.}}<br />
<br />
==== Testing validation ====<br />
<br />
To test if DNSSEC is working, after [[starting]] {{ic|unbound.service}}, do:<br />
<br />
$ unbound-host -C /etc/unbound/unbound.conf -v sigok.verteiltesysteme.net<br />
<br />
The response should be the ip address with the word {{ic|(secure)}} next to it.<br />
<br />
$ unbound-host -C /etc/unbound/unbound.conf -v sigfail.verteiltesysteme.net<br />
<br />
Here the response should include {{ic|(BOGUS (security failure))}}.<br />
<br />
Additionally you can use ''drill'' to test the resolver as follows:<br />
<br />
$ drill sigfail.verteiltesysteme.net<br />
$ drill sigok.verteiltesysteme.net<br />
<br />
The first command should give an {{ic|rcode}} of {{ic|SERVFAIL}}. The second should give an {{ic|rcode}} of {{ic|NOERROR}}.<br />
<br />
=== Forwarding queries ===<br />
<br />
If you only want to forward queries to an external DNS server, skip ahead to [[#Forward all remaining requests]].<br />
<br />
==== Allow local network to use DNS ====<br />
<br />
===== Using openresolv =====<br />
<br />
{{Style|Explanatory comments should be in the text itself rather than in code snippets. Grammar and language should be improved instead of copy-pasted literally from the linked source.}}<br />
<br />
If your network manager supports [[openresolv]], you can configure it to provide local DNS servers and search domains to Unbound[https://roy.marples.name/projects/openresolv/config]:<br />
<br />
{{hc|/etc/resolvconf.conf|2=<br />
...<br />
<br />
# If don't want to forward the root zone and let the local resolver<br />
# recursively query the root servers directly,<br />
# simply mark all interfaces private.<br />
# You may need to do this if you enable DNSSEC in the local resolver but the<br />
# upstream DNS servers say from your router or ISP don't support DNSSEC.<br />
private_interfaces="*"<br />
<br />
# Write out unbound configuration file<br />
unbound_conf=/etc/unbound/resolvconf.conf<br />
}}<br />
<br />
Run {{ic|resolvconf -u}} to generate the file.<br />
<br />
Configure Unbound to read the openresolv's generated file and allow replies with [[Wikipedia:Private network|private IP address ranges]]:<br />
<br />
{{hc|/etc/unbound/unbound.conf|<br />
include: "/etc/unbound/resolvconf.conf"<br />
...<br />
server:<br />
...<br />
private-domain: "intranet"<br />
private-domain: "internal"<br />
private-domain: "private"<br />
private-domain: "corp"<br />
private-domain: "home"<br />
private-domain: "lan"<br />
<br />
unblock-lan-zones: yes<br />
insecure-lan-zones: yes<br />
...<br />
}}<br />
<br />
Additionally you may want to disable DNSSEC validation for private DNS namespaces[https://tools.ietf.org/html/rfc6762#appendix-G]:<br />
<br />
{{hc|/etc/unbound/unbound.conf|<br />
...<br />
server:<br />
...<br />
domain-insecure: "intranet"<br />
domain-insecure: "internal"<br />
domain-insecure: "private"<br />
domain-insecure: "corp"<br />
domain-insecure: "home"<br />
domain-insecure: "lan"<br />
...<br />
}}<br />
<br />
===== Manually specifying DNS servers =====<br />
<br />
If you have a local network which you wish to have DNS queries for and there is a local DNS server that you would like to forward queries to then you should include this line:<br />
<br />
private-address: ''local_subnet/subnet_mask''<br />
<br />
For example:<br />
<br />
private-address: 10.0.0.0/24<br />
<br />
{{Note|You can use private-address to protect against DNS Rebind attacks. Therefore you may enable RFC1918 networks (10.0.0.0/8 172.16.0.0/12 192.168.0.0/16 169.254.0.0/16 fd00::/8 fe80::/10). Unbound may enable this feature by default in future releases.}} <br />
<br />
====== Include local DNS server ======<br />
<br />
To include a local DNS server for both forward and reverse local addresses a set of lines similar to these below is necessary with a forward and reverse lookup (choose the IP address of the server providing DNS for the local network accordingly by changing 10.0.0.1 in the lines below):<br />
<br />
local-zone: "10.in-addr.arpa." transparent<br />
<br />
This line above is important to get the reverse lookup to work correctly.<br />
<br />
forward-zone:<br />
name: "mynetwork.com."<br />
forward-addr: 10.0.0.1<br />
<br />
forward-zone:<br />
name: "10.in-addr.arpa."<br />
forward-addr: 10.0.0.1<br />
<br />
{{Note|There is a difference between forward zones and stub zones - stub zones will only work when connected to an authoritative DNS server directly. This would work for lookups from a [[BIND]] DNS server if it is providing authoritative DNS - but if you are referring queries to an ''unbound'' server in which internal lookups are forwarded on to another DNS server, then defining the referral as a stub zone in the machine here will not work. In that case it is necessary to define a forward zone as above, since forward zones can have daisy chain lookups onward to other DNS servers. i.e. forward zones can refer queries to recursive DNS servers. This distinction is important as you do not get any error messages indicating what the problem is if you use a stub zone inappropriately.}}<br />
<br />
You can set up the localhost forward and reverse lookups with the following lines:<br />
<br />
local-zone: "localhost." static<br />
local-data: "localhost. 10800 IN NS localhost."<br />
local-data: "localhost. 10800 IN SOA localhost. nobody.invalid. 1 3600 1200 604800 10800"<br />
local-data: "localhost. 10800 IN A 127.0.0.1"<br />
local-zone: "127.in-addr.arpa." static<br />
local-data: "127.in-addr.arpa. 10800 IN NS localhost."<br />
local-data: "127.in-addr.arpa. 10800 IN SOA localhost. nobody.invalid. 2 3600 1200 604800 10800"<br />
local-data: "1.0.0.127.in-addr.arpa. 10800 IN PTR localhost."<br />
<br />
==== Forward all remaining requests ====<br />
<br />
===== Using openresolv =====<br />
<br />
If your network manager supports [[openresolv]], you can configure it to provide upstream DNS servers to Unbound. [https://roy.marples.name/projects/openresolv/config]<br />
<br />
{{hc|/etc/resolvconf.conf|2=<br />
...<br />
# Write out unbound configuration file<br />
unbound_conf=/etc/unbound/resolvconf.conf<br />
}}<br />
<br />
Run {{ic|resolvconf -u}} to generate the file.<br />
<br />
Finally configure Unbound to read the openresolv's generated file:<br />
<br />
include: "/etc/unbound/resolvconf.conf"<br />
<br />
===== Manually specifying DNS servers =====<br />
<br />
To use specific servers for default forward zones that are outside of the local machine and outside of the local network add a forward zone with the name {{ic|.}} to the configuration file. In this example, all requests are forwarded to Google's DNS servers:<br />
<br />
forward-zone:<br />
name: "."<br />
forward-addr: 8.8.8.8<br />
forward-addr: 8.8.4.4<br />
<br />
=== Access control ===<br />
<br />
You can specify the interfaces to answer queries from by IP address. The default, is to listen on ''localhost''.<br />
<br />
To listen on all interfaces, use the following:<br />
<br />
interface: 0.0.0.0<br />
<br />
To control which systems can access the server by IP address, use the {{ic|access-control}} option:<br />
<br />
access-control: ''subnet'' ''action''<br />
<br />
For example:<br />
<br />
access-control: 192.168.1.0/24 allow<br />
<br />
''action'' can be one of {{ic|deny}} (drop message), {{ic|refuse}} (polite error reply), {{ic|allow}} (recursive ok), or {{ic|allow_snoop}} (recursive and nonrecursive ok). By default everything is refused except for localhost.<br />
<br />
=== Forwarding using DNS over TLS ===<br />
<br />
To use [[DNS over TLS]], you will need to specify {{ic|tls-cert-bundle}} option that points to the local system's root certificate authority bundle, allow unbound to forward TLS requests and also specify any number of servers that allow DNS of TLS. <br />
<br />
For each server you will need to specify that the connection port using @, and you will also need to indicate which is its domain name with #. Even though it looks like an comment the hashtag name allows for the TLS authentication name to be set for stub-zones and with {{ic|unbound-control forward control}} command. There should not be any spaces between the @ and # markups.<br />
<br />
{{hc|/etc/unbound/unbound.conf|<br />
...<br />
server:<br />
...<br />
tls-cert-bundle: /etc/ssl/certs/ca-certificates.crt<br />
...<br />
forward-zone:<br />
name: "."<br />
forward-tls-upstream: yes<br />
forward-addr: 1.1.1.1@853#cloudflare-dns.com<br />
}}<br />
<br />
== Usage ==<br />
<br />
=== Starting Unbound ===<br />
<br />
[[Start/enable]] the {{ic|unbound.service}} systemd service.<br />
<br />
=== Remotely control Unbound ===<br />
<br />
''unbound'' ships with the {{ic|unbound-control}} utility which enables us to remotely administer the unbound server. It is similar to the [[Pdnsd#pdnsd-ctl|pdnsd-ctl]] command of {{Pkg|pdnsd}}.<br />
<br />
==== Setting up unbound-control ====<br />
<br />
Before you can start using it, the following steps need to be performed:<br />
<br />
1) Firstly, you need to run the following command<br />
<br />
# unbound-control-setup<br />
<br />
which will generate a self-signed certificate and private key for the server, as well as the client. These files will be created in the {{ic|/etc/unbound}} directory.<br />
<br />
2) After that, edit {{ic|/etc/unbound/unbound.conf}} and put the following contents in that. The {{ic|control-enable: yes}} option is necessary, the rest can be adjusted as required.<br />
<br />
remote-control:<br />
# Enable remote control with unbound-control(8) here.<br />
# set up the keys and certificates with unbound-control-setup.<br />
control-enable: yes<br />
<br />
# what interfaces are listened to for remote control.<br />
# give 0.0.0.0 and ::0 to listen to all interfaces.<br />
control-interface: 127.0.0.1<br />
<br />
# port number for remote control operations.<br />
control-port: 8953<br />
<br />
# unbound server key file.<br />
server-key-file: "/etc/unbound/unbound_server.key"<br />
<br />
# unbound server certificate file.<br />
server-cert-file: "/etc/unbound/unbound_server.pem"<br />
<br />
# unbound-control key file.<br />
control-key-file: "/etc/unbound/unbound_control.key"<br />
<br />
# unbound-control certificate file.<br />
control-cert-file: "/etc/unbound/unbound_control.pem"<br />
<br />
==== Using unbound-control ====<br />
<br />
Some of the commands that can be used with ''unbound-control'' are:<br />
<br />
* print statistics without resetting them<br />
# unbound-control stats_noreset<br />
<br />
* dump cache to stdout<br />
# unbound-control dump_cache<br />
<br />
* flush cache and reload configuration<br />
# unbound-control reload<br />
<br />
Please refer to {{man|8|unbound-control}} for a detailed look at the operations it supports.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Domain blacklisting ===<br />
<br />
To blacklist a domain, by returning a NXDOMAIN to the queries for it, use the {{ic|local-zone: "''domainname''" always_nxdomain}} option in unbound configuration. To ease the blacklist's management, save it as a separate file (e.g. {{ic|/etc/unbound/blacklist.conf}}) and include it from {{ic|/etc/unbound/unbound.conf}}. For example:<br />
<br />
{{hc|/etc/unbound/blacklist.conf|<br />
local-zone: "blacklisted.example" always_nxdomain<br />
local-zone: "another.blacklisted.example" always_nxdomain<br />
}}<br />
<br />
{{hc|/etc/unbound/unbound.conf|<br />
server:<br />
...<br />
include: /etc/unbound/blacklist.conf<br />
}}<br />
<br />
{{Tip|<br />
* In order to return some OK statuses on those hosts, you can change the 127.0.0.1 redirection to a server you control and have that server respond with empty 204 replies, see [http://www.shadowandy.net/2014/04/adblocking-nginx-serving-1-pixel-gif-204-content.htm this page]<br />
* To convert a hosts file from another source to the unbound format do: {{bc|$ grep '^0\.0\.0\.0' ''hostsfile'' {{!}} awk '{print "local-zone: \""$2"\" always_nxdomain"}' > /etc/unbound/blacklist.conf}}<br />
* A list of potential sources for the blacklist can be found in [https://github.com/openwrt/packages/blob/master/net/adblock/files/README.md OpenWrt's adblock package's README].<br />
}}<br />
<br />
=== Adding an authoritative DNS server ===<br />
<br />
{{Accuracy|Running two DNS servers is not inherently more secure than running one providing all features.|section=Two DNS servers are not inherently more secure than one}}<br />
<br />
For users who wish to run both a validating, recursive, caching DNS server as well as an authoritative DNS server on a single machine then it may be useful to refer to the wiki page [[NSD]] which gives an example of a configuration for such a system. Having one server for authoritative DNS queries and a separate DNS server for the validating, recursive, caching DNS functions gives increased security over a single DNS server providing all of these functions. Many users have used Bind as a single DNS server, and some help on migration from Bind to the combination of running NSD and Bind is provided in the [[NSD]] wiki page.<br />
<br />
=== WAN facing DNS ===<br />
<br />
It is also possible to change the configuration files and interfaces on which the server is listening so that DNS queries from machines outside of the local network can access specific machines within the LAN. This is useful for web and mail servers which are accessible from anywhere, and the same techniques can be employed as has been achieved using bind for many years, in combination with suitable port forwarding on firewall machines to forward incoming requests to the right machine.<br />
<br />
=== Roothints systemd timer ===<br />
<br />
Here is an example systemd service and timer that update {{ic|root.hints}} monthly using the method in [[#Root hints]]:<br />
<br />
{{hc|1=/etc/systemd/system/roothints.service|2=<br />
[Unit]<br />
Description=Update root hints for unbound<br />
After=network.target<br />
<br />
[Service]<br />
ExecStart=/usr/bin/curl -o /etc/unbound/root.hints <nowiki>https://www.internic.net/domain/named.cache</nowiki><br />
}}<br />
<br />
{{hc|1=/etc/systemd/system/roothints.timer|2=<br />
[Unit]<br />
Description=Run root.hints monthly<br />
<br />
[Timer]<br />
OnCalendar=monthly<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=timers.target}}<br />
<br />
[[Start/enable]] the {{ic|roothints.timer}} systemd timer.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Issues concerning num-threads ===<br />
<br />
The man page for {{ic|unbound.conf}} mentions:<br />
<br />
outgoing-range: <number><br />
Number of ports to open. This number of file descriptors can be opened per thread.<br />
<br />
and some sources suggest that the {{ic|num-threads}} parameter should be set to the number of cpu cores. The sample {{ic|unbound.conf.example}} file merely has:<br />
<br />
# number of threads to create. 1 disables threading.<br />
# num-threads: 1<br />
<br />
However it is not possible to arbitrarily increase {{ic|num-threads}} above {{ic|1}} without causing ''unbound'' to start with warnings in the logs about exceeding the number of file descriptors. In reality for most users running on small networks or on a single machine it should be unnecessary to seek performance enhancement by increasing {{ic|num-threads}} above {{ic|1}}. If you do wish to do so then refer to [http://www.unbound.net/documentation/howto_optimise.html official documentation] and the following rule of thumb should work:<br />
<br />
:''Set {{ic|num-threads}} equal to the number of CPU cores on the system. E.g. for 4 CPUs with 2 cores each, use 8.''<br />
<br />
Set the {{ic|outgoing-range}} to as large a value as possible, see the sections in the referred web page above on how to overcome the limit of {{ic|1024}} in total. This services more clients at a time. With 1 core, try {{ic|950}}. With 2 cores, try {{ic|450}}. With 4 cores try {{ic|200}}. The {{ic|num-queries-per-thread}} is best set at half the number of the {{ic|outgoing-range}}. <br />
<br />
Because of the limit on {{ic|outgoing-range}} thus also limits {{ic|num-queries-per-thread}}, it is better to compile with {{Pkg|libevent}}, so that there is no {{ic|1024}} limit on {{ic|outgoing-range}}. If you need to compile this way for a heavy duty DNS server then you will need to compile the programme from source instead of using the {{Pkg|unbound}} package.<br />
<br />
== See also ==<br />
<br />
* [https://fedoraproject.org/wiki/Changes/Default_Local_DNS_Resolver Fedora change to Unbound]<br />
* [https://github.com/jodrell/unbound-block-hosts/ Block hosts that contain advertisements]</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_TLS&diff=594152DNS over TLS2020-01-06T21:54:57Z<p>Simon04: Redirected page to DNS over HTTPS</p>
<hr />
<div>#REDIRECT [[DNS over HTTPS]]</div>Simon04https://wiki.archlinux.org/index.php?title=Talk:DNS_over_HTTPS&diff=594151Talk:DNS over HTTPS2020-01-06T21:52:46Z<p>Simon04: re</p>
<hr />
<div>== Structure ==<br />
There is quite a bit more to this topic than what is on this page. Perhaps this should just be a landing page for general the general topic with links to a new page specifically for CoreDNS, and a separate Client configuration page for Firefox and Chromium. Additionally, links and page data should be added for both dns-over-https and dns-proxy. I'll get around to writing pages for both proxy implementations at some point soon -- still testing both in more complex environments. [[User:DJ L|DJ L]] ([[User talk:DJ L|talk]])<br />
:Hi [[User:DJ L]], thanks for your efforts in documenting DNS over HTTPS. I like your idea of linking to specific DNS server wiki pages (such as [[Unbound#Forwarding_using_DNS_over_TLS]]). However, I'm no fan of splitting the page [[DNS over HTTPS]] itself to various sub-pages (browser 1, …, browser n) since I find it difficult to get a total view of the existing documentation and I find myself navigating forward/backward between pages each only containing one paragraph/section. Having said that, and since the page [[DNS over HTTPS servers]] focuses on doh-proxy plus corresponding web server proxies, could you rename [[DNS over HTTPS servers]] to [[doh-proxy]] for a total documentation to implement doh-proxy? For the other servers, I'd like to keep using [[DNS over HTTPS]] for their documentation (links). Thanks! –[[User:Simon04|Simon04]] ([[User talk:Simon04|talk]]) 21:52, 6 January 2020 (UTC)</div>Simon04https://wiki.archlinux.org/index.php?title=Talk:DNS_over_HTTPS_servers&diff=594149Talk:DNS over HTTPS servers2020-01-06T21:41:30Z<p>Simon04: Redirected page to Talk:DNS over HTTPS</p>
<hr />
<div>#REDIRECT [[Talk:DNS over HTTPS]]</div>Simon04https://wiki.archlinux.org/index.php?title=Pi-hole&diff=594147Pi-hole2020-01-06T21:26:04Z<p>Simon04: /* Cloudflared DOH */ → DNS over HTTPS</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[it:Pi-hole]]<br />
[[ja:Pi-hole]]<br />
{{Related articles start}}<br />
{{Related|dnsmasq}}<br />
{{Related|Domain name resolution}}<br />
{{Related|lighttpd}}<br />
{{Related|Linux Containers}}<br />
{{Related|nginx}}<br />
{{Related|OpenVPN}}<br />
{{Related|WireGuard}}<br />
{{Related articles end}}<br />
<br />
[https://pi-hole.net/ Pi-hole] project is a [[wikipedia:DNS_sinkhole|DNS sinkhole]] that compiles a blocklist of domains from multiple third-party sources. Pi-hole uses {{AUR|pi-hole-ftl}} ([[dnsmasq]] fork) to seamlessly drop any and all requests for domains in its blocklist. Running it effectively deploys network-wide ad-blocking without the need to configure individual clients. The package comes with an optional web and a CLI interfaces.<br />
<br />
{{Note|Pi-hole on Arch Linux is not officially supported by the Pi-hole project.}}<br />
<br />
== Overview ==<br />
<br />
There are 2 versions of Pi-Hole available for Arch Linux:<br />
<br />
* [[#Pi-hole server]] - This is default and well-known Pi-Hole server that most users are looking for. It is designed to be used as a DNS server for other devices on the LAN.<br />
* [[#Pi-hole standalone]] - This is alternative lightweight Pi-Hole installation, designed for a mobile context. It is intended to be used on the same device (e.g. laptop), where no external and centralised Pi-Hole server is available. It also has no web interface and automatically updates.<br />
<br />
== Pi-hole server ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{AUR|pi-hole-server}} package.<br />
<br />
=== Configuration ===<br />
<br />
==== FTL ====<br />
<br />
It is a DNS resolver/forwarder and a database-like wrapper/API that provides long-term storage of requests which users can query through the "long-term data" section of the WebGUI. Data are collected and stored in two places:<br />
# Daily data are stored in RAM and are captured in real-time within {{ic|/run/log/pihole/pihole.log}}<br />
# Historical data (i.e. over multiple days/weeks/months) are stored on the file system {{ic|/etc/pihole/pihole-FTL.db}} written out at a user-specified interval.<br />
<br />
{{ic|pihole-FTL.service}} is statically enabled; re/start it. For FTL configuration, see [https://docs.pi-hole.net/ftldns/configfile/ upstream documentation].<br />
<br />
{{Note|Starting {{ic|pihole-FTL.service}} is likelly going to fail. See [[#Failed to start Pi-hole FTLDNS engine]].}}<br />
<br />
==== Web interface ====<br />
<br />
Pi-hole has a very powerful, user friendly, but completely optional web interface. It allows not only to change settings, but analyse and visualise DNS queries performed by other devices.<br />
<br />
===== Set-up PHP =====<br />
<br />
Install {{pkg|php-sqlite}} ({{pkg|php}} will be installed automatically) and enable the relevant extensions detailed here:<br />
<br />
{{hc|/etc/php/php.ini|2=<br />
[...]<br />
extension=pdo_sqlite<br />
[...]<br />
extension=sockets<br />
extension=sqlite3<br />
[...]<br />
}}<br />
<br />
For security reasons, one can optionally populate the [[PHP#Configuration|PHP open_basedir]] directive however, the Pi-hole administration web interface will need access to following files and directories:<br />
<br />
/srv/http/pihole<br />
/run/pihole-ftl/pihole-FTL.port<br />
/run/log/pihole/pihole.log<br />
/run/log/pihole-ftl/pihole-FTL.log<br />
/etc/pihole<br />
/etc/hosts<br />
/etc/hostname<br />
/etc/dnsmasq.d/02-pihole-dhcp.conf<br />
/etc/dnsmasq.d/03-pihole-wildcard.conf<br />
/etc/dnsmasq.d/04-pihole-static-dhcp.conf<br />
/proc/meminfo<br />
/proc/cpuinfo<br />
/sys/class/thermal/thermal_zone0/temp<br />
/tmp<br />
<br />
===== Set-up lighttpd =====<br />
<br />
{{Tip|You can use Nginx web server instead. See [[#Nginx instead of Lighttpd]].}}<br />
<br />
[[Install]] {{Pkg|lighttpd}} and {{Pkg|php-cgi}}.<br />
<br />
Copy the package provided default config for Pi-hole:<br />
# cp /usr/share/pihole/configs/lighttpd.example.conf /etc/lighttpd/lighttpd.conf<br />
[[Enable]] {{ic|lighttpd.service}} and re/start it.<br />
<br />
==== Update hosts file ====<br />
<br />
{{Pkg|filesystem}} ships with an empty {{ic|/etc/hosts}} file which is known to prevent Pi-hole from fetching block lists. One must append the following to this file to ensure correct operation, noting that ''ip.address.of.pihole'' should be the actual IP address of the machine running Pi-hole (eg 192.168.1.250) and ''myhostname'' should be the actual hostname of the machine running Pi-hole.<br />
127.0.0.1 localhost<br />
ip.address.of.pihole pi.hole myhostname<br />
<br />
For more, see [https://github.com/pi-hole/pi-hole/issues/1800 Issue#1800].<br />
<br />
=== Making devices use Pi-hole ===<br />
<br />
To use Pi-Hole, make sure that your devices use Pi-Hole's IP address as their only DNS server. To accomplish this, there are generally 2 methods to make it happen:<br />
<br />
# In router's LAN DHCP settings, set Pi-Hole's IP address as the only DNS server available for connected devices.<br />
# Manually configure each device to use Pi-Hole's IP address as their only DNS server.<br />
<br />
{{Note|Some routers (or even ISPs) do not allow to change LAN DNS settings, so you might want to disable router's DHCP server and use [https://discourse.pi-hole.net/t/how-do-i-use-pi-holes-built-in-dhcp-server-and-why-would-i-want-to Pi-Hole's built in DHCP server instead], as it is automatically configured to use Pi-Hole.}}<br />
<br />
More information about making other devices use Pi-Hole can be found at [https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245 upstream documentation].<br />
<br />
{{Tip|Pi-Hole hosting device can also make use of Pi-Hole. Just change DNS settings to only IP address {{ic|127.0.0.1}}.}}<br />
<br />
== Pi-hole standalone ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{AUR|pi-hole-standalone}} package.<br />
<br />
=== Configuration ===<br />
<br />
==== Timer ====<br />
<br />
The Pi-hole standalone package install a statically enabled timer (and relative service) will weekly update Pi-hole blacklisted servers list.<br />
If you do not like default timer timings (from upstrem project) you can, of course, [[edit]] it or preventing from being executed by [[systemd#Using units|masking]] it.<br />
You need to manually start {{ic|pi-hole-gravity.timer}} or simply reboot after your configuration is finished.<br />
<br />
==== FTL ====<br />
<br />
See [[#FTL]].<br />
<br />
=== Usage ===<br />
<br />
Change the computer's network settings so the only DNS server in use is {{ic|127.0.0.1}}.<br />
<br />
== Usage ==<br />
<br />
Both standalone and server versions can be controlled via CLI, but only server version can be controlled via web interface.<br />
<br />
{{Note|Web interface is so powerful that you don't need CLI at all.}}<br />
<br />
=== Using web interface ===<br />
<br />
Go to [http://pi.hole/admin/ pi.hole] or {{ic|<Pi-Hole IP address>/admin/}} to access web interface.<br />
<br />
=== Using CLI ===<br />
<br />
==== Pi-hole DNS management ====<br />
<br />
By default Pi-hole uses the Google DNS server. You can change which DNS servers Pi-hole uses with:<br />
<br />
$ pihole -a setdns ''server''<br />
<br />
You can specify multiple DNS servers by separating their addresses with commas.<br />
<br />
==== Forced update of ad-serving domains list ====<br />
<br />
If you need to update the blocked domain list, on the machine running Pi-hole you can execute<br />
<br />
$ pihole -g<br />
<br />
==== Temporarily disable Pi-hole ====<br />
<br />
Pi-hole can be paused via CLI by executing:<br />
<br />
$ pihole disable [time]<br />
<br />
If you leave {{ic|time}} blank disabling will be permanent until later manual reenabling.<br />
{{ic|time}} can be expressed in seconds or minutes with syntax #s and #m. For example, to disable Pi-hole for 5 minutes only, you can execute<br />
<br />
$ pihole disable 5m<br />
<br />
At any time you can reenable Pi-hole by executing<br />
<br />
$ pihole enable<br />
<br />
== Tips & Tricks ==<br />
<br />
=== Password-protected web interface ===<br />
<br />
You might want to password-protect the Pi-hole web interface. Run the following command and enter your password:<br />
<br />
pihole -a -p<br />
<br />
To disable the password protection, set a blank password.<br />
<br />
=== DNS over HTTPS ===<br />
<br />
Pi-Hole can be configured to use [[DNS over HTTPS]]. Run a local DNS-server such as [[DNS over HTTPS#cloudflared|cloudflared]] using the privacy-first DNS [https://1.1.1.1/ 1.1.1.1] by Cloudflare, and use {{ic|127.0.0.1#5053}} as a DNS server in Pi-Hole.<br />
<br />
=== Optimise for solid state drives ===<br />
<br />
If Pi-hole is running on a [[solid state drive]] (SD card, SSD etc..) it is recommended to uncomment the {{ic|DBINTERVAL}} value and change it to at least {{ic|60.0}} to minimize writes to the database:<br />
<br />
{{hc|/etc/pihole/pihole-FTL.conf|<nowiki><br />
<br />
...<br />
<br />
## Database Interval<br />
## How often do we store queries in FTL's database -minutes-?<br />
## See: https://docs.pi-hole.net/ftldns/database/<br />
## Options: number of minutes<br />
DBINTERVAL=60.0<br />
<br />
...<br />
<br />
</nowiki>}}<br />
<br />
After changes have been performed, [[restart]] {{ic|pihole-FTL.service}}.<br />
<br />
=== Use with VPN server ===<br />
<br />
Pi-Hole can be used by connected VPN clients.<br />
<br />
==== OpenVPN ====<br />
<br />
An [[OpenVPN]] server can be configured to advertise a Pi-hole instance to its clients. Add the following two lines to your {{ic|/etc/openvpn/server/server.conf}}:<br />
<br />
push "redirect-gateway def1 bypass-dhcp"<br />
push "dhcp-option DNS ''Pi-Hole-IP''"<br />
<br />
If it still does not work, try creating a file {{ic|/etc/dnsmasq.d/00-openvpn.conf}} with the following content:<br />
<br />
interface=tun0<br />
<br />
It may be necessary to make {{ic|dnsmasq}} listen on {{ic|tun0}}.<br />
<br />
==== WireGuard ====<br />
<br />
[[WireGuard]] clients can be configured to use Pi-Hole DNS server. In the client configuration file, specify the following line:<br />
<br />
DNS = ''Pi-Hole-IP''<br />
<br />
See more information in [[WireGuard#Client config]].<br />
<br />
=== Nginx instead of Lighttpd ===<br />
<br />
This is [https://docs.pi-hole.net/guides/nginx-configuration/ unofficial, community-supported configuration]. Make sure that PHP is set-up (see [[#Set-up PHP]]) and lighttpd server is inactive.<br />
<br />
[[Install]] {{Pkg|nginx-mainline}} and {{Pkg|php-fpm}}. <br />
<br />
Edit {{ic|/etc/php/php-fpm.d/www.conf}} and change the listen directive to the following:<br />
<br />
listen = 127.0.0.1:9000 <br />
<br />
Modify {{ic|/etc/nginx/nginx.conf}} to contain the following in the '''http''' section:<br />
<br />
gzip on;<br />
gzip_min_length 1000;<br />
gzip_proxied expired no-cache no-store private auth;<br />
gzip_types text/plain application/xml application/json application/javascript application/octet-stream text/css;<br />
include /etc/nginx/conf.d/*.conf;<br />
<br />
Copy the package provided default config for Pi-hole:<br />
<br />
# mkdir /etc/nginx/conf.d<br />
# cp /usr/share/pihole/configs/nginx.example.conf /etc/nginx/conf.d/pihole.conf<br />
<br />
[[Enable]] {{ic|nginx.service}} {{ic|php-fpm.service}} and re/start them.<br />
<br />
=== Additional blocklists ===<br />
<br />
Pi-Hole was intended to block ads, but it can also be used to block other unwanted content:<br />
<br />
# Tracking domains<br />
# Malware domains<br />
# Piracy sites<br />
# Fake news sites<br />
# Phishing sites<br />
<br />
{{Note|Pi-Hole blocklists must contain '''domains'''. Some blocklists might contain IP addresses of 127.0.0.1 and domain combination - this format is accepted by Pi-Hole.}}<br />
<br />
There are many sources providing these blocklists. Some examples: [https://hosts-file.net/?s=Download hosts-file.net], [https://firebog.net/ firebog.net] and [https://www.reddit.com/comments/bppug1 dbl.oisd.nl].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Data loss on reboot ===<br />
<br />
Systems without a [[RTC]] such as some ARM devices will likely experience loss of data in the query log upon rebooting. When systems lacking a [[RTC]] boot, the time is set ''after'' the network and resolver come up. Aspects of Pi-hole can get started before this happens leading to the data loss. An incorrectly set [[RTC]] can also cause problems. See: [[Installation guide#Time zone]] and [[System time]].<br />
<br />
For devices lacking a [[RTC]]:<br />
A hacky work-around for this is to use [[Systemd#Drop-in files]] against {{ic|pihole-FTL.service}} wherein a delay is built in calling {{ic|/usr/bin/sleep x}} in a {{ic|ExecStartPre}} statement. Note that the value of "x" in the sleep time depends on how long your specific hardware takes to establish the time sync.<br />
<br />
[https://github.com/systemd/systemd/issues/11008 Issue#11008] against systemd-timesyncd is currently preventing the use of the ''time-sync.target'' to automate this.<br />
<br />
=== Failed to start Pi-hole FTLDNS engine ===<br />
<br />
It might be that {{ic|systemd-resolved.service}} already occupied port 53, which is required for {{ic|pihole-FTL.service}}. To resolve this, [[Systemd#Using_units|stop and disable]] {{ic|systemd-resolved.service}} and [[restart]] {{ic|pihole-FTL.service}}.<br />
<br />
=== DNSMasq package conflict ===<br />
<br />
Since Pi-hole-FTL 4.0, a private fork of dnsmasq is integrated in the FTL sub-project. The original {{Pkg|dnsmasq}} package is now conflicting with {{AUR|pi-hole-ftl}} and will be uninstalled when upgrading from a previous version. It's still possible to use the previous dnsmasq config files, just ensure that {{ic|1=conf-dir=/etc/dnsmasq.d/,*.conf}} in the original {{ic|/etc/dnsmasq.conf}} is not commented out.<br />
<br />
=== Unknown Status and changes not being saved ===<br />
The issue, as seen in Task#63704, is with SystemD-created user {{ic|http}}, which is created in expired state. To fix it, run:<br />
<br />
sudo chage --expiredate -1 http<br />
<br />
== See also ==<br />
<br />
* [https://pi-hole.net/ Pi-hole homepage]<br />
* [https://github.com/pi-hole/pi-hole Pi-hole GitHub page]<br />
* [https://github.com/pi-hole/FTL Pi-hole FTL GitHub page]<br />
* [http://dlaa.me/blog/post/skyhole Sky-Hole, the basic idea under Pi-hole standalone]</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_HTTPS&diff=594146DNS over HTTPS2020-01-06T21:24:54Z<p>Simon04: /* Local DNS server */ +cloudflared +Unbound</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[Category:Transport Layer Security]]<br />
[[ja:DNS over HTTPS]]<br />
{{Related articles start}}<br />
{{Related|DNS over HTTPS servers}}<br />
{{Related articles end}}<br />
'''DNS over HTTPS''' (DNS Queries over HTTPS; '''DoH''') wraps [[DNS]] queries in [[TLS|HTTPS]]. Therefore, privacy and integrity of the DNS response is guaranteed, and the system is protected agains man-in-the-middle attacks.<br />
<br />
== Publicly available servers ==<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== Client Configuration ==<br />
<br />
To check whether your browser is using Cloudflare DoH, visit https://1.1.1.1/help.<br />
<br />
=== [[Firefox]] ===<br />
<br />
Based on [https://support.mozilla.org/en-US/kb/firefox-dns-over-https]:<br />
<br />
# open Network Settings in Preferences<br />
# click Settings<br />
# check Enable DNS over HTTPS<br />
<br />
=== [[Google Chrome]] ===<br />
<br />
Chrome 78 includes an experimental support for DoH which can be configured via <code>chrome://flags/#dns-over-https</code>. [https://winaero.com/blog/chrome-78-is-out-with-shared-clipboard-and-more/]<br />
<br />
== Local [[DNS#DNS servers|DNS server]] ==<br />
<br />
You may want to run a local DNS server and configure it to use DoH.<br />
<br />
=== cloudflared ===<br />
<br />
1. Install {{AUR|cloudflared-bin}}<br />
2. Create the following file: {{hc|/etc/cloudflared/cloudflared.yml|<nowiki><br />
proxy-dns: true<br />
proxy-dns-upstream:<br />
- https://1.0.0.1/dns-query<br />
- https://1.1.1.1/dns-query<br />
- https://2606:4700:4700::1111/dns-query<br />
- https://2606:4700:4700::1001/dns-query<br />
proxy-dns-port: 5053<br />
proxy-dns-address: 0.0.0.0<br />
</nowiki>}}<br />
3. [[Start]] and [[enable]] {{ic|cloudflared@cloudflared.service}}<br />
<br />
4. Use {{ic|127.0.0.1#5053}} as a DNS server<br />
<br />
Upstream documentation: https://developers.cloudflare.com/1.1.1.1/dns-over-https/cloudflared-proxy/<br />
<br />
=== CoreDNS ===<br />
<br />
1. Install {{AUR|coredns}} or {{AUR|coredns-bin}}<br />
2. Configure CoreDNS to use Cloudflare, see [https://coredns.io/plugins/forward/] for details. {{hc|/etc/coredns/Corefile|2=<br />
. {<br />
forward . tls://1.1.1.1 tls://1.0.0.1 {<br />
tls_servername cloudflare-dns.com<br />
health_check 5s<br />
}<br />
cache 30<br />
}<br />
}}<br />
3. [[Start]] and [[enable]] <code>coredns.service</code><br />
4. Use CoreDNS as nameserver. {{hc|/etc/resolv.conf|2=<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
=== Unbound ===<br />
→ [[Unbound#Forwarding_using_DNS_over_TLS]]<br />
<br />
== See also ==<br />
* [[wikipedia:DNS over HTTPS]]<br />
* [https://tools.ietf.org/html/rfc8484 RFC 8484 - DNS Queries over HTTPS (DoH)]<br />
* DNS over TLS (DoT) from [https://tools.ietf.org/html/rfc7858 RFC 7858] provides similar protections.</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_HTTPS&diff=594144DNS over HTTPS2020-01-06T21:17:41Z<p>Simon04: </p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[Category:Transport Layer Security]]<br />
[[ja:DNS over HTTPS]]<br />
{{Related articles start}}<br />
{{Related|DNS over HTTPS servers}}<br />
{{Related articles end}}<br />
'''DNS over HTTPS''' (DNS Queries over HTTPS; '''DoH''') wraps [[DNS]] queries in [[TLS|HTTPS]]. Therefore, privacy and integrity of the DNS response is guaranteed, and the system is protected agains man-in-the-middle attacks.<br />
<br />
== Publicly available servers ==<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== Client Configuration ==<br />
<br />
To check whether your browser is using Cloudflare DoH, visit https://1.1.1.1/help.<br />
<br />
=== [[Firefox]] ===<br />
<br />
Based on [https://support.mozilla.org/en-US/kb/firefox-dns-over-https]:<br />
<br />
# open Network Settings in Preferences<br />
# click Settings<br />
# check Enable DNS over HTTPS<br />
<br />
=== [[Google Chrome]] ===<br />
<br />
Chrome 78 includes an experimental support for DoH which can be configured via <code>chrome://flags/#dns-over-https</code>. [https://winaero.com/blog/chrome-78-is-out-with-shared-clipboard-and-more/]<br />
<br />
== Local [[DNS#DNS servers|DNS server]] ==<br />
<br />
You may want to run a local DNS server and configure it to use DoH.<br />
<br />
=== CoreDNS ===<br />
<br />
1. Install {{AUR|coredns}} or {{AUR|coredns-bin}}<br />
2. Configure CoreDNS to use Cloudflare, see [https://coredns.io/plugins/forward/] for details. {{hc|/etc/coredns/Corefile|2=<br />
. {<br />
forward . tls://1.1.1.1 tls://1.0.0.1 {<br />
tls_servername cloudflare-dns.com<br />
health_check 5s<br />
}<br />
cache 30<br />
}<br />
}}<br />
3. [[Start]] and [[enable]] <code>coredns.service</code><br />
4. Use CoreDNS as nameserver. {{hc|/etc/resolv.conf|2=<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
== See also ==<br />
* [[wikipedia:DNS over HTTPS]]<br />
* [https://tools.ietf.org/html/rfc8484 RFC 8484 - DNS Queries over HTTPS (DoH)]<br />
* DNS over TLS (DoT) from [https://tools.ietf.org/html/rfc7858 RFC 7858] provides similar protections.</div>Simon04https://wiki.archlinux.org/index.php?title=Domain_name_resolution&diff=592592Domain name resolution2019-12-25T14:36:33Z<p>Simon04: Related: DNS over HTTPS</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[de:Resolv.conf]]<br />
[[es:Domain name resolution]]<br />
[[fr:Resolv.conf]]<br />
[[it:Resolv.conf]]<br />
[[ja:Resolv.conf]]<br />
[[pt:Domain name resolution]]<br />
[[zh-hans:Domain name resolution]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|DNS over HTTPS}}<br />
{{Related articles end}}<br />
In general, a [[Wikipedia:Domain name|domain name]] represents an IP address and is associated to it in the [[Wikipedia:Domain Name System|Domain Name System]] (DNS).<br />
This article explains how to configure domain name resolution and resolve domain names.<br />
<br />
== Name Service Switch ==<br />
<br />
{{Expansion|Mention {{Pkg|nss-mdns}}, {{AUR|nss-tls-git}} and others.}}<br />
<br />
The [[Wikipedia:Name Service Switch|Name Service Switch]] (NSS) facility is part of the GNU C Library ({{Pkg|glibc}}) and backs the {{man|3|getaddrinfo}} API, used to resolve domain names. NSS allows system databases to be provided by separate services, whose search order can be configured by the administrator in {{man|5|nsswitch.conf}}. The database responsible for domain name resolution is the ''hosts'' database, for which glibc offers the following services:<br />
<br />
* ''file'': reads the {{ic|/etc/hosts}} file, see {{man|5|hosts}}<br />
* ''dns'': the [[#Glibc resolver|glibc resolver]] which reads {{ic|/etc/resolv.conf}}, see {{man|5|resolv.conf}}<br />
<br />
[[Systemd]] provides three NSS services for hostname resolution:<br />
<br />
* {{man|8|nss-resolve}} - a caching DNS stub resolver, described in [[systemd-resolved]]<br />
* {{man|8|nss-myhostname}} - provides hostname resolution without having to edit {{ic|/etc/hosts}}, described in [[Network configuration#Local hostname resolution]]<br />
* {{man|8|nss-mymachines}} - provides hostname resolution for the names of local {{man|8|systemd-machined}} containers <br />
<br />
=== Resolve a domain name using NSS ===<br />
<br />
NSS databases can be queried with {{man|1|getent}}. A domain name can be resolved through NSS using:<br />
<br />
$ getent hosts ''domain_name''<br />
<br />
{{Note|While most programs resolve domain names using NSS, some may read {{ic|/etc/resolv.conf}} and/or {{ic|/etc/hosts}} directly. See [[Network configuration#Local hostname resolution]].}}<br />
<br />
== Glibc resolver ==<br />
<br />
The glibc resolver reads {{ic|/etc/resolv.conf}} for every resolution to determine the nameservers and options to use. <br />
<br />
{{man|5|resolv.conf}} lists nameservers together with some configuration options.<br />
Nameservers listed first are tried first, up to three nameservers may be listed. Lines starting with a number sign ({{ic|#}}) are ignored.<br />
<br />
{{Note|The glibc resolver does not cache queries. To improve query lookup time you can set up a caching resolver. Glibc resolver also can not validate DNSSEC. A DNSSEC capable validator resolver is required for that one. See [[#DNS servers]] for more information.}}<br />
<br />
=== Overwriting of /etc/resolv.conf ===<br />
<br />
[[Network manager]]s tend to overwrite {{ic|/etc/resolv.conf}}, for specifics see the corresponding section:<br />
<br />
* [[dhcpcd#/etc/resolv.conf]]<br />
* [[netctl#resolv.conf]]<br />
* [[NetworkManager#/etc/resolv.conf]]<br />
<br />
To prevent programs from overwriting {{ic|/etc/resolv.conf}}, it is also possible to write-protect it by setting the immutable [[file attribute]]:<br />
<br />
# chattr +i /etc/resolv.conf<br />
<br />
{{Tip|If you want multiple processes to write to {{ic|/etc/resolv.conf}}, you can use [[resolvconf]].}}<br />
<br />
=== Limit lookup time ===<br />
<br />
If you are confronted with a very long hostname lookup (may it be in [[pacman]] or while browsing), it often helps to define a small timeout after which an alternative nameserver is used. To do so, put the following in {{ic|/etc/resolv.conf}}.<br />
<br />
options timeout:1<br />
<br />
=== Hostname lookup delayed with IPv6 ===<br />
<br />
If you experience a 5 second delay when resolving hostnames it might be due to a DNS-server/Firewall misbehaving and only giving one reply to a parallel A and AAAA request.[https://udrepper.livejournal.com/20948.html] You can fix that by setting the following option in {{ic|/etc/resolv.conf}}:<br />
<br />
options single-request<br />
<br />
=== Local domain names ===<br />
<br />
To be able to use the hostname of local machine names without the fully qualified domain name, add a line to {{ic|/etc/resolv.conf}} with the local domain such as:<br />
domain example.org<br />
That way you can refer to local hosts such as {{ic|mainmachine1.example.org}} as simply {{ic|mainmachine1}} when using the ''ssh'' command, but the [[#Lookup utilities|drill]] command still requires the fully qualified domain names in order to perform lookups.<br />
<br />
== Lookup utilities ==<br />
<br />
To query specific DNS servers and DNS/[[DNSSEC]] records you can use dedicated DNS lookup utilities. These tools implement DNS themselves and do not use [[#Name Service Switch|NSS]].<br />
<br />
* {{Pkg|ldns}} provides {{man|1|drill}}, which is a tool designed to retrieve information out of the DNS.<br />
<br />
For example, to query a specific nameserver with ''drill'' for the TXT records of a domain:<br />
<br />
$ drill @''nameserver'' TXT ''domain''<br />
<br />
Unless a DNS server is specified, ''drill'' will use the nameservers defined in {{ic|/etc/resolv.conf}}.<br />
<br />
* {{Pkg|bind-tools}} provides {{man|1|dig}}, {{man|1|host}}, {{man|1|nslookup}} and a bunch of {{ic|dnssec-}} tools.<br />
<br />
{{Tip|Some DNS servers ship with their own DNS lookup utilities. E.g. {{Pkg|knot}} has {{man|1|khost}} and {{man|1|kdig}}, [[Unbound]]—{{man|1|unbound-host}}.}}<br />
<br />
== Resolver performance ==<br />
<br />
The Glibc resolver does not cache queries. To implement local caching, use [[systemd-resolved]] or set up a local caching [[#DNS servers|DNS server]] and use it as the name server by setting {{ic|127.0.0.1}} and {{ic|::1}} as the name servers in {{ic|/etc/resolv.conf}} or in {{ic|/etc/resolvconf.conf}} if using [[openresolv]].<br />
<br />
{{Tip|<br />
* The ''drill'' or ''dig'' [[#Lookup utilities|lookup utilities]] report the query time.<br />
* A router usually sets its own caching resolver as the network's DNS server thus providing DNS cache for the whole network. <br />
* If it takes too long to switch to the next DNS server you can try [[#Limit lookup time|decreasing the timeout]].}}<br />
<br />
== Privacy and security ==<br />
<br />
The DNS protocol is unencrypted and does not account for confidentiality, integrity or authentication, so if you use an untrusted network or a malicious ISP, your DNS queries can be eavesdropped and the responses [[Wikipedia:Man-in-the-middle attack|manipulated]]. Furthermore, DNS servers can conduct [[Wikipedia:DNS hijacking|DNS hijacking]].<br />
<br />
You need to trust your DNS server to treat your queries confidentially. DNS servers are provided by ISPs and [[#Third-party DNS services|third-parties]]. Alternatively you can run your own [[#DNS servers|recursive name server]], which however takes more effort. If you use a [[DHCP]] client in untrusted networks, be sure to set static name servers to avoid using and being subject to arbitrary DNS servers. To secure your communication with a remote DNS server you can use an encrypted protocol, like [[Wikipedia:DNS over TLS|DNS over TLS]], [[Wikipedia:DNS over HTTPS|DNS over HTTPS]] or [[Wikipedia:DNSCrypt|DNSCrypt]], provided that both the upstream server and your [[#DNS servers|resolver]] support the protocol. To verify that responses are actually from [[Wikipedia:Authoritative name server|authoritative name servers]], you can validate [[DNSSEC]], provided that both the upstream server(s) and your [[#DNS servers|resolver]] support it.<br />
<br />
Be aware that client software, such as major web browsers, may also (start to) implement some of the encrypted DNS protocols. While the encryption of queries may often be seen as a bonus, it also means the software sidetracks queries around the system resolver configuration.[https://hacks.mozilla.org/2018/05/a-cartoon-intro-to-dns-over-https/#trr-and-doh] [https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https Mozilla has proposed] disabling application-level DNS if the system resolver cannot resolve the domain "[http://use-application-dns.net/ use-application-dns.net]". Currently this check is only implemented in [[Firefox]].<br />
<br />
== Third-party DNS services ==<br />
<br />
{{Note|Before using a third-party DNS service, check its privacy policy for information on how user data is handled. User data has value and can be sold to other parties.}}<br />
<br />
There are various [[Wikipedia:Public recursive name server#List of public DNS service operators|third-party DNS services]] available, some of which also have dedicated software:<br />
<br />
* {{App|dingo|A DNS client for Google DNS over HTTPS|https://github.com/pforemski/dingo|{{AUR|dingo-git}}}}<br />
* {{App|opennic-up|Automates the renewal of the DNS servers with the most responsive OpenNIC servers|https://github.com/kewlfft/opennic-up|{{AUR|opennic-up}}}}<br />
<br />
== DNS servers ==<br />
<br />
[[DNS]] servers can be [[Wikipedia:Authoritative name server|authoritative]] and [[Wikipedia:Name server#Recursive query|recursive]]. If they are neither, they are called '''stub resolvers''' and simply forward all queries to another recursive name server. Stub resolvers are typically used to introduce DNS caching on the local host or network. Note that the same can also be achieved with a fully-fledged name server. This section compares the available DNS servers, for a more detailed comparison, refer to [[Wikipedia:Comparison of DNS server software]].<br />
<br />
{{Expansion|Fill in the unknowns.}}<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! rowspan=2 | Name !! rowspan=2 | Package !! colspan=4 | Capabilities !! rowspan=2 | [[resolvconf]] !! colspan=4 | Supported protocols<br />
|-<br />
! [[Wikipedia:Authoritative name server|Authoritative]] !! [[Wikipedia:Name server#Recursive query|Recursive]] !! [[Wikipedia:Name server#Caching name server|Cache]] !! [[Wikipedia:Domain Name System Security Extensions#The lookup procedure|Validates]]<br>[[DNSSEC]] !! [[Wikipedia:Domain Name System|DNS]] !! [[Wikipedia:DNSCrypt|DNSCrypt]] !! [[Wikipedia:DNS over TLS|DNS<br>over TLS]] !! [[Wikipedia:DNS over HTTPS|DNS<br>over HTTPS]]<br />
|-<br />
! [[dnscrypt-proxy]]<br />
| {{Pkg|dnscrypt-proxy}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{Y|Server}} || {{Y|Resolver}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Rescached]]<br />
| {{AUR|rescached-git}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Yes|https://github.com/shuLhan/rescached-go#integration-with-openresolv}} || {{Yes}} || {{No}} || {{No}} || {{Y|Limited}}<sup>1</sup><br />
|-<br />
! [[Stubby]]<br />
| {{Pkg|stubby}} || {{No}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Y|Server}} || {{No}} || {{Y|Resolver}} || {{No}}<br />
|-<br />
!style="white-space: nowrap;"| [[systemd-resolved]]<br />
| {{Pkg|systemd}} || {{No}} || {{No}} || {{Yes}} || {{Yes}} || {{G|[[systemd-resolvconf|Yes]]}} || {{Y|Resolver and [https://github.com/systemd/systemd/issues/4621#issuecomment-260050033 limited server]}} || {{No}} || {{Y|Insecure resolver}}<sup>2</sup> || {{No|https://github.com/systemd/systemd/issues/8639}}<br />
|-<br />
! [[dnsmasq]]<br />
| {{Pkg|dnsmasq}} || {{Y|Partial}}<sup>3</sup> || {{No}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No|http://lists.thekelleys.org.uk/pipermail/dnsmasq-discuss/2018q2/012131.html}} || {{No}}<br />
|-<br />
! [[BIND]]<br />
| {{Pkg|bind}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{Y|[[stunnel#DNS over TLS]]}}|| {{No}}<br />
|-<br />
! [[Knot Resolver]]<br />
| {{AUR|knot-resolver}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Y|[https://knot-resolver.readthedocs.io/en/stable/modules.html#dns-over-http-doh Server]}}<br />
|-<br />
! [[Wikipedia:MaraDNS|MaraDNS]]<br />
| {{AUR|maradns}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[pdnsd]]<br />
| {{Pkg|pdnsd}} || {{Yes}} || {{Yes}} || {{G|Permanent}} || {{No}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Wikipedia:PowerDNS#Recursor|PowerDNS Recursor]]<br />
| {{Pkg|powerdns-recursor}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Unbound]]<br />
| {{Pkg|unbound}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{Y|Server}} || {{Yes}} || {{No|1=https://nlnetlabs.nl/bugs-script/show_bug.cgi?id=1200}}<br />
|-<br />
! [https://maradns.samiam.org/deadwood/ Deadwood]<br />
| {{AUR|deadwood}} || ? || ? || ? || ? || ? || ? || ? || ? || ?<br />
|-<br />
! [https://coredns.io/ CoreDNS]<br />
| {{AUR|coredns}} or {{AUR|coredns-bin}} || ? || ? || ? || ? || ? || ? || ? || ? || ?<br />
|}<br />
<br />
# Only forwards using DNS over HTTPS when Rescached itself is queried using DNS over HTTPS.[https://github.com/shuLhan/rescached-go#integration-with-dns-over-https]<br />
# From {{man|5|resolved.conf}}: ''Note as the resolver is not capable of authenticating the server, it is vulnerable for "man-in-the-middle" attacks.''[https://github.com/systemd/systemd/issues/9397]<br />
# From [[Wikipedia:Comparison of DNS server software#cite_note-masqauth-28|Wikipedia]]: dnsmasq has limited authoritative support, intended for internal network use rather than public Internet use.<br />
<br />
=== Authoritative-only servers ===<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! Name !! Package !! [[DNSSEC]] !! Geographic<br>balancing<br />
|-<br />
! gdnsd<br />
| {{Pkg|gdnsd}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Wikipedia:Knot DNS|Knot DNS]]<br />
| {{Pkg|knot}} || {{Yes}} || {{Yes|https://www.knot-dns.cz/docs/2.7/singlehtml/#geoip-geography-based-responses}}<br />
|-<br />
! [[NSD]]<br />
| {{Pkg|nsd}} || {{No}} || {{No}}<br />
|-<br />
! [[PowerDNS]]<br />
| {{Pkg|powerdns}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
=== Conditional forwarding ===<br />
<br />
{{Remove|Pointless section, there is no software list or instructions.|section=Template remove of Conditional forwarding}}<br />
<br />
It is possible to use specific DNS resolvers when querying specific domain names. This is particularly useful when connecting to a VPN, so that queries to the VPN network are resolved by the VPN's DNS, while queries to the internet will still be resolved by your standard DNS resolver. It can also be used on local networks.<br />
<br />
{{Merge|#Glibc resolver|Keep glibc resolver's limitations in one place.|section=Mentionning glibc limitation}}<br />
<br />
To implement it, you need to use a [[#DNS servers|local resolver]] because glibc does not support it.<br />
<br />
In a dynamic environment (laptops and to some extents desktops), you need to configure your resolver based on the network(s) you are connected to. The best way to do that is to use [[openresolv]] because it supports [[openresolv#Subscribers|multiple subscribers]]. Some [[network manager]]s support it, either through openresolv, or by configuring the resolver directly.<br />
<br />
==== Software combination support ====<br />
<br />
===== openresolv user support =====<br />
<br />
{| class="wikitable sortable"<br />
|+ DHCP Clients<br />
! Software !! Support ?<br />
|-<br />
| [[dhcpcd]] || Unknown<br />
|-<br />
| [[iwd]] || Unknown<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Network managers<br />
! Software !! Support ?<br />
|-<br />
| [[NetworkManager]] || {{Y|Partial}}<br />
|-<br />
| [[netctl]] || Unknown<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ VPN Clients<br />
! Software !! Support ?<br />
|-<br />
| [[OpenConnect]] || Unknown<br />
|-<br />
| [[OpenVPN]] || Unknown<br />
|-<br />
| [[strongSwan]] || Unknown<br />
|-<br />
| [[WireGuard]] || Unknown<br />
|}<br />
<br />
===== openresolv subscriber support =====<br />
<br />
{| class="wikitable sortable"<br />
! Software !! Support ?<br />
|-<br />
| [[BIND]] || Unknown<br />
|-<br />
| [[dnsmasq]] || {{Yes}}<br />
|-<br />
| [[pdnsd]] || Unknown<br />
|-<br />
| {{Pkg|powerdns-recursor}} || Unknown<br />
|-<br />
| [[Unbound]] || Unknown<br />
|}<br />
<br />
===== Other solutions =====<br />
<br />
NetworkManager [[NetworkManager#DNS caching and conditional forwarding|supports conditional forwarding without openresolv]].<br />
<br />
{{Note|Although you could use other conditions for forwarding (for example, source IP address), "conditional forwarding" appears to be the name used for the "domain queried" condition.}}<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/x-087-2-resolv.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-handbook/sect.hostname-name-service.en.html#sect.name-resolution Debian Handbook]<br />
* [[RFC:7706]] - Decreasing Access Time to Root Servers by Running One on Loopback<br />
* [http://linux-ip.net/pages/diagrams.html#domain-name-system-overview Domain name system overview] - Diagram about DNS<br />
* [[Alternative DNS services]]</div>Simon04https://wiki.archlinux.org/index.php?title=DNS_over_HTTPS&diff=592590DNS over HTTPS2019-12-25T14:31:51Z<p>Simon04: Created page with "'''DNS over HTTPS''' (DNS Queries over HTTPS; '''DoH''') wraps DNS queries in HTTPS. Therefore, privacy and integrity of the DNS response is guaranteed, and the sy..."</p>
<hr />
<div>'''DNS over HTTPS''' (DNS Queries over HTTPS; '''DoH''') wraps [[DNS]] queries in [[TLS|HTTPS]]. Therefore, privacy and integrity of the DNS response is guaranteed, and the system is protected agains man-in-the-middle attacks.<br />
<br />
== Publicly available servers ==<br />
<br />
For a list of publicly available DoH servers see [https://github.com/curl/curl/wiki/DNS-over-HTTPS] in the ''curl Wiki''.<br />
<br />
== Configuration ==<br />
<br />
To check whether your browser is using DoH, check https://1.1.1.1/help.<br />
<br />
=== [[Firefox]] ===<br />
<br />
Based on [https://support.mozilla.org/en-US/kb/firefox-dns-over-https]:<br />
<br />
# open Network Settings in Preferences<br />
# click Settings<br />
# check Enable DNS over HTTPS<br />
<br />
=== [[Google Chrome]] ===<br />
<br />
Chrome 78 includes an experimental support for DoH which can be configured via <code>chrome://flags/#dns-over-https</code>. [https://winaero.com/blog/chrome-78-is-out-with-shared-clipboard-and-more/]<br />
<br />
=== Local [[DNS#DNS servers|DNS server]] ===<br />
<br />
You may want to run a local DNS server and configure it to use DoH.<br />
<br />
==== CoreDNS ====<br />
<br />
1. Install {{AUR|coredns}} or {{AUR|coredns-bin}}<br />
2. Configure CoreDNS to use Cloudflare, see [https://coredns.io/plugins/forward/] for details. {{hc|/etc/coredns/Corefile|2=<br />
. {<br />
forward . tls://1.1.1.1 tls://1.0.0.1 {<br />
tls_servername cloudflare-dns.com<br />
health_check 5s<br />
}<br />
cache 30<br />
}<br />
}}<br />
3. [[Start]] and [[enable]] <code>coredns.service</code><br />
4. Use CoreDNS as nameserver. {{hc|/etc/resolv.conf|2=<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
== See also ==<br />
* [[wikipedia:DNS over HTTPS]]<br />
* [https://tools.ietf.org/html/rfc8484 RFC 8484 - DNS Queries over HTTPS (DoH)]<br />
* DNS over TLS (DoT) from [https://tools.ietf.org/html/rfc7858 RFC 7858] provides similar protections.<br />
<br />
[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[Category:Transport Layer Security]]</div>Simon04https://wiki.archlinux.org/index.php?title=Domain_name_resolution&diff=592545Domain name resolution2019-12-24T16:12:30Z<p>Simon04: /* DNS servers */ +deadwood +coredns</p>
<hr />
<div>[[Category:Domain Name System]]<br />
[[Category:Network configuration]]<br />
[[de:Resolv.conf]]<br />
[[es:Domain name resolution]]<br />
[[fr:Resolv.conf]]<br />
[[it:Resolv.conf]]<br />
[[ja:Resolv.conf]]<br />
[[pt:Domain name resolution]]<br />
[[zh-hans:Domain name resolution]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related articles end}}<br />
In general, a [[Wikipedia:Domain name|domain name]] represents an IP address and is associated to it in the [[Wikipedia:Domain Name System|Domain Name System]] (DNS).<br />
This article explains how to configure domain name resolution and resolve domain names.<br />
<br />
== Name Service Switch ==<br />
<br />
{{Expansion|Mention {{Pkg|nss-mdns}}, {{AUR|nss-tls-git}} and others.}}<br />
<br />
The [[Wikipedia:Name Service Switch|Name Service Switch]] (NSS) facility is part of the GNU C Library ({{Pkg|glibc}}) and backs the {{man|3|getaddrinfo}} API, used to resolve domain names. NSS allows system databases to be provided by separate services, whose search order can be configured by the administrator in {{man|5|nsswitch.conf}}. The database responsible for domain name resolution is the ''hosts'' database, for which glibc offers the following services:<br />
<br />
* ''file'': reads the {{ic|/etc/hosts}} file, see {{man|5|hosts}}<br />
* ''dns'': the [[#Glibc resolver|glibc resolver]] which reads {{ic|/etc/resolv.conf}}, see {{man|5|resolv.conf}}<br />
<br />
[[Systemd]] provides three NSS services for hostname resolution:<br />
<br />
* {{man|8|nss-resolve}} - a caching DNS stub resolver, described in [[systemd-resolved]]<br />
* {{man|8|nss-myhostname}} - provides hostname resolution without having to edit {{ic|/etc/hosts}}, described in [[Network configuration#Local hostname resolution]]<br />
* {{man|8|nss-mymachines}} - provides hostname resolution for the names of local {{man|8|systemd-machined}} containers <br />
<br />
=== Resolve a domain name using NSS ===<br />
<br />
NSS databases can be queried with {{man|1|getent}}. A domain name can be resolved through NSS using:<br />
<br />
$ getent hosts ''domain_name''<br />
<br />
{{Note|While most programs resolve domain names using NSS, some may read {{ic|/etc/resolv.conf}} and/or {{ic|/etc/hosts}} directly. See [[Network configuration#Local hostname resolution]].}}<br />
<br />
== Glibc resolver ==<br />
<br />
The glibc resolver reads {{ic|/etc/resolv.conf}} for every resolution to determine the nameservers and options to use. <br />
<br />
{{man|5|resolv.conf}} lists nameservers together with some configuration options.<br />
Nameservers listed first are tried first, up to three nameservers may be listed. Lines starting with a number sign ({{ic|#}}) are ignored.<br />
<br />
{{Note|The glibc resolver does not cache queries. To improve query lookup time you can set up a caching resolver. Glibc resolver also can not validate DNSSEC. A DNSSEC capable validator resolver is required for that one. See [[#DNS servers]] for more information.}}<br />
<br />
=== Overwriting of /etc/resolv.conf ===<br />
<br />
[[Network manager]]s tend to overwrite {{ic|/etc/resolv.conf}}, for specifics see the corresponding section:<br />
<br />
* [[dhcpcd#/etc/resolv.conf]]<br />
* [[netctl#resolv.conf]]<br />
* [[NetworkManager#/etc/resolv.conf]]<br />
<br />
To prevent programs from overwriting {{ic|/etc/resolv.conf}}, it is also possible to write-protect it by setting the immutable [[file attribute]]:<br />
<br />
# chattr +i /etc/resolv.conf<br />
<br />
{{Tip|If you want multiple processes to write to {{ic|/etc/resolv.conf}}, you can use [[resolvconf]].}}<br />
<br />
=== Limit lookup time ===<br />
<br />
If you are confronted with a very long hostname lookup (may it be in [[pacman]] or while browsing), it often helps to define a small timeout after which an alternative nameserver is used. To do so, put the following in {{ic|/etc/resolv.conf}}.<br />
<br />
options timeout:1<br />
<br />
=== Hostname lookup delayed with IPv6 ===<br />
<br />
If you experience a 5 second delay when resolving hostnames it might be due to a DNS-server/Firewall misbehaving and only giving one reply to a parallel A and AAAA request.[https://udrepper.livejournal.com/20948.html] You can fix that by setting the following option in {{ic|/etc/resolv.conf}}:<br />
<br />
options single-request<br />
<br />
=== Local domain names ===<br />
<br />
To be able to use the hostname of local machine names without the fully qualified domain name, add a line to {{ic|/etc/resolv.conf}} with the local domain such as:<br />
domain example.org<br />
That way you can refer to local hosts such as {{ic|mainmachine1.example.org}} as simply {{ic|mainmachine1}} when using the ''ssh'' command, but the [[#Lookup utilities|drill]] command still requires the fully qualified domain names in order to perform lookups.<br />
<br />
== Lookup utilities ==<br />
<br />
To query specific DNS servers and DNS/[[DNSSEC]] records you can use dedicated DNS lookup utilities. These tools implement DNS themselves and do not use [[#Name Service Switch|NSS]].<br />
<br />
* {{Pkg|ldns}} provides {{man|1|drill}}, which is a tool designed to retrieve information out of the DNS.<br />
<br />
For example, to query a specific nameserver with ''drill'' for the TXT records of a domain:<br />
<br />
$ drill @''nameserver'' TXT ''domain''<br />
<br />
Unless a DNS server is specified, ''drill'' will use the nameservers defined in {{ic|/etc/resolv.conf}}.<br />
<br />
* {{Pkg|bind-tools}} provides {{man|1|dig}}, {{man|1|host}}, {{man|1|nslookup}} and a bunch of {{ic|dnssec-}} tools.<br />
<br />
{{Tip|Some DNS servers ship with their own DNS lookup utilities. E.g. {{Pkg|knot}} has {{man|1|khost}} and {{man|1|kdig}}, [[Unbound]]—{{man|1|unbound-host}}.}}<br />
<br />
== Resolver performance ==<br />
<br />
The Glibc resolver does not cache queries. To implement local caching, use [[systemd-resolved]] or set up a local caching [[#DNS servers|DNS server]] and use it as the name server by setting {{ic|127.0.0.1}} and {{ic|::1}} as the name servers in {{ic|/etc/resolv.conf}} or in {{ic|/etc/resolvconf.conf}} if using [[openresolv]].<br />
<br />
{{Tip|<br />
* The ''drill'' or ''dig'' [[#Lookup utilities|lookup utilities]] report the query time.<br />
* A router usually sets its own caching resolver as the network's DNS server thus providing DNS cache for the whole network. <br />
* If it takes too long to switch to the next DNS server you can try [[#Limit lookup time|decreasing the timeout]].}}<br />
<br />
== Privacy and security ==<br />
<br />
The DNS protocol is unencrypted and does not account for confidentiality, integrity or authentication, so if you use an untrusted network or a malicious ISP, your DNS queries can be eavesdropped and the responses [[Wikipedia:Man-in-the-middle attack|manipulated]]. Furthermore, DNS servers can conduct [[Wikipedia:DNS hijacking|DNS hijacking]].<br />
<br />
You need to trust your DNS server to treat your queries confidentially. DNS servers are provided by ISPs and [[#Third-party DNS services|third-parties]]. Alternatively you can run your own [[#DNS servers|recursive name server]], which however takes more effort. If you use a [[DHCP]] client in untrusted networks, be sure to set static name servers to avoid using and being subject to arbitrary DNS servers. To secure your communication with a remote DNS server you can use an encrypted protocol, like [[Wikipedia:DNS over TLS|DNS over TLS]], [[Wikipedia:DNS over HTTPS|DNS over HTTPS]] or [[Wikipedia:DNSCrypt|DNSCrypt]], provided that both the upstream server and your [[#DNS servers|resolver]] support the protocol. To verify that responses are actually from [[Wikipedia:Authoritative name server|authoritative name servers]], you can validate [[DNSSEC]], provided that both the upstream server(s) and your [[#DNS servers|resolver]] support it.<br />
<br />
Be aware that client software, such as major web browsers, may also (start to) implement some of the encrypted DNS protocols. While the encryption of queries may often be seen as a bonus, it also means the software sidetracks queries around the system resolver configuration.[https://hacks.mozilla.org/2018/05/a-cartoon-intro-to-dns-over-https/#trr-and-doh] [https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https Mozilla has proposed] disabling application-level DNS if the system resolver cannot resolve the domain "[http://use-application-dns.net/ use-application-dns.net]". Currently this check is only implemented in [[Firefox]].<br />
<br />
== Third-party DNS services ==<br />
<br />
{{Note|Before using a third-party DNS service, check its privacy policy for information on how user data is handled. User data has value and can be sold to other parties.}}<br />
<br />
There are various [[Wikipedia:Public recursive name server#List of public DNS service operators|third-party DNS services]] available, some of which also have dedicated software:<br />
<br />
* {{App|dingo|A DNS client for Google DNS over HTTPS|https://github.com/pforemski/dingo|{{AUR|dingo-git}}}}<br />
* {{App|opennic-up|Automates the renewal of the DNS servers with the most responsive OpenNIC servers|https://github.com/kewlfft/opennic-up|{{AUR|opennic-up}}}}<br />
<br />
== DNS servers ==<br />
<br />
[[DNS]] servers can be [[Wikipedia:Authoritative name server|authoritative]] and [[Wikipedia:Name server#Recursive query|recursive]]. If they are neither, they are called '''stub resolvers''' and simply forward all queries to another recursive name server. Stub resolvers are typically used to introduce DNS caching on the local host or network. Note that the same can also be achieved with a fully-fledged name server. This section compares the available DNS servers, for a more detailed comparison, refer to [[Wikipedia:Comparison of DNS server software]].<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! rowspan=2 | Name !! rowspan=2 | Package !! colspan=4 | Capabilities !! rowspan=2 | [[resolvconf]] !! colspan=4 | Supported protocols<br />
|-<br />
! [[Wikipedia:Authoritative name server|Authoritative]] !! [[Wikipedia:Name server#Recursive query|Recursive]] !! [[Wikipedia:Name server#Caching name server|Cache]] !! [[Wikipedia:Domain Name System Security Extensions#The lookup procedure|Validates]]<br>[[DNSSEC]] !! [[Wikipedia:Domain Name System|DNS]] !! [[Wikipedia:DNSCrypt|DNSCrypt]] !! [[Wikipedia:DNS over TLS|DNS<br>over TLS]] !! [[Wikipedia:DNS over HTTPS|DNS<br>over HTTPS]]<br />
|-<br />
! [[dnscrypt-proxy]]<br />
| {{Pkg|dnscrypt-proxy}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{Y|Server}} || {{Y|Resolver}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Rescached]]<br />
| {{AUR|rescached-git}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Yes|https://github.com/shuLhan/rescached-go#integration-with-openresolv}} || {{Yes}} || {{No}} || {{No}} || {{Y|Limited}}<sup>1</sup><br />
|-<br />
! [[Stubby]]<br />
| {{Pkg|stubby}} || {{No}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{Y|Server}} || {{No}} || {{Y|Resolver}} || {{No}}<br />
|-<br />
!style="white-space: nowrap;"| [[systemd-resolved]]<br />
| {{Pkg|systemd}} || {{No}} || {{No}} || {{Yes}} || {{Yes}} || {{G|[[systemd-resolvconf|Yes]]}} || {{Y|Resolver and [https://github.com/systemd/systemd/issues/4621#issuecomment-260050033 limited server]}} || {{No}} || {{Y|Insecure resolver}}<sup>2</sup> || {{No|https://github.com/systemd/systemd/issues/8639}}<br />
|-<br />
! [[dnsmasq]]<br />
| {{Pkg|dnsmasq}} || {{Y|Partial}}<sup>3</sup> || {{No}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No|http://lists.thekelleys.org.uk/pipermail/dnsmasq-discuss/2018q2/012131.html}} || {{No}}<br />
|-<br />
! [[BIND]]<br />
| {{Pkg|bind}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{Y|[[stunnel#DNS over TLS]]}}|| {{No}}<br />
|-<br />
! [[Knot Resolver]]<br />
| {{AUR|knot-resolver}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{Yes}} || {{No}} || {{Yes}} || {{Y|[https://knot-resolver.readthedocs.io/en/stable/modules.html#dns-over-http-doh Server]}}<br />
|-<br />
! [[Wikipedia:MaraDNS|MaraDNS]]<br />
| {{AUR|maradns}} || {{Yes}} || {{Yes}} || {{Yes}} || {{No}} || {{No}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[pdnsd]]<br />
| {{Pkg|pdnsd}} || {{Yes}} || {{Yes}} || {{G|Permanent}} || {{No}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Wikipedia:PowerDNS#Recursor|PowerDNS Recursor]]<br />
| {{Pkg|powerdns-recursor}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
! [[Unbound]]<br />
| {{Pkg|unbound}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{G|[[openresolv#Subscribers|Yes]]}} || {{Yes}} || {{Y|Server}} || {{Yes}} || {{No|1=https://nlnetlabs.nl/bugs-script/show_bug.cgi?id=1200}}<br />
|-<br />
! [https://maradns.samiam.org/deadwood/ Deadwood]<br />
| {{AUR|deadwood}}<br />
|-<br />
! [https://coredns.io/ CoreDNS]<br />
| {{AUR|coredns}} or {{AUR|coredns-bin}}<br />
|}<br />
<br />
# Only forwards using DNS over HTTPS when Rescached itself is queried using DNS over HTTPS.[https://github.com/shuLhan/rescached-go#integration-with-dns-over-https]<br />
# From {{man|5|resolved.conf}}: ''Note as the resolver is not capable of authenticating the server, it is vulnerable for "man-in-the-middle" attacks.''[https://github.com/systemd/systemd/issues/9397]<br />
# From [[Wikipedia:Comparison of DNS server software#cite_note-masqauth-28|Wikipedia]]: dnsmasq has limited authoritative support, intended for internal network use rather than public Internet use.<br />
<br />
=== Authoritative-only servers ===<br />
<br />
{| class="wikitable sortable" style="text-align:center"<br />
! Name !! Package !! [[DNSSEC]] !! Geographic<br>balancing<br />
|-<br />
! gdnsd<br />
| {{Pkg|gdnsd}} || {{No}} || {{Yes}}<br />
|-<br />
! [[Wikipedia:Knot DNS|Knot DNS]]<br />
| {{Pkg|knot}} || {{Yes}} || {{Yes|https://www.knot-dns.cz/docs/2.7/singlehtml/#geoip-geography-based-responses}}<br />
|-<br />
! [[NSD]]<br />
| {{Pkg|nsd}} || {{No}} || {{No}}<br />
|-<br />
! [[PowerDNS]]<br />
| {{Pkg|powerdns}} || {{Yes}} || {{Yes}}<br />
|}<br />
<br />
=== Conditional forwarding ===<br />
<br />
{{Remove|Pointless section, there is no software list or instructions.|section=Template remove of Conditional forwarding}}<br />
<br />
It is possible to use specific DNS resolvers when querying specific domain names. This is particularly useful when connecting to a VPN, so that queries to the VPN network are resolved by the VPN's DNS, while queries to the internet will still be resolved by your standard DNS resolver. It can also be used on local networks.<br />
<br />
{{Merge|#Glibc resolver|Keep glibc resolver's limitations in one place.|section=Mentionning glibc limitation}}<br />
<br />
To implement it, you need to use a [[#DNS servers|local resolver]] because glibc does not support it.<br />
<br />
In a dynamic environment (laptops and to some extents desktops), you need to configure your resolver based on the network(s) you are connected to. The best way to do that is to use [[openresolv]] because it supports [[openresolv#Subscribers|multiple subscribers]]. Some [[network manager]]s support it, either through openresolv, or by configuring the resolver directly.<br />
<br />
==== Software combination support ====<br />
<br />
===== openresolv user support =====<br />
<br />
{| class="wikitable sortable"<br />
|+ DHCP Clients<br />
! Software !! Support ?<br />
|-<br />
| [[dhcpcd]] || Unknown<br />
|-<br />
| [[iwd]] || Unknown<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Network managers<br />
! Software !! Support ?<br />
|-<br />
| [[NetworkManager]] || {{Y|Partial}}<br />
|-<br />
| [[netctl]] || Unknown<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ VPN Clients<br />
! Software !! Support ?<br />
|-<br />
| [[OpenConnect]] || Unknown<br />
|-<br />
| [[OpenVPN]] || Unknown<br />
|-<br />
| [[strongSwan]] || Unknown<br />
|-<br />
| [[WireGuard]] || Unknown<br />
|}<br />
<br />
===== openresolv subscriber support =====<br />
<br />
{| class="wikitable sortable"<br />
! Software !! Support ?<br />
|-<br />
| [[BIND]] || Unknown<br />
|-<br />
| [[dnsmasq]] || {{Yes}}<br />
|-<br />
| [[pdnsd]] || Unknown<br />
|-<br />
| {{Pkg|powerdns-recursor}} || Unknown<br />
|-<br />
| [[Unbound]] || Unknown<br />
|}<br />
<br />
===== Other solutions =====<br />
<br />
NetworkManager [[NetworkManager#DNS caching and conditional forwarding|supports conditional forwarding without openresolv]].<br />
<br />
{{Note|Although you could use other conditions for forwarding (for example, source IP address), "conditional forwarding" appears to be the name used for the "domain queried" condition.}}<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/x-087-2-resolv.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-handbook/sect.hostname-name-service.en.html#sect.name-resolution Debian Handbook]<br />
* [[RFC:7706]] - Decreasing Access Time to Root Servers by Running One on Loopback<br />
* [http://linux-ip.net/pages/diagrams.html#domain-name-system-overview Domain name system overview] - Diagram about DNS<br />
* [[Alternative DNS services]]</div>Simon04https://wiki.archlinux.org/index.php?title=Talk:Arch_package_guidelines&diff=592535Talk:Arch package guidelines2019-12-24T15:21:27Z<p>Simon04: /* Package versioning: `v` prefix */ new section</p>
<hr />
<div>== Fields order ==<br />
<br />
[[Arch_Packaging_Standards#Package_etiquette]] states: "It is common practice to preserve the order of the PKGBUILD fields as shown above." But this is not true. Common practice is to use {{ic|/usr/share/pacman/PKGBUILD.proto}} as a template, and the order of fields in that prototype has a far greater influence on packages in the wild than this page. This page should edited to reflect the current state of {{ic|PKGBUILD.proto}}. Perhaps this page should state: "It is common practice to order PKGBUILD fields so they match the order of fields in {{ic|PKGBUILD.proto}}. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 14:32, 19 October 2013 (UTC)<br />
<br />
== Punctuation in PKGBUILD ==<br />
What is the official guidance regarding ending a pkgdesc in a period or using commas and English prose punctuation in general?<br />
<br />
[[https://bbs.archlinux.org/viewtopic.php?pid=1288063 Link]] to discussion thread.<br />
<br />
[[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 15:17, 14 June 2013 (UTC)<br />
<br />
==Package naming==<br />
* Package names should consist of '''alphanumeric characters only'''; all letters should be '''lowercase'''.<br />
:--unsigned<br />
<br />
::This is a guideline, but I see some packages with hypens and underscores (tesseract-data-chi_sim), dots (gstreamer0.10), plus (libxml++) and even at-signs (kde-l10n-ca@valencia). A package with uppercase name is libreoffice-bn-IN. According to the makepkg source, the allowed chars are: {{ic|[:alnum:]+_.@-}}. [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
:::"alphanumeric characters only" rule is ridiculous, 85% of official packages break this rule. I think it should be changed to allow hypens. It makes package names more readable. In regards to other characters, the + sign breaks [https://aur.archlinux.org/rpc.php AUR search] ([https://aur.archlinux.org/rpc.php?type=search&arg=a++ example], [https://aur.archlinux.org/rpc.php?type=search&arg=a%2B%2B should be escaped]). [[User:Axper|axper]] ([[User talk:Axper|talk]]) 11:19, 11 May 2014 (UTC)<br />
<br />
* Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.<br />
:--unsigned<br />
<br />
* Package versions '''should be the same as the version released by the author'''. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). '''Version tags may not include hyphens!''' Letters, numbers, and periods only.<br />
:--unsigned<br />
<br />
::This rule needs to get more stricter. Having a slash in the version breaks filenames. For craziness, I tried setting up a pkgver containing all characters from 0x01 to 0xff which makes makepkg throw a Bash syntax error. The current packages have versions matching {{ic}[[alnum:]._+~]+} (and a colon for epoch, a hypen for pkgrel). What about limiting to those characters? Debian has a similar set, see [https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version their policy docs] [[User:Lekensteyn|Lekensteyn]] ([[User talk:Lekensteyn|talk]]) 22:38, 1 February 2014 (UTC)<br />
<br />
* Package releases are '''specific to Arch Linux packages'''. These allow users to differentiate between newer and older package builds. When a new package version is first released, the '''release count starts at 1'''. Then as fixes and optimizations are made, the package will be '''re-released''' to the Arch Linux public and the '''release number will increment'''. When a new version comes out, the release count resets to 1. Package release tags follow the '''same naming restrictions as version tags'''.<br />
:--unsigned<br />
<br />
* Why is there no mentioning of suffixes for different build sources, such as vcs sources (-git, -hg, …) or binary distributions (-bin)? IMO this is an important part of the package naming conventions in AUR. [[User:Fordprefect|Fordprefect]] ([[User talk:Fordprefect|talk]]) 13:43, 10 May 2016 (UTC)<br />
<br />
::Some of the information is sequestered into the [[Arch User Repository#What is the difference between foo and foo-git packages?|AUR page's FAQ]] and other places, but I have [[Talk:Arch User Repository#Integrate FAQ content|a proposal]] to bring it together <s>(and add some additional conventions). Since this page already has a section on package naming conventions, it would integrate well here.</s> Unfortunately, as this is a protected page, I wouldn't be able to make the edits myself. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:29, 23 February 2019 (UTC)<br />
<br />
::[[User:Quequotion/Arch package guidelines#Package naming|Here]]'s a whole-page draft of what that might look like. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 16:04, 23 February 2019 (UTC)<br />
<br />
:::In addition to updating links above, I have changed my point of view on where this information is best kept. The thing to do, for minimal redundancy, is to link to [[VCS package guidelines]], which itself needs authorized user intervention to implement [[Talk:VCS package guidelines#Proposal: Break "Guidelines" header into subsections|this proposal]] so as to have a "Package naming" subsection to link to directly. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 15:24, 24 August 2019 (UTC)<br />
<br />
=== Proposal: Unofficial packages ===<br />
<br />
* Unofficial packages having extra features enabled and/or patches in comparison to their official counterparts should be named differently to express that. For example, a package for GNU {{Pkg|screen}} containing the sidebar patch could be named {{ic|screen-sidebar}}. Additionally the {{ic|1=provides=('screen')}} array should be used to avoid conflicts with the official package and satisfy its dependents.<br />
<br />
{{Comment|This rule is not relevant for the official repositories so it does not fit to this page. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:00, 16 March 2019 (UTC)<br />
:There's nothing indicating that the advice on this page is limited to official packages. On the contrary, I think we very much want these guidelines to apply to official packages, AUR packages, third-party repository packages, etc. Such that if ever someone comes looking to help with such a package on the forums or IRC, we can know right away if they are using official or unofficial packages (it should not be assumed the user will know the difference or the significance of it). [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 23:30, 16 March 2019 (UTC)<br />
::Yes, these guidelines apply to everything, but everything on this page should apply to official repositories as the least common denominator. Rules which are not common should belong elsewhere. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:12, 17 March 2019 (UTC)<br />
:::That would leave this convention with nowhere to go, as it applies not only to AUR packages but third-party packages anywhere. How about prepending "Unofficial" to make clear that this convention applies to packages that are disqualified for inclusion in official repositories? [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 08:47, 17 March 2019 (UTC)}}<br />
<br />
See also the various [[:Category:Arch package guidelines|package guidelines]] pages for other naming conventions.<br />
<br />
== Is it acceptable for build() to start by removing directories? ==<br />
<br />
I just downloaded a PKGBUILD whose build() function begins with the following:<br />
<br />
find ./ -maxdepth 1 -mindepth 1 -type d -exec rm -r {} \;<br />
<br />
It seems to me that a PKGBUILD has no business doing this and that it is potentially dangerous. I admit that its danger will typically require people to do non-standard things and, arguably, things they would be better advised not to do anyway. But it still seems to me to invite trouble.<br />
<br />
I don't remember seeing this in a PKGBUILD before but I can't find anything definitely ruling it out.<br />
<br />
Is it acceptable for a build function to start by removing directories in this way? Is it safe?<br />
<br />
--[[User:Margali|cfr]] ([[User talk:Margali|talk]]) 03:03, 27 February 2014 (UTC)<br />
<br />
: I'd argue that this is an acceptable thing to do, at least in some cases. As an example, consider [http://www.talend.com/products/data-integration Talend Open Studio DI]: a single source file provides files for Windows, Linux, Mac OS, PowerPC (?) and Solaris. In response, the {{AUR|talend-open-studio-di}} PKGBUILD simply removes them. Does removing those files invite trouble? Yes. But removing files seems like an integral tool in the package maintainer's toolkit, and plenty of other weird stuff happens in PKGBUILDs too. [[User:Ichimonji10|Ichimonji10]] ([[User talk:Ichimonji10|talk]]) 02:20, 3 March 2014 (UTC)<br />
<br />
== Unique sources ==<br />
<br />
The source array should only contain unique sources names if a shares source directory is used. This applies to most github download. You can use "${pkgname}-${pkgver}.tar.gz::" prependet to each source to make the filename unique. <br />
I am not allowed to edit the page, could someone please do so?--[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 15:33, 16 December 2016 (UTC)<br />
<br />
== Add security standards ==<br />
<br />
As we decided to use https and GPG wherever possible for PKGBUILDs this should be added here as well. A Link to the mailing list would be also nice. The usage of strong hashes could also be mentioned, but I assume some people will not like the idea. A Link to the discussion about the hashes could also help for everyone to get his own opinion. It should be also mentioned that maintainers still need to validate the content of the downloads and test the update. Another important point is to contact upstream for GPG signatures if they are not available yet. One can link to some templates/tutorials I made on nicohood.de --[[User:NicoHood|NicoHood]] ([[User talk:NicoHood|talk]]) 19:40, 16 December 2016 (UTC)<br />
<br />
:Forget about the checksums part, as it was already declined multiple times by the developers. For the rest, patches welcome. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 20:19, 16 December 2016 (UTC)<br />
:edit: see also [[User:Apg#makepkg:_replace_default_checksums]] -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:21, 14 March 2017 (UTC)<br />
<br />
== Architecture Section not clear enough ==<br />
<br />
The arch array depends "on which architectures it can be built on". This is okay but I believe it should be clarified that the program also needs to run and work on that architecture. I know it's a bit "obvious" but people who write interpreted programs may understand that they should put "any" in the arch array even if their program is not usable at all for some architectures. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 07:14, 28 April 2017 (UTC)<br />
<br />
:How does fixing "built on" to "built for" prevent people from abusing {{ic|any}}? That's a separate problem. Also, interpreted programs like scripts ''should'' use {{ic|any}}, where do you think they shouldn't? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:39, 28 April 2017 (UTC)<br />
<br />
::There is that program (debtap in AUR) wrote in bash that converts deb packages to Arch Linux packages. Unfortunately the program works only for i386 and amd64 because it fetches Ubuntu repositories at some specific locations. So when you run it on an arm architecture it fails with a curl output saying 404 which is not user friendly at all. IMHO a package should be restricted to the architectures where it works but in the specifications here, the only requirement is that it compiles. [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 09:08, 28 April 2017 (UTC)<br />
<br />
:::Actually it is better specified here: [[PKGBUILD#arch]] "If instead a package can be compiled for any architecture, but is architecture-specific once compiled, specify all architectures officially supported by Arch, i.e. arch=('i686' 'x86_64'). " [[User:Cecton|Cecton]] ([[User talk:Cecton|talk]]) 10:10, 29 April 2017 (UTC)<br />
<br />
Since we no longer support i686 and the section had to be edited anyway, I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=507402&oldid=485119 tried to clarify] the situation described above. I don't think it should include something like ".. and any other architectures the package builds/compiles/runs on", as we only support x86_64. None of the packages in the official repositories specify architectures besides 'x86_64' and 'any' (I think). [[User:Lonaowna|Lonaowna]] ([[User talk:Lonaowna|talk]]) 15:41, 13 January 2018 (UTC)<br />
:Maybe we should just do like we do for Licenses, and say "See [[PKGBUILD#arch]]". I think we explain in sufficient detail there. :) -- [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 03:26, 14 January 2018 (UTC)<br />
<br />
::Not saying it's a bad thing, but following this approach there wouldn't be much left of the ''official'' packaging guidelines... The purpose of the entire page should be rethought. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 09:41, 14 January 2018 (UTC)<br />
<br />
== /opt vs /usr/share ==<br />
<br />
Should there be a clause here or somewhere about preferring {{ic|/opt}} for big/self-contained AUR packages instead of {{ic|/usr/share}}? Isn't there such a policy? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 17:17, 21 May 2017 (UTC)<br />
<br />
:That's somewhat covered by the [http://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html FHS]. There's no reason to make it specific only to AUR, even official packages like {{Pkg|cuda}} or {{Pkg|vtk6}} are installed into {{ic|/opt}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 18:34, 21 May 2017 (UTC)<br />
<br />
::Do you mean that actual page? So sections like [[Arch packaging standards#Directories]] should really be replaced with a link there? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 19:02, 21 May 2017 (UTC)<br />
<br />
:::There you go, you even ''have'' the policy, so what's the point of this discussion really?? -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:07, 21 May 2017 (UTC)<br />
<br />
::::Alad, I'd appreciate it, if you didn't just come in and close an ongoing discussion. Anyway, so shouldn't that text be amended if that small piece is our official guideline? 1) Java is not installed in {{ic|/opt}} (neither {{Pkg|jre7-openjdk}} nor {{Pkg|jre8-openjdk}}), 2) what is a "self-contained" package? Can it have e.g. icons and desktop files in {{ic|/usr}}? I would hope so. —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 21:19, 21 May 2017 (UTC)<br />
<br />
:::::Det, you really need to improve the way you ask questions. We don't have telepathic powers like you might have, so there is no way we could have guessed from the first post that you want an explanation for a section that you linked in your second post. Please read the standard reference on this topic, [http://www.catb.org/~esr/faqs/smart-questions.html How To Ask Questions The Smart Way].<br />
:::::Now back to the topic. You're right about Java, so I [https://wiki.archlinux.org/index.php?title=Arch_packaging_standards&diff=477997&oldid=462352 removed] that example. There are multiple reasons to use {{ic|/opt}}, most often it is because it may be too hard or even impossible to merge the software with the system's {{ic|/usr}} hierarchy. For example the software might come with bundled libraries which may conflict with the system libraries, this is where the "self-contained" comes from. If you take a look at the content of the {{pkg|cuda}} package, you will see that manual pages, licenses and desktop files are installed into {{ic|/usr/share}}.<br />
:::::-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:17, 22 May 2017 (UTC)<br />
<br />
::::::Hmm. I don't think I was looking for an explanation to another article from the talk page of a different article. What "telepathic powers" that I "may have" have got to do with that, I've no clue. Also, I don't ''think'' I need patronisations about how to ask good questions. :-)<br />
::::::Anyway, as you can see from the flow of the conversation, first I thought there should be an AUR-specific instruction on {{ic|/opt}}. Then you say no, and there's also a different site. Then I ask about that other general one I found, different article, which is very cryptic, a bit out-of-date, and maybe that's the reason that it is. Then you respond, well exactly, that's what we already got, so why ask in the first place, and Alad closes the conversation?<br />
::::::Right? On the issue, I can see {{Pkg|cuda}} has its stuff elsewhere besides {{ic|/opt}}. ''However'', the ''point is'', why isn't it explained ''in that'' article? Why isn't ''your'' explanation in the article? Also, it currently says "large self-contained". What is the definition of ''large''? Smaller ones belong in {{ic|/usr}}?<br />
::::::''I'' don't need that explanation, the ''article'' needs it. People reading for the ''first time'' need it. Right? —'''<span style="text-shadow:grey 0.1em 0.1em 0.1em; font-size:110%">[[User:Det|<font color="gold">D</font><font color="orange">e</font><font color="red">t</font>]][[User talk:Det|<sup><font color="white">talk</font></sup>]]</span>''' 08:24, 22 May 2017 (UTC)<br />
<br />
== Directories -- Why shouldn't /srv be used? ==<br />
<br />
I'm updating the AUR package for the cyrus-imapd package, and noticed that this guideline states that the /srv directory should not be included in the package. Persistent application data should be placed in /var/lib/{pkg}. I'm wondering if there is a good reason for this? From long experience, /var tends to include a lot of rapidly changing ephemeral data and often ends up on a (typically smaller and faster) OS disk partition. And in the past, mounting another partition to /var lead to timing issues. systemd has fixed the latter, but the former persists, and IMAP mail stores tend to grow quite large over time. As a result, I've adopted the convention of using /srv for data which is served out and which can grow in size indefinitely. Furthermore, this is precisely how the directory is intended to be used according to the FHS. So I'd like to put the IMAP user mail store in /srv/imap by default, and was planning to do so until I ran across this document. Sort of feeling like this specific instruction is out of date (but agree that the other directories listed shouldn't be used) [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:15, 13 March 2019 (UTC)<br />
: Adding to my own comment, for purposes of clarification. Again, from long experience, people find setting up an imap server to be complicated and intimidating, so it would be better to offer an a priori rational directory structure which needn't be modified after the fact. [[User:Pgoetz|Pgoetz]] ([[User talk:Pgoetz|talk]]) 22:20, 13 March 2019 (UTC)<br />
<br />
::''> /var tends to include a lot of rapidly changing '''ephemeral''' data''<br />
::Wrong. E.g. [[PostgreSQL]] and [[MariaDB]] store their database data, which are definitely not ephemeral, in {{ic|/var/lib/}}. The {{ic|/srv/}} directory is intended for files which are directly served, such as static {{ic|.html}}, not for files which have to be decoded or decrypted to assemble the served content. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 17:07, 16 March 2019 (UTC)<br />
<br />
== Package naming: Redundant bullet points (pkgver, pkgrel) ==<br />
<br />
The bullet points regarding {{ic|pkgver}} and {{ic|pkgrel}} are highly redundant with the content on the {{ic|PKGBUILD}} page. They are also not ''technically'' part of a package's "name". I would remove these from the page. [[User:Quequotion|quequotion]] ([[User talk:Quequotion|talk]]) 14:35, 15 May 2019 (UTC)<br />
<br />
== Specify you can not rely on environment variables being passed between functions ==<br />
<br />
I've seen many packages that declare variables in one function. Then expect that variable to still be set when accessed from another function.<br />
<br />
This works with a normal makepkg invocation but can break some workflows.<br />
<br />
For example using {{ic|makepkg --nobuild}} to extract files and prepare, then manually tweaking {{ic|src/}} and finishing the build with {{ic|makepkg --noextract}}.<br />
<br />
Another is building a package normally, then after tweaking some metadata such as {{ic|pkgdesc}} or {{ic|depends}}, using {{ic|makepkg --repackage}} to quickly repackage without having to wait for the whole build to finish.<br />
<br />
I believe these to be acceptable uses of makepkg so this should be official pkgbuild etiquette.<br />
<br />
[[User:Morganamilo|Morganamilo]] ([[User talk:Morganamilo|talk]]) 13:26, 24 August 2019 (UTC)<br />
<br />
:Since none of those workflows (including --repackage) are applicable to packages in the [[official repositories]], I would say it's not relevant to this article. It could be a note in [[PKGBUILD]] or [[Creating packages]]. -- [[User:Alad|Alad]] ([[User talk:Alad|talk]]) 15:04, 24 August 2019 (UTC)<br />
<br />
:: These workflows are more for pkgbuild hacking than packaging for a repo. So it would make sense that the offical repos never need to use these flags. But I still think it makes sense for the repos and every one else to follow this rule so it is easier for people to hack pkgbuilds.<br />
<br />
:: Also as some one who is used to languages where variables are scoped. Seeing a variable declared in prepare that then effects build is weird. Either make the variable global or add it to build too. Not very hard to change.<br />
<br />
:: [[User:Morganamilo|Morganamilo]] ([[User talk:Morganamilo|talk]]) 15:46, 24 August 2019 (UTC)<br />
<br />
::: I agree with [[User:Alad|Alad]], that this should go as a warning/note on the [[PKGBUILD]]/ [[Creating packages]] page, as it doesn't make much sense to try to enforce this (it's kinda common sense, when writing bash). Therefore a warning for people new to writing/using bash would be the better idea here (maybe even with a link to how to use local variables, e.g. http://www.tldp.org/LDP/abs/html/localvar.html).<br />
::: [[User:Davezerave|Davezerave]] ([[User talk:Davezerave|talk]]) 16:54, 25 August 2019 (UTC)<br />
<br />
::For what it's worth, devtools does explicitly support using --noextract or --repackage with makechrootpkg, and I've used it before for repository packages which have non-deterministically failing testsuites in order to rerun the test until it succeeds (so, like two or three times) and then run package(). So I would say that the official repos '''do''' need to support these flags. [[User:Eschwartz|Eschwartz]] ([[User talk:Eschwartz|talk]]) 17:58, 25 August 2019 (UTC)<br />
<br />
== What does it mean: Stable packages package stable releases ==<br />
<br />
[[Special:Diff/581167]] added:<br />
:'''Stable packages package stable releases''': Release candidates (...)"<br />
<br />
What is supposed to be '''Stable packages releases'''? -- [[User:Josephgbr|Josephgbr]] ([[User talk:Josephgbr|talk]]) 14:23, 8 October 2019 (UTC)<br />
<br />
:Here's my attempt of breaking the sentence down in parts:<br />
:; Stable packages: packages that are in the [[Official repositories#Stable repositories|stable repositories]] (core/extra/community) and not in [[testing]] (or staging) repositories.<br />
:; package: verb; place in a package file ({{ic|*.pkg.tar(.*)}}).<br />
:; stable releases: versions of the software deemed stable by upstream , i.e. not [[w:Software versioning#Pre-release versions|pre-releases, development releases, etc.]].<br />
: -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 17:13, 8 October 2019 (UTC)<br />
<br />
::: Ok, I see. Although it is grammatically correct, it looks a little bit weird. I could not tell why "stable" and "package" were repeated and it looked like an error. How about changing it to '''Stable packages provide stable release'''? We already use "provides" to say a package provides another package. -- [[User:Josephgbr|Josephgbr]] ([[User talk:Josephgbr|talk]]) 18:00, 8 October 2019 (UTC)<br />
<br />
== Package versioning: `v` prefix ==<br />
<br />
I've found various packages in AUR that include a `v` prefix in the `pkgver` (such as `v0.123.3-1`). To my understanding, this `v` prefix should be dropped. However, I could not find a rule on [[Arch package guidelines]] regarding such a prefix. Is there a rule? Should a rule be added to [[Arch_package_guidelines#Package_versioning]]? Thanks! –[[User:Simon04|Simon04]] ([[User talk:Simon04|talk]]) 15:21, 24 December 2019 (UTC)</div>Simon04https://wiki.archlinux.org/index.php?title=Lenovo_ThinkPad_T470s&diff=575160Lenovo ThinkPad T470s2019-06-11T14:19:40Z<p>Simon04: +Troubleshooting +BIOS/UEFI update</p>
<hr />
<div>[[Category:Lenovo]]<br />
[[ja:Lenovo ThinkPad T470s]]<br />
{| class="wikitable" style="float: right;"<br />
| '''Device''' || '''Status''' <br />
|-<br />
| [[Intel graphics]] || {{Yes}} <br />
|-<br />
| [[Wireless]] || {{Yes}}<br />
|-<br />
| Mobile Broadband || {{Yes}}<br />
|-<br />
| [[ALSA]] || {{Yes}}<br />
|-<br />
| [[TrackPoint]] || {{Yes}}<br />
|-<br />
| [[Touchpad]] || {{Yes}}<br />
|-<br />
| Smartcard Reader || {{Yes}}<br />
|-<br />
| [[Bluetooth]] || {{Yes}}<br />
|-<br />
| Fingerprint Reader || {{Yes}}<br />
|-<br />
|}<br />
<br />
This article covers the installation and configuration of Arch Linux on a Lenovo T470s laptop.<br />
<br />
For a general overview of laptop-related articles and recommendations, see [[Laptop]].<br />
<br />
== firmware (e.g. bios and peripherals) ==<br />
<br />
As of writing, the current bios version is 1.30. By visiting the downloads section (for the type HG/HF T470s) an iso can be downloaded and burned to disk which will perform the update [http://pcsupport.lenovo.com/us/en/products/laptops-and-netbooks/thinkpad-t-series-laptops/thinkpad-t470s/downloads]<br />
<br />
This laptop is unique in that it retains the thinkpad dock connection as well as provides docking ability over USB-C. We have tested with the [http://www.thinkwiki.org/wiki/ThinkPad_Ultra_Dock Thinkpad Ultra Dock] and are able to utilize multiple HiDPI monitors via individual connections (e.g. no display port chaining). There are published [https://support.lenovo.com/us/en/solutions/pd014572 firmware updates] for the dock that require windows to install. DisplayPort chaining works via USB-C to DisplayPort adapter.<br />
<br />
== kernel and hardware support ==<br />
<br />
Installation with modern media puts you on Kernel 4.10.10-1, however [[Dell_XPS_13_(9360)#NVME_Power_Saving_Patch|this note]]{{Broken section link}} made {{AUR|linux-mainline}} seem essential.<br />
<br />
As advised in [[Intel graphics#Enable early KMS]] and [[Kernel mode setting]] you can add i915 to your modules.<br />
<br />
[[Hardware video acceleration]] with Kaby Lake seems to work fine via va-api.<br />
<br />
== mobile broadband ==<br />
<br />
The mobile broadband card is a [https://www.sierrawireless.com/products-and-solutions/embedded-solutions/networking-modules/ Sierra EM7455], which can be seen below in the lsusb. We have confirmed working with [https://fi.google.com Google's Project Fi].<br />
<br />
== lspci and lsusb ==<br />
<br />
On kernel '4.11.0-rc6-mainline' via {{AUR|linux-mainline}} on a ''20HG'' T470s<br />
<br />
=== lspci ===<br />
<br />
00:00.0 Host bridge: Intel Corporation Device 5904 (rev 02)<br />
00:02.0 VGA compatible controller: Intel Corporation Device 5916 (rev 02)<br />
00:14.0 USB controller: Intel Corporation Sunrise Point-LP USB 3.0 xHCI Controller (rev 21)<br />
00:14.2 Signal processing controller: Intel Corporation Sunrise Point-LP Thermal subsystem (rev 21)<br />
00:16.0 Communication controller: Intel Corporation Sunrise Point-LP CSME HECI #1 (rev 21)<br />
00:16.3 Serial controller: Intel Corporation Device 9d3d (rev 21)<br />
00:1c.0 PCI bridge: Intel Corporation Device 9d10 (rev f1)<br />
00:1c.2 PCI bridge: Intel Corporation Device 9d12 (rev f1)<br />
00:1d.0 PCI bridge: Intel Corporation Sunrise Point-LP PCI Express Root Port #9 (rev f1)<br />
00:1f.0 ISA bridge: Intel Corporation Device 9d4e (rev 21)<br />
00:1f.2 Memory controller: Intel Corporation Sunrise Point-LP PMC (rev 21)<br />
00:1f.3 Audio device: Intel Corporation Device 9d71 (rev 21)<br />
00:1f.4 SMBus: Intel Corporation Sunrise Point-LP SMBus (rev 21)<br />
00:1f.6 Ethernet controller: Intel Corporation Ethernet Connection (4) I219-LM (rev 21)<br />
3a:00.0 Network controller: Intel Corporation Device 24fd (rev 78)<br />
3c:00.0 Non-Volatile memory controller: Samsung Electronics Co Ltd Device a804<br />
<br />
=== lsusb ===<br />
<br />
Bus 002 Device 003: ID 0bda:0316 Realtek Semiconductor Corp. <br />
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub<br />
Bus 001 Device 006: ID 138a:0097 Validity Sensors, Inc. <br />
Bus 001 Device 005: ID 5986:111c Acer, Inc <br />
Bus 001 Device 008: ID 1199:9079 Sierra Wireless, Inc. <br />
Bus 001 Device 002: ID 058f:9540 Alcor Micro Corp. AU9540 Smartcard Reader<br />
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub<br />
<br />
== Configuration ==<br />
<br />
=== Smartcard Reader ===<br />
<br />
Bus 001 Device 002: ID 058f:9540 Alcor Micro Corp. AU9540 Smartcard Reader<br />
<br />
=== Fingerprint reader ===<br />
As of writing this, the fingerprint reader is still under [https://github.com/nmikhailov/Validity90 prototype development], but looks like working fine on the T470s.<br />
<br />
To get the sensor working, it first must be initialized with data. This currently only works with Windows. So if you had used the reader before installing Arch, this should work fine. Otherwise install a Windows version in a virtualbox, connect the Validity Sensor over USB(USB 2.0), install the drivers and use it a few times.<br />
<br />
As soon as this step is completed, the sensor can be used under Linux.<br />
Check out [https://github.com/nmikhailov/Validity90/tree/master/prototype Validity90 prototype], build it and check if the sensor is working.<br />
Install {{Pkg|fprintd}}, {{Aur|libfprint-vfs0097-git}} and for testing {{Aur|fprint_demo}}.<br />
You can now enroll your fingers. fprintd and fprint_demo might have be started with superuser privileges.<br />
<br />
After setting up the fingerprint sensor is complete, one can use it to login or authenticate for {{ic|sudo}} or {{ic|su}}(To use this, launch fprintd_enroll prior as root).<br />
<br />
For login edit {{ic|/etc/pam.d/login}}<br />
<br />
Add the following and comment out the other entrys<br />
<br />
auth required pam_env.so<br />
auth sufficient pam_fprintd.so<br />
auth sufficient pam_unix.so try_first_pass likeauth nullok<br />
auth required pam_deny.so<br />
<br />
Do the same for sudo with {{ic | /etc/pam.d/sudo}} or su with {{ic | /etc/pam.d/su}}<br />
<br />
For more information visit [https://github.com/3v1n0/libfprint libfprint] and adapt for the vfs0097 package. <br />
<br />
== Troubleshooting == <br />
<br />
=== Fan does not spin down after suspend-resume ===<br />
<br />
On {{Pkg|gnome-shell}} via [[wayland]], suspend-resume results in the fan holding at 100% without ever spinning down. Alternatively if you use [[xorg]] this doesn't seem to happen. This issue has been resolved in BIOS/UEFI version 1.20.<br />
<br />
== BIOS/UEFI update ==<br />
<br />
In order to update the BIOS/UEFI using a USB key, follow this procedure (based on [https://bugzilla.redhat.com/show_bug.cgi?id=1480844#c64]):<br />
<br />
# Install {{AUR|geteltorito}}<br />
# Download ISO "BIOS Update (Bootable CD)" from [https://pcsupport.lenovo.com/at/en/products/LAPTOPS-AND-NETBOOKS/THINKPAD-T-SERIES-LAPTOPS/THINKPAD-T470S/downloads/DS120418]<br />
# {{ic|geteltorito.pl -o bios.img n1wur26w.iso}}<br />
# {{ic|sudo dd if=bios.img of=<USB key> bs=1M<br />
<br />
== See also ==<br />
<br />
* [http://support.lenovo.com/us/en/products/Laptops-and-netbooks/ThinkPad-T-Series-laptops/ThinkPad-T470s?beta=false Lenovo Support Page]</div>Simon04https://wiki.archlinux.org/index.php?title=DeveloperWiki:ReproducibleBuilds&diff=571386DeveloperWiki:ReproducibleBuilds2019-04-16T21:28:22Z<p>Simon04: /* Reproducible Build Arch Update 09-12-2018 */ ref. to mailing list</p>
<hr />
<div>[[Category:DeveloperWiki]]<br />
A list of reproducible build meetings and work in progress documentation.<br />
<br />
[https://tests.reproducible-builds.org/archlinux/archlinux.html Reproducible build results]<br />
<br />
==Helping out==<br />
<br />
Arch Linux is currently in the process of having it 100% reproducible, for the exact definition of reproducible builds and it's benefits take a look at the [https://reproducible-builds.org/ project website].<br />
<br />
Arch users can help contribute to Reproducible Build issues by looking at the [https://tests.reproducible-builds.org/archlinux/archlinux.html continuous reproducing environment]. There are various issues which can be sorted out:<br />
<br />
* FTBS (failed to build from source): reproduce the build failure locally and create a bug report if the package can't be [[DeveloperWiki:Building_in_a_clean_chroot|built from a clean chroot]] (extra-x86_64-build or multilib-build).<br />
* Failed to download sources, reproduce the issue (makepkg -o -d) and create a bug report on the Arch bugtracker.<br />
* Failed to reproduce. Locally you can reproduce packages using {{pkg|reprotest}}. Note that not all variations can be used. For simple time related testing:<br />
reprotest --variations '+time' 'sudo extra-x86_64-build' '*.pkg.tar.xz' <br />
There might be various reasons for a package to not be reproducible, but before digging in take a look at the upstream repository or the reproducible status in [https://tests.reproducible-builds.org/debian/reproducible.html Debian]<br />
* Failed to run tests, these failures are heavily on the testing env. Most likely due to to LANG=C being set and Arch not supporting LANG=C.UTF-8<br />
<br />
<br />
If you are interested in the code which runs the continuous reproducing environment, the first build code starts here on [https://salsa.debian.org/qa/jenkins.debian.net/blob/master/bin/reproducible_build_archlinux_pkg.sh#L115 salsa]<br />
<br />
==To-do list==<br />
<br />
* Arch Linux Archive cleanup script<br />
* Arch Linux Reproducible script<br />
:* A script to locally reproduce an installed package<br />
* Resolve reproducible build issues<br />
* Documentation about reproducing a build<br />
<br />
==Reproducible Build Arch Update 09-12-2018 ==<br />
<br />
Posted to the [https://www.mail-archive.com/rb-general@lists.reproducible-builds.org/msg00104.html ''rb-general''] mailing list:<br />
<br />
{{Quote|1=<br />
As Bernhard did a wonderful writeup for the rpm ecosystem ahead of the Paris<br />
summit, we thought we should attempt the same thing. We have summarized the work<br />
Arch Linux has done towards reproducible builds the past year(s). Hopefully it<br />
will be somewhat interesting! Feel free to ask if there are any questions.<br />
<br />
1. Pacman<br />
2. BUILDINFO<br />
3. The repro tool<br />
4. Reproducible Builds environment<br />
5. Packaging<br />
<br />
=== Pacman ===<br />
<br />
Support for SOURCE_DATE_EPOCH was added to makepkg in May of 2017 [1]. makepkg <br />
is<br />
the tool used to create packages from PKGBUILD files. After some testing it was<br />
later discovered that we also needed to make sure that files inside packages<br />
need to have the correct time, as build artifacts sometimes embed the<br />
timestamps [2]. In May 2018 we released pacman 5.1.0 which included support for<br />
reproducible builds.<br />
<br />
[1]: <br />
https://git.archlinux.org/pacman.git/commit/?id=d30878763ce1b5be453b563f2729d7333242e79b<br />
[2]: <br />
https://git.archlinux.org/pacman.git/commit/?id=4dae3fde17d663bf39a17978c2ee365696a54fb0<br />
<br />
=== BUILDINFO ===<br />
<br />
Recording of build information in a .BUILDINFO file was added to pacman in<br />
2015[1].<br />
<br />
The intial file included:<br />
- builddir<br />
- pkgbuild_sha256sum<br />
- buildenv (makepkg configuration option which affects the build <br />
environment)<br />
- options (options which affect packaging, removing debug symbols, <br />
staticlibs, etc.)<br />
- installed<br />
<br />
<br />
The initial file was expanded in 2017 with the following fields[2]:<br />
- format (version of buildinfo file format)<br />
- pkgname<br />
- pkgbase<br />
- pkgver<br />
- packager<br />
- builddate<br />
<br />
In 2018 a man page was written which describes the BUILDINFO file [3].<br />
<br />
During development of tools to reproduce packages, we discovered the BUILDINFO<br />
file was lacking the architecture information of installed packages. As Arch<br />
Linux produces packages with different architectures, such as 'x86_64' and<br />
'any', we had to guess the architecture of the package when fetching from our<br />
archive. This was subsequently fixed. [4]<br />
<br />
[1]: <br />
https://git.archlinux.org/pacman.git/commit/?id=137ea39fa11c321a9c33000ff1b5c6cc3c59b47d<br />
[2]: <br />
https://git.archlinux.org/pacman.git/commit/?id=c44c649a5280189ea28a54b82e60fc38279fed23<br />
[3]: <br />
https://git.archlinux.org/pacman.git/commit/?id=a7dbe4635b4af9b5bd927ec0e7a211d1f6c1b0f2<br />
[4]: <br />
https://git.archlinux.org/pacman.git/commit/?id=f173f6d0da3793952691416d80441b46af12fc94<br />
<br />
=== The repro tool ===<br />
<br />
repro is a tool to aid in verification of Arch Linux packages. It creates a<br />
chroot, fetches the correct PKGBUILD and installs the needed dependencies as<br />
described by a BUILDINFO file.<br />
<br />
The tool has the following goals:<br />
- Easily auditable<br />
- Distribution independent<br />
- Do not duplicate features from other tools, like reprotest[2].<br />
<br />
This helps us in making it easier for users, or other interested parties, to<br />
audit Arch packages in the future. It is currently very much a work in progress,<br />
however it is capable of reproducing archive packages in its current state.<br />
<br />
[1]: https://github.com/archlinux/archlinux-repro<br />
[2]: https://salsa.debian.org/reproducible-builds/reprotest<br />
<br />
=== Reproducible Builds environment ===<br />
<br />
The continuous reproducing environment has been continuously improved by Holger <br />
and<br />
numerous others. It now uses a database to render the HTML pages which allows<br />
showing the reproducibility status. We have also donated some servers which<br />
where sponsored by Private Internet Access to help reproduce packages.<br />
<br />
https://tests.reproducible-builds.org/archlinux/archlinux.html<br />
<br />
=== Packaging ===<br />
<br />
As for packaging, Arch tries to be as vanilla as possible and therefore does not<br />
patch packages specifically for reproducible builds and tries to upstream the<br />
found issues instead. There are some issues with the actual packaging which<br />
made packages reproducible, for example convert was used in PKGBUILDs to convert<br />
images to a different format mostly for for desktop files. Imagemagick's<br />
convert by default is not reproducible since it embeds dates in the converted<br />
files, this was fixed in our PKGBUILDs. [1]<br />
<br />
Another issue was found using the repro tool with our SVN propsets making it<br />
unreproducible, the propsets are now removed from our PKGBUILDs - also due to<br />
not being useful anymore. [2]<br />
<br />
Apart from these issues, numerous 404 sources have been fixed (since Arch does<br />
not mirror the upstream source tarballs) and fixed FTBS packages, especially for<br />
the [core] repository.<br />
<br />
[1]: <br />
https://git.archlinux.org/svntogit/community.git/tree/trunk/PKGBUILD?h=packages/bt747<br />
[2]: https://www.mail-archive.com/arch-dev-public@archlinux.org/msg25744.html<br />
}}<br />
<br />
==Agenda meeting 10-01-2018==<br />
<br />
* UTF-8 failures with Python.<br />
*: There are a lot of reproducible build issues due to the lack of LANG=$lang-UTF-8. Do we need to explicitly set the LANG in the PKGBUILD<br />
*: See for example https://tests.reproducible-builds.org/archlinux/community/python-cssselect2/build1.log<br />
* Package disorderfs<br />
*: Not high important right now, I've added it on my todolist. This could be used later in combination with the reproducible build script<br />
* Pacman release<br />
*: How do we convince the Pacman team to create a new release, are there any known blockers they waiting on? <br />
* Reproducible build script progress<br />
*: Discuss what the script exactly should do, create an RFC? To describe it's functionality.<br />
*: FIXME: add issues I encountered.<br />
* Arch Linux Archive: Don't remove packages mentioned in BUILDINFO file<br />
*: There is currently no script to remove old packages from the archive, it is not sure how long we want to keep old packges<br />
*: Sangy was working on this if I recall correctly, what is the status? [https://github.com/SantiagoTorres/reproarch-dependency-crawler poc script]<br />
<br />
*: Write documentation what this script should do. (Specification)<br />
* Killed builds<br />
*: Someone should investigate this, how do we reproduce this locally? Hints?<br />
* SSL verification issues<br />
*: How do we circumvent SSL issues from reproducing a package locally which was build earlier, when the SSL certificate was valid. HG and SVN are still left to be fixed.<br />
* Create a public to-do list<br />
*: We should get more people in to work on reproducible builds, how can we guide them and where do we keep track of the progress made and issues which require attention.<br />
<br />
The meeting minute can be seen [https://arch.nyu.wtf/logs/archlinux-reproducible/2018/archlinux-reproducible.2018-01-10-19.04.html here]{{Dead link|2018|11|04}}.</div>Simon04https://wiki.archlinux.org/index.php?title=SSH_keys&diff=563183SSH keys2019-01-13T21:59:55Z<p>Simon04: /* Managing multiple keys */ not best practice → controversial</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[es:SSH keys]]<br />
[[it:SSH keys]]<br />
[[ja:SSH 鍵]]<br />
[[ru:SSH keys]]<br />
[[sr:SSH keys]]<br />
[[zh-hans:SSH keys]]<br />
{{Expansion|The intro and ''Background'' section ignore the server perspective.}}<br />
<br />
SSH keys can serve as a means of identifying yourself to an SSH server using [[Wikipedia:Public-key cryptography|public-key cryptography]] and [[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]<br />
<br />
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.<br />
<br />
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. <br />
<br />
This article assumes you already have a basic understanding of the [[Secure Shell]] protocol and have [[install]]ed the {{Pkg|openssh}} package.<br />
<br />
== Background ==<br />
<br />
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.<br />
<br />
If an SSH server has your 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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
== Generating an SSH key pair ==<br />
<br />
An SSH key pair can be generated by running the {{ic|ssh-keygen}} command, defaulting to 2048-bit RSA (and SHA256) which the {{man|1|ssh-keygen}} man page says is "''generally considered sufficient''" and should be compatible with virtually all clients and servers:<br />
<br />
{{hc<br />
|$ ssh-keygen<br />
|<nowiki>Generating public/private rsa key pair.<br />
Enter file in which to save the key (/home/<username>/.ssh/id_rsa): <br />
Enter passphrase (empty for no passphrase): <br />
Enter same passphrase again: <br />
Your identification has been saved in /home/<username>/.ssh/id_rsa.<br />
Your public key has been saved in /home/<username>/.ssh/id_rsa.pub.<br />
The key fingerprint is:<br />
SHA256:gGJtSsV8BM+7w018d39Ji57F8iO6c0N2GZq3/RY2NhI username@hostname<br />
The key's randomart image is:<br />
+---[RSA 2048]----+<br />
| ooo. |<br />
| oo+. |<br />
| + +.+ |<br />
| o + + E . |<br />
| . . S . . =.o|<br />
| . + . . B+@o|<br />
| + . oo*=O|<br />
| . ..+=o+|<br />
| o=ooo+|<br />
+----[SHA256]-----+</nowiki>}}<br />
<br />
The [http://www.cs.berkeley.edu/~dawnsong/papers/randomart.pdf randomart image] was [http://www.openssh.com/txt/release-5.1 introduced in OpenSSH 5.1] as an easier means of visually identifying the key fingerprint.<br />
<br />
{{Note|If you set a passphrase for your key, it is ''strongly encouraged'' to use the {{ic|-o}} option to ''ssh-keygen''. This will save your private key in the new OpenSSH format, which has greatly increased resistance to brute-force password cracking, but is not supported by versions of OpenSSH prior to 6.5. According to {{man|1|ssh-keygen}}, Ed25519 keys always use the new private key format. Also use the {{ic|-a}} switch to specify the number of KDF rounds on the password encryption.}}<br />
<br />
You can also add an optional comment field to the public key with the {{ic|-C}} switch, to more easily identify it in places such as {{ic|~/.ssh/known_hosts}}, {{ic|~/.ssh/authorized_keys}} and {{ic|ssh-add -L}} output. For example:<br />
<br />
$ ssh-keygen -C "$(whoami)@$(hostname)-$(date -I)"<br />
<br />
will add a comment saying which user created the key on which machine and when.<br />
<br />
=== Choosing the authentication key type ===<br />
<br />
OpenSSH supports several signing algorithms (for authentication keys) which can be divided in two groups depending on the mathematical properties they exploit:<br />
<br />
# [[Wikipedia:Digital_Signature_Algorithm|DSA]] and [[Wikipedia:RSA_(cryptosystem)|RSA]], which rely on the [[wikipedia:Integer_factorization#Difficulty_and_complexity|practical difficulty]] of factoring the product of two large prime numbers,<br />
# [[Wikipedia:Elliptic_Curve_Digital_Signature_Algorithm|ECDSA]] and [[Wikipedia:Curve25519|Ed25519]], which rely on the elliptic curve [[Wikipedia:Discrete_logarithm|discrete logarithm]] problem. ([https://www.certicom.com/content/certicom/en/52-the-elliptic-curve-discrete-logarithm-problem.html example])<br />
<br />
[https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/ Elliptic curve cryptography] (ECC) algorithms are a [[Wikipedia:Elliptic_curve_cryptography#History|more recent addition]] to public key cryptosystems. One of their main advantages is their ability to provide [[Wikipedia:Elliptic_curve_cryptography#Rationale|the same level of security with smaller keys]], which makes for less computationally intensive operations (''i.e.'' faster key creation, encryption and decryption) and reduced storage and transmission requirements.<br />
<br />
OpenSSH 7.0 [https://www.archlinux.org/news/openssh-70p1-deprecates-ssh-dss-keys/ deprecated and disabled support for DSA keys] due to discovered vulnerabilities, therefore the choice of [[Wikipedia:cryptosystem|cryptosystem]] lies within RSA or one of the two types of ECC.<br />
<br />
[[#RSA]] keys will give you the greatest portability, while [[#Ed25519]] will give you the best security but requires recent versions of client & server[https://www.gentoo.org/support/news-items/2015-08-13-openssh-weak-keys.html]. [[#ECDSA]] is likely more compatible than Ed25519 (though still less than RSA), but suspicions exist about its security (see below).<br />
<br />
{{Note|These keys are used only to authenticate you; choosing stronger keys will not increase CPU load when transferring data over SSH.<br />
}}<br />
<br />
==== RSA ====<br />
<br />
{{ic|ssh-keygen}} defaults to RSA therefore there is no need to specify it with the {{ic|-t}} option. It provides the best compatibility of all algorithms but requires the key size to be larger to provide sufficient security.<br />
<br />
Minimum key size is 1024 bits, default is 2048 (see {{man|1|ssh-keygen}}) and maximum is 16384.<br />
<br />
If you wish to generate a stronger RSA key pair (''e.g.'' to guard against cutting-edge or unknown attacks and more sophisticated attackers), simply specify the {{ic|-b}} option with a higher bit value than the default:<br />
<br />
{{hc<br />
|$ ssh-keygen -b 4096<br />
|<nowiki>Generating public/private rsa key pair.<br />
Enter file in which to save the key (/home/<username>/.ssh/id_rsa):<br />
Enter passphrase (empty for no passphrase):<br />
Enter same passphrase again:<br />
Your identification has been saved in /home/<username>/.ssh/id_rsa.<br />
Your public key has been saved in /home/<username>/.ssh/id_rsa.pub.<br />
The key fingerprint is:<br />
SHA256:+Pqo84NC+vAQQ9lUV0z+/zPHsyCe8oZpy6hLkIa7qfk <username>@<hostname><br />
The key's randomart image is:<br />
+---[RSA 4096]----+<br />
| ... .+o |<br />
| + . .. |<br />
| o . . |<br />
|. . . . . |<br />
|o. + . S . |<br />
| o+ . . . |<br />
|o+ o . o. o . |<br />
|.=+ + .oo=..o o+o|<br />
|+=E..**+oo=+ o*|<br />
+----[SHA256]-----+</nowiki>}}<br />
<br />
Be aware though that there are diminishing returns in using longer keys.[https://security.stackexchange.com/a/25377][https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096] The GnuPG FAQ reads: "''If you need more security than RSA-2048 offers, the way to go would be to switch to elliptical curve cryptography — not to continue using RSA''".[https://www.gnupg.org/faq/gnupg-faq.html#please_use_ecc]<br />
<br />
On the other hand, the latest iteration of the [https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml NSA Fact Sheet Suite B Cryptography] suggests a minimum 3072-bit modulus for RSA while "''[preparing] for the upcoming quantum resistant algorithm transition''".[http://www.keylength.com/en/6/]<br />
<br />
==== ECDSA ====<br />
<br />
The Elliptic Curve Digital Signature Algorithm (ECDSA) was introduced as the preferred algorithm for authentication [http://www.openssh.com/txt/release-5.7 in OpenSSH 5.7]. Some vendors also disable the required implementations due to potential patent issues.<br />
<br />
There are two sorts of concerns with it:<br />
<br />
# ''Political concerns'', the trustworthiness of NIST-produced curves [https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters being questioned] after revelations that the NSA willingly inserts backdoors into softwares, hardware components and published standards were made; well-known cryptographers [https://www.schneier.com/blog/archives/2013/09/the_nsa_is_brea.html#c1675929 have] [http://safecurves.cr.yp.to/rigid.html expressed] [https://www.hyperelliptic.org/tanja/vortraege/20130531.pdf doubts] about how the NIST curves were designed, and voluntary tainting has already [https://www.schneier.com/blog/archives/2007/11/the_strange_sto.html been] [http://www.scientificamerican.com/article/nsa-nist-encryption-scandal/ proved] in the past.<br />
# ''Technical concerns'', about the [http://blog.cr.yp.to/20140323-ecdsa.html difficulty to properly implement the standard] and the [http://www.gossamer-threads.com/lists/openssh/dev/57162#57162 slowness and design flaws] which reduce security in insufficiently precautious implementations. <br />
<br />
Both of those concerns are best summarized in [https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt#n4 libssh curve25519 introduction]. Although the political concerns are still subject to debate, there is a [https://news.ycombinator.com/item?id=7597653 clear consensus] that [[#Ed25519]] is technically superior and should therefore be preferred.<br />
<br />
==== Ed25519 ====<br />
<br />
[http://ed25519.cr.yp.to/ Ed25519] was introduced in [http://www.openssh.com/txt/release-6.5 OpenSSH 6.5] of January 2014: "''Ed25519 is an elliptic curve signature scheme that offers better security than ECDSA and DSA and good performance''". Its main strengths are its speed, its constant-time run time (and resistance against side-channel attacks), and its lack of nebulous hard-coded constants.[https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt] See also [https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/ this blog post] by a Mozilla developer on how it works.<br />
<br />
It is already implemented in [[Wikipedia:Curve25519#Popularity|many applications and libraries]] and is the [https://www.libssh.org/2013/11/03/openssh-introduces-curve25519-sha256libssh-org-key-exchange/ default key exchange algorithm] (which is different from key ''signature'') in OpenSSH.<br />
<br />
Ed25519 key pairs can be generated with:<br />
<br />
$ ssh-keygen -t ed25519<br />
<br />
There is no need to set the key size, as all Ed25519 keys are 256 bits. Also, they rely on a [http://www.gossamer-threads.com/lists/openssh/dev/57162#57162 new key format] which "''uses a bcrypt-based key derivation function that makes brute-force attacks against stolen private keys far slower''".<br />
<br />
For those reasons, compatibility with older versions of OpenSSH or [[SSH|other SSH clients and servers]] may prove troublesome.<br />
<br />
=== Choosing the key location and passphrase ===<br />
<br />
Upon issuing the {{ic|ssh-keygen}} command, you will be prompted for the desired name and location of your private key. By default, keys are stored in the {{ic|~/.ssh/}} directory and named according to the type of encryption used. You are advised to accept the default name and location in order for later code examples in this article to work properly.<br />
<br />
When prompted for a passphrase, choose something that will be hard to guess if you have the security of your private key in mind. A longer, more random password will generally be stronger and harder to crack should it fall into the wrong hands.<br />
<br />
It is also possible to create your private key without a passphrase. While this can be convenient, you need to be aware of the associated risks. Without a passphrase, your private key will be stored on disk in an unencrypted form. Anyone who gains access to your private key file will then be able to assume your identity on any SSH server to which you connect using key-based authentication. Furthermore, without a passphrase, you must also trust the root user, as he can bypass file permissions and will be able to access your unencrypted private key file at any time.<br />
<br />
{{Note|The old, default password encoding for ''ssh'' private keys '''is insecure'''; it is only a single round of an MD5 hash. Since OpenSSH version 6.5, use the {{ic|-o}} option to {{ic|ssh-keygen}} to encode your private key in a new, more secure format.}}<br />
<br />
==== Changing the private key's passphrase without changing the key ====<br />
If the originally chosen SSH key passphrase is undesirable or must be changed, one can use the {{ic|ssh-keygen}} command to change the passphrase without changing the actual key.<br />
<br />
To upgrade your private RSA key to use the more secure password encryption format, and also change the passphrase, run the following command:<br />
$ ssh-keygen -o -f ~/.ssh/id_rsa -p<br />
<br />
Otherwise, to use the old key format, run the following command:<br />
$ ssh-keygen -f ~/.ssh/id_rsa -p<br />
<br />
==== Managing multiple keys ====<br />
<br />
It is possible — although controversial [https://security.stackexchange.com/questions/40050/best-practice-separate-ssh-key-per-host-and-user-vs-one-ssh-key-for-all-hos] [https://security.stackexchange.com/questions/10963/whats-the-common-pragmatic-strategy-for-managing-key-pairs] — to use the same SSH key pair for multiple hosts.<br />
<br />
On the other hand, it is rather easy to maintain distinct keys for multiple hosts by using the {{ic|IdentityFile}} directive in your openSSH config file:<br />
<br />
{{hc|~/.ssh/config|<br />
Host SERVER1<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_rsa_SERVER1<br />
<br />
Host SERVER2<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_ed25519_SERVER2<br />
}}<br />
<br />
See {{man|5|ssh_config}} for full description of these options.<br />
<br />
==== Storing SSH keys on hardware tokens ====<br />
<br />
SSH keys can also be stored on a security token like a smart card or a USB token. This has the advantage that the private key is stored securely on the token instead of being stored on disk. When using a security token the sensitive private key is also never present in the RAM of the PC; the cryptographic operations are performed on the token itself. A cryptographic token has the additional advantage that it is not bound to a single computer; it can easily be removed from the computer and carried around to be used on other computers.<br />
<br />
Examples are hardware tokens are described in:<br />
<br />
* [[YubiKey#Using a YubiKey with SSH]], and<br />
* [[Trusted Platform Module#Securing SSH Keys]]<br />
<br />
==Copying the public key to the remote server==<br />
<br />
{{Expansion|How to do this if you [[OpenSSH#Force public key authentication|force public key authentication]]?}}<br />
<br />
Once you have generated a key pair, you will need to copy the public key to the remote server so that it will use SSH key authentication. The public key file shares the same name as the private key except that it is appended with a {{ic|.pub}} extension. Note that the private key is not shared and remains on the local machine.<br />
<br />
=== Simple method ===<br />
<br />
{{Note|1=This method might fail if the remote server uses a non-{{ic|sh}} shell such as {{ic|tcsh}} as default and uses OpenSSH older than 6.6.1p1. See [https://bugzilla.redhat.com/show_bug.cgi?id=1045191 this bug report].}}<br />
<br />
If your key file is {{ic|~/.ssh/id_rsa.pub}} you can simply enter the following command.<br />
<br />
$ ssh-copy-id remote-server.org<br />
<br />
If your username differs on remote machine, be sure to prepend the username followed by {{ic|@}} to the server name.<br />
<br />
$ ssh-copy-id username@remote-server.org<br />
<br />
If your public key filename is anything other than the default of {{ic|~/.ssh/id_rsa.pub}} you will get an error stating {{ic|/usr/bin/ssh-copy-id: ERROR: No identities found}}. In this case, you must explicitly provide the location of the public key.<br />
<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub username@remote-server.org<br />
<br />
If the ssh server is listening on a port other than default of 22, be sure to include it within the host argument.<br />
<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 221 username@remote-server.org<br />
<br />
=== Manual method ===<br />
<br />
By default, for OpenSSH, the public key needs to be concatenated with {{ic|~/.ssh/authorized_keys}}. Begin by copying the public key to the remote server.<br />
<br />
$ scp ~/.ssh/id_ecdsa.pub username@remote-server.org:<br />
<br />
The above example copies the public key ({{ic|id_ecdsa.pub}}) to your home directory on the remote server via {{ic|scp}}. Do not forget to include the {{ic|:}} at the end of the server address. Also note that the name of your public key may differ from the example given.<br />
<br />
On the remote server, you will need to create the {{ic|~/.ssh}} directory if it does not yet exist and append your public key to the {{ic|authorized_keys}} file.<br />
<br />
$ ssh username@remote-server.org<br />
username@remote-server.org's password:<br />
$ mkdir ~/.ssh<br />
$ chmod 700 ~/.ssh<br />
$ cat ~/id_ecdsa.pub >> ~/.ssh/authorized_keys<br />
$ rm ~/id_ecdsa.pub<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
The last two commands remove the public key file from the server and set the permissions on the {{ic|authorized_keys}} file such that it is only readable and writable by you, the owner.<br />
<br />
== SSH agents ==<br />
<br />
If your private key is encrypted with a passphrase, this passphrase must be entered every time you attempt to connect to an SSH server using public-key authentication. Each individual invocation of {{ic|ssh}} or {{ic|scp}} will need the passphrase in order to decrypt your private key before authentication can proceed.<br />
<br />
An SSH agent is a program which caches your decrypted private keys and provides them to SSH client programs on your behalf. In this arrangement, you must only provide your passphrase once, when adding your private key to the agent's cache. This facility can be of great convenience when making frequent SSH connections.<br />
<br />
An agent is typically configured to run automatically upon login and persist for the duration of your login session. A variety of agents, front-ends, and configurations exist to achieve this effect. This section provides an overview of a number of different solutions which can be adapted to meet your specific needs.<br />
<br />
=== ssh-agent ===<br />
<br />
{{ic|ssh-agent}} is the default agent included with OpenSSH. It can be used directly or serve as the back-end to a few of the front-end solutions mentioned later in this section. When {{ic|ssh-agent}} is run, it forks to background and prints necessary environment variables. E.g.<br />
<br />
{{hc|$ ssh-agent|2=<br />
SSH_AUTH_SOCK=/tmp/ssh-vEGjCM2147/agent.2147; export SSH_AUTH_SOCK;<br />
SSH_AGENT_PID=2148; export SSH_AGENT_PID;<br />
echo Agent pid 2148;<br />
}}<br />
<br />
To make use of these variables, run the command through the {{ic|eval}} command.<br />
<br />
{{hc|$ eval $(ssh-agent)|<br />
Agent pid 2157<br />
}}<br />
<br />
Once {{ic|ssh-agent}} is running, you will need to add your private key to its cache:<br />
<br />
{{hc|$ ssh-add ~/.ssh/id_ed25519|<br />
Enter passphrase for /home/user/.ssh/id_ed25519:<br />
Identity added: /home/user/.ssh/id_ed25519 (/home/user/.ssh/id_ed25519)<br />
}}<br />
<br />
If your private key is encrypted, {{ic|ssh-add}} will prompt you to enter your passphrase. Once your private key has been successfully added to the agent you will be able to make SSH connections without having to enter your passphrase.<br />
<br />
{{Tip|To make all {{ic|ssh}} clients, including {{ic|git}} store keys in the agent on first use, add the configuration setting {{ic|AddKeysToAgent yes}} to {{ic|~/.ssh/config}}. Other possible values are {{ic|confirm}}, {{ic|ask}} and {{ic|no}} (default).}}<br />
<br />
In order to start the agent automatically and make sure that only one {{ic|ssh-agent}} process runs at a time, add the following to your {{ic|~/.bashrc}}:<br />
<br />
{{bc|<nowiki><br />
if ! pgrep -u "$USER" ssh-agent > /dev/null; then<br />
ssh-agent > ~/.ssh-agent-thing<br />
fi<br />
if [[ "$SSH_AGENT_PID" == "" ]]; then<br />
eval "$(<~/.ssh-agent-thing)"<br />
fi<br />
</nowiki>}}<br />
<br />
This will run a {{ic|ssh-agent}} process if there is not one already, and save the output thereof. If there is one running already, we retrieve the cached {{ic|ssh-agent}} output and evaluate it which will set the necessary environment variables.<br />
<br />
There also exist a number of front-ends to {{ic|ssh-agent}} and alternative agents described later in this section which avoid this problem.<br />
<br />
==== Start ssh-agent with systemd user ====<br />
<br />
It is possible to use the [[systemd/User]] facilities to start the agent.<br />
<br />
{{hc|~/.config/systemd/user/ssh-agent.service|<nowiki><br />
[Unit]<br />
Description=SSH key agent<br />
<br />
[Service]<br />
Type=simple<br />
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket<br />
ExecStart=/usr/bin/ssh-agent -D -a $SSH_AUTH_SOCK<br />
<br />
[Install]<br />
WantedBy=</nowiki>''default''.target<br />
}}<br />
<br />
Add {{ic|1=SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/ssh-agent.socket"}} to {{ic|~/.pam_environment}}. Then [[enable]] or [[start]] the service.<br />
<br />
{{Note|If you use GNOME, this environment variable is overridden by default. See [[GNOME/Keyring#Disable keyring daemon components]].}}<br />
<br />
==== ssh-agent as a wrapper program ====<br />
<br />
An alternative way to start ssh-agent (with, say, each X session) is described in [http://upc.lbl.gov/docs/user/sshagent.shtml this ssh-agent tutorial by UC Berkeley Labs]. A basic use case is if you normally begin X with the {{ic|startx}} command, you can instead prefix it with {{ic|ssh-agent}} like so:<br />
<br />
$ ssh-agent startx<br />
<br />
And so you do not even need to think about it you can put an alias in your {{ic|.bash_aliases}} file or equivalent:<br />
<br />
alias startx='ssh-agent startx'<br />
<br />
Doing it this way avoids the problem of having extraneous {{ic|ssh-agent}} instances floating around between login sessions. Exactly one instance will live and die with the entire X session.<br />
<br />
{{Note|As an alternative to calling {{ic|ssh-agent startx}}, you can add {{ic|eval $(ssh-agent)}} to {{ic|~/.xinitrc}}.}}<br />
<br />
See [[#Calling x11-ssh-askpass with ssh-add|the below notes on using x11-ssh-askpass with ssh-add]] for an idea on how to immediately add your key to the agent.<br />
<br />
=== GnuPG Agent ===<br />
<br />
The [[GnuPG#gpg-agent|gpg-agent]] has OpenSSH agent emulation. See [[GnuPG#SSH agent]] for necessary configuration.<br />
<br />
=== Keychain ===<br />
<br />
[http://www.funtoo.org/Keychain Keychain] is a program designed to help you easily manage your SSH keys with minimal user interaction. It is implemented as a shell script which drives both ''ssh-agent'' and ''ssh-add''. A notable feature of Keychain is that it can maintain a single ''ssh-agent'' process across multiple login sessions. This means that you only need to enter your passphrase once each time your local machine is booted.<br />
<br />
==== Installation ====<br />
<br />
[[Install]] the {{Pkg|keychain}} package.<br />
<br />
==== Configuration ====<br />
<br />
{{Warning|As of 2015-09-26, the {{ic|-Q, --quick}} option has the unexpected side-effect of making ''keychain'' switch to a newly-spawned ''ssh-agent'' upon relogin (at least on systems using [[GNOME]]), forcing you to re-add all the previously registered keys.}}<br />
<br />
Add a line similar to the following to your [[shell]] configuration file, ''e.g.'' if using [[Bash]]:<br />
<br />
{{hc|~/.bashrc|<br />
eval $(keychain --eval --quiet id_ed25519 id_rsa ~/.keys/my_custom_key)<br />
}}<br />
<br />
{{Note|{{ic|~/.bashrc}} is used instead of the upstream suggested {{ic|~/.bash_profile}} because on Arch it is sourced by both login and non-login shells, making it suitable for textual and graphical environments alike. See [[Bash#Invocation]] for more information on the difference between those.}}<br />
<br />
In the above example,<br />
* the {{ic|--eval}} switch outputs lines to be evaluated by the opening {{ic|eval}} command; this sets the necessary environments variables for SSH client to be able to find your agent.<br />
* {{ic|--quiet}} will limit output to warnings, errors, and user prompts.<br />
<br />
Multiple keys can be specified on the command line, as shown in the example. By default keychain will look for key pairs in the {{ic|~/.ssh/}} directory, but absolute path can be used for keys in non-standard location. You may also use the {{ic|--confhost}} option to inform keychain to look in {{ic|~/.ssh/config}} for {{ic|IdentityFile}} settings defined for particular hosts, and use these paths to locate keys.<br />
<br />
See {{ic|keychain --help}} or {{man|1|keychain}} for details on setting ''keychain'' for other shells.<br />
<br />
To test Keychain, simply open a new terminal emulator or log out and back in your session. It should prompt you for the passphrase of the specified private key(s) (if applicable), either using the program set in {{ic|$SSH_ASKPASS}} or on the terminal.<br />
<br />
Because Keychain reuses the same ''ssh-agent'' process on successive logins, you should not have to enter your passphrase the next time you log in or open a new terminal. You will only be prompted for your passphrase once each time the machine is rebooted.<br />
<br />
==== Tips ====<br />
<br />
* ''keychain'' expects public key files to exist in the same directory as their private counterparts, with a {{ic|.pub}} extension. If the private key is a symlink, the public key can be found alongside the symlink or in the same directory as the symlink target (this capability requires the {{ic|readlink}} command to be available on the system).<br />
<br />
*to disable the graphical prompt and always enter your passphrase on the terminal, use the {{ic|--nogui}} option. This allows to copy-paste long passphrases from a password manager for example.<br />
<br />
*if you do not want to be immediately prompted for unlocking the keys but rather wait until they are needed, use the {{ic|--noask}} option.<br />
<br />
{{Note|Keychain is able to manage [[GPG]] keys in the same fashion. By default it attempts to start ''ssh-agent'' only, but you can modify this behavior using the {{ic|--agents}} option, ''e.g.'' {{ic|--agents ssh,gpg}}. See {{man|1|keychain}}.}}<br />
<br />
=== x11-ssh-askpass ===<br />
<br />
The {{pkg|x11-ssh-askpass}} package provides a graphical dialog for entering your passhrase when running an X session. ''x11-ssh-askpass'' depends only on the {{Pkg|libx11}} and {{Pkg|libxt}} libraries, and the appearance of ''x11-ssh-askpass'' is customizable. While it can be invoked by the ''ssh-add'' program, which will then load your decrypted keys into [[#ssh-agent|ssh-agent]], the following instructions will, instead, configure ''x11-ssh-askpass'' to be invoked by the aforementioned [[#Keychain|Keychain]] script.<br />
<br />
Install the {{Pkg|keychain}} and {{Pkg|x11-ssh-askpass}} packages.<br />
<br />
Edit your {{ic|~/.xinitrc}} file to include the following lines, replacing the name and location of your private key if necessary. Be sure to place these commands '''before''' the line which invokes your window manager.<br />
<br />
{{hc|~/.xinitrc|<br />
keychain ~/.ssh/id_ecdsa<br />
[ -f ~/.keychain/$HOSTNAME-sh ] && . ~/.keychain/$HOSTNAME-sh 2>/dev/null<br />
[ -f ~/.keychain/$HOSTNAME-sh-gpg ] && . ~/.keychain/$HOSTNAME-sh-gpg 2>/dev/null<br />
...<br />
exec openbox-session}}<br />
<br />
In the above example, the first line invokes ''keychain'' and passes the name and location of your private key. If this is not the first time ''keychain'' was invoked, the following two lines load the contents of {{ic|$HOSTNAME-sh}} and {{ic|$HOSTNAME-sh-gpg}}, if they exist. These files store the environment variables of the previous instance of ''keychain''.<br />
<br />
==== Calling x11-ssh-askpass with ssh-add ====<br />
<br />
The ''ssh-add'' manual page specifies that, in addition to needing the {{ic|DISPLAY}} variable defined, you also need {{ic|SSH_ASKPASS}} set to the name of your askpass program (in this case ''x11-ssh-askpass''). It bears keeping in mind that the default Arch Linux installation places the ''x11-ssh-askpass'' binary in {{ic|/usr/lib/ssh/}}, which will not be in most people's {{ic|PATH}}. This is a little annoying, not only when declaring the {{ic|SSH_ASKPASS}} variable, but also when theming. You have to specify the full path everywhere. Both inconveniences can be solved simultaneously by symlinking:<br />
<br />
$ ln -sv /usr/lib/ssh/x11-ssh-askpass ~/bin/ssh-askpass<br />
<br />
This is assuming that {{ic|~/bin}} is in your {{ic|PATH}}. So now in your {{ic|.xinitrc}}, before calling your window manager, one just needs to export the {{ic|SSH_ASKPASS}} environment variable:<br />
<br />
$ export SSH_ASKPASS=ssh-askpass<br />
<br />
and your [[X resources]] will contain something like:<br />
<br />
ssh-askpass*background: #000000<br />
<br />
Doing it this way works well with [[#ssh-agent as a wrapper program|the above method on using ''ssh-agent'' as a wrapper program]]. You start X with {{ic|ssh-agent startx}} and then add ''ssh-add'' to your window manager's list of start-up programs.<br />
<br />
==== Theming ====<br />
<br />
The appearance of the ''x11-ssh-askpass'' dialog can be customized by setting its associated [[X resources]]. The ''x11-ssh-askpass'' [http://www.jmknoble.net/software/x11-ssh-askpass/ home page]{{Dead link|2015|04|01}} presents some [http://www.jmknoble.net/software/x11-ssh-askpass/screenshots.html example themes]{{Dead link|2015|04|01}}. See the ''x11-ssh-askpass'' manual page for full details.<br />
<br />
==== Alternative passphrase dialogs ====<br />
<br />
There are other passphrase dialog programs which can be used instead of ''x11-ssh-askpass''. The following list provides some alternative solutions.<br />
<br />
* {{Pkg|ksshaskpass}} is dependent on {{AUR|kdelibs}} and is suitable for the [[KDE]] Desktop Environment.<br />
<br />
* {{Pkg|openssh-askpass}} depends on the {{Pkg|qt4}} libraries.<br />
<br />
=== pam_ssh ===<br />
<br />
The [http://pam-ssh.sourceforge.net/ pam_ssh] project exists to provide a [[Pluggable Authentication Module]] (PAM) for SSH private keys. This module can provide single sign-on behavior for your SSH connections. On login, your SSH private key passphrase can be entered in place of, or in addition to, your traditional system password. Once you have been authenticated, the pam_ssh module spawns ssh-agent to store your decrypted private key for the duration of the session.<br />
<br />
To enable single sign-on behavior at the tty login prompt, install the unofficial {{AUR|pam_ssh}} package. <br />
<br />
{{Note|pam_ssh 2.0 now requires that all private keys used in the authentication process be located under {{ic|~/.ssh/login-keys.d/}}.}}<br />
<br />
Create a symlink to your private key file and place it in {{ic|~/.ssh/login-keys.d/}}. Replace the {{ic|id_rsa}} in the example below with the name of your own private key file.<br />
<br />
$ mkdir ~/.ssh/login-keys.d/<br />
$ cd ~/.ssh/login-keys.d/<br />
$ ln -s ../id_rsa<br />
<br />
Edit the {{ic|/etc/pam.d/login}} configuration file to include the text highlighted in bold in the example below. The order in which these lines appear is significiant and can affect login behavior.<br />
<br />
{{Warning|Misconfiguring PAM can leave the system in a state where all users become locked out. Before making any changes, you should have an understanding of how PAM configuration works as well as a backup means of accessing the PAM configuration files, such as an Arch Live CD, in case you become locked out and need to revert any changes. An IBM developerWorks [http://www.ibm.com/developerworks/linux/library/l-pam/index.html article] is available which explains PAM configuration in further detail.}}<br />
<br />
{{hc|/etc/pam.d/login|2=<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
'''auth optional pam_ssh.so try_first_pass'''<br />
account include system-local-login<br />
session include system-local-login<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
In the above example, login authentication initially proceeds as it normally would, with the user being prompted to enter his user password. The additional {{ic|auth}} authentication rule added to the end of the authentication stack then instructs the pam_ssh module to try to decrypt any private keys found in the {{ic|~/.ssh/login-keys.d}} directory. The {{ic|try_first_pass}} option is passed to the pam_ssh module, instructing it to first try to decrypt any SSH private keys using the previously entered user password. If the user's private key passphrase and user password are the same, this should succeed and the user will not be prompted to enter the same password twice. In the case where the user's private key passphrase user password differ, the pam_ssh module will prompt the user to enter the SSH passphrase after the user password has been entered. The {{ic|optional}} control value ensures that users without an SSH private key are still able to log in. In this way, the use of pam_ssh will be transparent to users without an SSH private key.<br />
<br />
If you use another means of logging in, such as an X11 display manager like [[SLiM]] or [[XDM]] and you would like it to provide similar functionality, you must edit its associated PAM configuration file in a similar fashion. Packages providing support for PAM typically place a default configuration file in the {{ic|/etc/pam.d/}} directory.<br />
<br />
Further details on how to use pam_ssh and a list of its options can be found in the pam_ssh man page.<br />
<br />
==== Using a different password to unlock the SSH key ====<br />
<br />
If you want to unlock the SSH keys or not depending on whether you use your key's passphrase or the (different!) login password, you can modify {{ic|/etc/pam.d/system-auth}} to<br />
<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth [success=1 new_authtok_reqd=1 ignore=ignore default=ignore] pam_unix.so try_first_pass nullok'''<br />
'''auth required pam_ssh.so use_first_pass'''<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
session optional pam_permit.so<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
For an explanation, see [http://unix.stackexchange.com/a/239486/863 here].<br />
<br />
==== Known issues with pam_ssh ====<br />
<br />
Work on the pam_ssh project is infrequent and the documentation provided is sparse. You should be aware of some of its limitations which are not mentioned in the package itself.<br />
<br />
* Versions of pam_ssh prior to version 2.0 do not support SSH keys employing the newer option of ECDSA (elliptic curve) cryptography. If you are using earlier versions of pam_ssh you must use either RSA or DSA keys.<br />
<br />
* The {{ic|ssh-agent}} process spawned by pam_ssh does not persist between user logins. If you like to keep a [[GNU Screen]] session active between logins you may notice when reattaching to your screen session that it can no longer communicate with ssh-agent. This is because the GNU Screen environment and those of its children will still reference the instance of ssh-agent which existed when GNU Screen was invoked but was subsequently killed in a previous logout. The [[#Keychain|Keychain]] front-end avoids this problem by keeping the ssh-agent process alive between logins.<br />
<br />
=== GNOME Keyring ===<br />
<br />
If you use the [[GNOME]] desktop, the [[GNOME Keyring]] tool can be used as an SSH agent. See the [[GNOME Keyring]] article for further details.<br />
<br />
=== Store SSH keys with Kwallet ===<br />
<br />
For instructions on how to use kwallet to store your SSH keys, see [[KDE Wallet#Using the KDE Wallet to store ssh key passphrases]].<br />
<br />
=== KeePass2 with KeeAgent plugin ===<br />
<br />
[http://lechnology.com/software/keeagent/ KeeAgent] is a plugin for [[KeePass]] that allows SSH keys stored in a KeePass database to be used for SSH authentication by other programs.<br />
<br />
* Supports both PuTTY and OpenSSH private key formats.<br />
* Works with native SSH agent on Linux/Mac and with PuTTY on Windows.<br />
<br />
See [[KeePass#Plugin Installation]] or [[install]] the {{Pkg|keepass-plugin-keeagent}} package. There is also the beta version, where new features appear first, {{AUR|keepass-plugin-keeagent-beta}}.<br />
<br />
This agent can be used directly, by matching KeeAgent socket: {{ic|KeePass -> Tools -> Options -> KeeAgent -> Agent mode socket file -> %XDG_RUNTIME_DIR%/keeagent.socket}}-<br />
and environment variable:<br />
{{ic|1=export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR"'/keeagent.socket'}}.<br />
<br />
=== KeePassXC ===<br />
The KeePassXC fork of KeePass [https://keepassxc.org/docs/#faq-ssh-agent-how supports being used as an SSH agent by default]. It is also compatible with KeeAgent's database format.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Key ignored by the server ===<br />
<br />
* If it appears that the SSH server is ignoring your keys, ensure that you have the proper permissions set on all relevant files.<br />
:For the local machine:<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/''key''<br />
<br />
:For the remote machine:<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
* If that does not solve the problem you may try temporarily setting {{ic|StrictModes}} to {{ic|no}} in {{ic|/etc/ssh/sshd_config}}. If authentication with {{ic|StrictModes off}} is successful, it is likely an issue with file permissions persists.<br />
<br />
* Make sure keys in {{ic|~/.ssh/authorized_keys}} are entered correctly and only use one single line.<br />
<br />
* Make sure the remote machine supports the type of keys you are using: some servers do not support ECDSA keys, try using RSA or DSA keys instead, see [[#Generating an SSH key pair]].<br />
<br />
* You may want to use debug mode and monitor the output while connecting:<br />
<br />
# /usr/bin/sshd -d<br />
<br />
== See also ==<br />
<br />
* [https://www.ibm.com/developerworks/linux/library/l-keyc/ OpenSSH key management, Part 1]<br />
* [https://www.ibm.com/developerworks/linux/library/l-keyc2/ OpenSSH key management, Part 2]<br />
* [https://www.ibm.com/developerworks/library/l-keyc3/ OpenSSH key management, Part 3]<br />
* [https://web.archive.org/web/20170708074341/https://kimmo.suominen.com/docs/ssh/ Getting started with SSH]<br />
* [https://www.openssh.com/txt/release-5.7 OpenSSH 5.7 Release Notes]<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Simon04https://wiki.archlinux.org/index.php?title=Display_manager&diff=546505Display manager2018-10-07T11:04:26Z<p>Simon04: /* List of display managers */ nodm unmaintained</p>
<hr />
<div>[[Category:Graphical user interfaces]]<br />
[[Category:Lists]]<br />
[[ar:Display manager]]<br />
[[cs:Display manager]]<br />
[[de:Login-Manager]]<br />
[[es:Display manager]]<br />
[[fa:Display manager]]<br />
[[fr:Gestionnaire de connexions]]<br />
[[he:Display manager]]<br />
[[it:Display manager]]<br />
[[ja:ディスプレイマネージャ]]<br />
[[pt:Display manager]]<br />
[[ru:Display manager]]<br />
[[zh-hans:Display manager]]<br />
[[zh-hant:Display manager]]<br />
{{Related articles start}}<br />
{{Related|Start X at login}}<br />
{{Related articles end}}<br />
<br />
A [[Wikipedia:X display manager (program type)|display manager]], or login manager, is typically a graphical user interface that is displayed at the end of the boot process in place of the default shell. There are various implementations of display managers, just as there are various types of [[window managers]] and [[desktop environments]]. There is usually a certain amount of customization and themeability available with each one.<br />
<br />
== List of display managers ==<br />
<br />
=== Console ===<br />
<br />
* {{App|[[CDM]]|Ultra-minimalistic, yet full-featured login manager written in Bash.|https://github.com/ghost1227/cdm|{{AUR|cdm-git}}}}<br />
* {{App|[[Console TDM]]|Extension for ''xinit'' written in pure Bash.|https://github.com/dopsi/console-tdm|{{AUR|console-tdm}}}}<br />
* {{App|[[nodm]]|Minimalistic display manager for automatic logins.|https://github.com/spanezz/nodm|{{Pkg|nodm}}}} – [https://github.com/spanezz/nodm/issues/8 unmaintained as of 2018-10]<br />
* {{App|[[Ly]]|Experimental ncurses display manager.|https://github.com/cylgom/ly|{{AUR|ly-git}}}}<br />
* {{App|tbsm|A pure bash session or application launcher.|https://loh-tar.github.io/tbsm/|{{AUR|tbsm}}}}<br />
<br />
=== Graphical ===<br />
<br />
* {{App|[[GDM]]|[[GNOME]] display manager.|https://wiki.gnome.org/Projects/GDM|{{Pkg|gdm}}}}<br />
* {{App|[[LightDM]]|Cross-desktop display manager, can use various front-ends written in any toolkit.|https://www.freedesktop.org/wiki/Software/LightDM/|{{Pkg|lightdm}}}}<br />
* {{App|[[LXDM]]|[[LXDE]] display manager. Can be used independent of the LXDE desktop environment.|https://sourceforge.net/projects/lxdm/|{{Pkg|lxdm}}}}<br />
* {{App|[[SDDM]]|QML-based display manager and successor to KDE4's kdm; recommended for Plasma 5 and LXQt.|https://github.com/sddm/sddm|{{Pkg|sddm}}}}<br />
* {{App|[[XDM]]|X display manager with support for XDMCP, host chooser.|{{man|8|xdm}}|{{Pkg|xorg-xdm}}}}<br />
<br />
== Loading the display manager ==<br />
<br />
To enable graphical login, [[enable]] the appropriate systemd service. For example, for [[SDDM]], enable {{ic|sddm.service}}.<br />
<br />
This should work out of the box. If not, you might have to reset a custom {{ic|default.target}} symlink to point to the default {{ic|graphical.target}}.<br />
<br />
After enabling [[SDDM]] a symlink {{ic|display-manager.service}} should be set in {{ic|/etc/systemd/system/}}. You may need to use {{ic|--force}} to override old symlinks.<br />
<br />
{{hc|$ file /etc/systemd/system/display-manager.service|<br />
/etc/systemd/system/display-manager.service: symbolic link to /usr/lib/systemd/system/sddm.service<br />
}}<br />
<br />
=== Using systemd-logind ===<br />
<br />
In order to check the status of your user session, you can use ''loginctl''. All [[polkit]] actions like suspending the system or mounting external drives will work out of the box.<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
== Session configuration ==<br />
<br />
Many display managers read available sessions from {{ic|/usr/share/xsessions/}} directory. It contains standard [http://standards.freedesktop.org/desktop-entry-spec/latest/ desktop entry files] for each DM/WM.<br />
<br />
To add/remove entries to your display manager's session list; create/remove the ''.desktop'' files in {{ic|/usr/share/xsessions/}} as desired. A typical ''.desktop'' file will look something like:<br />
<br />
[Desktop Entry]<br />
Name=Openbox<br />
Comment=Log in using the Openbox window manager (without a session manager)<br />
Exec=/usr/bin/openbox-session<br />
TryExec=/usr/bin/openbox-session<br />
Icon=openbox.png<br />
Type=Application<br />
<br />
===Run ~/.xinitrc as a session===<br />
Installing {{AUR|xinit-xsession}} will provide an option to run your [[xinitrc]] as a session. Simply set {{ic|xinitrc}} as the session in your display manager's settings and make sure that the {{ic|~/.xinitrc}} file is executable.<br />
<br />
=== Starting applications without a window manager ===<br />
<br />
You can also launch an application without any decoration, desktop, or window management. For example to launch {{AUR|google-chrome}} create a {{ic|web-browser.desktop}} file in {{ic|/usr/share/xsessions/}} like this:<br />
<br />
[Desktop Entry]<br />
Name=Web Browser<br />
Comment=Use a web browser as your session<br />
Exec=/usr/bin/google-chrome --auto-launch-at-startup<br />
TryExec=/usr/bin/google-chrome --auto-launch-at-startup<br />
Icon=google-chrome<br />
Type=Application<br />
<br />
In this case, once you login, the application set with {{ic|Exec}} will be launched immediately. When you close the application, you will be taken back to the login manager (same as logging out of a normal DE/WM).<br />
<br />
It is important to remember that most graphical applications are not intended to be launched this way and you might have manual tweaking to do or limitations to live with (there is no window manager, so do not expect to be able to move or resize ''any'' windows, including dialogs; nonetheless, you might be able to set the window geometry in the application's configuration files).<br />
<br />
See also [[xinitrc#Starting applications without a window manager]].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Autostarting ===<br />
<br />
Most display managers source {{ic|/etc/xprofile}}, {{ic|~/.xprofile}} and {{ic|/etc/X11/xinit/xinitrc.d/}}. For more details, see [[xprofile]].<br />
<br />
=== Set language for user session ===<br />
<br />
For display managers that use [http://freedesktop.org/wiki/Software/AccountsService/ AccountsService] the [[locale]] for the user session can be set by editing:{{hc|/var/lib/AccountsService/users/$USER|2=<br />
[User]<br />
Language=''your_locale''}}<br />
<br />
where ''your_locale'' is a value such as {{ic|en_GB.UTF-8}}.<br />
<br />
Log out and then back in again for the changes to take effect.</div>Simon04https://wiki.archlinux.org/index.php?title=Autofs&diff=540179Autofs2018-09-06T13:19:57Z<p>Simon04: /* Samba */ single shares, multiple shares, auto discovery</p>
<hr />
<div>[[Category:File systems]]<br />
[[es:Autofs]]<br />
[[it:Autofs]]<br />
[[ja:Autofs]]<br />
[[ru:Autofs]]<br />
[[zh-hans:Autofs]]<br />
AutoFS provides automounting of removable media or network shares when they are inserted or accessed.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|autofs}} package.<br />
<br />
{{Note|You no longer need to load {{ic|autofs4}} module.}}<br />
<br />
== Configuration ==<br />
<br />
AutoFS uses template files for configuration which are located in {{ic|/etc/autofs}} The main template is called {{ic|auto.master}}, which can point to one or more other templates for specific media types.<br />
<br />
* Open the file {{ic|/etc/autofs/auto.master}} with your favorite editor, you will see something similar to this:<br />
<br />
{{hc|/etc/autofs/auto.master|2=<br />
#/media /etc/autofs/auto.media<br />
<br />
}}<br />
<br />
The first value on each line determines the base directory under which all the media in a template are mounted, the second value is which template to use. The default base path is {{ic|/media}}, but you can change this to any other location you prefer. For instance:<br />
<br />
{{hc|/etc/autofs/auto.master|2=<br />
/media/misc /etc/autofs/auto.misc --timeout=5<br />
/media/net /etc/autofs/auto.net --timeout=60<br />
<br />
}}<br />
{{Note|Make sure there is an empty line on the end of template files (press {{ic|ENTER}} after last word). If there is no correct EOF (end of file) line, the AutoFS daemon will not properly load.}}<br />
<br />
The optional parameter {{ic|timeout}} sets the amount of seconds after which to unmount directories.<br />
<br />
The base directory will be created if it does not exist on your system. The base directory will be mounted on to load the dynamically loaded media, which means any content in the base directory will not be accessible while autofs is on. This procedure is however non-destructive, so if you accidentally automount into a live directory you can just change the location in {{ic|auto.master}} and restart AutoFS to regain the original contents.<br />
<br />
If you still want to automount to a target non-empty directory and want to have the original files available even after the dynamically loaded directories are mounted, you can use autofs to mount them to another directory (e.g. /var/autofs/net) and create soft links.<br />
<br />
# ln -s /var/autofs/net/share_name /media/share_name<br />
<br />
Alternatively, you can have autofs mount your media to a specific folder, rather than inside a common folder.<br />
<br />
{{hc|/etc/autofs/auto.master|2=<br />
/- /etc/autofs/auto.template<br />
}}<br />
{{hc|/etc/autofs/auto.template|2=<br />
/path/to/folder -options :/device/path<br />
/home/user/usbstick -fstype=auto,async,nodev,nosuid,umask=000 :/dev/sdb1<br />
}}<br />
{{Note|This can cause problems with resources getting locked if the connection to the share is lost. When trying to access the folder, programs will get locked into waiting for a response, and either the connection has to be restored or the process has to be forcibly killed before unmounting is possible. To mitigate this, only use if you will always be connected to the share, and do not use your home folder or other commonly used folders lest your file browser reads ahead into the disconnected folder}}<br />
<br />
* Open the file {{ic|/etc/nsswitch.conf}} and add an entry for automount:<br />
automount: files<br />
<br />
* When you are done configuring your templates (see below), launch the AutoFS daemon as root by [[enabling]] and starting the {{ic|autofs.service}}.<br />
<br />
Devices are now automatically mounted when they are accessed, they will remain mounted as long as you access them.<br />
<br />
=== Removable media ===<br />
<br />
* Open {{ic|/etc/autofs/auto.misc}} to add, remove or edit miscellaneous devices. For instance:<br />
<br />
{{hc|/etc/autofs/auto.misc|<nowiki><br />
#kernel -ro ftp.kernel.org:/pub/linux<br />
#boot -fstype=ext2 :/dev/hda1<br />
usbstick -fstype=auto,async,nodev,nosuid,umask=000 :/dev/sdb1<br />
cdrom -fstype=iso9660,ro :/dev/cdrom<br />
#floppy -fstype=auto :/dev/fd0<br />
</nowiki>}}<br />
<br />
If you have a CD/DVD combo-drive you can change the {{ic|cdrom}} line with {{ic|-fstype<nowiki>=</nowiki>auto}} to have the media type autodetected.<br />
<br />
=== NFS network mounts ===<br />
<br />
{{Style|"New" compared to what? In what way?; don't show systemctl start; formatting cleanup}}<br />
<br />
AutoFS provides a new way of automatically discovering and mounting [[NFS]]-shares on remote servers (the AutoFS network template in {{ic|/etc/autofs/auto.net}} has been removed in autofs5). To enable automatic discovery and mounting of network shares from all accessible servers without any further configuration, you will need to add the following to the {{ic|/etc/autofs/auto.master}} file:<br />
<br />
/net -hosts --timeout=60<br />
<br />
{{Note|Each host name needs to be resolveable, e.g. the name an IP address in {{ic|/etc/hosts}} or via [[Wikipedia:Domain_Name_System|DNS]] and make sure you have {{Pkg|nfs-utils}} installed and configured. You also have to [[enable]] {{ic|rpcbind}} to browse shared Folders.}}<br />
<br />
For instance, if you have a remote server ''fileserver'' (the name of the directory is the hostname of the server) with an NFS share named ''/home/share'', you can just access the share by typing:<br />
<br />
# cd /net/fileserver/home/share<br />
<br />
{{Note|Please note that ''ghosting'', i.e. automatically creating directory placeholders before mounting shares is enabled by default, although AutoFS installation notes claim to remove that option from {{ic|/etc/conf.d/autofs}} in order to start the AutoFS daemon.}}<br />
<br />
The {{ic|-hosts}} option uses a similar mechanism as the {{ic|showmount}} command to detect remote shares. You can see the exported shares by typing:<br />
<br />
# showmount <servername> -e <br />
<br />
Replacing ''<servername>'' with the name of your own server.<br />
<br />
==== Manual NFS configuration ====<br />
To mount a NFS share on server_name called /srv/shared_dir to another computer named client_pc at location /mnt/foo, edit auto.master and create a configuration file for the share (auto.server_name):<br />
{{hc|<nowiki>/etc/autofs/auto.master</nowiki>|<nowiki>/mnt /etc/autofs/auto.server_name --timeout 60</nowiki>}}<br />
{{hc|<nowiki>/etc/autofs/auto.server_name</nowiki>|<nowiki>foo -rw,soft,intr,rsize=8192,wsize=8192 server_name:/srv/shared_dir</nowiki>}}<br />
<br />
=== Samba ===<br />
<br />
==== Single shares ====<br />
<br />
Add the following to {{ic|/etc/autofs/auto.master}}:<br />
/media/[my_server] /etc/autofs/auto.[my_server] --timeout=60 --ghost<br />
where {{ic|--timeout}} defines how many seconds to wait before the file system is unmounted. The {{ic|--ghost}} option creates empty folders for each mount-point in the file in order to prevent timeouts, if a network share cannot be contacted. <br />
<br />
Next create a file {{ic|/etc/autofs/auto.[my_server]}}<br />
[any_name] -fstype=cifs,[other_options] ://[remote_server]/[remote_share_name]<br />
<br />
You can specify a user name and password to use with the share in the {{ic|other_options}} section:<br />
[any_name] -fstype=cifs,username=[username],password=[password],[other_options] ://[remote_server]/[remote_share_name]<br />
<br />
{{Note|Escape &#36;, and other characters, with a backslash when neccessary.}}<br />
<br />
==== Multiple shares ====<br />
<br />
You may be specify multiple shares in the {{ic|/etc/autofs/auto.[my_server]}}, for instance:<br />
<br />
[any_name] -fstype=cifs,[other_options] /photos ://[remote_server]/photos /music ://[remote_server]/music /video ://[remote_server]/video<br />
<br />
==== Auto discovery ====<br />
<br />
See the comments in {{ic|/etc/autofs/auto.smb}}.<br />
<br />
=== FTP and SSH (with FUSE) ===<br />
<br />
Remote FTP and [[SSH]] servers can be accessed seamlessly with AutoFS using [[Wikipedia:Filesystem in Userspace|FUSE]], a virtual file system layer. <br />
<br />
==== Remote FTP ====<br />
<br />
First, install the {{Pkg|curlftpfs}} package.<br />
Load the '''fuse''' module:<br />
<br />
# modprobe fuse<br />
<br />
Create a {{ic|/etc/modules-load.d/fuse.conf}} file containg {{ic|fuse}} to load it on each system boot.<br />
<br />
Next, add a new entry for FTP servers in {{ic|/etc/autofs/auto.master}}:<br />
<br />
/media/ftp /etc/autofs/auto.ftp --timeout=60<br />
<br />
Create the file {{ic|/etc/autofs/auto.ftp}} and add a server using the {{ic|ftp://myuser:mypassword@host:port/path}} format:<br />
<br />
servername -fstype=curl,rw,allow_other,nodev,nonempty,noatime :ftp\://myuser\:mypassword\@remoteserver<br />
<br />
{{Note| Your passwords are plainly visible for anyone that can run {{ic|df}} (only for mounted servers) or view the file {{ic|/etc/autofs/auto.ftp}}.}}<br />
If you want slightly more security you can create the file {{ic|~root/.netrc}} and add the passwords there. <br />
Passwords are still plain text, but you can have mode 600, and {{ic|df}} command will not show them (mounted or not).<br />
This method is also less sensitive to special characters (that else must be escaped) in the passwords. The format is:<br />
<br />
machine remoteserver <br />
login myuser<br />
password mypassword<br />
<br />
The line in {{ic|/etc/autofs/auto.ftp}} looks like this without user and password:<br />
<br />
servername -fstype=curl,allow_other :ftp\://remoteserver<br />
<br />
Create the file {{ic|/sbin/mount.curl}} with this code:<br />
<br />
{{hc|/sbin/mount.curl|<nowiki><br />
#! /bin/sh<br />
curlftpfs $1 $2 -o $4,disable_eprt<br />
</nowiki>}}<br />
<br />
Create the file {{ic|/sbin/umount.curl}} with this code:<br />
<br />
{{hc|/sbin/umount.curl|<nowiki><br />
#! /bin/sh<br />
fusermount -u $1<br />
</nowiki>}}<br />
<br />
Set the permissions for both files:<br />
<br />
# chmod 755 /sbin/mount.curl<br />
# chmod 755 /sbin/umount.curl<br />
<br />
After a restart your new FTP server should be accessible through {{ic|/media/ftp/servername}}.<br />
<br />
==== Remote SSH ====<br />
<br />
{{Accuracy|1=All the ''ssh*'' commands should be executed as the same user, as before [https://wiki.archlinux.org/index.php?title=Autofs&diff=prev&oldid=318335 this edit]. It should not matter if it is root or unprivileged.}}<br />
<br />
These are basic instructions to access a remote filesystem over [[SSH]] with AutoFS. <br />
<br />
{{Note|Password-less authentication may be convenient but also has security implications. See [[Using SSH Keys|SSH keypair]] for more details}}<br />
<br />
Install the {{Pkg|sshfs}} package.<br />
<br />
Load the {{ic|fuse}} module:<br />
<br />
# modprobe fuse<br />
<br />
Create a {{ic|/etc/modules-load.d/fuse.conf}} file containg {{ic|fuse}} to load it on each system boot if you have not one yet.<br />
<br />
Install {{Pkg|openssh}}.<br />
<br />
Generate an [[Using SSH Keys|SSH keypair]]:<br />
$ ssh-keygen<br />
<br />
When the generator ask for a passphrase, just press {{ic|ENTER}}. Using SSH keys without a passphrase is less secure, yet running AutoFS together with passphrases poses some additional difficulties which are not (yet) covered in this article. <br />
<br />
Next, copy the public key to the remote SSH server:<br />
$ ssh-copy-id username@remotehost<br />
<br />
'''As root''', see that you can login to the remote server without entering a password:<br />
# ssh username@remotehost<br />
<br />
{{Note|This will add the remote server to root's list of {{ic|known_hosts}}. Hosts can be also be manually added to {{ic|/etc/ssh/ssh_known_hosts}}.}}<br />
<br />
Create a new entry for SSH servers in {{ic|/etc/autofs/auto.master}}:<br />
/media/ssh /etc/autofs/auto.ssh --timeout=60<br />
<br />
Create the file {{ic|/etc/autofs/auto.ssh}} and add an SSH server:<br />
{{hc|/etc/autofs/auto.ssh|2=<br />
servername -fstype=fuse,rw,allow_other,IdentityFile=/home/username/.ssh/id_rsa :sshfs\#username@host\:/<br />
}}<br />
<br />
After a restart your SSH server should be accessible through {{ic|/media/ssh/servername}}.<br />
<br />
== MTP ==<br />
<br />
Media Transfer Protocol ([[MTP]]) is used in some Android devices.<br />
<br />
Install the {{Pkg|mtpfs}} package.<br />
<br />
Create a new entry for MTP Device in {{ic|/etc/autofs/auto.misc}}:<br />
android -fstype=fuse,allow_other,umask=000 :mtpfs<br />
<br />
== Troubleshooting and tweaks ==<br />
<br />
This section contains a few solutions for common issues with AutoFS.<br />
<br />
=== Using NIS ===<br />
<br />
Version 5.0.5 of AutoFS has more advanced support for [[NIS]]. To use AutoFS together with NIS, add {{ic|yp:}} in front of the template names in {{ic|/etc/autofs/auto.master}}:<br />
<br />
/home yp:auto_home --timeout=60 <br />
/sbtn yp:auto_sbtn --timeout=60<br />
+auto.master<br />
<br />
On earlier versions of NIS (before 5.0.4), you should add {{ic|nis}} to {{ic|/etc/nsswitch.conf}}:<br />
automount: files nis<br />
<br />
=== Optional parameters ===<br />
<br />
You can set parameters like {{ic|timeout}} systemwide for all AutoFS media in {{ic|/etc/default/autofs}}:<br />
<br />
* Open the {{ic|/etc/default/autofs}} file and edit the {{ic|OPTIONS}} line:<br />
OPTIONS='--timeout=5'<br />
<br />
* To enable logging (default is no logging at all), uncomment and add {{ic|--verbose}} to the {{ic|OPTIONS}} line in {{ic|/etc/default/autofs}} e.g.:<br />
OPTIONS='--verbose --timeout=5'<br />
<br />
After restarting the {{ic|autofs}} daemon, verbose output is visible in {{ic|systemctl status}} or in {{ic|journalctl}}.<br />
<br />
=== Identify multiple devices ===<br />
<br />
If you use multiple USB drives/sticks and want to easily tell them apart, you can use AutoFS to set up the mount points and [[Udev]] to create distinct names for your USB drives. See [[udev#Setting static device names]] for instructions on setting up Udev rules.<br />
<br />
=== AutoFS permissions ===<br />
<br />
If AutoFS is not working for you, make sure that the permissions of the templates files are correct, otherwise AutoFS will not start. This may happen if you backed up your configuration files in a manner which did not preserve file modes. Here are what the modes should be on the configuration files:<br />
<br />
*0644 - /etc/autofs/auto.master<br />
*0644 - /etc/autofs/auto.media<br />
*0644 - /etc/autofs/auto.misc<br />
*0644 - /etc/conf.d/autofs<br />
<br />
In general, scripts (like previous {{ic|auto.net}}) should have executable ({{ic|chmod a+x filename}}) bits set and lists of mounts should not.<br />
<br />
If you are getting errors in {{ic|/var/log/daemon.log}} similar to this, you have a permissions problem:<br />
<br />
May 7 19:44:16 peterix automount[15218]: lookup(program): lookup for petr failed<br />
May 7 19:44:16 peterix automount[15218]: failed to mount /media/cifs/petr<br />
<br />
=== fusermount problems ===<br />
With certain versions of util-linux, you may not be able to unmount a fuse file system drive mounted by autofs, even if you use the "user=" option. See the discussion here:<br />
http://fuse.996288.n3.nabble.com/Cannot-umount-as-non-root-user-anymore-tp689p697.html<br />
<br />
=== Debugging auto mount issues ===<br />
For better debugging you might try running automount in foreground.<br />
<br />
# systemctl stop autofs.service<br />
# automount -f -v<br />
<br />
Of if you want more debug info than try:<br />
# automount -f --debug<br />
<br />
== Alternatives to AutoFS ==<br />
<br />
* [[Systemd]] can automount filesystems upon demand; see [[Fstab#Automount_with_systemd|here]] for the description and the article on [[SSHFS#On demand|sshfs]] for an example.<br />
* [[Thunar Volume Manager]] is an automount system for users of the [[Thunar]] file manager.<br />
* [[PCManFM]] is a lightweight file manager with built-in support for accessing remote shares<br />
* [[Udisks]] is a minimalistic automatic disk mounting service<br />
<br />
== See also ==<br />
<br />
* FTP and SFTP usage with AutoFS is based on this Gentoo Wiki article: https://web.archive.org/web/20130414074212/http://en.gentoo-wiki.com/wiki/Mounting_SFTP_and_FTP_shares<br />
* More information on SSH can be found on the [[SSH]] and [[Using SSH Keys]] pages of this wiki.<br />
* Ubuntu's Autofs help wiki is at https://help.ubuntu.com/community/Autofs<br />
* For filesystem specific mount options check http://manpages.ubuntu.com/manpages/natty/en/man8/mount.8.html#contenttoc5<br />
* For fuse specific mount options check http://manpages.ubuntu.com/manpages/precise/man8/mount.fuse.8.html</div>Simon04