https://wiki.archlinux.org/api.php?action=feedcontributions&user=JoshuaRLi&feedformat=atomArchWiki - User contributions [en]2024-03-29T09:08:49ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Network_configuration&diff=611107Network configuration2020-05-05T17:02:15Z<p>JoshuaRLi: Add iwd's builtin DHCP client.</p>
<hr />
<div>[[Category:Network configuration]]<br />
[[cs:Network configuration]]<br />
[[el:Network configuration]]<br />
[[es:Network configuration]]<br />
[[fr:Connexions reseau]]<br />
[[it:Network configuration]]<br />
[[ja:ネットワーク設定]]<br />
[[nl:Network configuration]]<br />
[[pl:Network configuration]]<br />
[[pt:Network configuration]]<br />
[[ru:Network configuration]]<br />
[[zh-hans:Network configuration]]<br />
[[zh-hant:Network configuration]]<br />
{{Related articles start}}<br />
{{Related|Network Debugging}}<br />
{{Related|Firewalls}}<br />
{{Related|Jumbo frames}}<br />
{{Related|Internet sharing}}<br />
{{Related|Router}}<br />
{{Related articles end}}<br />
<br />
This article describes how to configure network connections on [[Wikipedia:OSI layer 3|OSI layer 3]] and above. Medium-specifics are handled in the [[/Ethernet]] and [[/Wireless]] subpages.<br />
<br />
== Check the connection ==<br />
<br />
To troubleshoot a network connection, go through the following conditions and ensure that you meet them:<br />
<br />
# Your [[#Network interfaces|network interface]] is listed and enabled. Otherwise, check the device driver – see [[/Ethernet#Device driver]] or [[/Wireless#Device driver]].<br />
# You are connected to the network. The cable is plugged in or you are [[/Wireless|connected to the wireless LAN]].<br />
# Your network interface has an [[#IP addresses|IP address]].<br />
# Your [[#Routing table|routing table]] is correctly set up.<br />
# You can [[#Ping|ping]] a local IP address (e.g. your default gateway).<br />
# You can [[#Ping|ping]] a public IP address (e.g. {{ic|8.8.8.8}}, which is a Google DNS server and is a convenient address to test with).<br />
# [[Check if you can resolve domain names]] (e.g. {{ic|archlinux.org}}).<br />
<br />
=== Ping ===<br />
<br />
{{Expansion|Add or link explanation of common ping errors like Unknown hosts / Network is unreachable.}}<br />
<br />
[[Wikipedia:Ping (networking utility)|ping]] is used to test if you can reach a host.<br />
<br />
{{hc|$ ping www.example.com|2=<br />
PING www.example.com (93.184.216.34): 56(84) data bytes<br />
64 bytes from 93.184.216.34: icmp_seq=0 ttl=56 time=11.632 ms<br />
64 bytes from 93.184.216.34: icmp_seq=1 ttl=56 time=11.726 ms<br />
64 bytes from 93.184.216.34: icmp_seq=2 ttl=56 time=10.683 ms<br />
...<br />
}}<br />
<br />
For every reply you receive, the ping utility will print a line like the above. For more information see the {{man|8|ping}} manual. Note that computers can be configured not to respond to ICMP echo requests. [https://unix.stackexchange.com/questions/412446/how-to-disable-ping-response-icmp-echo-in-linux-all-the-time]<br />
<br />
If you receive no reply, this may be related to your default gateway or your Internet Service Provider (ISP). You can run a [[traceroute]] to further diagnose the route to the host.<br />
<br />
{{Note|If you receive an error like {{ic|ping: icmp open socket: Operation not permitted}} when executing ''ping'', try to re-install the {{Pkg|iputils}} package.}}<br />
<br />
== Network management ==<br />
<br />
To set up a network connection, go through the following steps:<br />
<br />
# Ensure your [[#Network interfaces|network interface]] is listed and enabled.<br />
# Connect to the network. Plug in the Ethernet cable or [[/Wireless|connect to the wireless LAN]].<br />
# Configure your network connection:<br />
#* [[#Static IP address|static IP address]]<br />
#* dynamic IP address: use [[#DHCP|DHCP]]<br />
<br />
{{Note|The installation image enables [[dhcpcd]] ({{ic|dhcpcd@''interface''.service}}) for [https://git.archlinux.org/archiso.git/tree/configs/releng/airootfs/etc/udev/rules.d/81-dhcpcd.rules wired network devices] on boot.}}<br />
<br />
=== net-tools ===<br />
<br />
Arch Linux has deprecated {{Pkg|net-tools}} in favor of {{Pkg|iproute2}}.[https://www.archlinux.org/news/deprecation-of-net-tools/]<br />
<br />
{| class="wikitable"<br />
! Deprecated command !! Replacement commands<br />
|-<br />
| arp || ip neighbor<br />
|-<br />
| [[Wikipedia:ifconfig|ifconfig]] || ip address, ip link<br />
|-<br />
| netstat || [[#Investigate sockets|ss]]<br />
|-<br />
| route || ip route<br />
|}<br />
<br />
For a more complete rundown, see [https://dougvitale.wordpress.com/2011/12/21/deprecated-linux-networking-commands-and-their-replacements/ this blog post].<br />
<br />
=== iproute2 ===<br />
<br />
[[Wikipedia:iproute2|iproute2]] is a dependency of the {{Pkg|base}} [[meta package]] and provides the {{man|8|ip}} command-line interface, used to manage [[#Network interfaces|network interfaces]], [[#IP addresses|IP addresses]] and the [[#Routing table|routing table]]. Be aware that configuration made using {{ic|ip}} will be lost after a reboot. For persistent configuration, you can use a [[network manager]] or automate ''ip'' commands using scripts and [[systemd#Writing unit files|systemd units]]. Also note that {{ic|ip}} commands can generally be abbreviated, for clarity they are however spelled out in this article.<br />
<br />
=== Network interfaces ===<br />
<br />
By default [[udev]] assigns names to your network interfaces using [http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names], which prefixes interfaces names with {{ic|en}} (wired/[[Wikipedia:Ethernet|Ethernet]]), {{ic|wl}} (wireless/WLAN), or {{ic|ww}} ([[Wikipedia:Wireless WAN|WWAN]]).<br />
<br />
{{Tip|To change interface names, see [[#Change interface name]] and [[#Revert to traditional interface names]].}}<br />
<br />
==== Listing network interfaces ====<br />
<br />
Both wired and wireless interface names can be found via {{ic|ls /sys/class/net}} or {{ic|ip link}}. Note that {{ic|lo}} is the [[Wikipedia:loop device|loop device]] and not used in making network connections.<br />
<br />
Wireless device names can also be retrieved using {{ic|iw dev}}. See also [[/Wireless#Get the name of the interface]].<br />
<br />
If your network interface is not listed, make sure your device driver was loaded successfully. See [[/Ethernet#Device driver]] or [[/Wireless#Device driver]].<br />
<br />
==== Enabling and disabling network interfaces ====<br />
<br />
Network interfaces can be enabled / disabled using {{ic|ip link set ''interface'' up{{!}}down}}, see {{man|8|ip-link}}.<br />
<br />
To check the status of the interface {{ic|eth0}}:<br />
<br />
{{hc|$ ip link show dev eth0|<br />
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast master br0 state DOWN mode DEFAULT qlen 1000<br />
...<br />
}}<br />
<br />
The {{ic|UP}} in {{ic|<BROADCAST,MULTICAST,UP,LOWER_UP>}} is what indicates the interface is up, not the later {{ic|state DOWN}}.<br />
<br />
{{Note|If your default route is through interface {{ic|eth0}}, taking it down will also remove the route, and bringing it back up will not automatically re-establish the default route. See [[#Routing table]] for re-establishing it.}}<br />
<br />
=== Static IP address ===<br />
<br />
A static IP address can be configured with most standard [[#Network managers|network managers]] and also [[dhcpcd]].<br />
<br />
To manually configure a static IP address, add an IP address as described in [[#IP addresses]], set up your [[#Routing table|routing table]] and [[Domain name resolution|configure your DNS servers]].<br />
<br />
=== IP addresses ===<br />
<br />
[[Wikipedia:IP address|IP addresses]] are managed using {{man|8|ip-address}}.<br />
<br />
List IP addresses:<br />
<br />
$ ip address show<br />
<br />
Add an IP address to an interface:<br />
<br />
# ip address add ''address/prefix_len'' broadcast + dev ''interface''<br />
<br />
:Note that:<br />
<br />
:* the address is given in [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR notation]] to also supply a [[Wikipedia:Subnetwork|subnet mask]]<br />
:* {{ic|+}} is a special symbol that makes {{ic|ip}} derive the [[Wikipedia:Broadcast address|broadcast address]] from the IP address and the subnet mask<br />
<br />
:{{Note|Make sure manually assigned IP addresses do not conflict with DHCP assigned ones.}}<br />
<br />
Delete an IP address from an interface:<br />
<br />
$ ip address del ''address/prefix_len'' dev ''interface''<br />
<br />
Delete all addresses matching a criteria, e.g. of a specific interface:<br />
<br />
$ ip address flush dev ''interface''<br />
<br />
{{Tip|IP addresses can be calculated with [http://jodies.de/ipcalc ipcalc] ({{Pkg|ipcalc}}).}}<br />
<br />
=== Routing table ===<br />
<br />
The [[Wikipedia:Routing table|routing table]] is used to determine if you can reach an IP address directly or what gateway (router) you should use. If no other route matches the IP address, the [[Wikipedia:Default gateway|default gateway]] is used.<br />
<br />
The routing table is managed using {{man|8|ip-route}}.<br />
<br />
''PREFIX'' is either a CIDR notation or {{ic|default}} for the default gateway.<br />
<br />
List IPv4 routes:<br />
<br />
$ ip route show<br />
<br />
List IPv6 routes:<br />
<br />
$ ip -6 route<br />
<br />
Add a route:<br />
<br />
# ip route add ''PREFIX'' via ''address'' dev ''interface''<br />
<br />
Delete a route:<br />
<br />
# ip route del ''PREFIX'' via ''address'' dev ''interface''<br />
<br />
=== DHCP ===<br />
<br />
A [[Wikipedia:Dynamic Host Configuration Protocol|Dynamic Host Configuration Protocol]] (DHCP) server provides clients with a dynamic IP address, the subnet mask, the default gateway IP address and optionally also with DNS name servers.<br />
<br />
To use DHCP you need a DHCP server in your network and a DHCP client:<br />
<br />
{| class="wikitable"<br />
! Client !! Package !! [[Archiso]] !! Note !! Systemd units<br />
|-<br />
| [[dhcpcd]] || {{Pkg|dhcpcd}} || {{Yes}} || DHCP, DHCPv6, ZeroConf, static IP || {{ic|dhcpcd.service}}, {{ic|dhcpcd@''interface''.service}}<br />
|-<br />
| [https://www.isc.org/downloads/dhcp/ ISC dhclient] || {{Pkg|dhclient}} || {{Yes}} || DHCP, DHCPv6, BOOTP, static IP || {{ic|dhclient@''interface''.service}}<br />
|}<br />
<br />
Alternatively, {{Pkg|iwd}} has a built-in DHCP client that can be used with some configuration: [[iwd#Enable built-in network configuration]]<br />
<br />
{{Note|<br />
* You should not run two DHCP clients simultaneously.<br />
* Instead of directly using a DHCP client you can also use a [[#Network managers|network manager]].<br />
}}<br />
<br />
{{Tip|You can check if a DHCP server is running with {{Pkg|dhcping}}.}}<br />
<br />
==== Servers ====<br />
<br />
{{Expansion|[[systemd-networkd]] has DHCP server support.}}<br />
<br />
{| class="wikitable"<br />
! Server !! Package !! IPv4 !! IPv6 !! GUI !! Interfaces !! Storage backend(s) !! Note<br />
|-<br />
| [[dhcpd]] || {{Pkg|dhcp}} || {{Yes}} || {{Yes}} || [https://github.com/Akkadius/glass-isc-dhcp Glass-ISC-DHCP] || ? || File || <br />
|-<br />
| [[dnsmasq]] || {{Pkg|dnsmasq}} || {{Yes}} || {{Yes}} || {{No}} || ? || File || Also DNS, PXE and TFTP<br />
|-<br />
| [[Kea]] || {{Pkg|kea}} || {{Yes}} || {{Yes}} || [https://github.com/isc-projects/kea-anterius Kea-Anterius (Experimental)] || REST, RADIUS and NETCONF || File, MySQL, PostgreSQL and Cassandra || Also DNS <br />
|}<br />
<br />
=== Network managers ===<br />
<br />
A network manager lets you manage network connection settings in so called network profiles to facilitate switching networks.<br />
<br />
{{Note|There are many solutions to choose from, but remember that all of them are mutually exclusive; you should not run two daemons simultaneously.}}<br />
<br />
{| class="wikitable"<br />
! Network manager || GUI || [[Archiso]] [https://git.archlinux.org/archiso.git/tree/configs/releng/packages.x86_64] || CLI tools || [[Wikipedia:Point-to-Point Protocol|PPP]] support <br>(e.g. 3G modem) || [[#DHCP|DHCP client]] || Systemd units <br />
|-<br />
! [[ConnMan]]<br />
| {{Y|8 unofficial}} || {{No}} || {{man|1|connmanctl}} || {{Yes}} (with {{aur|ofono}}) || internal || {{ic|connman.service}}<br />
|-<br />
! [[netctl]]<br />
| {{Y|2 unofficial}} || {{Yes}} || {{man|1|netctl}}, wifi-menu || {{Yes}} || [[dhcpcd]] or {{Pkg|dhclient}} || {{ic|netctl-ifplugd@''interface''.service}}, {{ic|netctl-auto@''interface''.service}}<br />
|-<br />
! [[NetworkManager]]<br />
| {{Yes}} || {{No}} || {{man|1|nmcli}}, {{man|1|nmtui}} || {{Yes}} || internal, [[dhcpcd]] or {{Pkg|dhclient}} || {{ic|NetworkManager.service}}<br />
|-<br />
! [[systemd-networkd]]<br />
| {{No}} || {{Yes}} ({{Pkg|base}}) || {{man|1|networkctl}} || {{No|https://github.com/systemd/systemd/issues/481}} || internal || {{ic|systemd-networkd.service}}, {{ic|systemd-resolved.service}}<br />
|-<br />
! [[Wicd]]<br />
| {{Yes}} || {{No}} || {{man|8|wicd-cli|url=https://manned.org/wicd-cli.8}}, {{man|8|wicd-curses|url=https://manned.org/wicd-curses.8}} || {{No}} || [[dhcpcd]] || {{ic|wicd.service}}<br />
|}<br />
<br />
There also is [[Wifi Radar]], a GUI application to manage WiFi networks with {{Pkg|wireless_tools}}, it however does not handle wired connections.<br />
<br />
== Set the hostname ==<br />
<br />
A [[Wikipedia:Hostname|hostname]] is a unique name created to identify a machine on a network, configured in {{ic|/etc/hostname}}—see {{man|5|hostname}} and {{man|7|hostname}} for details. The file can contain the system's domain name, if any. To set the hostname, [[textedit|edit]] {{ic|/etc/hostname}} to include a single line with {{ic|''myhostname''}}:<br />
<br />
{{hc|/etc/hostname|<br />
''myhostname''<br />
}}<br />
<br />
{{Tip|For advice on choosing a hostname, see [https://tools.ietf.org/html/rfc1178 RFC 1178].}}<br />
<br />
Alternatively, using {{man|1|hostnamectl}}:<br />
<br />
# hostnamectl set-hostname ''myhostname''<br />
<br />
To temporarily set the hostname (until reboot), use {{man|1|hostname}} from {{Pkg|inetutils}}:<br />
<br />
# hostname ''myhostname''<br />
<br />
To set the "pretty" hostname and other machine metadata, see {{man|5|machine-info}}.<br />
<br />
=== Local hostname resolution ===<br />
<br />
{{Expansion|Explain why you want a resolvable hostname, why {{ic|127.0.1.1}} is used (and why a static IP address should be preferred over it).}}<br />
<br />
The {{ic|myhostname}} [[Name Service Switch]] (NSS) module of [[systemd]] provides local hostname resolution without having to edit {{ic|/etc/hosts}} ({{man|5|hosts}}). It is enabled by default.<br />
<br />
Some clients may however still rely on {{ic|/etc/hosts}}, see [https://lists.debian.org/debian-devel/2013/07/msg00809.html] [https://bugzilla.mozilla.org/show_bug.cgi?id=87717#c55] for examples.<br />
<br />
To configure the hosts file, add the following lines to {{ic|/etc/hosts}}:<br />
<br />
127.0.0.1 localhost<br />
::1 localhost<br />
127.0.1.1 ''myhostname''.localdomain ''myhostname''<br />
<br />
{{Note|The order of hostnames/aliases that follow the IP address in {{ic|/etc/hosts}} is significant. The first string is considered the canonical hostname and may be appended with parent domains, where domain components are separated by a dot (ie. {{ic|.localdomain}} above). All following strings on the same line are considered aliases. See {{man|5|hosts}} for more info.}}<br />
<br />
As a result the system resolves to both entries: <br />
<br />
{{hc|$ getent hosts|<br />
127.0.0.1 localhost<br />
127.0.0.1 localhost<br />
127.0.1.1 ''myhostname''.localdomain ''myhostname''<br />
}}<br />
<br />
For a system with a permanent IP address, that permanent IP address should be used instead of {{ic|127.0.1.1}}.<br />
<br />
=== Local network hostname resolution ===<br />
<br />
To make your machine accessible in your LAN via its hostname you can:<br />
<br />
* edit the {{ic|/etc/hosts}} file for every device in your LAN, see {{man|5|hosts}}<br />
* set up a [[DNS server]] to resolve your hostname and make the LAN devices use it (e.g. via [[#DHCP]])<br />
* or the easy way: use a [[Wikipedia:Zero-configuration networking|Zero-configuration networking]] service:<br />
** Hostname resolution via Microsoft's [[Wikipedia:NetBIOS#Name service|NetBIOS]]. Provided by [[Samba]] on Linux. It only requires the {{ic|nmb.service}}. Computers running Windows, macOS, or Linux with {{ic|nmb}} running, will be able to find your machine.<br />
** Hostname resolution via [[Wikipedia:Multicast DNS|mDNS]]. Provided by either {{ic|nss_mdns}} with [[Avahi]] (see [[Avahi#Hostname resolution]] for setup details) or [[systemd-resolved]]. Computers running macOS, or Linux with Avahi or systemd-resolved running, will be able to find your machine. The older Win32 API does not support mDNS, which may prevent some older Windows applications from accessing your device.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Change interface name ===<br />
<br />
{{Note|When changing the naming scheme, do not forget to update all network-related configuration files and custom systemd unit files to reflect the change.}}<br />
<br />
You can change the device name by defining the name manually with an udev-rule. For example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="aa:bb:cc:dd:ee:ff", NAME="net1"<br />
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="ff:ee:dd:cc:bb:aa", NAME="net0"<br />
}}<br />
<br />
These rules will be applied automatically at boot.<br />
<br />
A couple of things to note:<br />
<br />
* To get the MAC address of each card, use this command: {{ic|cat /sys/class/net/''device_name''/address}}<br />
* Make sure to use the lower-case hex values in your udev rules. It does not like upper-case.<br />
<br />
If the network card has a dynamic MAC, you can use {{ic|DEVPATH}}, for example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", DEVPATH=="/devices/platform/wemac.*", NAME="int"<br />
SUBSYSTEM=="net", DEVPATH=="/devices/pci*/*1c.0/*/net/*", NAME="en"<br />
}}<br />
<br />
To get the {{ic|DEVPATH}} of all currently-connected devices, see where the symlinks in {{ic|/sys/class/net/}} lead. For example:<br />
<br />
{{hc|file /sys/class/net/*|<br />
/sys/class/net/enp0s20f0u4u1: symbolic link to ../../devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4.1/2-4.1:1.0/net/enp0s20f0u4u1<br />
/sys/class/net/enp0s31f6: symbolic link to ../../devices/pci0000:00/0000:00:1f.6/net/enp0s31f6<br />
/sys/class/net/lo: symbolic link to ../../devices/virtual/net/lo<br />
/sys/class/net/wlp4s0: symbolic link to ../../devices/pci0000:00/0000:00:1c.6/0000:04:00.0/net/wlp4s0<br />
}}<br />
<br />
The device path should match both the new and old device name, since the rule may be executed more than once on bootup. For example, in the second rule, {{ic|"/devices/pci*/*1c.0/*/net/enp*"}} would be wrong since it will stop matching once the name is changed to {{ic|en}}. Only the system-default rule will fire the second time around, causing the name to be changed back to e.g. {{ic|enp1s0}}.<br />
<br />
If you are using a USB network device (e.g. Android phone tethering) that has a dynamic MAC address and you want to be able to use different USB ports, you could use a rule that matched depending on vendor and product ID instead:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
SUBSYSTEM=="net", ACTION=="add", ATTRS{idVendor}=="12ab", ATTRS{idProduct}=="3cd4", NAME="net2"<br />
}}<br />
<br />
To [[udev#Testing rules before loading|test]] your rules, they can be triggered directly from userspace, e.g. with {{ic|udevadm --debug test /sys/class/net/*}}. Remember to first take down the interface you are trying to rename (e.g. {{ic|ip link set enp1s0 down}}).<br />
<br />
{{Note|When choosing the static names '''it should be avoided to use names in the format of "eth''X''" and "wlan''X''"''', because this may lead to race conditions between the kernel and udev during boot. Instead, it is better to use interface names that are not used by the kernel as default, e.g.: {{ic|net0}}, {{ic|net1}}, {{ic|wifi0}}, {{ic|wifi1}}. For further details please see the [http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames systemd] documentation.}}<br />
<br />
=== Revert to traditional interface names ===<br />
<br />
If you would prefer to retain traditional interface names such as eth0, [http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames Predictable Network Interface Names] can be disabled by masking the udev rule:<br />
<br />
# ln -s /dev/null /etc/udev/rules.d/80-net-setup-link.rules<br />
<br />
Alternatively, add {{ic|1=net.ifnames=0}} to the [[kernel parameters]].<br />
<br />
=== Set device MTU and queue length ===<br />
<br />
You can change the device [[wikipedia:Maximum transmission unit|MTU]] and queue length by defining manually with an udev-rule. For example:<br />
<br />
{{hc|/etc/udev/rules.d/10-network.rules|2=<br />
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wl*", ATTR{mtu}="1500", ATTR{tx_queue_len}="2000"<br />
}}<br />
<br />
{{Note|<br />
* {{ic|mtu}}: For PPPoE, the MTU should be no larger than 1492. You can also set MTU via {{man|5|systemd.netdev}}.<br />
* {{ic|tx_queue_len}}: Small value for slower devices with a high latency like modem links and ISDN. High value is recommend for server connected over the high-speed Internet connections that perform large data transfers.<br />
}}<br />
<br />
=== Bonding or LAG ===<br />
<br />
See [[netctl#Bonding|netctl]] or [[systemd-networkd#Bonding a wired and wireless interface|systemd-networkd]], or [[Wireless bonding]].<br />
<br />
=== IP address aliasing ===<br />
<br />
IP aliasing is the process of adding more than one IP address to a network interface. With this, one node on a network can have multiple connections to a network, each serving a different purpose. Typical uses are virtual hosting of Web and FTP servers, or reorganizing servers without having to update any other machines (this is especially useful for nameservers).<br />
<br />
==== Example ====<br />
<br />
To manually set an alias, for some NIC, use {{Pkg|iproute2}} to execute<br />
<br />
# ip addr add 192.168.2.101/24 dev eth0 label eth0:1<br />
<br />
To remove a given alias execute<br />
<br />
# ip addr del 192.168.2.101/24 dev eth0:1<br />
<br />
Packets destined for a subnet will use the primary alias by default. If the destination IP is within a subnet of a secondary alias, then the source IP is set respectively. Consider the case where there is more than one NIC, the default routes can be listed with {{ic|ip route}}.<br />
<br />
=== Promiscuous mode ===<br />
<br />
Toggling [[wikipedia:Promiscuous mode|promiscuous mode]] will make a (wireless) NIC forward all traffic it receives to the OS for further processing. This is opposite to "normal mode" where a NIC will drop frames it is not intended to receive. It is most often used for advanced network troubleshooting and [[wikipedia:Packet sniffing|packet sniffing]].<br />
<br />
{{hc|/etc/systemd/system/promiscuous@.service|<nowiki><br />
[Unit]<br />
Description=Set %i interface in promiscuous mode<br />
After=network.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/ip link set dev %i promisc on<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
If you want to enable promiscuous mode on interface {{ic|eth0}} run [[enable]] {{ic|promiscuous@eth0.service}}.<br />
<br />
=== Investigate sockets ===<br />
<br />
''ss'' is a utility to investigate network ports and is part of the {{Pkg|iproute2}} package. It has a similar functionality to the [https://www.archlinux.org/news/deprecation-of-net-tools/ deprecated] netstat utility. <br />
<br />
Common usage includes:<br />
<br />
Display all TCP Sockets with service names:<br />
$ ss -at<br />
<br />
Display all TCP Sockets with port numbers:<br />
$ ss -atn<br />
<br />
Display all UDP Sockets:<br />
$ ss -au<br />
<br />
For more information see {{man|8|ss}}.<br />
<br />
== Troubleshooting ==<br />
<br />
=== The TCP window scaling problem ===<br />
<br />
TCP packets contain a "window" value in their headers indicating how much data the other host may send in return. This value is represented with only 16 bits, hence the window size is at most 64Kb. TCP packets are cached for a while (they have to be reordered), and as memory is (or used to be) limited, one host could easily run out of it.<br />
<br />
Back in 1992, as more and more memory became available, [http://www.faqs.org/rfcs/rfc1323.html RFC 1323] was written to improve the situation: Window Scaling. The "window" value, provided in all packets, will be modified by a Scale Factor defined once, at the very beginning of the connection. That 8-bit Scale Factor allows the Window to be up to 32 times higher than the initial 64Kb.<br />
<br />
It appears that some broken routers and firewalls on the Internet are rewriting the Scale Factor to 0 which causes misunderstandings between hosts. The Linux kernel 2.6.17 introduced a new calculation scheme generating higher Scale Factors, virtually making the aftermaths of the broken routers and firewalls more visible.<br />
<br />
The resulting connection is at best very slow or broken.<br />
<br />
==== How to diagnose the problem ====<br />
<br />
First of all, let us make it clear: this problem is odd. In some cases, you will not be able to use TCP connections (HTTP, FTP, ...) at all and in others, you will be able to communicate with some hosts (very few).<br />
<br />
When you have this problem, the {{ic|dmesg}}'s output is OK, logs are clean and {{ic|ip addr}} will report normal status... and actually everything appears normal.<br />
<br />
If you cannot browse any website, but you can ping some random hosts, chances are great that you are experiencing this problem: ping uses ICMP and is not affected by TCP problems.<br />
<br />
You can try to use [[Wireshark]]. You might see successful UDP and ICMP communications but unsuccessful TCP communications (only to foreign hosts).<br />
<br />
==== Ways of fixing it ====<br />
<br />
===== Bad =====<br />
<br />
To fix it the bad way, you can change the {{ic|tcp_rmem}} value, on which Scale Factor calculation is based. Although it should work for most hosts, it is not guaranteed, especially for very distant ones.<br />
<br />
# echo "4096 87380 174760" > /proc/sys/net/ipv4/tcp_rmem<br />
<br />
===== Good =====<br />
<br />
Simply disable Window Scaling. Since Window Scaling is a nice TCP feature, it may be uncomfortable to disable it, especially if you cannot fix the broken router. There are several ways to disable Window Scaling, and it seems that the most bulletproof way (which will work with most kernels) is to add the following line to {{ic|/etc/sysctl.d/99-disable_window_scaling.conf}} (see also [[sysctl]]):<br />
<br />
net.ipv4.tcp_window_scaling = 0<br />
<br />
===== Best =====<br />
<br />
This problem is caused by broken routers/firewalls, so let us change them. Some users have reported that the broken router was their very own DSL router.<br />
<br />
==== More about it ====<br />
<br />
This section is based on the LWN article [http://lwn.net/Articles/92727/ TCP window scaling and broken routers] and an archived Kernel Trap article: [https://web.archive.org/web/20120426135627/http://kerneltrap.org:80/node/6723 Window Scaling on the Internet].<br />
<br />
There are also several relevant threads on the LKML.<br />
<br />
== See also ==<br />
<br />
* [https://www.tldp.org/LDP/nag2/index.html Linux Network Administrators Guide]<br />
* [https://www.debian.org/doc/manuals/debian-reference/ch05.en.html Debian Reference: Network setup]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/ RHEL7: Networking Guide]<br />
* [http://www.linuxhomenetworking.com/wiki/ Linux Home Networking]<br />
* [https://blog.packagecloud.io/eng/2016/06/22/monitoring-tuning-linux-networking-stack-receiving-data/ Monitoring and tuning the Linux Networking Stack: Receiving data]<br />
* [https://blog.packagecloud.io/eng/2017/02/06/monitoring-tuning-linux-networking-stack-sending-data/ Monitoring and tuning the Linux Networking Stack: Sending data]<br />
* [http://blog.yadutaf.fr/2017/07/28/tracing-a-packet-journey-using-linux-tracepoints-perf-ebpf/ Tracing a packet journey using tracepoints, perf and eBPF]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=Iwd&diff=611106Iwd2020-05-05T16:57:26Z<p>JoshuaRLi: mention alternative DHCP clients that iwd's builtin one can be substituted for</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Wireless networking]]<br />
[[Category:Network configuration]]<br />
[[ja:Iwd]]<br />
{{Related articles start}}<br />
{{Related|Network configuration}}<br />
{{Related|Wireless network configuration}}<br />
{{Related|WPA supplicant}}<br />
{{Related articles end}}<br />
[https://iwd.wiki.kernel.org/ iwd] (iNet wireless daemon) is a wireless daemon for Linux written by Intel. The core goal of the project is to optimize resource utilization by not depending on any external libraries and instead utilizing features provided by the Linux Kernel to the maximum extent possible. [https://www.youtube.com/watch?v=F2Q86cphKDo]<br />
<br />
iwd can work in standalone mode or in combination with comprehensive network managers like [[ConnMan]], [[systemd-networkd]] and [[NetworkManager#Using_iwd_as_the_Wi-Fi_backend|NetworkManager]].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|iwd}} package.<br />
<br />
== Usage ==<br />
<br />
The {{Pkg|iwd}} package provides the client program {{ic|iwctl}}, the daemon {{ic|iwd}} and the Wi-Fi monitoring tool {{ic|iwmon}}.<br />
<br />
[[Start/enable]] {{ic|iwd.service}} so it can be controlled using the {{ic|iwctl}} command.<br />
<br />
=== iwctl ===<br />
<br />
To get an interactive prompt do:<br />
<br />
$ iwctl<br />
<br />
The interactive prompt is then displayed with a prefix of {{ic|[iwd]#}}.<br />
<br />
{{Tip|<br />
* In the {{ic|iwctl}} prompt you can auto-complete commands and device names by hitting {{ic|Tab}}.<br />
* You can use all commands as command line arguments without entering an interactive prompt. For example: {{ic|iwctl device wlp3s0 show}}.}}<br />
<br />
To list all available commands:<br />
<br />
[iwd]# help<br />
<br />
==== Connect to a network ====<br />
<br />
First, if you do not know your wireless device name, list all wifi devices:<br />
<br />
[iwd]# device list<br />
<br />
Then, to scan for networks:<br />
<br />
[iwd]# station ''device'' scan<br />
<br />
You can then list all available networks:<br />
<br />
[iwd]# station ''device'' get-networks<br />
<br />
Finally, to connect to a network:<br />
<br />
[iwd]# station ''device'' connect ''SSID''<br />
<br />
If a passphrase is required, you will be prompted to enter it. Alternatively, you can supply as a command line argument:<br />
<br />
$ iwctl --passphrase ''passphrase'' station ''device'' connect ''SSID''<br />
<br />
{{Note|<br />
* {{ic|iwd}} automatically stores network passphrases in the {{ic|/var/lib/iwd}} directory and uses them to auto-connect in the future. See [[#Optional configuration]].<br />
* To connect to a network with spaces in the SSID, the network name should be double quoted when connecting.<br />
* iwd only supports PSK pass-phrases from 8 to 63 ASCII-encoded characters. The following error message will be given if the requirements are not met: "PMK generation failed. Ensure Crypto Engine is properly configured"<br />
}}<br />
<br />
==== Connect to a network using WPS/WSC ====<br />
<br />
If your network is configured such that you can connect to it by pressing a button ([[Wikipedia:Wi-Fi Protected Setup]]), check first that your network device is also capable of using this setup procedure.<br />
<br />
[iwd]# wsc list<br />
<br />
Then, provided that your device appeared in the above list,<br />
<br />
[iwd]# wsc ''device'' push-button<br />
<br />
and go push the button on your router. That's it. The procedure works also if the button was pushed beforehand, less than 2 minutes earlier.<br />
<br />
If your network requires to validate a PIN number to connect that way, check the {{ic|help}} command output to see how to provide the right options to the {{ic|wsc}} command.<br />
<br />
==== Disconnect from a network ====<br />
<br />
To disconnect from a network:<br />
<br />
[iwd]# station ''device'' disconnect<br />
<br />
==== Show device and connection information ====<br />
<br />
To display the details of a WiFi device, like MAC address:<br />
<br />
[iwd]# device ''device'' show<br />
<br />
To display the connection state, including the connected network of a WiFi device:<br />
<br />
[iwd]# station ''device'' show<br />
<br />
==== Manage known networks ====<br />
<br />
To list networks you have connected to previously:<br />
<br />
[iwd]# known-networks list<br />
<br />
To forget a known network:<br />
<br />
[iwd]# known-networks ''SSID'' forget<br />
<br />
== WPA Enterprise ==<br />
<br />
=== EAP-PWD ===<br />
<br />
For connecting to a EAP-PWD protected enterprise access point you need to create a file called: {{ic|''essid''.8021x}} in the folder {{ic|/var/lib/iwd}} with the following content:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=<br />
[Security]<br />
EAP-Method=PWD<br />
EAP-Identity=''your_enterprise_email''<br />
EAP-Password=''your_password''<br />
<br />
[Settings]<br />
AutoConnect=True<br />
}}<br />
<br />
If you do not want autoconnect to the AP you can set the option to False and connect manually to the access point via {{ic|iwctl}}. The same applies to the password, if you do not want to store it plaintext leave the option out of the file and just connect to the enterprise AP.<br />
<br />
=== EAP-PEAP ===<br />
Like EAP-PWD, you also need to create a {{ic|''essid''.8021x}} in the folder. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses MSCHAPv2 password authentication:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=[Security]<br />
EAP-Method=PEAP<br />
EAP-Identity=anonymous@realm.edu<br />
EAP-PEAP-CACert=/path/to/root.crt<br />
EAP-PEAP-ServerDomainMask=radius.realm.edu<br />
EAP-PEAP-Phase2-Method=MSCHAPV2<br />
EAP-PEAP-Phase2-Identity=johndoe@realm.edu<br />
EAP-PEAP-Phase2-Password=hunter2<br />
<br />
[Settings]<br />
AutoConnect=true}}<br />
<br />
{{Tip|If you are planning on using ''eduroam'' and you are affiliated with a US-based institution, your CA is likely {{ic|Addtrust External CA Root}}, as your institution probably issues certificates through Internet2's InCommon. However, you should always refer to your organization's help desk if in doubt. See also [[#Eduroam]].}}<br />
<br />
=== TTLS-PAP ===<br />
<br />
Like EAP-PWD, you also need to create a {{ic|''essid''.8021x}} in the folder. Before you proceed to write the configuration file, this is also a good time to find out which CA certificate your organization uses. This is an example configuration file that uses PAP password authentication:<br />
<br />
{{hc|/var/lib/iwd/''essid''.8021x|2=[Security]<br />
EAP-Method=TTLS<br />
EAP-Identity=anonymous@uni-test.de<br />
EAP-TTLS-CACert=cert.pem<br />
EAP-TTLS-ServerDomainMask=*.uni-test.de<br />
EAP-TTLS-Phase2-Method=Tunneled-PAP<br />
EAP-TTLS-Phase2-Identity=user<br />
EAP-TTLS-Phase2-Password=password<br />
<br />
[Settings]<br />
AutoConnect=true}}<br />
<br />
=== TLS Based EAP Methods on older kernels ===<br />
<br />
Linux kernels older than v4.20 (e.g. {{Pkg|linux-lts}}) have to be patched to connect to EAP-TLS, EAP-TTLS, and EAP-PEAP.<br />
Edit the PKGBUILD for the kernel and add the following sources<br />
{{hc|PKGBUILD|2=<br />
"iwd1.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=ab2a33c1c0b1b0a45c16746dd0101057c6d432ed"<br />
"iwd2.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=3a478ace6154e33009f9b01acbd4eaf7615fef0e"<br />
"iwd3.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5faadff684460b7f4064f9f28db8915a56601147"<br />
"iwd4.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=3c7f3a6c70b47858a065b7a86313f390b083ee40" <br />
"iwd5.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5362bbfdf2a8a5810d4237e4dbbf5da043e47fb6"<br />
"iwd6.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=5c93ce3acc010425eab01dc8e0ffb5529f3f85c1"<br />
"iwd7.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=ca4d545b92cf52ffe777cc7cfbaf64100dfa6e9c"<br />
"iwd8.patch::https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/linux-fs.git/patch/?id=f2ac228eaba9fe3f4fcf80b121eb92707afdd4de"<br />
}}<br />
And add the following line to the end of the kernel config:<br />
{{hc|config|2=<br />
CONFIG_PKCS8_PRIVATE_KEY_PARSER=y<br />
}}<br />
Then update the checksums of the PKGBUILD with {{ic|updpkgsums}} (from {{Pkg|pacman-contrib}}):<br />
<br />
$ updpkgsums<br />
<br />
and build the package.<br />
<br />
=== Eduroam ===<br />
<br />
Eduroam offers a [https://cat.eduroam.org/ configuration assistant tool (CAT)], which unfortunately does not support iwd. However, the installer, which you can download by clicking on the download button then selecting your university, is just a Python script. It is easy to extract the necessary configuration options, including the certificate and server domain mask.<br />
<br />
The following table contains a mapping of iwd configuration options to eduroam CAT install script variables.<br />
<br />
{| class="wikitable<br />
! Iwd Configuration Option !! CAT Script Variable<br />
|-<br />
| file name || one of {{ic|Config.ssids}}<br />
|-<br />
| {{ic|EAP-Method}} || {{ic|Config.eap_outer}}<br />
|-<br />
| {{ic|EAP-Identity}} || {{ic|Config.email}}<br />
|-<br />
| {{ic|EAP-PEAP-CACert}} || {{ic|Config.CA}}<br />
|-<br />
| {{ic|EAP-PEAP-ServerDomainMask}} || one of {{ic|Config.servers}}<br />
|-<br />
| {{ic|EAP-PEAP-Phase2-Method}} || {{ic|Config.eap_inner}}<br />
|-<br />
| {{ic|EAP-PEAP-Phase2-Identity}} || username@{{ic|Config.user_realm}}<br />
|}<br />
<br />
{{Note| {{ic|EAP-Identity}} may not be required by your Eduroam provider, in which case you can use {{ic|anonymous}} in this field.}}<br />
<br />
=== Other cases ===<br />
<br />
More example tests can be [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests found in the test cases] of the upstream repository.<br />
<br />
== Optional configuration ==<br />
<br />
File {{ic|/etc/iwd/main.conf}} can be used for main configuration. See {{man|5|iwd.config}}.<br />
<br />
By default, {{ic|iwd}} stores the network configuration in {{ic|/var/lib/iwd}} directory. The configuration file is named as {{ic|''network''.''type''}} where ''network'' is network SSID and ''type'' is network type i.e. one of "open", "wep", "psk", "8021x". The file is used to store the encrypted {{ic|PreSharedKey}} and optionally the cleartext {{ic|Passphrase}} and can be created by the user without invoking {{ic|iwctl}}. The file can also be used for other configuration pertaining to that network SSID. For more settings, see {{man|5|iwd.network}}.<br />
<br />
A minimal example file to connect to a WPA2/PSK secured network with SSID "spaceship" and passphrase "test1234":<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[Security]<br />
PreSharedKey=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295<br />
}}<br />
<br />
The PreSharedKey can be calculated from the SSID and the WiFi passphrase using ''wpa_passphrase'' (from {{Pkg|wpa_supplicant}}) or {{AUR|wpa-psk}}:<br />
<br />
{{hc|$ wpa_passphrase "spaceship" "test1234"|2=<br />
network={<br />
ssid="spaceship"<br />
#psk="test1234"<br />
psk=aafb192ce2da24d8c7805c956136f45dd612103f086034c402ed266355297295<br />
}<br />
}}<br />
<br />
{{Note|The SSID of the network is used as a filename only when it contains only alphanumeric characters or one of {{ic|- _}}. If it contains any other characters, the name will instead be an {{ic|1==}}-character followed by the hex-encoded version of the SSID.}}<br />
<br />
=== Disable auto-connect for a particular network ===<br />
<br />
Create / edit file {{ic|/var/lib/iwd/''network''.''type''}}. Add the following section to it:<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk (for example)|2=<nowiki><br />
[Settings]<br />
AutoConnect=false<br />
</nowiki>}}<br />
<br />
=== Disable periodic scan for available networks ===<br />
<br />
By default when {{ic|iwd}} is in disconnected state, it periodically scans for available networks. To disable periodic scan (so as to always scan manually), create / edit file {{ic|/etc/iwd/main.conf}} and add the following section to it:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Scan]<br />
DisablePeriodicScan=true<br />
}}<br />
<br />
=== Enable built-in network configuration ===<br />
<br />
Since version 0.19, iwd can assign IP address(es) and set up routes using a built-in DHCP client or with static configuration. It's a good alternative to standalone DHCP clients such as {{Pkg|dhcpcd}} or {{Pkg|dhclient}}.<br />
<br />
To activate iwd's network configuration feature, create/edit {{ic|/etc/iwd/main.conf}} and add the following section to it:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[General]<br />
EnableNetworkConfiguration=true<br />
}}<br />
<br />
There is also ability to set route metric with {{ic|route_priority_offset}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[General]<br />
route_priority_offset=300<br />
}}<br />
<br />
==== Setting static IP address in network configuration ====<br />
<br />
Add the following section to {{ic|/var/lib/iwd/''network''.''type''}} file. For example:<br />
<br />
{{hc|/var/lib/iwd/spaceship.psk|2=<br />
[IPv4]<br />
ip=192.168.1.10<br />
netmask=255.255.255.0<br />
gateway=192.168.1.1<br />
broadcast=192.168.1.255<br />
dns=192.168.1.1<br />
}}<br />
<br />
==== Select DNS manager ====<br />
<br />
At the moment, iwd supports two DNS managers—[[systemd-resolved]] and [[resolvconf]].<br />
<br />
Add the following section to {{ic|/etc/iwd/main.conf}} for {{ic|systemd-resolved}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
NameResolvingService=systemd<br />
}}<br />
<br />
For {{ic|resolvconf}}:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[Network]<br />
NameResolvingService=resolvconf<br />
}}<br />
<br />
=== Deny console (local) user from modifying the settings ===<br />
<br />
By default {{ic|iwd}} D-Bus interface allows ''any'' console user to connect to {{ic|iwd}} daemon and modify the settings, even if that user is not a ''root'' user.<br />
<br />
If you do not want to allow console user to modify the settings but allow reading the status information, then create a D-Bus configuration file as follows.<br />
<br />
{{hc|/etc/dbus-1/system.d/iwd-strict.conf|2=<nowiki><br />
<!-- prevent local users from changing iwd settings, but allow<br />
reading status information. overrides some part of<br />
/usr/share/dbus-1/system.d/iwd-dbus.conf. --><br />
<br />
<!-- This configuration file specifies the required security policies<br />
for iNet Wireless Daemon to work. --><br />
<br />
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"<br />
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"><br />
<busconfig><br />
<br />
<policy at_console="true"><br />
<deny send_destination="net.connman.iwd"/><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="GetAll" /><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.Properties" send_member="Get" /><br />
<allow send_destination="net.connman.iwd" send_interface="org.freedesktop.DBus.ObjectManager" send_member="GetManagedObjects" /><br />
<allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="RegisterSignalLevelAgent" /><br />
<allow send_destination="net.connman.iwd" send_interface="net.connman.iwd.Device" send_member="UnregisterSignalLevelAgent" /><br />
</policy><br />
<br />
</busconfig><br />
</nowiki>}}<br />
<br />
{{Tip|Remove ''<allow>'' lines above to deny reading the status information as well.}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Verbose TLS debugging ===<br />
<br />
This can be useful, if you have trouble setting up MSCHAPv2 or TTLS. You can set the following environment variable via {{ic|systemctl edit iwd.service}}:<br />
<br />
{{hc|/etc/systemd/system/iwd.conf.d/override.conf|2=<br />
[Service]<br />
Environment=IWD_TLS_DEBUG=TRUE<br />
}}<br />
<br />
Check the iwd logs afterwards via {{ic|journalctl -u iwd}}<br />
<br />
=== Connect issues after reboot ===<br />
<br />
A low entropy pool can cause connection problems in particular noticeable after reboot. See [[Random number generation]] for suggestions to increase the entropy pool.<br />
<br />
=== Systemd unit fails on startup due to device not being available ===<br />
<br />
Some users have reported that the provided systemd unit does not wait for the wireless device to become available [https://bbs.archlinux.org/viewtopic.php?id=241803]. Unfortunately, if iwd is started before udev renaming is done, the network device will be blocked and renaming will fail. Thus, the unit fails on startup [https://iwd.wiki.kernel.org/interface_lifecycle#udev_interface_renaming]. The issue can be fixed by forcing iwd to legacy mode and thus, not renaming newly detected devices, by adding an option to {{ic|/etc/iwd/main.conf}} as follows:<br />
<br />
{{hc|/etc/iwd/main.conf|2=<br />
[General]<br />
use_default_interface=true<br />
}}<br />
<br />
Optionally, bind iwd to a specific wireless device by creating a systemd unit with the following content. As of ''0.21'', it has been observed that this will not prevent iwd from renaming the wireless device later, thus the use of iwd's legacy mode is mandatory:<br />
<br />
{{hc|1=/etc/systemd/system/iwd@.service|2=<br />
[Unit]<br />
Description=Wireless service on %I<br />
BindsTo=sys-subsystem-net-devices-%i.device<br />
After=sys-subsystem-net-devices-%i.device<br />
<br />
[Service]<br />
Type=dbus<br />
BusName=net.connman.iwd<br />
ExecStart=/usr/lib/iwd/iwd --interface %i<br />
LimitNPROC=1<br />
Restart=on-failure}}<br />
<br />
Then, disable {{ic|iwd.service}} and enable {{ic|iwd@''device''.service}} unit for the specific wireless ''device''.<br />
<br />
Alternatively, set a proper dependency for iwd to run after systemd/udevd by creating a [[drop-in file]] as follows: [https://lists.01.org/pipermail/iwd/2019-March/005837.html]<br />
<br />
{{Accuracy|1=Is "After=network-pre.target" needed? If so, is "After=systemd-udevd" even needed? This solution does not seem to work for all cases. See [https://lists.01.org/pipermail/iwd/2019-March/005839.html] and {{man|7|systemd.special}}.}}<br />
<br />
{{hc|1=/etc/systemd/system/iwd.service.d/override.conf|2=<br />
[Unit]<br />
After=systemd-udevd.service}}<br />
<br />
If systemd-networkd is used, since both systemd-udevd/networkd play relatively well together, and both are involved, it is reasonable to start iwd after both of them:<br />
<br />
{{hc|1=/etc/systemd/system/iwd.service.d/override.conf|2=<br />
[Unit]<br />
After=systemd-udevd.service systemd-networkd.service}} <br />
<br />
See {{Bug|61367}}.<br />
<br />
=== Wireless device is not renamed by udev ===<br />
<br />
Upgrade to {{Pkg|iwd}} 1.0 introduces the systemd network link configuration file:<br />
<br />
{{hc|1=/usr/lib/systemd/network/80-iwd.link|2=<br />
[Match]<br />
Type=wlan<br />
<br />
[Link]<br />
NamePolicy=keep kernel}}<br />
<br />
This prevents udev from renaming the interface to {{ic|wlp#s#}}. As a result the wireless link name {{ic|wlan#}} is kept after boot.<br />
<br />
If this results in issues try masking it with:<br />
<br />
# ln -s /dev/null /etc/systemd/network/80-iwd.link<br />
<br />
=== WPA Enterprise connection with NetworkManager ===<br />
<br />
{{Move|NetworkManager#Troubleshooting|This is not a problem of iwd.}}<br />
<br />
If you try to connect to an WPA Enterprise network like 'eduroam' with NetworkManager with the iwd backend then you will get the following error from NetworkManager:<br />
<br />
Connection 'eduroam' is not avialable on device wlan0 because profile is not compatible with device (802.1x connections must have IWD provisioning files)<br />
<br />
This is because NetworkManager can not configure a WPA Enterprise network. Therefore you have to configure it using an iwd config file {{ic|/var/lib/iwd/''essid''.8021x}} like described in [[#WPA Enterprise]].<br />
<br />
== See also ==<br />
<br />
* [https://iwd.wiki.kernel.org/gettingstarted Getting Started with iwd]<br />
* [https://iwd.wiki.kernel.org/networkconfigurationsettings Network Configuration Settings]<br />
* [https://git.kernel.org/pub/scm/network/wireless/iwd.git/tree/autotests More Examples for WPA Enterprise]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=User:JoshuaRLi&diff=589106User:JoshuaRLi2019-11-17T01:41:47Z<p>JoshuaRLi: Blanked the page</p>
<hr />
<div></div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539530GnuPG2018-09-03T23:07:58Z<p>JoshuaRLi: remove unnecessary header prefix</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent]] 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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Then send the key that was revoked back to your keyserver(s) of choice.<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<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>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539529GnuPG2018-09-03T23:06:32Z<p>JoshuaRLi: remove unnecessary header prefix</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent]] 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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Then send the key that was revoked back to your keyserver(s) of choice.<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== gpg: WARNING: 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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<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>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539528GnuPG2018-09-03T23:05:22Z<p>JoshuaRLi: remove outdated resource and slight reordering</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent]] 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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Then send the key that was revoked back to your keyserver(s) of choice.<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== gpg: WARNING: 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 />
=== gpg: ..., 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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<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>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539527GnuPG2018-09-03T23:02:19Z<p>JoshuaRLi: subkeys.pgp.net doesn't exist anymore, and there are already instructions on how to send keys to keyservers in the wiki page</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent]] 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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Then send the key that was revoked back to your keyserver(s) of choice.<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== gpg: WARNING: 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 />
=== gpg: ..., 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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539526GnuPG2018-09-03T22:55:30Z<p>JoshuaRLi: pinentry ic -> pkg</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{Pkg|pinentry}} user interface when prompting the user for a passphrase. For example:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
pinentry-program /usr/bin/pinentry-curses<br />
}}<br />
<br />
There are other pinentry programs that you can choose from - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}.<br />
<br />
{{Tip|In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
Remember to [[#Reload the agent]] 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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== gpg: WARNING: 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 />
=== gpg: ..., 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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539525GnuPG2018-09-03T22:54:36Z<p>JoshuaRLi: Less verbose pinentry section.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
{{ic|gpg-agent}} can be configured via the {{ic|pinentry-program}} stanza to use a particular {{ic|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]] 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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== gpg: WARNING: 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 />
=== gpg: ..., 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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=GnuPG&diff=539524GnuPG2018-09-03T22:43:38Z<p>JoshuaRLi: same # of X's</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
[[zh-hant:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as 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. Version 2 of 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 />
{{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/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|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 />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a 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. Later, 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 />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg'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 be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w: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 --output ''public.key'' --armor --export ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''user-id''<br />
<br />
{{Warning|Once a key has been submitted to a keyserver, it cannot be deleted from the server.[https://pgp.mit.edu/faq.html]}}<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 />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed, but this can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg}}. <br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* If your network blocks ports used for hkp/hkps, you may need to specify port 80, i.e. {{ic|pool.sks-keyservers.net:80}}<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] 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 {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<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 />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). 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|--decrypt}} or {{ic|-d}}) 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 instead; 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 [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<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|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. 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 />
$ gpg --import ''privkey.asc''<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 />
Some useful commands in the edit key sub menu:<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 />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<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 -K<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 />
=== 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 />
If you have set your subkeys to expire after a set time, 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.}}<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 />
{{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 />
== 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|--sign}} or {{ic|-s}} 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 as 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 />
{{Expansion|Add {{ic|gpg-agent-browser.socket}} to the list.}}<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-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Directory location]], you will need to [[edit]] all socket files to use the values of {{ic|gpgconf --list-dirs}}.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
However in some cases only the restart may not be sufficient, like when {{ic|keep-screen}} has been added to the agent configuration.<br />
In this case you firstly need to kill the ongoing gpg-agent process and then you can restart it as was explained above.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses {{ic|/usr/bin/pinentry-gtk-2}}, falling back to {{ic|/usr/bin/pinentry-curses}} if gtk2 is unavailable. However there are other options - see {{ic|pacman -Ql pinentry {{!}} grep /usr/bin/}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
# pinentry-program /usr/bin/pinentry-gnome3<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, [[#Reload the agent]].<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 />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
You have to set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{note|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 />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}.<br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''}}<br />
<br />
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]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to 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 />
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 />
== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send-keys ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<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 />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<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, even as root. 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 likely to be 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 />
The default pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, which 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 />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<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 />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<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 doesn't matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread]<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. 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 commnads:<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 />
{{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 />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== gpg: WARNING: 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 />
=== gpg: ..., 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 />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=Core_utilities&diff=510717Core utilities2018-02-13T22:16:54Z<p>JoshuaRLi: Updating fd short pitch to more closely match the README of the official project repo: https://github.com/sharkdp/fd</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:Command shells]]<br />
[[fa:Core utilities]]<br />
[[es:Core utilities]]<br />
[[it:Core utilities]]<br />
[[ja:Core Utilities]]<br />
[[ko:Core utilities]]<br />
[[pt:Core utilities]]<br />
[[ru:Core utilities]]<br />
[[zh-hans:Core utilities]]<br />
[[zh-hant:Core utilities]]<br />
{{Related articles start}}<br />
{{Related|Bash}}<br />
{{Related|Zsh}}<br />
{{Related|General recommendations}}<br />
{{Related|GNU Project}}<br />
{{Related|sudo}}<br />
{{Related|cron}}<br />
{{Related|man page}}<br />
{{Related|Securely wipe disk#shred}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Color output in console}}<br />
{{Related articles end}}<br />
<br />
This article deals with so-called ''core'' utilities on a GNU/Linux system, such as ''less'', ''ls'', and ''grep''. The scope of this article includes, but is not limited to, those utilities included with the GNU {{Pkg|coreutils}} package. What follows are various tips and tricks and other helpful information related to these utilities.<br />
<br />
== Basic commands ==<br />
<br />
The following table lists basic shell commands every Linux user should be familiar with. See the below sections and ''Related articles'' for details.<br />
<br />
{| class="wikitable"<br />
! Command<br />
! Description<br />
! Manual page<br />
! Example<br />
|-<br />
| man<br />
| Show manual page for a command<br />
| {{man|7|man}}<br />
| man ed<br />
|-<br />
| cd<br />
| Change directory (shell built-in command)<br />
| {{man|1p|cd}}<br />
| cd /etc/pacman.d<br />
|-<br />
| mkdir<br />
| Create a directory<br />
| {{man|1|mkdir}}<br />
| mkdir ~/newfolder<br />
|-<br />
| rmdir<br />
| Remove empty directory<br />
| {{man|1|rmdir}}<br />
| rmdir ~/emptyfolder<br />
|-<br />
| rm<br />
| Remove a file<br />
| {{man|1|rm}}<br />
| rm ~/file.txt<br />
|-<br />
| rm -r<br />
| Remove directory and contents<br />
|<br />
| rm -r ~/.cache<br />
|-<br />
| ls<br />
| List files<br />
| {{man|1|ls}}<br />
| ls *.mkv<br />
|-<br />
| ls -a<br />
| List hidden files<br />
|<br />
| ls -a /home/archie<br />
|-<br />
| ls -al<br />
| List hidden files and file properties<br />
|<br />
|<br />
|-<br />
| mv<br />
| Move a file<br />
| {{man|1|mv}}<br />
| mv ~/compressed.zip ~/archive/compressed2.zip<br />
|-<br />
| cp<br />
| Copy a file<br />
| {{man|1|cp}}<br />
| cp ~/.bashrc ~/.bashrc.bak<br />
|-<br />
| chmod +x<br />
| Make a file [[executable]]<br />
| {{man|1|chmod}}<br />
| chmod +x ~/.local/bin/myscript.sh<br />
|-<br />
| cat<br />
| Show file contents<br />
| {{man|1|cat}}<br />
| cat /etc/hostname<br />
|-<br />
| strings<br />
| Show printable characters in binary files<br />
| {{man|1|strings}}<br />
| strings /usr/bin/free<br />
|-<br />
| find<br />
| Search for a file<br />
| {{man|1|find}}<br />
| find ~ -name myfile<br />
|-<br />
| mount<br />
| Mount a partition<br />
| {{man|8|mount}}<br />
| mount /dev/sdc1 /media/usb<br />
|-<br />
| df -h<br />
| Show remaining space on all partitions<br />
| {{man|1|df}}<br />
|<br />
|-<br />
| ps -A<br />
| Show all running processes<br />
| {{man|1|ps}}<br />
|<br />
|-<br />
| killall<br />
| Kill all running instances of a process<br />
| {{man|1|killall}}<br />
|<br />
|-<br />
| ss -at<br />
| Display a list of open TCP sockets<br />
| {{man|8|ss}}<br />
|<br />
|}<br />
<br />
== cat ==<br />
<br />
[[Wikipedia:cat_(Unix)|cat]] is a standard Unix utility that concatenates and lists files.<br />
<br />
* Because ''cat'' is not built into the shell, on many occasions you may find it more convenient to use a [[Wikipedia:Redirection (computing)|redirection]], for example in scripts, or if you care a lot about performance. In fact {{ic|< ''file''}} does the same as {{ic|cat ''file''}}.<br />
<br />
* ''cat'' is able to work with multiple lines:<br />
<br />
{{bc|<br />
$ cat << EOF >> ''path/file''<br />
''first line''<br />
...<br />
''last line''<br />
EOF<br />
}}<br />
<br />
Alternatively, using {{ic|printf}}:<br />
<br />
{{bc|<br />
$ printf '%s\n' 'first line' ... 'last line'<br />
}}<br />
<br />
* If you need to list file lines in reverse order, there is a utility called [[Wikipedia:tac (Unix)|tac]] (''cat'' reversed).<br />
<br />
== dd ==<br />
<br />
[[Wikipedia:dd (Unix)|dd]] is a utility for Unix and Unix-like operating systems whose primary purpose is to convert and copy a file.<br />
<br />
Similarly to ''cp'', by default ''dd'' makes a bit-to-bit copy of the file, but with lower-level I/O flow control features.<br />
<br />
{{Tip|By default, ''dd'' outputs nothing until the task has finished. To monitor the progress of the operation, add the {{ic|1=status=progress}} option to the command.}}<br />
<br />
For more information see {{man|1|dd}} or the [https://www.gnu.org/software/coreutils/dd full documentation].<br />
<br />
== grep ==<br />
<br />
[[Wikipedia:grep|grep]] (from [[Wikipedia:Ed_(text_editor)|ed]]'s ''g/re/p'', ''global/regular expression/print'') is a command line text search utility originally written for Unix. The ''grep'' command searches files or standard input for lines matching a given regular expression, and prints these lines to the program's standard output.<br />
<br />
* Remember that ''grep'' handles files, so a construct like {{ic|cat ''file'' <nowiki>|</nowiki> grep ''pattern''}} is replaceable with {{ic|grep ''pattern'' ''file''}}<br />
* There are ''grep'' alternatives optimized for VCS source code, such as {{Pkg|ripgrep}}, {{Pkg|the_silver_searcher}}, and {{Pkg|ack}}.<br />
* To include file line numbers in the output, use the {{ic|-n}} option. <br />
<br />
{{Note|Some commands send their output to {{man|3|stderr}}, and grep has no apparent effect. In this case, redirect ''stderr'' to ''stdout'' with {{ic|''command'' 2>&1 {{!}} grep ''args''}} or (for Bash 4) {{ic|''command'' {{!}}& grep ''args''}}. See also [http://www.tldp.org/LDP/abs/html/io-redirection.html I/O Redirection].}}<br />
<br />
For color support, see [[Color output in console#grep]].<br />
<br />
== find ==<br />
<br />
''find'' is part of the {{Pkg|findutils}} package, which belongs to the {{Grp|base}} package group. <br />
<br />
{{Tip|{{Pkg|fd}} is a simple, fast and user-friendly alternative to {{ic|find}} that provides more sensible defaults (e.g. ignores hidden files, dirs and {{ic|.gitignore}}'d files, {{ic|fd PATTERN}} instead of {{ic|find -iname '*PATTERN*'}}). It features colorized output (similar to {{ic|ls}}), unicode awareness, regular expressions and more.}}<br />
<br />
One would probably expect a ''find'' command to take as argument a file name and search the filesystem for files matching that name. For a program that does exactly that see [[#locate]] below. <br />
<br />
Instead, find takes a set of directories and matches each file under them against a set of expressions. This design allows for some very powerful "one-liners" that would not be possible using the "intuitive" design described above. See [http://mywiki.wooledge.org/UsingFind UsingFind] for usage details.<br />
<br />
== iconv ==<br />
<br />
''iconv'' converts the encoding of characters from one codeset to another.<br />
<br />
The following command will convert the file {{ic|''foo''}} from ISO-8859-15 to UTF-8, saving it to {{ic|''foo''.utf}}:<br />
<br />
$ iconv -f ISO-8859-15 -t UTF-8 ''foo'' > ''foo''.utf<br />
<br />
See {{man|1|iconv}} for more details.<br />
<br />
=== Convert a file in place ===<br />
<br />
{{Tip|You can use {{pkg|recode}} instead of iconv if you do not want to touch the mtime.}}<br />
Unlike [[#sed|sed]], ''iconv'' does not provide an option to convert a file in place. However, {{ic|sponge}} from the {{pkg|moreutils}} package can help:<br />
<br />
$ iconv -f WINDOWS-1251 -t UTF-8 ''foobar''.txt | sponge ''foobar''.txt<br />
<br />
See {{man|1|sponge}} for details.<br />
<br />
== ip ==<br />
<br />
[[Wikipedia:Iproute2|ip]] allows you to show information about network devices, IP addresses, routing tables, and other objects in the Linux [[Wikipedia:Internet Protocol|IP]] software stack. By appending various commands, you can also manipulate or configure most of these objects.<br />
<br />
{{Note|The ''ip'' utility is provided by the {{Pkg|iproute2}} package, which is included in the {{Grp|base}} group.}}<br />
<br />
{| class="wikitable"<br />
! Object !! Purpose !! Manual page<br />
|-<br />
| ip addr || protocol address management || {{man|8|ip-address}}<br />
|-<br />
| ip addrlabel || protocol address label management || {{man|8|ip-addrlabel}}<br />
|-<br />
| ip l2tp || tunnel Ethernet over IP (L2TPv3) || {{man|8|ip-l2tp}}<br />
|-<br />
| ip link || network device configuration || {{man|8|ip-link}}<br />
|-<br />
| ip maddr || multicast addresses management || {{man|8|ip-maddress}}<br />
|-<br />
| ip monitor || watch for netlink messages || {{man|8|ip-monitor}}<br />
|-<br />
| ip mroute || multicast routing cache management || {{man|8|ip-mroute}}<br />
|-<br />
| ip mrule || rule in multicast routing policy db ||<br />
|-<br />
| ip neigh || neighbour/ARP tables management || {{man|8|ip-neighbour}}<br />
|-<br />
| ip netns || process network namespace management || {{man|8|ip-netns}}<br />
|-<br />
| ip ntable || neighbour table configuration || {{man|8|ip-ntable}}<br />
|-<br />
| ip route || routing table management || {{man|8|ip-route}}<br />
|-<br />
| ip rule || routing policy database management || {{man|8|ip-rule}}<br />
|-<br />
| ip tcp_metrics || management for TCP Metrics || {{man|8|ip-tcp_metrics}}<br />
|-<br />
| ip tunnel || tunnel configuration || {{man|8|ip-tunnel}}<br />
|-<br />
| ip tuntap || manage TUN/TAP devices ||<br />
|-<br />
| ip xfrm || manage IPsec policies || {{man|8|ip-xfrm}}<br />
|}<br />
<br />
The {{ic|help}} command is available for all objects. For example, typing {{ic|ip addr help}} will show you the command syntax available for the address object. For advanced usage see the [http://www.policyrouting.org/iproute2.doc.html iproute2 documentation].<br />
<br />
The [[Network configuration]] article shows how the ''ip'' command is used in practice for various common tasks.<br />
<br />
{{Note|You might be familiar with the [[Wikipedia:ifconfig|ifconfig]] command, which was used in older versions of Linux for interface configuration. It is now deprecated in Arch Linux; you should use ''ip'' instead. }}<br />
<br />
== locate ==<br />
<br />
[[Install]] the {{Pkg|mlocate}} package. The package contains an {{ic|updatedb.timer}} unit, which invokes a database update each day. The timer is enabled right after installation, [[start]] it manually if you want to use it before reboot. You can also manually run ''updatedb'' as root at any time. By default, paths such as {{ic|/media}} and {{ic|/mnt}} are ignored, so ''locate'' may not discover files on external devices. See {{man|8|updatedb}} for details.<br />
<br />
The ''locate'' command is a common Unix tool for quickly finding files by name. It offers speed improvements over the [[wikipedia:Find|find]] tool by searching a pre-constructed database file, rather than the filesystem directly. The downside of this approach is that changes made since the construction of the database file cannot be detected by ''locate''.<br />
<br />
Before ''locate'' can be used, the database will need to be created. To do this, execute {{ic|updatedb}} as root.<br />
<br />
See also [http://jvns.ca/blog/2015/03/05/how-the-locate-command-works-and-lets-rewrite-it-in-one-minute/ How locate works and rewrite it in one minute].<br />
<br />
== less ==<br />
<br />
{{Expansion|less is a complex beast, and this section should explain some of the basic less commands}}<br />
<br />
[[Wikipedia:less (Unix)|less]] is a terminal pager program used to view the contents of a text file one screen at a time. Whilst similar to other pagers such as [[Wikipedia:more (command)|more]] and [[Wikipedia:pg (Unix)|pg]], ''less'' offers a more advanced interface and complete [http://www.greenwoodsoftware.com/less/faq.html feature-set].<br />
<br />
See [[List of applications#Terminal pagers]] for alternatives.<br />
<br />
=== Vim as alternative pager ===<br />
<br />
[[Vim]] includes a script to view the content of text files, compressed files, binaries and directories. Add the following line to your shell configuration file to use it as a pager:<br />
{{hc|~/.bashrc|2=alias less='/usr/share/vim/vim80/macros/less.sh'}}<br />
<br />
There is also an alternative to the ''less.sh'' macro, which may work as the {{ic|PAGER}} environment variable. Install {{Pkg|vimpager}} and add the following to your shell configuration file:<br />
{{hc|~/.bashrc|2=<br />
export PAGER='vimpager'<br />
alias less=$PAGER<br />
}}<br />
<br />
Now programs that use the {{ic|PAGER}} environment variable, like [[git]], will use ''vim'' as pager.<br />
<br />
== ls ==<br />
<br />
[[Wikipedia:ls|ls]] lists directory contents.<br />
<br />
See {{ic|info ls}} or [https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation the online manual] for more information.<br />
<br />
[https://the.exa.website exa] is a modern, and more user friendly alternative to {{ic|ls}} and {{ic|tree}}, that has more features, such as displaying [[Git]] modifications along with filenames, colouring differently each columnn in {{ic|--long}} mode, or displaying {{ic|--long}} mode metadata along with a {{ic|tree}} view. {{Pkg|exa}}<br />
=== Long format ===<br />
<br />
The {{ic|-l}} option displays some metadata, for example:<br />
<br />
{{hc|$ ls -l ''/path/to/directory''|<br />
total 128<br />
drwxr-xr-x 2 archie users 4096 Jul 5 21:03 Desktop<br />
drwxr-xr-x 6 archie users 4096 Jul 5 17:37 Documents<br />
drwxr-xr-x 2 archie users 4096 Jul 5 13:45 Downloads<br />
-rw-rw-r-- 1 archie users 5120 Jun 27 08:28 customers.ods<br />
-rw-r--r-- 1 archie users 3339 Jun 27 08:28 todo<br />
-rwxr-xr-x 1 archie users 2048 Jul 6 12:56 myscript.sh<br />
}}<br />
<br />
The {{ic|total}} value represents the total disk allocation for the files in the directory, by default in number of blocks.<br />
<br />
Below, each file and subdirectory is represented by a line divided into 7 metadata fields, in the following order:<br />
<br />
* type and permissions:<br />
** the first character is the entry type, see {{ic|info ls -n "What information is listed"}} for an explanation of all the possible types; for example:<br />
*** {{ic|-}} denotes a normal file;<br />
*** {{ic|d}} denotes a directory, i.e. a folder containing other files or folders;<br />
*** {{ic|p}} denotes a named pipe (aka FIFO);<br />
*** {{ic|l}} denotes a symbolic link;<br />
** the remaining characters are the entry's [[permissions]];<br />
* number of [[Wikipedia:Hard link|hard links]] for the entity; files will have at least 1, i.e. the showed reference itself; folders will have at least 2: the showed reference, the self-referencing {{ic|.}} entry, and then a {{ic|..}} entry in each of its subfolders;<br />
* owner [[user]] name;<br />
* [[group]] name;<br />
* size;<br />
* last modification timestamp;<br />
* entity name.<br />
<br />
=== File names containing spaces enclosed in quotes ===<br />
<br />
By default, file and directory names that contain spaces are displayed surrounded by single quotes. To change this behavior use the {{ic|-N}} or {{ic|1=--quoting-style=literal}} options. Alternatively, set the {{ic|QUOTING_STYLE}} [[environment variable]] to {{ic|literal}}. [https://unix.stackexchange.com/questions/258679/why-is-ls-suddenly-surrounding-items-with-spaces-in-single-quotes]<br />
<br />
== lsblk ==<br />
<br />
{{man|8|lsblk}} will show all available [[w:Device_file#Block_devices|block devices]] along with their partitioning schemes, for example:<br />
<br />
{{hc|$ lsblk -f|<br />
NAME FSTYPE LABEL UUID MOUNTPOINT<br />
sda<br />
├─sda1 vfat C4DA-2C4D /boot<br />
├─sda2 swap 5b1564b2-2e2c-452c-bcfa-d1f572ae99f2 [SWAP]<br />
└─sda3 ext4 56adc99b-a61e-46af-aab7-a6d07e504652 /<br />
}}<br />
<br />
The beginning of the device name specifies the type of block device. Most modern storage devices (e.g. hard disks, [[SSD]]s and USB flash drives) are recognised as SCSI disks ({{ic|sd}}). The type is followed by a lower-case letter starting from {{ic|a}} for the first device ({{ic|sda}}), {{ic|b}} for the second device ({{ic|sdb}}), and so on. ''Existing'' partitions on each device will be listed with a number starting from {{ic|1}} for the first partition ({{ic|sda1}}), {{ic|2}} for the second ({{ic|sda2}}), and so on. In the example above, only one device is available ({{ic|sda}}), and that device has three partitions ({{ic|sda1}} to {{ic|sda3}}), each with a different [[file system]].<br />
<br />
Other common block device types include for example {{ic|mmcblk}} for memory cards and {{ic|nvme}} for [[NVMe]] devices. Unknown types can be searched in the [https://www.kernel.org/doc/Documentation/devices.txt kernel documentation]{{Dead link|2017|11|11}}.<br />
<br />
== mkdir ==<br />
<br />
[[Wikipedia:mkdir|mkdir]] makes directories.<br />
<br />
To create a directory and its whole hierarchy, the {{ic|-p}} switch is used, otherwise an error is printed. As users are supposed to know what they want, {{ic|-p}} switch may be used as a default:<br />
<br />
alias mkdir='mkdir -p -v'<br />
<br />
The {{ic|-v}} switch make it verbose.<br />
<br />
Changing mode of a just created directory using ''chmod'' is not necessary as the {{ic|-m}} option lets you define the access permissions.<br />
<br />
{{Tip|If you just want a temporary directory, a better alternative may be [[Wikipedia:Temporary file|mktemp]]: {{ic|mktemp -p}}.}}<br />
<br />
== mv ==<br />
<br />
[[Wikipedia:mv|mv]] moves and renames files and directories.<br />
<br />
To limit potential damage caused by the command, use an alias:<br />
<br />
alias mv='timeout 8 mv -iv'<br />
<br />
This alias suspends ''mv'' after eight seconds, asks for confirmation before overwriting any existing files, lists the operations in progress and does not store itself in the shell history file if the shell is configured to ignore space starting commands.<br />
<br />
== od ==<br />
<br />
The [[Wikipedia:od (Unix)|od]] (''o''ctal ''d''ump) command is useful for visualizing data that is not in a human-readable format, like the executable code of a program, or the contents of an unformatted device. See the [https://www.gnu.org/software/coreutils/manual/html_node/od-invocation.html#od-invocation manual] for more information.<br />
<br />
== pv ==<br />
<br />
You can use {{Pkg|pv}} (''pipe viewer'') to monitor the progress of data through a pipeline, for example:<br />
<br />
# dd if=''/source/filestream'' | pv -''monitor_options'' -s ''size_of_file'' | dd of=''/destination/filestream''<br />
<br />
In most cases {{ic|pv}} functions as a drop-in replacement for {{ic|cat}}.<br />
<br />
== rm ==<br />
<br />
[[Wikipedia:rm_(Unix)|rm]] removes files or directories.<br />
<br />
To limit potential damage caused by the command, use an alias:<br />
<br />
alias rm='timeout 3 rm -Iv --one-file-system'<br />
<br />
This alias suspends ''rm'' after three seconds, asks confirmation to delete three or more files, lists the operations in progress, does not involve more than one file systems and does not store itself in the shell history file if the shell is configured to ignore space starting commands. Substitute {{ic|-I}} with {{ic|-i}} if you prefer to confirm even for one file.<br />
<br />
Zsh users may want to put {{ic|noglob}} before {{ic|timeout}} to avoid implicit expansions.<br />
<br />
To remove directories believed to be empty, use ''rmdir'' as it fails if there are files inside the target.<br />
<br />
== sed ==<br />
<br />
[[Wikipedia:sed|sed]] is stream editor for filtering and transforming text.<br />
<br />
Here is a handy [http://sed.sourceforge.net/sed1line.txt list] of ''sed'' one-liners examples.<br />
<br />
{{Tip|More powerful alternatives are [[Wikipedia:AWK|AWK]] and the [[Wikipedia:Perl|Perl]] language.}}<br />
<br />
== seq ==<br />
<br />
''seq'' prints a sequence of numbers. Shell built-in alternatives are available, so it is good practice to use them as explained on [[Wikipedia:Seq (Unix)|Wikipedia]].<br />
<br />
== ss ==<br />
<br />
''ss'' is a utility to investigate network ports and is part of the {{Pkg|iproute2}} package in the {{Grp|base}} group. It has a similar functionality to the [https://www.archlinux.org/news/deprecation-of-net-tools/ deprecated] netstat utility. <br />
<br />
Common usage includes:<br />
<br />
Display all TCP Sockets with service names:<br />
$ ss -at<br />
<br />
Display all TCP Sockets with port numbers:<br />
$ ss -atn<br />
<br />
Display all UDP Sockets:<br />
$ ss -au<br />
<br />
For more information see {{man|8|ss}} or {{ic|ss.html}} from the {{Pkg|iproute2}} package.<br />
<br />
== tar ==<br />
<br />
As an early Unix archiving format, .tar files—known as "tarballs"—are widely used for packaging in Unix-like operating systems. Both [[pacman]] and [[AUR]] packages are compressed tarballs, and Arch uses [[GNU Project|GNU's]] ''tar'' program by default. <br />
<br />
For .tar archives, ''tar'' by default will extract the file according to its extension:<br />
<br />
$ tar xvf ''file.EXTENSION''<br />
<br />
Forcing a given format:<br />
<br />
{| class="wikitable"<br />
!File Type !! Extraction Command<br />
|-<br />
|{{ic|''file''.tar}} || {{Ic|tar xvf ''file''.tar}}<br />
|-<br />
|{{ic|''file''.tgz}} || {{Ic|tar xvzf ''file''.tgz}}<br />
|-<br />
|{{ic|''file''.tar.gz}} || {{Ic|tar xvzf ''file''.tar.gz}}<br />
|-<br />
|{{ic|''file''.tar.bz}} || {{Ic|bzip -cd ''file''.bz <nowiki>|</nowiki> tar xvf -}}<br />
|-<br />
|{{ic|''file''.tar.bz2}} || {{Ic|tar xvjf ''file''.tar.bz2}}<br> {{Ic|bzip2 -cd ''file''.bz2 <nowiki>| tar xvf -</nowiki>}}<br />
|-<br />
|{{ic|''file''.tar.xz}} || {{Ic|tar xvJf ''file''.tar.xz}}<br> {{Ic|xz -cd ''file''.xz <nowiki>| tar xvf -</nowiki>}}<br />
|}<br />
<br />
The construction of some of these ''tar'' arguments may be considered legacy, but they are still useful when performing specific operations. See {{man|1|tar}} for details.<br />
<br />
== which ==<br />
<br />
[[wikipedia:Which_(Unix)|which]] shows the full path of shell commands. In the following example the full path of {{ic|ssh}} is used as an argument for {{ic|journalctl}}:<br />
<br />
# journalctl $(which sshd)<br />
<br />
== wipefs ==<br />
<br />
''wipefs'' can list or erase [[file system]], [[RAID]] or [[partition|partition-table]] signatures (magic strings) from the specified device. It does not erase the file systems themselves nor any other data from the device.<br />
<br />
See {{man|8|wipefs}} for more information.<br />
<br />
For example, to erase all signatures from the device {{ic|/dev/sdb}} and create a signature backup {{ic|~/wipefs-sdb-''offset''.bak}} file for each signature:<br />
<br />
# wipefs --all --backup /dev/sdb<br />
<br />
== See also ==<br />
<br />
* [http://www.reddit.com/r/commandline/comments/19garq/a_sampling_of_coreutils_120/ A sampling of coreutils] [http://www.reddit.com/r/commandline/comments/19ge6v/a_sampling_of_coreutils_2040/ , part 2] [http://www.reddit.com/r/commandline/comments/19j1w3/a_sampling_of_coreutils_4060/ , part 3] - Overview of commands in coreutils<br />
* [https://www.gnu.org/software/coreutils/manual/coreutils.html GNU Coreutils online documentation]<br />
* [https://www.linuxquestions.org/questions/linux-newbie-8/learn-the-dd-command-362506/ Learn the DD command]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=Core_utilities&diff=510716Core utilities2018-02-13T22:09:57Z<p>JoshuaRLi: find: formatting tip as actual Tip, replacing GitHub link with official package link</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:Command shells]]<br />
[[fa:Core utilities]]<br />
[[es:Core utilities]]<br />
[[it:Core utilities]]<br />
[[ja:Core Utilities]]<br />
[[ko:Core utilities]]<br />
[[pt:Core utilities]]<br />
[[ru:Core utilities]]<br />
[[zh-hans:Core utilities]]<br />
[[zh-hant:Core utilities]]<br />
{{Related articles start}}<br />
{{Related|Bash}}<br />
{{Related|Zsh}}<br />
{{Related|General recommendations}}<br />
{{Related|GNU Project}}<br />
{{Related|sudo}}<br />
{{Related|cron}}<br />
{{Related|man page}}<br />
{{Related|Securely wipe disk#shred}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Color output in console}}<br />
{{Related articles end}}<br />
<br />
This article deals with so-called ''core'' utilities on a GNU/Linux system, such as ''less'', ''ls'', and ''grep''. The scope of this article includes, but is not limited to, those utilities included with the GNU {{Pkg|coreutils}} package. What follows are various tips and tricks and other helpful information related to these utilities.<br />
<br />
== Basic commands ==<br />
<br />
The following table lists basic shell commands every Linux user should be familiar with. See the below sections and ''Related articles'' for details.<br />
<br />
{| class="wikitable"<br />
! Command<br />
! Description<br />
! Manual page<br />
! Example<br />
|-<br />
| man<br />
| Show manual page for a command<br />
| {{man|7|man}}<br />
| man ed<br />
|-<br />
| cd<br />
| Change directory (shell built-in command)<br />
| {{man|1p|cd}}<br />
| cd /etc/pacman.d<br />
|-<br />
| mkdir<br />
| Create a directory<br />
| {{man|1|mkdir}}<br />
| mkdir ~/newfolder<br />
|-<br />
| rmdir<br />
| Remove empty directory<br />
| {{man|1|rmdir}}<br />
| rmdir ~/emptyfolder<br />
|-<br />
| rm<br />
| Remove a file<br />
| {{man|1|rm}}<br />
| rm ~/file.txt<br />
|-<br />
| rm -r<br />
| Remove directory and contents<br />
|<br />
| rm -r ~/.cache<br />
|-<br />
| ls<br />
| List files<br />
| {{man|1|ls}}<br />
| ls *.mkv<br />
|-<br />
| ls -a<br />
| List hidden files<br />
|<br />
| ls -a /home/archie<br />
|-<br />
| ls -al<br />
| List hidden files and file properties<br />
|<br />
|<br />
|-<br />
| mv<br />
| Move a file<br />
| {{man|1|mv}}<br />
| mv ~/compressed.zip ~/archive/compressed2.zip<br />
|-<br />
| cp<br />
| Copy a file<br />
| {{man|1|cp}}<br />
| cp ~/.bashrc ~/.bashrc.bak<br />
|-<br />
| chmod +x<br />
| Make a file [[executable]]<br />
| {{man|1|chmod}}<br />
| chmod +x ~/.local/bin/myscript.sh<br />
|-<br />
| cat<br />
| Show file contents<br />
| {{man|1|cat}}<br />
| cat /etc/hostname<br />
|-<br />
| strings<br />
| Show printable characters in binary files<br />
| {{man|1|strings}}<br />
| strings /usr/bin/free<br />
|-<br />
| find<br />
| Search for a file<br />
| {{man|1|find}}<br />
| find ~ -name myfile<br />
|-<br />
| mount<br />
| Mount a partition<br />
| {{man|8|mount}}<br />
| mount /dev/sdc1 /media/usb<br />
|-<br />
| df -h<br />
| Show remaining space on all partitions<br />
| {{man|1|df}}<br />
|<br />
|-<br />
| ps -A<br />
| Show all running processes<br />
| {{man|1|ps}}<br />
|<br />
|-<br />
| killall<br />
| Kill all running instances of a process<br />
| {{man|1|killall}}<br />
|<br />
|-<br />
| ss -at<br />
| Display a list of open TCP sockets<br />
| {{man|8|ss}}<br />
|<br />
|}<br />
<br />
== cat ==<br />
<br />
[[Wikipedia:cat_(Unix)|cat]] is a standard Unix utility that concatenates and lists files.<br />
<br />
* Because ''cat'' is not built into the shell, on many occasions you may find it more convenient to use a [[Wikipedia:Redirection (computing)|redirection]], for example in scripts, or if you care a lot about performance. In fact {{ic|< ''file''}} does the same as {{ic|cat ''file''}}.<br />
<br />
* ''cat'' is able to work with multiple lines:<br />
<br />
{{bc|<br />
$ cat << EOF >> ''path/file''<br />
''first line''<br />
...<br />
''last line''<br />
EOF<br />
}}<br />
<br />
Alternatively, using {{ic|printf}}:<br />
<br />
{{bc|<br />
$ printf '%s\n' 'first line' ... 'last line'<br />
}}<br />
<br />
* If you need to list file lines in reverse order, there is a utility called [[Wikipedia:tac (Unix)|tac]] (''cat'' reversed).<br />
<br />
== dd ==<br />
<br />
[[Wikipedia:dd (Unix)|dd]] is a utility for Unix and Unix-like operating systems whose primary purpose is to convert and copy a file.<br />
<br />
Similarly to ''cp'', by default ''dd'' makes a bit-to-bit copy of the file, but with lower-level I/O flow control features.<br />
<br />
{{Tip|By default, ''dd'' outputs nothing until the task has finished. To monitor the progress of the operation, add the {{ic|1=status=progress}} option to the command.}}<br />
<br />
For more information see {{man|1|dd}} or the [https://www.gnu.org/software/coreutils/dd full documentation].<br />
<br />
== grep ==<br />
<br />
[[Wikipedia:grep|grep]] (from [[Wikipedia:Ed_(text_editor)|ed]]'s ''g/re/p'', ''global/regular expression/print'') is a command line text search utility originally written for Unix. The ''grep'' command searches files or standard input for lines matching a given regular expression, and prints these lines to the program's standard output.<br />
<br />
* Remember that ''grep'' handles files, so a construct like {{ic|cat ''file'' <nowiki>|</nowiki> grep ''pattern''}} is replaceable with {{ic|grep ''pattern'' ''file''}}<br />
* There are ''grep'' alternatives optimized for VCS source code, such as {{Pkg|ripgrep}}, {{Pkg|the_silver_searcher}}, and {{Pkg|ack}}.<br />
* To include file line numbers in the output, use the {{ic|-n}} option. <br />
<br />
{{Note|Some commands send their output to {{man|3|stderr}}, and grep has no apparent effect. In this case, redirect ''stderr'' to ''stdout'' with {{ic|''command'' 2>&1 {{!}} grep ''args''}} or (for Bash 4) {{ic|''command'' {{!}}& grep ''args''}}. See also [http://www.tldp.org/LDP/abs/html/io-redirection.html I/O Redirection].}}<br />
<br />
For color support, see [[Color output in console#grep]].<br />
<br />
== find ==<br />
<br />
''find'' is part of the {{Pkg|findutils}} package, which belongs to the {{Grp|base}} package group. <br />
<br />
{{Tip|{{Pkg|fd}} is a modern and user friendly alternative to {{ic|find}}, that tries to improve performance, and offer more friendly defaults. For example {{ic|fd PATTERN}} instead of {{ic|find -iname '*PATTERN*'}}. It features colorized output (similar to {{ic|ls}}), smart-case search by default, hidden files ignoring, and more.}}<br />
<br />
One would probably expect a ''find'' command to take as argument a file name and search the filesystem for files matching that name. For a program that does exactly that see [[#locate]] below. <br />
<br />
Instead, find takes a set of directories and matches each file under them against a set of expressions. This design allows for some very powerful "one-liners" that would not be possible using the "intuitive" design described above. See [http://mywiki.wooledge.org/UsingFind UsingFind] for usage details.<br />
<br />
== iconv ==<br />
<br />
''iconv'' converts the encoding of characters from one codeset to another.<br />
<br />
The following command will convert the file {{ic|''foo''}} from ISO-8859-15 to UTF-8, saving it to {{ic|''foo''.utf}}:<br />
<br />
$ iconv -f ISO-8859-15 -t UTF-8 ''foo'' > ''foo''.utf<br />
<br />
See {{man|1|iconv}} for more details.<br />
<br />
=== Convert a file in place ===<br />
<br />
{{Tip|You can use {{pkg|recode}} instead of iconv if you do not want to touch the mtime.}}<br />
Unlike [[#sed|sed]], ''iconv'' does not provide an option to convert a file in place. However, {{ic|sponge}} from the {{pkg|moreutils}} package can help:<br />
<br />
$ iconv -f WINDOWS-1251 -t UTF-8 ''foobar''.txt | sponge ''foobar''.txt<br />
<br />
See {{man|1|sponge}} for details.<br />
<br />
== ip ==<br />
<br />
[[Wikipedia:Iproute2|ip]] allows you to show information about network devices, IP addresses, routing tables, and other objects in the Linux [[Wikipedia:Internet Protocol|IP]] software stack. By appending various commands, you can also manipulate or configure most of these objects.<br />
<br />
{{Note|The ''ip'' utility is provided by the {{Pkg|iproute2}} package, which is included in the {{Grp|base}} group.}}<br />
<br />
{| class="wikitable"<br />
! Object !! Purpose !! Manual page<br />
|-<br />
| ip addr || protocol address management || {{man|8|ip-address}}<br />
|-<br />
| ip addrlabel || protocol address label management || {{man|8|ip-addrlabel}}<br />
|-<br />
| ip l2tp || tunnel Ethernet over IP (L2TPv3) || {{man|8|ip-l2tp}}<br />
|-<br />
| ip link || network device configuration || {{man|8|ip-link}}<br />
|-<br />
| ip maddr || multicast addresses management || {{man|8|ip-maddress}}<br />
|-<br />
| ip monitor || watch for netlink messages || {{man|8|ip-monitor}}<br />
|-<br />
| ip mroute || multicast routing cache management || {{man|8|ip-mroute}}<br />
|-<br />
| ip mrule || rule in multicast routing policy db ||<br />
|-<br />
| ip neigh || neighbour/ARP tables management || {{man|8|ip-neighbour}}<br />
|-<br />
| ip netns || process network namespace management || {{man|8|ip-netns}}<br />
|-<br />
| ip ntable || neighbour table configuration || {{man|8|ip-ntable}}<br />
|-<br />
| ip route || routing table management || {{man|8|ip-route}}<br />
|-<br />
| ip rule || routing policy database management || {{man|8|ip-rule}}<br />
|-<br />
| ip tcp_metrics || management for TCP Metrics || {{man|8|ip-tcp_metrics}}<br />
|-<br />
| ip tunnel || tunnel configuration || {{man|8|ip-tunnel}}<br />
|-<br />
| ip tuntap || manage TUN/TAP devices ||<br />
|-<br />
| ip xfrm || manage IPsec policies || {{man|8|ip-xfrm}}<br />
|}<br />
<br />
The {{ic|help}} command is available for all objects. For example, typing {{ic|ip addr help}} will show you the command syntax available for the address object. For advanced usage see the [http://www.policyrouting.org/iproute2.doc.html iproute2 documentation].<br />
<br />
The [[Network configuration]] article shows how the ''ip'' command is used in practice for various common tasks.<br />
<br />
{{Note|You might be familiar with the [[Wikipedia:ifconfig|ifconfig]] command, which was used in older versions of Linux for interface configuration. It is now deprecated in Arch Linux; you should use ''ip'' instead. }}<br />
<br />
== locate ==<br />
<br />
[[Install]] the {{Pkg|mlocate}} package. The package contains an {{ic|updatedb.timer}} unit, which invokes a database update each day. The timer is enabled right after installation, [[start]] it manually if you want to use it before reboot. You can also manually run ''updatedb'' as root at any time. By default, paths such as {{ic|/media}} and {{ic|/mnt}} are ignored, so ''locate'' may not discover files on external devices. See {{man|8|updatedb}} for details.<br />
<br />
The ''locate'' command is a common Unix tool for quickly finding files by name. It offers speed improvements over the [[wikipedia:Find|find]] tool by searching a pre-constructed database file, rather than the filesystem directly. The downside of this approach is that changes made since the construction of the database file cannot be detected by ''locate''.<br />
<br />
Before ''locate'' can be used, the database will need to be created. To do this, execute {{ic|updatedb}} as root.<br />
<br />
See also [http://jvns.ca/blog/2015/03/05/how-the-locate-command-works-and-lets-rewrite-it-in-one-minute/ How locate works and rewrite it in one minute].<br />
<br />
== less ==<br />
<br />
{{Expansion|less is a complex beast, and this section should explain some of the basic less commands}}<br />
<br />
[[Wikipedia:less (Unix)|less]] is a terminal pager program used to view the contents of a text file one screen at a time. Whilst similar to other pagers such as [[Wikipedia:more (command)|more]] and [[Wikipedia:pg (Unix)|pg]], ''less'' offers a more advanced interface and complete [http://www.greenwoodsoftware.com/less/faq.html feature-set].<br />
<br />
See [[List of applications#Terminal pagers]] for alternatives.<br />
<br />
=== Vim as alternative pager ===<br />
<br />
[[Vim]] includes a script to view the content of text files, compressed files, binaries and directories. Add the following line to your shell configuration file to use it as a pager:<br />
{{hc|~/.bashrc|2=alias less='/usr/share/vim/vim80/macros/less.sh'}}<br />
<br />
There is also an alternative to the ''less.sh'' macro, which may work as the {{ic|PAGER}} environment variable. Install {{Pkg|vimpager}} and add the following to your shell configuration file:<br />
{{hc|~/.bashrc|2=<br />
export PAGER='vimpager'<br />
alias less=$PAGER<br />
}}<br />
<br />
Now programs that use the {{ic|PAGER}} environment variable, like [[git]], will use ''vim'' as pager.<br />
<br />
== ls ==<br />
<br />
[[Wikipedia:ls|ls]] lists directory contents.<br />
<br />
See {{ic|info ls}} or [https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation the online manual] for more information.<br />
<br />
[https://the.exa.website exa] is a modern, and more user friendly alternative to {{ic|ls}} and {{ic|tree}}, that has more features, such as displaying [[Git]] modifications along with filenames, colouring differently each columnn in {{ic|--long}} mode, or displaying {{ic|--long}} mode metadata along with a {{ic|tree}} view. {{Pkg|exa}}<br />
=== Long format ===<br />
<br />
The {{ic|-l}} option displays some metadata, for example:<br />
<br />
{{hc|$ ls -l ''/path/to/directory''|<br />
total 128<br />
drwxr-xr-x 2 archie users 4096 Jul 5 21:03 Desktop<br />
drwxr-xr-x 6 archie users 4096 Jul 5 17:37 Documents<br />
drwxr-xr-x 2 archie users 4096 Jul 5 13:45 Downloads<br />
-rw-rw-r-- 1 archie users 5120 Jun 27 08:28 customers.ods<br />
-rw-r--r-- 1 archie users 3339 Jun 27 08:28 todo<br />
-rwxr-xr-x 1 archie users 2048 Jul 6 12:56 myscript.sh<br />
}}<br />
<br />
The {{ic|total}} value represents the total disk allocation for the files in the directory, by default in number of blocks.<br />
<br />
Below, each file and subdirectory is represented by a line divided into 7 metadata fields, in the following order:<br />
<br />
* type and permissions:<br />
** the first character is the entry type, see {{ic|info ls -n "What information is listed"}} for an explanation of all the possible types; for example:<br />
*** {{ic|-}} denotes a normal file;<br />
*** {{ic|d}} denotes a directory, i.e. a folder containing other files or folders;<br />
*** {{ic|p}} denotes a named pipe (aka FIFO);<br />
*** {{ic|l}} denotes a symbolic link;<br />
** the remaining characters are the entry's [[permissions]];<br />
* number of [[Wikipedia:Hard link|hard links]] for the entity; files will have at least 1, i.e. the showed reference itself; folders will have at least 2: the showed reference, the self-referencing {{ic|.}} entry, and then a {{ic|..}} entry in each of its subfolders;<br />
* owner [[user]] name;<br />
* [[group]] name;<br />
* size;<br />
* last modification timestamp;<br />
* entity name.<br />
<br />
=== File names containing spaces enclosed in quotes ===<br />
<br />
By default, file and directory names that contain spaces are displayed surrounded by single quotes. To change this behavior use the {{ic|-N}} or {{ic|1=--quoting-style=literal}} options. Alternatively, set the {{ic|QUOTING_STYLE}} [[environment variable]] to {{ic|literal}}. [https://unix.stackexchange.com/questions/258679/why-is-ls-suddenly-surrounding-items-with-spaces-in-single-quotes]<br />
<br />
== lsblk ==<br />
<br />
{{man|8|lsblk}} will show all available [[w:Device_file#Block_devices|block devices]] along with their partitioning schemes, for example:<br />
<br />
{{hc|$ lsblk -f|<br />
NAME FSTYPE LABEL UUID MOUNTPOINT<br />
sda<br />
├─sda1 vfat C4DA-2C4D /boot<br />
├─sda2 swap 5b1564b2-2e2c-452c-bcfa-d1f572ae99f2 [SWAP]<br />
└─sda3 ext4 56adc99b-a61e-46af-aab7-a6d07e504652 /<br />
}}<br />
<br />
The beginning of the device name specifies the type of block device. Most modern storage devices (e.g. hard disks, [[SSD]]s and USB flash drives) are recognised as SCSI disks ({{ic|sd}}). The type is followed by a lower-case letter starting from {{ic|a}} for the first device ({{ic|sda}}), {{ic|b}} for the second device ({{ic|sdb}}), and so on. ''Existing'' partitions on each device will be listed with a number starting from {{ic|1}} for the first partition ({{ic|sda1}}), {{ic|2}} for the second ({{ic|sda2}}), and so on. In the example above, only one device is available ({{ic|sda}}), and that device has three partitions ({{ic|sda1}} to {{ic|sda3}}), each with a different [[file system]].<br />
<br />
Other common block device types include for example {{ic|mmcblk}} for memory cards and {{ic|nvme}} for [[NVMe]] devices. Unknown types can be searched in the [https://www.kernel.org/doc/Documentation/devices.txt kernel documentation]{{Dead link|2017|11|11}}.<br />
<br />
== mkdir ==<br />
<br />
[[Wikipedia:mkdir|mkdir]] makes directories.<br />
<br />
To create a directory and its whole hierarchy, the {{ic|-p}} switch is used, otherwise an error is printed. As users are supposed to know what they want, {{ic|-p}} switch may be used as a default:<br />
<br />
alias mkdir='mkdir -p -v'<br />
<br />
The {{ic|-v}} switch make it verbose.<br />
<br />
Changing mode of a just created directory using ''chmod'' is not necessary as the {{ic|-m}} option lets you define the access permissions.<br />
<br />
{{Tip|If you just want a temporary directory, a better alternative may be [[Wikipedia:Temporary file|mktemp]]: {{ic|mktemp -p}}.}}<br />
<br />
== mv ==<br />
<br />
[[Wikipedia:mv|mv]] moves and renames files and directories.<br />
<br />
To limit potential damage caused by the command, use an alias:<br />
<br />
alias mv='timeout 8 mv -iv'<br />
<br />
This alias suspends ''mv'' after eight seconds, asks for confirmation before overwriting any existing files, lists the operations in progress and does not store itself in the shell history file if the shell is configured to ignore space starting commands.<br />
<br />
== od ==<br />
<br />
The [[Wikipedia:od (Unix)|od]] (''o''ctal ''d''ump) command is useful for visualizing data that is not in a human-readable format, like the executable code of a program, or the contents of an unformatted device. See the [https://www.gnu.org/software/coreutils/manual/html_node/od-invocation.html#od-invocation manual] for more information.<br />
<br />
== pv ==<br />
<br />
You can use {{Pkg|pv}} (''pipe viewer'') to monitor the progress of data through a pipeline, for example:<br />
<br />
# dd if=''/source/filestream'' | pv -''monitor_options'' -s ''size_of_file'' | dd of=''/destination/filestream''<br />
<br />
In most cases {{ic|pv}} functions as a drop-in replacement for {{ic|cat}}.<br />
<br />
== rm ==<br />
<br />
[[Wikipedia:rm_(Unix)|rm]] removes files or directories.<br />
<br />
To limit potential damage caused by the command, use an alias:<br />
<br />
alias rm='timeout 3 rm -Iv --one-file-system'<br />
<br />
This alias suspends ''rm'' after three seconds, asks confirmation to delete three or more files, lists the operations in progress, does not involve more than one file systems and does not store itself in the shell history file if the shell is configured to ignore space starting commands. Substitute {{ic|-I}} with {{ic|-i}} if you prefer to confirm even for one file.<br />
<br />
Zsh users may want to put {{ic|noglob}} before {{ic|timeout}} to avoid implicit expansions.<br />
<br />
To remove directories believed to be empty, use ''rmdir'' as it fails if there are files inside the target.<br />
<br />
== sed ==<br />
<br />
[[Wikipedia:sed|sed]] is stream editor for filtering and transforming text.<br />
<br />
Here is a handy [http://sed.sourceforge.net/sed1line.txt list] of ''sed'' one-liners examples.<br />
<br />
{{Tip|More powerful alternatives are [[Wikipedia:AWK|AWK]] and the [[Wikipedia:Perl|Perl]] language.}}<br />
<br />
== seq ==<br />
<br />
''seq'' prints a sequence of numbers. Shell built-in alternatives are available, so it is good practice to use them as explained on [[Wikipedia:Seq (Unix)|Wikipedia]].<br />
<br />
== ss ==<br />
<br />
''ss'' is a utility to investigate network ports and is part of the {{Pkg|iproute2}} package in the {{Grp|base}} group. It has a similar functionality to the [https://www.archlinux.org/news/deprecation-of-net-tools/ deprecated] netstat utility. <br />
<br />
Common usage includes:<br />
<br />
Display all TCP Sockets with service names:<br />
$ ss -at<br />
<br />
Display all TCP Sockets with port numbers:<br />
$ ss -atn<br />
<br />
Display all UDP Sockets:<br />
$ ss -au<br />
<br />
For more information see {{man|8|ss}} or {{ic|ss.html}} from the {{Pkg|iproute2}} package.<br />
<br />
== tar ==<br />
<br />
As an early Unix archiving format, .tar files—known as "tarballs"—are widely used for packaging in Unix-like operating systems. Both [[pacman]] and [[AUR]] packages are compressed tarballs, and Arch uses [[GNU Project|GNU's]] ''tar'' program by default. <br />
<br />
For .tar archives, ''tar'' by default will extract the file according to its extension:<br />
<br />
$ tar xvf ''file.EXTENSION''<br />
<br />
Forcing a given format:<br />
<br />
{| class="wikitable"<br />
!File Type !! Extraction Command<br />
|-<br />
|{{ic|''file''.tar}} || {{Ic|tar xvf ''file''.tar}}<br />
|-<br />
|{{ic|''file''.tgz}} || {{Ic|tar xvzf ''file''.tgz}}<br />
|-<br />
|{{ic|''file''.tar.gz}} || {{Ic|tar xvzf ''file''.tar.gz}}<br />
|-<br />
|{{ic|''file''.tar.bz}} || {{Ic|bzip -cd ''file''.bz <nowiki>|</nowiki> tar xvf -}}<br />
|-<br />
|{{ic|''file''.tar.bz2}} || {{Ic|tar xvjf ''file''.tar.bz2}}<br> {{Ic|bzip2 -cd ''file''.bz2 <nowiki>| tar xvf -</nowiki>}}<br />
|-<br />
|{{ic|''file''.tar.xz}} || {{Ic|tar xvJf ''file''.tar.xz}}<br> {{Ic|xz -cd ''file''.xz <nowiki>| tar xvf -</nowiki>}}<br />
|}<br />
<br />
The construction of some of these ''tar'' arguments may be considered legacy, but they are still useful when performing specific operations. See {{man|1|tar}} for details.<br />
<br />
== which ==<br />
<br />
[[wikipedia:Which_(Unix)|which]] shows the full path of shell commands. In the following example the full path of {{ic|ssh}} is used as an argument for {{ic|journalctl}}:<br />
<br />
# journalctl $(which sshd)<br />
<br />
== wipefs ==<br />
<br />
''wipefs'' can list or erase [[file system]], [[RAID]] or [[partition|partition-table]] signatures (magic strings) from the specified device. It does not erase the file systems themselves nor any other data from the device.<br />
<br />
See {{man|8|wipefs}} for more information.<br />
<br />
For example, to erase all signatures from the device {{ic|/dev/sdb}} and create a signature backup {{ic|~/wipefs-sdb-''offset''.bak}} file for each signature:<br />
<br />
# wipefs --all --backup /dev/sdb<br />
<br />
== See also ==<br />
<br />
* [http://www.reddit.com/r/commandline/comments/19garq/a_sampling_of_coreutils_120/ A sampling of coreutils] [http://www.reddit.com/r/commandline/comments/19ge6v/a_sampling_of_coreutils_2040/ , part 2] [http://www.reddit.com/r/commandline/comments/19j1w3/a_sampling_of_coreutils_4060/ , part 3] - Overview of commands in coreutils<br />
* [https://www.gnu.org/software/coreutils/manual/coreutils.html GNU Coreutils online documentation]<br />
* [https://www.linuxquestions.org/questions/linux-newbie-8/learn-the-dd-command-362506/ Learn the DD command]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=Core_utilities&diff=510715Core utilities2018-02-13T22:06:54Z<p>JoshuaRLi: Adding ripgrep, a very popular grep alternative.</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:Command shells]]<br />
[[fa:Core utilities]]<br />
[[es:Core utilities]]<br />
[[it:Core utilities]]<br />
[[ja:Core Utilities]]<br />
[[ko:Core utilities]]<br />
[[pt:Core utilities]]<br />
[[ru:Core utilities]]<br />
[[zh-hans:Core utilities]]<br />
[[zh-hant:Core utilities]]<br />
{{Related articles start}}<br />
{{Related|Bash}}<br />
{{Related|Zsh}}<br />
{{Related|General recommendations}}<br />
{{Related|GNU Project}}<br />
{{Related|sudo}}<br />
{{Related|cron}}<br />
{{Related|man page}}<br />
{{Related|Securely wipe disk#shred}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Color output in console}}<br />
{{Related articles end}}<br />
<br />
This article deals with so-called ''core'' utilities on a GNU/Linux system, such as ''less'', ''ls'', and ''grep''. The scope of this article includes, but is not limited to, those utilities included with the GNU {{Pkg|coreutils}} package. What follows are various tips and tricks and other helpful information related to these utilities.<br />
<br />
== Basic commands ==<br />
<br />
The following table lists basic shell commands every Linux user should be familiar with. See the below sections and ''Related articles'' for details.<br />
<br />
{| class="wikitable"<br />
! Command<br />
! Description<br />
! Manual page<br />
! Example<br />
|-<br />
| man<br />
| Show manual page for a command<br />
| {{man|7|man}}<br />
| man ed<br />
|-<br />
| cd<br />
| Change directory (shell built-in command)<br />
| {{man|1p|cd}}<br />
| cd /etc/pacman.d<br />
|-<br />
| mkdir<br />
| Create a directory<br />
| {{man|1|mkdir}}<br />
| mkdir ~/newfolder<br />
|-<br />
| rmdir<br />
| Remove empty directory<br />
| {{man|1|rmdir}}<br />
| rmdir ~/emptyfolder<br />
|-<br />
| rm<br />
| Remove a file<br />
| {{man|1|rm}}<br />
| rm ~/file.txt<br />
|-<br />
| rm -r<br />
| Remove directory and contents<br />
|<br />
| rm -r ~/.cache<br />
|-<br />
| ls<br />
| List files<br />
| {{man|1|ls}}<br />
| ls *.mkv<br />
|-<br />
| ls -a<br />
| List hidden files<br />
|<br />
| ls -a /home/archie<br />
|-<br />
| ls -al<br />
| List hidden files and file properties<br />
|<br />
|<br />
|-<br />
| mv<br />
| Move a file<br />
| {{man|1|mv}}<br />
| mv ~/compressed.zip ~/archive/compressed2.zip<br />
|-<br />
| cp<br />
| Copy a file<br />
| {{man|1|cp}}<br />
| cp ~/.bashrc ~/.bashrc.bak<br />
|-<br />
| chmod +x<br />
| Make a file [[executable]]<br />
| {{man|1|chmod}}<br />
| chmod +x ~/.local/bin/myscript.sh<br />
|-<br />
| cat<br />
| Show file contents<br />
| {{man|1|cat}}<br />
| cat /etc/hostname<br />
|-<br />
| strings<br />
| Show printable characters in binary files<br />
| {{man|1|strings}}<br />
| strings /usr/bin/free<br />
|-<br />
| find<br />
| Search for a file<br />
| {{man|1|find}}<br />
| find ~ -name myfile<br />
|-<br />
| mount<br />
| Mount a partition<br />
| {{man|8|mount}}<br />
| mount /dev/sdc1 /media/usb<br />
|-<br />
| df -h<br />
| Show remaining space on all partitions<br />
| {{man|1|df}}<br />
|<br />
|-<br />
| ps -A<br />
| Show all running processes<br />
| {{man|1|ps}}<br />
|<br />
|-<br />
| killall<br />
| Kill all running instances of a process<br />
| {{man|1|killall}}<br />
|<br />
|-<br />
| ss -at<br />
| Display a list of open TCP sockets<br />
| {{man|8|ss}}<br />
|<br />
|}<br />
<br />
== cat ==<br />
<br />
[[Wikipedia:cat_(Unix)|cat]] is a standard Unix utility that concatenates and lists files.<br />
<br />
* Because ''cat'' is not built into the shell, on many occasions you may find it more convenient to use a [[Wikipedia:Redirection (computing)|redirection]], for example in scripts, or if you care a lot about performance. In fact {{ic|< ''file''}} does the same as {{ic|cat ''file''}}.<br />
<br />
* ''cat'' is able to work with multiple lines:<br />
<br />
{{bc|<br />
$ cat << EOF >> ''path/file''<br />
''first line''<br />
...<br />
''last line''<br />
EOF<br />
}}<br />
<br />
Alternatively, using {{ic|printf}}:<br />
<br />
{{bc|<br />
$ printf '%s\n' 'first line' ... 'last line'<br />
}}<br />
<br />
* If you need to list file lines in reverse order, there is a utility called [[Wikipedia:tac (Unix)|tac]] (''cat'' reversed).<br />
<br />
== dd ==<br />
<br />
[[Wikipedia:dd (Unix)|dd]] is a utility for Unix and Unix-like operating systems whose primary purpose is to convert and copy a file.<br />
<br />
Similarly to ''cp'', by default ''dd'' makes a bit-to-bit copy of the file, but with lower-level I/O flow control features.<br />
<br />
{{Tip|By default, ''dd'' outputs nothing until the task has finished. To monitor the progress of the operation, add the {{ic|1=status=progress}} option to the command.}}<br />
<br />
For more information see {{man|1|dd}} or the [https://www.gnu.org/software/coreutils/dd full documentation].<br />
<br />
== grep ==<br />
<br />
[[Wikipedia:grep|grep]] (from [[Wikipedia:Ed_(text_editor)|ed]]'s ''g/re/p'', ''global/regular expression/print'') is a command line text search utility originally written for Unix. The ''grep'' command searches files or standard input for lines matching a given regular expression, and prints these lines to the program's standard output.<br />
<br />
* Remember that ''grep'' handles files, so a construct like {{ic|cat ''file'' <nowiki>|</nowiki> grep ''pattern''}} is replaceable with {{ic|grep ''pattern'' ''file''}}<br />
* There are ''grep'' alternatives optimized for VCS source code, such as {{Pkg|ripgrep}}, {{Pkg|the_silver_searcher}}, and {{Pkg|ack}}.<br />
* To include file line numbers in the output, use the {{ic|-n}} option. <br />
<br />
{{Note|Some commands send their output to {{man|3|stderr}}, and grep has no apparent effect. In this case, redirect ''stderr'' to ''stdout'' with {{ic|''command'' 2>&1 {{!}} grep ''args''}} or (for Bash 4) {{ic|''command'' {{!}}& grep ''args''}}. See also [http://www.tldp.org/LDP/abs/html/io-redirection.html I/O Redirection].}}<br />
<br />
For color support, see [[Color output in console#grep]].<br />
<br />
== find ==<br />
<br />
''find'' is part of the {{Pkg|findutils}} package, which belongs to the {{Grp|base}} package group. <br />
<br />
Tip: [https://github.com/sharkdp/fd fd] is a modern and user friendly alternative to {{ic|find}}, that tries to improve performance, and offer more friendly defaults. For example {{ic|fd PATTERN}} instead of {{ic|find -iname '*PATTERN*'}}. It features colorized output (similar to {{ic|ls}}), smart-case search by default, hidden files ignoring, and more. {{Pkg|fd}}<br />
<br />
One would probably expect a ''find'' command to take as argument a file name and search the filesystem for files matching that name. For a program that does exactly that see [[#locate]] below. <br />
<br />
Instead, find takes a set of directories and matches each file under them against a set of expressions. This design allows for some very powerful "one-liners" that would not be possible using the "intuitive" design described above. See [http://mywiki.wooledge.org/UsingFind UsingFind] for usage details.<br />
<br />
== iconv ==<br />
<br />
''iconv'' converts the encoding of characters from one codeset to another.<br />
<br />
The following command will convert the file {{ic|''foo''}} from ISO-8859-15 to UTF-8, saving it to {{ic|''foo''.utf}}:<br />
<br />
$ iconv -f ISO-8859-15 -t UTF-8 ''foo'' > ''foo''.utf<br />
<br />
See {{man|1|iconv}} for more details.<br />
<br />
=== Convert a file in place ===<br />
<br />
{{Tip|You can use {{pkg|recode}} instead of iconv if you do not want to touch the mtime.}}<br />
Unlike [[#sed|sed]], ''iconv'' does not provide an option to convert a file in place. However, {{ic|sponge}} from the {{pkg|moreutils}} package can help:<br />
<br />
$ iconv -f WINDOWS-1251 -t UTF-8 ''foobar''.txt | sponge ''foobar''.txt<br />
<br />
See {{man|1|sponge}} for details.<br />
<br />
== ip ==<br />
<br />
[[Wikipedia:Iproute2|ip]] allows you to show information about network devices, IP addresses, routing tables, and other objects in the Linux [[Wikipedia:Internet Protocol|IP]] software stack. By appending various commands, you can also manipulate or configure most of these objects.<br />
<br />
{{Note|The ''ip'' utility is provided by the {{Pkg|iproute2}} package, which is included in the {{Grp|base}} group.}}<br />
<br />
{| class="wikitable"<br />
! Object !! Purpose !! Manual page<br />
|-<br />
| ip addr || protocol address management || {{man|8|ip-address}}<br />
|-<br />
| ip addrlabel || protocol address label management || {{man|8|ip-addrlabel}}<br />
|-<br />
| ip l2tp || tunnel Ethernet over IP (L2TPv3) || {{man|8|ip-l2tp}}<br />
|-<br />
| ip link || network device configuration || {{man|8|ip-link}}<br />
|-<br />
| ip maddr || multicast addresses management || {{man|8|ip-maddress}}<br />
|-<br />
| ip monitor || watch for netlink messages || {{man|8|ip-monitor}}<br />
|-<br />
| ip mroute || multicast routing cache management || {{man|8|ip-mroute}}<br />
|-<br />
| ip mrule || rule in multicast routing policy db ||<br />
|-<br />
| ip neigh || neighbour/ARP tables management || {{man|8|ip-neighbour}}<br />
|-<br />
| ip netns || process network namespace management || {{man|8|ip-netns}}<br />
|-<br />
| ip ntable || neighbour table configuration || {{man|8|ip-ntable}}<br />
|-<br />
| ip route || routing table management || {{man|8|ip-route}}<br />
|-<br />
| ip rule || routing policy database management || {{man|8|ip-rule}}<br />
|-<br />
| ip tcp_metrics || management for TCP Metrics || {{man|8|ip-tcp_metrics}}<br />
|-<br />
| ip tunnel || tunnel configuration || {{man|8|ip-tunnel}}<br />
|-<br />
| ip tuntap || manage TUN/TAP devices ||<br />
|-<br />
| ip xfrm || manage IPsec policies || {{man|8|ip-xfrm}}<br />
|}<br />
<br />
The {{ic|help}} command is available for all objects. For example, typing {{ic|ip addr help}} will show you the command syntax available for the address object. For advanced usage see the [http://www.policyrouting.org/iproute2.doc.html iproute2 documentation].<br />
<br />
The [[Network configuration]] article shows how the ''ip'' command is used in practice for various common tasks.<br />
<br />
{{Note|You might be familiar with the [[Wikipedia:ifconfig|ifconfig]] command, which was used in older versions of Linux for interface configuration. It is now deprecated in Arch Linux; you should use ''ip'' instead. }}<br />
<br />
== locate ==<br />
<br />
[[Install]] the {{Pkg|mlocate}} package. The package contains an {{ic|updatedb.timer}} unit, which invokes a database update each day. The timer is enabled right after installation, [[start]] it manually if you want to use it before reboot. You can also manually run ''updatedb'' as root at any time. By default, paths such as {{ic|/media}} and {{ic|/mnt}} are ignored, so ''locate'' may not discover files on external devices. See {{man|8|updatedb}} for details.<br />
<br />
The ''locate'' command is a common Unix tool for quickly finding files by name. It offers speed improvements over the [[wikipedia:Find|find]] tool by searching a pre-constructed database file, rather than the filesystem directly. The downside of this approach is that changes made since the construction of the database file cannot be detected by ''locate''.<br />
<br />
Before ''locate'' can be used, the database will need to be created. To do this, execute {{ic|updatedb}} as root.<br />
<br />
See also [http://jvns.ca/blog/2015/03/05/how-the-locate-command-works-and-lets-rewrite-it-in-one-minute/ How locate works and rewrite it in one minute].<br />
<br />
== less ==<br />
<br />
{{Expansion|less is a complex beast, and this section should explain some of the basic less commands}}<br />
<br />
[[Wikipedia:less (Unix)|less]] is a terminal pager program used to view the contents of a text file one screen at a time. Whilst similar to other pagers such as [[Wikipedia:more (command)|more]] and [[Wikipedia:pg (Unix)|pg]], ''less'' offers a more advanced interface and complete [http://www.greenwoodsoftware.com/less/faq.html feature-set].<br />
<br />
See [[List of applications#Terminal pagers]] for alternatives.<br />
<br />
=== Vim as alternative pager ===<br />
<br />
[[Vim]] includes a script to view the content of text files, compressed files, binaries and directories. Add the following line to your shell configuration file to use it as a pager:<br />
{{hc|~/.bashrc|2=alias less='/usr/share/vim/vim80/macros/less.sh'}}<br />
<br />
There is also an alternative to the ''less.sh'' macro, which may work as the {{ic|PAGER}} environment variable. Install {{Pkg|vimpager}} and add the following to your shell configuration file:<br />
{{hc|~/.bashrc|2=<br />
export PAGER='vimpager'<br />
alias less=$PAGER<br />
}}<br />
<br />
Now programs that use the {{ic|PAGER}} environment variable, like [[git]], will use ''vim'' as pager.<br />
<br />
== ls ==<br />
<br />
[[Wikipedia:ls|ls]] lists directory contents.<br />
<br />
See {{ic|info ls}} or [https://www.gnu.org/software/coreutils/manual/html_node/ls-invocation.html#ls-invocation the online manual] for more information.<br />
<br />
[https://the.exa.website exa] is a modern, and more user friendly alternative to {{ic|ls}} and {{ic|tree}}, that has more features, such as displaying [[Git]] modifications along with filenames, colouring differently each columnn in {{ic|--long}} mode, or displaying {{ic|--long}} mode metadata along with a {{ic|tree}} view. {{Pkg|exa}}<br />
=== Long format ===<br />
<br />
The {{ic|-l}} option displays some metadata, for example:<br />
<br />
{{hc|$ ls -l ''/path/to/directory''|<br />
total 128<br />
drwxr-xr-x 2 archie users 4096 Jul 5 21:03 Desktop<br />
drwxr-xr-x 6 archie users 4096 Jul 5 17:37 Documents<br />
drwxr-xr-x 2 archie users 4096 Jul 5 13:45 Downloads<br />
-rw-rw-r-- 1 archie users 5120 Jun 27 08:28 customers.ods<br />
-rw-r--r-- 1 archie users 3339 Jun 27 08:28 todo<br />
-rwxr-xr-x 1 archie users 2048 Jul 6 12:56 myscript.sh<br />
}}<br />
<br />
The {{ic|total}} value represents the total disk allocation for the files in the directory, by default in number of blocks.<br />
<br />
Below, each file and subdirectory is represented by a line divided into 7 metadata fields, in the following order:<br />
<br />
* type and permissions:<br />
** the first character is the entry type, see {{ic|info ls -n "What information is listed"}} for an explanation of all the possible types; for example:<br />
*** {{ic|-}} denotes a normal file;<br />
*** {{ic|d}} denotes a directory, i.e. a folder containing other files or folders;<br />
*** {{ic|p}} denotes a named pipe (aka FIFO);<br />
*** {{ic|l}} denotes a symbolic link;<br />
** the remaining characters are the entry's [[permissions]];<br />
* number of [[Wikipedia:Hard link|hard links]] for the entity; files will have at least 1, i.e. the showed reference itself; folders will have at least 2: the showed reference, the self-referencing {{ic|.}} entry, and then a {{ic|..}} entry in each of its subfolders;<br />
* owner [[user]] name;<br />
* [[group]] name;<br />
* size;<br />
* last modification timestamp;<br />
* entity name.<br />
<br />
=== File names containing spaces enclosed in quotes ===<br />
<br />
By default, file and directory names that contain spaces are displayed surrounded by single quotes. To change this behavior use the {{ic|-N}} or {{ic|1=--quoting-style=literal}} options. Alternatively, set the {{ic|QUOTING_STYLE}} [[environment variable]] to {{ic|literal}}. [https://unix.stackexchange.com/questions/258679/why-is-ls-suddenly-surrounding-items-with-spaces-in-single-quotes]<br />
<br />
== lsblk ==<br />
<br />
{{man|8|lsblk}} will show all available [[w:Device_file#Block_devices|block devices]] along with their partitioning schemes, for example:<br />
<br />
{{hc|$ lsblk -f|<br />
NAME FSTYPE LABEL UUID MOUNTPOINT<br />
sda<br />
├─sda1 vfat C4DA-2C4D /boot<br />
├─sda2 swap 5b1564b2-2e2c-452c-bcfa-d1f572ae99f2 [SWAP]<br />
└─sda3 ext4 56adc99b-a61e-46af-aab7-a6d07e504652 /<br />
}}<br />
<br />
The beginning of the device name specifies the type of block device. Most modern storage devices (e.g. hard disks, [[SSD]]s and USB flash drives) are recognised as SCSI disks ({{ic|sd}}). The type is followed by a lower-case letter starting from {{ic|a}} for the first device ({{ic|sda}}), {{ic|b}} for the second device ({{ic|sdb}}), and so on. ''Existing'' partitions on each device will be listed with a number starting from {{ic|1}} for the first partition ({{ic|sda1}}), {{ic|2}} for the second ({{ic|sda2}}), and so on. In the example above, only one device is available ({{ic|sda}}), and that device has three partitions ({{ic|sda1}} to {{ic|sda3}}), each with a different [[file system]].<br />
<br />
Other common block device types include for example {{ic|mmcblk}} for memory cards and {{ic|nvme}} for [[NVMe]] devices. Unknown types can be searched in the [https://www.kernel.org/doc/Documentation/devices.txt kernel documentation]{{Dead link|2017|11|11}}.<br />
<br />
== mkdir ==<br />
<br />
[[Wikipedia:mkdir|mkdir]] makes directories.<br />
<br />
To create a directory and its whole hierarchy, the {{ic|-p}} switch is used, otherwise an error is printed. As users are supposed to know what they want, {{ic|-p}} switch may be used as a default:<br />
<br />
alias mkdir='mkdir -p -v'<br />
<br />
The {{ic|-v}} switch make it verbose.<br />
<br />
Changing mode of a just created directory using ''chmod'' is not necessary as the {{ic|-m}} option lets you define the access permissions.<br />
<br />
{{Tip|If you just want a temporary directory, a better alternative may be [[Wikipedia:Temporary file|mktemp]]: {{ic|mktemp -p}}.}}<br />
<br />
== mv ==<br />
<br />
[[Wikipedia:mv|mv]] moves and renames files and directories.<br />
<br />
To limit potential damage caused by the command, use an alias:<br />
<br />
alias mv='timeout 8 mv -iv'<br />
<br />
This alias suspends ''mv'' after eight seconds, asks for confirmation before overwriting any existing files, lists the operations in progress and does not store itself in the shell history file if the shell is configured to ignore space starting commands.<br />
<br />
== od ==<br />
<br />
The [[Wikipedia:od (Unix)|od]] (''o''ctal ''d''ump) command is useful for visualizing data that is not in a human-readable format, like the executable code of a program, or the contents of an unformatted device. See the [https://www.gnu.org/software/coreutils/manual/html_node/od-invocation.html#od-invocation manual] for more information.<br />
<br />
== pv ==<br />
<br />
You can use {{Pkg|pv}} (''pipe viewer'') to monitor the progress of data through a pipeline, for example:<br />
<br />
# dd if=''/source/filestream'' | pv -''monitor_options'' -s ''size_of_file'' | dd of=''/destination/filestream''<br />
<br />
In most cases {{ic|pv}} functions as a drop-in replacement for {{ic|cat}}.<br />
<br />
== rm ==<br />
<br />
[[Wikipedia:rm_(Unix)|rm]] removes files or directories.<br />
<br />
To limit potential damage caused by the command, use an alias:<br />
<br />
alias rm='timeout 3 rm -Iv --one-file-system'<br />
<br />
This alias suspends ''rm'' after three seconds, asks confirmation to delete three or more files, lists the operations in progress, does not involve more than one file systems and does not store itself in the shell history file if the shell is configured to ignore space starting commands. Substitute {{ic|-I}} with {{ic|-i}} if you prefer to confirm even for one file.<br />
<br />
Zsh users may want to put {{ic|noglob}} before {{ic|timeout}} to avoid implicit expansions.<br />
<br />
To remove directories believed to be empty, use ''rmdir'' as it fails if there are files inside the target.<br />
<br />
== sed ==<br />
<br />
[[Wikipedia:sed|sed]] is stream editor for filtering and transforming text.<br />
<br />
Here is a handy [http://sed.sourceforge.net/sed1line.txt list] of ''sed'' one-liners examples.<br />
<br />
{{Tip|More powerful alternatives are [[Wikipedia:AWK|AWK]] and the [[Wikipedia:Perl|Perl]] language.}}<br />
<br />
== seq ==<br />
<br />
''seq'' prints a sequence of numbers. Shell built-in alternatives are available, so it is good practice to use them as explained on [[Wikipedia:Seq (Unix)|Wikipedia]].<br />
<br />
== ss ==<br />
<br />
''ss'' is a utility to investigate network ports and is part of the {{Pkg|iproute2}} package in the {{Grp|base}} group. It has a similar functionality to the [https://www.archlinux.org/news/deprecation-of-net-tools/ deprecated] netstat utility. <br />
<br />
Common usage includes:<br />
<br />
Display all TCP Sockets with service names:<br />
$ ss -at<br />
<br />
Display all TCP Sockets with port numbers:<br />
$ ss -atn<br />
<br />
Display all UDP Sockets:<br />
$ ss -au<br />
<br />
For more information see {{man|8|ss}} or {{ic|ss.html}} from the {{Pkg|iproute2}} package.<br />
<br />
== tar ==<br />
<br />
As an early Unix archiving format, .tar files—known as "tarballs"—are widely used for packaging in Unix-like operating systems. Both [[pacman]] and [[AUR]] packages are compressed tarballs, and Arch uses [[GNU Project|GNU's]] ''tar'' program by default. <br />
<br />
For .tar archives, ''tar'' by default will extract the file according to its extension:<br />
<br />
$ tar xvf ''file.EXTENSION''<br />
<br />
Forcing a given format:<br />
<br />
{| class="wikitable"<br />
!File Type !! Extraction Command<br />
|-<br />
|{{ic|''file''.tar}} || {{Ic|tar xvf ''file''.tar}}<br />
|-<br />
|{{ic|''file''.tgz}} || {{Ic|tar xvzf ''file''.tgz}}<br />
|-<br />
|{{ic|''file''.tar.gz}} || {{Ic|tar xvzf ''file''.tar.gz}}<br />
|-<br />
|{{ic|''file''.tar.bz}} || {{Ic|bzip -cd ''file''.bz <nowiki>|</nowiki> tar xvf -}}<br />
|-<br />
|{{ic|''file''.tar.bz2}} || {{Ic|tar xvjf ''file''.tar.bz2}}<br> {{Ic|bzip2 -cd ''file''.bz2 <nowiki>| tar xvf -</nowiki>}}<br />
|-<br />
|{{ic|''file''.tar.xz}} || {{Ic|tar xvJf ''file''.tar.xz}}<br> {{Ic|xz -cd ''file''.xz <nowiki>| tar xvf -</nowiki>}}<br />
|}<br />
<br />
The construction of some of these ''tar'' arguments may be considered legacy, but they are still useful when performing specific operations. See {{man|1|tar}} for details.<br />
<br />
== which ==<br />
<br />
[[wikipedia:Which_(Unix)|which]] shows the full path of shell commands. In the following example the full path of {{ic|ssh}} is used as an argument for {{ic|journalctl}}:<br />
<br />
# journalctl $(which sshd)<br />
<br />
== wipefs ==<br />
<br />
''wipefs'' can list or erase [[file system]], [[RAID]] or [[partition|partition-table]] signatures (magic strings) from the specified device. It does not erase the file systems themselves nor any other data from the device.<br />
<br />
See {{man|8|wipefs}} for more information.<br />
<br />
For example, to erase all signatures from the device {{ic|/dev/sdb}} and create a signature backup {{ic|~/wipefs-sdb-''offset''.bak}} file for each signature:<br />
<br />
# wipefs --all --backup /dev/sdb<br />
<br />
== See also ==<br />
<br />
* [http://www.reddit.com/r/commandline/comments/19garq/a_sampling_of_coreutils_120/ A sampling of coreutils] [http://www.reddit.com/r/commandline/comments/19ge6v/a_sampling_of_coreutils_2040/ , part 2] [http://www.reddit.com/r/commandline/comments/19j1w3/a_sampling_of_coreutils_4060/ , part 3] - Overview of commands in coreutils<br />
* [https://www.gnu.org/software/coreutils/manual/coreutils.html GNU Coreutils online documentation]<br />
* [https://www.linuxquestions.org/questions/linux-newbie-8/learn-the-dd-command-362506/ Learn the DD command]</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=CUPS/Troubleshooting&diff=509745CUPS/Troubleshooting2018-02-04T20:02:32Z<p>JoshuaRLi: Added an elaboration on the symptoms for this troubleshooting section, most notably a stacktrace for the hp-setup script which I personally found very useful for troubleshooting: https://bbs.archlinux.org/viewtopic.php?id=210452</p>
<hr />
<div>[[Category:Printers]]<br />
[[ja:CUPS/トラブルシューティング]]<br />
[[ru:CUPS (Русский)/Troubleshooting]]<br />
{{Related articles start}}<br />
{{Related|CUPS}}<br />
{{Related|CUPS/Printer-specific problems}}<br />
{{Related articles end}}<br />
<br />
This article covers all non-specific (ie, not related to any one printer) troubleshooting of CUPS and printing drivers (but not problems related to printer sharing), including methods of determining the exact nature of the problem, and of solving the identified problem. <br />
<br />
== Introduction ==<br />
<br />
The best way to get printing working is to set 'LogLevel' in {{ic|/etc/cups/cupsd.conf}} to:<br />
LogLevel debug<br />
<br />
And then viewing the output from {{ic|/var/log/cups/error_log}} like this:<br />
# tail -n 100 -f /var/log/cups/error_log<br />
<br />
The characters at the left of the output stand for:<br />
*D=Debug<br />
*E=Error<br />
*I=Information<br />
*And so on<br />
<br />
These files may also prove useful:<br />
*{{ic|/var/log/cups/page_log}} - Echoes a new entry each time a print is successful<br />
*{{ic|/var/log/cups/access_log}} - Lists all cupsd http1.1 server activity<br />
<br />
Of course, it is important to know how CUPS works if wanting to solve related issues:<br />
# An application sends a .ps file (PostScript, a script language that details how the page will look) to CUPS when 'print' has been selected (this is the case with most programs).<br />
# CUPS then looks at the printer's PPD file (printer description file) and figures out what filters it needs to use to convert the .ps file to a language that the printer understands (like PJL, PCL), usually GhostScript.<br />
# GhostScript takes the input and figures out which filters it should use, then applies them and converts the .ps file to a format understood by the printer.<br />
# Then it is sent to the back-end. For example, if the printer is connected to a USB port, it uses the USB back-end.<br />
<br />
Print a document and watch {{ic|error_log}} to get a more detailed and correct image of the printing process.<br />
<br />
== Problems resulting from upgrades ==<br />
<br />
''Issues that appeared after CUPS and related program packages underwent a version increment''<br />
<br />
=== CUPS stops working ===<br />
<br />
The chances are that a new configuration file is needed for the new version to work properly. Messages such as "404 - page not found" may result from trying to manage CUPS via localhost:631, for example.<br />
<br />
To use the new configuration, copy {{ic|/etc/cups/cupsd.conf.default}} to {{ic|/etc/cups/cupsd.conf}} (backup the old configuration if needed) and restart CUPS to employ the new settings.<br />
<br />
=== All jobs are "stopped" ===<br />
<br />
{{Accuracy|This seems a rather brute-force way of fixing this; maybe the printer is simply disabled?}}<br />
<br />
If all jobs sent to the printer become "stopped", delete the printer and add it again.<br />
Using the [http://localhost:631 CUPS web interface], go to Printers > Delete Printer.<br />
<br />
To check the printer's settings go to ''Printers'', then ''Modify Printer''. Copy down the information displayed, click 'Modify Printer' to proceed to the next page(s), and so on.<br />
<br />
=== All jobs are "The printer is not responding" ===<br />
<br />
On networked printers, you should check that the hostname in the printer's URI resolves to the printer's IP address via DNS, e.g. if your printer's connection looks like this:<br />
<br />
lpd://BRN_020554/BINARY_P1<br />
<br />
then the hostname 'BRN_020554' needs to resolve to the printer's IP from the server running CUPS. If [[Avahi]] is being used, ensure that [[Avahi#Hostname_resolution|Avahi's hostname resolution]] is working.<br />
<br />
Alternatively, replace the hostname used in the URI with the printer's IP address.<br />
<br />
=== The PPD version is not compatible with gutenprint ===<br />
<br />
Run:<br />
# /usr/bin/cups-genppdupdate<br />
<br />
And restart CUPS (as pointed out in gutenprint's post-install message).<br />
<br />
=== Printers are not present in the print dialog for GTK3 applications ===<br />
<br />
As of GTK3 3.22, [[GTK+#Printers not shown in the GTK print dialog|printing support is moved to a new package]]{{Broken section link}}.<br />
<br />
Signs and symptoms: printer targets do not show up in the GTK3 print dialogs, making it impossible to print directly from from applications like [[gedit]], [[Chromium]], and [[Firefox]]; but printers still appear in the CUPS web interface and lpstat, and printing from the command line interface or GTK2 applications (GIMP, for example) still works.<br />
<br />
== Networking issues ==<br />
<br />
=== Unable to locate printer ===<br />
<br />
Even if CUPS can detect networked printers, you may still end up with an "Unable to locate printer" error when trying to print something. The solution to this problem is to enable Avahi's [[Avahi#Hostname_resolution|.local hostname resolution]]. See [[CUPS#Network]] for details.<br />
<br />
This problem may also arise when you have a firewall. You may need to disable your firewall or set the right rules. Using system-config-printer to detect network printers will do that automatically.<br />
<br />
=== Old CUPS server ===<br />
<br />
As of CUPS version 1.6, the client defaults to IPP 2.0. If the server uses CUPS <= 1.5 / IPP <= 1.1, the client does not downgrade the protocol automatically and thus cannot communicate with the server. A workaround is to append the {{ic|1=version=1.1}} option documented at [https://www.cups.org/doc/network.html#TABLE2] to the URI.<br />
<br />
=== Shared printer works locally but remote machine fails to print ===<br />
<br />
This is caused by a print job being sent through a filter twice, once on the local machine and once on the remote. See also the warning on the main [[CUPS#Network_2|CUPS]] page.<br />
<br />
== USB printers ==<br />
<br />
=== Conflict with SANE ===<br />
<br />
If you are also running [[SANE]], it's possible that it is conflicting with CUPS. To fix this create a [[Udev]] rule marking the device as matched by libsane:<br />
{{hc|/etc/udev/rules.d/99-printer.rules|output=<br />
ATTRS{idVendor}=="''vendor id''", ATTRS{idProduct}=="''product id''", MODE="0664", GROUP="lp", ENV{libsane_matched}="yes"}}<br />
<br />
=== Conflict with usblp ===<br />
<br />
USB printers can be accessed using two methods: The usblp kernel module and libusb. The former is the classic way. It is simple: data is sent to the printer by writing it to a device file as a simple serial data stream. Reading the same device file allows bi-di access, at least for things like reading out ink levels, status, or printer capability information (PJL). It works very well for simple printers, but for multi-function devices (printer/scanner) it is not suitable and manufacturers like HP supply their own backends. Source: [http://lists.linuxfoundation.org/pipermail/printing-architecture/2012/002412.html here].<br />
<br />
{{Warning|As of {{Pkg|cups}} version 1.6.0, it should no longer be necessary to blacklist the {{ic|usblp}} kernel module.<br />
<br />
If you find out this is the only way to fix a remaining issue please report this upstream to the CUPS bug tracker and maybe also get in contact with Till Kamppeter (Debian CUPS maintainer). See [http://cups.org/str.php?L4128 upstream bug] for more info.}}<br />
<br />
If you have problems getting your USB printer to work, you can try [[blacklisting]] the {{ic|usblp}} [[kernel module]]:<br />
<br />
{{hc|/etc/modprobe.d/blacklistusblp.conf|<br />
blacklist usblp<br />
}}<br />
<br />
Custom kernel users may need to manually load the {{ic|usbcore}} [[kernel module]] before proceeding.<br />
<br />
Once the modules are installed, plug in the printer and check if the kernel detected it by running the following:<br />
# journalctl -e<br />
or<br />
# dmesg<br />
<br />
If you are using {{ic|usblp}}, the output should indicate that the printer has been detected like so:<br />
Feb 19 20:17:11 kernel: printer.c: usblp0: USB Bidirectional<br />
printer dev 2 if 0 alt 0 proto 2 vid 0x04E8 pid 0x300E<br />
Feb 19 20:17:11 kernel: usb.c: usblp driver claimed interface cfef3920<br />
Feb 19 20:17:11 kernel: printer.c: v0.13: USB Printer Device Class driver<br />
<br />
If you blacklisted {{ic|usblp}}, you will see something like:<br />
usb 3-2: new full speed USB device using uhci_hcd and address 3<br />
usb 3-2: configuration #1 chosen from 1 choice<br />
<br />
=== USB autosuspend ===<br />
<br />
The Linux kernel automatically suspends USB devices when there is driver support and the devices are not in use. This can save power, but some USB printers think that they are disconnected when the kernel suspends the USB port, preventing printing. This can be fixed by deactivating autosuspend for the specific device, see [[Power management#USB autosuspend]].<br />
<br />
== HP issues ==<br />
<br />
See also [[CUPS/Printer-specific problems#HP]].<br />
<br />
=== CUPS: "/usr/lib/cups/backend/hp failed" ===<br />
<br />
{{Accuracy|Backend failures can be caused by many issues, and [[Avahi]] should not be required}}<br />
<br />
Make sure dbus is installed and running. If the error persists, try starting avahi-daemon.<br />
<br />
Try adding the printer as a Network Printer using the http:// protocol.<br />
<br />
{{Note|There might need to set permissions issues right.}}<br />
<br />
=== CUPS: Job is shown as complete but the printer does nothing ===<br />
<br />
This happens on HP printers when you select the (old) hpijs driver (e.g. the Deskjet D1600 series). Use the hpcups driver instead.<br />
<br />
Some HP printers require their firmware to be downloaded from the computer every time the printer is switched on. If there is an issue with udev (or equivalent) and the firmware download rule is never fired, you may experience this issue.<br />
As a workaround, you can manually download the firmware to the printer. Ensure the printer is plugged in and switched on, then run<br />
hp-firmware -n<br />
<br />
=== CUPS: '"foomatic-rip" not available/stopped with status 3' ===<br />
<br />
If receiving any of the following error messages in {{ic|/var/log/cups/error_log}} while using a HP printer, with jobs appearing to be processed while they all end up not being completed with their status set to 'stopped':<br />
Filter "foomatic-rip" for printer ''printer_name'' not available: No such file or director<br />
or:<br />
PID ''pid'' (/usr/lib/cups/filter/foomatic-rip) stopped with status 3!<br />
make sure {{pkg|hplip}} has been [[installed]].<br />
<br />
=== CUPS: "Filter failed" ===<br />
<br />
A "filter failed" error can be caused by any number of issues. The CUPS error log (by default {{ic|/var/log/cups/error_log}}) should record which filter failed and why.<br />
<br />
==== Missing ghostscript ====<br />
<br />
Install {{pkg|ghostscript}} ({{ic|/usr/lib/cups/filter/gstoraster}} needs it to run).<br />
<br />
==== Missing foomatic-db ====<br />
<br />
Install {{pkg|foomatic-db}} and {{pkg|foomatic-db-ppds}}. This fixes it in some cases.<br />
<br />
==== Bad permissions ====<br />
<br />
{{Accuracy|{{ic|chmod 666}} on a system device sounds dubious to say the least}}<br />
<br />
Change the permissions of the printer USB port. Get the bus and device number from {{ic|lsusb}}, then set the permission using:<br />
<br />
{{hc| lsusb |<br />
Bus <BUSID> Device <DEVID>: ID <PRINTERID>:<VENDOR> Hewlett-Packard DeskJet D1360}}<br />
<br />
Then substitute the provided device information to the <br />
<br />
# chmod 0666 /dev/bus/usb/<BUSID>/<DEVID><br />
<br />
To make the persistent permission change that will be triggered automatically each time the computer is rebooted, add the following line.<br />
<br />
{{hc|/etc/udev/rules.d/10-local.rules|2=<br />
SUBSYSTEM=="usb", ATTRS{idVendor}=="<VENDOR>", ATTRS{idProduct}=="<PRINTERID>", GROUP="lp", MODE:="666"<br />
}}<br />
<br />
Each system may vary, so consult [[udev#List attributes of a device]] wiki page.<br />
<br />
==== Avahi not enabled ====<br />
<br />
[[Start]], and [[enable]] the {{ic|avahi-daemon}} service.<br />
<br />
==== Out-of-date plugin ====<br />
<br />
This error can also indicate that the plugin is out of date (version is mismatched) and may occur after a system upgrade, possibly showing up as a {{ic|Plugin error}} message in the logs.<br />
If you have installed {{AUR|hplip-plugin}} you will need to update the package, otherwise re-run {{ic|hp-setup -i}} to install the latest version of the plugin.<br />
<br />
==== Outdated printer configuration ====<br />
<br />
As of {{AUR|hplip-plugin}} v3.17.11 hpijs is not longer available. If you have printers using hpijs they will fail to print. You must modify them and select the new hpcups driver instead.<br />
<br />
You can check if this is your case looking at cups error_log:<br />
<br />
{{hc| $ cat /var/log/cups/error_log {{!}} grep hpijs |<br />
...<br />
D [09/Jan/2018:14:32:58 +0000] [Job 97] '''sh: hpijs: command not found'''<br />
...}}<br />
<br />
=== CUPS: prints only an empty and an error-message page on HP LaserJet ===<br />
<br />
{{Out of date|The bug was reported in 2012; is this still an issue?}}<br />
<br />
There is a bug that causes CUPS to fail when printing images on HP LaserJet (in my case 3380). The bug has been reported and fixed by [https://bugs.launchpad.net/ubuntu/+source/cups-filters/+bug/998087 Ubuntu].<br />
The first page is empty, the second page contains the following error message:<br />
ERROR:<br />
invalidaccess<br />
OFFENDING COMMAND:<br />
filter<br />
STACK:<br />
/SubFileDecode<br />
endstream<br />
...<br />
<br />
In order to fix the issue, run the following command as root:<br />
# lpadmin -p ''printer'' -o pdftops-renderer-default=pdftops<br />
<br />
=== HPLIP 3.13: Plugin is installed, but HP Device Manager complains it is not ===<br />
<br />
The issue might have to do with the file permission change that had been made to {{ic|/var/lib/hp/hplip.state}}. To correct the issue, a simple {{ic|chmod 644 /var/lib/hp/hplip.state}} and {{ic|chmod 755 /var/lib/hp}} should be sufficient. For further information, please read this [https://bugs.launchpad.net/hplip/+bug/1131596 link].<br />
<br />
=== hp-toolbox: "Unable to communicate with device" ===<br />
<br />
# hp-toolbox<br />
# error: Unable to communicate with device (code=12): hp:/usb/''printer id''<br />
<br />
==== Permission problem ====<br />
<br />
{{Accuracy|Presumably, hp-toolbox tries to access /dev/usb/* or /dev/lp, so it needs to be in the {{ic|lp}} group. But why {{ic|sys}}? And I can't seem to reproduce this...}}<br />
<br />
It may be needed to add the user to the {{ic|lp}} and {{ic|sys}} [[group]]s.<br />
<br />
==== Virtual CDROM printers ====<br />
<br />
This can also be caused by printers such as the P1102 that provide a virtual CD-ROM drive for MS Windows drivers. The lp dev appears and then disappears. In that case, try the '''usb-modeswitch''' and '''usb-modeswitch-data''' packages, that lets one switch off the "Smart Drive" (udev rules included in said packages).<br />
<br />
==== Networked printers ====<br />
<br />
This can also occur with network attached printers using dynamic hostnames if the [[Avahi|avahi-daemon]] is not running. Another possibility is that ''hp-setup'' failed to locate the printer because the IP address of the the printer changed due to DHCP. If this is the case, consider adding a DHCP reservation for the printer in the DHCP server's configuration.<br />
<br />
=== hp-setup asks to specify the PPD file for the discovered printer ===<br />
<br />
Furthermore, when selecting a PPD file in hp-setup's graphical mode, the field does not update and no error message is shown.<br />
<br />
Or, if in interactive (console) mode, you may encounter something similar to this even when providing a correct path to a valid ppd file:<br />
<br />
Please enter the full filesystem path to the PPD file to use (q=quit) :/usr/share/ppd/HP/hp-deskjet_2050_j510_series.ppd.gz<br />
Traceback (most recent call last):<br />
File "/usr/bin/hp-setup", line 536, in <module><br />
desc = nickname_pat.search(nickname).group(1)<br />
TypeError: cannot use a string pattern on a bytes-like object<br />
<br />
The solution is to install and start {{pkg|cups}} before running {{ic|hp-setup}}.<br />
<br />
=== hp-setup: "Qt/PyQt 4 initialization failed" ===<br />
<br />
[[Install]] {{pkg|python-pyqt4}}, which is an optdepend of {{Pkg|hplip}}. Alternatively, to run hp-setup with the command line interface, use the {{ic|-i}} flag.<br />
<br />
=== hp-setup: finds the printer automatically but reports "Unable to communicate with device" when printing test page immediately afterwards ===<br />
<br />
This at least happens to hplip 3.13.5-2 for HP Officejet 6500A through local network connection. To solve the problem, specify the IP address of the HP printer for hp-setup to locate the printer.<br />
<br />
== Other ==<br />
<br />
=== Printer "Paused" or "Stopped" with Status "Rendering completed" ===<br />
<br />
==== Low ink ====<br />
<br />
When low on ink, some printers will get stuck in "Rendering completed" status and, if it is a network printer, the printer may even become unreachable from CUPS' perspective despite being properly connected to the network. Replacing the low/depleted ink cartridge(s) in this setting will return the printer to "Ready" status and, if it is a network printer, will make the printer available to CUPS again.<br />
<br />
{{Note|If you use third-party ink cartridges, the ink levels reported by the printer may be inaccurate. If you use third-party ink and your printer used to work fine but is now getting stuck on "Rendering completed" status, replace the ink cartridges regardless of the reported ink levels before trying other fixes.}}<br />
<br />
==== Permission issue ====<br />
<br />
Prior to {{pkg|cups}} 2.0.0-2, if the group set in the {{ic|Group}} directive is also listed in the {{ic|SystemGroup}} directive in {{ic|/etc/cups/cups-files.conf}}, {{ic|cupsd}} will instead run any helper programs with a group of {{ic|nobody}}. However, the helpers may need to write to printer devices, which are created with user {{ic|root}} and group {{ic|lp}}, and will be unable to if they are run with a group of {{ic|nobody}}, causing the print queue to become "Paused" or "Stopped".<br />
<br />
To fix this, ensure that the the {{ic|Group}} directive is set to {{ic|lp}}, and the {{ic|SystemGroup}} directive does not include {{ic|lp}}.<br />
<br />
Fixed in Arch with [https://git.archlinux.org/svntogit/packages.git/commit/trunk?h=packages/cups&id=c20b22f4f996cb08b1aa856d4c8991e869459eb2].<br />
<br />
=== Printing fails with unauthorised error ===<br />
<br />
If a remote printer requests authentication CUPS will automatically add an {{ic|AuthInfoRequired}} directive to the printer in {{ic|/etc/cups/printers.conf}}. However, some graphical applications (for instance, some versions of [[LibreOffice]] [https://bugs.documentfoundation.org/show_bug.cgi?id=53029]) have no way to prompt for credentials, so printing fails.<br />
To fix this include the required username and password in the URI.<br />
See [https://bugs.launchpad.net/ubuntu/+source/cups/+bug/283811], [https://bbs.archlinux.org/viewtopic.php?id=61826].<br />
<br />
=== Unknown supported format: application/postscript ===<br />
<br />
Comment the lines:<br />
application/octet-stream application/vnd.cups-raw 0 -<br />
from {{ic|/etc/cups/mime.convs}}, and:<br />
application/octet-stream<br />
in {{ic|/etc/cups/mime.types}}.<br />
<br />
=== Print-Job client-error-document-format-not-supported ===<br />
<br />
Try installing the foomatic packages and use a foomatic driver.<br />
<br />
=== Unable to get list of printer drivers ===<br />
(Also applicable to error "-1 not supported!")<br />
<br />
Try to remove Foomatic drivers or refer to [[CUPS/Printer-specific problems#HPLIP Driver]] for a workaround.<br />
<br />
=== lp: Error - Scheduler Not Responding ===<br />
<br />
If you get this error, ensure [[CUPS]] is running, the environmental variable {{ic|CUPS_SERVER}} is unset, and that {{ic|/etc/cups/client.conf}} is correct.<br />
<br />
=== "Using invalid Host" error message ===<br />
<br />
Try adding {{ic|ServerAlias *}} into {{ic|/etc/cups/cupsd.conf}}.<br />
<br />
=== Cannot print from LibreOffice ===<br />
<br />
If you can print a test page from the [[CUPS]] web interface, but not from [[LibreOffice]], try to [[install]] the {{Pkg|a2ps}} package.<br />
<br />
=== Printer output shifted ===<br />
<br />
This seems to be caused by the wrong page size being set in [[CUPS]].<br />
<br />
=== Printer becomes stuck after a problem ===<br />
<br />
When an issue arises during printing, the printer in CUPS may become unresponsive. {{ic|lpq}} reports that the printer {{ic|is not ready}}, and it can be reactivated using {{ic|cupsenable}}. In the CUPS web interface, the printer is shown as ''Paused'', and can be reactivated by ''resuming'' the printer.<br />
<br />
To automatically have CUPS reactivate the printer, change [https://www.cups.org/doc/man-cupsd.conf.html?TOPIC=Man+Pages#ErrorPolicy ErrorPolicy] from the default {{ic|stop-printer}} to {{ic|retry-this-job}}.<br />
<br />
=== Samsung: URF ERROR - Incomplete Session by time out ===<br />
<br />
This error is usually encountered when printing files over the network through IPP to a Samsung printer, and is solved by using the {{aur|samsung-unified-driver}} package.<br />
<br />
{{Note|The corresponding error code 11-1112 corresponds to an internal wiring problem with the printer, so contacting Samsung's tech support is futile.}}<br />
<br />
=== Brother: Printer prints multiple copies ===<br />
<br />
Sometimes the printer will print multiple copies of a document (for instance a MFC-9330CDW printed 10 copies). The solution is to [[CUPS/Printer-specific problems#Updating the firmware|update the printer firmware]].<br />
<br />
=== Regular user cannot change properties of the printer or remove certain jobs ===<br />
<br />
If a regular user needs to be able to change the printers properties or manage the printer queue, the user may need to be added to the {{ic|sys}} group.</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=Rxvt-unicode&diff=505717Rxvt-unicode2018-01-02T01:39:36Z<p>JoshuaRLi: urxvt is widely used because it offers true/native transparency support. As such, I've noted this feature in the pitch line.</p>
<hr />
<div>{{DISPLAYTITLE:rxvt-unicode}}<br />
[[Category:Terminal emulators]]<br />
[[de:urxvt]]<br />
[[es:Rxvt-unicode]]<br />
[[fr:urxvt]]<br />
[[ja:Rxvt-unicode]]<br />
[[ru:Rxvt-unicode]]<br />
[[sr:Rxvt-unicode]]<br />
{{Related articles start}}<br />
{{Related|rxvt-unicode/Tips and tricks}}<br />
{{Related articles end}}<br />
[http://software.schmorp.de/pkg/rxvt-unicode.html rxvt-unicode] is a customizable terminal emulator forked from [[Wikipedia:Rxvt|rxvt]]. Features of rxvt-unicode include international language support through [[Wikipedia:Unicode|Unicode]], transparency, the ability to display multiple font types and support for [[Perl]] extensions.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|rxvt-unicode}} package.<br />
<br />
== Configuration ==<br />
<br />
See {{man|1|urxvt}} and {{man|7|urxvt}} for available settings and values.<br />
<br />
=== Xresources ===<br />
<br />
Rxvt-unicode is controlled by command-line arguments or [[Xresources]]. Command-line arguments override, and take precedence over resource settings, see the [[X resources]] article for details.<br />
<br />
{{ic|urxvt --help}} prints all available ''rxvt'' resources to standard error. The man page has full explanations of each resource.<br />
<br />
=== Scrollback position ===<br />
<br />
By default, when shell output appears the scrollback view will automatically jump to the bottom of the buffer to display new output. If in cases where you want to see previous output (e.g., compiler messages), set the following options in {{ic|~/.Xresources}}:<br />
<br />
! do not scroll with output<br />
URxvt*scrollTtyOutput: false<br />
<br />
! scroll in relation to buffer (with mouse scroll or Shift+Page Up)<br />
URxvt*scrollWithBuffer: true<br />
<br />
! scroll back to the bottom on keypress<br />
URxvt*scrollTtyKeypress: true<br />
<br />
=== Scrollback buffer in secondary screen ===<br />
<br />
When you scroll a pager in a ''secondary screen'' (e.g. {{ic|less}} without the {{ic|'''-X'''}} option), it may be a good idea to disable the scrollback buffer to be able to scroll in the pager ''itself'', instead of the terminal's buffer: this is default and unchangeable behaviour in konsole and vte-based terminals.<br />
<br />
In urxvt, to disable the scrollback buffer for the ''secondary screen'':<br />
<br />
URxvt.secondaryScreen: 1<br />
URxvt.secondaryScroll: 0<br />
<br />
The above configuration works as expected except when scrolling with a mouse wheel. When you scroll a pager in the ''secondary screen'' with the mouse wheel - and there has been something in the scrollback buffer, instead of the pager itself - the scrollback buffer will be scrolled by the mouse wheel. To solve this issue, it is necessary to introduce a new option into rxvt-unicode [https://bbs.archlinux.org/viewtopic.php?id=132150]. A patched rxvt-unicode is available in AUR as {{aur|rxvt-unicode-better-wheel-scrolling}}. After installing it, add the following to the configuration file:<br />
<br />
URxvt.secondaryWheel: 1<br />
<br />
{{Note|Avoid using this option with the {{AUR|urxvt-vtwheel}} perl extension, as it will conflict.}}<br />
<br />
=== Font declaration methods ===<br />
<br />
URxvt.font: 9x15<br />
is the same as:<br />
URxvt.font: -misc-fixed-medium-r-normal--15-140-75-75-c-90-iso8859-1<br />
<br />
And, for the same font in bold:<br />
<br />
URxvt.font: 9x15bold<br />
<br />
is the same as:<br />
<br />
URxvt.font: -misc-fixed-bold-r-normal--15-140-75-75-c-90-iso8859-1<br />
<br />
The complete list of short names for X core fonts can be found in {{ic|/usr/share/fonts/misc/fonts.alias}} (there is also some fonts.alias files in some of the other subdirectories of {{ic|/usr/share/fonts/}}, but as they are packaged separately from the actual fonts, they may list fonts you do not actually have installed). It is worth noting that these short aliases select for ISO-8859-1 versions of the fonts rather than ISO-10646-1 (Unicode) versions, and 75 DPI rather than 100 DPI versions, so you are probably better off avoiding them and choosing fonts by their full long names instead.<br />
<br />
{{Note|The above paragraph is only for bitmap fonts. Other fonts can be used through Xft using the following format:}}<br />
URxvt.font: xft:monaco:size=10<br />
<br />
Or<br />
<br />
URxvt.font: xft:monaco:bold:size=10<br />
<br />
{{Note|If there is a hyphen(-) in an Xft font name, it must be escaped with backslash(\) twice. It's different from the usage of urxvt -fn option and the result that fc-list returns, where backslash present only once}}<br />
<br />
A nice method for testing out fonts in a live terminal before committing to the config is by printing escape codes in the terminal, for example:<br />
<br />
$ printf '\e]710;%s\007' "xft:Terminus:pixelsize=12"<br />
<br />
=== Font spacing ===<br />
<br />
By default the distance between characters can feel too wide. The spacing can be reduced by one pixel as such:<br />
<br />
{{hc|~/.Xresources|<nowiki><br />
URxvt.letterSpace: -1<br />
</nowiki>}}<br />
<br />
There is some debate [http://lists.schmorp.de/pipermail/rxvt-unicode/2007q4/000511.html][http://lists.schmorp.de/pipermail/rxvt-unicode/2007q4/000512.html] over how ''urxvt'' calculates character widths. {{AUR|rxvt-unicode-patched}} changes this calculation, usually resulting in tighter character spacing.<br />
<br />
=== Colors ===<br />
<br />
By default, rxvt-unicode is compiled with color support. In addition to the default foreground and background colors, rxvt can display up to 256 colors (plus high-intensity bold/blinking/underlined and any mix of these).<br />
<br />
It is also possible to specify the color values of foreground, background, cursorColor, cursorColor2, colorBD, colorUL as a number 0-15, as a convenient shorthand to reference the color name of color0-color15. See [[#Xresources]] for details.<br />
<br />
{{Note|By default {{ic|urxvt}} uses the same colors as [[Xterm]], except one. Add {{ic|URxvt.color12: rgb:5c/5c/ff}} to Xresources to change this.}}<br />
<br />
== Cut and paste ==<br />
<br />
Rxvt-unicode uses cut buffers which are loaded into the current {{Ic|PRIMARY}} selection by default. See [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod#THE_SELECTION_SELECTING_AND_PASTING_ Selecting and pasting text] for details. <br />
<br />
It is possible to access the {{ic|CLIPBOARD}} selection with the bindings {{ic|ALT-CTRL-c}} and {{ic|ALT-CTRL-v}} for copy and paste respectively.<br />
<br />
{{Note|Selected text is automatically copied to {{ic|PRIMARY}} selection. The {{ic|selection-to-clipboard}} [[#Perl extensions|perl extension]], available since {{Pkg|rxvt-unicode}} 9.20, copies to {{ic|CLIPBOARD}} selection as well. }}<br />
<br />
See also [[Clipboard#List of clipboard managers]].<br />
<br />
== Perl extensions ==<br />
<br />
{{Style|Bias towards url-select while matcher and url-select are mostly equivalent, as well as man page duplication}}<br />
<br />
We can enable URxvt perl extensions by including the following line:<br />
<br />
URxvt.perl-ext-common: extension_name_1,extension_name_2,...<br />
<br />
Please take note that there '''should not''' be any spacing between extension names.<br />
<br />
=== Clickable URLs ===<br />
<br />
You can make URLs in the terminal clickable using the matcher extension. For example, to open links in the default web browser with the left mouse button, add the following to {{ic|.Xresources}}:<br />
<br />
URxvt.perl-ext-common: default,matcher<br />
URxvt.url-launcher: /usr/bin/xdg-open<br />
URxvt.matcher.button: 1<br />
<br />
Since rxvt-unicode 9.14, it's also possible to use matcher to open and list recent (currently limited to 10) URLs via keyboard:<br />
<br />
URxvt.keysym.C-Delete: perl:matcher:last<br />
URxvt.keysym.M-Delete: perl:matcher:list<br />
<br />
Matching links can be colored with a chosen foreground or background [[#Colors|color]], for example blue:<br />
<br />
URxvt.matcher.rend.0: Uline Bold fg5<br />
<br />
Alternatively, use {{ic|colorUL}} for a #RRGGBB color. This will however color all underlined text, instead of only link matches:<br />
<br />
URxvt.colorUL: #4682B4<br />
<br />
=== Yankable URLs (no mouse) ===<br />
In addition, you can select and open URLs in your web browser without using the mouse.<br />
Install the {{Pkg|urxvt-perls}} package from the [[official repositories]] and adjust your {{ic|.Xresources}} as necessary. An example is shown below:<br />
URxvt.perl-ext: default,url-select<br />
URxvt.keysym.M-u: perl:url-select:select_next<br />
URxvt.url-select.launcher: /usr/bin/xdg-open<br />
URxvt.url-select.underline: true<br />
<br />
{{Note|This extension replaces the Clickable URLs extension mentioned above, so {{Ic|matcher}} can be removed from the {{Ic|URxvt.perl-ext}} list.}}<br />
<br />
'''Key commands:'''<br />
<br />
{| class="wikitable"<br />
! Key !! Description<br />
|-<br />
| Alt+u || Enter selection mode. The last URL on your screen will be selected. You can repeat {{ic|Alt+u}} to select the next upward URL.<br />
|-<br />
| k || Select next upward URL<br />
|-<br />
| j || Select next downward URL<br />
|-<br />
| Return || Open selected URL in browser and quit selection mode<br />
|-<br />
| o || Open selected URL in browser without quitting selection mode<br />
|-<br />
| y || Copy (yank) selected URL and quit selection mode<br />
|-<br />
| Esc || Cancel URL selection mode<br />
|}<br />
<br />
=== Simple tabs ===<br />
<br />
To add tabs to urxvt, add the following to your {{ic|~/.Xresources}}:<br />
URxvt.perl-ext-common: ...,tabbed,...<br />
<br />
To control tabs use:<br />
<br />
{| class="wikitable"<br />
! Key !! Description<br />
|-<br />
| Shift+Down || New tab<br />
|-<br />
| Shift+Left || Go to left tab<br />
|-<br />
| Shift+Right || Go to right tab<br />
|-<br />
| Ctrl+Left || Move tab to the left<br />
|-<br />
| Ctrl+Right || Move tab to the right<br />
|-<br />
| Ctrl+d || Close tab<br />
|}<br />
<br />
You can change the colors of tabs with the following:<br />
<br />
URxvt.tabbed.tabbar-fg: 2<br />
URxvt.tabbed.tabbar-bg: 0<br />
URxvt.tabbed.tab-fg: 3<br />
URxvt.tabbed.tab-bg: 0<br />
<br />
=== Fullscreen ===<br />
<br />
You can install the [[AUR]] package {{AUR|urxvt-fullscreen}}, and then set a key binding to put urxvt fullscreen.<br />
<br />
{{hc|~/.Xresources|<br />
...<br />
URxvt.perl-ext-common: ...,fullscreen,...<br />
URxvt.keysym.F11: perl:fullscreen:switch<br />
...<br />
}}<br />
<br />
=== Changing font size on the fly ===<br />
<br />
Install {{AUR|urxvt-resize-font-git}} from the [[AUR]], add it to your Perl extensions within {{ic|~/.Xresources}}<br />
<br />
URxvt.perl-ext-common: ...,resize-font,...<br />
<br />
The default keybindings are<br />
* {{ic|Ctrl++}} (or {{ic|1=Ctrl+Shift+=}}) to increase size<br />
* {{ic|Ctrl+-}} to decrease size<br />
* {{ic|1=Ctrl+=}} to reset size<br />
* {{ic|Ctrl+?}} to see current size<br />
<br />
You can also change key bindings, for example like this:<br />
<br />
URxvt.resize-font.smaller: C-Down<br />
URxvt.resize-font.bigger: C-Up<br />
<br />
For the Ctrl+Shift bindings to work, a default binding needs to be disabled (see discussion [http://wilmer.gaa.st/blog/archives/36-rxvt-unicode-and-ISO-14755-mode.html here]):<br />
<br />
URxvt.iso14755: false<br />
URxvt.iso14755_52: false<br />
<br />
=== Disabling Perl extensions ===<br />
<br />
If you do not use the Perl extension features, you can improve the security and speed by disabling Perl extensions completely.<br />
URxvt.perl-ext:<br />
URxvt.perl-ext-common:<br />
<br />
{{Note|If you use multiple Perl extension features, you can list them in succession, comma-separated: {{ic|URxvt.perl-ext-common:default,matcher,tabbed}}}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Transparency not working after upgrade to v9.09 ===<br />
<br />
The rxvt-unicode developers removed compatibility code for a lot of non standard wallpaper setters with this update. Using a non compatible wallpaper setter will break transparency support. Recommended wallpaper setters:<br />
<br />
* [[feh]]<br />
* hsetroot<br />
* esetroot<br />
<br />
To make true transparency work, make sure to comment URxvt.tintColor and URxvt.inheritPixmap.<br />
<br />
=== Remote hosts ===<br />
<br />
If you are logging into a remote host, you may encounter problems when running text-mode programs under rxvt-unicode. This can be fixed by installing {{Pkg|rxvt-unicode-terminfo}} on the remote host or by copying {{ic|/usr/share/terminfo/r/rxvt-unicode}} from your local machine to your host at {{ic|~/.terminfo/r/rxvt-unicode}}; same for rxvt-unicode-256color.<br />
<br />
Some remote systems do not change title automatically unless you specify TERM=xterm. To fix the issue add this line to .bashrc on the remote machine:<br />
<br />
PROMPT_COMMAND='echo -ne "\033]0;${USER}@${HOSTNAME}:${PWD}\007"'<br />
<br />
=== Using rxvt-unicode as gmrun terminal ===<br />
<br />
Unlike some other terminals, urxvt expects the arguments to {{Ic|-e}} to be given separately, rather than grouped together with quotes. This causes trouble with gmrun, which assumes the opposite behavior. This can be worked around by putting an "eval" in front of gmrun's "Terminal" variable in {{ic|.gmrunrc}}:<br />
<br />
Terminal = eval urxvt<br />
TermExec = ${Terminal} -e<br />
<br />
(gmrun uses {{ic|/bin/sh}} to execute commands, so the "eval" is understood here.) The "eval" has the side-effect of "breaking up" the argument to {{Ic|-e}} in the same way that {{Ic|$@}} does in [[Bash]], making the command intelligible to urxvt.<br />
<br />
=== My numerical keypad acts weird and generates differing output? (e.g. in vim) ===<br />
<br />
Some Debian GNU/Linux users seem to have this problem, although no specific details were reported so far. It is possible that this is caused by the wrong TERM setting, although the details of whether and how this can happen are unknown, as TERM=rxvt should offer a compatible keymap. See the answer to the previous question, and please report if that helped.<br />
<br />
However, using the ''xmodmap'' program ({{Pkg|xorg-xmodmap}}), you can re-map your number pad keys back.<br />
<br />
1. Check the keycode that your numerical keypad (numpad) generates using {{ic|xev}} program.<br />
<br />
* Start the {{ic|xev}} program<br />
* Press your number pad keys and look for ''... keycode xxx ...'' in {{ic|xev}}'s output. For example, numpad 1 in my keyboard is also "End" key, that have a ''''keycode 87''''.<br />
<br />
2. Create or modify your xmodmap file, usually {{ic|~/.Xmodmap}}, with the content representing your keycode.<br />
<br />
Example of xmodmap file with number pad keycode:<br />
<br />
{{bc|1=<br />
keycode 63 = KP_Multiply<br />
keycode 79 = Home KP_7<br />
keycode 80 = Up KP_8<br />
keycode 81 = Prior KP_9<br />
keycode 82 = KP_Subtract<br />
keycode 83 = Left KP_4<br />
keycode 84 = KP_5<br />
keycode 85 = Right KP_6<br />
keycode 86 = KP_Add<br />
keycode 87 = End KP_1<br />
keycode 88 = Down KP_2<br />
keycode 89 = Next KP_3<br />
keycode 90 = Insert KP_0<br />
keycode 91 = Delete KP_Decimal<br />
keycode 112 = Prior<br />
keycode 117 = Next<br />
}}<br />
<br />
3. Load your xmodmap file at X session start-up.<br />
<br />
For example, in {{ic|~/.xinitrc}} file add:<br />
<br />
...<br />
xmodmap ~/.Xmodmap<br />
...<br />
<br />
=== Key combinations do not work ===<br />
<br />
See [http://vim.wikia.com/wiki/Get_Alt_key_to_work_in_terminal?useskin=monobook Get Alt key to work in terminal].<br />
<br />
=== Slow performance when drawing glyphs ===<br />
<br />
Some programs like alsamixer and xprop do not perform well with some graphics drivers and in consequence redraw very slowly. The option "skipBuiltinGlyphs" for {{ic|~/.Xresources}} or the command line option {{ic|-sbg}} may fix this. One possible solution is to add the following to {{ic|~/.Xresources}}:<br />
<br />
URxvt*skipBuiltinGlyphs: true<br />
<br />
=== Very long lines cause slowdown ===<br />
<br />
The {{ic|matcher}} plugin may be the culprit here. It must match a regex against a line every time the line updates, and if you have a large {{ic|saveLines}} value this can exacerbate the problem by allowing a very large maximum line length.<br />
<br />
There are some simple workarounds:<br />
<br />
* Reduce {{ic|saveLines}}<br />
* Disable the {{ic|matcher}} plugin<br />
<br />
If neither of those are palatable options, you can compromise by disabling URL matching past a certain cutoff point:<br />
<br />
# Copy {{ic|/usr/lib/urxvt/perl/matcher}} to {{ic|~/.urxvt/ext/}} (creating the directory if necessary)<br />
# Edit {{ic|~/.urxvt/ext/matcher}}, and find the {{ic|<nowiki>my ($self, $row) = @_;</nowiki>}} line in the {{ic|on_line_update}} sub. It should be line 270.<br />
# After that line, insert the line {{ic|return () if $row < -100;}}. This disables URL matching on any line that starts more than 100 rows behind the top of the terminal.<br />
<br />
== See also ==<br />
<br />
* [http://software.schmorp.de/pkg/rxvt-unicode.html rxvt-unicode] - Official site<br />
* [http://cvs.schmorp.de/rxvt-unicode/ Source Code] - Browseable CVS<br />
* [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.7.pod rxvt-unicode FAQ] - Official FAQ<br />
* [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/doc/rxvt.1.pod rxvt-unicode Reference] - Official manual page<br />
* [http://pod.tst.eu/http://cvs.schmorp.de/rxvt-unicode/src/urxvt.pm urxvtperl] - Official Perl extension reference</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=User:JoshuaRLi&diff=503014User:JoshuaRLi2017-12-17T19:15:50Z<p>JoshuaRLi: Added my own user page.</p>
<hr />
<div>I like python, shell, gnu/linux and f(l)oss.<br />
<br />
https://github.com/joshuarli</div>JoshuaRLihttps://wiki.archlinux.org/index.php?title=List_of_applications&diff=503013List of applications2017-12-17T19:13:02Z<p>JoshuaRLi: I added privacytools.io to the specialized software lists. It's a very well known privacy resource, with lots of great software recommendations (including Arch). Didn't find it elsewhere on the wiki.</p>
<hr />
<div>[[Category:Applications]]<br />
[[cs:List of applications]]<br />
[[es:List of applications]]<br />
[[fa:لیست برنامههای کاربردی]]<br />
[[it:List of applications]]<br />
[[ja:アプリケーション一覧]]<br />
[[ru:List of applications]]<br />
[[sv:Lättviktiga program]]<br />
[[zh-hans:List of applications]]<br />
[[zh-hant:List of applications]]<br />
{{List of applications navigation}}<br />
<br />
{{Related articles start}}<br />
{{Related|Core utilities}}<br />
{{Related|List of games}}<br />
{{Related articles end}}<br />
<br />
This article is a general list of applications sorted by category, as a reference for those looking for packages. Many sections are split between console and graphical applications.<br />
{{Tip|1=<br><br />
* This page exists primarily to make it easier to search for alternatives to an application that you do not know under which section has been added. Use the links in the template at the top to view the main sections as separate pages.<br />
* Please consider [[installing]] the [[pkgstats]] package, which provides a timer that sends a list of the packages installed on your system, along with the architecture and the mirrors you use, to the Arch Linux developers in order to help them prioritize their efforts and make the distribution even better. The information is sent anonymously and cannot be used to identify you. You can view the collected data at the [https://www.archlinux.de/?page=Statistics Statistics page]. More information is available in [https://bbs.archlinux.org/viewtopic.php?id=105431 this forum thread].<br />
* Daemon packages usually include the relevant systemd unit file to [[start]]; some packages even include different ones. After installation {{ic|pacman -Qql ''package'' <nowiki>|</nowiki> grep -Fe .service -e .socket}} can be used to check and find the relevant one.<br />
}}<br />
{{Note|Applications listed in "Console" sections can have graphical front-ends. Official ones are currently omitted.}}<br />
<!-- Subcategories --><br />
{{:List of applications/Internet}}<br />
{{:List of applications/Multimedia}}<br />
{{:List of applications/Utilities}}<br />
{{:List of applications/Documents}}<br />
{{:List of applications/Security}}<br />
{{:List of applications/Science}}<br />
{{:List of applications/Other}}<br />
<br />
== See also ==<br />
<br />
'''Generic software lists'''<br />
<br />
* [[Wikipedia:List of free and open source software packages]]<br />
* [[Wikipedia:List of GNU packages]]<br />
* [[Wikipedia:Portal:Free and open-source software]]<br />
* [https://alternativeto.net/platform/linux/ alternativeto.net] - Linux alternatives to popular programs<br />
* [https://linuxappfinder.com/all Linux App Finder] - Linux applications directory<br />
* [https://packages.debian.org Debian packages] and [https://screenshots.debian.net screenshots]<br />
* [http://www.linuxalt.com/ Linux Alternative Project] - Linux equivalents to Windows software<br />
* [https://www.osalt.com/ Open Source Alternative] - Alternatives to commercial software<br />
* [http://www.linuxlinks.com/ Linux Links] - Application and articles directory<br />
<br />
'''Software [[Wikipedia:Forge (software)|forges]]'''<br />
<br />
* [https://sourceforge.net/ Sourceforge.net] - Open Source Software forge<br />
* [https://launchpad.net/projects/+all Launchpad.net] - Open Source Software forge<br />
* [https://gitlab.com/explore Gitlab.com] - Open Source Software forge<br />
* [https://github.com/explore** GitHub.com] - Open Source Software forge<br />
<br />
'''Specialized software lists'''<br />
<br />
* [https://kmandla.wordpress.com/software/ K.Mandla's blog] - Terminal applications screenshots and reviews<br />
* [https://inconsolation.wordpress.com/index/ Inconsolation] - Lightweight and minimalist software<br />
* [https://github.com/alebcay/awesome-shell awesome-shell] - Command-line frameworks, toolkits and guides<br />
* [https://github.com/Kickball/awesome-selfhosted awesome-selfhosted] - Network services and web applications<br />
* [http://libreprojects.net/ Libre Projects] - Open Source hosted Web services<br />
* [https://github.com/n1trux/awesome-sysadmin awesome-sysadmin] - Software for system administrators<br />
* [https://github.com/nodiscc/awesome-linuxaudio awesome-linuxaudio] - Software for audio/video/live production<br />
* [https://prism-break.org/en/all/ PRISM Break] - Software against mass surveillance<br />
* [https://www.privacytools.io/ Privacy Tools] - Knowledge and tools to protect your privacy against global mass surveillance.<br />
* [http://lin-app.com/ lin-app.com] - Commercial applications and games for Linux<br />
<br />
'''Arch Linux forum threads'''<br />
<br />
* [https://bbs.archlinux.org/viewtopic.php?id=111878 Arch Linux Forums / LnF Awards 2011] - The best Light & Fast apps of 2011<br />
* [https://bbs.archlinux.org/viewtopic.php?id=138281 Arch Linux Forums / LnF Awards 2012] - The best Light & Fast apps of 2012<br />
* [https://bbs.archlinux.org/viewtopic.php?id=174764 Arch Linux Forums / most popular apps of 2013-2014]<br />
* [https://bbs.archlinux.org/viewtopic.php?pid=1702332 Arch Linux Forums / most popular apps of 2017+]</div>JoshuaRLi