https://wiki.archlinux.org/api.php?action=feedcontributions&user=Comrumino&feedformat=atomArchWiki - User contributions [en]2024-03-29T11:49:31ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Pi-hole&diff=799728Pi-hole2024-02-04T22:35:30Z<p>Comrumino: /* Optional: read permissions for PHP */ Rewrote note to clarify why the settings are needed and what they fix</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}} (a [[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 administration interface.<br />
<br />
{{Note|Pi-hole on Arch Linux is not officially supported by the Pi-hole project.}}<br />
<br />
== Overview ==<br />
<br />
Two versions are available for Arch Linux:<br />
<br />
* [[#Pi-hole server]] – This is the default and well-known Pi-hole server that most users are looking for. It provides a DNS server for other devices on the LAN.<br />
* [[#Pi-hole standalone]] – This is an alternative lightweight Pi-hole installation, designed for a mobile context. It is intended to be used on the same device (e.g. a laptop), where no external and centralised Pi-hole server is available. It has no web interface, and automatically updates itself.<br />
<br />
== Pi-hole server ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{AUR|pi-hole-server}} package.<br />
<br />
=== Configuration ===<br />
<br />
==== FTL (Faster Than Light) ====<br />
<br />
Pi-hole's FTL 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 />
<br />
# Daily data are stored in RAM and are captured in real-time within {{ic|/run/log/pihole/pihole.log}}<br />
# Historical data (several days/weeks/months) are stored on the file system {{ic|/etc/pihole/pihole-FTL.db}} and written out at a user-specified interval.<br />
<br />
{{Note|<br />
* To disable logging, see [[#Disable query logging]].<br />
* Starting {{ic|pihole-FTL.service}} is likely to fail. See [[#Failed to start Pi-hole FTLDNS engine]].<br />
}}<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 />
==== Web interface ====<br />
<br />
Pi-hole has a powerful, user-friendly, but completely optional web interface. As well as changing settings, the user can analyse and visualise DNS queries handled by Pi-hole.<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 />
[...]<br />
extension=sqlite3<br />
[...]<br />
}}<br />
<br />
===== Optional: read permissions for PHP =====<br />
<br />
In php 7.0 and newer, the [[PHP#Configuration|PHP open_basedir]] directive defaults to empty, meaning PHP can access every directory and file that can be read by the webserver's userid. For greater security, uncomment {{ic|open_basedir}} in {{ic|/etc/php/php.ini}} and add the list of directories and files accessed by the Pi-hole administration web interface. The list is quite long:<br />
<br />
{{bc|<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 />
/var/log/lighttpd/error-pihole.log<br />
/proc/cpuinfo<br />
/proc/loadavg<br />
/proc/meminfo<br />
/sys/class/thermal/thermal_zone0/temp<br />
/tmp<br />
}}<br />
<br />
The {{ic|open_basedir}} directive expects a colon-separated list:<br />
<br />
{{hc|1=/etc/php/php.ini|2=open_basedir = /srv/http/pihole:/run/pihole-ftl/pihole-FTL.port:/run/log/pihole/pihole.log:/run/log/pihole-ftl/pihole-FTL.log:/etc/pihole:/etc/hosts:/etc/hostname:/etc/dnsmasq.d/02-pihole-dhcp.conf:/etc/dnsmasq.d/03-pihole-wildcard.conf:/etc/dnsmasq.d/04-pihole-static-dhcp.conf:/var/log/lighttpd/error-pihole.log:/proc/loadavg:/proc/meminfo:/proc/cpuinfo:/sys/class/thermal/thermal_zone0/temp:/tmp}}<br />
<br />
<br />
{{note|If you choose to use ''nginx'', you will need to replace {{ic|/var/log/lighttpd/error-pihole.log}} with {{ic|/var/log/nginx/error-pihole.log}} and add {{ic|env[PHP_ERROR_LOG] {{=}} /var/log/nginx/error-pihole.log}} to {{ic|/etc/php/php-fpm.d/www.conf}}. Without specifying the environment variable {{ic|PHP_ERROR_LOG}}, the code will attempt to log to {{ic|/var/log/apache2}}. These changes resolve the logging permission error reported by the console when using ''nginx'' instead of ''lighttpd''.}}<br />
<br />
===== Set-up lighttpd =====<br />
<br />
{{Tip|Users can also run 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 configuration for Pi-hole:<br />
<br />
# cp /usr/share/pihole/configs/lighttpd.example.conf /etc/lighttpd/lighttpd.conf<br />
<br />
[[Enable]] {{ic|lighttpd.service}} and [[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 (e.g. 192.168.1.250) and ''myhostname'' should be the actual hostname of the machine running Pi-hole:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 localhost<br />
ip.address.of.pihole pi.hole myhostname<br />
}}<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, devices within the network should use Pi-hole's IP address as their sole DNS server. To accomplish this, there are generally two methods:<br />
<br />
# In the 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 modifications to LAN DNS settings, so disabling the router's DHCP server and using [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] might be a solution.}}<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|The 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 installs a statically enabled timer (and relative service) which will weekly update Pi-hole blacklisted servers list.<br />
The default values can be changed via an [[edit]] to the service or it can be prevented from being executed by [[systemd#Using units|masking]] it.<br />
Remember to manually start {{ic|pi-hole-gravity.timer}} or simply reboot after editing.<br />
<br />
==== FTL ====<br />
<br />
See [[#FTL (Faster Than Light)]].<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 />
If using DHCP to lease IP addresses from an external router, append {{ic|bind-interfaces}} to {{ic|/etc/dnsmasq.conf}} for DNS queries to resolve.<br />
<br />
Test DNS queries independently of network-configured nameserver in {{ic|/etc/resolv.conf}} using {{ic|drill @127.0.0.1 archlinux.org}} .<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 />
=== 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. Change which DNS servers Pi-hole uses with:<br />
<br />
$ pihole -a setdns ''ipaddress#port''<br />
<br />
Specify multiple DNS servers by separating their addresses with commas.<br />
<br />
==== Forced update of ad-serving domains list ====<br />
<br />
To update the blocked domain list, 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 />
Leaving the value for {{ic|time}} blank, the 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:<br />
<br />
$ pihole disable 5m<br />
<br />
At any time, reenable Pi-hole by executing:<br />
<br />
$ pihole enable<br />
<br />
== Tips and tricks ==<br />
<br />
=== Password-protected web interface ===<br />
<br />
To password-protect the Pi-hole web interface, run the following command and enter the password:<br />
<br />
$ pihole -a -p<br />
<br />
To disable the password protection, set a blank password.<br />
<br />
=== Cloudflare DoH ===<br />
<br />
Pi-hole can be configured to use [[Cloudflared]] to achieve [[DNS over HTTPS]] functionality.<br />
<br />
To make [[Cloudflared]] work with Pi-hole, edit {{ic|cloudflared.yml}} file and change settings as per below:<br />
<br />
{{hc|/etc/cloudflared/cloudflared.yml|<br />
...<br />
proxy-dns-port: 53000<br />
proxy-dns-address: 127.0.0.1<br />
}}<br />
<br />
Then [[restart]] {{ic|cloudflared@cloudflared.service}}. Now use {{ic|127.0.0.1#53000}} as the only DNS server entry 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 />
=== Disable query logging ===<br />
<br />
Both daily and historic data collected by default contain query data that might be considered sensitive.<br />
<br />
To disable the query database for historic data, set privacy level to the maximum ''Anonymous mode'' either in the web administration (Settings > Privacy) or in the configuration file {{ic|/etc/pihole/pihole-FTL.conf}} by editing the line:<br />
<br />
PRIVACYLEVEL=3<br />
<br />
To also disable the logging for daily data, use the following command:<br />
<br />
$ pihole logging off<br />
<br />
{{Warning|Pi-hole will erase all statistics upon executing this command.}}<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 {{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 the Pi-hole DNS server. In the client configuration file, specify the following line:<br />
<br />
DNS = ''Pi-hole-IP''<br />
<br />
In order for the DNS to be functional from the VPN, Pi-hole has to listen to all local interfaces:<br />
<br />
pihole -a -i local<br />
<br />
See more information in [[WireGuard#Client configuration]].<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 />
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 configuration 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 />
Edit {{ic|/etc/nginx/conf.d/pihole.conf}} and change the {{ic|fastcgi_pass}} directive to the following:<br />
<br />
fastcgi_pass unix:/run/php-fpm/php-fpm.sock; <br />
<br />
Optionally, set {{ic|VIRTUAL_HOST}} to the CNAME of Pi-hole if the intention is to run multiple virtual hosts on Nginx.<br />
<br />
fastcgi_param VIRTUAL_HOST "pihole.example.com";<br />
<br />
Since version 7.4 php-fpm is hardened by default and revokes read/write access on {{ic|/usr}} (and sub-directories).<br />
<br />
Create an [[drop-in file]] for {{ic|php-fpm}} with the following content:<br />
<br />
{{hc|/etc/systemd/system/php-fpm.service.d/pihole.conf|2=<br />
[Service]<br />
ReadWritePaths = /srv/http/pihole<br />
ReadWritePaths = /run/pihole-ftl/pihole-FTL.port<br />
ReadWritePaths = /run/log/pihole/pihole.log<br />
ReadWritePaths = /run/log/pihole-ftl/pihole-FTL.log<br />
ReadWritePaths = /etc/pihole<br />
ReadWritePaths = /etc/hosts<br />
ReadWritePaths = /etc/hostname<br />
ReadWritePaths = /etc/dnsmasq.d/01-pihole.conf<br />
ReadWritePaths = /proc/meminfo<br />
ReadWritePaths = /proc/cpuinfo<br />
ReadWritePaths = /sys/class/thermal/thermal_zone0/temp<br />
ReadWritePaths = /tmp<br />
}}<br />
<br />
Then [[start]] and [[enable]] {{ic|nginx.service}} and {{ic|php-fpm.service}}.<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://firebog.net/ firebog.net] and [https://oisd.nl/ oisd.nl].<br />
<br />
=== Use Unbound as upstream DNS server ===<br />
<br />
By default, Pi-hole forwards requests to upstream DNS servers, which might lead to privacy concerns.<br />
See [https://docs.pi-hole.net/guides/dns/unbound/ upstream documentation] for a guide on setting up [[Unbound]] locally to resolve DNS requests.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Odd behavior in the web interface after an upgrade ===<br />
<br />
Some strange/unexplained rendering issues in the web GUI can often be fixed by clearing one's browser cache.<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]] and [[System time]].<br />
<br />
For devices lacking a [[RTC]]:<br />
A hacky work-around for this is to use [[drop-in file]]s 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 the 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 />
{{Tip|Check which process opened port 53 with: {{ic|# lsof -i :53}}.}}<br />
<br />
It might be that {{ic|systemd-resolved.service}} already occupied port 53, which is required for {{ic|pihole-FTL.service}}.<br />
To resolve this, disable the stub listener by creating a [[drop-in snippet]] form [[systemd-resolved]]'s configuration file:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/pi-hole.conf|2=<br />
[Resolve]<br />
DNSStubListener=no<br />
}}<br />
<br />
Then [[restart]] {{ic|systemd-resolved.service}} and {{ic|pihole-FTL.service}}.<br />
<br />
For more information, see {{man|5|resolved.conf}}.<br />
<br />
Alternatively, tell dnsmasq to bind to each interface explicitly, instead of the wildcard {{ic|0.0.0.0:53}}, by uncommenting the line {{ic|bind-interfaces}} in {{ic|/etc/dnsmasq.conf}}. This will avoid conflicting with {{ic|systemd-resolved}} which listens on {{ic|127.0.0.53:53}}.<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 is still possible to use the previous dnsmasq configuration 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 />
<br />
The issue, as seen in {{Bug|63704}}, is with systemd-sysusers created user {{ic|http}}, which is created in expired state. To fix it, run:<br />
<br />
# chage --expiredate -1 http<br />
<br />
=== Slow loading times ===<br />
<br />
{{Accuracy|This issue seems to pertain to DNS configuration. It might not be a good idea to instruct direct changes to {{ic|/etc/resolv.conf}}.}}<br />
<br />
If browsers report "Resolving host" or it just takes longer to load pages than usual, ensure that {{ic|/etc/resolv.conf}} looks '''exactly''' like this:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
If it takes very long to load pages, it can be a problem with {{ic|lsof}} call in pihole script {{ic|(/usr/bin/pihole)}} called through php. Verify it while loading page with: {{ic|<nowiki>ps -ef | grep lsof</nowiki>}}. Kill it and if the page is displayed, replace {{ic|lsof}} call in pihole script (there is only one) with:<br />
<br />
{{bc|<nowiki>ss -lnp '( sport = 53 )'</nowiki>}}<br />
<br />
=== Prevent DNS resolution issues for other virtual hosts ===<br />
<br />
By default, the DNS service (pihole-FTL) will be bind to the 0.0.0.0 IP address :<br />
<br />
{{hc|# netstat -ltnp {{!}} grep 53|<br />
tcp 0 0 0.0.0.0:53 0.0.0.0:* LISTEN 2196/pihole-FTL<br />
tcp6 0 0 :::53 :::* LISTEN 2196/pihole-FTL<br />
}}<br />
<br />
This will prevent any other virtual host onto the same machine hosting the pihole instance (such as docker containers) to get DNS resolution.[https://discourse.pi-hole.net/t/make-pihole-ftl-bind-only-on-certain-ips-v4-0/11883][https://discourse.pi-hole.net/t/solve-dns-resolution-in-other-containers-when-using-docker-pihole/31413]<br />
<br />
In order to solve this, you need to create a config file in {{ic|/etc/dnsmasq.d/}} with the following content (where {{ic|X.X.X.X}} is the IP address of your pi-hole) :<br />
<br />
{{hc|/etc/dnsmasq.d/99-dns-bind.conf|2=<br />
listen-address=''X.X.X.X''<br />
bind-interfaces<br />
}}<br />
<br />
Then, you need to [[restart]] the {{ic|pihole-FTL.service}} to apply changes. <br />
<br />
{{Tip|To complete this configuration you may need to activate the online waiting service of your network manager}}<br />
<br />
=== Interface not up when pihole starts ===<br />
<br />
If after booting domain name resolution does not work, and the [[journal]] shows an error message like:<br />
<br />
pihole-FTL [...] FATAL ERROR in dnsmasq core: unknown interface wlo1<br />
<br />
Then it might be that the interface name is wrong, or the interface is not up when pihole tries to run.<br />
<br />
# Check the interface name with {{ic|ip a}}. If it is wrong, set {{ic|PIHOLE_INTERFACE}} to the correct value in {{ic|/etc/pihole/setupVars.conf}}<br />
# If the interface is right, it may not be up when pihole is started (even if the systemd service depends on {{ic|1=After=network-online.target}}). Set {{ic|DELAY_STARTUP}} in {{ic|/etc/pihole/pihole-FTL.conf}} to a value greater than 0 (expressed in seconds). <br />
<br />
Reboot to verify the issue is fixed.<br />
<br />
[https://discourse.pi-hole.net/t/strange-error-and-ftl-not-working-on-every-reboot/46391 Reference].<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 />
* [https://dlaa.me/blog/post/skyhole Sky-hole, the idea behind Pi-hole standalone]<br />
* [https://unix.stackexchange.com/questions/304050/how-to-avoid-conflicts-between-dnsmasq-and-systemd-resolved Stopping systemd-resolved stub server opening port 53]<br />
* [https://www.reddit.com/r/pihole/comments/d9j1z6/unbound_as_recursive_dns_server_slow_performance/f1jnuq1/ Unbound performance issue]</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pi-hole&diff=799646Pi-hole2024-02-04T06:43:54Z<p>Comrumino: /* Optional: read permissions for PHP */ When setting read permissions and using nginx, there are a couple extra configuration steps that would otherwise require users to read code.</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}} (a [[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 administration interface.<br />
<br />
{{Note|Pi-hole on Arch Linux is not officially supported by the Pi-hole project.}}<br />
<br />
== Overview ==<br />
<br />
Two versions are available for Arch Linux:<br />
<br />
* [[#Pi-hole server]] – This is the default and well-known Pi-hole server that most users are looking for. It provides a DNS server for other devices on the LAN.<br />
* [[#Pi-hole standalone]] – This is an alternative lightweight Pi-hole installation, designed for a mobile context. It is intended to be used on the same device (e.g. a laptop), where no external and centralised Pi-hole server is available. It has no web interface, and automatically updates itself.<br />
<br />
== Pi-hole server ==<br />
<br />
=== Installation ===<br />
<br />
[[Install]] the {{AUR|pi-hole-server}} package.<br />
<br />
=== Configuration ===<br />
<br />
==== FTL (Faster Than Light) ====<br />
<br />
Pi-hole's FTL 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 />
<br />
# Daily data are stored in RAM and are captured in real-time within {{ic|/run/log/pihole/pihole.log}}<br />
# Historical data (several days/weeks/months) are stored on the file system {{ic|/etc/pihole/pihole-FTL.db}} and written out at a user-specified interval.<br />
<br />
{{Note|<br />
* To disable logging, see [[#Disable query logging]].<br />
* Starting {{ic|pihole-FTL.service}} is likely to fail. See [[#Failed to start Pi-hole FTLDNS engine]].<br />
}}<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 />
==== Web interface ====<br />
<br />
Pi-hole has a powerful, user-friendly, but completely optional web interface. As well as changing settings, the user can analyse and visualise DNS queries handled by Pi-hole.<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 />
[...]<br />
extension=sqlite3<br />
[...]<br />
}}<br />
<br />
===== Optional: read permissions for PHP =====<br />
<br />
In php 7.0 and newer, the [[PHP#Configuration|PHP open_basedir]] directive defaults to empty, meaning PHP can access every directory and file that can be read by the webserver's userid. For greater security, uncomment {{ic|open_basedir}} in {{ic|/etc/php/php.ini}} and add the list of directories and files accessed by the Pi-hole administration web interface. The list is quite long:<br />
<br />
{{bc|<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 />
/var/log/lighttpd/error-pihole.log<br />
/proc/cpuinfo<br />
/proc/loadavg<br />
/proc/meminfo<br />
/sys/class/thermal/thermal_zone0/temp<br />
/tmp<br />
}}<br />
<br />
The {{ic|open_basedir}} directive expects a colon-separated list:<br />
<br />
{{hc|1=/etc/php/php.ini|2=open_basedir = /srv/http/pihole:/run/pihole-ftl/pihole-FTL.port:/run/log/pihole/pihole.log:/run/log/pihole-ftl/pihole-FTL.log:/etc/pihole:/etc/hosts:/etc/hostname:/etc/dnsmasq.d/02-pihole-dhcp.conf:/etc/dnsmasq.d/03-pihole-wildcard.conf:/etc/dnsmasq.d/04-pihole-static-dhcp.conf:/var/log/lighttpd/error-pihole.log:/proc/loadavg:/proc/meminfo:/proc/cpuinfo:/sys/class/thermal/thermal_zone0/temp:/tmp}}<br />
<br />
<br />
{{note|If you choose to use ''nginx'', you will need to replace {{ic|/var/log/lighttpd/error-pihole.log}} with {{ic|/var/log/nginx/error-pihole.log}} and add {{ic|env[PHP_ERROR_LOG] {{=}} /var/log/nginx/error-pihole.log}} to {{ic|/etc/php/php-fpm.d/www.conf}}. Otherwise, the code will not know where to log to and try to log in a directory it does not have access to.}}<br />
<br />
===== Set-up lighttpd =====<br />
<br />
{{Tip|Users can also run 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 configuration for Pi-hole:<br />
<br />
# cp /usr/share/pihole/configs/lighttpd.example.conf /etc/lighttpd/lighttpd.conf<br />
<br />
[[Enable]] {{ic|lighttpd.service}} and [[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 (e.g. 192.168.1.250) and ''myhostname'' should be the actual hostname of the machine running Pi-hole:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 localhost<br />
ip.address.of.pihole pi.hole myhostname<br />
}}<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, devices within the network should use Pi-hole's IP address as their sole DNS server. To accomplish this, there are generally two methods:<br />
<br />
# In the 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 modifications to LAN DNS settings, so disabling the router's DHCP server and using [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] might be a solution.}}<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|The 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 installs a statically enabled timer (and relative service) which will weekly update Pi-hole blacklisted servers list.<br />
The default values can be changed via an [[edit]] to the service or it can be prevented from being executed by [[systemd#Using units|masking]] it.<br />
Remember to manually start {{ic|pi-hole-gravity.timer}} or simply reboot after editing.<br />
<br />
==== FTL ====<br />
<br />
See [[#FTL (Faster Than Light)]].<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 />
If using DHCP to lease IP addresses from an external router, append {{ic|bind-interfaces}} to {{ic|/etc/dnsmasq.conf}} for DNS queries to resolve.<br />
<br />
Test DNS queries independently of network-configured nameserver in {{ic|/etc/resolv.conf}} using {{ic|drill @127.0.0.1 archlinux.org}} .<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 />
=== 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. Change which DNS servers Pi-hole uses with:<br />
<br />
$ pihole -a setdns ''ipaddress#port''<br />
<br />
Specify multiple DNS servers by separating their addresses with commas.<br />
<br />
==== Forced update of ad-serving domains list ====<br />
<br />
To update the blocked domain list, 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 />
Leaving the value for {{ic|time}} blank, the 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:<br />
<br />
$ pihole disable 5m<br />
<br />
At any time, reenable Pi-hole by executing:<br />
<br />
$ pihole enable<br />
<br />
== Tips and tricks ==<br />
<br />
=== Password-protected web interface ===<br />
<br />
To password-protect the Pi-hole web interface, run the following command and enter the password:<br />
<br />
$ pihole -a -p<br />
<br />
To disable the password protection, set a blank password.<br />
<br />
=== Cloudflare DoH ===<br />
<br />
Pi-hole can be configured to use [[Cloudflared]] to achieve [[DNS over HTTPS]] functionality.<br />
<br />
To make [[Cloudflared]] work with Pi-hole, edit {{ic|cloudflared.yml}} file and change settings as per below:<br />
<br />
{{hc|/etc/cloudflared/cloudflared.yml|<br />
...<br />
proxy-dns-port: 53000<br />
proxy-dns-address: 127.0.0.1<br />
}}<br />
<br />
Then [[restart]] {{ic|cloudflared@cloudflared.service}}. Now use {{ic|127.0.0.1#53000}} as the only DNS server entry 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 />
=== Disable query logging ===<br />
<br />
Both daily and historic data collected by default contain query data that might be considered sensitive.<br />
<br />
To disable the query database for historic data, set privacy level to the maximum ''Anonymous mode'' either in the web administration (Settings > Privacy) or in the configuration file {{ic|/etc/pihole/pihole-FTL.conf}} by editing the line:<br />
<br />
PRIVACYLEVEL=3<br />
<br />
To also disable the logging for daily data, use the following command:<br />
<br />
$ pihole logging off<br />
<br />
{{Warning|Pi-hole will erase all statistics upon executing this command.}}<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 {{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 the Pi-hole DNS server. In the client configuration file, specify the following line:<br />
<br />
DNS = ''Pi-hole-IP''<br />
<br />
In order for the DNS to be functional from the VPN, Pi-hole has to listen to all local interfaces:<br />
<br />
pihole -a -i local<br />
<br />
See more information in [[WireGuard#Client configuration]].<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 />
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 configuration 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 />
Edit {{ic|/etc/nginx/conf.d/pihole.conf}} and change the {{ic|fastcgi_pass}} directive to the following:<br />
<br />
fastcgi_pass unix:/run/php-fpm/php-fpm.sock; <br />
<br />
Optionally, set {{ic|VIRTUAL_HOST}} to the CNAME of Pi-hole if the intention is to run multiple virtual hosts on Nginx.<br />
<br />
fastcgi_param VIRTUAL_HOST "pihole.example.com";<br />
<br />
Since version 7.4 php-fpm is hardened by default and revokes read/write access on {{ic|/usr}} (and sub-directories).<br />
<br />
Create an [[drop-in file]] for {{ic|php-fpm}} with the following content:<br />
<br />
{{hc|/etc/systemd/system/php-fpm.service.d/pihole.conf|2=<br />
[Service]<br />
ReadWritePaths = /srv/http/pihole<br />
ReadWritePaths = /run/pihole-ftl/pihole-FTL.port<br />
ReadWritePaths = /run/log/pihole/pihole.log<br />
ReadWritePaths = /run/log/pihole-ftl/pihole-FTL.log<br />
ReadWritePaths = /etc/pihole<br />
ReadWritePaths = /etc/hosts<br />
ReadWritePaths = /etc/hostname<br />
ReadWritePaths = /etc/dnsmasq.d/01-pihole.conf<br />
ReadWritePaths = /proc/meminfo<br />
ReadWritePaths = /proc/cpuinfo<br />
ReadWritePaths = /sys/class/thermal/thermal_zone0/temp<br />
ReadWritePaths = /tmp<br />
}}<br />
<br />
Then [[start]] and [[enable]] {{ic|nginx.service}} and {{ic|php-fpm.service}}.<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://firebog.net/ firebog.net] and [https://oisd.nl/ oisd.nl].<br />
<br />
=== Use Unbound as upstream DNS server ===<br />
<br />
By default, Pi-hole forwards requests to upstream DNS servers, which might lead to privacy concerns.<br />
See [https://docs.pi-hole.net/guides/dns/unbound/ upstream documentation] for a guide on setting up [[Unbound]] locally to resolve DNS requests.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Odd behavior in the web interface after an upgrade ===<br />
<br />
Some strange/unexplained rendering issues in the web GUI can often be fixed by clearing one's browser cache.<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]] and [[System time]].<br />
<br />
For devices lacking a [[RTC]]:<br />
A hacky work-around for this is to use [[drop-in file]]s 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 the 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 />
{{Tip|Check which process opened port 53 with: {{ic|# lsof -i :53}}.}}<br />
<br />
It might be that {{ic|systemd-resolved.service}} already occupied port 53, which is required for {{ic|pihole-FTL.service}}.<br />
To resolve this, disable the stub listener by creating a [[drop-in snippet]] form [[systemd-resolved]]'s configuration file:<br />
<br />
{{hc|/etc/systemd/resolved.conf.d/pi-hole.conf|2=<br />
[Resolve]<br />
DNSStubListener=no<br />
}}<br />
<br />
Then [[restart]] {{ic|systemd-resolved.service}} and {{ic|pihole-FTL.service}}.<br />
<br />
For more information, see {{man|5|resolved.conf}}.<br />
<br />
Alternatively, tell dnsmasq to bind to each interface explicitly, instead of the wildcard {{ic|0.0.0.0:53}}, by uncommenting the line {{ic|bind-interfaces}} in {{ic|/etc/dnsmasq.conf}}. This will avoid conflicting with {{ic|systemd-resolved}} which listens on {{ic|127.0.0.53:53}}.<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 is still possible to use the previous dnsmasq configuration 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 />
<br />
The issue, as seen in {{Bug|63704}}, is with systemd-sysusers created user {{ic|http}}, which is created in expired state. To fix it, run:<br />
<br />
# chage --expiredate -1 http<br />
<br />
=== Slow loading times ===<br />
<br />
{{Accuracy|This issue seems to pertain to DNS configuration. It might not be a good idea to instruct direct changes to {{ic|/etc/resolv.conf}}.}}<br />
<br />
If browsers report "Resolving host" or it just takes longer to load pages than usual, ensure that {{ic|/etc/resolv.conf}} looks '''exactly''' like this:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver 127.0.0.1<br />
}}<br />
<br />
If it takes very long to load pages, it can be a problem with {{ic|lsof}} call in pihole script {{ic|(/usr/bin/pihole)}} called through php. Verify it while loading page with: {{ic|<nowiki>ps -ef | grep lsof</nowiki>}}. Kill it and if the page is displayed, replace {{ic|lsof}} call in pihole script (there is only one) with:<br />
<br />
{{bc|<nowiki>ss -lnp '( sport = 53 )'</nowiki>}}<br />
<br />
=== Prevent DNS resolution issues for other virtual hosts ===<br />
<br />
By default, the DNS service (pihole-FTL) will be bind to the 0.0.0.0 IP address :<br />
<br />
{{hc|# netstat -ltnp {{!}} grep 53|<br />
tcp 0 0 0.0.0.0:53 0.0.0.0:* LISTEN 2196/pihole-FTL<br />
tcp6 0 0 :::53 :::* LISTEN 2196/pihole-FTL<br />
}}<br />
<br />
This will prevent any other virtual host onto the same machine hosting the pihole instance (such as docker containers) to get DNS resolution.[https://discourse.pi-hole.net/t/make-pihole-ftl-bind-only-on-certain-ips-v4-0/11883][https://discourse.pi-hole.net/t/solve-dns-resolution-in-other-containers-when-using-docker-pihole/31413]<br />
<br />
In order to solve this, you need to create a config file in {{ic|/etc/dnsmasq.d/}} with the following content (where {{ic|X.X.X.X}} is the IP address of your pi-hole) :<br />
<br />
{{hc|/etc/dnsmasq.d/99-dns-bind.conf|2=<br />
listen-address=''X.X.X.X''<br />
bind-interfaces<br />
}}<br />
<br />
Then, you need to [[restart]] the {{ic|pihole-FTL.service}} to apply changes. <br />
<br />
{{Tip|To complete this configuration you may need to activate the online waiting service of your network manager}}<br />
<br />
=== Interface not up when pihole starts ===<br />
<br />
If after booting domain name resolution does not work, and the [[journal]] shows an error message like:<br />
<br />
pihole-FTL [...] FATAL ERROR in dnsmasq core: unknown interface wlo1<br />
<br />
Then it might be that the interface name is wrong, or the interface is not up when pihole tries to run.<br />
<br />
# Check the interface name with {{ic|ip a}}. If it is wrong, set {{ic|PIHOLE_INTERFACE}} to the correct value in {{ic|/etc/pihole/setupVars.conf}}<br />
# If the interface is right, it may not be up when pihole is started (even if the systemd service depends on {{ic|1=After=network-online.target}}). Set {{ic|DELAY_STARTUP}} in {{ic|/etc/pihole/pihole-FTL.conf}} to a value greater than 0 (expressed in seconds). <br />
<br />
Reboot to verify the issue is fixed.<br />
<br />
[https://discourse.pi-hole.net/t/strange-error-and-ftl-not-working-on-every-reboot/46391 Reference].<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 />
* [https://dlaa.me/blog/post/skyhole Sky-hole, the idea behind Pi-hole standalone]<br />
* [https://unix.stackexchange.com/questions/304050/how-to-avoid-conflicts-between-dnsmasq-and-systemd-resolved Stopping systemd-resolved stub server opening port 53]<br />
* [https://www.reddit.com/r/pihole/comments/d9j1z6/unbound_as_recursive_dns_server_slow_performance/f1jnuq1/ Unbound performance issue]</div>Comruminohttps://wiki.archlinux.org/index.php?title=X_resources&diff=761477X resources2022-12-19T06:02:21Z<p>Comrumino: /* Basic syntax */ Updated example of basic syntax to clarify the rules around separators for name/class/reource to fix the previous inaccuracy/ambiguity. Xrm handles this with quarks I am unclear on the behavior around one or more separators within the resource substring, but clearly at least one is supported. See https://github.com/freedesktop/xorg-lib-libX11/blob/master/src/Xrm.c#L1225-L1226</p>
<hr />
<div>[[Category:Configuration files]]<br />
[[Category:X server]]<br />
[[de:Xdefaults]]<br />
[[ja:X resources]]<br />
[[ru:X resources]]<br />
{{Related articles start}}<br />
{{Related|X Logical Font Description}}<br />
{{Related|dotfiles}}<br />
{{Related articles end}}<br />
'''Xresources''' is a user-level configuration ''dotfile'', typically located at {{ic|~/.Xresources}}.<br />
It can be used to set [[Wikipedia:X resources|X resources]], which are configuration parameters for X client applications.<br />
<br />
Among other things they can be used to:<br />
<br />
* configure terminal preferences (e.g. terminal colors)<br />
* set DPI, anti-aliasing, hinting and other X font settings<br />
* change the [[cursor theme|Xcursor theme]]<br />
* theme [[XScreenSaver]]<br />
* configure low-level X applications like: {{Pkg|xorg-xclock}}, {{Pkg|xpdf}}, [[rxvt-unicode]]<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|xorg-xrdb}} package.<br />
<br />
== Usage ==<br />
<br />
=== Load resource file ===<br />
<br />
Resources are stored in the X server, so have to only be read once. They are also accessible to ''remote'' X11 clients (such as those [[OpenSSH#X11 forwarding|forwarded over SSH]]).<br />
<br />
Load a resource file (such as the conventional {{ic|.Xresources}}), replacing any current settings:<br />
<br />
$ xrdb ''~/.Xresources''<br />
<br />
Load a resource file, and merge with the current settings:<br />
<br />
$ xrdb -merge ''~/.Xresources''<br />
<br />
{{Note|<br />
* Most [[Display manager]]s load the {{ic|~/.Xresources}} file on login.<br />
* The older {{ic|~/.Xdefaults}} file is read when an X11 program starts, but only if ''xrdb'' has not been used in the current session. [https://groups.google.com/forum/#!msg/comp.windows.x/hQBEdql8l-Q/hF3DETcIHGwJ]<br />
}}<br />
<br />
=== xinitrc ===<br />
<br />
If you are using a copy of the default [[xinitrc]] as your {{ic|.xinitrc}} it already merges {{ic|~/.Xresources}}.<br />
<br />
If you are using a custom {{ic|.xinitrc}} add the following line:<br />
<br />
<nowiki>[[ -f ~/.Xresources ]] && xrdb -merge -I$HOME ~/.Xresources</nowiki><br />
<br />
{{Note|Do not background the xrdb command within {{ic|~/.xinitrc}}. Otherwise, programs launched after xrdb may look for resources before it has finished loading them.}}<br />
<br />
=== Default settings ===<br />
<br />
To see the default settings for your installed X11 applications, look in {{ic|/usr/share/X11/app-defaults/}}.<br />
<br />
Detailed information on program-specific resources is usually provided in the man page for the program. xterm's man page is a good example, as it contains a list of X resources and their default values.<br />
<br />
To see the currently loaded resources:<br />
<br />
$ xrdb -query -all<br />
<br />
=== Xresources syntax ===<br />
<br />
==== Basic syntax ====<br />
<br />
The syntax of an Xresources file is as follows:<br />
'''name.Class.resource: value'''<br />
The {{ic|resource}} substring may contain a separator ({{ic|name}} and {{ic|Class}} will never contain a separator). For example, {{ic|Dialog.bodyFont}} is a [[XScreenSaver]] internal resource that is specfied to set the body font and fallback font:<br />
<br />
xscreensaver-auth.default.Dialog.bodyFont: times new roman 12, dejavu serif 12<br />
<br />
;name<br />
:The name of the application, such as xterm, xpdf, etc<br />
<br />
;class<br />
:The classification used to group resources together. Class names are typically uppercase.<br />
<br />
;resource<br />
:The name of the resource whose value is to be changed. Resources are typically lowercase with uppercase concatenation.<br />
<br />
;value<br />
:The actual value of the resource. This can be 1 of 3 types:<br />
:* Integer (whole numbers)<br />
:* Boolean (true/false, yes/no, on/off)<br />
:* String (a string of characters) (for example a word ({{ic|white}}), a color ({{ic|#ffffff}}), or a path ({{ic|/usr/bin/firefox}}))<br />
<br />
;delimiters<br />
:A dot ({{ic|'''.'''}}) is used to signify each step down into the hierarchy — in the above example we start at name, then descend into Class, and finally into the resource itself. A colon ({{ic|''':'''}}) is used to separate the resource declaration from the actual value.<br />
<br />
{{Note|For more information about Xresources file syntax see {{man|3|XrmGetDatabase|FILE_SYNTAX}}.}}<br />
<br />
==== Wildcard matching ====<br />
<br />
Question mark ({{ic|?}}) and asterisk ({{ic|*}}) can be used as wildcards, making it easy to write a single rule that can be applied to many different applications or elements. {{ic|?}} is used to match any single component name, while {{ic|*}} is used to represent any number of intervening components including none.<br />
<br />
Using the previous example, if you want to apply the same font to all programs (not just XScreenSaver) that contain the class name {{ic|Dialog}} which contains the resource name {{ic|headingFont}}, you could write:<br />
<br />
'''?'''.Dialog.headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
If you want to apply this same rule to all programs that contain the resource {{ic|headingFont}}, regardless of its class, you could write:<br />
<br />
'''*'''headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
For more information about wildcard matching rules see {{man|3|XrmGetResource|MATCHING_RULES}}.<br />
<br />
==== Comments ====<br />
<br />
Lines starting with an exclamation mark ({{ic|!}}) are ignored, for example:<br />
<br />
! The following rule will be ignored because it has been commented out<br />
!Xft.antialias: true<br />
<br />
Note that the exclamation mark must be the first character on the line.<br />
<br />
==== Include files ====<br />
<br />
{{Note|You need to have a C preprocessor, such as {{ic|GNU CPP}}, installed to use this functionality.}}<br />
<br />
To use different files for each application, use {{ic|#include}} in the main file. For example:<br />
<br />
{{hc|~/.Xresources|<br />
#include ".Xresources.d/xterm"<br />
#include ".Xresources.d/rxvt-unicode"<br />
#include ".Xresources.d/fonts"<br />
#include ".Xresources.d/xscreensaver"<br />
}}<br />
<br />
If files fail to load, specify the directory to ''xrdb'' with the {{ic|-I}} parameter. For example:<br />
<br />
{{hc|~/.xinitrc|<br />
xrdb -I''$HOME'' ~/.Xresources<br />
}}<br />
<br />
=== Getting resource values ===<br />
<br />
If you want to get the value of a resource (for example if you want to use it in a bash script) you can use {{AUR|xgetres}}:<br />
<br />
$ xgetres xscreensaver.Dialog.headingFont<br />
-*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
== Sample usage ==<br />
<br />
The following samples should provide a good understanding of how application settings can be modified using an Xresources file. See [https://gist.github.com/anonymous/fa98de9fd70b51611303 this gist] for more examples. Refer to the man page of the application in question otherwise.<br />
<br />
* [[Color output in console#Terminal emulators]]<br />
* [[Cursor themes#X resources]]<br />
* [[Font configuration#Applications without fontconfig support]]<br />
* [[Xterm#Configuration]]<br />
* [[rxvt-unicode#Configuration]]<br />
* {{man|1|xpdf|OPTIONS}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Parsing errors ===<br />
<br />
[[Display manager]]s such as [[GDM]] may use the {{ic|--nocpp}} argument for ''xrdb''.<br />
<br />
=== No output from xrdb -query ===<br />
<br />
It is not rare for {{ic|xrdb -query}} to output nothing. Try following [[#Load resource file]] and [[#xinitrc]] from above. And note some of the files mentioned there could be empty.<br />
<br />
== See also ==<br />
<br />
* [https://engineering.purdue.edu/ECN/Support/KB/Docs/UsingTheXdefaultsFil Using the Xdefaults File] - An in-depth article on how X interprets the Xdefaults file</div>Comruminohttps://wiki.archlinux.org/index.php?title=OpenSSH&diff=749505OpenSSH2022-09-29T01:58:23Z<p>Comrumino: /* Usage */ Removed xhost references as the error referenced was due to improperly set DISPLAY and resolved accuracy template</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 />
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 other user on the SSH server you need to {{Ic|xauth add}} the authentication line taken from {{Ic|xauth list}} of the SSH logged in user.<br />
<br />
{{Tip|[https://unix.stackexchange.com/a/12772 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 separted with a comma, they will be connected to in the order listed. The {{ic|user...@}} part is not required, but can be used. The host specifications for {{ic|-J}} use the ssh configuration file, so specific per-host options can be set there, if needed.<br />
<br />
An equivalent of the {{ic|-J}} flag in the configuration file is the {{ic|ProxyJump}} option, see {{man|5|ssh_config}} for details.<br />
<br />
=== Reverse SSH through a relay ===<br />
<br />
{{Style|The idea of SSH tunneling is classic, so some references for detailed explanation would be nice. E.g. [https://unix.stackexchange.com/questions/46235/how-does-reverse-ssh-tunneling-work/118650#118650] which includes other scenarios.}}<br />
<br />
The idea is that client connects to the server via another relay, while the server is connected to the same relay using a reverse SSH tunnel. This is for example useful when the server is behind a NAT and relay is a publicly accessible SSH server used as a proxy to which the user has access. So the prerequisite is that client's keys are authorized against both the relay and the server and server's need to be authorized against the relay as well for the reverse SSH connection.<br />
<br />
The following configuration example assumes that user1 is the user account used on client, user2 on relay and user3 on server. First the server needs to establish the reverse tunnel with:<br />
<br />
ssh -R 2222:localhost:22 -N user2@relay<br />
<br />
Which can also be automated with a startup script, systemd service or [[#Autossh - automatically restarts SSH sessions and tunnels|autossh]].<br />
<br />
{{Expansion|Explain why {{ic|ssh user3@relay -p 2222}} is not sufficient.}}<br />
<br />
At the client side the connection is established with:<br />
<br />
ssh -t user2@relay ssh user3@localhost -p 2222<br />
<br />
The remote command to establish the connection to reverse tunnel can also be defined in relay's {{ic|~/.ssh/authorized_keys}} by including the {{ic|command}} field as follows:<br />
<br />
command="ssh user3@localhost -p 2222" ssh-rsa KEY2 user1@client<br />
<br />
In this case the connection is established with:<br />
<br />
ssh user2@relay<br />
<br />
Note that SCP's autocomplete function in client's terminal is not working and even the SCP transfers themselves are not working under some configurations.<br />
<br />
=== Multiplexing ===<br />
<br />
The SSH daemon usually listens on port 22. However, it is common practice for many public internet hotspots to block all traffic that is not on the regular HTTP/S ports (80 and 443, respectively), thus effectively blocking SSH connections. The immediate solution for this is to have {{ic|sshd}} listen additionally on one of the whitelisted ports:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
Port 22<br />
Port 443<br />
}}<br />
<br />
However, it is likely that port 443 is already in use by a web server serving HTTPS content, in which case it is possible to use a multiplexer, such as {{Pkg|sslh}}, which listens on the multiplexed port and can intelligently forward packets to many services.<br />
<br />
=== Speeding up SSH ===<br />
<br />
There are several [[#Configuration|client configuration]] options which can speed up connections either globally or for specific hosts. See {{man|5|ssh_config}} for full descriptions of these options.<br />
<br />
* ''Use a faster cipher'': on modern CPUs with AESNI instructions, {{ic|aes128-gcm@openssh.com}} and {{ic|aes256-gcm@openssh.com}} should offer significantly better performance over openssh's default preferred cipher, usually {{ic|chacha20-poly1305@openssh.com}}. Cipher can be selected 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 nmcli, and the connection is configured (manually or through DHCP) to use a search-domain:<br />
<br />
{{bc|1=<br />
Match exec "nmcli {{!}} grep domains: {{!}} grep example.com"<br />
CanonicalDomains example.com<br />
# Should you use a different username on this network<br />
#User username<br />
# Use a different known_hosts file (for private network or synchronisation)<br />
#UserKnownHostsFile <network>_known_hosts<br />
}}<br />
<br />
=== Private networks hostkeys verification ===<br />
<br />
Because different servers on different networks are likely to share a common private IP address, you might want to handle them differently.<br />
<br />
{{Accuracy|The best solution would not need a warning to use something else in practice.}}<br />
<br />
The best solution is to use the [[#Network specific configuration]] to use a different {{ic|UserKnownHostsFile}} depending on the network you are on. The second solution, best used as default when you are working on new/prototype networks, would be to simply ignore hostkeys for private networks:<br />
<br />
{{bc|1=<br />
Host 10.* 192.168.*.* 172.31.* 172.30.* 172.2?.* 172.1?.*<br />
# Disable HostKey verification<br />
# Trust HostKey automatically<br />
StrictHostKeyChecking no<br />
# Do not save the HostKey<br />
UserKnownHostsFile=/dev/null<br />
# Do not display: "Warning: Permanently Added ..."<br />
LogLevel Error<br />
}}<br />
<br />
{{Accuracy|The {{ic|known_hosts}} file records an IP address even when you use hostname to access the server.}}<br />
<br />
{{Warning|In a production environment, make sure to either use the hostname to access the host and/or to use network specific known_hosts files.}}<br />
<br />
=== Run command at login ===<br />
<br />
If you are using an interactive session, there are multiple ways to execute a command on login:<br />
<br />
* use the {{ic|authorized_keys}} file on the remote host (see {{ic|AUTHORIZED_KEYS FILE FORMAT}} in {{man|8|sshd}})<br />
* use {{ic|~/.ssh/rc}} on the remote host if the server has enabled the {{ic|PermitUserRC}} option<br />
* use your shell 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 trough 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>Comruminohttps://wiki.archlinux.org/index.php?title=OpenSSH&diff=749504OpenSSH2022-09-29T01:15:30Z<p>Comrumino: /* Remote */ Removed xorg-xhost from remote install step since it is only suitable for single user environments and not required</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 />
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 />
{{Accuracy|{{ic|xhost}} is [https://unix.stackexchange.com/questions/12755/how-to-forward-x-over-ssh-from-ubuntu-machine#comment17148_12772 generally not needed]|section=X11 forwarding}}<br />
<br />
Log on to the remote machine normally, specifying the {{ic|-X}} switch if ''ForwardX11'' was not enabled in the client's configuration file:<br />
<br />
$ ssh -X ''user@host''<br />
<br />
If you receive errors trying to run graphical applications, try ''ForwardX11Trusted'' instead:<br />
<br />
$ ssh -Y ''user@host''<br />
<br />
You can now start any X program on the remote server, the output will be forwarded to your local session:<br />
<br />
$ xclock<br />
<br />
If you get "Cannot open display" errors try the following command as the non root user:<br />
<br />
$ xhost +<br />
<br />
The above command will allow anybody to forward X11 applications. To restrict forwarding to a particular host type:<br />
<br />
$ xhost +hostname<br />
<br />
where hostname is the name of the particular host you want to forward to. See {{man|1|xhost}} for more details.<br />
<br />
Be careful with some applications as they check for a running instance on the local machine. [[Firefox]] is an example: either close the running Firefox instance or use the following start parameter to start a remote instance on the local machine:<br />
<br />
$ firefox --no-remote<br />
<br />
If you get "X11 forwarding request failed on channel 0" when you connect (and the server {{ic|/var/log/errors.log}} shows "Failed to allocate internet-domain X11 display socket"), make sure package {{Pkg|xorg-xauth}} is installed. If its installation is not working, try to either:<br />
<br />
* enable the {{ic|AddressFamily any}} option in {{ic|ssh'''d'''_config}} on the ''server'', or<br />
* set the {{ic|AddressFamily}} option in {{ic|ssh'''d'''_config}} on the ''server'' to inet.<br />
Setting it to inet may fix problems with Ubuntu clients on IPv4.<br />
<br />
For running X applications as other user on the SSH server you need to {{Ic|xauth add}} the authentication line taken from {{Ic|xauth list}} of the SSH logged in user.<br />
<br />
{{Tip|[https://unix.stackexchange.com/a/12772 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 separted with a comma, they will be connected to in the order listed. The {{ic|user...@}} part is not required, but can be used. The host specifications for {{ic|-J}} use the ssh configuration file, so specific per-host options can be set there, if needed.<br />
<br />
An equivalent of the {{ic|-J}} flag in the configuration file is the {{ic|ProxyJump}} option, see {{man|5|ssh_config}} for details.<br />
<br />
=== Reverse SSH through a relay ===<br />
<br />
{{Style|The idea of SSH tunneling is classic, so some references for detailed explanation would be nice. E.g. [https://unix.stackexchange.com/questions/46235/how-does-reverse-ssh-tunneling-work/118650#118650] which includes other scenarios.}}<br />
<br />
The idea is that client connects to the server via another relay, while the server is connected to the same relay using a reverse SSH tunnel. This is for example useful when the server is behind a NAT and relay is a publicly accessible SSH server used as a proxy to which the user has access. So the prerequisite is that client's keys are authorized against both the relay and the server and server's need to be authorized against the relay as well for the reverse SSH connection.<br />
<br />
The following configuration example assumes that user1 is the user account used on client, user2 on relay and user3 on server. First the server needs to establish the reverse tunnel with:<br />
<br />
ssh -R 2222:localhost:22 -N user2@relay<br />
<br />
Which can also be automated with a startup script, systemd service or [[#Autossh - automatically restarts SSH sessions and tunnels|autossh]].<br />
<br />
{{Expansion|Explain why {{ic|ssh user3@relay -p 2222}} is not sufficient.}}<br />
<br />
At the client side the connection is established with:<br />
<br />
ssh -t user2@relay ssh user3@localhost -p 2222<br />
<br />
The remote command to establish the connection to reverse tunnel can also be defined in relay's {{ic|~/.ssh/authorized_keys}} by including the {{ic|command}} field as follows:<br />
<br />
command="ssh user3@localhost -p 2222" ssh-rsa KEY2 user1@client<br />
<br />
In this case the connection is established with:<br />
<br />
ssh user2@relay<br />
<br />
Note that SCP's autocomplete function in client's terminal is not working and even the SCP transfers themselves are not working under some configurations.<br />
<br />
=== Multiplexing ===<br />
<br />
The SSH daemon usually listens on port 22. However, it is common practice for many public internet hotspots to block all traffic that is not on the regular HTTP/S ports (80 and 443, respectively), thus effectively blocking SSH connections. The immediate solution for this is to have {{ic|sshd}} listen additionally on one of the whitelisted ports:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
Port 22<br />
Port 443<br />
}}<br />
<br />
However, it is likely that port 443 is already in use by a web server serving HTTPS content, in which case it is possible to use a multiplexer, such as {{Pkg|sslh}}, which listens on the multiplexed port and can intelligently forward packets to many services.<br />
<br />
=== Speeding up SSH ===<br />
<br />
There are several [[#Configuration|client configuration]] options which can speed up connections either globally or for specific hosts. See {{man|5|ssh_config}} for full descriptions of these options.<br />
<br />
* ''Use a faster cipher'': on modern CPUs with AESNI instructions, {{ic|aes128-gcm@openssh.com}} and {{ic|aes256-gcm@openssh.com}} should offer significantly better performance over openssh's default preferred cipher, usually {{ic|chacha20-poly1305@openssh.com}}. Cipher can be selected 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 nmcli, and the connection is configured (manually or through DHCP) to use a search-domain:<br />
<br />
{{bc|1=<br />
Match exec "nmcli {{!}} grep domains: {{!}} grep example.com"<br />
CanonicalDomains example.com<br />
# Should you use a different username on this network<br />
#User username<br />
# Use a different known_hosts file (for private network or synchronisation)<br />
#UserKnownHostsFile <network>_known_hosts<br />
}}<br />
<br />
=== Private networks hostkeys verification ===<br />
<br />
Because different servers on different networks are likely to share a common private IP address, you might want to handle them differently.<br />
<br />
{{Accuracy|The best solution would not need a warning to use something else in practice.}}<br />
<br />
The best solution is to use the [[#Network specific configuration]] to use a different {{ic|UserKnownHostsFile}} depending on the network you are on. The second solution, best used as default when you are working on new/prototype networks, would be to simply ignore hostkeys for private networks:<br />
<br />
{{bc|1=<br />
Host 10.* 192.168.*.* 172.31.* 172.30.* 172.2?.* 172.1?.*<br />
# Disable HostKey verification<br />
# Trust HostKey automatically<br />
StrictHostKeyChecking no<br />
# Do not save the HostKey<br />
UserKnownHostsFile=/dev/null<br />
# Do not display: "Warning: Permanently Added ..."<br />
LogLevel Error<br />
}}<br />
<br />
{{Accuracy|The {{ic|known_hosts}} file records an IP address even when you use hostname to access the server.}}<br />
<br />
{{Warning|In a production environment, make sure to either use the hostname to access the host and/or to use network specific known_hosts files.}}<br />
<br />
=== Run command at login ===<br />
<br />
If you are using an interactive session, there are multiple ways to execute a command on login:<br />
<br />
* use the {{ic|authorized_keys}} file on the remote host (see {{ic|AUTHORIZED_KEYS FILE FORMAT}} in {{man|8|sshd}})<br />
* use {{ic|~/.ssh/rc}} on the remote host if the server has enabled the {{ic|PermitUserRC}} option<br />
* use your shell 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 trough 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>Comruminohttps://wiki.archlinux.org/index.php?title=Network_Time_Protocol_daemon&diff=748195Network Time Protocol daemon2022-09-24T18:22:57Z<p>Comrumino: /* NTP server mode */ I added the restrict flag "limited" as it is required by the kod flag and it is also specified within the official docs: https://support.ntp.org/bin/view/Support/AccessRestrictions#Section_6.5.1.1.4.</p>
<hr />
<div>[[Category:Network Time Protocol]]<br />
[[es:Network Time Protocol daemon]]<br />
[[ja:Network Time Protocol daemon]]<br />
[[ru:Network Time Protocol daemon]]<br />
[[zh-hans:Network Time Protocol daemon]]<br />
{{Related articles start}}<br />
{{Related|NTPSec}}<br />
{{Related|Chrony}}<br />
{{Related|Time synchronization}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Network Time Protocol|Network Time Protocol]] is the most common method to synchronize the [[System time|software clock]] of a GNU/Linux system with internet time servers. It is designed to mitigate the effects of variable network latency and can usually maintain time to within tens of milliseconds over the public Internet. The accuracy on local area networks is even better, up to one millisecond.<br />
<br />
[https://support.ntp.org/bin/view/Main/WebHome#The_NTP_Project The NTP Project] provides a reference implementation of the protocol called simply NTP. This article further describes how to set up and run the NTP daemon, both as a client and as a server.<br />
<br />
See [[System time#Time synchronization]] for other NTP implementations.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|ntp}} package. By default, ''ntpd'' works in client mode without further configuration. You can skip to [[#Usage]], if you want to use the Arch Linux default configuration file for it. For server configuration, see [[#NTP server mode]].<br />
<br />
== Configuration ==<br />
<br />
The main daemon is ''ntpd'', which is configured in {{ic|/etc/ntp.conf}}. Refer to {{man|5|ntp.conf}} for detail.<br />
<br />
=== Connection to NTP servers ===<br />
<br />
NTP servers are classified in a hierarchical system with many levels called ''strata'': the devices which are considered independent time sources are classified as ''stratum 0'' sources; the servers directly connected to ''stratum 0'' devices are classified as ''stratum 1'' sources; servers connected to ''stratum 1'' sources are then classified as ''stratum 2'' sources and so on.<br />
<br />
It has to be understood that a server's stratum cannot be taken as an indication of its accuracy or reliability. Typically, stratum 2 servers are used for general synchronization purposes: if you do not already know the servers you are going to connect to, you should choose a server pool close to your location from the [https://www.pool.ntp.org/ pool.ntp.org] servers ([https://support.ntp.org/bin/view/Servers/NTPPoolServers alternative link]).<br />
<br />
Since ''ntp'' version 4.2.7.p465-2, Arch Linux uses its own default vendor pool of NTP servers provided by [https://www.pool.ntp.org the NTP Pool Project] (see {{Bug|41700}}). Modify those to suit your needs, e.g. if you want to use your country's servers with an option:<br />
{{hc|/etc/ntp.conf|<br />
server 0.fr.pool.ntp.org iburst<br />
server 1.fr.pool.ntp.org iburst<br />
server 2.fr.pool.ntp.org iburst<br />
server 3.fr.pool.ntp.org iburst<br />
}}<br />
The {{ic|iburst}} option is recommended, and sends a burst of packets only if it cannot obtain a connection with the first attempt. The {{ic|burst}} option always does this, even on the first attempt, and should never be used without explicit permission and may result in blacklisting.<br />
<br />
=== NTP server mode ===<br />
<br />
If setting up an NTP server, check that you have [http://doc.ntp.org/archives/4.2.8-series/orphan/ orphan mode]{{Dead link|2022|09|22|status=404}} enabled, so that, in case it loses internet access, it will continue serving time to the network; enable orphan mode using the {{ic|tos}} configuration parameter (you can set up to [https://www.ntp.org/ntpfaq/NTP-s-algo.htm#Q-ALGO-BASIC-STRATUM stratum 15]) so that it will never be used unless internet access is lost:<br />
<br />
tos orphan 15<br />
<br />
Next, define the rules that will allow clients to connect to your service (''localhost'' is considered a client too) using the ''restrict'' command; you should already have a line like this in your file:<br />
<br />
restrict default nomodify nopeer noquery<br />
<br />
This restricts everyone from modifying anything and prevents everyone from querying the status of your time server: {{ic|nomodify}} prevents reconfiguring ''ntpd'' (with ''ntpq'' or ''ntpdc''), and {{ic|noquery}} is important to [https://lists.archlinux.org/archives/list/arch-dev-public@lists.archlinux.org/thread/QOJ3ADKWXOQ2HCW6WSLIS3N2U6SC7YV7/ prevent] dumping status data from ''ntpd'' (also with ''ntpq'' or ''ntpdc'').<br />
<br />
You can also add other options:<br />
<br />
restrict default kod limited nomodify notrap nopeer noquery<br />
<br />
{{Note|This still allows other people to query your time server. You need to add {{ic|noserve}} to stop serving time. It will also block time synchronization since it blocks all packets except ''ntpq'' and ''ntpdc'' queries.}}<br />
<br />
If you want to change any of these, see the full docs for the "restrict" option in {{man|5|ntp.conf}}, the detailed ntp [https://support.ntp.org/bin/view/Support/AccessRestrictions instructions] and [[#Usage]].<br />
<br />
Following this line, you need to tell ''ntpd'' what to allow through into your server; the following line is enough if you are not configuring an NTP server:<br />
<br />
restrict 127.0.0.1<br />
<br />
If you want to force DNS resolution to the IPv6 namespace, write {{ic|-6}} before the IP address or host name ({{ic|-4}} forces IPv4 instead), for example:<br />
<br />
restrict -6 default kod limited nomodify notrap nopeer noquery<br />
restrict -6 ::1 # ::1 is the IPv6 equivalent for 127.0.0.1<br />
<br />
Lastly, specify the drift file (which keeps track of your clock's time deviation) and optionally the log file location:<br />
<br />
driftfile /var/lib/ntp/ntp.drift<br />
logfile /var/log/ntp.log<br />
<br />
A very basic configuration file will look like this:<br />
<br />
{{hc|/etc/ntp.conf|<br />
server 0.pool.ntp.org iburst<br />
server 1.pool.ntp.org iburst<br />
server 2.pool.ntp.org iburst<br />
server 3.pool.ntp.org iburst<br />
tos orphan 15<br />
<br />
restrict default kod limited nomodify notrap nopeer noquery<br />
restrict -6 default kod limited nomodify notrap nopeer noquery<br />
<br />
restrict 127.0.0.1<br />
restrict -6 ::1 <br />
<br />
driftfile /var/lib/ntp/ntp.drift<br />
logfile /var/log/ntp.log<br />
}}<br />
<br />
{{Note|Defining the log file is not mandatory, but it is always a good idea to have feedback for ''ntpd'' operations.}}<br />
<br />
== Usage ==<br />
<br />
The package has a default client-mode configuration and its own user and group to drop root privileges after starting. If you start it from the console, you should always do so with the {{ic|-u}} option:<br />
<br />
# ntpd -u ntp:ntp<br />
<br />
The {{ic|-u}} option is employed by the two included systemd services. These services also use the {{ic|-g}} option, which disables a threshold (so-called ''panic-gate''). Hence, they will synchonize time even in case the ntp-server's time exceeds the threshold deviation from the system clock.<br />
<br />
{{Warning|One reason the panic-gate was introduced is that background jobs/services may be susceptible to time-jumps. If the system's clock was never synchronized before, consider stopping them before running ''ntpd'' for the first time.}}<br />
<br />
Both services are tied to the system's resolver, and will start synchronizing when an active network connection is detected.<br />
<br />
=== Start ntpd at boot ===<br />
<br />
[[Enable]] the daemon with {{ic|ntpd.service}}. See also [[#Running in a chroot]].<br />
<br />
{{Note|The systemd command ''timedatectl'' can only be used to control [[systemd-timesyncd]]. Executing {{ic|timedatectl set-ntp 1}} as root will inadvertedly stop a running {{ic|ntpd.service}}.[https://lists.freedesktop.org/archives/systemd-devel/2015-April/030277.html]}}<br />
<br />
Use ''ntpq'' to see the list of configured peers and status of synchronization:<br />
<br />
$ ntpq -p<br />
<br />
The delay, offset and jitter columns should be non-zero. The servers ''ntpd'' is synchronizing with are prefixed by an asterisk. It can take several minutes before ''ntpd'' selects a server to synchronize with; try checking after 17 minutes (1024 seconds).<br />
<br />
=== Synchronize time once per boot ===<br />
<br />
Alternatively, [[enable]] {{ic|ntpdate.service}} to synchronize time once (option {{ic|-q}}) and non-forking (option {{ic|-n}}) per boot, instead of running the daemon in the background. This method is discouraged on servers, and in general on machines that run without rebooting for more than a few days.<br />
<br />
If the synchronized time should be written to the hardware clock as well, configure the provided unit as described in [[systemd#Editing provided units]] before starting it:<br />
<br />
{{hc|/etc/systemd/system/ntpdate.service.d/hwclock.conf|2=<br />
[Service]<br />
ExecStart=/usr/bin/hwclock -w<br />
}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Start ntpd on network connection ===<br />
<br />
''ntpd'' can be started by your network manager, so that the daemon only runs when the computer is online.<br />
<br />
==== Netctl ====<br />
<br />
{{Style|add {{ic|-u}} and optionally refer to [[#Usage]], or use systemctl if possible}}<br />
<br />
Append the following lines to your [[netctl]] profile:<br />
<br />
ExecUpPost='/usr/bin/ntpd || true'<br />
ExecDownPre='killall ntpd || true'<br />
<br />
==== NetworkManager ====<br />
<br />
The ''ntpd'' daemon can be brought up/down along with a network connection through the use of NetworkManager's [[NetworkManager#Network services with NetworkManager dispatcher|dispatcher]] scripts. The {{AUR|networkmanager-dispatcher-ntpd}} package installs one, pre-configured to start and stop the [[#Start ntpd at boot|ntpd service]] with a connection.<br />
<br />
==== KDE ====<br />
<br />
KDE can use NTP (ntp must be installed) by right clicking the clock and selecting ''Adjust date/time''. However, this requires the ntp daemon to be [[disable]]d before configuring KDE to use NTP. [https://bugs.kde.org/show_bug.cgi?id=178968]<br />
<br />
=== Using ntpd with GPS ===<br />
<br />
Most of the articles online about configuring ''ntpd'' to receive time from a GPS suggest to use the SHM (shared memory) method. However, at least since ''ntpd'' version 4.2.8 a ''much better'' method is available. It connects directly to ''gpsd'', so {{Pkg|gpsd}} needs to be installed.<br />
<br />
Add these lines to your {{ic|/etc/ntp.conf}}:<br />
<br />
{{hc|head=/etc/ntp.conf|output=<br />
#=========================================================<br />
# GPSD native ntpd driver<br />
#=========================================================<br />
# This driver exists from at least ntp version 4.2.8<br />
# Details at<br />
# https://www.eecis.udel.edu/~mills/ntp/html/drivers/driver46.html<br />
server 127.127.46.0 <br />
fudge 127.127.46.0 time1 0.0 time2 0.0 refid GPS <br />
}}<br />
<br />
This will work as long as you have ''gpsd'' working. It connects to ''gpsd'' via the local socket and queries the "gpsd_json" object that is returned.<br />
<br />
To test the setup, first ensure that ''gpsd'' is working by running:<br />
<br />
$ cgps -s <br />
<br />
Then wait a few minutes and run {{ic|ntpq -p}}. This will show if ''ntpd'' is talking to ''gpsd'':<br />
<br />
{{hc|$ ntpq -p|output=<br />
remote refid st t when poll reach delay offset jitter<br />
==================================================================================<br />
*GPSD_JSON(0) .GPS. 0 l 55 64 377 0.000 2.556 14.109<br />
}}<br />
<br />
{{Tip|<br />
* If the ''reach'' column is 0, it means ''ntpd'' has not been able to talk to ''gpsd''. Wait a few minutes and try again. Sometimes it takes ''ntpd'' a while.<br />
* The GPS device must have PPS capabilities. You can test if your device is capable running {{ic|ppscheck /dev/gps0}}.<br />
}}<br />
<br />
{{Note|''ntpd'' expects that your GPS device is called e.g. {{ic|/dev/gps0}}. If your GPS device is connected via USB, it may appear as {{ic|/dev/ttyUSB0}} instead, and you may have to create a symlink {{ic|ln -s /dev/ttyUSB0 /dev/gps0}} and run ''gpsd'' on that linked {{ic|/dev/gps0}} so that the {{ic|GPSD_JSON}} line appears as expected. ''gpsd'' should be run with the {{ic|-n}} flag on the {{ic|GPSD_OPTIONS}} line and use {{ic|/dev/gps0}} on the {{ic|DEVICES}} line in the {{ic|/etc/default/gpsd}} config file.}}<br />
<br />
=== Running in a chroot ===<br />
<br />
{{Note|''ntpd'' should be started as non-root (default in the Arch Linux package) before attempting to jail it in a chroot, since chroots are relatively useless at securing processes running as root.}}<br />
<br />
Create a new directory {{ic|/etc/systemd/system/ntpd.service.d/}} if it does not exist and a file named {{ic|customexec.conf}} inside with the following content:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/bin/ntpd -g -u ntp:ntp '''-i /var/lib/ntp'''<br />
<br />
Then, edit {{ic|/etc/ntp.conf}} to change the driftfile path such that it is relative to the chroot directory, rather than to the real system root. Change:<br />
driftfile /var/lib/ntp/ntp.drift<br />
<br />
to<br />
driftfile /ntp.drift<br />
<br />
Create a suitable chroot environment so that getaddrinfo() will work by creating pertinent directories and files (as root):<br />
<br />
# mkdir /var/lib/ntp/etc /var/lib/ntp/lib /var/lib/ntp/proc<br />
# mkdir /var/lib/ntp/usr /var/lib/ntp/usr/lib<br />
# touch /var/lib/ntp/etc/resolv.conf /var/lib/ntp/etc/services<br />
<br />
and by bind-mounting the aformentioned files:<br />
<br />
{{hc|/etc/fstab|<br />
...<br />
#ntpd chroot mounts<br />
/etc/resolv.conf /var/lib/ntp/etc/resolv.conf none bind 0 0<br />
/etc/services /var/lib/ntp/etc/services none bind 0 0<br />
/lib /var/lib/ntp/lib none bind 0 0<br />
/usr/lib /var/lib/ntp/usr/lib none bind 0 0<br />
/proc /var/lib/ntp/proc none bind 0 0<br />
}}<br />
<br />
# mount -a<br />
<br />
Finally, restart {{ic|ntpd}} daemon again. Once it restarted you can verify that the daemon process is chrooted by checking where {{ic|/proc/{PID}/root}} symlinks to: <br />
<br />
# ps -C ntpd | awk '{print $1}' | sed 1d | while read -r PID; do ls -l /proc/$PID/root; done<br />
<br />
should now link to {{ic|/var/lib/ntp}} instead of {{ic|/}}.<br />
<br />
It is relatively difficult to be sure that your driftfile configuration is actually working without waiting a while, as ''ntpd'' does not read or write it very often. If you get it wrong, it will log an error; if you get it right, it will update the timestamp. If you do not see any errors about it after a full day of running, and the timestamp is updated, you should be confident of success.<br />
<br />
=== Restrict listening sockets ===<br />
<br />
You can limit sockets ''ntpd'' is listening to using the ''interface'' option:<br />
interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | name | address[/prefixlen]]<br />
<br />
like<br />
<br />
{{hc|head=/etc/ntp.conf|output=<br />
interface listen lo<br />
interface listen enp3s0<br />
interface ignore enp5s0<br />
}}<br />
<br />
== See also ==<br />
<br />
* https://www.ntp.org/<br />
* https://support.ntp.org/<br />
* https://www.pool.ntp.org/<br />
* https://www.eecis.udel.edu/~mills/ntp/html/index.html<br />
* https://www.akadia.com/services/ntp_synchronize.html</div>Comruminohttps://wiki.archlinux.org/index.php?title=User:Comrumino&diff=735967User:Comrumino2022-07-01T23:37:21Z<p>Comrumino: for padding the resume, it is helpful to note home many contribution are from my old handle</p>
<hr />
<div>'''Useful wikis:'''<br />
* [https://wiki.archlinux.org/index.php/Category:Help Help]<br />
* [https://wiki.archlinux.org/index.php/Help:Template#List_of_templates List of templates]<br />
<br />
'''Searches:'''<br />
* [https://wiki.archlinux.org/index.php?title=Special%3AWhatLinksHere&target=Template%3AAccuracy&namespace= Template:Accuracy]<br />
* [https://wiki.archlinux.org/index.php?title=Special%3AWhatLinksHere&target=Template%3AStyle&namespace= Template:Style]<br />
* [https://wiki.archlinux.org/index.php?title=Special:WhatLinksHere&target=User:Comrumino&namespace=4&invert=1 Links to user]<br />
<br />
'''Subpages:'''<br />
* [[/Pentration test]]<br />
<br />
'''Contributions:'''<br />
* [[Special:Contributions/Comrumino|Comrumino - more than 195 contributions]]<br />
* [[Special:Contributions/StrayArch|StrayArch (legacy) - 147 contributions]]<br />
<br />
'''Contact info:'''<br />
* [https://www.linkedin.com/in/stronz/| linkedin]<br />
* [https://stro.nz/| personal website]</div>Comruminohttps://wiki.archlinux.org/index.php?title=OpenSSH&diff=735943OpenSSH2022-07-01T16:34:08Z<p>Comrumino: /* Troubleshooting */ Added trouble shooting subsection for an subsystem error that I experienced since there was previously no mention of subsystem settings or errors</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 />
{{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 />
This is highly useful for laptop users connected to various unsafe wireless connections. The only thing you need is an SSH server running at a somewhat secure location, like your home or at work. It might be useful to use a dynamic DNS service like [https://dyn.com/dns/ DynDNS] so you do not have to remember your IP-address.<br />
<br />
==== Step 1: start the connection ====<br />
<br />
You only have to execute this single command to start the connection:<br />
<br />
$ ssh -TND 4711 ''user''@''host''<br />
<br />
where {{Ic|''user''}} is your username at the SSH server running at the {{Ic|''host''}}. It will ask for your password, and then you are connected. The {{Ic|N}} flag disables the interactive prompt, and the {{Ic|D}} flag specifies the local port on which to listen on (you can choose any port number if you want). The {{Ic|T}} flag disables pseudo-tty allocation.<br />
<br />
It is nice to add the verbose ({{Ic|-v}}) flag, because then you can verify that it is actually connected from that output.<br />
<br />
==== Step 2 (Variant A): configure your browser (or other programs) ====<br />
<br />
The above step is useful only in combination with a web browser or another program that uses this newly created SOCKS tunnel. Since SSH currently supports both SOCKS v4 and SOCKS v5, you can use either of them.<br />
<br />
* For Firefox: At ''Preferences > General'' navigates to the bottom of the page and click ''Settings...'', which is to the right of the Network Settings title. Next, within the new semi window, check the ''Manual proxy configuration'' option and enter {{ic|localhost}} in the ''SOCKS host'' text field, and the port number in the ''Port'' text field ({{ic|4711}} in the example above) next to it.<br />
:Firefox does not automatically make DNS requests through the socks tunnel. This potential privacy concern can be mitigated by scrolling further down, checking in the ''Proxy DNS when using SOCKS v5''. Obviously, this will only work if you chooses SOCKS v5 rather then v4.<br />
: Restart Firefox to activate these settings.<br />
<br />
* For Chromium: You can set the SOCKS settings as environment variables or as command line options. I recommend to add one of the following functions to your {{ic|.bashrc}}:<br />
<br />
function secure_chromium {<br />
port=4711<br />
export SOCKS_SERVER=localhost:$port<br />
export SOCKS_VERSION=5<br />
chromium &<br />
exit<br />
}<br />
<br />
OR<br />
<br />
function secure_chromium {<br />
port=4711<br />
chromium --proxy-server="socks://localhost:$port" &<br />
exit<br />
}<br />
<br />
Now open a terminal and just do:<br />
<br />
$ secure_chromium<br />
<br />
Enjoy your secure tunnel!<br />
<br />
==== Step 2 (Variant B): set up a local TUN interface ====<br />
<br />
This variant is slightly more involved upfront but results in you not having to manually configure every single application one by one to use the SOCKS proxy. It involves setting up a local TUN interface and routing traffic through it.<br />
<br />
See [[VPN over SSH#Set up badvpn and tunnel interface]].<br />
<br />
=== X11 forwarding ===<br />
<br />
X11 forwarding is a mechanism that allows graphical interfaces of X11 programs running on a remote system to be displayed on a local client machine. For X11 forwarding the remote host does not need to have a full X11 system installed, however it needs at least to have ''xauth'' installed. ''xauth'' is a utility that maintains {{ic|Xauthority}} configurations used by server and client for authentication of X11 session ([http://xmodulo.com/2012/11/how-to-enable-x11-forwarding-using-ssh.html source]).<br />
<br />
{{Warning|X11 forwarding has important security implications which should be at least acknowledged by reading relevant sections of {{man|1|ssh}}, {{man|5|sshd_config}}, and {{man|5|ssh_config}} manual pages. See also [https://security.stackexchange.com/questions/14815/security-concerns-with-x11-forwarding this StackExchange question.]}}<br />
<br />
==== Setup ====<br />
<br />
===== Remote =====<br />
<br />
* [[install]] the {{Pkg|xorg-xauth}} and {{Pkg|xorg-xhost}} packages<br />
* in {{ic|/etc/ssh/ssh'''d'''_config}}:<br />
** set {{ic|X11Forwarding}} to ''yes''<br />
** verify that {{ic|AllowTcpForwarding}} and {{ic|X11UseLocalhost}} options are set to ''yes'', and that {{ic|X11DisplayOffset}} is set to ''10'' (those are the default values if nothing has been changed, see {{man|5|sshd_config}})<br />
* then [[restart]] the [[#Daemon management|''sshd'' daemon]].<br />
<br />
===== Client =====<br />
<br />
* [[install]] the {{Pkg|xorg-xauth}} package<br />
* enable the {{ic|ForwardX11}} option by either specifying the {{ic|-X}} switch on the command line for opportunistic connections, or by setting {{ic|ForwardX11}} to ''yes'' in the [[#Configuration|client's configuration]].<br />
<br />
{{Tip|You can enable the {{ic|ForwardX11Trusted}} option ({{ic|-Y}} switch on the command line) if GUI is drawing badly or you receive errors; this will prevent X11 forwardings from being subjected to the [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 />
{{Accuracy|{{ic|xhost}} is [https://unix.stackexchange.com/questions/12755/how-to-forward-x-over-ssh-from-ubuntu-machine#comment17148_12772 generally not needed]|section=X11 forwarding}}<br />
<br />
Log on to the remote machine normally, specifying the {{ic|-X}} switch if ''ForwardX11'' was not enabled in the client's configuration file:<br />
<br />
$ ssh -X ''user@host''<br />
<br />
If you receive errors trying to run graphical applications, try ''ForwardX11Trusted'' instead:<br />
<br />
$ ssh -Y ''user@host''<br />
<br />
You can now start any X program on the remote server, the output will be forwarded to your local session:<br />
<br />
$ xclock<br />
<br />
If you get "Cannot open display" errors try the following command as the non root user:<br />
<br />
$ xhost +<br />
<br />
The above command will allow anybody to forward X11 applications. To restrict forwarding to a particular host type:<br />
<br />
$ xhost +hostname<br />
<br />
where hostname is the name of the particular host you want to forward to. See {{man|1|xhost}} for more details.<br />
<br />
Be careful with some applications as they check for a running instance on the local machine. [[Firefox]] is an example: either close the running Firefox instance or use the following start parameter to start a remote instance on the local machine:<br />
<br />
$ firefox --no-remote<br />
<br />
If you get "X11 forwarding request failed on channel 0" when you connect (and the server {{ic|/var/log/errors.log}} shows "Failed to allocate internet-domain X11 display socket"), make sure package {{Pkg|xorg-xauth}} is installed. If its installation is not working, try to either:<br />
<br />
* enable the {{ic|AddressFamily any}} option in {{ic|ssh'''d'''_config}} on the ''server'', or<br />
* set the {{ic|AddressFamily}} option in {{ic|ssh'''d'''_config}} on the ''server'' to inet.<br />
Setting it to inet may fix problems with Ubuntu clients on IPv4.<br />
<br />
For running X applications as other user on the SSH server you need to {{Ic|xauth add}} the authentication line taken from {{Ic|xauth list}} of the SSH logged in user.<br />
<br />
{{Tip|[https://unix.stackexchange.com/a/12772 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 separted with a comma, they will be connected to in the order listed. The {{ic|user...@}} part is not required, but can be used. The host specifications for {{ic|-J}} use the ssh configuration file, so specific per-host options can be set there, if needed.<br />
<br />
An equivalent of the {{ic|-J}} flag in the configuration file is the {{ic|ProxyJump}} option, see {{man|5|ssh_config}} for details.<br />
<br />
=== Reverse SSH through a relay ===<br />
<br />
{{Style|The idea of SSH tunneling is classic, so some references for detailed explanation would be nice. E.g. [https://unix.stackexchange.com/questions/46235/how-does-reverse-ssh-tunneling-work/118650#118650] which includes other scenarios.}}<br />
<br />
The idea is that client connects to the server via another relay, while the server is connected to the same relay using a reverse SSH tunnel. This is for example useful when the server is behind a NAT and relay is a publicly accessible SSH server used as a proxy to which the user has access. So the prerequisite is that client's keys are authorized against both the relay and the server and server's need to be authorized against the relay as well for the reverse SSH connection.<br />
<br />
The following configuration example assumes that user1 is the user account used on client, user2 on relay and user3 on server. First the server needs to establish the reverse tunnel with:<br />
<br />
ssh -R 2222:localhost:22 -N user2@relay<br />
<br />
Which can also be automated with a startup script, systemd service or [[#Autossh - automatically restarts SSH sessions and tunnels|autossh]].<br />
<br />
{{Expansion|Explain why {{ic|ssh user3@relay -p 2222}} is not sufficient.}}<br />
<br />
At the client side the connection is established with:<br />
<br />
ssh -t user2@relay ssh user3@localhost -p 2222<br />
<br />
The remote command to establish the connection to reverse tunnel can also be defined in relay's {{ic|~/.ssh/authorized_keys}} by including the {{ic|command}} field as follows:<br />
<br />
command="ssh user3@localhost -p 2222" ssh-rsa KEY2 user1@client<br />
<br />
In this case the connection is established with:<br />
<br />
ssh user2@relay<br />
<br />
Note that SCP's autocomplete function in client's terminal is not working and even the SCP transfers themselves are not working under some configurations.<br />
<br />
=== Multiplexing ===<br />
<br />
The SSH daemon usually listens on port 22. However, it is common practice for many public internet hotspots to block all traffic that is not on the regular HTTP/S ports (80 and 443, respectively), thus effectively blocking SSH connections. The immediate solution for this is to have {{ic|sshd}} listen additionally on one of the whitelisted ports:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
Port 22<br />
Port 443<br />
}}<br />
<br />
However, it is likely that port 443 is already in use by a web server serving HTTPS content, in which case it is possible to use a multiplexer, such as {{Pkg|sslh}}, which listens on the multiplexed port and can intelligently forward packets to many services.<br />
<br />
=== Speeding up SSH ===<br />
<br />
There are several [[#Configuration|client configuration]] options which can speed up connections either globally or for specific hosts. See {{man|5|ssh_config}} for full descriptions of these options.<br />
<br />
* ''Use a faster cipher'': on modern CPUs with AESNI instructions, {{ic|aes128-gcm@openssh.com}} and {{ic|aes256-gcm@openssh.com}} should offer significantly better performance over openssh's default preferred cipher, usually {{ic|chacha20-poly1305@openssh.com}}. Cipher can be selected {{ic|-c}} flag. For a permanent effect, put {{ic|Ciphers}} option in your {{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 nmcli, and the connection is configured (manually or through DHCP) to use a search-domain:<br />
<br />
{{bc|1=<br />
Match exec "nmcli {{!}} grep domains: {{!}} grep example.com"<br />
CanonicalDomains example.com<br />
# Should you use a different username on this network<br />
#User username<br />
# Use a different known_hosts file (for private network or synchronisation)<br />
#UserKnownHostsFile <network>_known_hosts<br />
}}<br />
<br />
=== Private networks hostkeys verification ===<br />
<br />
Because different servers on different networks are likely to share a common private IP address, you might want to handle them differently.<br />
<br />
{{Accuracy|The best solution would not need a warning to use something else in practice.}}<br />
<br />
The best solution is to use the [[#Network specific configuration]] to use a different {{ic|UserKnownHostsFile}} depending on the network you are on. The second solution, best used as default when you are working on new/prototype networks, would be to simply ignore hostkeys for private networks:<br />
<br />
{{bc|1=<br />
Host 10.* 192.168.*.* 172.31.* 172.30.* 172.2?.* 172.1?.*<br />
# Disable HostKey verification<br />
# Trust HostKey automatically<br />
StrictHostKeyChecking no<br />
# Do not save the HostKey<br />
UserKnownHostsFile=/dev/null<br />
# Do not display: "Warning: Permanently Added ..."<br />
LogLevel Error<br />
}}<br />
<br />
{{Accuracy|The {{ic|known_hosts}} file records an IP address even when you use hostname to access the server.}}<br />
<br />
{{Warning|In a production environment, make sure to either use the hostname to access the host and/or to use network specific known_hosts files.}}<br />
<br />
=== Run command at login ===<br />
<br />
If you are using an interactive session, there are multiple ways to execute a command on login:<br />
<br />
* use the {{ic|authorized_keys}} file on the remote host (see {{ic|AUTHORIZED_KEYS FILE FORMAT}} in {{man|8|sshd}})<br />
* use {{ic|~/.ssh/rc}} on the remote host if the server has enabled the {{ic|PermitUserRC}} option<br />
* use your shell 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 [https://man.archlinux.org/man/sshd_config.5#Subsystem Subsystem] settings. 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 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 trough 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>Comruminohttps://wiki.archlinux.org/index.php?title=Xinit&diff=733008Xinit2022-06-17T04:17:43Z<p>Comrumino: /* Tips and tricks */ Rewrote note about the need to set DISPLAY when overriding the display to make the note more understandable to readers.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Xorg commands]]<br />
[[de:Xinitrc]]<br />
[[es:Xinit]]<br />
[[fr:Xinit]]<br />
[[ja:Xinit]]<br />
[[pt:Xinit]]<br />
[[ru:Xinit]]<br />
[[zh-hans:Xinit]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related|Xorg}}<br />
{{Related|xprofile}}<br />
{{Related|Xresources}}<br />
{{Related articles end}}<br />
From [[Wikipedia:xinit|Wikipedia]]:<br />
:The '''xinit''' program allows a user to manually start an [[Xorg]] display server. The {{man|1|startx}} script is a front-end for {{man|1|xinit}}.<br />
<br />
''xinit'' is typically used to start [[window manager]]s or [[desktop environment]]s. While you can also use ''xinit'' to run GUI applications without a window manager, many graphical applications expect an [[Wikipedia:Extended Window Manager Hints|EWMH]] compliant window manager. [[Display manager]]s start [[Xorg]] for you and generally source [[xprofile]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|xorg-xinit}} package.<br />
<br />
== Configuration ==<br />
<br />
''xinit'' and ''startx'' take an optional client program argument, see [[#Override xinitrc]]. If you do not provide one they will look for {{ic|~/.xinitrc}} to run as a shell script to start up client programs.<br />
<br />
=== xinitrc ===<br />
<br />
{{ic|~/.xinitrc}} is handy to run programs depending on X and set environment variables on X server startup. If it is present in a user's home directory, ''startx'' and ''xinit'' execute it. Otherwise ''startx'' will run the default {{ic|/etc/X11/xinit/xinitrc}}.<br />
<br />
{{note|''Xinit'' has its own default behaviour instead of executing the file. See {{man|1|xinit}} for details.}}<br />
<br />
This default xinitrc will start a basic environment with [[Twm]], {{Pkg|xorg-xclock}} and [[Xterm]] (assuming that the necessary packages are installed). Therefore, to start a different window manager or desktop environment, first create a copy of the default {{ic|xinitrc}} in your home directory:<br />
<br />
$ cp /etc/X11/xinit/xinitrc ~/.xinitrc<br />
<br />
Then [[Help:Reading#Append, add, create, edit|edit]] the file and replace the default programs with desired commands. Remember that lines following a command using {{ic|exec}} would be ignored. For example, to start {{ic|xscreensaver}} in the background and then start [[Openbox#Standalone|openbox]], use the following:<br />
<br />
{{hc|~/.xinitrc|<br />
...<br />
xscreensaver &<br />
exec openbox-session}}<br />
<br />
{{Note|At the very least, ensure that the last {{ic|if}} block in {{ic|/etc/X11/xinit/xinitrc}} is present in your {{ic|~/.xinitrc}} file to ensure that the scripts in {{ic|/etc/X11/xinit/xinitrc.d}} are sourced.}} <br />
<br />
Long-running programs started before the window manager, such as a screensaver and wallpaper application, must either fork themselves or be run in the background by appending an {{ic|&}} sign. Otherwise, the script would halt and wait for each program to exit before executing the window manager or desktop environment. Note that some programs should instead not be forked, to avoid race bugs, as is the case of [[xrdb]]. Prepending {{ic|exec}} will replace the script process with the window manager process, so that X does not exit even if this process forks to the background.<br />
<br />
=== xserverrc ===<br />
<br />
The {{ic|xserverrc}} file is a shell script responsible for starting up the X server. Both ''startx'' and ''xinit'' execute {{ic|~/.xserverrc}} if it exists, ''startx'' will use {{ic|/etc/X11/xinit/xserverrc}} otherwise.<br />
<br />
In order to maintain an [[General troubleshooting#Session permissions|authenticated session]] with {{ic|logind}} and to prevent bypassing the screen locker by switching terminals, [[Xorg]] has to be started on the same virtual terminal where the login occurred [http://blog.falconindy.com/articles/back-to-basics-with-x-and-systemd.html]. Therefore it is recommended to specify {{ic|vt$XDG_VTNR}} in the {{ic|~/.xserverrc}} file:<br />
<br />
{{hc|~/.xserverrc|<br />
#!/bin/sh<br />
<br />
exec /usr/bin/Xorg -nolisten tcp "$@" vt$XDG_VTNR<br />
}}<br />
<br />
See {{man|1|Xserver}} for a list of all command line options.<br />
<br />
{{Tip|{{ic|-nolisten local}} can be added after {{ic|-nolisten tcp}} to disable abstract sockets of X11 to help with isolation. There is a [https://tstarling.com/blog/2016/06/x11-security-isolation/ quick background] on how this potentially affects X11 security.}}<br />
<br />
Alternatively, if you wish to have the X display on a separate console from the one where the server is invoked, you can do so by using the X server wrapper provided by {{ic|/usr/lib/systemd/systemd-multi-seat-x}}. For convenience, ''xinit'' and ''startx'' can be set up to use this wrapper by modifying your {{ic|~/.xserverrc}}.<br />
<br />
{{Note|To re-enable redirection of the output from X session into the Xorg log file, add the {{ic|-keeptty}} option. See [[Xorg#Session log redirection]] for details.}}<br />
<br />
== Usage ==<br />
<br />
To run Xorg as a regular user, issue:<br />
<br />
$ startx<br />
<br />
Or if [[#xserverrc]] is configured:<br />
<br />
$ xinit -- :1<br />
<br />
{{Note|''xinit'' does not handle multiple displays when another X server is already started. For that you must specify the display by appending {{ic|-- :''display_number''}}, where {{ic|''display_number''}} is {{ic|1}} or more.}}<br />
<br />
Your window manager (or desktop environment) of choice should now start correctly.<br />
<br />
To quit X, run your window manager's exit function (assuming it has one). If it lacks such functionality, run:<br />
<br />
$ pkill -15 Xorg<br />
<br />
{{Note|''pkill'' will kill all running X instances. To specifically kill the window manager on the current virtual terminal, run:<br />
<br />
$ pkill -15 -t tty"$XDG_VTNR" Xorg<br />
}}<br />
<br />
See also {{man|7|signal}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Override xinitrc ===<br />
<br />
If you have a working {{ic|~/.xinitrc}} but just want to try other window manager or desktop environment, you can run it by issuing ''startx'' followed by the path to the window manager, for example:<br />
<br />
$ startx /usr/bin/i3<br />
<br />
If the binary takes arguments, they need to be quoted to be recognized as part of the first parameter of ''startx'':<br />
<br />
$ startx "/usr/bin/''application'' --''key value''"<br />
<br />
Note that the full path is '''required'''. You can also specify custom options for the [[#xserverrc]] script by appending them after the double dash {{ic|--}} sign:<br />
<br />
$ startx /usr/bin/enlightenment -- -br +bs -dpi 96<br />
<br />
See also {{man|1|startx}}.<br />
<br />
{{Note|1=Since the scripts under {{ic|/etc/X11/xinit/xinitrc.d/}} are skipped, in this scenario, the environment variable {{ic|DISPLAY}} may need be to set. You can try out ''i3'' on the desired display by executing {{ic|DISPLAY<nowiki>=</nowiki>:''display_number'' startx /usr/bin/i3}}.}}<br />
<br />
{{Tip|This can be used to start regular GUI programs but without any of the basic window manager features. See also [[#Starting applications without a window manager]] and [[Running program in separate X display]].}}<br />
<br />
=== Autostart X at login ===<br />
<br />
Make sure that ''startx'' is properly [[#Configuration|configured]].<br />
<br />
Place the following in your [[login shell]] initialization file (e.g. {{ic|~/.bash_profile}} for [[Bash]] or {{ic|~/.zprofile}} for [[Zsh]]):<br />
<br />
{{bc|1=<nowiki><br />
if [ -z "${DISPLAY}" ] && [ "${XDG_VTNR}" -eq 1 ]; then<br />
exec startx<br />
fi<br />
</nowiki>}}<br />
<br />
You can replace the {{ic|-eq}} comparison with one like {{ic|-le 3}} (for vt1 to vt3) if you want to use graphical logins on more than one virtual terminal.<br />
<br />
Alternative conditions to detect the virtual terminal include {{ic|<nowiki>"$(tty)" = "/dev/tty1"</nowiki>}}, which does not allow comparison with {{ic|-le}}, and {{ic|<nowiki>"$(fgconsole 2>/dev/null || echo -1)" -eq 1</nowiki>}}, which does not work in [[serial console]]s.<br />
<br />
The {{ic|exec}} command ensures that the user is logged out when the X server exits, crashes or is killed by an attacker. If you want to take the risk and remain logged in when the X session ends, remove {{ic|exec}}.<br />
<br />
See also [[Fish#Start X at login]] and [[Systemd/User#Automatic login into Xorg without display manager]].<br />
<br />
{{Tip|This method can be combined with [[automatic login to virtual console]].}}<br />
<br />
=== Switching between desktop environments/window managers ===<br />
<br />
If you are frequently switching between different desktop environments or window managers, it is convenient to either use a [[display manager]] or expand {{ic|~/.xinitrc}} to make the switching possible.<br />
<br />
The following example shows how to start a particular desktop environment or window manager with an argument:<br />
<br />
{{hc|~/.xinitrc|<nowiki><br />
...<br />
<br />
# Here Xfce is kept as default<br />
session=${1:-xfce}<br />
<br />
case $session in<br />
i3|i3wm ) exec i3;;<br />
kde ) exec startplasma-x11;;<br />
xfce|xfce4 ) exec startxfce4;;<br />
# No known session, try to run it as command<br />
* ) exec $1;;<br />
esac<br />
</nowiki>}}<br />
<br />
To pass the argument ''session'':<br />
<br />
$ xinit ''session''<br />
<br />
or<br />
<br />
$ startx ~/.xinitrc ''session''<br />
<br />
=== Starting applications without a window manager ===<br />
<br />
It is possible to start only specific applications without a window manager, although most likely this is only useful with a single application shown in full-screen mode. For example:<br />
<br />
{{hc|~/.xinitrc|<br />
...<br />
<br />
exec chromium<br />
}}<br />
<br />
Alternatively the binary can be called directly from the command prompt as described in [[#Override xinitrc]].<br />
<br />
With this method you need to set each application's window geometry through its own configuration files (if possible at all).<br />
<br />
{{Tip|This can be useful to launch graphical games, where excluding the overhead of a compositor can help improve the game's performance.}}<br />
<br />
See also [[Display manager#Starting applications without a window manager]].<br />
<br />
=== Output redirection using startx ===<br />
<br />
See [[Xorg#Session log redirection]] for details.</div>Comruminohttps://wiki.archlinux.org/index.php?title=GnuPG&diff=730375GnuPG2022-05-22T03:03:39Z<p>Comrumino: /* IPC connect call failed */ Resolved accuracy template based on GnuPG documentation to improve clarity around default behavior and checking agent-socket path settings</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ko:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/file''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular the newer ECC cipher ([[Wikipedia:Elliptic-curve cryptography]]).<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use_OpenPGP_with_external_GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver hkps://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* {{ic|/usr/bin/pinentry-gtk-2}} and {{ic|/usr/bin/pinentry-gnome3}} support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]] or [[KeePass#Secret_Service|KeePassXC]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Comruminohttps://wiki.archlinux.org/index.php?title=Arch_Linux_AMIs_for_Amazon_Web_Services&diff=713473Arch Linux AMIs for Amazon Web Services2022-01-24T17:44:31Z<p>Comrumino: Added a warning to inform users that Uplink Labs is no longer maintaining their AMIs. Unpatched systems have security implications and various other complications (e.g., updating).</p>
<hr />
<div>[[Category:Installation process]]<br />
[[es:Arch Linux AMIs for Amazon Web Services]]<br />
[[ja:Amazon Web Services の Arch Linux AMI]]<br />
== Public community Arch AMIs ==<br />
<br />
{{Note|Arch Linux currently does not offer official AMIs. The AMIs listed here are created by the community.}}<br />
<br />
=== AMI Images from Uplink Labs ===<br />
{{Warning|The AMIs provided by Uplink Labs are no longer maintained}}<br />
<br />
Uplink Labs creates new images approximately twice a month. Images are being built<br />
for a number of regions, and cover the following configurations:<br />
<br />
* ebs hvm x86_64 lts <br />
* s3 hvm x86_64 lts<br />
* ebs hvm x86_64 stable<br />
* s3 hvm x86_64 stable<br />
<br />
AMI links and more information are available at https://www.uplinklabs.net/projects/arch-linux-on-ec2/ .<br />
<br />
== Building Arch AMIs ==<br />
<br />
You can also build your own Arch Linux AMI. Here are some guides:<br />
<br />
* {{AUR|linux-ec2}} in [[AUR]] compiles the Arch linux kernel for AWS with Xen modules enabled and the XSAVE patch applied. Note that at least some instance types will also work with the stock Arch Linux kernel.<br />
* Aforementioned [https://www.uplinklabs.net/projects/arch-linux-on-ec2/ Uplink Labs webpage] also has a manual on the build process.<br />
* Another tutorial on building your own AMIs can be found at https://gitlab.com/bitfehler/archlinux-ec2<br />
* Mathcom publishes a detailed guide that uses only core Arch tools, at http://mathcom.com/arch.aws.ami.html</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682373Pacman2021-06-20T03:59:20Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Removed accuracy template as the concerns have been fully addressed; accuracy improvements beyond those already made would require rechecking outline of source code flow and comments within blocks.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
When successful, the workflow of a transaction follows five high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# Commit the transaction:<br />
## When applicable, download packages (`_alpm_sync_load`)<br />
## If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
## Packages are removed that are to-be replaced, conflicting, or explicitly targeted to be removed<br />
## If there packages to add, then each package is committed<br />
### If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
### ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
### ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
### If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
## If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
# Release the transaction and transaction resource (i.e. db lock)<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682372Pacman2021-06-20T03:56:20Z<p>Comrumino: Removed understanding section and placed the subsection that explains runtime steps at a high-level under usage---the only documentation on these steps is in the source code and may help uses better understand advance usage w/ hooks</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows five high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# Commit the transaction:<br />
## When applicable, download packages (`_alpm_sync_load`)<br />
## If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
## Packages are removed that are to-be replaced, conflicting, or explicitly targeted to be removed<br />
## If there packages to add, then each package is committed<br />
### If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
### ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
### ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
### If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
## If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
# Release the transaction and transaction resource (i.e. db lock)<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682369Pacman2021-06-20T03:40:56Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Branched package committing another level for accuracy</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows five high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# Commit the transaction:<br />
## When applicable, download packages (`_alpm_sync_load`)<br />
## If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
## Packages are removed that are to-be replaced, conflicting, or explicitly targeted to be removed<br />
## If there packages to add, then each package is committed<br />
### If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
### ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
### ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
### If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
## If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
# Release the transaction and transaction resource (i.e. db lock)<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682368Pacman2021-06-20T03:29:17Z<p>Comrumino: /* What happens during package install/upgrade/removal */ added download step missing prior to pre transaction hook for accuracy</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows five high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# Commit the transaction:<br />
## When applicable, download packages (`_alpm_sync_load`)<br />
## If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
## Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
## If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
# Release the transaction and transaction resource (i.e. db lock)<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682367Pacman2021-06-20T03:27:45Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Corrected summary by changing number of steps from 4 to 5 and added release transaction step</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows five high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# Commit the transaction:<br />
## If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
## Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
## If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
# Release the transaction and transaction resource (i.e. db lock)<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682366Pacman2021-06-20T03:26:32Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Added commit transaction step and moved remaining steps into commit transaction for accuracy</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows four high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# Commit the transaction:<br />
## If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
## Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
## If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682365Pacman2021-06-20T03:22:21Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Improved precision on sanity step checks to address accuracy</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows four high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# Prepare the transaction, based on flags, by performing sanity checks on the sync databases, packages, and their dependencies<br />
# If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
# Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
# If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682362Pacman2021-06-20T03:11:38Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Corrected phrasing about pacman choosing packages for a transaction in step 2 for accuracy</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows four high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# Choose which packages will be added or removed in the transaction<br />
# ''pacman'' performs various checks that the packages can likely be installed.<br />
# If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
# Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
# If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682361Pacman2021-06-20T03:08:38Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Added step prior to package selection based comments in source code to improve accuracy</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows four high-level steps plus pre/post transaction hooks:<br />
<br />
# Initialize the transaction if there is not a db lock<br />
# ''pacman'' obtains the to-be installed package file for all packages queued in a transaction.<br />
# ''pacman'' performs various checks that the packages can likely be installed.<br />
# If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
# Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
# If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pacman&diff=682360Pacman2021-06-20T03:04:25Z<p>Comrumino: /* What happens during package install/upgrade/removal */ Edited summary of steps to reflect edits to come base on source code of pacman to address accurracy template concerns</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package manager]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[ar:Pacman]]<br />
[[cs:Pacman]]<br />
[[de:Pacman]]<br />
[[el:Pacman]]<br />
[[es:Pacman]]<br />
[[fa:Pacman]]<br />
[[fi:Pacman]]<br />
[[fr:Pacman]]<br />
[[id:Pacman]]<br />
[[it:Pacman]]<br />
[[ja:Pacman]]<br />
[[pl:Pacman]]<br />
[[pt:Pacman]]<br />
[[ru:Pacman]]<br />
[[sr:Pacman]]<br />
[[sv:Pacman]]<br />
[[zh-hans:Pacman]]<br />
[[zh-hant:Pacman]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|Downgrading packages}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|pacman/Pacnew and Pacsave}}<br />
{{Related|pacman/Restore local database}}<br />
{{Related|pacman/Rosetta}}<br />
{{Related|pacman/Tips and tricks}}<br />
{{Related|FAQ#Package management}}<br />
{{Related|System maintenance}}<br />
{{Related|Arch Build System}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch User Repository}}<br />
{{Related articles end}}<br />
<br />
The [https://archlinux.org/pacman/ pacman] [[Wikipedia:Package manager|package manager]] is one of the major distinguishing features of Arch Linux. It combines a simple binary package format with an easy-to-use [[Arch Build System|build system]]. The goal of ''pacman'' is to make it possible to easily manage packages, whether they are from the [[official repositories]] or the user's own builds.<br />
<br />
''pacman'' keeps the system up to date by synchronizing package lists with the master server. This server/client model also allows the user to download/install packages with a simple command, complete with all required dependencies.<br />
<br />
''pacman'' is written in the [[C]] programming language and uses the {{man|1|bsdtar}} [[w:tar (computing)|tar]] format for packaging.<br />
<br />
{{Tip|1=The {{Pkg|pacman}} package contains tools such as [[makepkg]] and {{man|8|vercmp}}. Other useful tools such as [[#Pactree|pactree]] and [[checkupdates]] are found in {{Pkg|pacman-contrib}} ([https://git.archlinux.org/pacman.git/commit/?id=0c99eabd50752310f42ec808c8734a338122ec86 formerly] part of pacman). Run {{ic|pacman -Ql pacman pacman-contrib {{!}} grep -E 'bin/.+'}} to see the full list.}}<br />
<br />
== Usage ==<br />
<br />
What follows is just a small sample of the operations that ''pacman'' can perform. To read more examples, refer to {{man|8|pacman}}.<br />
<br />
{{Tip|For those who have used other Linux distributions before, there is a helpful [[Pacman Rosetta]] article.}}<br />
<br />
=== Installing packages ===<br />
<br />
A package is an archive containing:<br />
<br />
* all of the (compiled) files of an application<br />
* metadata about the application, such as application name, version, dependencies, ...<br />
* installation files and directives for pacman<br />
* (optionally) extra files to make your life easier, such as a start/stop script<br />
<br />
Arch's package manager pacman can install, update, and remove those packages. Using packages instead of compiling and installing programs yourself has various benefits:<br />
<br />
* easily updatable: pacman will update existing packages as soon as updates are available<br />
* dependency checks: pacman handles dependencies for you, you only need to specify the program and pacman installs it together with every other program it needs<br />
* clean removal: pacman has a list of every file in a package; this way, no files are unintentionally left behind when you decide to remove a package.<br />
<br />
{{Note|<br />
* Packages often have [[PKGBUILD#optdepends|optional dependencies]] which are packages that provide additional functionality to the application but not strictly required for running it. When installing a package, ''pacman'' will list a package's optional dependencies, but they will not be found in {{ic|pacman.log}}. Use the [[#Querying package databases]] command to view the optional dependencies of a package.<br />
* When installing a package which you require only as (optional) dependency of some other package (i.e. not required by you explicitly otherwise), it is recommended to use {{ic|--asdeps}} option. For details see the [[#Installation reason]] section.}}<br />
<br />
{{Warning|1=When installing packages in Arch, avoid refreshing the package list without [[#Upgrading packages|upgrading the system]] (for example, when a [[#Packages cannot be retrieved on installation|package is no longer found]] in the official repositories). In practice, do '''not''' run {{ic|pacman -Sy ''package_name''}} instead of {{ic|pacman -Sy'''u''' ''package_name''}}, as this could lead to dependency issues. See [[System maintenance#Partial upgrades are unsupported]] and [https://bbs.archlinux.org/viewtopic.php?id=89328 BBS#89328].}}<br />
<br />
==== Installing specific packages ====<br />
<br />
To install a single package or list of packages, including dependencies, issue the following command:<br />
<br />
# pacman -S ''package_name1'' ''package_name2'' ...<br />
<br />
To install a list of packages with regex (see [https://bbs.archlinux.org/viewtopic.php?id=7179 this forum thread]):<br />
<br />
# pacman -S $(pacman -Ssq ''package_regex'')<br />
<br />
Sometimes there are multiple versions of a package in different repositories (e.g. ''extra'' and ''testing''). To install the version from the ''extra'' repository in this example, the repository needs to be defined in front of the package name:<br />
<br />
# pacman -S extra/''package_name''<br />
<br />
To install a number of packages sharing similar patterns in their names one can use curly brace expansion. For example:<br />
<br />
# pacman -S plasma-{desktop,mediacenter,nm}<br />
<br />
This can be expanded to however many levels needed:<br />
<br />
# pacman -S plasma-{workspace{,-wallpapers},pa}<br />
<br />
===== Virtual packages =====<br />
<br />
A virtual package is a special package which does not exist by itself, but is [[PKGBUILD#provides|provided]] by one or more other packages. Virtual packages allow other packages to not name a specific package as a dependency, in case there are several candidates. Virtual packages cannot be installed by their name, instead they become installed in your system when you have install a package ''providing'' the virtual package.<br />
<br />
==== Installing package groups ====<br />
<br />
Some packages belong to a [[Package group|group of packages]] that can all be installed simultaneously. For example, issuing the command:<br />
<br />
# pacman -S gnome<br />
<br />
will prompt you to select the packages from the {{Grp|gnome}} group that you wish to install.<br />
<br />
Sometimes a package group will contain a large amount of packages, and there may be only a few that you do or do not want to install. Instead of having to enter all the numbers except the ones you do not want, it is sometimes more convenient to select or exclude packages or ranges of packages with the following syntax:<br />
<br />
Enter a selection (default=all): 1-10 15<br />
<br />
which will select packages 1 through 10 and 15 for installation, or:<br />
<br />
Enter a selection (default=all): ^5-8 ^2<br />
<br />
which will select all packages except 5 through 8 and 2 for installation.<br />
<br />
To see what packages belong to the gnome group, run:<br />
<br />
# pacman -Sg gnome<br />
<br />
Also visit https://archlinux.org/groups/ to see what package groups are available.<br />
<br />
{{Note|If a package in the list is already installed on the system, it will be reinstalled even if it is already up to date. This behavior can be overridden with the {{ic|--needed}} option.}}<br />
<br />
=== Removing packages ===<br />
<br />
To remove a single package, leaving all of its dependencies installed:<br />
<br />
# pacman -R ''package_name''<br />
<br />
To remove a package and its dependencies which are not required by any other installed package:<br />
<br />
# pacman -Rs ''package_name''<br />
<br />
{{Warning|When removing a group, such as ''gnome'', this ignores the install reason of the packages in the group, because it acts as though each package in the group is listed separately. Install reason of dependencies is still respected.}}<br />
<br />
The above may sometimes refuse to run when removing a group which contains otherwise needed packages. In this case try:<br />
<br />
# pacman -Rsu ''package_name''<br />
<br />
To remove a package, its dependencies and all the packages that depend on the target package:<br />
<br />
{{Warning|This operation is recursive, and must be used with care since it can remove many potentially needed packages.}}<br />
<br />
# pacman -Rsc ''package_name''<br />
<br />
To remove a package, which is required by another package, without removing the dependent package:<br />
<br />
{{Warning|The following operation can break a system and should be avoided. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
# pacman -Rdd ''package_name''<br />
<br />
''pacman'' saves important configuration files when removing certain applications and names them with the extension: ''.pacsave''. To prevent the creation of these backup files use the {{ic|-n}} option:<br />
<br />
# pacman -Rn ''package_name''<br />
<br />
{{Note|''pacman'' will not remove configurations that the application itself creates (for example "dotfiles" in the home folder).}}<br />
<br />
=== Upgrading packages ===<br />
<br />
{{Warning|<br />
*Users are expected to follow the guidance in the [[System maintenance#Upgrading the system]] section to upgrade their systems regularly and not blindly run the following command.<br />
*Arch only supports full system upgrades. See [[System maintenance#Partial upgrades are unsupported]] and [[#Installing packages]] for details.}}<br />
<br />
''pacman'' can update all packages on the system with just one command. This could take quite a while depending on how up-to-date the system is. The following command synchronizes the repository databases ''and'' updates the system's packages, excluding "local" packages that are not in the configured repositories:<br />
<br />
# pacman -Syu<br />
<br />
=== Querying package databases ===<br />
<br />
''pacman'' queries the local package database with the {{ic|-Q}} flag, the sync database with the {{ic|-S}} flag and the files database with the {{ic|-F}} flag. See {{ic|pacman -Q --help}}, {{ic|pacman -S --help}} and {{ic|pacman -F --help}} for the respective suboptions of each flag.<br />
<br />
''pacman'' can search for packages in the database, searching both in packages' names and descriptions:<br />
<br />
$ pacman -Ss ''string1'' ''string2'' ...<br />
<br />
Sometimes, {{Ic|-s}}'s builtin ERE (Extended Regular Expressions) can cause a lot of unwanted results, so it has to be limited to match the package name only; not the description nor any other field:<br />
<br />
$ pacman -Ss '^vim-'<br />
<br />
To search for already installed packages:<br />
<br />
$ pacman -Qs ''string1'' ''string2'' ...<br />
<br />
To search for package file names in remote packages:<br />
<br />
$ pacman -F ''string1'' ''string2'' ...<br />
<br />
To display extensive information about a given package:<br />
<br />
$ pacman -Si ''package_name''<br />
<br />
For locally installed packages:<br />
<br />
$ pacman -Qi ''package_name''<br />
<br />
Passing two {{ic|-i}} flags will also display the list of backup files and their modification states:<br />
<br />
$ pacman -Qii ''package_name''<br />
<br />
To retrieve a list of the files installed by a package:<br />
<br />
$ pacman -Ql ''package_name''<br />
<br />
To retrieve a list of the files installed by a remote package:<br />
<br />
$ pacman -Fl ''package_name''<br />
<br />
To verify the presence of the files installed by a package:<br />
<br />
$ pacman -Qk ''package_name''<br />
<br />
Passing the {{ic|k}} flag twice will perform a more thorough check.<br />
<br />
To query the database to know which package a file in the file system belongs to:<br />
<br />
$ pacman -Qo ''/path/to/file_name''<br />
<br />
To query the database to know which remote package a file belongs to:<br />
<br />
$ pacman -F ''/path/to/file_name''<br />
<br />
To list all packages no longer required as dependencies (orphans):<br />
<br />
$ pacman -Qdt<br />
<br />
{{Tip|Add the above command to a pacman post-transaction [[#Hooks|hook]] to be notified if a transaction orphaned a package. This can be useful for being notified when a package has been dropped from a repository, since any dropped package will also be orphaned on a local installation (unless it was explicitly installed). To avoid any "failed to execute command" errors when no orphans are found, use the following command for {{ic|Exec}} in your hook: {{ic|<nowiki>/usr/bin/bash -c "/usr/bin/pacman -Qtd || /usr/bin/echo '=> None found.'"</nowiki>}}}}<br />
<br />
To list all packages explicitly installed and not required as dependencies:<br />
<br />
$ pacman -Qet<br />
<br />
See [[Pacman/Tips and tricks]] for more examples.<br />
<br />
==== Pactree ====<br />
<br />
{{Note|{{man|8|pactree}} is not part of the {{Pkg|pacman}} package anymore. Instead it can be found in {{Pkg|pacman-contrib}}.}}<br />
<br />
To view the dependency tree of a package:<br />
<br />
$ pactree ''package_name''<br />
<br />
To view the dependant tree of a package, pass the reverse flag {{ic|-r}} to ''pactree'', or use ''whoneeds'' from {{AUR|pkgtools}}.<br />
<br />
==== Database structure ====<br />
<br />
The ''pacman'' databases are normally located at {{ic|/var/lib/pacman/sync}}. For each repository specified in {{ic|/etc/pacman.conf}} there will be a corresponding database file located there. Database files are gzipped tar archives containing one directory for each package, for example for the {{Pkg|which}} package:<br />
<br />
{{hc|$ tree which-2.21-5|<br />
which-2.21-5<br />
{{!}}-- desc<br />
}}<br />
<br />
The {{ic|desc}} file contains meta data such as the package description, dependencies, file size and MD5 hash.<br />
<br />
=== Cleaning the package cache ===<br />
<br />
''pacman'' stores its downloaded packages in {{ic|/var/cache/pacman/pkg/}} and does not remove the old or uninstalled versions automatically. This has some advantages:<br />
# It allows to [[downgrade]] a package without the need to retrieve the previous version through other means, such as the [[Arch Linux Archive]].<br />
# A package that has been uninstalled can easily be reinstalled directly from the cache folder, not requiring a new download from the repository.<br />
<br />
However, it is necessary to deliberately clean up the cache periodically to prevent the folder to grow indefinitely in size.<br />
<br />
The {{man|8|paccache}} script, provided within the {{Pkg|pacman-contrib}} package, deletes all cached versions of installed and uninstalled packages, except for the most recent 3, by default:<br />
<br />
# paccache -r<br />
<br />
[[Enable]] and [[start]] {{ic|paccache.timer}} to discard unused packages weekly.<br />
<br />
{{Tip|1=You can create a [[#Hooks|hook]] to run this automatically after every pacman transaction, see [https://bbs.archlinux.org/viewtopic.php?pid=1694743#p1694743 examples] and {{AUR|pacman-cleanup-hook}}.}}<br />
<br />
You can also define how many recent versions you want to keep. To retain only one past version use:<br />
<br />
# paccache -rk1<br />
<br />
Add the {{ic|-u}}/{{ic|--uninstalled}} switch to limit the action of ''paccache'' to uninstalled packages. For example to remove all cached versions of uninstalled packages, use the following:<br />
<br />
# paccache -ruk0<br />
<br />
See {{ic|paccache -h}} for more options.<br />
<br />
''pacman'' also has some built-in options to clean the cache and the leftover database files from repositories which are no longer listed in the configuration file {{ic|/etc/pacman.conf}}. However ''pacman'' does not offer the possibility to keep a number of past versions and is therefore more aggressive than ''paccache'' default options.<br />
<br />
To remove all the cached packages that are not currently installed, and the unused sync database, execute:<br />
<br />
# pacman -Sc<br />
<br />
To remove all files from the cache, use the clean switch twice, this is the most aggressive approach and will leave nothing in the cache folder:<br />
<br />
# pacman -Scc<br />
<br />
{{Warning|One should avoid deleting from the cache all past versions of installed packages and all uninstalled packages unless one desperately needs to free some disk space. This will prevent downgrading or reinstalling packages without downloading them again.}}<br />
<br />
{{AUR|pkgcacheclean}} and {{AUR|pacleaner}} are two further alternatives to clean the cache.<br />
<br />
=== Additional commands ===<br />
<br />
Download a package without installing it:<br />
<br />
# pacman -Sw ''package_name''<br />
<br />
Install a 'local' package that is not from a remote repository (e.g. the package is from the [[AUR]]):<br />
<br />
# pacman -U ''/path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
To keep a copy of the local package in ''pacman'''s cache, use:<br />
<br />
# pacman -U file:///''path/to/package/package_name-version.pkg.tar.zst''<br />
<br />
Install a 'remote' package (not from a repository stated in ''pacman'''s configuration files):<br />
<br />
# pacman -U ''<nowiki>http://www.example.com/repo/example.pkg.tar.zst</nowiki>''<br />
<br />
To inhibit the {{ic|-S}}, {{ic|-U}} and {{ic|-R}} actions, {{ic|-p}} can be used.<br />
<br />
''pacman'' always lists packages to be installed or removed and asks for permission before it takes action.<br />
<br />
=== Installation reason ===<br />
<br />
The ''pacman'' database distinguishes the installed packages in two groups according to the reason why they were installed:<br />
<br />
* '''explicitly-installed''': the packages that were literally passed to a generic ''pacman'' {{ic|-S}} or {{ic|-U}} command;<br />
* '''dependencies''': the packages that, despite never (in general) having been passed to a ''pacman'' installation command, were implicitly installed because [[dependency|required]] by another package that was explicitly installed.<br />
<br />
When installing a package, it is possible to force its installation reason to ''dependency'' with:<br />
<br />
# pacman -S --asdeps ''package_name''<br />
<br />
{{Tip|Installing optional dependencies with {{ic|--asdeps}} will cause it such that if you [[Pacman/Tips_and_tricks#Removing_unused_packages_.28orphans.29|remove orphans]], ''pacman'' will also remove leftover optional dependencies.}}<br />
<br />
When '''re'''installing a package, though, the current installation reason is preserved by default.<br />
<br />
The list of explicitly-installed packages can be shown with {{ic|pacman -Qe}}, while the complementary list of dependencies can be shown with {{ic|pacman -Qd}}.<br />
<br />
To change the installation reason of an already installed package, execute:<br />
<br />
# pacman -D --asdeps ''package_name''<br />
<br />
Use {{ic|--asexplicit}} to do the opposite operation.<br />
<br />
{{Note|Using {{ic|--asdeps}} and {{ic|--asexplicit}} options when upgrading, such as with {{ic|pacman -Syu ''package_name'' --asdeps}}, is discouraged. This would change the installation reason of not only the package being installed, but also the packages being upgraded.}}<br />
<br />
=== Search for a package that contains a specific file ===<br />
<br />
Sync the files database:<br />
<br />
# pacman -Fy<br />
<br />
Search for a package containing a file, e.g.:<br />
<br />
{{hc|$ pacman -F pacman|<br />
core/pacman 5.2.1-1 (base base-devel) [installed]<br />
usr/bin/pacman<br />
usr/share/bash-completion/completions/pacman<br />
extra/xscreensaver 5.43-1<br />
usr/lib/xscreensaver/pacman<br />
}}<br />
<br />
{{Tip|You can set a cron job or a systemd timer to sync the files database regularly.}}<br />
<br />
For advanced functionality install [[pkgfile]], which uses a separate database with all files and their associated packages.<br />
<br />
== Configuration ==<br />
<br />
''pacman'''s settings are located in {{ic|/etc/pacman.conf}}: this is the place where the user configures the program to work in the desired manner. In-depth information about the configuration file can be found in {{man|5|pacman.conf}}.<br />
<br />
=== General options ===<br />
<br />
General options are in the {{ic|[options]}} section. Read {{man|5|pacman.conf}} or look in the default {{ic|pacman.conf}} for information on what can be done here.<br />
<br />
==== Comparing versions before updating ====<br />
<br />
To see old and new versions of available packages, uncomment the "VerbosePkgLists" line in {{ic|/etc/pacman.conf}}. The output of {{ic|pacman -Syu}} will be like this:<br />
<br />
Package (6) Old Version New Version Net Change Download Size<br />
<br />
extra/libmariadbclient 10.1.9-4 10.1.10-1 0.03 MiB 4.35 MiB<br />
extra/libpng 1.6.19-1 1.6.20-1 0.00 MiB 0.23 MiB<br />
extra/mariadb 10.1.9-4 10.1.10-1 0.26 MiB 13.80 MiB<br />
<br />
==== Enabling parallel downloads ====<br />
<br />
''pacman'' 6.0 introduced the option to download packages in parallel. {{ic|ParallelDownloads}} needs to be set to a positive integer in {{ic|/etc/pacman.conf}} to use this feature (e.g., {{ic|5}}). Packages will otherwise be downloaded sequentially if this option is unset.<br />
<br />
==== Skip package from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping packages, since [[partial upgrades]] are unsupported.}}<br />
<br />
To have a specific package skipped when [[#Upgrading packages|upgrading]] the system, add this line in the {{ic|[options]}} section:<br />
<br />
IgnorePkg=linux<br />
<br />
For multiple packages use a space-separated list, or use additional {{ic|IgnorePkg}} lines. Also, [[Wikipedia:glob (programming)|glob]] patterns can be used. If you want to skip packages just once, you can also use the {{ic|--ignore}} option on the command-line - this time with a comma-separated list.<br />
<br />
It will still be possible to upgrade the ignored packages using {{ic|pacman -S}}: in this case ''pacman'' will remind you that the packages have been included in an {{ic|IgnorePkg}} statement.<br />
<br />
==== Skip package group from being upgraded ====<br />
<br />
{{Warning|Be careful in skipping package groups, since [[partial upgrades]] are unsupported.}}<br />
<br />
As with packages, skipping a whole package group is also possible:<br />
<br />
IgnoreGroup=gnome<br />
<br />
==== Skip file from being upgraded ====<br />
<br />
All files listed with a {{Ic|NoUpgrade}} directive will never be touched during a package install/upgrade, and the new files will be installed with a ''.pacnew'' extension.<br />
<br />
NoUpgrade=''path/to/file''<br />
<br />
{{Note|The path refers to files in the package archive. Therefore, do not include the leading slash.}}<br />
<br />
==== Skip files from being installed to system ====<br />
<br />
To always skip installation of specific directories list them under {{Ic|NoExtract}}. For example, to avoid installation of [[systemd]] units use this:<br />
<br />
NoExtract=usr/lib/systemd/system/*<br />
<br />
Later rules override previous ones, and you can negate a rule by prepending {{ic|!}}.<br />
<br />
{{Tip|''pacman'' issues warning messages about missing locales when updating a package for which locales have been cleared by ''localepurge'' or ''bleachbit''. Commenting the {{ic|CheckSpace}} option in {{ic|pacman.conf}} suppresses such warnings, but consider that the space-checking functionality will be disabled for all packages.}}<br />
<br />
==== Maintain several configuration files ====<br />
<br />
If you have several configuration files (e.g. main configuration and configuration with [[testing]] repository enabled) and would have to share options between configurations you may use {{ic|Include}} option declared in the configuration files, e.g.:<br />
<br />
Include = ''/path/to/common/settings''<br />
<br />
where {{ic|''/path/to/common/settings''}} file contains the same options for both configurations.<br />
<br />
==== Hooks ====<br />
<br />
''pacman'' can run pre- and post-transaction hooks from the {{ic|/usr/share/libalpm/hooks/}} directory; more directories can be specified with the {{ic|HookDir}} option in {{ic|pacman.conf}}, which defaults to {{ic|/etc/pacman.d/hooks}}. Hook file names must be suffixed with ''.hook''. Pacman hooks are not interactive.<br />
<br />
''pacman'' hooks are used, for example, in combination with {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} to automatically create system users and files during the installation of packages. For example, {{Pkg|tomcat8}} specifies that it wants a system user called {{ic|tomcat8}} and certain directories owned by this user. The ''pacman'' hooks {{ic|systemd-sysusers.hook}} and {{ic|systemd-tmpfiles.hook}} invoke {{ic|systemd-sysusers}} and {{ic|systemd-tmpfiles}} when ''pacman'' determines that {{Pkg|tomcat8}} contains files specifying users and tmp files.<br />
<br />
For more information on alpm hooks, see {{man|5|alpm-hooks}}.<br />
<br />
=== Repositories and mirrors ===<br />
<br />
Besides the special [[#General options|[options]]] section, each other {{ic|[section]}} in {{ic|pacman.conf}} defines a package repository to be used. A ''repository'' is a ''logical'' collection of packages, which are ''physically'' stored on one or more servers: for this reason each server is called a ''mirror'' for the repository.<br />
<br />
Repositories are distinguished between [[Official repositories|official]] and [[Unofficial user repositories|unofficial]]. The order of repositories in the configuration file matters; repositories listed first will take precedence over those listed later in the file when packages in two repositories have identical names, regardless of version number. In order to use a repository after adding it, you will need to [[#Upgrading packages|upgrade]] the whole system first.<br />
<br />
Each repository section allows defining the list of its mirrors directly or in a dedicated external file through the {{ic|Include}} directive: for example, the mirrors for the official repositories are included from {{ic|/etc/pacman.d/mirrorlist}}. See the [[Mirrors]] article for mirror configuration.<br />
<br />
==== Package security ====<br />
<br />
''pacman'' supports package signatures, which add an extra layer of security to the packages. The default configuration, {{ic|1=SigLevel = Required DatabaseOptional}}, enables signature verification for all the packages on a global level: this can be overridden by per-repository {{ic|SigLevel}} lines. For more details on package signing and signature verification, take a look at [[pacman-key]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== "Failed to commit transaction (conflicting files)" error ===<br />
<br />
If you see the following error: [https://bbs.archlinux.org/viewtopic.php?id=56373]<br />
<br />
error: could not prepare transaction<br />
error: failed to commit transaction (conflicting files)<br />
''package'': ''/path/to/file'' exists in filesystem<br />
Errors occurred, no packages were upgraded.<br />
<br />
This is happening because ''pacman'' has detected a file conflict, and by design, will not overwrite files for you. This is by design, not a flaw.<br />
<br />
The problem is usually trivial to solve. A safe way is to first check if another package owns the file ({{ic|pacman -Qo ''/path/to/file''}}). If the file is owned by another package, [[Reporting bug guidelines|file a bug report]]. If the file is not owned by another package, rename the file which 'exists in filesystem' and re-issue the update command. If all goes well, the file may then be removed.<br />
<br />
If you had installed a program manually without using ''pacman'', for example through {{ic|make install}}, you have to remove/uninstall this program with all of its files. See also [[Pacman tips#Identify files not owned by any package]].<br />
<br />
Every installed package provides a {{ic|/var/lib/pacman/local/''package-version''/files}} file that contains metadata about this package. If this file gets corrupted, is empty or goes missing, it results in {{ic|file exists in filesystem}} errors when trying to update the package. Such an error usually concerns only one package. Instead of manually renaming and later removing all the files that belong to the package in question, you may explicitly run {{ic|pacman -S --overwrite ''glob'' ''package''}} to force ''pacman'' to overwrite files that match {{ic|''glob''}}.<br />
<br />
{{Warning|Generally avoid using the {{ic|--overwrite}} switch. See [[System maintenance#Avoid certain pacman commands]].}}<br />
<br />
=== "Failed to commit transaction (invalid or corrupted package)" error ===<br />
<br />
Look for ''.part'' files (partially downloaded packages) in {{ic|/var/cache/pacman/pkg/}} and remove them (often caused by usage of a custom {{ic|XferCommand}} in {{ic|pacman.conf}}).<br />
<br />
# find /var/cache/pacman/pkg/ -iname "*.part" -delete<br />
<br />
=== "Failed to init transaction (unable to lock database)" error ===<br />
<br />
When ''pacman'' is about to alter the package database, for example installing a package, it creates a lock file at {{ic|/var/lib/pacman/db.lck}}. This prevents another instance of ''pacman'' from trying to alter the package database at the same time.<br />
<br />
If ''pacman'' is interrupted while changing the database, this stale lock file can remain. If you are certain that no instances of ''pacman'' are running then delete the lock file:<br />
<br />
# rm /var/lib/pacman/db.lck<br />
<br />
=== Packages cannot be retrieved on installation ===<br />
<br />
This error manifests as {{ic|Not found in sync db}}, {{ic|Target not found}} or {{ic|Failed retrieving file}}.<br />
<br />
Firstly, ensure the package actually exists. If certain the package exists, your package list may be out-of-date. Try running {{ic|pacman -Syu}} to force a refresh of all package lists and upgrade. Also make sure the selected [[mirrors]] are up-to-date and [[#Repositories and mirrors|repositories]] are correctly configured.<br />
<br />
It could also be that the repository containing the package is not enabled on your system, e.g. the package could be in the [[multilib]] repository, but ''multilib'' is not enabled in your {{ic|pacman.conf}}.<br />
<br />
See also [[FAQ#Why is there only a single version of each shared library in the official repositories?]].<br />
<br />
=== pacman crashes during an upgrade ===<br />
<br />
In the case that ''pacman'' crashes with a "database write" error while removing packages, and reinstalling or upgrading packages fails thereafter, do the following:<br />
<br />
# Boot using the Arch installation media. Preferably use a recent media so that the ''pacman'' version matches/is newer than the system. <br />
# Mount the system's root filesystem, e.g., {{ic|mount /dev/sdaX /mnt}} as root, and check the mount has sufficient space with {{ic|df -h}}<br />
# Mount the proc, sys and dev filesystems as well: {{ic|mount -t proc proc /mnt/proc; mount --rbind /sys /mnt/sys; mount --rbind /dev /mnt/dev }} <br />
# If the system uses default database and directory locations, you can now update the system's ''pacman'' database and upgrade it via {{ic|1=pacman --sysroot /mnt -Syu}} as root.<br />
#* Alternatively, if you cannot update/upgrade, refer to [[Pacman/Tips and tricks#Reinstalling all packages]].<br />
# After the upgrade, one way to double-check for not upgraded but still broken packages: {{ic|find /mnt/usr/lib -size 0}} <br />
# Followed by a re-install of any still broken package via {{ic|1=pacman --sysroot /mnt -S ''package''}}.<br />
<br />
=== Manually reinstalling pacman ===<br />
<br />
==== Using pacman-static ====<br />
<br />
{{AUR|pacman-static}} is a statically compiled version of pacman, so it will be able to run even when the libraries on the system are not working. This can also come in handy when a [[partial upgrade]] was performed and pacman can not run anymore.<br />
<br />
The pinned comment and the PKGBUILD provides a way to directly download the binary, which can be used to reinstall pacman or to upgrade the entire system in case of partial upgrades.<br />
<br />
==== Using an external pacman ====<br />
<br />
If even {{ic|pacman-static}} does not work, it is possible to recover using an external pacman. One of the easiest methods to do so is by using the [[archiso]] and simply using {{ic|--sysroot}} or {{ic|--root}} to specify the mount point. See [[Chroot#Using chroot]] on how to mount the necessary filesystems required by {{ic|--sysroot}}.<br />
<br />
==== By manually extracting ====<br />
<br />
{{Warning|It is extremely easy to break your system even worse using this approach. Use this only as a last resort if the method from [[#pacman crashes during an upgrade]] is not an option.}}<br />
<br />
Even if ''pacman'' is terribly broken, you can fix it manually by downloading the latest packages and extracting them to the correct locations. The rough steps to perform are:<br />
<br />
# Determine the {{pkg|pacman}} dependencies to install<br />
# Download each package from a [[mirror]] of your choice<br />
# Extract each package to root<br />
# Reinstall these packages with {{ic|pacman -S --overwrite}} to update the package database accordingly<br />
# Do a full system upgrade<br />
<br />
If you have a healthy Arch system on hand, you can see the full list of dependencies with:<br />
<br />
$ pacman -Q $(pactree -u pacman)<br />
<br />
But you may only need to update a few of them depending on your issue. An example of extracting a package is<br />
<br />
# tar -xvpwf ''package.tar.zst'' -C / --exclude .PKGINFO --exclude .INSTALL --exclude .MTREE --exclude .BUILDINFO<br />
<br />
Note the use of the {{ic|w}} flag for interactive mode. Running non-interactively is very risky since you might end up overwriting an important file. Also take care to extract packages in the correct order (i.e. dependencies first). [https://bbs.archlinux.org/viewtopic.php?id=95007 This forum post] contains an example of this process where only a couple ''pacman'' dependencies are broken.<br />
<br />
=== "Unable to find root device" error after rebooting ===<br />
<br />
Most likely the [[initramfs]] became corrupted during a [[kernel]] update (improper use of ''pacman'''s {{ic|--overwrite}} option can be a cause). There are two options; first, try the ''Fallback'' entry.<br />
<br />
{{Tip|In case you removed the ''Fallback'' entry, you can always press the {{ic|Tab}} key when the boot loader menu shows up (for Syslinux) or {{ic|e}} (for GRUB or systemd-boot), rename it {{ic|initramfs-linux-fallback.img}} and press {{ic|Enter}} or {{ic|b}} (depending on your [[boot loader]]) to boot with the new parameters.}}<br />
<br />
Once the system starts, run this command (for the stock {{Pkg|linux}} kernel) either from the console or from a terminal to rebuild the initramfs image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
If that does not work, from a current Arch release (CD/DVD or USB stick), [[mount]] your root and boot partitions. Then [[chroot]] using ''arch-chroot'':<br />
<br />
# arch-chroot /mnt<br />
# pacman -Syu mkinitcpio systemd linux<br />
<br />
{{Note|<br />
* If you do not have a current release or if you only have some other "live" Linux distribution laying around, you can [[chroot]] using the old fashioned way. Obviously, there will be more typing than simply running the {{ic|arch-chroot}} script.<br />
* If ''pacman'' fails with {{ic|Could not resolve host}}, please [[Network configuration#Check the connection|check your internet connection]].<br />
* If you cannot enter the arch-chroot or chroot environment but need to re-install packages you can use the command {{ic|pacman --sysroot /mnt -Syu foo bar}} to use ''pacman'' on your root partition.}}<br />
<br />
Reinstalling the kernel (the {{Pkg|linux}} package) will automatically re-generate the initramfs image with {{ic|mkinitcpio -p linux}}. There is no need to do this separately.<br />
<br />
Afterwards, it is recommended that you run {{ic|exit}}, {{ic|umount /mnt/{boot,} }} and {{ic|reboot}}.<br />
<br />
=== Signature from "User <email@example.org>" is unknown trust, installation failed ===<br />
<br />
Potential solutions:<br />
* Update the known keys, i.e. {{ic|pacman-key --refresh-keys}}<br />
* Manually upgrade {{Pkg|archlinux-keyring}} package first, i.e. {{ic|pacman -Sy archlinux-keyring && pacman -Su}}<br />
* Follow [[pacman-key#Resetting all the keys]]<br />
<br />
=== Request on importing PGP keys ===<br />
<br />
If installing Arch with an outdated ISO, you are likely prompted to import PGP keys. Agree to download the key to proceed. If you are unable to add the PGP key successfully, update the keyring or upgrade {{Pkg|archlinux-keyring}} (see [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]]).<br />
<br />
=== Error: key "0123456789ABCDEF" could not be looked up remotely ===<br />
<br />
If packages are signed with new keys, which were only recently added to {{Pkg|archlinux-keyring}}, these keys are not locally available during update (chicken-egg-problem). The installed {{Pkg|archlinux-keyring}} does not contain the key, until it is updated. Pacman tries to bypass this by a lookup through a key-server, which might not be possible e.g. behind proxys or firewalls and results in the stated error. Upgrade {{Pkg|archlinux-keyring}} first as shown [[#Signature from "User <email@example.org>" is unknown trust, installation failed|above]].<br />
<br />
=== Signature from "User <email@archlinux.org>" is invalid, installation failed ===<br />
<br />
When the system time is faulty, signing keys are considered expired (or invalid) and signature checks on packages will fail with the following error:<br />
<br />
error: ''package'': signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
<br />
Make sure to correct the [[system time]], for example with {{ic|ntpd -qg}} run as root, and run {{ic|hwclock -w}} as root before subsequent installations or upgrades.<br />
<br />
=== "Warning: current locale is invalid; using default "C" locale" error ===<br />
<br />
As the error message says, your locale is not correctly configured. See [[Locale]].<br />
<br />
=== Pacman does not honor proxy settings ===<br />
<br />
Make sure that the relevant environment variables ({{ic|$http_proxy}}, {{ic|$ftp_proxy}} etc.) are set up. If you use ''pacman'' with [[sudo]], you need to configure sudo to [[sudo#Environment variables|pass these environment variables to pacman]]. Also, ensure the configuration of [[GnuPG#Use_a_keyserver|dirmngr]] has {{ic|honor-http-proxy}} in {{ic|/etc/pacman.d/gnupg/dirmngr.conf}} to honor the proxy when refreshing the keys.<br />
<br />
=== How do I reinstall all packages, retaining information on whether something was explicitly installed or as a dependency? ===<br />
<br />
To reinstall all the native packages: {{ic|pacman -Qnq {{!}} pacman -S -}} or {{ic|pacman -S $(pacman -Qnq)}} (the {{ic|-S}} option preserves the installation reason by default).<br />
<br />
You will then need to reinstall all the foreign packages, which can be listed with {{ic|pacman -Qmq}}.<br />
<br />
=== "Cannot open shared object file" error ===<br />
<br />
It looks like previous ''pacman'' transaction removed or corrupted shared libraries needed for ''pacman'' itself.<br />
<br />
To recover from this situation you need to unpack required libraries to your filesystem manually. First find what package contains the missed library and then locate it in the ''pacman'' cache ({{ic|/var/cache/pacman/pkg/}}). Unpack required shared library to the filesystem. This will allow to run ''pacman''.<br />
<br />
Now you need to [[#Installing specific packages|reinstall]] the broken package. Note that you need to use {{ic|--overwrite}} flag as you just unpacked system files and ''pacman'' does not know about it. ''pacman'' will correctly replace our shared library file with one from package.<br />
<br />
That's it. Update the rest of the system.<br />
<br />
=== Freeze of package downloads ===<br />
<br />
Some issues have been reported regarding network problems that prevent ''pacman'' from updating/synchronizing repositories. [https://bbs.archlinux.org/viewtopic.php?id&#61;68944] [https://bbs.archlinux.org/viewtopic.php?id&#61;65728] When installing Arch Linux natively, these issues have been resolved by replacing the default ''pacman'' file downloader with an alternative (see [[Improve pacman performance]] for more details). When installing Arch Linux as a guest OS in [[VirtualBox]], this issue has also been addressed by using ''Host interface'' instead of ''NAT'' in the machine properties.<br />
<br />
=== Failed retrieving file 'core.db' from mirror ===<br />
<br />
If you receive this error message with correct [[mirrors]], try setting a different [[Resolv.conf|name server]].<br />
<br />
=== error: 'local-package.pkg.tar': permission denied ===<br />
<br />
If you want to install a package on an sshfs mount using {{ic|pacman -U}} and receive this error, move the package to a local directory and try to install again.<br />
<br />
=== error: could not determine cachedir mount point /var/cache/pacman/pkg ===<br />
<br />
Upon executing, e.g., {{ic|pacman -Syu}} inside a chroot environment an error is encountered:<br />
<br />
error: could not determine cachedir mount point /var/cache/pacman/pkg<br />
error: failed to commit transaction (not enough free disk space)<br />
<br />
This is frequently caused by the chroot directory not being a mountpoint when the chroot is entered. See the note at [[Install Arch Linux from existing Linux#Downloading basic tools]] for a solution, and {{man|8|arch-chroot}} for an explanation and an example of using bind mounting to make the chroot directory a mountpoint.<br />
<br />
== Understanding ==<br />
<br />
=== What happens during package install/upgrade/removal ===<br />
<br />
{{Accuracy|1=From [https://bbs.archlinux.org/viewtopic.php?pid=1775592 the forum], may be incomplete/incorrect so far. Move above [[#Troubleshooting]] or even inside [[#Installing packages]]?}}<br />
<br />
When successful, the workflow of a transaction follows four high-level steps plus pre/post transaction hooks:<br />
<br />
# ''pacman'' obtains the to-be installed package file for all packages queued in a transaction.<br />
# ''pacman'' performs various checks that the packages can likely be installed.<br />
# If pre-existing ''pacman'' {{ic|PreTransaction}} hooks apply, they are executed.<br />
# Each package is installed/upgraded/removed in turn.<br />
## If the package has an install script, its {{ic|pre_install}} function is executed (or {{ic|pre_upgrade}} or {{ic|pre_remove}} in the case of an upgraded or removed package).<br />
## ''pacman'' deletes all the files from a pre-existing version of the package (in the case of an upgraded or removed package). However, files that were marked as configuration files in the package are kept (see [[Pacman/Pacnew and Pacsave]]).<br />
## ''pacman'' untars the package and dumps its files into the file system (in the case of an installed or upgraded package). Files that would overwrite kept, and manually modified, configuration files (see previous step), are stored with a new name (.pacnew).<br />
## If the package has an install script, its {{ic|post_install}} function is executed (or {{ic|post_upgrade}} or {{ic|post_remove}} in the case of an upgraded or removed package).<br />
# If ''pacman'' {{ic|PostTransaction}} hooks that exist at the end of the transaction apply, they are executed.<br />
<br />
== See also ==<br />
<br />
* [https://archlinux.org/pacman/ Pacman Home Page]<br />
* {{man|3|libalpm}}<br />
* {{man|8|pacman}}<br />
* {{man|5|pacman.conf}}<br />
* {{man|8|repo-add}}</div>Comruminohttps://wiki.archlinux.org/index.php?title=SSH_keys&diff=682353SSH keys2021-06-20T01:49:19Z<p>Comrumino: /* GnuPG Agent */ Minor change to make the appositive compound of emulation consistent with the official documentation on gpg-agent and technically more accurate</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[es:SSH keys]]<br />
[[it: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.[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 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 />
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. Note that not all hardware tokens support this option.<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 />
Keep in mind that many SSH servers may not support these keys.<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}}.<br />
<br />
Finally, [[enable]] or [[start]] the service with the {{ic|--user}} flag.<br />
<br />
{{Note|If you use GNOME, this environment variable is overridden by default. See [[GNOME/Keyring#Disable keyring daemon components]].}}<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 [[GnuPG#gpg-agent|gpg-agent]] has OpenSSH Agent protocol emulation. See [[GnuPG#SSH agent]] for necessary configuration.<br />
<br />
=== Keychain ===<br />
<br />
[https://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 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: [https://www.funtoo.org/OpenSSH_Key_Management,_Part_1 Part 1], [https://www.funtoo.org/OpenSSH_Key_Management,_Part_2 Part 2], [https://www.funtoo.org/OpenSSH_Key_Management,_Part_3 Part 3]<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Comruminohttps://wiki.archlinux.org/index.php?title=GnuPG&diff=682348GnuPG2021-06-20T00:44:39Z<p>Comrumino: /* Set SSH_AUTH_SOCK */ Rewrote to clarify that a user is replacing ssh-agent by setting SSH_AUTH_SOCK since processes other than SSH may be affected</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ko:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set the {{ic|GNUPGHOME}} [[environment variable]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/doc/gnupg/}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular the newer ECC cipher ([[Wikipedia:Elliptic-curve cryptography]]).<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use_OpenPGP_with_external_GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lkml.org/lkml/2016/8/15/445 fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://sks-keyservers.net SKS Keyserver Pool]{{Dead link|2021|05|13|status=SSL error}}: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://pool.sks-keyservers.net<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver hkps://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If your network blocks connection to port 11371 used for hkp, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}. Alternatively, some HKPS servers provide access through port 443, for example, {{ic|hkps://hkps.pool.sks-keyservers.net:443}}.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
You have to set {{ic|SSH_AUTH_SOCK}} to communicate with ''gpg-agent'' and replace the default ''ssh-agent''. User-based configuration of [[Environment_variables#Using_pam_env|pam_env]] allows you to set environment variables by user, instead of shell.<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* Re-login after making changes to {{ic|~/.pam_environment}} to set your environment variables.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually (such as in this pam_env example), keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It's possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
{{Accuracy|The {{ic|gpg-agent*.socket}} systemd sockets provided by the {{Pkg|gnupg}} package create the sockets in {{ic|/run/user/$UID/gnupg/}} which is guaranteed to be an appropriate file system.}}<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
If your keyring is stored on a vFat filesystem (e.g. a USB drive), {{ic|gpg-agent}} will fail to create the required sockets (vFat does not support sockets), you can create redirects to a location that handles sockets, e.g. {{ic|/dev/shm}}:<br />
<br />
# export GNUPGHOME=/custom/gpg/home<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent\n' > $GNUPGHOME/S.gpg-agent<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.browser\n' > $GNUPGHOME/S.gpg-agent.browser<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.extra\n' > $GNUPGHOME/S.gpg-agent.extra<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.ssh\n' > $GNUPGHOME/S.gpg-agent.ssh<br />
<br />
Test that gpg-agent starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Comruminohttps://wiki.archlinux.org/index.php?title=GnuPG&diff=682347GnuPG2021-06-20T00:34:48Z<p>Comrumino: /* Set SSH_AUTH_SOCK */ Changed language to better describe the example that follows the sentence. The previous sentence had grammar errors...</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ko:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set the {{ic|GNUPGHOME}} [[environment variable]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/doc/gnupg/}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular the newer ECC cipher ([[Wikipedia:Elliptic-curve cryptography]]).<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use_OpenPGP_with_external_GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lkml.org/lkml/2016/8/15/445 fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://sks-keyservers.net SKS Keyserver Pool]{{Dead link|2021|05|13|status=SSL error}}: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://pool.sks-keyservers.net<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver hkps://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If your network blocks connection to port 11371 used for hkp, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}. Alternatively, some HKPS servers provide access through port 443, for example, {{ic|hkps://hkps.pool.sks-keyservers.net:443}}.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. User-based configuration of [[Environment_variables#Using_pam_env|pam_env]] allows you to set environment variables by user, instead of shell.<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* Re-login after making changes to {{ic|~/.pam_environment}} to set your environment variables.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually (such as in this pam_env example), keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It's possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
{{Accuracy|The {{ic|gpg-agent*.socket}} systemd sockets provided by the {{Pkg|gnupg}} package create the sockets in {{ic|/run/user/$UID/gnupg/}} which is guaranteed to be an appropriate file system.}}<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
If your keyring is stored on a vFat filesystem (e.g. a USB drive), {{ic|gpg-agent}} will fail to create the required sockets (vFat does not support sockets), you can create redirects to a location that handles sockets, e.g. {{ic|/dev/shm}}:<br />
<br />
# export GNUPGHOME=/custom/gpg/home<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent\n' > $GNUPGHOME/S.gpg-agent<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.browser\n' > $GNUPGHOME/S.gpg-agent.browser<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.extra\n' > $GNUPGHOME/S.gpg-agent.extra<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.ssh\n' > $GNUPGHOME/S.gpg-agent.ssh<br />
<br />
Test that gpg-agent starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Comruminohttps://wiki.archlinux.org/index.php?title=GnuPG&diff=682340GnuPG2021-06-19T23:30:19Z<p>Comrumino: /* Set SSH_AUTH_SOCK */ Added note to tell users to re-login since the subsection on using pam_env linked does not mention it---new users would overlook this</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ko:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set the {{ic|GNUPGHOME}} [[environment variable]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/doc/gnupg/}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular the newer ECC cipher ([[Wikipedia:Elliptic-curve cryptography]]).<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''RSA and RSA'' for sign and encrypt keys.<br />
* A keysize of the default 3072 value. A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot" (see [https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096 why doesn’t GnuPG default to using RSA-4096]).<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public.key''}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public.key'' ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use_OpenPGP_with_external_GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server. The reason is explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''key-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lkml.org/lkml/2016/8/15/445 fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://sks-keyservers.net SKS Keyserver Pool]{{Dead link|2021|05|13|status=SSL error}}: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://pool.sks-keyservers.net<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver hkps://keys.openpgp.org/ --search-keys 931FF8E79F0876134EDDBDCCA87FF9DF48BF1C90<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If your network blocks connection to port 11371 used for hkp, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}. Alternatively, some HKPS servers provide access through port 443, for example, {{ic|hkps://hkps.pool.sks-keyservers.net:443}}.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.}}<br />
<br />
=== Web Key Directory ===<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''privkey.asc'' ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''privkey.asc''<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert.asc'' ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''user-id''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys ''[subkey id]''! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver pgp.mit.edu --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert.asc''<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* Re-login after making changes to {{ic|~/.pam_environment}} to set your environment variables.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually (such as in this pam_env example), keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disable keyring daemon components|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It's possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
And select an option that allows you to set your own capabilities.<br />
<br />
Comparably, to specify custom capabilities for subkeys, add the {{ic|--expert}} flag to {{ic|gpg --edit-key}}, see [[#Edit your key]] for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
<br />
When generating a key, gpg can run into this error:<br />
<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
<br />
To check the available entropy, check the kernel parameters:<br />
<br />
$ cat /proc/sys/kernel/random/entropy_avail<br />
<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
See [[GNOME/Keyring#Disable keyring daemon components]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
{{Accuracy|The {{ic|gpg-agent*.socket}} systemd sockets provided by the {{Pkg|gnupg}} package create the sockets in {{ic|/run/user/$UID/gnupg/}} which is guaranteed to be an appropriate file system.}}<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
If your keyring is stored on a vFat filesystem (e.g. a USB drive), {{ic|gpg-agent}} will fail to create the required sockets (vFat does not support sockets), you can create redirects to a location that handles sockets, e.g. {{ic|/dev/shm}}:<br />
<br />
# export GNUPGHOME=/custom/gpg/home<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent\n' > $GNUPGHOME/S.gpg-agent<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.browser\n' > $GNUPGHOME/S.gpg-agent.browser<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.extra\n' > $GNUPGHOME/S.gpg-agent.extra<br />
# printf '%%Assuan%%\nsocket=/dev/shm/S.gpg-agent.ssh\n' > $GNUPGHOME/S.gpg-agent.ssh<br />
<br />
Test that gpg-agent starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Comruminohttps://wiki.archlinux.org/index.php?title=Help:Template&diff=647635Help:Template2020-12-30T05:55:12Z<p>Comrumino: /* Named and numbered parameters */ Explained how white space characters are handled for named parameter values because the recommended solution is not accurate when using a bulleted list</p>
<hr />
<div>[[Category:Help]]<br />
[[el:Help:Template]]<br />
[[es:Help:Template]]<br />
[[fa:راهنما:الگو]]<br />
[[fi:Help:Template]]<br />
[[ja:ヘルプ:テンプレート]]<br />
[[pt:Help:Template]]<br />
[[ru:Help:Template]]<br />
[[zh-hans:Help:Template]]<br />
[[zh-hant:Help:Template]]<br />
{{Related articles start}}<br />
{{Related|Help:Editing}}<br />
{{Related|Help:Reading}}<br />
{{Related|Help:Style}}<br />
{{Related articles end}}<br />
<br />
A template is a piece of predefined [[Wikipedia:Wikitext|wikitext]] that can be inserted into an article. Templates are primarily used to aid in formatting content.<br />
<br />
== Usage ==<br />
<br />
Templates are used by adding the following markup to an article:<br />
<br />
<nowiki>{{Template name}}</nowiki><br />
<br />
Most templates take additional arguments, such as [[Template:Note]]:<br />
<br />
<nowiki>{{Note|This text should be noted.}}</nowiki><br />
<br />
which produces:<br />
<br />
{{Note|This text should be noted.}}<br />
<br />
Some templates use named parameters, such as [[Template:hc]]:<br />
<br />
<nowiki>{{hc|head=/etc/rc.local|output=exit 0}}</nowiki><br />
<br />
which produces:<br />
<br />
{{hc|head=/etc/rc.local|output=exit 0}}<br />
<br />
The general format is:<br />
<br />
<nowiki>{{Template name|param1|param2|...|paramN}}</nowiki><br />
<br />
See each template's page for specific usage instructions.<br />
<br />
=== Style ===<br />
<br />
* Templates should be used with the capitalization shown in the examples in their pages, for example {{ic|&#123;{Pkg&#124;...}} and {{ic|&#123;{ic&#124;...}} are correct, while {{ic|&#123;{pkg&#124;...}} and {{ic|&#123;{Ic&#124;...}} are not.<br />
* There should be no spaces around the template name: {{ic|&#123;{Template name&#124;...}} is correct, while for example {{ic|&#123;{ Template name &#124;...}} is not.<br />
* Templates should not be categorized.<br />
<br />
=== Escape template-breaking characters ===<br />
<br />
There are some characters that, if used inside a template, will break its output: most frequently this happens with "=" (the equal sign) and "|" (the pipe sign). Solutions to this problem are described below.<br />
<br />
{{Tip|The pipe symbol "{{!}}" can be escaped using the {{ic|<nowiki>{{!}}</nowiki>}} [[MW:Help:Magic_words#Other|magic word]].}}<br />
<br />
==== Named and numbered parameters ====<br />
<br />
If the problem is only with "=" signs, the recommended solution is to explicitly introduce template parameters with their positional numbers or names.<br />
<br />
Example: {{ic|<nowiki>{{Tip|1=https://www.archlinux.org/?foo=bar}}</nowiki>}}<br />
<br />
Result: {{Tip|1=https://archlinux.org/?foo=bar}}<br />
<br />
This is very useful for:<br />
<br />
* Variable definitions.<br />
<br />
* [[Help:Editing#External_links|External links]] with query strings in URLs.<br />
<br />
* Shell strings and commands.<br />
<br />
* Lines of code.<br />
<br />
White space characters (i.e. newlines) are automatically stripped from the beginnings and ends of named parameter values. To preserve white space characters, start the parameter value with a {{ic|<nowiki><nowiki/></nowiki>}} tag.<br />
<br />
Example: {{ic|<nowiki>{{Tip|1=<nowiki/><br />
* https://www.archlinux.org/?foo=bar}}</nowiki>}}<br />
<br />
Result: {{Tip|1=<nowiki/><br />
* https://www.archlinux.org/?foo=bar}}<br />
<br />
===== Multiple parameters =====<br />
<br />
* Using positional parameters {{ic|1}} and {{ic|2}}<br />
<br />
<nowiki>{{hc|1=$ echo "="|2==}}</nowiki><br />
<br />
Result: {{hc|1=$ echo "="|2==}}<br />
<br />
* Using named parameters {{ic|head}} and {{ic|output}}<br />
<br />
<nowiki>{{hc|head=$ echo "="|output==}}</nowiki><br />
<br />
Result: {{hc|head=$ echo "="|output==}}<br />
<br />
==== nowiki tags ====<br />
<br />
If you are having problems with characters other than "=", e.g. "}", the recommended solution is to enclose the whole parameter in {{ic|<nowiki><nowiki></nowiki>}} tags. This method displays all kinds of characters, but completely prevents the wiki engine from processing text markup, such as links and other templates. For example:<br />
<br />
<nowiki>{{Tip|&lt;nowiki>= | }} https://www.archlinux.org/ {{ic|foo}}&lt;/nowiki>}}</nowiki><br />
<br />
{{Tip|<nowiki>= | }} https://www.archlinux.org/ {{ic|foo}}</nowiki>}}<br />
<br />
Enclosing only specific parts (or even single characters) in {{ic|<nowiki><nowiki></nowiki>}} tags still works of course, but for readability it is recommended to use such method only if links or other templates have to be normally displayed. For example:<br />
<br />
<nowiki>{{Tip|&lt;nowiki>= | }}&lt;/nowiki> https://www.archlinux.org/ {{ic|foo}}}}</nowiki><br />
<br />
{{Tip|<nowiki>= | }}</nowiki> https://archlinux.org/ {{ic|foo}}}}<br />
<br />
==== HTML entities ====<br />
<br />
Replacing the offending characters with their respective HTML entities always works, but since it reduces the readability of the source text, it is recommended only when the solutions above are not practicable. For example:<br />
<br />
<nowiki>{{Tip|&amp;#61; &amp;#124; &amp;#123;&amp;#123; &amp;#125;&amp;#125;}}</nowiki><br />
<br />
{{Tip|&#61; &#124; &#123;&#123; &#125;&#125;}}<br />
<br />
== Creation ==<br />
<br />
{{Note|<br />
* Before creating a template, discuss the idea in [[Help talk:Template]].<br />
* Only create relevant templates. If you are attempting to create a very specialized template that will likely only ever be used on a few articles, please do not bother, avoid cluttering up the templates namespace.<br />
* Only create concise templates. Remember [[The Arch Way]]: Keep It Simple, Stupid!<br />
}}<br />
<br />
The following template should be used when creating new templates to facilitate usage and editing:<br />
<br />
<nowiki><noinclude><br />
{{Template}}<br />
<br />
A brief description of the template<br />
<br />
== Usage ==<br />
<br />
&lt;nowiki&gt;{{Template name|param1|param2|...|paramN}}&lt;/nowiki&gt;<br />
<br />
== Example ==<br />
<br />
{{Template name|param1|param2|...|paramN}}</noinclude><includeonly>Template code goes here...</includeonly></nowiki><br />
<br />
To begin the creation process, simply visit [[:Template:Template name]] (substituting {{ic|Template name}} with the desired name of the template), [[Help:Editing|edit, and add the relevant wikitext]].<br />
<br />
== List of templates ==<br />
<br />
The templates that users can use directly in articles on the ArchWiki are listed below. Click on the links to see their detailed usage. For a list that also includes localizations and meta templates see [[Special:AllPages/Template:]], [[Special:PrefixIndex/Template:]] or [[Special:MostLinkedTemplates]].<br />
<br />
{{Warning|Please do not experiment with existing templates. If you want to edit a non-protected template, copy the text to [[Template:Sandbox]], edit and test it there, and copy it back when it works. It is strongly recommended (and necessary for protected templates) to suggest any modifications on discussion pages first.}}<br />
<br />
=== Testing ===<br />
<br />
* [[Template:Sandbox]]<br />
* [[Template:Lorem Ipsum]]<br />
<br />
=== Article status templates ===<br />
<br />
These templates should be added at the beginning of concerning articles or sections. See also [[Help:Style#Article status templates]].<br />
<br />
Translators should also check template guidelines in [[ArchWiki:Translation Team]].<br />
<br />
The pages flagged with the article status templates are tracked in the corresponding [[:Category:Maintenance|maintenance category]] and in [[ArchWiki:Statistics#Maintenance statistics]].<br />
<br />
{| class="wikitable"<br />
! Name !! Recommended use !! Parameters<br />
|-<br />
| [[Template:Style]] || Content with language, wiki syntax or style issues.<br />
| rowspan=9 | {{ic|1}} — reason, {{ic|2}} — optional talk page, {{ic|section}} — optional section in the default talk page<br />
|-<br />
| [[Template:Accuracy]] || Incorrect, misleading or confusing content.<br />
|-<br />
| [[Template:Expansion]] || Incomplete content.<br />
|-<br />
| [[Template:Out of date]] || Outdated content.<br />
|-<br />
| [[Template:Remove]] || Irrelevant or unhelpful content.<br />
|-<br />
| [[Template:Archive]] || Obsolete pages.<br />
|-<br />
| [[Template:Laptop style]] || [[Laptop]] articles duplicating other articles.<br />
|-<br />
| [[Template:Translateme]] || Incomplete translations.<br />
|-<br />
| [[Template:Bad translation]] || Problematic translations.<br />
|-<br />
| [[Template:TranslationStatus]] || Status of translations.<br />
| {{ic|1}} — original title, {{ic|2}} — translation date, {{ic|3}} — revision number<br />
|-<br />
| [[Template:Merge]] || Content overlaps with another article.<br />
| rowspan=3 | {{ic|1}} — target page, {{ic|2}} — reason, {{ic|3}} — optional talk page, {{ic|section}} — optional section in the default talk page<br />
|-<br />
| [[Template:Move]] || Rename page, move section to another article.<br />
|-<br />
| [[Template:Redirect]] || Redirect page to another article.<br />
|-<br />
| [[Template:Unsupported]] || User pages unsupported by Arch Linux. || {{ic|1}} — date of last review by page author<br />
|}<br />
<br />
=== Related articles templates ===<br />
<br />
* [[Template:Related articles start]]<br />
* [[Template:Related]]<br />
* [[Template:Related articles end]]<br />
<br />
=== Code formatting templates ===<br />
<br />
* [[Template:ic]]<br />
* [[Template:bc]]<br />
* [[Template:hc]]<br />
* [[Template:Text art]]<br />
<br />
=== Note templates ===<br />
<br />
* [[Template:Note]]<br />
* [[Template:Tip]]<br />
* [[Template:Warning]]<br />
<br />
For use in drafts on discussion pages only:<br />
* [[Template:Comment]]<br />
<br />
=== Miscellaneous templates ===<br />
<br />
* [[Template:App]]<br />
* [[Template:Broken package link]]<br />
* [[Template:Broken section link]]<br />
* [[Template:Bug]]<br />
* [[Template:Committed identity]]<br />
* [[Template:Dead link]]<br />
* [[Template:Lowercase title]]<br />
* [[Template:man]]<br />
* [[Template:Unsigned]]<br />
<br />
=== Package templates ===<br />
<br />
* [[Template:Pkg]]<br />
* [[Template:Grp]]<br />
* [[Template:AUR]]<br />
<br />
=== Table cell templates ===<br />
<br />
Text align:<br />
<br />
{| class="wikitable"<br />
|-<br />
! width=100px | Name !! width=100px | Align !! width=100px | Wiki markup !! width=100px | Result<br />
|-<br />
| [[Template:C]] || center || {{ic|<nowiki>{{C|text}}</nowiki>}} || {{C|text}}<br />
|-<br />
| [[Template:L]] || left || {{ic|<nowiki>{{L|text}}</nowiki>}} || {{L|text}}<br />
|}<br />
<br />
Cell background:<br />
<br />
{| class="wikitable"<br />
! width=100px | Name !! width=100px | Color !! width=100px | Wiki markup !! width=100px | Result<br />
|-<br />
| [[Template:R]] || red || {{ic|<nowiki>{{R|text}}</nowiki>}} || {{R|text}}<br />
|-<br />
| [[Template:O]] || orange || {{ic|<nowiki>{{O|text}}</nowiki>}} || {{O|text}}<br />
|-<br />
| [[Template:Y]] || yellow || {{ic|<nowiki>{{Y|text}}</nowiki>}} || {{Y|text}}<br />
|-<br />
| [[Template:G]] || green || {{ic|<nowiki>{{G|text}}</nowiki>}} || {{G|text}}<br />
|-<br />
| [[Template:B]] || blue || {{ic|<nowiki>{{B|text}}</nowiki>}} || {{B|text}}<br />
|-<br />
| [[Template:V]] || violet || {{ic|<nowiki>{{V|text}}</nowiki>}} || {{V|text}}<br />
|-<br />
| [[Template:Grey]] || grey || {{ic|<nowiki>{{Grey|text}}</nowiki>}} || {{Grey|text}}<br />
|}<br />
<br />
Common text:<br />
<br />
{| class="wikitable"<br />
! width=100px | Name !! Wiki markup !! width=100px | Result<br />
|-<br />
| rowspan=2 | [[Template:Yes]] || {{ic|<nowiki>{{Yes}}</nowiki>}} || {{Yes}}<br />
|-<br />
| {{ic|<nowiki>{{Yes|https://wiki.archlinux.org/}}</nowiki>}} || {{Yes|https://wiki.archlinux.org/}}<br />
|-<br />
| rowspan=2 | [[Template:No]] || {{ic|<nowiki>{{No}}</nowiki>}} || {{No}}<br />
|-<br />
| {{ic|<nowiki>{{No|https://wiki.archlinux.org/}}</nowiki>}} || {{No|https://wiki.archlinux.org/}}<br />
|-<br />
| [[Template:-]] || {{ic|<nowiki>{{-}}</nowiki>}} || {{-}}<br />
|}<br />
<br />
{{Tip|You can use attributes with table cell templates by prefixing them, e.g: {{ic|<nowiki>| colspan=2 {{Yes}}</nowiki>}}.}}<br />
<br />
=== Category templates ===<br />
<br />
* [[Template:Cat main]]<br />
<br />
== See also ==<br />
<br />
* [[Template:Template]]<br />
* [[MetaWikimedia: Help:Template]]</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pam_oath&diff=597251Pam oath2020-02-11T19:02:04Z<p>Comrumino: Rewrote first two sentences of the preface to: removed some bias (i.e. mfa >= 2fa), favored upstream author's description, not all RFCs are "standards track", and adjusted vague "it" reference</p>
<hr />
<div>{{DISPLAYTITLE:pam_oath}}<br />
[[Category:Secure Shell]]<br />
[[Category:Authentication]]<br />
[[ja:Pam oath]]<br />
The [http://www.nongnu.org/oath-toolkit/index.html OATH Toolkit] provides one-time password (OTP) components for authentication systems. It contains a PAM authentication module that supports [[w:HMAC-based_One-time_Password_Algorithm|HOTP]] and [[w:Time-based_One-time_Password_Algorithm|TOTP]] as described by their ''informational'' RFC, RFC [https://tools.ietf.org/html/rfc4226 4226] and [https://tools.ietf.org/html/rfc6238 6328] respectively. The OTP generator applications are available for iOS, Android, Blackberry and other devices. Similar to [[Google Authenticator]] the authentication mechanism integrates into the Linux [[PAM]] system. This guide shows the installation and configuration of this mechanism.<br />
<br />
== Installation ==<br />
<br />
Install the {{Pkg|oath-toolkit}} package.<br />
<br />
== Setting up the oath ==<br />
<br />
The oath seed is an hexadecimal number that should be unique per user. To generate a new seed for a user, you could use the following command line:<br />
<br />
$ head -10 /dev/urandom | sha512sum | cut -b 1-30<br />
1ab4321412aebcw<br />
<br />
Note the above output seed is used as example seed in this article and '''must not''' be used. There needs to be one oath per user and link to it in a configuration file {{ic|/etc/users.oath}}. While being root create the file and insert the user seed:<br />
<br />
{{hc|/etc/users.oath|# Option User Prefix Seed<br />
HOTP/T30/6 ''user'' - ''1ab4321412aebcw''}}<br />
<br />
Make sure that the file can only be accessed by root:<br />
<br />
# chmod 600 /etc/users.oath<br />
# chown root /etc/users.oath<br />
<br />
== Setting up the PAM ==<br />
<br />
To enable oath for a specific service only, like ssh, you can edit the file {{ic|/etc/pam.d/sshd}} and add at the beginning of the file the following line:<br />
<br />
auth sufficient pam_oath.so usersfile=/etc/users.oath window=30 digits=6<br />
<br />
This will allow authentication if you just enter the right oath code. You can make it a requirement and let the rest of the pam stack be processed if you use the following line instead:<br />
<br />
auth required pam_oath.so usersfile=/etc/users.oath window=30 digits=6<br />
<br />
For ssh login to work make sure that both {{ic|ChallengeResponseAuthentication}} and {{ic|UsePAM}} options are enabled:<br />
<br />
ChallengeResponseAuthentication yes<br />
UsePAM yes<br />
<br />
If you want to force OATH request-response even if there is a working public/private key authentication also add the following:<br />
<br />
AuthenticationMethods publickey,keyboard-interactive<br />
PasswordAuthentication yes<br />
<br />
== Logging with an oath pass ==<br />
<br />
Run the following command if you are logging in and need the current oath pass:<br />
<br />
oathtool -v -d6 ''1ab4321412aebcw''<br />
<br />
Of course replace {{ic|''1ab4321412aebcw''}} by the seed corresponding to your user. It will display something like that:<br />
<br />
Hex secret: 1ab4321412aebc<br />
Base32 secret: DK2DEFASV26A====<br />
Digits: 6<br />
Window size: 0<br />
Start counter: 0x0 (0)<br />
<br />
820170<br />
<br />
The last number is actually the code you can use to log in right now, but more interestingly the Base32 secret, is actually what we need to generate a qr code for this user. To do so install the package {{Pkg|qrencode}} to run the following command:<br />
<br />
qrencode -o ''user''.png 'otpauth://totp/''user''@''machine''?secret=''DK2DEFASV26A===='''<br />
<br />
Of course change ''user'', ''machine'' and {{ic|''DK2DEFASV26A<nowiki>====</nowiki>''}} accordingly. Once done, you can visualize your qrcode with your preferred image visualizer application and use that to configure your phone. Alternatively you may generate the QR code directly onto terminal with:<br />
<br />
qrencode -t UTF8 'otpauth://totp/''user''@''machine''?secret=''DK2DEFASV26A===='''<br />
<br />
It is pretty straight forward to use FreeOTP to then take a screenshot of that ''.png'' (or ASCII-art like image) and get it to display OTP pass when needed.<br />
<br />
{{Note|The secret key of your users is the most important information in this system. Once you setup a phone to provide OTP, it does have that key. The qr code in that ''.png'' file does have that key. You need to take extra care of this file. They should only be stored on encrypted medium (Your phone need to be using encryption for any sane level of security). If not even confined in a sandbox like Samsung Knox to prevent third party application to potentially access them.}}<br />
<br />
== See also ==<br />
<br />
* [http://spod.cx/blog/two-factor-ssh-auth-with-pam_oath-google-authenticator.shtml Two-factor time based (TOTP) SSH authentication with pam_oath and Google Authenticator]<br />
* [http://www.nongnu.org/oath-toolkit/pam_oath.html pam_oath man page]</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pam_oath&diff=597250Pam oath2020-02-11T18:14:32Z<p>Comrumino: /* Logging with an oath pass */ Removed extra whitespace character for consistency with the rest of article</p>
<hr />
<div>{{DISPLAYTITLE:pam_oath}}<br />
[[Category:Secure Shell]]<br />
[[Category:Authentication]]<br />
[[ja:Pam oath]]<br />
The [http://www.nongnu.org/oath-toolkit/index.html OATH Toolkit] provides a two-step authentication procedure using one-time passcodes (OTP). It complies to two OTP method RFC standards ([[w:HMAC-based_One-time_Password_Algorithm|HOTP]], [[w:Time-based_One-time_Password_Algorithm|TOTP]]). The OTP generator applications are available for iOS, Android, Blackberry and other devices. Similar to [[Google Authenticator]] the authentication mechanism integrates into the Linux [[PAM]] system. This guide shows the installation and configuration of this mechanism.<br />
<br />
== Installation ==<br />
<br />
Install the {{Pkg|oath-toolkit}} package.<br />
<br />
== Setting up the oath ==<br />
<br />
The oath seed is an hexadecimal number that should be unique per user. To generate a new seed for a user, you could use the following command line:<br />
<br />
$ head -10 /dev/urandom | sha512sum | cut -b 1-30<br />
1ab4321412aebcw<br />
<br />
Note the above output seed is used as example seed in this article and '''must not''' be used. There needs to be one oath per user and link to it in a configuration file {{ic|/etc/users.oath}}. While being root create the file and insert the user seed:<br />
<br />
{{hc|/etc/users.oath|# Option User Prefix Seed<br />
HOTP/T30/6 ''user'' - ''1ab4321412aebcw''}}<br />
<br />
Make sure that the file can only be accessed by root:<br />
<br />
# chmod 600 /etc/users.oath<br />
# chown root /etc/users.oath<br />
<br />
== Setting up the PAM ==<br />
<br />
To enable oath for a specific service only, like ssh, you can edit the file {{ic|/etc/pam.d/sshd}} and add at the beginning of the file the following line:<br />
<br />
auth sufficient pam_oath.so usersfile=/etc/users.oath window=30 digits=6<br />
<br />
This will allow authentication if you just enter the right oath code. You can make it a requirement and let the rest of the pam stack be processed if you use the following line instead:<br />
<br />
auth required pam_oath.so usersfile=/etc/users.oath window=30 digits=6<br />
<br />
For ssh login to work make sure that both {{ic|ChallengeResponseAuthentication}} and {{ic|UsePAM}} options are enabled:<br />
<br />
ChallengeResponseAuthentication yes<br />
UsePAM yes<br />
<br />
If you want to force OATH request-response even if there is a working public/private key authentication also add the following:<br />
<br />
AuthenticationMethods publickey,keyboard-interactive<br />
PasswordAuthentication yes<br />
<br />
== Logging with an oath pass ==<br />
<br />
Run the following command if you are logging in and need the current oath pass:<br />
<br />
oathtool -v -d6 ''1ab4321412aebcw''<br />
<br />
Of course replace {{ic|''1ab4321412aebcw''}} by the seed corresponding to your user. It will display something like that:<br />
<br />
Hex secret: 1ab4321412aebc<br />
Base32 secret: DK2DEFASV26A====<br />
Digits: 6<br />
Window size: 0<br />
Start counter: 0x0 (0)<br />
<br />
820170<br />
<br />
The last number is actually the code you can use to log in right now, but more interestingly the Base32 secret, is actually what we need to generate a qr code for this user. To do so install the package {{Pkg|qrencode}} to run the following command:<br />
<br />
qrencode -o ''user''.png 'otpauth://totp/''user''@''machine''?secret=''DK2DEFASV26A===='''<br />
<br />
Of course change ''user'', ''machine'' and {{ic|''DK2DEFASV26A<nowiki>====</nowiki>''}} accordingly. Once done, you can visualize your qrcode with your preferred image visualizer application and use that to configure your phone. Alternatively you may generate the QR code directly onto terminal with:<br />
<br />
qrencode -t UTF8 'otpauth://totp/''user''@''machine''?secret=''DK2DEFASV26A===='''<br />
<br />
It is pretty straight forward to use FreeOTP to then take a screenshot of that ''.png'' (or ASCII-art like image) and get it to display OTP pass when needed.<br />
<br />
{{Note|The secret key of your users is the most important information in this system. Once you setup a phone to provide OTP, it does have that key. The qr code in that ''.png'' file does have that key. You need to take extra care of this file. They should only be stored on encrypted medium (Your phone need to be using encryption for any sane level of security). If not even confined in a sandbox like Samsung Knox to prevent third party application to potentially access them.}}<br />
<br />
== See also ==<br />
<br />
* [http://spod.cx/blog/two-factor-ssh-auth-with-pam_oath-google-authenticator.shtml Two-factor time based (TOTP) SSH authentication with pam_oath and Google Authenticator]<br />
* [http://www.nongnu.org/oath-toolkit/pam_oath.html pam_oath man page]</div>Comruminohttps://wiki.archlinux.org/index.php?title=Pam_oath&diff=597249Pam oath2020-02-11T18:10:12Z<p>Comrumino: /* Logging with an oath pass */ Used Template:ic for secret pseudo-variables to preserve monospace as described by the Help:Style example</p>
<hr />
<div>{{DISPLAYTITLE:pam_oath}}<br />
[[Category:Secure Shell]]<br />
[[Category:Authentication]]<br />
[[ja:Pam oath]]<br />
The [http://www.nongnu.org/oath-toolkit/index.html OATH Toolkit] provides a two-step authentication procedure using one-time passcodes (OTP). It complies to two OTP method RFC standards ([[w:HMAC-based_One-time_Password_Algorithm|HOTP]], [[w:Time-based_One-time_Password_Algorithm|TOTP]]). The OTP generator applications are available for iOS, Android, Blackberry and other devices. Similar to [[Google Authenticator]] the authentication mechanism integrates into the Linux [[PAM]] system. This guide shows the installation and configuration of this mechanism.<br />
<br />
== Installation ==<br />
<br />
Install the {{Pkg|oath-toolkit}} package.<br />
<br />
== Setting up the oath ==<br />
<br />
The oath seed is an hexadecimal number that should be unique per user. To generate a new seed for a user, you could use the following command line:<br />
<br />
$ head -10 /dev/urandom | sha512sum | cut -b 1-30<br />
1ab4321412aebcw<br />
<br />
Note the above output seed is used as example seed in this article and '''must not''' be used. There needs to be one oath per user and link to it in a configuration file {{ic|/etc/users.oath}}. While being root create the file and insert the user seed:<br />
<br />
{{hc|/etc/users.oath|# Option User Prefix Seed<br />
HOTP/T30/6 ''user'' - ''1ab4321412aebcw''}}<br />
<br />
Make sure that the file can only be accessed by root:<br />
<br />
# chmod 600 /etc/users.oath<br />
# chown root /etc/users.oath<br />
<br />
== Setting up the PAM ==<br />
<br />
To enable oath for a specific service only, like ssh, you can edit the file {{ic|/etc/pam.d/sshd}} and add at the beginning of the file the following line:<br />
<br />
auth sufficient pam_oath.so usersfile=/etc/users.oath window=30 digits=6<br />
<br />
This will allow authentication if you just enter the right oath code. You can make it a requirement and let the rest of the pam stack be processed if you use the following line instead:<br />
<br />
auth required pam_oath.so usersfile=/etc/users.oath window=30 digits=6<br />
<br />
For ssh login to work make sure that both {{ic|ChallengeResponseAuthentication}} and {{ic|UsePAM}} options are enabled:<br />
<br />
ChallengeResponseAuthentication yes<br />
UsePAM yes<br />
<br />
If you want to force OATH request-response even if there is a working public/private key authentication also add the following:<br />
<br />
AuthenticationMethods publickey,keyboard-interactive<br />
PasswordAuthentication yes<br />
<br />
== Logging with an oath pass ==<br />
<br />
Run the following command if you are logging in and need the current oath pass :<br />
<br />
oathtool -v -d6 ''1ab4321412aebcw''<br />
<br />
Of course replace {{ic|''1ab4321412aebcw''}} by the seed corresponding to your user. It will display something like that :<br />
<br />
Hex secret: 1ab4321412aebc<br />
Base32 secret: DK2DEFASV26A====<br />
Digits: 6<br />
Window size: 0<br />
Start counter: 0x0 (0)<br />
<br />
820170<br />
<br />
The last number is actually the code you can use to log in right now, but more interestingly the Base32 secret, is actually what we need to generate a qr code for this user. To do so install the package {{Pkg|qrencode}} to run the following command :<br />
<br />
qrencode -o ''user''.png 'otpauth://totp/''user''@''machine''?secret=''DK2DEFASV26A===='''<br />
<br />
Of course change ''user'', ''machine'' and {{ic|''DK2DEFASV26A<nowiki>====</nowiki>''}} accordingly. Once done, you can visualize your qrcode with your preferred image visualizer application and use that to configure your phone. Alternatively you may generate the QR code directly onto terminal with:<br />
<br />
qrencode -t UTF8 'otpauth://totp/''user''@''machine''?secret=''DK2DEFASV26A===='''<br />
<br />
It is pretty straight forward to use FreeOTP to then take a screenshot of that ''.png'' (or ASCII-art like image) and get it to display OTP pass when needed.<br />
<br />
{{Note|The secret key of your users is the most important information in this system. Once you setup a phone to provide OTP, it does have that key. The qr code in that ''.png'' file does have that key. You need to take extra care of this file. They should only be stored on encrypted medium (Your phone need to be using encryption for any sane level of security). If not even confined in a sandbox like Samsung Knox to prevent third party application to potentially access them.}}<br />
<br />
== See also ==<br />
<br />
* [http://spod.cx/blog/two-factor-ssh-auth-with-pam_oath-google-authenticator.shtml Two-factor time based (TOTP) SSH authentication with pam_oath and Google Authenticator]<br />
* [http://www.nongnu.org/oath-toolkit/pam_oath.html pam_oath man page]</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590240YubiKey2019-11-26T08:32:49Z<p>Comrumino: /* Troubleshooting */ Yubikey -> YubiKey, the proper spelling should be add to the dictionary</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
YubiKey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a YubiKey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH {{ic|authorized_keys}} file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the YubiKey's button.<br />
The YubiKey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a YubiKey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590239YubiKey2019-11-26T08:30:59Z<p>Comrumino: /* That is it! */ Another Yubikey -> YubiKey</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
YubiKey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a YubiKey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH {{ic|authorized_keys}} file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the YubiKey's button.<br />
The YubiKey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a YubiKey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590238YubiKey2019-11-26T08:29:54Z<p>Comrumino: /* That is it! */ Yubikey -> YubiKey, when in Rome... you CaMeL CaSe</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
YubiKey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a YubiKey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH {{ic|authorized_keys}} file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The YubiKey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a YubiKey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590237YubiKey2019-11-26T08:28:44Z<p>Comrumino: /* The default way */ Removed extra curly brace</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
YubiKey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a YubiKey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH {{ic|authorized_keys}} file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590236YubiKey2019-11-26T08:27:48Z<p>Comrumino: /* Per-user authorization mapping */ Added ic template, file names should use a template</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
YubiKey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a YubiKey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH {{ic|authorized_keys}} file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590235YubiKey2019-11-26T08:27:05Z<p>Comrumino: /* Central authorization mapping */ Yubikey -> YubiKey ... systematic lack of CaMeL CaSe</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
YubiKey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a YubiKey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590234YubiKey2019-11-26T08:24:57Z<p>Comrumino: /* Two-factor authentication with SSH */ Fixed use of Yubikey to YubiKey and used a language convention closer to the manufacturer's</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a YubiKey OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590233YubiKey2019-11-26T08:22:46Z<p>Comrumino: /* Further reading */ added ic template, command options should us the template</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the {{ic|-m}} option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590232YubiKey2019-11-26T08:21:01Z<p>Comrumino: /* Public key conversion */ Replaced italics with ic template on ssh-keygen again, ic implies that the command is being referred to</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the {{ic|ssh-keygen}}, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590231YubiKey2019-11-26T08:19:30Z<p>Comrumino: /* Public key conversion */ Changed italics of ssh-keygen to ic template since it was not referring to the software in general, it was referring to the command</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using {{ic|ssh-keygen}}:<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590230YubiKey2019-11-26T08:17:41Z<p>Comrumino: /* Setup the slot */ Addressed manual duplication template by referring the reader to the manual and only mentioning the most relevant option to give the reader somewhere to start as the manual lacks examples</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
One way to setup slot {{ic|2}} in challenge-response mode ({{ic|-ochal-resp}}) is with {{ic|ykpersonalize}}:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Check with {{man|1|ykpersonalize}} to make sure that the options used above are right for you. You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590228YubiKey2019-11-26T08:01:24Z<p>Comrumino: /* Executing actions on insertion/removal of Yubikey device */ Second pass on getting the capitalization of YubiKey right...</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
{{Style|Duplicates {{man|1|ykpersonalize}}.}}<br />
<br />
In order to setup slot {{ic|2}} in challenge-response mode you may run:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Above arguments mean:<br />
* Verbose output ({{ic|-v}})<br />
* Use slot 2 ({{ic|-2}})<br />
* Set challenge-response mode ({{ic|-ochal-resp}})<br />
* Generate HMAC-SHA1 challenge responses ({{ic|-ochal-hmac}})<br />
* Calculate HMAC on less than 64 bytes input ({{ic|-ohmac-lt64}})<br />
* Allow Yubikey serial number to be read using an API call ({{ic|-oserial-api-visible}})<br />
* Require touching Yubikey before issue response ({{ic|-ochal-btn-trig}})<br />
<br />
You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the YubiKey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590227YubiKey2019-11-26T07:59:55Z<p>Comrumino: /* Executing actions on insertion/removal of yubikey device */ capitalized yubikey to Yubikey for consistency with the artical and added ic template around lsusb</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
{{Style|Duplicates {{man|1|ykpersonalize}}.}}<br />
<br />
In order to setup slot {{ic|2}} in challenge-response mode you may run:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Above arguments mean:<br />
* Verbose output ({{ic|-v}})<br />
* Use slot 2 ({{ic|-2}})<br />
* Set challenge-response mode ({{ic|-ochal-resp}})<br />
* Generate HMAC-SHA1 challenge responses ({{ic|-ochal-hmac}})<br />
* Calculate HMAC on less than 64 bytes input ({{ic|-ohmac-lt64}})<br />
* Allow Yubikey serial number to be read using an API call ({{ic|-oserial-api-visible}})<br />
* Require touching Yubikey before issue response ({{ic|-ochal-btn-trig}})<br />
<br />
You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the Yubikey 4, and you will have to look at the output of {{ic|lsusb}} to get the vendor and model ID's, along with the description of the device. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590226YubiKey2019-11-26T07:55:05Z<p>Comrumino: /* Installation */ Change "Note:" usage to use the note template... that is what they're there for</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
{{Note|After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running}}<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
{{Style|Duplicates {{man|1|ykpersonalize}}.}}<br />
<br />
In order to setup slot {{ic|2}} in challenge-response mode you may run:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Above arguments mean:<br />
* Verbose output ({{ic|-v}})<br />
* Use slot 2 ({{ic|-2}})<br />
* Set challenge-response mode ({{ic|-ochal-resp}})<br />
* Generate HMAC-SHA1 challenge responses ({{ic|-ochal-hmac}})<br />
* Calculate HMAC on less than 64 bytes input ({{ic|-ohmac-lt64}})<br />
* Allow Yubikey serial number to be read using an API call ({{ic|-oserial-api-visible}})<br />
* Require touching Yubikey before issue response ({{ic|-ochal-btn-trig}})<br />
<br />
You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the yubikey 4, and 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. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590225YubiKey2019-11-26T07:51:46Z<p>Comrumino: /* Understanding the YubiKey */ Added etc. to enumeration of computers as a slight correction of style</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
Note: After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet, etc.).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
{{Style|Duplicates {{man|1|ykpersonalize}}.}}<br />
<br />
In order to setup slot {{ic|2}} in challenge-response mode you may run:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Above arguments mean:<br />
* Verbose output ({{ic|-v}})<br />
* Use slot 2 ({{ic|-2}})<br />
* Set challenge-response mode ({{ic|-ochal-resp}})<br />
* Generate HMAC-SHA1 challenge responses ({{ic|-ochal-hmac}})<br />
* Calculate HMAC on less than 64 bytes input ({{ic|-ohmac-lt64}})<br />
* Allow Yubikey serial number to be read using an API call ({{ic|-oserial-api-visible}})<br />
* Require touching Yubikey before issue response ({{ic|-ochal-btn-trig}})<br />
<br />
You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the yubikey 4, and 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. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590224YubiKey2019-11-26T07:50:14Z<p>Comrumino: /* Installation */ Made CLI capitalized as it should be and removed some extra white spaces</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
Note: After you install the yubikey-manager (which can be called by ykman in CLI), you need to enable {{ic|pcscd.service}} to get it running<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
{{Style|Duplicates {{man|1|ykpersonalize}}.}}<br />
<br />
In order to setup slot {{ic|2}} in challenge-response mode you may run:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Above arguments mean:<br />
* Verbose output ({{ic|-v}})<br />
* Use slot 2 ({{ic|-2}})<br />
* Set challenge-response mode ({{ic|-ochal-resp}})<br />
* Generate HMAC-SHA1 challenge responses ({{ic|-ochal-hmac}})<br />
* Calculate HMAC on less than 64 bytes input ({{ic|-ohmac-lt64}})<br />
* Allow Yubikey serial number to be read using an API call ({{ic|-oserial-api-visible}})<br />
* Require touching Yubikey before issue response ({{ic|-ochal-btn-trig}})<br />
<br />
You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the yubikey 4, and 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. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=YubiKey&diff=590223YubiKey2019-11-26T07:47:06Z<p>Comrumino: /* Installation */ added ic template around pcscd.service since style does matter</p>
<hr />
<div>[[Category:Authentication]]<br />
[[ja:Yubikey]]<br />
{{Accuracy|The article lacks sources, is interspersed with TODOs and probably out of date.}}<br />
{{Style|ykman-specifics should be grouped together.}}<br />
This article describes how [https://yubico.com Yubico]'s [[Wikipedia:YubiKey|YubiKey]] works and how you can use it.<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the warning under [[#Initial configuration]].}}<br />
<br />
== Introduction ==<br />
<br />
The YubiKey is a small [[Wikipedia:Security token|USB Security token]] that supports:<br />
<br />
* generating [[Wikipedia:One-time password|one-time passwords]] (OTP) - using either AES based Yubico OTP algorithm or OATH-HOTP following RFC 4226<br />
* outputting a up to 63 char long static password<br />
* handling [[Wikipedia:Challenge–response authentication|challenge-response requests]], using either Yubico OTP mode or HMAC-SHA1 mode<br />
* handling [[Wikipedia:Universal_2nd_Factor|Universal 2nd Factor]] (U2F) requests (YubiKey 4 and YubiKey NEO)<br />
* acting as smartcard (using the [[Wikipedia:CCID (protocol)|CCID protocol]]) (YubiKey 4 and YubiKey NEO) - allowing storage of signing, encrypting, authenticating (RSA) keys to be used for instance for SSH login (authentication), Email signature/encryption, git commit signature, etc.<br />
<br />
It is manufactured by [http://www.yubico.com/ Yubico].<br />
<br />
One of its strengths is that it emulates a USB keyboard to send the OTP as text, and thus requires only USB HID drivers found on practically all desktop computers.<br />
<br />
=== Installation ===<br />
<br />
There are several packages available:<br />
<br />
* {{App|Yubico PAM|Module to integrate the YubiKey into [[PAM]].|https://developers.yubico.com/yubico-pam/|{{Pkg|yubico-pam}}}}<br />
* {{App|YubiKey Manager|Python library and command-line tool ({{ic|ykman}}) for configuring a YubiKey over all USB connections. Has optional GUI.|https://developers.yubico.com/yubikey-manager/|{{Pkg|yubikey-manager}}, {{Pkg|yubikey-manager-qt}}}}<br />
Note: After you install the yubikey-manager ( which can be called by ykman in cli ), you need to enable {{ic|pcscd.service}} to get it running<br />
* {{App|Yubikey Personalization|Library and tool to configure slot features over the OTP USB connection. Has optional GUI.|https://developers.yubico.com/yubikey-personalization/|{{Pkg|yubikey-personalization}}, {{Pkg|yubikey-personalization-gui}}}}<br />
<br />
=== Understanding the YubiKey ===<br />
<br />
The YubiKey is a small USB dongle with one button and an LED to communicate with you.<br />
<br />
One of its strengths is that it can emulate a USB keyboard to send a password (OTP or static password) as text, and thus requires only USB HID drivers found on practically all computers (desktop, mobile, tablet).<br />
<br />
This also makes it vulnerable to keyloggers if the {{ic|static password}} functionality is used, which is why if possible one should avoid it and try to only use the one-time password (OTP), Challenge-Response and CCID Smartcard functionality.<br />
<br />
==== Inputs ====<br />
<br />
The YubiKey takes inputs in the form of:<br />
<br />
* API calls sent to it via the USB interface.<br />
* short button press<br />
* long button press<br />
<br />
==== Outputs ====<br />
<br />
The YubiKey transforms these inputs into outputs in the form of:<br />
<br />
* Sending keystroke keycodes (emulating a USB keyboard and typing for you) <br> This is used to:<br />
** type the static password<br />
** type the OTP<br />
<br />
* Sending back a Response via the API (over the USB interface). <br> This is used to send back:<br />
** the response of a Challenge-Response request (calculated using either Yubico OTP mode or HMAC-SHA1 mode)<br />
** the response of a U2F Challenge-Response request<br />
** the response of a CCID Smartcard related request<br />
<br />
=== The button ===<br />
<br />
The button activates by slightly touching it. Sometimes it even reacts when you are very close but are not touching it yet.<br />
<br />
Depending on the context, touching the button does one of these things:<br />
<br />
* triggering a function (like triggering the output of a static password or of a one-time password (OTP))<br />
* confirming / allowing a function or access<br />
* inserting / ejecting the smartcard<br />
<br />
In the OTP mode a short press yields slot 1 and a long press yields slot 2.<br />
<br />
=== USB connection modes ===<br />
<br />
Depending on the YubiKey model, the device provides up to three<br />
different USB interfaces with their associated protocols. Two of the<br />
interfaces implement the USB HID (Human Interface Device) device<br />
class; the third is a smart card interface (CCID). The YubiKey is a<br />
multi-function USB device, just like a USB printer that can also<br />
function as a scanner.<br />
<br />
The following table shows which interfaces the different applications<br />
use:<br />
<br />
{| class="wikitable"<br />
! Application !! USB 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 />
All three interfaces can be independently enabled or disabled.<br />
The ykman program uses the term "manage connection modes" and uses<br />
OTP, FIDO, and CCID as selectors for which modes should be enabled.<br />
<br />
{{Note|The old U2F mode has been renamed and is now called FIDO in ykman 0.6.1 and later (released<br />
2018-04-16) https://developers.yubico.com/yubikey-manager/Release_Notes.html}}<br />
<br />
The set of enabled USB interfaces affects which applications on the<br />
key can be accessed. As an example, if only the HID interfaces are<br />
enabled, the applications dependent on the CCID interface are<br />
unavailable.<br />
<br />
Which application on the key is chosen is determined by the host<br />
application and is a combination of USB interface and an application<br />
selection mechanism. For example, if the host application wants to<br />
communicate with the PIV application on the key, it accesses the key<br />
using the CCID interface and using the protocols defined by CCID sends<br />
a 'select application' command to the key selecting the PIV application.<br />
<br />
==== Get enabled modes ====<br />
<br />
{{ic|ykman mode}} will tell you what modes are currently activated/enabled/available.<br />
This could output something like<br />
{{bc|Current connection mode is: OTP+U2F+CCID}}<br />
Meaning that currently the OTP, U2F and CCID subsystem of the key are enabled.<br />
<br />
==== Set the enabled modes ====<br />
<br />
{{ic|ykman mode <MODE>}} will allow you to define which modes should be activated/enabled/available. <br />
* {{ic|<MODE>}} can be a string, such as {{ic|OTP+U2F+CCID}}, or a shortened form {{ic|o+u+c}}.<br>With "+" you can combine multiple modes that you wish to be enabled.<br />
* {{ic|<MODE>}} can be a mode-number, which is one number that encodes several enabled modes (like flags) into one value.<br>The only valid modes when using numbers is 0 - 6 ([https://github.com/Yubico/yubikey-manager/blob/master/ykman/util.py#L94 see here]). The extra flags are not part of the mode in that sense, they just need to be set at the same time as the mode is set.<br />
<br />
Usually what you want is to make all functionality available (you will still need to potentially configure stuff, see functionality sections below for more details).<br />
In order to do so you can use:<br />
<br />
{{ic|ykman mode c+u+o}} or {{ic|ykman mode 6}}<br />
<br />
{{Note|Using the "80" mode-number or the corresponding {{ic|--touch-eject}} parameter of {{ic|ykman mode}} can only be used when the device is ''only'' in CCID mode (by running {{ic|ykman mode ccid --touch-eject}} for instance).<br />
<br />
Once the {{ic|--touch-eject}} flag is set, you should be able to eject/insert the smartcard by pressing the button. The LED should indicate if the card is inserted or not as well.<br />
}}<br />
<br />
{{Warning|But using the 80 mode-number or the corresponding {{ic|--touch-eject}} is not recommend as it would prevent you from using the U2F and OTP features of the YubiKey.}}<br />
<br />
{{Note|The often seen:<br />
<br />
{{ic|ykman mode c+u+o --touch-eject}} or {{ic|ykman mode 86}}<br />
<br />
will ignore the {{ic|--touch-eject}} and be identical to the above recommended {{ic|ykman mode 6}}.<br />
<br />
86 is not a valid mode. It might be a bug that the tool accepts higher values ([https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 see here]).}}<br />
<br />
=== Two Slots ===<br />
<br />
Only if the OTP mode is activated (see Modes of the YubiKey below), the Yubikey provides 2 slots.<br />
<br />
If the transport mode OTP is enabled, the two YubiKey Slots, long press and short press, can be configured and used.<br />
<br />
==== Configuration of the slots ====<br />
<br />
These slots can have one of the following credentials configured: a [https://developers.yubico.com/OTP/ Yubico OTP] (which is what comes preconfigured in the short press slot on a new key), a static password, a challenge-response credential, an OATH-HOTP credential. All this functionality is found in the {{ic|ykman otp}} commands.<br />
<br />
{{Note|A slot has either a Yubico OTP or a challenge-response credential configured. More general: One, and only one, type of the above listed possible credential per slot.}}<br />
<br />
There are several flags that can be set during the configuration of the slots.<br />
These flags /cannot/ be read from the device once written. However, the behaviour of the device should change when the flags are set ;)<br />
<br />
{{Note|Actually most of (all of??) the parameters and details you use during configuration of the slots, cannot be read back, once written to the YubiKey.}}<br />
<br />
=== The LED ===<br />
<br />
The YubiKey has a small green LED able to communicate with you.<br />
Its message to you actually depends on the currently used [[#USB connection modes]] of your YubiKey.<br />
<br />
The possible messages are:<br />
* *steady on*: Press now, to allow access. (typically (TODO exclusively?) U2F mode)<br />
* *slow blinking*: Power/setting up/ready for use (TODO explain)<br />
* *rapid blinking*: Error, configuring driver (TODO explain)<br />
<br />
{{Note|If the CCID mode is turned on, then the LED of the key is always shortly flashing every two-three seconds once inserted.<br>You can turn the blinking off by disabling the CCID mode. This slow blinking just shows that the device has power, alternatively it shows a need for a button press. On Windows this behavior will typically stop once drivers are installed and it is ready for use. Mac and Linux systems will keep blinking; here [https://github.com/Yubico/yubikey-manager/issues/20#issuecomment-326496204 the best current workaround] to get the LED to blink less is to disable CCID.}}<br />
<br />
=== Initial configuration ===<br />
<br />
On a new YubiKey the Yubico OTP is preconfigured on slot 1. <br />
<br />
{{Warning|Before you overwrite your slot 1, please be aware that one is not able to reconfigure the same trust level [https://forum.yubico.com/viewtopic12ca.html?f%3D16&t%3D1960 see here]. Meaning:<br />
<br />
One could think that it is a good idea to reset configuration slot 1 to a new OTP. But then a "VV" prefix in your credentials must be used. Whereas the factory credentials on your Yubikey use a "CC" prefix. You can upload a "VV" credential using the Yubico personalization tool GUI or manually upload the new AES key to the [https://upload.yubico.com/ yubico.com website] in order to regain the same functionality than with the original factory configuration. VV credentials are not less secure than CC. However some services may only trust CC credentials as they believe that the user process is more prone to security vulnerabilities. This is because you could have malware on your machine or someone intercepting your key when sending it to the YubiCloud.<br />
}}<br />
<br />
=== Limitations of the passwords typed by YubiKey via USB-keyboard -- or "Why do my password look so weak ?" ===<br />
<br />
The YubiKey can type passwords (OTP or Static Password) for you by acting as USB keyboard and sending scan-codes like if you would type.<br />
<br />
A limitation of the YubiKey, however, prevents you from choosing characters that require a modifier key other than Shift.<br />
And in order for the YubiKey to work with all possible keyboard layouts (e.g. the {{ic|Z}} on a German keyboard has a different scan-code than the {{ic|Z}} on a US keyboard) it is necessary to limit the characters used by YubiKey passwords to the ModHex alphabet + Digits (0-9) (+ optionally "!" as the only available Symbol in static passwords).<br />
<br />
The 16 characters used in the ModHex alphabet are: {{ic|c,b,d,e,f,g,h,i,j,k,l,n,r,t,u,v}}. These characters share a property that makes them very valuable to a YubiKey: They use the same scan codes across a very large number of keyboard layouts. In other words, the scan code 0x06 maps to the character c for English, Swedish, German, French, and many others.<br />
<br />
[https://www.yubico.com/wp-content/uploads/2015/11/Yubico_WhitePaper_Static_Password_Function.pdf See here for full info]<br />
<br />
== One-time password ==<br />
<br />
=== Yubico OTP mode ===<br />
<br />
The Yubico OTP mode is AES symmetric key based. On a new YubiKey the Yubico OTP is preconfigured on slot 1. This initial AES symmetric key is stored in the YubiKey and the same AES key is already stored on the Yubico Authentication server. This allows validating against YubiCloud, meaning the use of Yubico OTP in combination with the Yubico Forum website for instance or on https://demo.yubico.com).<br />
<br />
The initial configuration and AES key stored in slot 1 can of course be overwritten.<br />
<br />
{{Warning|Please read [[#Initial configuration]] before you overwrite the intial configuration of slot 1 that your YubiKey comes shipped with.}}<br />
<br />
==== How does it work ====<br />
<br />
Yubikey's authentication protocol is based on [[Wikipedia:Symmetric_cryptography|symmetric cryptography]].<br />
More specifically, each YubiKey contains a 128-bit [[Wikipedia:Advanced_Encryption_Standard|AES]] key unique to that device.<br />
It is used to encrypt a token made of different fields such as the ID of the key, a counter, a random number, etc.<br />
The OTP is made from concatenating the ID of the key with this encrypted token.<br />
<br />
This OTP is sent to the target system to which we want to authenticate.<br />
This target system asks a validation server if the OTP is good.<br />
The validation server has a mapping of YubiKey IDs -> AES key.<br />
Using the key ID in the OTP, it can thus retrieve the AES key and decrypt the other part of the OTP.<br />
If it looks OK (plain-text ID and encrypted ID are the same, the counter is bigger than the last seen one to prevent [[wikipedia:Replay_attack|replay attacks]], then authentication is successful.<br />
<br />
The validation server sends that authentication status back to the target system, which grants access or not based on that response.<br />
<br />
==== Security risks ====<br />
<br />
===== AES key compromise =====<br />
<br />
As you can imagine, the AES key should be kept secret.<br />
It cannot be retrieved from the YubiKey itself (or it should not, at least not with software).<br />
It is present in the validation server though, so the security of this server is very important.<br />
<br />
===== Validation requests/responses tampering =====<br />
<br />
Since the target system relies on the ruling of the validation server, a trivial attack would be to impersonate the validation server.<br />
The target system thus needs to authenticate the validation server.<br />
2 methods are available :<br />
* '''HMAC''': This is also symmetric cryptography, the target server and validation server share a key that is used to sign requests and responses.<br />
* '''TLS''': Requests and responses travel via HTTP, so TLS (HTTPS) can be used to authenticate and encrypt the connection.<br />
<br />
==== YubiCloud and validation servers ====<br />
<br />
When you buy a YubiKey, it is preloaded with an AES key that is known only to Yubico.<br />
They will not even communicate it to you.<br />
Yubico provides a validation server with free unlimited access (YubiCloud).<br />
It also offers open-source implementations of the server.<br />
<br />
So you can either:<br />
* choose to use your YubiKey with its preloaded AES key and validate against Yubico's validation server ;<br />
* or load a new AES key in your YubiKey and run your own validation server.<br />
<br />
{{Note|To authenticate the Yubico validation server, you can:<br />
* '''with HMAC''': use https://upgrade.yubico.com/getapikey/ to get an HMAC key and ID<br />
* '''with HTTPS''': the validation server's certificate is signed by GoDaddy, and is thus trusted by default in Arch installs (at least if you have package ca-certificates)}}<br />
<br />
=== OATH-HOTP mode (RFC 4226) ===<br />
<br />
{{Expansion|Empty section.}}<br />
<br />
== Challenge-Response ==<br />
<br />
=== Function and Application of Challenge-Response ===<br />
This technique can be used to authenticate.<br />
<br />
A challenge is sent to the YubiKey and a response is (auto-magically) calculated and send back.<br />
This calculation needs a secret (e.g. an AES key in case of the Yubico OTP mode)<br />
The same challenge always results in the same response.<br />
Without the secret this calculation is not meant to be feasable. Even if in the possession of many challenge-response pairs.<br />
<br />
This can be used for:<br />
* true 2-factor (possession and knowledge) authentication:<br>If you combine the response (possession factor) with a password (knowledge factor) and to authenticate you need to present the triple (challenge,response, password) to 3rd party. In which case the challenge and the corresponding response can be (publicly) send to a 3rd party to authenticate the possession factor, by redoing basically the same (auto-magical) calculation. The needed secret needs to be shared with 3rd party to allow an authentication.<br />
<br />
* semi 2-factor (possession and knowledge) authentication:<br>The challenge can be public. Only with the possession of the YubiKey hardware the response can be generated. This can be used to create a "sort-of" 2-factor authentication (possession and knowledge): If you combine the response (possession factor) with a password (knowledge factor) and use the result for instance as passphrase for cryptsetup.<br />
<br />
This functionality will consume one slot. And it is used via API calls to the YubiKey. So you usually use some tool to communicate the challenge to your YubiKey and get back the response.<br />
<br />
There are two Challenge-Response modes:<br />
* Yubico OTP mode <br />
* HMAC-SHA1 mode<br />
<br />
=== Setup the slot ===<br />
<br />
{{Style|Duplicates {{man|1|ykpersonalize}}.}}<br />
<br />
In order to setup slot {{ic|2}} in challenge-response mode you may run:<br />
<br />
{{bc|ykpersonalize -v -2 -ochal-resp -ochal-hmac -ohmac-lt64 -oserial-api-visible -ochal-btn-trig}}<br />
<br />
Above arguments mean:<br />
* Verbose output ({{ic|-v}})<br />
* Use slot 2 ({{ic|-2}})<br />
* Set challenge-response mode ({{ic|-ochal-resp}})<br />
* Generate HMAC-SHA1 challenge responses ({{ic|-ochal-hmac}})<br />
* Calculate HMAC on less than 64 bytes input ({{ic|-ohmac-lt64}})<br />
* Allow Yubikey serial number to be read using an API call ({{ic|-oserial-api-visible}})<br />
* Require touching Yubikey before issue response ({{ic|-ochal-btn-trig}})<br />
<br />
You may also enable challenge-response mode using graphical interface through {{pkg|yubikey-personalization-gui}}<br />
<br />
{{Note|Before you overwrite the initial configuration of slot 1, please be aware of the '''Warning''' under [[#Initial configuration]].}}<br />
<br />
=== Use the slot - get a response for a challenge ===<br />
<br />
To use a Challenge-Response slot (no matter which mode):<br />
<br />
{{bc|ykchalresp -2 <CHALLENGE>}}<br />
<br />
== U2F ==<br />
<br />
{{Expansion}}<br />
<br />
=== Enabling U2F in the browser ===<br />
<br />
==== Chromium/Chrome ====<br />
<br />
[[Chromium/Tips and tricks#U2F authentication]]<br />
<br />
==== Firefox ====<br />
<br />
[[Firefox/Tweaks#Fido U2F authentication]]<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 U2F 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 [[#Set the enabled modes]].<br />
<br />
=== PIV ===<br />
<br />
Starting from the fourth generation devices, 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 distinguishing characteristic of a PIV token is that it is built to protect private keys and operate on them 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 />
=== Use OpenPGP smartcard mode ===<br />
<br />
See [[GnuPG#Smartcards]]<br />
<br />
=== Using a YubiKey with SSH ===<br />
<br />
The following example describes how to use a YubiKey for [[SSH keys]]. A YubiKey with the PIV (Personal Identification Verification) application is required; this means you need a YubiKey NEO or YubiKey 4 or later.<br />
<br />
==== Generating a key pair on the YubiKey ====<br />
<br />
A private key and associated certificate need to be either generated on the YubiKey or imported to it. Install the {{Pkg|yubikey-manager}}<br />
package. Insert the YubiKey in a USB port and check that it is recognized:<br />
<br />
$ ykman list<br />
YubiKey 4 [OTP+FIDO+CCID] Serial: 1234567<br />
<br />
The following two commands ({{ic|generate-key}} and {{ic|generate-certificate}}) require providing the PIV application's 24-byte management key, if it has been changed from its default value (recommended). The examples below assume the shell variable {{ic|MK}} has been set in advance to the 48 character hex string representation of the management key. For example:<br />
<br />
$ MK=AB019982CA48BDC6776B1F9A0A3E129FDE0705D219AF0037<br />
<br />
Generate a 2048-bit RSA key pair on the YubiKey. The private key will be stored in key slot 9a on the YubiKey, and the public key will be<br />
written to the file {{ic|pubkey.pem}}.<br />
<br />
$ ykman piv generate-key -m $MK -a RSA2048 9a pubkey.pem<br />
<br />
Next, use the YubiKey to generate a self-signed certificate for the public key:<br />
<br />
$ ykman piv generate-certificate -m $MK -d 1826 -s "SSH Key" 9a pubkey.pem<br />
<br />
The Subject field in the certificate will be set to "SSH Key" with the {{ic|-s}} option. This field will be included in the prompt for PIN to help identify which key is used for authentication. The example command also specifies the {{ic|-d}} option to set the number of days until the certificate expires. If the {{ic|-d}} option is omitted, a default value of 365 days is used.<br />
<br />
Note that the last parameter in the {{ic|generate-key}} command is the file name where the public key is written to, whereas the last parameter in the {{ic|generate-certificate}} command specifies where the public key is read from. The certificate is constructed and signed on the YubiKey and stored alongside the private key; the command does not output the certificate.<br />
<br />
At this point the YubiKey is ready for authenticating to a SSH server. For this to happen, some additional configuration on both the client and the server is required.<br />
<br />
==== Client configuration ====<br />
<br />
The standard API used to communicate with cryptographic tokens is defined by [[wikipedia:PKCS_11|PKCS#11]].<br />
Install the {{Pkg|opensc}} package which provides this API in the form of the shared library {{ic|/usr/lib/opensc-pkcs11.so}}. The ssh client should be configured to use this library with the directive PKCS11Provider in {{ic|~/.ssh/config}}:<br />
<br />
{{hc|~/.ssh/config|PKCS11Provider /usr/lib/opensc-pkcs11.so}}<br />
<br />
==== Public key conversion ====<br />
<br />
The {{ic|pubkey.pem}} file contains the public key in PEM (Privacy Enhanced Mail) format. OpenSSH uses a different format defined in RFC 4253,<br />
section 6.6, so the PEM formatted key should be converted to the format OpenSSH understands. This can be done using ''ssh-keygen'':<br />
<br />
$ ssh-keygen -i -m PKCS8 -f pubkey.pem > pubkey.txt<br />
<br />
This command uses the import ({{ic|-i}}) function of the ''ssh-keygen'' program, specifies PKCS8 as the input file format ({{ic|-m}}), and reads the input from the ({{ic|-f}}) file {{ic|pubkey.pem}}. The converted key is written on standard output, which is the example is redirected to the file {{ic|pubkey.txt}}.<br />
<br />
The converted public key should now be copied to the remote server as described in [[SSH keys#Copying the public key to the remote server]].<br />
<br />
==== Initiating an SSH session with the YubiKey ====<br />
<br />
To authenticate a SSH connection using the YubiKey, just use ''ssh'' normally. You will be prompted for the PIN instead of a password:<br />
<br />
$ ssh remote<br />
Enter PIN for 'SSH Key' <br />
[user@remote ~]$ <br />
<br />
==== Using ssh-agent to cache the PIN ====<br />
<br />
ssh-agent (see [[SSH keys#SSH agents]]) can also be used with the PKCS#11 library; in this case the PIN code is cached instead of the private key.<br />
<br />
$ ssh-add -s /usr/lib/pkcs11/opensc-pkcs11.so<br />
<br />
As long as the PIN is cached in by the agent, the cached value is used and the user is not prompted for it.<br />
<br />
==== Further reading ====<br />
<br />
The default PIN code of the PIV application on the YubiKey is {{ic|123456}}; you may want to change it. The YubiKey also requires a 24-byte management key for administrative functions like key generation. If the management key has been changed from its default value, the new value needs to be specified using the -m option on the command line for certain commands. See [https://developers.yubico.com/PIV/ What is PIV?]<br />
<br />
== Tips and tricks ==<br />
<br />
=== YubiKey and LUKS encrypted partition/disk ===<br />
<br />
YubiKey can be used to strengthen the security of your [[LUKS]] encrypted partition/disk.<br />
<br />
One way to achieve it is to use a Challenge-Response mode for creating strong LUKS passphrases. [https://github.com/agherzan/yubikey-full-disk-encryption yubikey-full-disk-encryption] is a robust and comfortable to use implementation of an [[initramfs]] hook and on-demand scripts to create/open LUKS encrypted partitions/disks using a stored or manually provided challenge.<br />
<br />
Another way of using YubiKey for full disk encryption is to utilize its OpenPGP applet to decrypt the LUKS keyfile during boot. [https://github.com/fuhry/initramfs-scencrypt initramfs-scencrypt] is a set of hooks for initramfs that automate this process.<br />
<br />
=== Yubikey and KeePass ===<br />
<br />
{{Style|Duplicates [[KeePass]].}}<br />
<br />
Yubikey can be integrated with [[KeePass]] using [[KeePass#Yubikey|plugins]].<br />
<br />
For a native open-source implementation of KeePass have a look at:<br />
<br />
==== keepassx2 ====<br />
<br />
{{AUR|keepassx2}} ([https://keepassx.org/ see keepassx.org]) a keepass QT FOSS reimplementation, extremely stable and available for Windows, MacOSX and Linux.<br />
<br />
==== KeePassXC ====<br />
<br />
{{Pkg|keepassxc}} ([https://keepassxc.org/ see keepassxc.org]) a KeePassX fork that integrated YubiKey into KeePassX v2.<br>The integration covers Challenge-Response as security factor to open the database, but also the generation of OTP using the YubiKey.<br />
<br />
In order to have a KeePassXC database work on Android (using the [https://play.google.com/store/apps/details?id=keepass2android.keepass2android Keepass2Android app]), you need to use version 1.06 of the app. You also need to save the database file in the KDBX 4 format, since Keepass2Android do not support the KDBX 3 format.<br />
<br />
YubiKey support in Keepass2Android (which is compatible with KeePassXC) is tracked [https://github.com/PhilippC/keepass2android/issues/4 on GitHub].<br />
<br />
=== Two-factor authentication with SSH ===<br />
<br />
{{Note|See also: https://developers.yubico.com/yubico-pam/Yubikey_and_SSH_via_PAM.html}}<br />
<br />
This details how to use a Yubikey to have [[wikipedia:Two-factor_authentication|two-factor authentication]] with SSH, that is, to use both a password and a Yubikey-generated OTP.<br />
<br />
==== Prerequisites ====<br />
<br />
Install {{Pkg|yubico-pam}}.<br />
<br />
{{Note|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 of your server if the configuration does not work and you exit your main session inadvertently}}<br />
<br />
{{Note|The following assumes you are using the default Yubico servers. See the [https://github.com/Yubico/yubico-pam yubico-pam documentation] for options relevant to using your own server.}}<br />
<br />
==== Configuration ====<br />
<br />
===== Authorization Mapping Files =====<br />
<br />
A mapping must be made between the YubiKey token ID and the user ID it is<br />
attached to. There are two ways to do this, either centrally in one file, or<br />
individually, where users can create the mapping in their home directories.<br />
If the central authorization mapping file is being used, user home directory<br />
mappings will not be used and vice versa.<br />
<br />
====== Central authorization mapping ======<br />
<br />
Create a file {{ic|/etc/yubico/authorized_yubikeys}}, the file must contain a user name and the<br />
Yubikey token ID separated by colons (same format as the passwd file) for<br />
each user you want to allow onto the system using a Yubikey.<br />
<br />
The mappings should look like this, one per line:<br />
<br />
<first user name>:<Yubikey token ID1>:<Yubikey token ID2>:...<br />
<second user name>:<Yubikey token ID3>:<Yubikey token ID4>:...<br />
<br />
You can specify multiple key tokens to correspond to one user, but only one is required.<br />
<br />
====== Per-user authorization mapping ======<br />
<br />
Each user creates a {{ic|~/.yubico/authorized_yubikeys}} file inside of their home<br />
directory and places the mapping in that file, the file must have only one<br />
line:<br />
<br />
<user name>:<Yubikey token ID1>:<Yubikey token ID2><br />
<br />
This is much the same concept as the SSH authorized_keys file.<br />
<br />
Note that this file must be readable by the {{ic|pam_yubico}} module when the user is authenticated, otherwise login will fail. If this is not possible or desired, use the global mapping file instead.<br />
<br />
====== Obtaining the YubiKey token ID (a.k.a. public ID) ======<br />
<br />
You can obtain the YubiKey token ID in several ways. One is by<br />
removing the last 32 characters of any OTP (One Time Password)<br />
generated with your YubiKey. Another is by using the<br />
[http://demo.yubico.com/php-yubico/Modhex_Calculator.php modhex calculator].<br />
<br />
Enter your YubiKey OTP and convert it, your Yubikey token ID is 12<br />
characters and listed as:<br />
<br />
Modhex encoded: XXXXXXX<br />
<br />
===== PAM configuration =====<br />
<br />
Having set up the {{ic|pam_yubico}} module, you next need to tell PAM to use it when logging in via SSH. There are several ways of doing this.<br />
<br />
====== The default way ======<br />
<br />
Obtain HMAC credentials from Yubico as described in [[#YubiCloud and validation servers]]. You will receive a Client ID and a secret key.<br />
<br />
Add one of the two following lines to the beginnning of {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID authfile=/etc/yubico/authorized_yubikeys<br />
<br />
if you are using a central authorization mapping file, or<br />
<br />
auth required pam_yubico.so id=CLIENTID<br />
<br />
if you are using per-user authorization mapping, where {{ic|CLIENTID}}} is your Client ID. This method utilizes your ID and the server's certificate to authenticate the connection.<br />
<br />
{{Note|This will authenticate via Yubico's free YubiCloud servers. If you want to use a different server, add it via the {{ic|urllist}} parameter.}}<br />
<br />
====== Using pure HMAC to authenticate the validation server ======<br />
<br />
Add {{ic|key}} to the above lines in {{ic|/etc/pam.d/sshd}}:<br />
<br />
auth required pam_yubico.so id=CLIENTID key=SECRETKEY ...<br />
<br />
where {{ic|CLIENTID}} and {{ic|SECRETKEY}} are your HMAC ID and key.<br />
<br />
You should also disallow unprivileged users to read the file to prevent them from seeing the HMAC credentials:<br />
# chmod o-r /etc/pam.d/sshd<br />
<br />
{{Note|HMAC credentials should be unique to a single target server. That way, if an attacker finds them, he will not be able to craft responses to authenticate to other target servers you own}}<br />
<br />
====== Using pure HTTPS to authenticate the validation server ======<br />
<br />
{{Warning|While this "old" method of using a dummy id still works, it is unknown how secure and/or future-proof it is, as Yubico no longer describes it in their documentation. Proceed at your own risk. At the very least you should ensure that only HTTPS servers with valid certificates are used for authentication.}}<br />
<br />
If you do not want to use HMAC credentials from Yubico, it is still possible to authenticate via the Yubico server by setting {{ic|1=CLIENTID=1}} instead of your own ID. Although {{ic|pam_yubico}}'s default server uses HTTPS already, for security reasons you should specify it manually via the {{ic|urllist}} parameter, as the servers certificate is the only way in which the connection is authenticated. You can find the keyserver URL by adding the {{ic|debug}} parameter to the {{ic|auth}} line.<br />
<br />
===== SSHD configuration =====<br />
<br />
You should check that {{ic|/etc/ssh/sshd_config}} contains these lines and that they are not commented. The {{ic|sshd_config}} shipped with {{pkg|openssh}} has these set correctly by default.<br />
ChallengeResponseAuthentication no<br />
UsePAM yes<br />
<br />
==== That is it! ====<br />
<br />
You should not need to restart anything if you did not change the SSHD config file.<br />
<br />
To log in, at the {{ic|Password:}} prompt of SSH, you have to type your password '''without pressing enter''' and touch the Yubikey's button.<br />
The Yubikey should send a return at the end of the OTP so you do not need to touch the enter key at all.<br />
<br />
You can display information about the login data generated by {{ic|pam_yubico}} by adding the {{ic|debug}} option to the auth line in{{ic|/etc/pam.d/sshd}}. However, if you are using a central authorization file, you should remove that option once finished testing, as it causes {{ic|pam_yubico}} to display the entire content of the central file to every user who logs in using a Yubikey.<br />
<br />
==== Explanation ====<br />
<br />
This works because the prompt is {{ic|pam_yubico.so}}'s one, since this module is before {{ic|pam_unix.so}}, which normally does basic password authentication.<br />
So, you are giving a string that is the concatenation of your password and the OTP to {{ic|pam_yubico.so}}.<br />
Since the OTPs have a fixed length (let us call this size N), it just has to get the last N characters to retrieve the OTP, and it assumes that the other characters at the start are the password.<br />
It tries to validate the OTP, and in case of success, sends the password to the next PAM module. In Archlinux' default PAM stack, the authenticator {{ic|pam_unix.so}} is instructed to try receiving a password from the previous module with {{ic|try_first_pass}}, so it automatically uses the password sent by {{ic|pam_yubico.so}}.<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_MODEL}=="Yubikey_4_OTP+U2F+CCID", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0407", RUN+="/usr/local/bin/script args"<br />
<br />
Please note, that this example is for the yubikey 4, and 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. 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 [http://opensource.yubico.com/ykneo-oath/releases.html 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 {{AUR|yubico-yubioath-desktop}}{{Broken package link|package not found}} or {{AUR|yubico-yubioath-desktop-git}}.<br />
<br />
While {{ic|pcscd.service}} is running, run {{ic|yubioath-gui}} 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 />
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 />
You may also need to [[install]] the package {{pkg|libu2f-host}} if you want support in chrome.<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 />
=== 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 {{ic|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.</div>Comruminohttps://wiki.archlinux.org/index.php?title=Talk:VMware/Install_Arch_Linux_as_a_guest&diff=587167Talk:VMware/Install Arch Linux as a guest2019-10-25T09:31:20Z<p>Comrumino: Created a new discussion titled "X11 and tools.conf" to discuss topic expansion and relevance to users</p>
<hr />
<div>== Additional info while installing on VMWare player 6.0.1 ==<br />
<br />
I had to do a few additional things while installing on VMWare player wrt the Official VMWare tools. The kernel version was 3.12 and vmware player was 6.0.1.<br />
To highlight the points:<br />
* I did not get the tools ISO with my VMware player installation and had to source it from one of the vmware websites.<br />
* The source for the vmci module had to be replaced with one which I found from the vmware forums in the tools .<br />
* A patch had to be applied vmhgfs module source<br />
If someone could let me know if any of this info would be qualify to go into the wiki then I can add them in. It might help someone trying to install on VMWare player.<br />
[[User:Nsmathew|Nsmathew]] ([[User talk:Nsmathew|talk]]) 07:31, 29 November 2013 (UTC) nsmathew<br />
<br />
== vsock and vmw_vsock_vmci_transport drivers ==<br />
<br />
What is the purpose of those drivers and when are they needed?<br />
<br />
According to this Ubuntu manual page it looks like they probably get loaded automatically anyway if needed: [http://manpages.ubuntu.com/manpages/saucy/man9/vmsock.9.html vmsock]<br />
<br />
--[[User:BertiBoeller|BertiBoeller]] ([[User talk:BertiBoeller|talk]]) 06:37, 8 May 2015 (UTC)<br />
<br />
== Disabling PC speaker. ==<br />
<br />
Add 'mks.noBeep = "TRUE"' to general [https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1664] or guest config. --[[User:Althathwe|Althathwe]] ([[User talk:Althathwe|talk]]) 17:21, 8 November 2016 (UTC)<br />
<br />
:Configuration of the vmx may belong in [[vmware]] [[User:StrayArch|StrayArch]] ([[User talk:StrayArch|talk]]) 17:32, 8 November 2016 (UTC)<br />
<br />
== Copy / Paste ==<br />
<br />
It should be mentioned in the installation section that {{Pkg|gtkmm3}} is required for copy and paste / drag and drop to function.<br />
--[[User:TheChickenMan|TheChickenMan]] ([[User talk:TheChickenMan|talk]]) 17:34, 6 March 2018 (UTC)<br />
<br />
== X11 and tools.conf ==<br />
I got tired if manually adjusting guest resolution for AwesomeWM, but I believe it applies to X11 more generally. Part of creating github.com/vmware/open-vm-tools/pull/382 to fix github.com/vmware/open-vm-tools/issues/265 required updating {{ic|tools.conf}} for debug level logging. So, we may want to add a section covering {{ic|/etc/vmware-tools/tools.conf.example}}. If {{ic|allow-x11-backend<nowiki>=</nowiki>true}} support is merged, it would be worth mentioning along with some existing configurations. I'm thinking that adding coverage regarding {{ic|Autofit Guest}} for X11 and at least a mention that {{ic|tools.conf}} exists would enrich the article. Do you think any particular part of {{ic|tools.conf}} would be of interest? Any thoughts on X11 with respect to {{ic|open-vm-tools}}? [[User:Comrumino|Comrumino]] ([[User talk:Comrumino|talk]]) 09:31, 25 October 2019 (UTC)</div>Comruminohttps://wiki.archlinux.org/index.php?title=Awesome&diff=564142Awesome2019-01-20T22:23:34Z<p>Comrumino: Removed out of date template as there are no more dead links</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Dynamic WMs]]<br />
[[Category:Tiling WMs]]<br />
[[cs:Awesome]]<br />
[[es:Awesome]]<br />
[[fr:Awesome3]]<br />
[[it:Awesome]]<br />
[[ja:Awesome]]<br />
[[ko:Awesome]]<br />
[[ru:Awesome]]<br />
[[sv:Awesome]]<br />
[[zh-hans:Awesome]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Xdg-menu}}<br />
{{Related articles end}}<br />
From the [https://awesomewm.org/ awesome website]:<br />
<br />
:[[Wikipedia:awesome (window manager)|awesome]] is a highly configurable, next generation framework [[window manager]] for [[Xorg]]. It is very fast and extensible [..]. It is primarily targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on its graphical environment.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|awesome}} package. The development version is {{AUR|awesome-git}}, which is considered unstable and may have a different configuration API.<br />
<br />
== Starting ==<br />
<br />
Run {{ic|awesome}} with [[xinit]]. To use the included [[xsession]] file, see [[Display manager]].<br />
<br />
=== KDM ===<br />
<br />
Create as root:<br />
<br />
{{hc|/usr/share/apps/kdm/sessions/awesome.desktop|2=<br />
[Desktop Entry]<br />
Name=Awesome<br />
Comment=Tiling Window Manager<br />
Type=Application<br />
Exec=/usr/bin/awesome<br />
TryExec=/usr/bin/awesome<br />
}}<br />
<br />
=== With GNOME ===<br />
<br />
You can set up [[GNOME]] to use awesome as the visual interface, but have GNOME work in the background. See [http://awesome.naquadah.org/wiki/Quickly_Setting_up_Awesome_with_Gnome awesome wiki]{{Dead link|2018|4|11}} for details.<br />
<br />
=== XFCE ===<br />
<br />
See [[Xfce#Use a different window manager]].<br />
<br />
== Configuration ==<br />
<br />
The lua based configuration file is at {{Ic|~/.config/awesome/rc.lua}}.<br />
<br />
=== Creating the configuration file ===<br />
<br />
First, run the following to create the directory needed in the next step:<br />
<br />
$ mkdir -p ~/.config/awesome/<br />
<br />
Whenever compiled, awesome will attempt to use whatever custom settings are contained in ~/.config/awesome/rc.lua. This file is not created by default, so we must copy the template file first:<br />
<br />
$ cp /etc/xdg/awesome/rc.lua ~/.config/awesome/<br />
<br />
The API for the configuration often changes when awesome updates. So, remember to repeat the command above when you get something strange with awesome, or you want to modify the configuration.<br />
<br />
For more information about configuring awesome, check out the [https://awesomewm.org/apidoc/documentation/90-FAQ.md.html#Configuration configuration section at awesome docs]<br />
<br />
==== Examples ====<br />
<br />
{{Note|The API for awesome configuration changes regularly, so you will likely have to modify any file you download.}}<br />
<br />
Some good examples of rc.lua would be as follows:<br />
<br />
* [https://github.com/setkeh/Awesome Setkeh's Awesome Configuration]<br />
* [http://awesome.naquadah.org/wiki/User_Configuration_Files Collection of user configurations on the awesome homepage]{{Dead link|2018|4|11}}<br />
* [https://github.com/copycat-killer/awesome-copycats User configuration that supports different themes, including a status bar]<br />
<br />
=== Extensions ===<br />
<br />
Several extensions are available for awesome:<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | Extension<br />
! style="font-weight: bold;" | Functionality<br />
! style="font-weight: bold;" | Version<br />
|-<br />
|<br />
* [https://github.com/guotsuan/awesome-revelation Revelation]<br />
| Bring up a view of all opened clients<br />
| Awesome 3.5+<br />
|-<br />
|<br />
* [https://github.com/bioe007/awesome-shifty Shifty]<br />
| Dynamic tagging<br />
| Awesome 3.5<br />
|-<br />
|<br />
* [https://awesomewm.org/apidoc/libraries/naughty.html Naughty]<br />
| Pop-up notifications<br />
| Awesome 3.5+<br />
|-<br />
| <br />
* [https://github.com/vicious-widgets/vicious Vicious]<br />
* [https://github.com/hoelzro/obvious Obvious]<br />
* [https://code.google.com/archive/p/bashets/ Bashets]<br />
| Additional [https://awesomewm.org/recipes/ widgets]<br />
| Awesome 3.5<br />
|-<br />
|}<br />
<br />
=== Autostart ===<br />
<br />
To autorun programs, create a shell script via <br />
$ touch ~/.config/awesome/autorun.sh<br />
and make it executable by <br />
$ chmod +x ~/.config/awesome/autorun.sh<br />
Open {{ic|autorun.sh}} in an editor and insert the following:<br />
{{hc|head=.config/awesome/autorun.sh|output=<br />
#!/usr/bin/env bash<br />
<br />
function run {<br />
if ! pgrep $1 ;<br />
then<br />
$@&<br />
fi<br />
}<br />
}}<br />
<br />
To add programs to autostart, simply append {{ic|run program [some arguments]}} to {{ic|autorun.sh}}. The {{ic|run}} function checks whether there already is an instance of {{ic|program}} running and only runs {{ic|program}} if there is none. You can check your {{ic|autorun.sh}} by running it:<br />
<br />
$ ~/.config/awesome/autorun.sh<br />
<br />
If everything is fine, add the following line to your {{ic|rc.lua}}:<br />
<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
...<br />
awful.spawn.with_shell("~/.config/awesome/autorun.sh")<br />
...<br />
}}<br />
<br />
=== Changing keyboard layout===<br />
There is multiple ways to configure keyboard layers. In the default config awesome already has the layout widget activated - but it wont show up until there is a choice. To set multiple layers temporary, run<br />
<br />
$ setxkbmap -layout "us,de"<br />
<br />
The awesome keyboard widget should appear, clicking on it should toggle the layout. If you want a keycombo to change the layout, you may append {{ic|-option "grp:alt_shift_toggle"}}. This for example will let you change the layout by pressing {{ic|Shift+Alt}}. So the complete command would be:<br />
<br />
$ setxkbmap -layout "us,de" -option "grp:alt_shift_toggle"<br />
<br />
Or you can use Awesome itself to switch(from v.4). Add the following line in the keybindings section of rc.lua:<br />
<br />
awful.key({ "Shift" }, "Alt_L", function ) mykeyboardlayout.next_layout(); end) <br />
awful.key({ "Mod1" }, "Shift_L", function ) mykeyboardlayout.next_layout(); end)<br />
<br />
This requires you to set up the keyboard layouts you want to be able to switch between either by the setxkbmap command or in X configuration files.<br />
<br />
Once you've found the appropriate command to setup your layouts, add it to [[#Autostart]].<br />
<br />
Alternatively, see [[Keyboard configuration in Xorg]].<br />
<br />
=== Theming ===<br />
<br />
[https://awesomewm.org/apidoc/libraries/beautiful.html Beautiful] is a Lua library that allows you to theme awesome using an external file, it becomes very easy to dynamically change your whole awesome colours and wallpaper without changing your {{ic|rc.lua}}. <br />
<br />
The default theme is at {{ic|/usr/share/awesome/themes/default}}. Copy it to {{ic|~/.config/awesome/themes/default}} and change {{ic|theme_path}} in {{ic|rc.lua}}. <br />
<br />
beautiful.init(awful.util.getdir("config") .. "/themes/default/theme.lua")<br />
<br />
See also [https://awesomewm.org/apidoc/libraries/beautiful.html] for additional theming options. To add a useless gap for example, add<br />
<br />
beautiful.useless_gap = 5<br />
<br />
At the bottom of the theming section in your {{ic|rc.lua}}.<br />
<br />
==== Wallpaper ====<br />
<br />
Beautiful can handle your wallpaper, thus you do not need to set it up in your {{ic|.xinitrc}} or {{ic|.xsession}} files. This allows you to have a specific wallpaper for each theme.<br />
<br />
With version 3.5 Awesome no longer provides a awsetbg command, instead it has a gears module. You can set your wallpaper inside {{ic|theme.lua}} with <br />
<br />
theme.wallpaper = "~/.config/awesome/themes/awesome-wallpaper.png" <br />
<br />
To load the wallpaper, make sure your {{ic|rc.lua}} contains<br />
<br />
beautiful.init("~/.config/awesome/themes/default/theme.lua")<br />
for s = 1, screen.count() do<br />
gears.wallpaper.maximized(beautiful.wallpaper, s, true)<br />
end<br />
<br />
For a random background image, add [https://gist.github.com/anonymous/37f3b1c58d6616cab756] to {{ic|rc.lua}} (v3.5+). To automatically fetch images from a given directory use [https://gist.github.com/anonymous/9072154f03247ab6e28c] instead.<br />
<br />
To simply specify the wallpaper in your {{ic|rc.lua}}, add the following line to the theming section:<br />
<br />
beautiful.wallpaper = awful.util.get_configuration_dir() .. "path/to/wallpaper.png"<br />
<br />
The optional {{ic|awful.util.get_configuration_dir()}} simply returns the path to your {{ic|rc.lua}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Hide / show wibox ===<br />
<br />
For awesome 4.0:<br />
<br />
awful.key({ modkey }, "b",<br />
function ()<br />
myscreen = awful.screen.focused()<br />
myscreen.mywibox.visible = not myscreen.mywibox.visible<br />
end,<br />
{description = "toggle statusbar"}<br />
),<br />
<br />
=== Screenshot ===<br />
<br />
See [[Extra keyboard keys]] to ensure the {{ic|PrtSc}} button is assigned correctly. Then install a [[Taking a screenshot|screen capturing program]] such as [[Taking a screenshot#scrot|scrot]]<br />
<br />
Add to the {{ic|globalkeys}} array:<br />
<br />
awful.key({ }, "Print", function () awful.util.spawn("scrot -e 'mv $f ~/screenshots/ 2>/dev/null'", false) end),<br />
<br />
This function saves screenshots inside {{ic|~/screenshots/}}, edit as needed.<br />
<br />
=== Removing window gaps ===<br />
<br />
As of awesome 3.4, it is possible to remove the small gaps between windows; in the ''awful.rules.rules'' table there is a ''properties'' section, add to it <br />
<br />
size_hints_honor = false<br />
<br />
=== Transparency ===<br />
<br />
See [[composite manager]].<br />
<br />
In awesome 3.5, window transparency can be set dynamically using signals. For example, {{ic|rc.lua}} could contain the following:<br />
<br />
client.connect_signal("focus", function(c)<br />
c.border_color = beautiful.border_focus<br />
c.opacity = 1<br />
end)<br />
client.connect_signal("unfocus", function(c)<br />
c.border_color = beautiful.border_normal<br />
c.opacity = 0.7<br />
end)<br />
<br />
==== Conky ====<br />
{{Merge|Conky}}<br />
<br />
If using conky, you must set it to create its own window instead of using the desktop. To do so, edit {{ic|~/.conkyrc}} to contain<br />
<br />
own_window yes<br />
own_window_transparent yes<br />
own_window_type desktop<br />
<br />
Otherwise strange behavior may be observed, such as all windows becoming fully transparent. Note also that since conky will be creating a transparent window on your desktop, any actions defined in awesome's {{ic|rc.lua}} for the desktop will not work where conky is.<br />
<br />
==== wiboxes ====<br />
<br />
As of Awesome 3.1, there is built-in pseudo-transparency for wiboxes. To enable it, append 2 hexadecimal digits to the colors in your theme file ({{ic|~/.config/awesome/themes/default}}, which is usually a copy of {{ic|/usr/share/awesome/themes/default}}), like shown here:<br />
<br />
bg_normal = #000000AA<br />
<br />
where "AA" is the transparency value.<br />
<br />
To change transparency for the actual selected window by pressing {{ic|Modkey + PgUp/PgDown}} you can also use {{Pkg|transset-df}} and the following modification to your {{ic|rc.lua}}:<br />
<br />
globalkeys = awful.util.table.join(<br />
-- your keybindings<br />
[...]<br />
awful.key({ modkey }, "Next", function (c)<br />
awful.util.spawn("transset-df --actual --inc 0.1")<br />
end),<br />
awful.key({ modkey }, "Prior", function (c)<br />
awful.util.spawn("transset-df --actual --dec 0.1")<br />
end),<br />
-- Your other key bindings<br />
[...]<br />
)<br />
<br />
==== ImageMagick ====<br />
<br />
{{Merge|Composite manager}}<br />
<br />
You may have problems if you set your wallpaper with imagemagick's ''display'' command. It does not work well with xcompmgr. Please note that awsetbg may be using ''display'' if it does not have any other options. Installing habak, feh, hsetroot or whatever should fix the problem (''grep -A 1 wpsetters /usr/bin/awsetbg'' to see your options).<br />
<br />
=== Passing content to widgets with awesome-client ===<br />
<br />
You can easily send text to an awesome widget. Just create a new widget:<br />
<br />
mywidget = widget({ type = "textbox", name = "mywidget" })<br />
mywidget.text = "initial text"<br />
<br />
To update the text from an external source, use awesome-client:<br />
<br />
echo -e 'mywidget.text = "new text"' | awesome-client<br />
<br />
Do not forget to add the widget to your wibox.<br />
<br />
=== Using a different panel with awesome ===<br />
<br />
If you like awesome's lightweightness and functionality but do not like the way its default panel looks, you can install a different panel, for example {{Pkg|xfce4-panel}}.<br />
<br />
Then add it to the [[#Autostart|autorun section]] of your {{ic|rc.lua}}. You may also comment out the section which creates wiboxes for each screen (starting from {{ic|1=mywibox[s] = awful.wibox({ position = "top", screen = s })}}) but it is not necessary. Do not forget to check your {{ic|rc.lua}} for errors by typing:<br />
<br />
$ awesome -k rc.lua<br />
<br />
You should also change your {{ic|''modkey''+R}} keybinding, in order to start some other application launcher instead of built in awesome. See [[List of applications#Application launchers]] for examples. Do not forget to add:<br />
<br />
{{bc|<nowiki><br />
properties = { floating = true } },<br />
{ rule = { instance = "$yourapplicationlauncher" },<br />
</nowiki>}}<br />
<br />
to your {{ic|rc.lua}}.<br />
<br />
=== Application directories in menubar ===<br />
<br />
{{Pkg|awesome}} includes [https://awesomewm.org/apidoc/libraries/menubar.html menubar]. By default, pressing {{ic|''Mod''+p}} will open a dmenu-like applications menu at the top of the screen. However, this menu only searches for {{ic|.desktop}} files in {{ic|/usr/share/applications}} and {{ic|/usr/local/share/applications}}. <br />
<br />
To change this, add the following line to {{ic|rc.lua}}, ideally, under ''Menubar configuration'':<br />
<br />
app_folders = { "/usr/share/applications/", "~/.local/share/applications/" }<br />
<br />
Note that the {{ic|.desktop}} files are re-read each time awesome starts, thereby slowing down the startup. If you prefer other means of launching programs, the menubar can be disabled in {{ic|rc.lua}} by removing {{ic|local menubar &#61; require("menubar")}} and other references to the {{ic|menubar}} variable.<br />
<br />
=== Pop-up menus ===<br />
<br />
{{Style|Duplicate section?}}<br />
<br />
There is a simple menu by default in awesome 3, simplifying custom menus. [https://awesomewm.org/apidoc/libraries/awful.menu.html] If you want a freedesktop.org menu, you could take a look at ''[https://github.com/copycat-killer/awesome-freedesktop awesome-freedesktop]''.<br />
<br />
=== Applications menu ===<br />
<br />
If you prefer to see a more traditional applications menu when you click on the Awesome icon, or right-click on an empty area of the desktop, you can follow the instructions in [[Xdg-menu#Awesome]]. However this menu is not updated when you add or remove programs. So, be sure to run the command to update your menu. It may look something like:<br />
<br />
xdg_menu --format awesome --root-menu /etc/xdg/menus/arch-applications.menu >~/.config/awesome/archmenu.lua<br />
<br />
=== Titlebars ===<br />
<br />
It is easy to enable titlebars in awesome by simply setting the variable titlebars_enabled to true in the config file. However, you may want to be able to toggle the titlebar on or off. You can do this by simply adding something like this to your key bindings:<br />
<br />
awful.key({ modkey, "Control" }, "t",<br />
function (c)<br />
-- toggle titlebar<br />
awful.titlebar.toggle(c)<br />
end)<br />
<br />
Then you may want to initially hide the titlebars. To do that just add this immediately after the title bar is created:<br />
<br />
awful.titlebar.hide(c)<br />
<br />
=== Battery notification ===<br />
<br />
See [http://bpdp.blogspot.be/2013/06/battery-warning-notification-for.html this blog post] for a simple battery notification to add to {{ic|rc.lua}}. Note that it needs ''naughty'' for the notifications (installed by default in version 3.5). Other examples are available at [https://awesomewm.org/recipes/ awesome wiki].<br />
<br />
4/10/2018: The above mentioned wiki no longer exists. [https://www.reddit.com/r/awesomewm/comments/5k9vob/what_happened_to_the_wiki/ (Reddit comment: What happened to the wiki?)]<br />
<br />
From the linked Reddit comment:<br />
<br />
'''Workaround:'''<br />
<br />
For those still interested in it's content: [https://github.com/gutierri/awesomewm-wiki-dump/tree/master/markdown https://github.com/gutierri/awesomewm-wiki-dump/tree/master/markdown] has a partial markdown conversion of the old wiki (and the raw dump in xml format too).<br />
<br />
[https://github.com/gutierri/awesomewm-wiki-dump/blob/master/markdown/Acpitools-based_battery_widget.md Here] is the only Battery widget from the partial wiki. It is based on [[ACPI_modules|ACPI]] and written for version 3.5. I am not reproducing it here b/c there may be additional steps to get it working.<br />
<br />
<br />
'''NOTE: This partial wiki only covers versions up to 3.x'''<br />
<br />
=== Media Controls ===<br />
<br />
It is possible to control both volume and media playback via a combination of amixer (available via the {{pkg|alsa-utils}} package) and {{Pkg|playerctl}}. The following can be added to the relevant key binding section of your rc.lua configuration file:<br />
<br />
-- Volume Keys<br />
awful.key({}, "XF86AudioLowerVolume", function ()<br />
awful.util.spawn("amixer -q -D pulse sset Master 5%-", false)<br />
end),<br />
awful.key({}, "XF86AudioRaiseVolume", function ()<br />
awful.util.spawn("amixer -q -D pulse sset Master 5%+", false)<br />
end),<br />
awful.key({}, "XF86AudioMute", function ()<br />
awful.util.spawn("amixer -D pulse set Master 1+ toggle", false)<br />
end),<br />
-- Media Keys<br />
awful.key({}, "XF86AudioPlay", function()<br />
awful.util.spawn("playerctl play-pause", false)<br />
end),<br />
awful.key({}, "XF86AudioNext", function()<br />
awful.util.spawn("playerctl next", false)<br />
end),<br />
awful.key({}, "XF86AudioPrev", function()<br />
awful.util.spawn("playerctl previous", false)<br />
end),<br />
<br />
=== Steam Keyboard ===<br />
<br />
The on screen Steam Keyboard that can be activated by the [[Steam Controller]] appears to freeze after trying to type one character. This is because the client that is supposed to receive the input has to be focussed to receive it and the keyboard will wait until this input is successfully send. Manually focussing another client will send the input to this client and unfreeze the keyboard again until the next character is entered.<br />
<br />
The trick to getting the keyboard to work correctly is to prevent it ever receiving focus. Add the following signal to your config (or merge with an existing client focus signal):<br />
<br />
client.connect_signal("focus", function(c)<br />
if awful.rules.match(c, { name = "^Steam Keyboard$" }) then<br />
awful.client.focus.history.previous()<br />
end<br />
end)<br />
<br />
This will return the focus to the last client whenever the keyboard receives focus. As the input to the keyboard is handled by the [[Steam]] client and as such doesn't need focus, inputting text will now work correctly.<br />
<br />
==Troubleshooting==<br />
<br />
=== Debugging rc.lua ===<br />
<br />
{{Pkg|xorg-server-xephyr}} allows you to run X nested in another X's client window. This allows you to debug rc.lua without breaking your current desktop. Start by copying rc.lua into a new file (e.g. rc.lua.new), and modify it as needed. Then run new instance of awesome in Xephyr, supplying rc.lua.new as a config file like this:<br />
<br />
$ Xephyr :1 -ac -br -noreset -screen 1152x720 &<br />
$ DISPLAY=:1.0 awesome -c ~/.config/awesome/rc.lua.new<br />
<br />
The advantage of this approach is that if you introduce bugs you do not break your current awesome desktop, potentially crashing X apps and losing work. Once you are happy with the new configuration, copy rc.lua.new to rc.lua and restart awesome.<br />
<br />
==== awmtt ====<br />
<br />
{{AUR|awmtt}} (Awesome WM Testing Tool) is an easy to use wrapper script around Xephyr. By default, it will use ~/.config/awesome/rc.lua.test. If it cannot find that test file, it will use your actual rc.lua. You can also specify the location of the configuration file you want to test:<br />
<br />
$ awmtt start -C ~/.config/awesome/rc.lua.new<br />
<br />
When you are done testing, close the window with:<br />
<br />
$ awmtt stop<br />
<br />
Or immediately see the changes you are doing to the configuration file by issuing:<br />
<br />
$ awmtt restart<br />
<br />
=== Log Files ===<br />
<br />
If you are using [[LightDM]], awesome will log errors to `$HOME/.xsession-errors`. If you use {{ic|.xinitrc}} to start awesome, the entry "Where are logs, error messages or something?" in [https://awesomewm.org/apidoc/documentation/90-FAQ.md.html the FAQ] may be a helpful resource.<br />
<br />
=== Mod4 key ===<br />
<br />
{{Merge|Configuring_keyboard_layouts_in_X}}<br />
<br />
Awesome recommends to remap {{ic|mod4}}, which by default should be '''Win key'''. If for some reason it is not mapped to {{ic|mod4}}, use [[xmodmap]] to find out what is. To change the mapping, use {{ic|xev}} to find the keycode and name of the key to be mapped. Then add something like the following to {{ic|~/.xinitrc}} <br />
<br />
xmodmap -e "keycode 115 = Super_L" -e "add mod4 = Super_L"<br />
exec awesome<br />
<br />
The problem in this case is that some xorg installations recognize keycode 115, but incorrectly as the 'Select' key. The above command explictly remaps keycode 115 to the correct 'Super_L' key.<br />
<br />
To remap {{ic|mod4}} with {{ic|setxkbmap}} (conflict with {{ic|xmodmap}}) see:<br />
<br />
tail -50 /usr/share/X11/xkb/rules/evdev<br />
<br />
To set the caps lock key as {{ic|mod4}} add the following to {{ic|~/.xinitrc}}:<br />
<br />
setxkbmap -option caps:hyper<br />
<br />
==== Mod4 key vs. IBM ThinkPad users ====<br />
<br />
{{Style|Duplicate section}}<br />
<br />
IBM ThinkPads, IBM Model M's and Chromebooks do not come equipped with a Window key (although Lenovo have changed this tradition on their ThinkPads). As of writing, the Alt key is not used in command combinations by the default rc.lua (refer to the Awesome wiki for a table of commands), which allows it be used as a replacement for the Super/Mod4/Win key. To do this, edit your rc.lua and replace:<br />
<br />
modkey = "Mod4"<br />
<br />
by:<br />
<br />
modkey = "Mod1"<br />
<br />
Note: Awesome does a have a few commands that make use of Mod4 plus a single letter. Changing Mod4 to Mod1/Alt could cause overlaps for some key combinations. The small amount of instances where this happens can be changed in the rc.lua file.<br />
<br />
If you have a Chromebook or do not like to change the Awesome standards, you might like to remap a key. For instance the caps lock key is rather useless (for me) adding the following contents to ~/.Xmodmap<br />
<br />
clear lock<br />
add mod4 = Caps_Lock<br />
<br />
and run {{ic|xmodmap ~/.Xmodmap}} to (re)load the file.<br />
This will change the caps lock key into the mod4 key and works nicely with the standard awesome settings. In addition, if needed, it provides the mod4 key to other X-programs as well.<br />
<br />
Recent updates of xorg related packages break mentioned remapping the second line can be replaced by (tested on a DasKeyboard and IBM Model M and xorg-server 1.14.5-2):<br />
<br />
keysym Caps_Lock = Super_L Caps_Lock<br />
<br />
=== Fix Java (GUI appears gray only) ===<br />
<br />
{{Merge|Java}}<br />
<br />
See [http://awesome.naquadah.org/wiki/Problems_with_Java awesome wiki]{{Dead link|2018|4|11}} and [https://bbs.archlinux.org/viewtopic.php?pid=450870].<br />
<br />
=== Eclipse: cannot resize/move main window ===<br />
<br />
If you get stuck and cannot move or resize the main window (using mod4 + left/right mouse button) edit the {{ic|workbench.xml}} and set fullscreen/maximized to false (if set) and reduce the width and height to numbers smaller than your single screen desktop area.<br />
<br />
{{ic|workbench.xml}} can be found in {{ic|''eclipse_workspace''/.metadata/.plugins/org.eclipse.ui.workbench/}}. Edit the line:<br />
<br />
<window height&#61;"xx" maximized&#61;"true" width&#61;"xx" x&#61;"xx" y&#61;"xx"<br />
<br />
=== Netbeans: code-prediction appears on wrong screen ===<br />
<br />
If you have two displays and use code-prediction (Ctrl + Space) in Netbeans, the code-predictions might appear on the wrong screen.<br />
This fixed it for me:<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
awful.rules.rules = {<br />
...<br />
{<br />
rule_matches = { -- Fix Netbeans<br />
class = {<br />
"sun-awt-X11-XWindowPeer", "NetBeans IDE 8.2"<br />
},<br />
name = {<br />
"win1"<br />
}<br />
}, properties = { screen = 1 } -- even with screen 1 here, this still works on the seccond screen, too (don't know why).<br />
},<br />
...<br />
<br />
}<br />
}}<br />
<br />
=== IntelliJ: menus appear on incorrect position, some windows don't open ===<br />
<br />
See [https://github.com/awesomeWM/awesome/issues/2204 GitHub issue #2204].<br />
<br />
This fixed it for me:<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
clientbuttons_jetbrains = gears.table.join(<br />
awful.button({ modkey }, 1, awful.mouse.client.move),<br />
awful.button({ modkey }, 3, awful.mouse.client.resize)<br />
)<br />
<br />
...<br />
<br />
awful.rules.rules = {<br />
...<br />
{<br />
rule = {<br />
class = "jetbrains-.*",<br />
}, properties = { focus = true, buttons = clientbuttons_jetbrains }<br />
},<br />
{<br />
rule = {<br />
class = "jetbrains-.*",<br />
name = "win.*"<br />
}, properties = { titlebars_enabled = false, focusable = false, focus = true, floating = true, placement = awful.placement.restore }<br />
},<br />
...<br />
}<br />
}}<br />
<br />
=== scrot: Cannot take a mouse selected screenshot with keyboard shortcuts===<br />
<br />
When using [[w:Scrot|scrot]], you may have problems at assigning a keyboard shortcut to the mouse selection option (formally {{ic|scrot -s}}). To fix it, add the following line to your {{ic|rc.lua}}:<br />
<br />
awful.key( { modkey, }, <shortcut>, nil, function () awful.spawn("scrot -s") end)<br />
<br />
Note that {{ic|nil}} is passed to the {{ic|press}} argument of {{ic|awful.key}}. Instead, the callback function is passed as fourth argument, which is the argument named {{ic|release}}.<br />
<br />
=== YouTube: fullscreen appears in background ===<br />
<br />
If YouTube videos appear underneath your web browser when in fullscreen mode, or underneath the panel with controls hidden, add this to {{ic|rc.lua}}<br />
<br />
{ rule = { instance = "plugin-container" },<br />
properties = { floating = true } },<br />
<br />
With Chromium add<br />
<br />
{ rule = { instance = "exe" },<br />
properties = { floating = true } },<br />
<br />
or:<br />
<br />
{ rule = { role = "_NET_WM_STATE_FULLSCREEN" },<br />
properties = { floating = true } },<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1085494#p1085494].<br />
<br />
=== Prevent the mouse scroll wheel from changing tags ===<br />
In your rc.lua, change the Mouse Bindings section to the following;<br />
-- {{{ Mouse bindings<br />
root.buttons(awful.util.table.join(<br />
awful.button({ }, 3, function () mymainmenu:toggle() end)))<br />
-- }}}<br />
<br />
=== Starting console clients on specific tags ===<br />
<br />
{{Accuracy|Useless without reasoning, probably related to instance names}}<br />
<br />
It does not work when the console application is invoked from a GTK terminal (e.g. LXTerminal). [[URxvt]] is known to work.<br />
<br />
=== Duplicate menu-entries generated by Xdg-menu ===<br />
<br />
Xdg-menu will generate duplicate entries if you copy desktop-files from /usr/share/applications to ~/.local/share/applications even though it might be preferable to simply override the originals, for example using a different theme for a specific application. One solution to the problem is to filter the generated output trough awk to remove entries with a name identical to the previous entry.<br />
<br />
xdg_menu --format awesome --root-menu /etc/xdg/menus/arch-applications.menu | awk -F, '{if (a!=$1) print $a; a=$1}' >~/.config/awesome/archmenu.lua<br />
<br />
=== Some Shortcuts not Working in Xfce4 overlapping Keys ===<br />
Check your <br />
$ xfce4-keyboard-settings<br />
<br />
for Overlapping keys like "Super L" or Key Combinations which should be run by Awesome<br />
<br />
== See also ==<br />
<br />
* https://awesomewm.org/apidoc/documentation/90-FAQ.md.html - FAQ<br />
* http://www.lua.org/pil/ - Programming in Lua (first edition)<br />
* https://awesomewm.org/ - The official awesome website<br />
* https://bbs.archlinux.org/viewtopic.php?id=88926 - share your awesome!</div>Comruminohttps://wiki.archlinux.org/index.php?title=Awesome&diff=564140Awesome2019-01-20T22:22:30Z<p>Comrumino: /* Battery notification */ Updated dead link to recipes so that information is more current</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Dynamic WMs]]<br />
[[Category:Tiling WMs]]<br />
[[cs:Awesome]]<br />
[[es:Awesome]]<br />
[[fr:Awesome3]]<br />
[[it:Awesome]]<br />
[[ja:Awesome]]<br />
[[ko:Awesome]]<br />
[[ru:Awesome]]<br />
[[sv:Awesome]]<br />
[[zh-hans:Awesome]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Xdg-menu}}<br />
{{Related articles end}}<br />
From the [https://awesomewm.org/ awesome website]:<br />
<br />
:[[Wikipedia:awesome (window manager)|awesome]] is a highly configurable, next generation framework [[window manager]] for [[Xorg]]. It is very fast and extensible [..]. It is primarily targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on its graphical environment.<br />
<br />
{{Out of date|This article references multiple pages of the [https://awesome.naquadah.org/wiki old awesome wiki], that went offline in December 2016.[https://www.reddit.com/r/awesomewm/comments/5k9vob/what_happened_to_the_wiki/] }}<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|awesome}} package. The development version is {{AUR|awesome-git}}, which is considered unstable and may have a different configuration API.<br />
<br />
== Starting ==<br />
<br />
Run {{ic|awesome}} with [[xinit]]. To use the included [[xsession]] file, see [[Display manager]].<br />
<br />
=== KDM ===<br />
<br />
Create as root:<br />
<br />
{{hc|/usr/share/apps/kdm/sessions/awesome.desktop|2=<br />
[Desktop Entry]<br />
Name=Awesome<br />
Comment=Tiling Window Manager<br />
Type=Application<br />
Exec=/usr/bin/awesome<br />
TryExec=/usr/bin/awesome<br />
}}<br />
<br />
=== With GNOME ===<br />
<br />
You can set up [[GNOME]] to use awesome as the visual interface, but have GNOME work in the background. See [http://awesome.naquadah.org/wiki/Quickly_Setting_up_Awesome_with_Gnome awesome wiki]{{Dead link|2018|4|11}} for details.<br />
<br />
=== XFCE ===<br />
<br />
See [[Xfce#Use a different window manager]].<br />
<br />
== Configuration ==<br />
<br />
The lua based configuration file is at {{Ic|~/.config/awesome/rc.lua}}.<br />
<br />
=== Creating the configuration file ===<br />
<br />
First, run the following to create the directory needed in the next step:<br />
<br />
$ mkdir -p ~/.config/awesome/<br />
<br />
Whenever compiled, awesome will attempt to use whatever custom settings are contained in ~/.config/awesome/rc.lua. This file is not created by default, so we must copy the template file first:<br />
<br />
$ cp /etc/xdg/awesome/rc.lua ~/.config/awesome/<br />
<br />
The API for the configuration often changes when awesome updates. So, remember to repeat the command above when you get something strange with awesome, or you want to modify the configuration.<br />
<br />
For more information about configuring awesome, check out the [https://awesomewm.org/apidoc/documentation/90-FAQ.md.html#Configuration configuration section at awesome docs]<br />
<br />
==== Examples ====<br />
<br />
{{Note|The API for awesome configuration changes regularly, so you will likely have to modify any file you download.}}<br />
<br />
Some good examples of rc.lua would be as follows:<br />
<br />
* [https://github.com/setkeh/Awesome Setkeh's Awesome Configuration]<br />
* [http://awesome.naquadah.org/wiki/User_Configuration_Files Collection of user configurations on the awesome homepage]{{Dead link|2018|4|11}}<br />
* [https://github.com/copycat-killer/awesome-copycats User configuration that supports different themes, including a status bar]<br />
<br />
=== Extensions ===<br />
<br />
Several extensions are available for awesome:<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | Extension<br />
! style="font-weight: bold;" | Functionality<br />
! style="font-weight: bold;" | Version<br />
|-<br />
|<br />
* [https://github.com/guotsuan/awesome-revelation Revelation]<br />
| Bring up a view of all opened clients<br />
| Awesome 3.5+<br />
|-<br />
|<br />
* [https://github.com/bioe007/awesome-shifty Shifty]<br />
| Dynamic tagging<br />
| Awesome 3.5<br />
|-<br />
|<br />
* [https://awesomewm.org/apidoc/libraries/naughty.html Naughty]<br />
| Pop-up notifications<br />
| Awesome 3.5+<br />
|-<br />
| <br />
* [https://github.com/vicious-widgets/vicious Vicious]<br />
* [https://github.com/hoelzro/obvious Obvious]<br />
* [https://code.google.com/archive/p/bashets/ Bashets]<br />
| Additional [https://awesomewm.org/recipes/ widgets]<br />
| Awesome 3.5<br />
|-<br />
|}<br />
<br />
=== Autostart ===<br />
<br />
To autorun programs, create a shell script via <br />
$ touch ~/.config/awesome/autorun.sh<br />
and make it executable by <br />
$ chmod +x ~/.config/awesome/autorun.sh<br />
Open {{ic|autorun.sh}} in an editor and insert the following:<br />
{{hc|head=.config/awesome/autorun.sh|output=<br />
#!/usr/bin/env bash<br />
<br />
function run {<br />
if ! pgrep $1 ;<br />
then<br />
$@&<br />
fi<br />
}<br />
}}<br />
<br />
To add programs to autostart, simply append {{ic|run program [some arguments]}} to {{ic|autorun.sh}}. The {{ic|run}} function checks whether there already is an instance of {{ic|program}} running and only runs {{ic|program}} if there is none. You can check your {{ic|autorun.sh}} by running it:<br />
<br />
$ ~/.config/awesome/autorun.sh<br />
<br />
If everything is fine, add the following line to your {{ic|rc.lua}}:<br />
<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
...<br />
awful.spawn.with_shell("~/.config/awesome/autorun.sh")<br />
...<br />
}}<br />
<br />
=== Changing keyboard layout===<br />
There is multiple ways to configure keyboard layers. In the default config awesome already has the layout widget activated - but it wont show up until there is a choice. To set multiple layers temporary, run<br />
<br />
$ setxkbmap -layout "us,de"<br />
<br />
The awesome keyboard widget should appear, clicking on it should toggle the layout. If you want a keycombo to change the layout, you may append {{ic|-option "grp:alt_shift_toggle"}}. This for example will let you change the layout by pressing {{ic|Shift+Alt}}. So the complete command would be:<br />
<br />
$ setxkbmap -layout "us,de" -option "grp:alt_shift_toggle"<br />
<br />
Or you can use Awesome itself to switch(from v.4). Add the following line in the keybindings section of rc.lua:<br />
<br />
awful.key({ "Shift" }, "Alt_L", function ) mykeyboardlayout.next_layout(); end) <br />
awful.key({ "Mod1" }, "Shift_L", function ) mykeyboardlayout.next_layout(); end)<br />
<br />
This requires you to set up the keyboard layouts you want to be able to switch between either by the setxkbmap command or in X configuration files.<br />
<br />
Once you've found the appropriate command to setup your layouts, add it to [[#Autostart]].<br />
<br />
Alternatively, see [[Keyboard configuration in Xorg]].<br />
<br />
=== Theming ===<br />
<br />
[https://awesomewm.org/apidoc/libraries/beautiful.html Beautiful] is a Lua library that allows you to theme awesome using an external file, it becomes very easy to dynamically change your whole awesome colours and wallpaper without changing your {{ic|rc.lua}}. <br />
<br />
The default theme is at {{ic|/usr/share/awesome/themes/default}}. Copy it to {{ic|~/.config/awesome/themes/default}} and change {{ic|theme_path}} in {{ic|rc.lua}}. <br />
<br />
beautiful.init(awful.util.getdir("config") .. "/themes/default/theme.lua")<br />
<br />
See also [https://awesomewm.org/apidoc/libraries/beautiful.html] for additional theming options. To add a useless gap for example, add<br />
<br />
beautiful.useless_gap = 5<br />
<br />
At the bottom of the theming section in your {{ic|rc.lua}}.<br />
<br />
==== Wallpaper ====<br />
<br />
Beautiful can handle your wallpaper, thus you do not need to set it up in your {{ic|.xinitrc}} or {{ic|.xsession}} files. This allows you to have a specific wallpaper for each theme.<br />
<br />
With version 3.5 Awesome no longer provides a awsetbg command, instead it has a gears module. You can set your wallpaper inside {{ic|theme.lua}} with <br />
<br />
theme.wallpaper = "~/.config/awesome/themes/awesome-wallpaper.png" <br />
<br />
To load the wallpaper, make sure your {{ic|rc.lua}} contains<br />
<br />
beautiful.init("~/.config/awesome/themes/default/theme.lua")<br />
for s = 1, screen.count() do<br />
gears.wallpaper.maximized(beautiful.wallpaper, s, true)<br />
end<br />
<br />
For a random background image, add [https://gist.github.com/anonymous/37f3b1c58d6616cab756] to {{ic|rc.lua}} (v3.5+). To automatically fetch images from a given directory use [https://gist.github.com/anonymous/9072154f03247ab6e28c] instead.<br />
<br />
To simply specify the wallpaper in your {{ic|rc.lua}}, add the following line to the theming section:<br />
<br />
beautiful.wallpaper = awful.util.get_configuration_dir() .. "path/to/wallpaper.png"<br />
<br />
The optional {{ic|awful.util.get_configuration_dir()}} simply returns the path to your {{ic|rc.lua}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Hide / show wibox ===<br />
<br />
For awesome 4.0:<br />
<br />
awful.key({ modkey }, "b",<br />
function ()<br />
myscreen = awful.screen.focused()<br />
myscreen.mywibox.visible = not myscreen.mywibox.visible<br />
end,<br />
{description = "toggle statusbar"}<br />
),<br />
<br />
=== Screenshot ===<br />
<br />
See [[Extra keyboard keys]] to ensure the {{ic|PrtSc}} button is assigned correctly. Then install a [[Taking a screenshot|screen capturing program]] such as [[Taking a screenshot#scrot|scrot]]<br />
<br />
Add to the {{ic|globalkeys}} array:<br />
<br />
awful.key({ }, "Print", function () awful.util.spawn("scrot -e 'mv $f ~/screenshots/ 2>/dev/null'", false) end),<br />
<br />
This function saves screenshots inside {{ic|~/screenshots/}}, edit as needed.<br />
<br />
=== Removing window gaps ===<br />
<br />
As of awesome 3.4, it is possible to remove the small gaps between windows; in the ''awful.rules.rules'' table there is a ''properties'' section, add to it <br />
<br />
size_hints_honor = false<br />
<br />
=== Transparency ===<br />
<br />
See [[composite manager]].<br />
<br />
In awesome 3.5, window transparency can be set dynamically using signals. For example, {{ic|rc.lua}} could contain the following:<br />
<br />
client.connect_signal("focus", function(c)<br />
c.border_color = beautiful.border_focus<br />
c.opacity = 1<br />
end)<br />
client.connect_signal("unfocus", function(c)<br />
c.border_color = beautiful.border_normal<br />
c.opacity = 0.7<br />
end)<br />
<br />
==== Conky ====<br />
{{Merge|Conky}}<br />
<br />
If using conky, you must set it to create its own window instead of using the desktop. To do so, edit {{ic|~/.conkyrc}} to contain<br />
<br />
own_window yes<br />
own_window_transparent yes<br />
own_window_type desktop<br />
<br />
Otherwise strange behavior may be observed, such as all windows becoming fully transparent. Note also that since conky will be creating a transparent window on your desktop, any actions defined in awesome's {{ic|rc.lua}} for the desktop will not work where conky is.<br />
<br />
==== wiboxes ====<br />
<br />
As of Awesome 3.1, there is built-in pseudo-transparency for wiboxes. To enable it, append 2 hexadecimal digits to the colors in your theme file ({{ic|~/.config/awesome/themes/default}}, which is usually a copy of {{ic|/usr/share/awesome/themes/default}}), like shown here:<br />
<br />
bg_normal = #000000AA<br />
<br />
where "AA" is the transparency value.<br />
<br />
To change transparency for the actual selected window by pressing {{ic|Modkey + PgUp/PgDown}} you can also use {{Pkg|transset-df}} and the following modification to your {{ic|rc.lua}}:<br />
<br />
globalkeys = awful.util.table.join(<br />
-- your keybindings<br />
[...]<br />
awful.key({ modkey }, "Next", function (c)<br />
awful.util.spawn("transset-df --actual --inc 0.1")<br />
end),<br />
awful.key({ modkey }, "Prior", function (c)<br />
awful.util.spawn("transset-df --actual --dec 0.1")<br />
end),<br />
-- Your other key bindings<br />
[...]<br />
)<br />
<br />
==== ImageMagick ====<br />
<br />
{{Merge|Composite manager}}<br />
<br />
You may have problems if you set your wallpaper with imagemagick's ''display'' command. It does not work well with xcompmgr. Please note that awsetbg may be using ''display'' if it does not have any other options. Installing habak, feh, hsetroot or whatever should fix the problem (''grep -A 1 wpsetters /usr/bin/awsetbg'' to see your options).<br />
<br />
=== Passing content to widgets with awesome-client ===<br />
<br />
You can easily send text to an awesome widget. Just create a new widget:<br />
<br />
mywidget = widget({ type = "textbox", name = "mywidget" })<br />
mywidget.text = "initial text"<br />
<br />
To update the text from an external source, use awesome-client:<br />
<br />
echo -e 'mywidget.text = "new text"' | awesome-client<br />
<br />
Do not forget to add the widget to your wibox.<br />
<br />
=== Using a different panel with awesome ===<br />
<br />
If you like awesome's lightweightness and functionality but do not like the way its default panel looks, you can install a different panel, for example {{Pkg|xfce4-panel}}.<br />
<br />
Then add it to the [[#Autostart|autorun section]] of your {{ic|rc.lua}}. You may also comment out the section which creates wiboxes for each screen (starting from {{ic|1=mywibox[s] = awful.wibox({ position = "top", screen = s })}}) but it is not necessary. Do not forget to check your {{ic|rc.lua}} for errors by typing:<br />
<br />
$ awesome -k rc.lua<br />
<br />
You should also change your {{ic|''modkey''+R}} keybinding, in order to start some other application launcher instead of built in awesome. See [[List of applications#Application launchers]] for examples. Do not forget to add:<br />
<br />
{{bc|<nowiki><br />
properties = { floating = true } },<br />
{ rule = { instance = "$yourapplicationlauncher" },<br />
</nowiki>}}<br />
<br />
to your {{ic|rc.lua}}.<br />
<br />
=== Application directories in menubar ===<br />
<br />
{{Pkg|awesome}} includes [https://awesomewm.org/apidoc/libraries/menubar.html menubar]. By default, pressing {{ic|''Mod''+p}} will open a dmenu-like applications menu at the top of the screen. However, this menu only searches for {{ic|.desktop}} files in {{ic|/usr/share/applications}} and {{ic|/usr/local/share/applications}}. <br />
<br />
To change this, add the following line to {{ic|rc.lua}}, ideally, under ''Menubar configuration'':<br />
<br />
app_folders = { "/usr/share/applications/", "~/.local/share/applications/" }<br />
<br />
Note that the {{ic|.desktop}} files are re-read each time awesome starts, thereby slowing down the startup. If you prefer other means of launching programs, the menubar can be disabled in {{ic|rc.lua}} by removing {{ic|local menubar &#61; require("menubar")}} and other references to the {{ic|menubar}} variable.<br />
<br />
=== Pop-up menus ===<br />
<br />
{{Style|Duplicate section?}}<br />
<br />
There is a simple menu by default in awesome 3, simplifying custom menus. [https://awesomewm.org/apidoc/libraries/awful.menu.html] If you want a freedesktop.org menu, you could take a look at ''[https://github.com/copycat-killer/awesome-freedesktop awesome-freedesktop]''.<br />
<br />
=== Applications menu ===<br />
<br />
If you prefer to see a more traditional applications menu when you click on the Awesome icon, or right-click on an empty area of the desktop, you can follow the instructions in [[Xdg-menu#Awesome]]. However this menu is not updated when you add or remove programs. So, be sure to run the command to update your menu. It may look something like:<br />
<br />
xdg_menu --format awesome --root-menu /etc/xdg/menus/arch-applications.menu >~/.config/awesome/archmenu.lua<br />
<br />
=== Titlebars ===<br />
<br />
It is easy to enable titlebars in awesome by simply setting the variable titlebars_enabled to true in the config file. However, you may want to be able to toggle the titlebar on or off. You can do this by simply adding something like this to your key bindings:<br />
<br />
awful.key({ modkey, "Control" }, "t",<br />
function (c)<br />
-- toggle titlebar<br />
awful.titlebar.toggle(c)<br />
end)<br />
<br />
Then you may want to initially hide the titlebars. To do that just add this immediately after the title bar is created:<br />
<br />
awful.titlebar.hide(c)<br />
<br />
=== Battery notification ===<br />
<br />
See [http://bpdp.blogspot.be/2013/06/battery-warning-notification-for.html this blog post] for a simple battery notification to add to {{ic|rc.lua}}. Note that it needs ''naughty'' for the notifications (installed by default in version 3.5). Other examples are available at [https://awesomewm.org/recipes/ awesome wiki].<br />
<br />
4/10/2018: The above mentioned wiki no longer exists. [https://www.reddit.com/r/awesomewm/comments/5k9vob/what_happened_to_the_wiki/ (Reddit comment: What happened to the wiki?)]<br />
<br />
From the linked Reddit comment:<br />
<br />
'''Workaround:'''<br />
<br />
For those still interested in it's content: [https://github.com/gutierri/awesomewm-wiki-dump/tree/master/markdown https://github.com/gutierri/awesomewm-wiki-dump/tree/master/markdown] has a partial markdown conversion of the old wiki (and the raw dump in xml format too).<br />
<br />
[https://github.com/gutierri/awesomewm-wiki-dump/blob/master/markdown/Acpitools-based_battery_widget.md Here] is the only Battery widget from the partial wiki. It is based on [[ACPI_modules|ACPI]] and written for version 3.5. I am not reproducing it here b/c there may be additional steps to get it working.<br />
<br />
<br />
'''NOTE: This partial wiki only covers versions up to 3.x'''<br />
<br />
=== Media Controls ===<br />
<br />
It is possible to control both volume and media playback via a combination of amixer (available via the {{pkg|alsa-utils}} package) and {{Pkg|playerctl}}. The following can be added to the relevant key binding section of your rc.lua configuration file:<br />
<br />
-- Volume Keys<br />
awful.key({}, "XF86AudioLowerVolume", function ()<br />
awful.util.spawn("amixer -q -D pulse sset Master 5%-", false)<br />
end),<br />
awful.key({}, "XF86AudioRaiseVolume", function ()<br />
awful.util.spawn("amixer -q -D pulse sset Master 5%+", false)<br />
end),<br />
awful.key({}, "XF86AudioMute", function ()<br />
awful.util.spawn("amixer -D pulse set Master 1+ toggle", false)<br />
end),<br />
-- Media Keys<br />
awful.key({}, "XF86AudioPlay", function()<br />
awful.util.spawn("playerctl play-pause", false)<br />
end),<br />
awful.key({}, "XF86AudioNext", function()<br />
awful.util.spawn("playerctl next", false)<br />
end),<br />
awful.key({}, "XF86AudioPrev", function()<br />
awful.util.spawn("playerctl previous", false)<br />
end),<br />
<br />
=== Steam Keyboard ===<br />
<br />
The on screen Steam Keyboard that can be activated by the [[Steam Controller]] appears to freeze after trying to type one character. This is because the client that is supposed to receive the input has to be focussed to receive it and the keyboard will wait until this input is successfully send. Manually focussing another client will send the input to this client and unfreeze the keyboard again until the next character is entered.<br />
<br />
The trick to getting the keyboard to work correctly is to prevent it ever receiving focus. Add the following signal to your config (or merge with an existing client focus signal):<br />
<br />
client.connect_signal("focus", function(c)<br />
if awful.rules.match(c, { name = "^Steam Keyboard$" }) then<br />
awful.client.focus.history.previous()<br />
end<br />
end)<br />
<br />
This will return the focus to the last client whenever the keyboard receives focus. As the input to the keyboard is handled by the [[Steam]] client and as such doesn't need focus, inputting text will now work correctly.<br />
<br />
==Troubleshooting==<br />
<br />
=== Debugging rc.lua ===<br />
<br />
{{Pkg|xorg-server-xephyr}} allows you to run X nested in another X's client window. This allows you to debug rc.lua without breaking your current desktop. Start by copying rc.lua into a new file (e.g. rc.lua.new), and modify it as needed. Then run new instance of awesome in Xephyr, supplying rc.lua.new as a config file like this:<br />
<br />
$ Xephyr :1 -ac -br -noreset -screen 1152x720 &<br />
$ DISPLAY=:1.0 awesome -c ~/.config/awesome/rc.lua.new<br />
<br />
The advantage of this approach is that if you introduce bugs you do not break your current awesome desktop, potentially crashing X apps and losing work. Once you are happy with the new configuration, copy rc.lua.new to rc.lua and restart awesome.<br />
<br />
==== awmtt ====<br />
<br />
{{AUR|awmtt}} (Awesome WM Testing Tool) is an easy to use wrapper script around Xephyr. By default, it will use ~/.config/awesome/rc.lua.test. If it cannot find that test file, it will use your actual rc.lua. You can also specify the location of the configuration file you want to test:<br />
<br />
$ awmtt start -C ~/.config/awesome/rc.lua.new<br />
<br />
When you are done testing, close the window with:<br />
<br />
$ awmtt stop<br />
<br />
Or immediately see the changes you are doing to the configuration file by issuing:<br />
<br />
$ awmtt restart<br />
<br />
=== Log Files ===<br />
<br />
If you are using [[LightDM]], awesome will log errors to `$HOME/.xsession-errors`. If you use {{ic|.xinitrc}} to start awesome, the entry "Where are logs, error messages or something?" in [https://awesomewm.org/apidoc/documentation/90-FAQ.md.html the FAQ] may be a helpful resource.<br />
<br />
=== Mod4 key ===<br />
<br />
{{Merge|Configuring_keyboard_layouts_in_X}}<br />
<br />
Awesome recommends to remap {{ic|mod4}}, which by default should be '''Win key'''. If for some reason it is not mapped to {{ic|mod4}}, use [[xmodmap]] to find out what is. To change the mapping, use {{ic|xev}} to find the keycode and name of the key to be mapped. Then add something like the following to {{ic|~/.xinitrc}} <br />
<br />
xmodmap -e "keycode 115 = Super_L" -e "add mod4 = Super_L"<br />
exec awesome<br />
<br />
The problem in this case is that some xorg installations recognize keycode 115, but incorrectly as the 'Select' key. The above command explictly remaps keycode 115 to the correct 'Super_L' key.<br />
<br />
To remap {{ic|mod4}} with {{ic|setxkbmap}} (conflict with {{ic|xmodmap}}) see:<br />
<br />
tail -50 /usr/share/X11/xkb/rules/evdev<br />
<br />
To set the caps lock key as {{ic|mod4}} add the following to {{ic|~/.xinitrc}}:<br />
<br />
setxkbmap -option caps:hyper<br />
<br />
==== Mod4 key vs. IBM ThinkPad users ====<br />
<br />
{{Style|Duplicate section}}<br />
<br />
IBM ThinkPads, IBM Model M's and Chromebooks do not come equipped with a Window key (although Lenovo have changed this tradition on their ThinkPads). As of writing, the Alt key is not used in command combinations by the default rc.lua (refer to the Awesome wiki for a table of commands), which allows it be used as a replacement for the Super/Mod4/Win key. To do this, edit your rc.lua and replace:<br />
<br />
modkey = "Mod4"<br />
<br />
by:<br />
<br />
modkey = "Mod1"<br />
<br />
Note: Awesome does a have a few commands that make use of Mod4 plus a single letter. Changing Mod4 to Mod1/Alt could cause overlaps for some key combinations. The small amount of instances where this happens can be changed in the rc.lua file.<br />
<br />
If you have a Chromebook or do not like to change the Awesome standards, you might like to remap a key. For instance the caps lock key is rather useless (for me) adding the following contents to ~/.Xmodmap<br />
<br />
clear lock<br />
add mod4 = Caps_Lock<br />
<br />
and run {{ic|xmodmap ~/.Xmodmap}} to (re)load the file.<br />
This will change the caps lock key into the mod4 key and works nicely with the standard awesome settings. In addition, if needed, it provides the mod4 key to other X-programs as well.<br />
<br />
Recent updates of xorg related packages break mentioned remapping the second line can be replaced by (tested on a DasKeyboard and IBM Model M and xorg-server 1.14.5-2):<br />
<br />
keysym Caps_Lock = Super_L Caps_Lock<br />
<br />
=== Fix Java (GUI appears gray only) ===<br />
<br />
{{Merge|Java}}<br />
<br />
See [http://awesome.naquadah.org/wiki/Problems_with_Java awesome wiki]{{Dead link|2018|4|11}} and [https://bbs.archlinux.org/viewtopic.php?pid=450870].<br />
<br />
=== Eclipse: cannot resize/move main window ===<br />
<br />
If you get stuck and cannot move or resize the main window (using mod4 + left/right mouse button) edit the {{ic|workbench.xml}} and set fullscreen/maximized to false (if set) and reduce the width and height to numbers smaller than your single screen desktop area.<br />
<br />
{{ic|workbench.xml}} can be found in {{ic|''eclipse_workspace''/.metadata/.plugins/org.eclipse.ui.workbench/}}. Edit the line:<br />
<br />
<window height&#61;"xx" maximized&#61;"true" width&#61;"xx" x&#61;"xx" y&#61;"xx"<br />
<br />
=== Netbeans: code-prediction appears on wrong screen ===<br />
<br />
If you have two displays and use code-prediction (Ctrl + Space) in Netbeans, the code-predictions might appear on the wrong screen.<br />
This fixed it for me:<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
awful.rules.rules = {<br />
...<br />
{<br />
rule_matches = { -- Fix Netbeans<br />
class = {<br />
"sun-awt-X11-XWindowPeer", "NetBeans IDE 8.2"<br />
},<br />
name = {<br />
"win1"<br />
}<br />
}, properties = { screen = 1 } -- even with screen 1 here, this still works on the seccond screen, too (don't know why).<br />
},<br />
...<br />
<br />
}<br />
}}<br />
<br />
=== IntelliJ: menus appear on incorrect position, some windows don't open ===<br />
<br />
See [https://github.com/awesomeWM/awesome/issues/2204 GitHub issue #2204].<br />
<br />
This fixed it for me:<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
clientbuttons_jetbrains = gears.table.join(<br />
awful.button({ modkey }, 1, awful.mouse.client.move),<br />
awful.button({ modkey }, 3, awful.mouse.client.resize)<br />
)<br />
<br />
...<br />
<br />
awful.rules.rules = {<br />
...<br />
{<br />
rule = {<br />
class = "jetbrains-.*",<br />
}, properties = { focus = true, buttons = clientbuttons_jetbrains }<br />
},<br />
{<br />
rule = {<br />
class = "jetbrains-.*",<br />
name = "win.*"<br />
}, properties = { titlebars_enabled = false, focusable = false, focus = true, floating = true, placement = awful.placement.restore }<br />
},<br />
...<br />
}<br />
}}<br />
<br />
=== scrot: Cannot take a mouse selected screenshot with keyboard shortcuts===<br />
<br />
When using [[w:Scrot|scrot]], you may have problems at assigning a keyboard shortcut to the mouse selection option (formally {{ic|scrot -s}}). To fix it, add the following line to your {{ic|rc.lua}}:<br />
<br />
awful.key( { modkey, }, <shortcut>, nil, function () awful.spawn("scrot -s") end)<br />
<br />
Note that {{ic|nil}} is passed to the {{ic|press}} argument of {{ic|awful.key}}. Instead, the callback function is passed as fourth argument, which is the argument named {{ic|release}}.<br />
<br />
=== YouTube: fullscreen appears in background ===<br />
<br />
If YouTube videos appear underneath your web browser when in fullscreen mode, or underneath the panel with controls hidden, add this to {{ic|rc.lua}}<br />
<br />
{ rule = { instance = "plugin-container" },<br />
properties = { floating = true } },<br />
<br />
With Chromium add<br />
<br />
{ rule = { instance = "exe" },<br />
properties = { floating = true } },<br />
<br />
or:<br />
<br />
{ rule = { role = "_NET_WM_STATE_FULLSCREEN" },<br />
properties = { floating = true } },<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1085494#p1085494].<br />
<br />
=== Prevent the mouse scroll wheel from changing tags ===<br />
In your rc.lua, change the Mouse Bindings section to the following;<br />
-- {{{ Mouse bindings<br />
root.buttons(awful.util.table.join(<br />
awful.button({ }, 3, function () mymainmenu:toggle() end)))<br />
-- }}}<br />
<br />
=== Starting console clients on specific tags ===<br />
<br />
{{Accuracy|Useless without reasoning, probably related to instance names}}<br />
<br />
It does not work when the console application is invoked from a GTK terminal (e.g. LXTerminal). [[URxvt]] is known to work.<br />
<br />
=== Duplicate menu-entries generated by Xdg-menu ===<br />
<br />
Xdg-menu will generate duplicate entries if you copy desktop-files from /usr/share/applications to ~/.local/share/applications even though it might be preferable to simply override the originals, for example using a different theme for a specific application. One solution to the problem is to filter the generated output trough awk to remove entries with a name identical to the previous entry.<br />
<br />
xdg_menu --format awesome --root-menu /etc/xdg/menus/arch-applications.menu | awk -F, '{if (a!=$1) print $a; a=$1}' >~/.config/awesome/archmenu.lua<br />
<br />
=== Some Shortcuts not Working in Xfce4 overlapping Keys ===<br />
Check your <br />
$ xfce4-keyboard-settings<br />
<br />
for Overlapping keys like "Super L" or Key Combinations which should be run by Awesome<br />
<br />
== See also ==<br />
<br />
* https://awesomewm.org/apidoc/documentation/90-FAQ.md.html - FAQ<br />
* http://www.lua.org/pil/ - Programming in Lua (first edition)<br />
* https://awesomewm.org/ - The official awesome website<br />
* https://bbs.archlinux.org/viewtopic.php?id=88926 - share your awesome!</div>Comruminohttps://wiki.archlinux.org/index.php?title=Awesome&diff=564139Awesome2019-01-20T22:20:25Z<p>Comrumino: /* Extensions */ Removed dead links and provided improved version compatibility information to make the information more current</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Dynamic WMs]]<br />
[[Category:Tiling WMs]]<br />
[[cs:Awesome]]<br />
[[es:Awesome]]<br />
[[fr:Awesome3]]<br />
[[it:Awesome]]<br />
[[ja:Awesome]]<br />
[[ko:Awesome]]<br />
[[ru:Awesome]]<br />
[[sv:Awesome]]<br />
[[zh-hans:Awesome]]<br />
{{Related articles start}}<br />
{{Related|Window manager}}<br />
{{Related|Comparison of tiling window managers}}<br />
{{Related|Desktop environment}}<br />
{{Related|Display manager}}<br />
{{Related|File manager functionality}}<br />
{{Related|Xdg-menu}}<br />
{{Related articles end}}<br />
From the [https://awesomewm.org/ awesome website]:<br />
<br />
:[[Wikipedia:awesome (window manager)|awesome]] is a highly configurable, next generation framework [[window manager]] for [[Xorg]]. It is very fast and extensible [..]. It is primarily targeted at power users, developers and any people dealing with every day computing tasks and who want to have fine-grained control on its graphical environment.<br />
<br />
{{Out of date|This article references multiple pages of the [https://awesome.naquadah.org/wiki old awesome wiki], that went offline in December 2016.[https://www.reddit.com/r/awesomewm/comments/5k9vob/what_happened_to_the_wiki/] }}<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{pkg|awesome}} package. The development version is {{AUR|awesome-git}}, which is considered unstable and may have a different configuration API.<br />
<br />
== Starting ==<br />
<br />
Run {{ic|awesome}} with [[xinit]]. To use the included [[xsession]] file, see [[Display manager]].<br />
<br />
=== KDM ===<br />
<br />
Create as root:<br />
<br />
{{hc|/usr/share/apps/kdm/sessions/awesome.desktop|2=<br />
[Desktop Entry]<br />
Name=Awesome<br />
Comment=Tiling Window Manager<br />
Type=Application<br />
Exec=/usr/bin/awesome<br />
TryExec=/usr/bin/awesome<br />
}}<br />
<br />
=== With GNOME ===<br />
<br />
You can set up [[GNOME]] to use awesome as the visual interface, but have GNOME work in the background. See [http://awesome.naquadah.org/wiki/Quickly_Setting_up_Awesome_with_Gnome awesome wiki]{{Dead link|2018|4|11}} for details.<br />
<br />
=== XFCE ===<br />
<br />
See [[Xfce#Use a different window manager]].<br />
<br />
== Configuration ==<br />
<br />
The lua based configuration file is at {{Ic|~/.config/awesome/rc.lua}}.<br />
<br />
=== Creating the configuration file ===<br />
<br />
First, run the following to create the directory needed in the next step:<br />
<br />
$ mkdir -p ~/.config/awesome/<br />
<br />
Whenever compiled, awesome will attempt to use whatever custom settings are contained in ~/.config/awesome/rc.lua. This file is not created by default, so we must copy the template file first:<br />
<br />
$ cp /etc/xdg/awesome/rc.lua ~/.config/awesome/<br />
<br />
The API for the configuration often changes when awesome updates. So, remember to repeat the command above when you get something strange with awesome, or you want to modify the configuration.<br />
<br />
For more information about configuring awesome, check out the [https://awesomewm.org/apidoc/documentation/90-FAQ.md.html#Configuration configuration section at awesome docs]<br />
<br />
==== Examples ====<br />
<br />
{{Note|The API for awesome configuration changes regularly, so you will likely have to modify any file you download.}}<br />
<br />
Some good examples of rc.lua would be as follows:<br />
<br />
* [https://github.com/setkeh/Awesome Setkeh's Awesome Configuration]<br />
* [http://awesome.naquadah.org/wiki/User_Configuration_Files Collection of user configurations on the awesome homepage]{{Dead link|2018|4|11}}<br />
* [https://github.com/copycat-killer/awesome-copycats User configuration that supports different themes, including a status bar]<br />
<br />
=== Extensions ===<br />
<br />
Several extensions are available for awesome:<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | Extension<br />
! style="font-weight: bold;" | Functionality<br />
! style="font-weight: bold;" | Version<br />
|-<br />
|<br />
* [https://github.com/guotsuan/awesome-revelation Revelation]<br />
| Bring up a view of all opened clients<br />
| Awesome 3.5+<br />
|-<br />
|<br />
* [https://github.com/bioe007/awesome-shifty Shifty]<br />
| Dynamic tagging<br />
| Awesome 3.5<br />
|-<br />
|<br />
* [https://awesomewm.org/apidoc/libraries/naughty.html Naughty]<br />
| Pop-up notifications<br />
| Awesome 3.5+<br />
|-<br />
| <br />
* [https://github.com/vicious-widgets/vicious Vicious]<br />
* [https://github.com/hoelzro/obvious Obvious]<br />
* [https://code.google.com/archive/p/bashets/ Bashets]<br />
| Additional [https://awesomewm.org/recipes/ widgets]<br />
| Awesome 3.5<br />
|-<br />
|}<br />
<br />
=== Autostart ===<br />
<br />
To autorun programs, create a shell script via <br />
$ touch ~/.config/awesome/autorun.sh<br />
and make it executable by <br />
$ chmod +x ~/.config/awesome/autorun.sh<br />
Open {{ic|autorun.sh}} in an editor and insert the following:<br />
{{hc|head=.config/awesome/autorun.sh|output=<br />
#!/usr/bin/env bash<br />
<br />
function run {<br />
if ! pgrep $1 ;<br />
then<br />
$@&<br />
fi<br />
}<br />
}}<br />
<br />
To add programs to autostart, simply append {{ic|run program [some arguments]}} to {{ic|autorun.sh}}. The {{ic|run}} function checks whether there already is an instance of {{ic|program}} running and only runs {{ic|program}} if there is none. You can check your {{ic|autorun.sh}} by running it:<br />
<br />
$ ~/.config/awesome/autorun.sh<br />
<br />
If everything is fine, add the following line to your {{ic|rc.lua}}:<br />
<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
...<br />
awful.spawn.with_shell("~/.config/awesome/autorun.sh")<br />
...<br />
}}<br />
<br />
=== Changing keyboard layout===<br />
There is multiple ways to configure keyboard layers. In the default config awesome already has the layout widget activated - but it wont show up until there is a choice. To set multiple layers temporary, run<br />
<br />
$ setxkbmap -layout "us,de"<br />
<br />
The awesome keyboard widget should appear, clicking on it should toggle the layout. If you want a keycombo to change the layout, you may append {{ic|-option "grp:alt_shift_toggle"}}. This for example will let you change the layout by pressing {{ic|Shift+Alt}}. So the complete command would be:<br />
<br />
$ setxkbmap -layout "us,de" -option "grp:alt_shift_toggle"<br />
<br />
Or you can use Awesome itself to switch(from v.4). Add the following line in the keybindings section of rc.lua:<br />
<br />
awful.key({ "Shift" }, "Alt_L", function ) mykeyboardlayout.next_layout(); end) <br />
awful.key({ "Mod1" }, "Shift_L", function ) mykeyboardlayout.next_layout(); end)<br />
<br />
This requires you to set up the keyboard layouts you want to be able to switch between either by the setxkbmap command or in X configuration files.<br />
<br />
Once you've found the appropriate command to setup your layouts, add it to [[#Autostart]].<br />
<br />
Alternatively, see [[Keyboard configuration in Xorg]].<br />
<br />
=== Theming ===<br />
<br />
[https://awesomewm.org/apidoc/libraries/beautiful.html Beautiful] is a Lua library that allows you to theme awesome using an external file, it becomes very easy to dynamically change your whole awesome colours and wallpaper without changing your {{ic|rc.lua}}. <br />
<br />
The default theme is at {{ic|/usr/share/awesome/themes/default}}. Copy it to {{ic|~/.config/awesome/themes/default}} and change {{ic|theme_path}} in {{ic|rc.lua}}. <br />
<br />
beautiful.init(awful.util.getdir("config") .. "/themes/default/theme.lua")<br />
<br />
See also [https://awesomewm.org/apidoc/libraries/beautiful.html] for additional theming options. To add a useless gap for example, add<br />
<br />
beautiful.useless_gap = 5<br />
<br />
At the bottom of the theming section in your {{ic|rc.lua}}.<br />
<br />
==== Wallpaper ====<br />
<br />
Beautiful can handle your wallpaper, thus you do not need to set it up in your {{ic|.xinitrc}} or {{ic|.xsession}} files. This allows you to have a specific wallpaper for each theme.<br />
<br />
With version 3.5 Awesome no longer provides a awsetbg command, instead it has a gears module. You can set your wallpaper inside {{ic|theme.lua}} with <br />
<br />
theme.wallpaper = "~/.config/awesome/themes/awesome-wallpaper.png" <br />
<br />
To load the wallpaper, make sure your {{ic|rc.lua}} contains<br />
<br />
beautiful.init("~/.config/awesome/themes/default/theme.lua")<br />
for s = 1, screen.count() do<br />
gears.wallpaper.maximized(beautiful.wallpaper, s, true)<br />
end<br />
<br />
For a random background image, add [https://gist.github.com/anonymous/37f3b1c58d6616cab756] to {{ic|rc.lua}} (v3.5+). To automatically fetch images from a given directory use [https://gist.github.com/anonymous/9072154f03247ab6e28c] instead.<br />
<br />
To simply specify the wallpaper in your {{ic|rc.lua}}, add the following line to the theming section:<br />
<br />
beautiful.wallpaper = awful.util.get_configuration_dir() .. "path/to/wallpaper.png"<br />
<br />
The optional {{ic|awful.util.get_configuration_dir()}} simply returns the path to your {{ic|rc.lua}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Hide / show wibox ===<br />
<br />
For awesome 4.0:<br />
<br />
awful.key({ modkey }, "b",<br />
function ()<br />
myscreen = awful.screen.focused()<br />
myscreen.mywibox.visible = not myscreen.mywibox.visible<br />
end,<br />
{description = "toggle statusbar"}<br />
),<br />
<br />
=== Screenshot ===<br />
<br />
See [[Extra keyboard keys]] to ensure the {{ic|PrtSc}} button is assigned correctly. Then install a [[Taking a screenshot|screen capturing program]] such as [[Taking a screenshot#scrot|scrot]]<br />
<br />
Add to the {{ic|globalkeys}} array:<br />
<br />
awful.key({ }, "Print", function () awful.util.spawn("scrot -e 'mv $f ~/screenshots/ 2>/dev/null'", false) end),<br />
<br />
This function saves screenshots inside {{ic|~/screenshots/}}, edit as needed.<br />
<br />
=== Removing window gaps ===<br />
<br />
As of awesome 3.4, it is possible to remove the small gaps between windows; in the ''awful.rules.rules'' table there is a ''properties'' section, add to it <br />
<br />
size_hints_honor = false<br />
<br />
=== Transparency ===<br />
<br />
See [[composite manager]].<br />
<br />
In awesome 3.5, window transparency can be set dynamically using signals. For example, {{ic|rc.lua}} could contain the following:<br />
<br />
client.connect_signal("focus", function(c)<br />
c.border_color = beautiful.border_focus<br />
c.opacity = 1<br />
end)<br />
client.connect_signal("unfocus", function(c)<br />
c.border_color = beautiful.border_normal<br />
c.opacity = 0.7<br />
end)<br />
<br />
==== Conky ====<br />
{{Merge|Conky}}<br />
<br />
If using conky, you must set it to create its own window instead of using the desktop. To do so, edit {{ic|~/.conkyrc}} to contain<br />
<br />
own_window yes<br />
own_window_transparent yes<br />
own_window_type desktop<br />
<br />
Otherwise strange behavior may be observed, such as all windows becoming fully transparent. Note also that since conky will be creating a transparent window on your desktop, any actions defined in awesome's {{ic|rc.lua}} for the desktop will not work where conky is.<br />
<br />
==== wiboxes ====<br />
<br />
As of Awesome 3.1, there is built-in pseudo-transparency for wiboxes. To enable it, append 2 hexadecimal digits to the colors in your theme file ({{ic|~/.config/awesome/themes/default}}, which is usually a copy of {{ic|/usr/share/awesome/themes/default}}), like shown here:<br />
<br />
bg_normal = #000000AA<br />
<br />
where "AA" is the transparency value.<br />
<br />
To change transparency for the actual selected window by pressing {{ic|Modkey + PgUp/PgDown}} you can also use {{Pkg|transset-df}} and the following modification to your {{ic|rc.lua}}:<br />
<br />
globalkeys = awful.util.table.join(<br />
-- your keybindings<br />
[...]<br />
awful.key({ modkey }, "Next", function (c)<br />
awful.util.spawn("transset-df --actual --inc 0.1")<br />
end),<br />
awful.key({ modkey }, "Prior", function (c)<br />
awful.util.spawn("transset-df --actual --dec 0.1")<br />
end),<br />
-- Your other key bindings<br />
[...]<br />
)<br />
<br />
==== ImageMagick ====<br />
<br />
{{Merge|Composite manager}}<br />
<br />
You may have problems if you set your wallpaper with imagemagick's ''display'' command. It does not work well with xcompmgr. Please note that awsetbg may be using ''display'' if it does not have any other options. Installing habak, feh, hsetroot or whatever should fix the problem (''grep -A 1 wpsetters /usr/bin/awsetbg'' to see your options).<br />
<br />
=== Passing content to widgets with awesome-client ===<br />
<br />
You can easily send text to an awesome widget. Just create a new widget:<br />
<br />
mywidget = widget({ type = "textbox", name = "mywidget" })<br />
mywidget.text = "initial text"<br />
<br />
To update the text from an external source, use awesome-client:<br />
<br />
echo -e 'mywidget.text = "new text"' | awesome-client<br />
<br />
Do not forget to add the widget to your wibox.<br />
<br />
=== Using a different panel with awesome ===<br />
<br />
If you like awesome's lightweightness and functionality but do not like the way its default panel looks, you can install a different panel, for example {{Pkg|xfce4-panel}}.<br />
<br />
Then add it to the [[#Autostart|autorun section]] of your {{ic|rc.lua}}. You may also comment out the section which creates wiboxes for each screen (starting from {{ic|1=mywibox[s] = awful.wibox({ position = "top", screen = s })}}) but it is not necessary. Do not forget to check your {{ic|rc.lua}} for errors by typing:<br />
<br />
$ awesome -k rc.lua<br />
<br />
You should also change your {{ic|''modkey''+R}} keybinding, in order to start some other application launcher instead of built in awesome. See [[List of applications#Application launchers]] for examples. Do not forget to add:<br />
<br />
{{bc|<nowiki><br />
properties = { floating = true } },<br />
{ rule = { instance = "$yourapplicationlauncher" },<br />
</nowiki>}}<br />
<br />
to your {{ic|rc.lua}}.<br />
<br />
=== Application directories in menubar ===<br />
<br />
{{Pkg|awesome}} includes [https://awesomewm.org/apidoc/libraries/menubar.html menubar]. By default, pressing {{ic|''Mod''+p}} will open a dmenu-like applications menu at the top of the screen. However, this menu only searches for {{ic|.desktop}} files in {{ic|/usr/share/applications}} and {{ic|/usr/local/share/applications}}. <br />
<br />
To change this, add the following line to {{ic|rc.lua}}, ideally, under ''Menubar configuration'':<br />
<br />
app_folders = { "/usr/share/applications/", "~/.local/share/applications/" }<br />
<br />
Note that the {{ic|.desktop}} files are re-read each time awesome starts, thereby slowing down the startup. If you prefer other means of launching programs, the menubar can be disabled in {{ic|rc.lua}} by removing {{ic|local menubar &#61; require("menubar")}} and other references to the {{ic|menubar}} variable.<br />
<br />
=== Pop-up menus ===<br />
<br />
{{Style|Duplicate section?}}<br />
<br />
There is a simple menu by default in awesome 3, simplifying custom menus. [https://awesomewm.org/apidoc/libraries/awful.menu.html] If you want a freedesktop.org menu, you could take a look at ''[https://github.com/copycat-killer/awesome-freedesktop awesome-freedesktop]''.<br />
<br />
=== Applications menu ===<br />
<br />
If you prefer to see a more traditional applications menu when you click on the Awesome icon, or right-click on an empty area of the desktop, you can follow the instructions in [[Xdg-menu#Awesome]]. However this menu is not updated when you add or remove programs. So, be sure to run the command to update your menu. It may look something like:<br />
<br />
xdg_menu --format awesome --root-menu /etc/xdg/menus/arch-applications.menu >~/.config/awesome/archmenu.lua<br />
<br />
=== Titlebars ===<br />
<br />
It is easy to enable titlebars in awesome by simply setting the variable titlebars_enabled to true in the config file. However, you may want to be able to toggle the titlebar on or off. You can do this by simply adding something like this to your key bindings:<br />
<br />
awful.key({ modkey, "Control" }, "t",<br />
function (c)<br />
-- toggle titlebar<br />
awful.titlebar.toggle(c)<br />
end)<br />
<br />
Then you may want to initially hide the titlebars. To do that just add this immediately after the title bar is created:<br />
<br />
awful.titlebar.hide(c)<br />
<br />
=== Battery notification ===<br />
<br />
See [http://bpdp.blogspot.be/2013/06/battery-warning-notification-for.html this blog post] for a simple battery notification to add to {{ic|rc.lua}}. Note that it needs ''naughty'' for the notifications (installed by default in version 3.5). Other examples are available at [https://awesome.naquadah.org/wiki/Gigamo_Battery_Widget#Simple_modular_version_for_3.4 awesome wiki].{{Dead link|2018|4|10}}<br />
<br />
4/10/2018: The above mentioned wiki no longer exists. [https://www.reddit.com/r/awesomewm/comments/5k9vob/what_happened_to_the_wiki/ (Reddit comment: What happened to the wiki?)]<br />
<br />
From the linked Reddit comment:<br />
<br />
'''Workaround:'''<br />
<br />
For those still interested in it's content: [https://github.com/gutierri/awesomewm-wiki-dump/tree/master/markdown https://github.com/gutierri/awesomewm-wiki-dump/tree/master/markdown] has a partial markdown conversion of the old wiki (and the raw dump in xml format too).<br />
<br />
[https://github.com/gutierri/awesomewm-wiki-dump/blob/master/markdown/Acpitools-based_battery_widget.md Here] is the only Battery widget from the partial wiki. It is based on [[ACPI_modules|ACPI]] and written for version 3.5. I am not reproducing it here b/c there may be additional steps to get it working.<br />
<br />
<br />
'''NOTE: This partial wiki only covers versions up to 3.x'''<br />
<br />
=== Media Controls ===<br />
<br />
It is possible to control both volume and media playback via a combination of amixer (available via the {{pkg|alsa-utils}} package) and {{Pkg|playerctl}}. The following can be added to the relevant key binding section of your rc.lua configuration file:<br />
<br />
-- Volume Keys<br />
awful.key({}, "XF86AudioLowerVolume", function ()<br />
awful.util.spawn("amixer -q -D pulse sset Master 5%-", false)<br />
end),<br />
awful.key({}, "XF86AudioRaiseVolume", function ()<br />
awful.util.spawn("amixer -q -D pulse sset Master 5%+", false)<br />
end),<br />
awful.key({}, "XF86AudioMute", function ()<br />
awful.util.spawn("amixer -D pulse set Master 1+ toggle", false)<br />
end),<br />
-- Media Keys<br />
awful.key({}, "XF86AudioPlay", function()<br />
awful.util.spawn("playerctl play-pause", false)<br />
end),<br />
awful.key({}, "XF86AudioNext", function()<br />
awful.util.spawn("playerctl next", false)<br />
end),<br />
awful.key({}, "XF86AudioPrev", function()<br />
awful.util.spawn("playerctl previous", false)<br />
end),<br />
<br />
=== Steam Keyboard ===<br />
<br />
The on screen Steam Keyboard that can be activated by the [[Steam Controller]] appears to freeze after trying to type one character. This is because the client that is supposed to receive the input has to be focussed to receive it and the keyboard will wait until this input is successfully send. Manually focussing another client will send the input to this client and unfreeze the keyboard again until the next character is entered.<br />
<br />
The trick to getting the keyboard to work correctly is to prevent it ever receiving focus. Add the following signal to your config (or merge with an existing client focus signal):<br />
<br />
client.connect_signal("focus", function(c)<br />
if awful.rules.match(c, { name = "^Steam Keyboard$" }) then<br />
awful.client.focus.history.previous()<br />
end<br />
end)<br />
<br />
This will return the focus to the last client whenever the keyboard receives focus. As the input to the keyboard is handled by the [[Steam]] client and as such doesn't need focus, inputting text will now work correctly.<br />
<br />
==Troubleshooting==<br />
<br />
=== Debugging rc.lua ===<br />
<br />
{{Pkg|xorg-server-xephyr}} allows you to run X nested in another X's client window. This allows you to debug rc.lua without breaking your current desktop. Start by copying rc.lua into a new file (e.g. rc.lua.new), and modify it as needed. Then run new instance of awesome in Xephyr, supplying rc.lua.new as a config file like this:<br />
<br />
$ Xephyr :1 -ac -br -noreset -screen 1152x720 &<br />
$ DISPLAY=:1.0 awesome -c ~/.config/awesome/rc.lua.new<br />
<br />
The advantage of this approach is that if you introduce bugs you do not break your current awesome desktop, potentially crashing X apps and losing work. Once you are happy with the new configuration, copy rc.lua.new to rc.lua and restart awesome.<br />
<br />
==== awmtt ====<br />
<br />
{{AUR|awmtt}} (Awesome WM Testing Tool) is an easy to use wrapper script around Xephyr. By default, it will use ~/.config/awesome/rc.lua.test. If it cannot find that test file, it will use your actual rc.lua. You can also specify the location of the configuration file you want to test:<br />
<br />
$ awmtt start -C ~/.config/awesome/rc.lua.new<br />
<br />
When you are done testing, close the window with:<br />
<br />
$ awmtt stop<br />
<br />
Or immediately see the changes you are doing to the configuration file by issuing:<br />
<br />
$ awmtt restart<br />
<br />
=== Log Files ===<br />
<br />
If you are using [[LightDM]], awesome will log errors to `$HOME/.xsession-errors`. If you use {{ic|.xinitrc}} to start awesome, the entry "Where are logs, error messages or something?" in [https://awesomewm.org/apidoc/documentation/90-FAQ.md.html the FAQ] may be a helpful resource.<br />
<br />
=== Mod4 key ===<br />
<br />
{{Merge|Configuring_keyboard_layouts_in_X}}<br />
<br />
Awesome recommends to remap {{ic|mod4}}, which by default should be '''Win key'''. If for some reason it is not mapped to {{ic|mod4}}, use [[xmodmap]] to find out what is. To change the mapping, use {{ic|xev}} to find the keycode and name of the key to be mapped. Then add something like the following to {{ic|~/.xinitrc}} <br />
<br />
xmodmap -e "keycode 115 = Super_L" -e "add mod4 = Super_L"<br />
exec awesome<br />
<br />
The problem in this case is that some xorg installations recognize keycode 115, but incorrectly as the 'Select' key. The above command explictly remaps keycode 115 to the correct 'Super_L' key.<br />
<br />
To remap {{ic|mod4}} with {{ic|setxkbmap}} (conflict with {{ic|xmodmap}}) see:<br />
<br />
tail -50 /usr/share/X11/xkb/rules/evdev<br />
<br />
To set the caps lock key as {{ic|mod4}} add the following to {{ic|~/.xinitrc}}:<br />
<br />
setxkbmap -option caps:hyper<br />
<br />
==== Mod4 key vs. IBM ThinkPad users ====<br />
<br />
{{Style|Duplicate section}}<br />
<br />
IBM ThinkPads, IBM Model M's and Chromebooks do not come equipped with a Window key (although Lenovo have changed this tradition on their ThinkPads). As of writing, the Alt key is not used in command combinations by the default rc.lua (refer to the Awesome wiki for a table of commands), which allows it be used as a replacement for the Super/Mod4/Win key. To do this, edit your rc.lua and replace:<br />
<br />
modkey = "Mod4"<br />
<br />
by:<br />
<br />
modkey = "Mod1"<br />
<br />
Note: Awesome does a have a few commands that make use of Mod4 plus a single letter. Changing Mod4 to Mod1/Alt could cause overlaps for some key combinations. The small amount of instances where this happens can be changed in the rc.lua file.<br />
<br />
If you have a Chromebook or do not like to change the Awesome standards, you might like to remap a key. For instance the caps lock key is rather useless (for me) adding the following contents to ~/.Xmodmap<br />
<br />
clear lock<br />
add mod4 = Caps_Lock<br />
<br />
and run {{ic|xmodmap ~/.Xmodmap}} to (re)load the file.<br />
This will change the caps lock key into the mod4 key and works nicely with the standard awesome settings. In addition, if needed, it provides the mod4 key to other X-programs as well.<br />
<br />
Recent updates of xorg related packages break mentioned remapping the second line can be replaced by (tested on a DasKeyboard and IBM Model M and xorg-server 1.14.5-2):<br />
<br />
keysym Caps_Lock = Super_L Caps_Lock<br />
<br />
=== Fix Java (GUI appears gray only) ===<br />
<br />
{{Merge|Java}}<br />
<br />
See [http://awesome.naquadah.org/wiki/Problems_with_Java awesome wiki]{{Dead link|2018|4|11}} and [https://bbs.archlinux.org/viewtopic.php?pid=450870].<br />
<br />
=== Eclipse: cannot resize/move main window ===<br />
<br />
If you get stuck and cannot move or resize the main window (using mod4 + left/right mouse button) edit the {{ic|workbench.xml}} and set fullscreen/maximized to false (if set) and reduce the width and height to numbers smaller than your single screen desktop area.<br />
<br />
{{ic|workbench.xml}} can be found in {{ic|''eclipse_workspace''/.metadata/.plugins/org.eclipse.ui.workbench/}}. Edit the line:<br />
<br />
<window height&#61;"xx" maximized&#61;"true" width&#61;"xx" x&#61;"xx" y&#61;"xx"<br />
<br />
=== Netbeans: code-prediction appears on wrong screen ===<br />
<br />
If you have two displays and use code-prediction (Ctrl + Space) in Netbeans, the code-predictions might appear on the wrong screen.<br />
This fixed it for me:<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
awful.rules.rules = {<br />
...<br />
{<br />
rule_matches = { -- Fix Netbeans<br />
class = {<br />
"sun-awt-X11-XWindowPeer", "NetBeans IDE 8.2"<br />
},<br />
name = {<br />
"win1"<br />
}<br />
}, properties = { screen = 1 } -- even with screen 1 here, this still works on the seccond screen, too (don't know why).<br />
},<br />
...<br />
<br />
}<br />
}}<br />
<br />
=== IntelliJ: menus appear on incorrect position, some windows don't open ===<br />
<br />
See [https://github.com/awesomeWM/awesome/issues/2204 GitHub issue #2204].<br />
<br />
This fixed it for me:<br />
{{hc|head=.config/awesome/rc.lua|output=<br />
clientbuttons_jetbrains = gears.table.join(<br />
awful.button({ modkey }, 1, awful.mouse.client.move),<br />
awful.button({ modkey }, 3, awful.mouse.client.resize)<br />
)<br />
<br />
...<br />
<br />
awful.rules.rules = {<br />
...<br />
{<br />
rule = {<br />
class = "jetbrains-.*",<br />
}, properties = { focus = true, buttons = clientbuttons_jetbrains }<br />
},<br />
{<br />
rule = {<br />
class = "jetbrains-.*",<br />
name = "win.*"<br />
}, properties = { titlebars_enabled = false, focusable = false, focus = true, floating = true, placement = awful.placement.restore }<br />
},<br />
...<br />
}<br />
}}<br />
<br />
=== scrot: Cannot take a mouse selected screenshot with keyboard shortcuts===<br />
<br />
When using [[w:Scrot|scrot]], you may have problems at assigning a keyboard shortcut to the mouse selection option (formally {{ic|scrot -s}}). To fix it, add the following line to your {{ic|rc.lua}}:<br />
<br />
awful.key( { modkey, }, <shortcut>, nil, function () awful.spawn("scrot -s") end)<br />
<br />
Note that {{ic|nil}} is passed to the {{ic|press}} argument of {{ic|awful.key}}. Instead, the callback function is passed as fourth argument, which is the argument named {{ic|release}}.<br />
<br />
=== YouTube: fullscreen appears in background ===<br />
<br />
If YouTube videos appear underneath your web browser when in fullscreen mode, or underneath the panel with controls hidden, add this to {{ic|rc.lua}}<br />
<br />
{ rule = { instance = "plugin-container" },<br />
properties = { floating = true } },<br />
<br />
With Chromium add<br />
<br />
{ rule = { instance = "exe" },<br />
properties = { floating = true } },<br />
<br />
or:<br />
<br />
{ rule = { role = "_NET_WM_STATE_FULLSCREEN" },<br />
properties = { floating = true } },<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1085494#p1085494].<br />
<br />
=== Prevent the mouse scroll wheel from changing tags ===<br />
In your rc.lua, change the Mouse Bindings section to the following;<br />
-- {{{ Mouse bindings<br />
root.buttons(awful.util.table.join(<br />
awful.button({ }, 3, function () mymainmenu:toggle() end)))<br />
-- }}}<br />
<br />
=== Starting console clients on specific tags ===<br />
<br />
{{Accuracy|Useless without reasoning, probably related to instance names}}<br />
<br />
It does not work when the console application is invoked from a GTK terminal (e.g. LXTerminal). [[URxvt]] is known to work.<br />
<br />
=== Duplicate menu-entries generated by Xdg-menu ===<br />
<br />
Xdg-menu will generate duplicate entries if you copy desktop-files from /usr/share/applications to ~/.local/share/applications even though it might be preferable to simply override the originals, for example using a different theme for a specific application. One solution to the problem is to filter the generated output trough awk to remove entries with a name identical to the previous entry.<br />
<br />
xdg_menu --format awesome --root-menu /etc/xdg/menus/arch-applications.menu | awk -F, '{if (a!=$1) print $a; a=$1}' >~/.config/awesome/archmenu.lua<br />
<br />
=== Some Shortcuts not Working in Xfce4 overlapping Keys ===<br />
Check your <br />
$ xfce4-keyboard-settings<br />
<br />
for Overlapping keys like "Super L" or Key Combinations which should be run by Awesome<br />
<br />
== See also ==<br />
<br />
* https://awesomewm.org/apidoc/documentation/90-FAQ.md.html - FAQ<br />
* http://www.lua.org/pil/ - Programming in Lua (first edition)<br />
* https://awesomewm.org/ - The official awesome website<br />
* https://bbs.archlinux.org/viewtopic.php?id=88926 - share your awesome!</div>Comrumino