https://wiki.archlinux.org/api.php?action=feedcontributions&user=Regid&feedformat=atomArchWiki - User contributions [en]2024-03-28T14:52:21ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Talk:PDF,_PS_and_DjVu&diff=804516Talk:PDF, PS and DjVu2024-03-25T09:50:55Z<p>Regid: /* LibreOffice as image-to-pdf convertor? */ Reply</p>
<hr />
<div>== Rename Basic Editors section ==<br />
<br />
I would rename this section in something like "Page Editors" or something like that, because that's what they really do.<br />
<br />
I would leave the word "Editor" for software that can actually act on the content of a page (insert/move/delete objects).<br />
<br />
So I would rename the "Advanced Editors" into "Editors".<br />
<br />
[[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 19:43, 16 July 2023 (UTC)<br />
<br />
The world of PDF editors is a weird one since they werent meant to be edited in the first place so I fully support some more clarity<br />
<br />
> software that can actually act on the content of a page<br />
<br />
How about we rename that section to exactly that, "Content editor"<br />
<br />
> "Page Editors"<br />
<br />
What do you think about "layout editor" which sounds a bit more clear to me.<br />
<br />
[[User:Nici|Nici]] ([[User talk:Nici|talk]]) 02:34, 17 July 2023 (UTC)<br />
<br />
== Add k2pdfopt to the wiki ? ==<br />
<br />
https://www.willus.com/k2pdfopt/<br />
An extremely usefull tool. Tough to build AUR package, but there's<br />
someone keeping up with the hard work, https://aur.archlinux.org/packages/k2pdfopt/<br />
Not sure where to put it in the article.Not sure if it was suggested before.<br />
<br />
{{unsigned|09:21, 3 December 2019|M040601}}<br />
<br />
== Scaling pdf ==<br />
<br />
I think it would be nice to discuss scaling pdf. I found a couple answers but found no supporting documentation in terms of how the posters found these answers.<br />
<br />
https://superuser.com/questions/676013/scaling-pdf-content-and-page-dimensions-from-command-line/676090#676090?newreg=9f301e4e969c4d948dffe786b56609a0<br />
<br />
https://unix.stackexchange.com/questions/146852/print-pdf-scaled-down-and-aligned<br />
<br />
<br />
[[User:ThinkPad|ThinkPad]] ([[User talk:ThinkPad|talk]]) 02:29, 3 June 2020 (UTC)<br />
<br />
<br />
== Create a PDF from images ==<br />
<br />
The man page of ImageMagick states ''"convert: Available for Backward compatiblity with ImageMagick's version 6 convert(1). Essentially, it is just an alias to a restrictive form of the magick(1) command, which should be used instead."''<br />
<br />
I think the wiki should recommend<br />
<br />
$ magick input_1.jpg input_2.jpg Input_3.jpg out.pdf<br />
<br />
[[User:Gerard|Gerard]] ([[User talk:Gerard|talk]]) 23:04, 29 March 2021 (UTC)<br />
<br />
:The section [[PDF, PS and DjVu#Create a PDF from images]] uses {{ic|gm convert}}, not {{ic|convert}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 3 April 2021 (UTC)<br />
<br />
::I put instructions for ImageMagick as well (note the command is {{ic|magick convert}}, just {{ic|convert}} is deprecated) [[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 05:04, 16 September 2023 (UTC)<br />
<br />
== LibreOffice as image-to-pdf convertor? ==<br />
<br />
The following is not related to the ImageMagick command discussed so far in this section, but is related to [[PDF,_PS_and_DjVu#Create a PDF from images]]:<br />
<br />
Quoting undoing revision [[Special:Diff/803987|803986]]: "this is not an image-to-pdf conversion". If you follow the process, you start with a file of an image (picture) and end with a pdf file that show the same image. Why this can not be thought of as a conversion process? I am also not sure the process can not be automated with the right LibreOffice related tools. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 00:50, 21 March 2024 (UTC)<br />
<br />
:It does not convert the image itself, but a document that includes the image. You get many useless things in the output: unrelated metadata as well as unnecessary content (e.g. white margins depending on the page size of the document) so the result is not even visually the same as using a proper image-to-pdf converter. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:10, 23 March 2024 (UTC)<br />
::As to the margins comment, to some degree you can change the margins settings in LibreOffice. There are also settings as {{ic|Width}}, {{ic|Height}}, {{ic|Keep ratio}}, {{ic|Original Size}}. It could be that with LibreOffice Draw you can also have a canvas size to your liking. As to the principal issue, I know very little about raster graphics, or about vector graphics. What LibreOffice does is most probably just an approximation for converting raster graphics to vector graphics. Or worth, it just embed the raster graphics as is. My point is although it could be far from perfect conversion, it is sufficient in many cases. And there are many people that are satisfied with it. I am not sure the methods mentioned so far are much better. Perhaps the section should begin with a statement there are no 100% algorithms for converting raster graphics into vector graphics. Which is why the suggested methods are only approximations. And include the comment about using LibreOffice for the job. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 21:29, 24 March 2024 (UTC)<br />
<br />
:::Why would you call this ''sufficient'' when all the other approaches produce better output, do not require manual configuration of the width/height/etc, and are available with much more lightweight programs (both {{pkg|imagemagick}} and {{pkg|graphicsmagick}} are over 20x smaller than libreoffice, not even mentioning {{pkg|img2pdf}})? Have you actually tried to use one of these tools? Why are you not satisfied with them and what problem are you trying to solve with libreoffice? — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:47, 24 March 2024 (UTC)<br />
::::I am using that feature. Mainly to have images embedded with text to send to people as pdf. I am quite satisfied with it, and haven't heard complaints about the image quality. I guess I am using it within the constraint of the conversion, if it can be called like that. As for mentioning it in the article, in my view this is one more option. In a way, some people might look at LibreOffice conversion as a more simple tool. One more place where their LibreOffice suit comes handy. For someone familiar with word processors, or only GUI sort of user, it can be thought of as an easier tool for a one time job. Despite the possible need, which is sometimes not required, to set some aspects of the conversion manually. With CLI tool one has to look for the required command options. Which can be thought of as a requirement to set some aspects of the conversion manually. And in a sometimes less obvious manner, as the manual page, or help text, or the example in the Internet is accompanied with only short explanation. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 09:50, 25 March 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:PDF,_PS_and_DjVu&diff=804453Talk:PDF, PS and DjVu2024-03-24T21:40:43Z<p>Regid: /* LibreOffice as image-to-pdf convertor? */ minor modification which does not change the claims</p>
<hr />
<div>== Rename Basic Editors section ==<br />
<br />
I would rename this section in something like "Page Editors" or something like that, because that's what they really do.<br />
<br />
I would leave the word "Editor" for software that can actually act on the content of a page (insert/move/delete objects).<br />
<br />
So I would rename the "Advanced Editors" into "Editors".<br />
<br />
[[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 19:43, 16 July 2023 (UTC)<br />
<br />
The world of PDF editors is a weird one since they werent meant to be edited in the first place so I fully support some more clarity<br />
<br />
> software that can actually act on the content of a page<br />
<br />
How about we rename that section to exactly that, "Content editor"<br />
<br />
> "Page Editors"<br />
<br />
What do you think about "layout editor" which sounds a bit more clear to me.<br />
<br />
[[User:Nici|Nici]] ([[User talk:Nici|talk]]) 02:34, 17 July 2023 (UTC)<br />
<br />
== Add k2pdfopt to the wiki ? ==<br />
<br />
https://www.willus.com/k2pdfopt/<br />
An extremely usefull tool. Tough to build AUR package, but there's<br />
someone keeping up with the hard work, https://aur.archlinux.org/packages/k2pdfopt/<br />
Not sure where to put it in the article.Not sure if it was suggested before.<br />
<br />
{{unsigned|09:21, 3 December 2019|M040601}}<br />
<br />
== Scaling pdf ==<br />
<br />
I think it would be nice to discuss scaling pdf. I found a couple answers but found no supporting documentation in terms of how the posters found these answers.<br />
<br />
https://superuser.com/questions/676013/scaling-pdf-content-and-page-dimensions-from-command-line/676090#676090?newreg=9f301e4e969c4d948dffe786b56609a0<br />
<br />
https://unix.stackexchange.com/questions/146852/print-pdf-scaled-down-and-aligned<br />
<br />
<br />
[[User:ThinkPad|ThinkPad]] ([[User talk:ThinkPad|talk]]) 02:29, 3 June 2020 (UTC)<br />
<br />
<br />
== Create a PDF from images ==<br />
<br />
The man page of ImageMagick states ''"convert: Available for Backward compatiblity with ImageMagick's version 6 convert(1). Essentially, it is just an alias to a restrictive form of the magick(1) command, which should be used instead."''<br />
<br />
I think the wiki should recommend<br />
<br />
$ magick input_1.jpg input_2.jpg Input_3.jpg out.pdf<br />
<br />
[[User:Gerard|Gerard]] ([[User talk:Gerard|talk]]) 23:04, 29 March 2021 (UTC)<br />
<br />
:The section [[PDF, PS and DjVu#Create a PDF from images]] uses {{ic|gm convert}}, not {{ic|convert}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 3 April 2021 (UTC)<br />
<br />
::I put instructions for ImageMagick as well (note the command is {{ic|magick convert}}, just {{ic|convert}} is deprecated) [[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 05:04, 16 September 2023 (UTC)<br />
<br />
== LibreOffice as image-to-pdf convertor? ==<br />
<br />
The following is not related to the ImageMagick command discussed so far in this section, but is related to [[PDF,_PS_and_DjVu#Create a PDF from images]]:<br />
<br />
Quoting undoing revision [[Special:Diff/803987|803986]]: "this is not an image-to-pdf conversion". If you follow the process, you start with a file of an image (picture) and end with a pdf file that show the same image. Why this can not be thought of as a conversion process? I am also not sure the process can not be automated with the right LibreOffice related tools. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 00:50, 21 March 2024 (UTC)<br />
<br />
:It does not convert the image itself, but a document that includes the image. You get many useless things in the output: unrelated metadata as well as unnecessary content (e.g. white margins depending on the page size of the document) so the result is not even visually the same as using a proper image-to-pdf converter. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:10, 23 March 2024 (UTC)<br />
::As to the margins comment, to some degree you can change the margins settings in LibreOffice. There are also settings as {{ic|Width}}, {{ic|Height}}, {{ic|Keep ratio}}, {{ic|Original Size}}. It could be that with LibreOffice Draw you can also have a canvas size to your liking. As to the principal issue, I know very little about raster graphics, or about vector graphics. What LibreOffice does is most probably just an approximation for converting raster graphics to vector graphics. Or worth, it just embed the raster graphics as is. My point is although it could be far from perfect conversion, it is sufficient in many cases. And there are many people that are satisfied with it. I am not sure the methods mentioned so far are much better. Perhaps the section should begin with a statement there are no 100% algorithms for converting raster graphics into vector graphics. Which is why the suggested methods are only approximations. And include the comment about using LibreOffice for the job. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 21:29, 24 March 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:PDF,_PS_and_DjVu&diff=804450Talk:PDF, PS and DjVu2024-03-24T21:29:45Z<p>Regid: /* LibreOffice as image-to-pdf convertor? */ Reply</p>
<hr />
<div>== Rename Basic Editors section ==<br />
<br />
I would rename this section in something like "Page Editors" or something like that, because that's what they really do.<br />
<br />
I would leave the word "Editor" for software that can actually act on the content of a page (insert/move/delete objects).<br />
<br />
So I would rename the "Advanced Editors" into "Editors".<br />
<br />
[[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 19:43, 16 July 2023 (UTC)<br />
<br />
The world of PDF editors is a weird one since they werent meant to be edited in the first place so I fully support some more clarity<br />
<br />
> software that can actually act on the content of a page<br />
<br />
How about we rename that section to exactly that, "Content editor"<br />
<br />
> "Page Editors"<br />
<br />
What do you think about "layout editor" which sounds a bit more clear to me.<br />
<br />
[[User:Nici|Nici]] ([[User talk:Nici|talk]]) 02:34, 17 July 2023 (UTC)<br />
<br />
== Add k2pdfopt to the wiki ? ==<br />
<br />
https://www.willus.com/k2pdfopt/<br />
An extremely usefull tool. Tough to build AUR package, but there's<br />
someone keeping up with the hard work, https://aur.archlinux.org/packages/k2pdfopt/<br />
Not sure where to put it in the article.Not sure if it was suggested before.<br />
<br />
{{unsigned|09:21, 3 December 2019|M040601}}<br />
<br />
== Scaling pdf ==<br />
<br />
I think it would be nice to discuss scaling pdf. I found a couple answers but found no supporting documentation in terms of how the posters found these answers.<br />
<br />
https://superuser.com/questions/676013/scaling-pdf-content-and-page-dimensions-from-command-line/676090#676090?newreg=9f301e4e969c4d948dffe786b56609a0<br />
<br />
https://unix.stackexchange.com/questions/146852/print-pdf-scaled-down-and-aligned<br />
<br />
<br />
[[User:ThinkPad|ThinkPad]] ([[User talk:ThinkPad|talk]]) 02:29, 3 June 2020 (UTC)<br />
<br />
<br />
== Create a PDF from images ==<br />
<br />
The man page of ImageMagick states ''"convert: Available for Backward compatiblity with ImageMagick's version 6 convert(1). Essentially, it is just an alias to a restrictive form of the magick(1) command, which should be used instead."''<br />
<br />
I think the wiki should recommend<br />
<br />
$ magick input_1.jpg input_2.jpg Input_3.jpg out.pdf<br />
<br />
[[User:Gerard|Gerard]] ([[User talk:Gerard|talk]]) 23:04, 29 March 2021 (UTC)<br />
<br />
:The section [[PDF, PS and DjVu#Create a PDF from images]] uses {{ic|gm convert}}, not {{ic|convert}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 3 April 2021 (UTC)<br />
<br />
::I put instructions for ImageMagick as well (note the command is {{ic|magick convert}}, just {{ic|convert}} is deprecated) [[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 05:04, 16 September 2023 (UTC)<br />
<br />
== LibreOffice as image-to-pdf convertor? ==<br />
<br />
The following is not related to the ImageMagick command discussed so far in this section, but is related to [[PDF,_PS_and_DjVu#Create a PDF from images]]:<br />
<br />
Quoting undoing revision [[Special:Diff/803987|803986]]: "this is not an image-to-pdf conversion". If you follow the process, you start with a file of an image (picture) and end with a pdf file that show the same image. Why this can not be thought of as a conversion process? I am also not sure the process can not be automated with the right LibreOffice related tools. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 00:50, 21 March 2024 (UTC)<br />
<br />
:It does not convert the image itself, but a document that includes the image. You get many useless things in the output: unrelated metadata as well as unnecessary content (e.g. white margins depending on the page size of the document) so the result is not even visually the same as using a proper image-to-pdf converter. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 08:10, 23 March 2024 (UTC)<br />
::About the margins comment, to some degree you can change the margins settings in LibreOffice. There are also settings as {{ic|Width}}, {{ic|Height}}, {{ic|Keep ratio}}, {{ic|Original Size}}. It could be that with LibreOffice Draw you can also have a canvas size to your liking. As to the principal issue, I know very little about raster graphics, or about vector graphics. What LibreOffice does is most probably just an approximation for converting raster graphics to vector graphics. Or worth, it just embed the raster graphics as is. My point is although it could be far from perfect conversion, it is sufficient in many cases. And there are many people that are satisfied with it. I am not sure the methods mentioned so far are much better. Perhaps the section should begin with a statement there are no 100% algorithms for converting raster graphics into vector graphics. Which is why the suggested methods are only approximations. And include the comment about using LibreOffice for the job. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 21:29, 24 March 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Uniform_look_for_Qt_and_GTK_applications&diff=804025Talk:Uniform look for Qt and GTK applications2024-03-21T01:12:27Z<p>Regid: /* Terminal Error with Instruction to Use Awk in Tips and tricks */ Indenting the code in the response</p>
<hr />
<div>== Distinguish theming GTK apps in KDE vs QT apps in Gnome? ==<br />
Right now I felt like the article was mostly talking about theming GTK apps in KDE while I want to theme QT apps in Gnome.<br />
I found it sorta unfortunate this distinction was not made explicit though, as this left me quite confused as to whether the info I'm reading is relevant to me... - [[User:Tycho01|Tycho01]] ([[User talk:Tycho01|talk]]) 16:19, 5 October 2019 (UTC)<br />
<br />
== UKUI ==<br />
<br />
I saw in https://wiki.archlinux.org/index.php/Desktop_environment that {{pkg|ukui}} is officially supported in ArchLinux and is developed based on both GTK and Qt. So I'm wondering how it is working and if it offers an uniform look for both engines or is using one form some parts and the other for others. {{Unsigned|13:44, 1 July 2020 (UTC)|Noraj}}<br />
<br />
== Tips and tricks - consistent file dialog ==<br />
<br />
Hey, I just spent a few hours trying to work out why GIO trash functionality was broken and why Cinnamon/libxapp 'xapp-sn-watcher' daemon was crashing whenever I started Cinnamon - it turns out setting GTK_USE_PORTAL=1 *globally* in /etc/environment is a really bad idea. This may have been a simple mistake from ignorance on my part but would anyone mind if I changed the line<br />
<br />
Install xdg-desktop-portal and xdg-desktop-portal-kde and set GTK_USE_PORTAL=1 as environment variable.<br />
<br />
to include something about how one should set that variable in the launcher for the specific program rather than in ~.profile or /etc/environment? It looks like I'm not the only person who's had this issue ( https://www.reddit.com/r/archlinux/comments/f69349/gnomegiogvfs_directories_refuse_to_be_moved_to/ ) so it might save someone some time in the future. {{Unsigned|03:57, 15 November 2020 (UTC)|Areographe}}<br />
<br />
: Where should I define this variable? I tried Thunderbird and it works when invoked directly as {{ic|1=GTK_USE_PORTAL=1 thunderbird}}. Saving email attachment uses dolphin's interface. However, when I define {{ic|1=export GTK_USE_PORTAL=1}} in ~/.profile, then log out and log in to kde, then launch thunderbird via start menu, it still uses the gtk file dialog to save file. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:33, 12 March 2021 (UTC)<br />
:: Reading the [[Environment variables]] I understand that defining variable in ~/.profile just affected a bash shell in konsole, but not the whole desktop environment. Setting the variable in /etc/environment and rebooting worked as expected - thunderbird uses kde file picker now.<br />
:: What about above question with trash functionality, I am not using cinnamon, so I cannot test if the issue still happens. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:37, 5 June 2021 (UTC)<br />
<br />
== kde-gtk-config ==<br />
<br />
Not sure if this is the right place, but I noticed the wiki tells that you can run kde-gtk-config from the command line, here<br />
> If running KDE Plasma, install kde-gtk-config and either run it from the command line<br />
<br />
I don't know if this is a mistake or not, but at the very least we should explain how to run it, since {{pkg|kde-gtk-config}} does not provide any executable. There might still be a way to load the library it provides in a graphical container, but I don't know how, and I suspect I'm not alone. If you are more knoledgable in this area, please update that section.<br />
<br />
{{Unsigned|13:31, 6 January 2022 (UTC)|Antoinep92}}<br />
<br />
== <s>Terminal Error with Instruction to Use Awk in Tips and tricks</s> ==<br />
<br />
awk -F\" '/<bookmark href=\"file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
in Tips and Tricks throws an error:<br />
awk: cmd. line:1: warning: regexp escape sequence `\"' is not a known regexp operator<br />
[[User:Neko-san|Neko-san]] ([[User talk:Neko-san|talk]]) 21:01, 22 April 2022 (UTC)<br />
:Quoting current code at [[Uniform_look_for_Qt_and_GTK_applications#Consistent file dialog under KDE Plasma|4.4 Consistent file dialog under KDE Plasma]]:<br />
:{{bc|1=$ awk -F\" '/<bookmark href="file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks}}<br />
:Therefore, I followed [[Help:Discussion#Closing a discussion]] to strike the section header. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:05, 21 March 2024 (UTC)<br />
<br />
== Installing xdg-desktop-portal-gtk to help with GTK styling in Wayland Plasma ==<br />
<br />
I ran into an issue today when trying out Wayland with Plasma for the first time. In Wayland, the mouse cursor would change when over top of a GTK app (Firefox, pamac, or the GTK style preview from KDE's settings specifically), and GTK fonts were horribly rendered.<br />
<br />
There's a comment here[https://bugs.kde.org/show_bug.cgi?id=474746#c3] about installing the GTK portal. That fixed the problem for me, but I wasn't able to find it documented anywhere in the wiki. There's also discussion at the link about editing /usr/share/xdg-desktop-portal/kde-portals.conf, which is owned by the package xdg-desktop-portal-kde.<br />
<br />
<br />
What's the best place to document this? The section about Breeze perhaps? [[User:Fynzh|Fynzh]] ([[User talk:Fynzh|talk]]) 21:03, 26 November 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Uniform_look_for_Qt_and_GTK_applications&diff=804024Talk:Uniform look for Qt and GTK applications2024-03-21T01:10:11Z<p>Regid: /* Terminal Error with Instruction to Use Awk in Tips and tricks */ No need tor a copy of the response</p>
<hr />
<div>== Distinguish theming GTK apps in KDE vs QT apps in Gnome? ==<br />
Right now I felt like the article was mostly talking about theming GTK apps in KDE while I want to theme QT apps in Gnome.<br />
I found it sorta unfortunate this distinction was not made explicit though, as this left me quite confused as to whether the info I'm reading is relevant to me... - [[User:Tycho01|Tycho01]] ([[User talk:Tycho01|talk]]) 16:19, 5 October 2019 (UTC)<br />
<br />
== UKUI ==<br />
<br />
I saw in https://wiki.archlinux.org/index.php/Desktop_environment that {{pkg|ukui}} is officially supported in ArchLinux and is developed based on both GTK and Qt. So I'm wondering how it is working and if it offers an uniform look for both engines or is using one form some parts and the other for others. {{Unsigned|13:44, 1 July 2020 (UTC)|Noraj}}<br />
<br />
== Tips and tricks - consistent file dialog ==<br />
<br />
Hey, I just spent a few hours trying to work out why GIO trash functionality was broken and why Cinnamon/libxapp 'xapp-sn-watcher' daemon was crashing whenever I started Cinnamon - it turns out setting GTK_USE_PORTAL=1 *globally* in /etc/environment is a really bad idea. This may have been a simple mistake from ignorance on my part but would anyone mind if I changed the line<br />
<br />
Install xdg-desktop-portal and xdg-desktop-portal-kde and set GTK_USE_PORTAL=1 as environment variable.<br />
<br />
to include something about how one should set that variable in the launcher for the specific program rather than in ~.profile or /etc/environment? It looks like I'm not the only person who's had this issue ( https://www.reddit.com/r/archlinux/comments/f69349/gnomegiogvfs_directories_refuse_to_be_moved_to/ ) so it might save someone some time in the future. {{Unsigned|03:57, 15 November 2020 (UTC)|Areographe}}<br />
<br />
: Where should I define this variable? I tried Thunderbird and it works when invoked directly as {{ic|1=GTK_USE_PORTAL=1 thunderbird}}. Saving email attachment uses dolphin's interface. However, when I define {{ic|1=export GTK_USE_PORTAL=1}} in ~/.profile, then log out and log in to kde, then launch thunderbird via start menu, it still uses the gtk file dialog to save file. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:33, 12 March 2021 (UTC)<br />
:: Reading the [[Environment variables]] I understand that defining variable in ~/.profile just affected a bash shell in konsole, but not the whole desktop environment. Setting the variable in /etc/environment and rebooting worked as expected - thunderbird uses kde file picker now.<br />
:: What about above question with trash functionality, I am not using cinnamon, so I cannot test if the issue still happens. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:37, 5 June 2021 (UTC)<br />
<br />
== kde-gtk-config ==<br />
<br />
Not sure if this is the right place, but I noticed the wiki tells that you can run kde-gtk-config from the command line, here<br />
> If running KDE Plasma, install kde-gtk-config and either run it from the command line<br />
<br />
I don't know if this is a mistake or not, but at the very least we should explain how to run it, since {{pkg|kde-gtk-config}} does not provide any executable. There might still be a way to load the library it provides in a graphical container, but I don't know how, and I suspect I'm not alone. If you are more knoledgable in this area, please update that section.<br />
<br />
{{Unsigned|13:31, 6 January 2022 (UTC)|Antoinep92}}<br />
<br />
== <s>Terminal Error with Instruction to Use Awk in Tips and tricks</s> ==<br />
<br />
awk -F\" '/<bookmark href=\"file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
in Tips and Tricks throws an error:<br />
awk: cmd. line:1: warning: regexp escape sequence `\"' is not a known regexp operator<br />
[[User:Neko-san|Neko-san]] ([[User talk:Neko-san|talk]]) 21:01, 22 April 2022 (UTC)<br />
:Quoting current code at [[Uniform_look_for_Qt_and_GTK_applications#Consistent file dialog under KDE Plasma|4.4 Consistent file dialog under KDE Plasma]]:<br />
{{bc|1=$ awk -F\" '/<bookmark href="file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks}}<br />
:Therefore, I followed [[Help:Discussion#Closing a discussion]] to strike the section header. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:05, 21 March 2024 (UTC)<br />
<br />
== Installing xdg-desktop-portal-gtk to help with GTK styling in Wayland Plasma ==<br />
<br />
I ran into an issue today when trying out Wayland with Plasma for the first time. In Wayland, the mouse cursor would change when over top of a GTK app (Firefox, pamac, or the GTK style preview from KDE's settings specifically), and GTK fonts were horribly rendered.<br />
<br />
There's a comment here[https://bugs.kde.org/show_bug.cgi?id=474746#c3] about installing the GTK portal. That fixed the problem for me, but I wasn't able to find it documented anywhere in the wiki. There's also discussion at the link about editing /usr/share/xdg-desktop-portal/kde-portals.conf, which is owned by the package xdg-desktop-portal-kde.<br />
<br />
<br />
What's the best place to document this? The section about Breeze perhaps? [[User:Fynzh|Fynzh]] ([[User talk:Fynzh|talk]]) 21:03, 26 November 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Uniform_look_for_Qt_and_GTK_applications&diff=804023Talk:Uniform look for Qt and GTK applications2024-03-21T01:07:06Z<p>Regid: /* Terminal Error with Instruction to Use Awk in Tips and tricks */ Reply</p>
<hr />
<div>== Distinguish theming GTK apps in KDE vs QT apps in Gnome? ==<br />
Right now I felt like the article was mostly talking about theming GTK apps in KDE while I want to theme QT apps in Gnome.<br />
I found it sorta unfortunate this distinction was not made explicit though, as this left me quite confused as to whether the info I'm reading is relevant to me... - [[User:Tycho01|Tycho01]] ([[User talk:Tycho01|talk]]) 16:19, 5 October 2019 (UTC)<br />
<br />
== UKUI ==<br />
<br />
I saw in https://wiki.archlinux.org/index.php/Desktop_environment that {{pkg|ukui}} is officially supported in ArchLinux and is developed based on both GTK and Qt. So I'm wondering how it is working and if it offers an uniform look for both engines or is using one form some parts and the other for others. {{Unsigned|13:44, 1 July 2020 (UTC)|Noraj}}<br />
<br />
== Tips and tricks - consistent file dialog ==<br />
<br />
Hey, I just spent a few hours trying to work out why GIO trash functionality was broken and why Cinnamon/libxapp 'xapp-sn-watcher' daemon was crashing whenever I started Cinnamon - it turns out setting GTK_USE_PORTAL=1 *globally* in /etc/environment is a really bad idea. This may have been a simple mistake from ignorance on my part but would anyone mind if I changed the line<br />
<br />
Install xdg-desktop-portal and xdg-desktop-portal-kde and set GTK_USE_PORTAL=1 as environment variable.<br />
<br />
to include something about how one should set that variable in the launcher for the specific program rather than in ~.profile or /etc/environment? It looks like I'm not the only person who's had this issue ( https://www.reddit.com/r/archlinux/comments/f69349/gnomegiogvfs_directories_refuse_to_be_moved_to/ ) so it might save someone some time in the future. {{Unsigned|03:57, 15 November 2020 (UTC)|Areographe}}<br />
<br />
: Where should I define this variable? I tried Thunderbird and it works when invoked directly as {{ic|1=GTK_USE_PORTAL=1 thunderbird}}. Saving email attachment uses dolphin's interface. However, when I define {{ic|1=export GTK_USE_PORTAL=1}} in ~/.profile, then log out and log in to kde, then launch thunderbird via start menu, it still uses the gtk file dialog to save file. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:33, 12 March 2021 (UTC)<br />
:: Reading the [[Environment variables]] I understand that defining variable in ~/.profile just affected a bash shell in konsole, but not the whole desktop environment. Setting the variable in /etc/environment and rebooting worked as expected - thunderbird uses kde file picker now.<br />
:: What about above question with trash functionality, I am not using cinnamon, so I cannot test if the issue still happens. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:37, 5 June 2021 (UTC)<br />
<br />
== kde-gtk-config ==<br />
<br />
Not sure if this is the right place, but I noticed the wiki tells that you can run kde-gtk-config from the command line, here<br />
> If running KDE Plasma, install kde-gtk-config and either run it from the command line<br />
<br />
I don't know if this is a mistake or not, but at the very least we should explain how to run it, since {{pkg|kde-gtk-config}} does not provide any executable. There might still be a way to load the library it provides in a graphical container, but I don't know how, and I suspect I'm not alone. If you are more knoledgable in this area, please update that section.<br />
<br />
{{Unsigned|13:31, 6 January 2022 (UTC)|Antoinep92}}<br />
<br />
== <s>Terminal Error with Instruction to Use Awk in Tips and tricks</s> ==<br />
<br />
awk -F\" '/<bookmark href=\"file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
in Tips and Tricks throws an error:<br />
awk: cmd. line:1: warning: regexp escape sequence `\"' is not a known regexp operator<br />
[[User:Neko-san|Neko-san]] ([[User talk:Neko-san|talk]]) 21:01, 22 April 2022 (UTC)<br />
:Quoting current code at [[Uniform_look_for_Qt_and_GTK_applications#Consistent file dialog under KDE Plasma 4.4 Consistent file dialog under KDE Plasma]]:<br />
$ awk -F\" '/<bookmark href="file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
:Therefore, I followed [[Help:Discussion#Closing a discussion]] to strike the section header. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:05, 21 March 2024 (UTC)<br />
:Quoting current code [[Uniform_look_for_Qt_and_GTK_applications#Consistent file dialog under KDE Plasma 4.4 Consistent file dialog under KDE Plasma]] presents:<br />
:$ awk -F\" '/<bookmark href="file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
:a [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:07, 21 March 2024 (UTC)<br />
<br />
== Installing xdg-desktop-portal-gtk to help with GTK styling in Wayland Plasma ==<br />
<br />
I ran into an issue today when trying out Wayland with Plasma for the first time. In Wayland, the mouse cursor would change when over top of a GTK app (Firefox, pamac, or the GTK style preview from KDE's settings specifically), and GTK fonts were horribly rendered.<br />
<br />
There's a comment here[https://bugs.kde.org/show_bug.cgi?id=474746#c3] about installing the GTK portal. That fixed the problem for me, but I wasn't able to find it documented anywhere in the wiki. There's also discussion at the link about editing /usr/share/xdg-desktop-portal/kde-portals.conf, which is owned by the package xdg-desktop-portal-kde.<br />
<br />
<br />
What's the best place to document this? The section about Breeze perhaps? [[User:Fynzh|Fynzh]] ([[User talk:Fynzh|talk]]) 21:03, 26 November 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Uniform_look_for_Qt_and_GTK_applications&diff=804022Talk:Uniform look for Qt and GTK applications2024-03-21T01:05:20Z<p>Regid: /* Terminal Error with Instruction to Use Awk in Tips and tricks */ In my opinion, this thread is exhausted.</p>
<hr />
<div>== Distinguish theming GTK apps in KDE vs QT apps in Gnome? ==<br />
Right now I felt like the article was mostly talking about theming GTK apps in KDE while I want to theme QT apps in Gnome.<br />
I found it sorta unfortunate this distinction was not made explicit though, as this left me quite confused as to whether the info I'm reading is relevant to me... - [[User:Tycho01|Tycho01]] ([[User talk:Tycho01|talk]]) 16:19, 5 October 2019 (UTC)<br />
<br />
== UKUI ==<br />
<br />
I saw in https://wiki.archlinux.org/index.php/Desktop_environment that {{pkg|ukui}} is officially supported in ArchLinux and is developed based on both GTK and Qt. So I'm wondering how it is working and if it offers an uniform look for both engines or is using one form some parts and the other for others. {{Unsigned|13:44, 1 July 2020 (UTC)|Noraj}}<br />
<br />
== Tips and tricks - consistent file dialog ==<br />
<br />
Hey, I just spent a few hours trying to work out why GIO trash functionality was broken and why Cinnamon/libxapp 'xapp-sn-watcher' daemon was crashing whenever I started Cinnamon - it turns out setting GTK_USE_PORTAL=1 *globally* in /etc/environment is a really bad idea. This may have been a simple mistake from ignorance on my part but would anyone mind if I changed the line<br />
<br />
Install xdg-desktop-portal and xdg-desktop-portal-kde and set GTK_USE_PORTAL=1 as environment variable.<br />
<br />
to include something about how one should set that variable in the launcher for the specific program rather than in ~.profile or /etc/environment? It looks like I'm not the only person who's had this issue ( https://www.reddit.com/r/archlinux/comments/f69349/gnomegiogvfs_directories_refuse_to_be_moved_to/ ) so it might save someone some time in the future. {{Unsigned|03:57, 15 November 2020 (UTC)|Areographe}}<br />
<br />
: Where should I define this variable? I tried Thunderbird and it works when invoked directly as {{ic|1=GTK_USE_PORTAL=1 thunderbird}}. Saving email attachment uses dolphin's interface. However, when I define {{ic|1=export GTK_USE_PORTAL=1}} in ~/.profile, then log out and log in to kde, then launch thunderbird via start menu, it still uses the gtk file dialog to save file. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:33, 12 March 2021 (UTC)<br />
:: Reading the [[Environment variables]] I understand that defining variable in ~/.profile just affected a bash shell in konsole, but not the whole desktop environment. Setting the variable in /etc/environment and rebooting worked as expected - thunderbird uses kde file picker now.<br />
:: What about above question with trash functionality, I am not using cinnamon, so I cannot test if the issue still happens. [[User:Ashark|Ashark]] ([[User talk:Ashark|talk]]) 10:37, 5 June 2021 (UTC)<br />
<br />
== kde-gtk-config ==<br />
<br />
Not sure if this is the right place, but I noticed the wiki tells that you can run kde-gtk-config from the command line, here<br />
> If running KDE Plasma, install kde-gtk-config and either run it from the command line<br />
<br />
I don't know if this is a mistake or not, but at the very least we should explain how to run it, since {{pkg|kde-gtk-config}} does not provide any executable. There might still be a way to load the library it provides in a graphical container, but I don't know how, and I suspect I'm not alone. If you are more knoledgable in this area, please update that section.<br />
<br />
{{Unsigned|13:31, 6 January 2022 (UTC)|Antoinep92}}<br />
<br />
== <s>Terminal Error with Instruction to Use Awk in Tips and tricks</s> ==<br />
<br />
awk -F\" '/<bookmark href=\"file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
in Tips and Tricks throws an error:<br />
awk: cmd. line:1: warning: regexp escape sequence `\"' is not a known regexp operator<br />
[[User:Neko-san|Neko-san]] ([[User talk:Neko-san|talk]]) 21:01, 22 April 2022 (UTC)<br />
:Quoting current code at [[Uniform_look_for_Qt_and_GTK_applications#Consistent file dialog under KDE Plasma 4.4 Consistent file dialog under KDE Plasma]]:<br />
$ awk -F\" '/<bookmark href="file/ {print $2}' < $HOME/.local/share/user-places.xbel > $HOME/.config/gtk-3.0/bookmarks<br />
:Therefore, I followed [[Help:Discussion#Closing a discussion]] to strike the section header. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:05, 21 March 2024 (UTC)<br />
<br />
== Installing xdg-desktop-portal-gtk to help with GTK styling in Wayland Plasma ==<br />
<br />
I ran into an issue today when trying out Wayland with Plasma for the first time. In Wayland, the mouse cursor would change when over top of a GTK app (Firefox, pamac, or the GTK style preview from KDE's settings specifically), and GTK fonts were horribly rendered.<br />
<br />
There's a comment here[https://bugs.kde.org/show_bug.cgi?id=474746#c3] about installing the GTK portal. That fixed the problem for me, but I wasn't able to find it documented anywhere in the wiki. There's also discussion at the link about editing /usr/share/xdg-desktop-portal/kde-portals.conf, which is owned by the package xdg-desktop-portal-kde.<br />
<br />
<br />
What's the best place to document this? The section about Breeze perhaps? [[User:Fynzh|Fynzh]] ([[User talk:Fynzh|talk]]) 21:03, 26 November 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:PDF,_PS_and_DjVu&diff=804021Talk:PDF, PS and DjVu2024-03-21T00:50:00Z<p>Regid: /* Create a PDF from images */ Response to another undoing revision of PDF,_PS_and_DjVu#Create a PDF from images</p>
<hr />
<div>== Rename Basic Editors section ==<br />
<br />
I would rename this section in something like "Page Editors" or something like that, because that's what they really do.<br />
<br />
I would leave the word "Editor" for software that can actually act on the content of a page (insert/move/delete objects).<br />
<br />
So I would rename the "Advanced Editors" into "Editors".<br />
<br />
[[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 19:43, 16 July 2023 (UTC)<br />
<br />
The world of PDF editors is a weird one since they werent meant to be edited in the first place so I fully support some more clarity<br />
<br />
> software that can actually act on the content of a page<br />
<br />
How about we rename that section to exactly that, "Content editor"<br />
<br />
> "Page Editors"<br />
<br />
What do you think about "layout editor" which sounds a bit more clear to me.<br />
<br />
[[User:Nici|Nici]] ([[User talk:Nici|talk]]) 02:34, 17 July 2023 (UTC)<br />
<br />
== Add k2pdfopt to the wiki ? ==<br />
<br />
https://www.willus.com/k2pdfopt/<br />
An extremely usefull tool. Tough to build AUR package, but there's<br />
someone keeping up with the hard work, https://aur.archlinux.org/packages/k2pdfopt/<br />
Not sure where to put it in the article.Not sure if it was suggested before.<br />
<br />
{{unsigned|09:21, 3 December 2019|M040601}}<br />
<br />
== Scaling pdf ==<br />
<br />
I think it would be nice to discuss scaling pdf. I found a couple answers but found no supporting documentation in terms of how the posters found these answers.<br />
<br />
https://superuser.com/questions/676013/scaling-pdf-content-and-page-dimensions-from-command-line/676090#676090?newreg=9f301e4e969c4d948dffe786b56609a0<br />
<br />
https://unix.stackexchange.com/questions/146852/print-pdf-scaled-down-and-aligned<br />
<br />
<br />
[[User:ThinkPad|ThinkPad]] ([[User talk:ThinkPad|talk]]) 02:29, 3 June 2020 (UTC)<br />
<br />
<br />
== Create a PDF from images ==<br />
<br />
The man page of ImageMagick states ''"convert: Available for Backward compatiblity with ImageMagick's version 6 convert(1). Essentially, it is just an alias to a restrictive form of the magick(1) command, which should be used instead."''<br />
<br />
I think the wiki should recommend<br />
<br />
$ magick input_1.jpg input_2.jpg Input_3.jpg out.pdf<br />
<br />
[[User:Gerard|Gerard]] ([[User talk:Gerard|talk]]) 23:04, 29 March 2021 (UTC)<br />
<br />
:The section [[PDF, PS and DjVu#Create a PDF from images]] uses {{ic|gm convert}}, not {{ic|convert}}. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 07:59, 3 April 2021 (UTC)<br />
<br />
::I put instructions for ImageMagick as well (note the command is {{ic|magick convert}}, just {{ic|convert}} is deprecated) [[User:Fhy|Fhy]] ([[User talk:Fhy|talk]]) 05:04, 16 September 2023 (UTC)<br />
<br />
<br />
The following is not related to the ImageMagick command discussed so far in this section, but is related to [[PDF,_PS_and_DjVu#Create a PDF from images]]:<br />
<br />
Quoting undoing revision [[Special:Diff/803987|803986]]: "this is not an image-to-pdf conversion". If you follow the process, you start with a file of an image (picture) and end with a pdf file that show the same image. Why this can not be thought of as a conversion process? I am also not sure the process can not be automated with the right LibreOffice related tools. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 00:50, 21 March 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=PDF,_PS_and_DjVu&diff=803986PDF, PS and DjVu2024-03-19T22:02:11Z<p>Regid: /* Create a PDF from images */ Another option to solve the task.</p>
<hr />
<div>[[Category:Applications]]<br />
[[Category:File formats]]<br />
[[Category:Lists of software]]<br />
[[Category:Software comparisons]]<br />
[[es:PDF, PS and DjVu]]<br />
This article covers software to view, edit and convert [[Wikipedia:PDF|PDF]], [[Wikipedia:PostScript|PostScript]] (PS), [[Wikipedia:DjVu|DjVu]] (''déjà vu'') and [[Wikipedia:Open XML Paper Specification|XPS]] files.<br />
<br />
== Engines ==<br />
<br />
* {{App|DjVuLibre|Suite to create, manipulate and view DjVu documents.|https://djvu.sourceforge.net/|{{Pkg|djvulibre}}}}<br />
* {{App|[[Wikipedia:Ghostscript|Ghostscript]]|Interpreter for PostScript and PDF. Provides the {{man|1|gs}} command-line interface, see also {{ic|/usr/share/doc/ghostscript/*/Use.htm}} ([https://ghostscript.readthedocs.io/en/latest/Use.html online]), along with many wrapper scripts like ''ps2pdf'' and ''pdf2ps''.|https://ghostscript.com/|{{Pkg|ghostscript}}}}<br />
* {{App|libgxps|GObject based library for handling and rendering XPS documents.|https://wiki.gnome.org/Projects/libgxps|{{Pkg|libgxps}}}}<br />
* {{App|libspectre|Small library for rendering Postscript documents.|https://www.freedesktop.org/wiki/Software/libspectre|{{Pkg|libspectre}}}}<br />
* {{App|[[Wikipedia:MuPDF|Mupdf]]| MuPDF is a lightweight PDF, XPS, and EPUB viewer, consisting of a software library, command line tools, and viewers.|https://mupdf.com/|{{Pkg|libmupdf}}}}<br />
* {{App|[[Wikipedia:Poppler (software)|Poppler]]|PDF rendering library based on Xpdf. For CJK (Chinese, Japanese, Korean) support with Poppler, [[install]] {{Pkg|poppler-data}}.|https://poppler.freedesktop.org/|{{Pkg|poppler}}}}<br />
<br />
== Viewers ==<br />
<br />
=== Framebuffer ===<br />
<br />
* {{App|fbgs|Poor man's PostScript/pdf viewer for the linux framebuffer console.|https://www.kraxel.org/blog/linux/fbida/|{{Pkg|fbida}}}}<br />
* {{App|fbpdf|Small framebuffer PDF and DjVu viewer based on MuPDF, with [[Vim]] keybindings and written in C|https://repo.or.cz/w/fbpdf.git|{{AUR|fbpdf-git}}}}<br />
* {{App|jfbview|Framebuffer PDF and image viewer. Features include Vim-like controls, zoom-to-fit, a TOC (outline) view and fast multi-threaded rendering.|https://github.com/jichu4n/jfbview|{{AUR|jfbview}}}}<br />
<br />
=== Graphical ===<br />
<br />
{{Note|Some [[web browser]]s can display PDF files, for example with [https://github.com/mozilla/pdf.js PDF.js].}}<br />
<br />
* {{App|apvlv|Lightweight document viewer with [[Vim]] keybindings using GTK libraries. Supports PDF, DjVu, EPUB, HTML and TXT.|https://naihe2010.github.io/apvlv/|{{AUR|apvlv}}}}<br />
* {{App|Atril|Simple multi-page document viewer for MATE. Supports DjVu, DVI, EPS, EPUB, PDF, PostScript, TIFF, XPS and Comicbook.|https://github.com/mate-desktop/atril|{{Pkg|atril}}}}<br />
* {{App|CorePDF|Simple lightweight PDF viewer based on Qt and poppler. Part of C-Suite.|https://cubocore.org/{{Dead link|2023|06|17|status=SSL error}}|{{AUR|corepdf}}}}<br />
* {{App|Deepin Document Viewer|A simple PDF and DjVu reader, supporting bookmarks, highlights and annotations.|https://github.com/linuxdeepin/deepin-reader|{{Pkg|deepin-reader}}}}<br />
* {{App|DjView|Viewer for DjVu documents.|https://djvu.sourceforge.net/djview4.html|{{Pkg|djview}}}}<br />
* {{App|ePDFView|Lightweight PDF document viewer using the Poppler and GTK libraries. Development stopped.|http://freecode.com/projects/epdfview|{{AUR|epdfview-git}}}}<br />
* {{App|[[Emacs]]|See also [https://github.com/vedang/pdf-tools pdf-tools] for improved pdf support ({{AUR|emacs-pdf-tools-git}}) and the [https://elpa.gnu.org/packages/djvu.html djvu package] for djvu support.|https://www.gnu.org/software/emacs/|{{Pkg|emacs}}}}<br />
* {{App|[[Evince]]|Document viewer for GNOME using GTK. Supports DjVu, DVI, EPS, PDF, PostScript, TIFF, XPS and Comicbook. Part of {{Grp|gnome}}.|https://wiki.gnome.org/Apps/Evince|{{Pkg|evince}}}}<br />
* {{App|[[Wikipedia:Foxit Reader|Foxit Reader]]|Small, fast (compared to Acrobat) proprietary PDF viewer. Releases (outside of security updates) are [https://forums.foxitsoftware.com/forum/portable-document-format-pdf-tools/foxit-reader/180532-linux-how-to-get-automatically-updates-for-foxit-reader-free-version?p&#61;180540#post180540 discontinued for Linux (November 2020)].|https://www.foxitsoftware.com/pdf-reader/|{{AUR|foxitreader}}}}<br />
* {{App|gv|Graphical user interface for the Ghostscript interpreter that allows to view and navigate through PostScript and PDF documents.|https://www.gnu.org/software/gv/|{{Pkg|gv}}}}<br />
* {{App|[[llpp]]|Very fast PDF reader based off of MuPDF, that supports continuous page scrolling, bookmarking, and text search through the whole document.|https://repo.or.cz/w/llpp.git|{{AUR|llpp}}}}<br />
* {{App|[[MuPDF]]|Very fast EPUB, FictionBook, PDF, XPS and Comicbook viewer written in portable C. Features CJK font support and vim-like bindings.|https://mupdf.com/|{{Pkg|mupdf}}}}<br />
* {{App|[[Wikipedia:Okular|Okular]]|Universal document viewer for KDE. Supports CHM, Comicbook, DjVu, DVI, EPUB, FictionBook, Mobipocket, ODT, PDF, Plucker, PostScript, TIFF and XPS.|https://okular.kde.org/|{{Pkg|okular}}}}<br />
* {{App|PDF4QT|Open source PDF editor.|https://jakubmelka.github.io/|{{AUR|pdf4qt-git}}}}<br />
* {{App|pdfpc|Presenter console with multi-monitor support for PDF files.|https://pdfpc.github.io/|{{Pkg|pdfpc}}}}<br />
* {{App|qpdfview|Tabbed document viewer. It uses Poppler for PDF support, libspectre for PS support, DjVuLibre for DjVu support, CUPS for printing support and the Qt toolkit for its interface.|https://launchpad.net/qpdfview|{{AUR|qpdfview}}}}<br />
* {{App|Sioyek|Lightweight PDF viewer based on MuPDF with features designed for viewing research papers and technical books, e.g., marking, bookmarking, highlighting, searchable command palette, jumping to references, and more.|https://sioyek.info/|{{AUR|sioyek}}}}<br />
* {{App|[[Wikipedia:Xpdf|Xpdf]]|Viewer that can decode LZW and read encrypted PDFs.|https://www.xpdfreader.com/|{{Pkg|xpdf}}}}<br />
* {{App|Xreader|Document viewer part of the X-Apps Project. Supports DjVu, DVI, EPUB, PDF, PostScript, TIFF, XPS, Comicbook.|https://github.com/linuxmint/xreader/|{{Pkg|xreader}}}}<br />
* {{App|[[Zathura]]|Highly customizable and functional document viewer (plugin based). Supports PDF, DjVu, PostScript and Comicbook.|https://pwmt.org/projects/zathura/|{{Pkg|zathura}}}}<br />
<br />
==== Comparison ====<br />
<br />
{{Accuracy|Filling out PDF forms seem to be broken in MuPDF and llpp.}}<br />
<br />
{| class="wikitable sortable" style="text-align:center;"<br />
! Name !! PDF !! PostScript !! DjVu !! XPS !! PDF forms !! PDF Annotation !! [https://git.pwmt.org/pwmt/zathura/-/issues/26 Non-rectangle selection] !! License<br />
|-<br />
! [[Wikipedia:Adobe Reader|Adobe Reader]]<br />
| Custom || {{-}} || {{-}} || {{-}} || {{Yes}} || {{-}} || {{Yes}} || {{V|proprietary}}<br />
|-<br />
! apvlv<br />
| Poppler || {{-}} || DjVuLibre || {{-}} || {{No}} || {{-}} || {{No}} (not by default, at least) || {{B|GPLv2}}<br />
|-<br />
! Atril<br />
| Poppler || libspectre || DjVuLibre || libgxps || {{Yes}} || {{-}} || {{-}} || {{B|GPLv2}}<br />
|-<br />
! DjView<br />
| {{-}} || {{-}} || DjVuLibre || {{-}} || {{-}} || {{-}} || {{-}} || {{B|GPLv2}}<br />
|-<br />
! [[Emacs]]<br />
| colspan=2 | Ghostscript<sup>1</sup> || DjVuLibre<sup>1</sup> || {{-}} || {{No}} || {{Yes}} || {{Yes}} || {{B|GPLv3}}<br />
|-<br />
! Emacs pdf-tools<br />
| Poppler || {{-}} || {{-}} || {{-}} || {{-}} || {{Yes}} || {{Yes}} || {{B|GPLv3}}<br />
|-<br />
! ePDFView<br />
| Poppler || {{-}} || {{-}} || {{-}} || {{No}} || {{-}} || {{-}} || {{B|GPLv2}}<br />
|-<br />
! [[Evince]]<br />
| Poppler || libspectre || DjVuLibre || libgxps || {{Yes}} || {{Yes}} || {{Yes}} || {{B|GPLv2}}<br />
|-<br />
! [[Wikipedia:Foxit Reader|Foxit Reader]]<br />
| Custom || {{-}} || {{-}} || {{-}} || {{Yes}} || {{Yes}} || {{Yes}} || {{V|proprietary}}<br />
|-<br />
! gv<br />
| colspan=2 | Ghostscript || {{-}} || {{-}} || {{No}} || {{-}} || {{-}} || {{B|GPLv3}}<br />
|-<br />
! [[llpp]]<br />
| libmupdf || {{-}} || {{-}} || libmupdf || {{Yes}} || {{-}} || {{-}} || {{B|GPLv3}}<br />
|-<br />
! [[MuPDF]]<br />
| Custom || {{-}} || {{-}} || Custom || {{Yes}} ({{pkg|mupdf-gl}}) || {{Yes}} ({{pkg|mupdf-gl}}) || {{Yes}} ({{pkg|mupdf-gl}}) || {{B|AGPLv3}}<br />
|-<br />
! [[Wikipedia:Okular|Okular]]<br />
| Poppler || libspectre || DjVuLibre || Custom || {{Yes}} || {{Yes}} || {{Yes}} || {{B|GPL, LGPL}}<br />
|-<br />
! PDF4QT<br />
| Custom || {{-}} || {{-}} || {{-}} || {{No}} || {{Yes}} || {{Yes}} || {{B|LGPLv3}}<br />
|-<br />
! pdfpc<br />
| Poppler || {{-}} || {{-}} || {{-}} || {{No}} || {{-}} || {{-}} || {{B|GPLv2}}<br />
|-<br />
! qpdfview<br />
| Poppler || libspectre<sup>1</sup> || DjVuLibre<sup>1</sup> || {{-}} || {{Yes}} || {{Yes}} || {{-}} || {{B|GPLv2}}<br />
|-<br />
! [[Wikipedia:Xpdf|Xpdf]]<br />
| Custom || {{-}} || {{-}} || {{-}} || {{No}} || {{-}} || {{-}} || {{B|GPLv3}}<br />
|-<br />
! Xreader<br />
| Poppler || libspectre<sup>1</sup> || DjVuLibre<sup>1</sup> || libgxps<sup>1</sup> || {{Yes}} || {{Yes}} || {{Yes}} || {{B|GPLv2}}<br />
|-<br />
! [[Zathura]]<br />
| libmupdf<sup>1</sup> / Poppler<sup>1</sup> || libspectre<sup>1</sup> || DjVuLibre<sup>1</sup> || libmupdf<sup>1</sup> || {{No|https://git.pwmt.org/pwmt/zathura/issues/101}} || {{No|https://git.pwmt.org/pwmt/zathura/-/issues/7}} || {{Yes|https://git.pwmt.org/pwmt/zathura/-/issues/26}} || {{B|zlib}}<br />
|}<br />
<br />
# Optional dependency needs to be installed<br />
<br />
==== PDF forms ====<br />
<br />
The ''PDF forms'' column in the above table refers to [[Wikipedia:PDF#Forms|AcroForms]] support. If you do not need your input to be directly extractable from the PDF, you can also use the applications in [[#Graphical PDF editing]] to put text on top of a PDF. PDF forms can be created with [[LibreOffice|LibreOffice Writer]] (''View > Toolbars > Form Controls'') and the [[#Advanced editors|advanced PDF editors]].<br />
<br />
The proprietary and deprecated [[Wikipedia:XFA|XFA]] format for forms is not fully supported by Poppler[https://gitlab.freedesktop.org/poppler/poppler/issues/199][https://gitlab.freedesktop.org/poppler/poppler/issues/530] and only supported by [[#Graphical|Adobe Reader]] and [[#Advanced editors|Master PDF Editor]].<br />
<br />
Alternatively, web browsers such as [[Firefox]] or [[Chromium]] feature a built-in PDF viewer capable of filling out forms.<br />
<br />
== Graphical PDF editing ==<br />
<br />
=== Editors that can import PDF files ===<br />
<br />
* [[Scribus]] can import and export PDF; text is imported as polygons.[https://wiki.scribus.net/canvas/Importing_PDF_files_as_Vector_Graphics]<br />
* [[LibreOffice|LibreOffice Draw]] can import and export PDF; text is imported as text; embedded fonts are substituted.[https://bugs.documentfoundation.org/show_bug.cgi?id=82163][https://ask.libreoffice.org/en/question/38991/garbled-text-when-opening-pdfs-in-draw/]<br />
* [[Inkscape]] can import a single page from a PDF and export to PDF; text is imported as cloned glyphs or text; with the latter embedded fonts are substituted.<br />
* Graphics editors like [[GIMP]] and {{Pkg|krita}} can also import and export PDFs at the cost of [[Wikipedia:Raster graphics|rasterization]].<br />
<br />
=== Basic editors ===<br />
<br />
* {{App|flpsed|A PostScript and PDF annotator, only supports text boxes.|https://flpsed.org/flpsed.html|{{AUR|flpsed}}}}<br />
* {{App|HandyOutliner for DjVu / PDF|Make easier and faster the process of creating bookmarks for DjVu and PDF documents.|https://handyoutlinerfo.sourceforge.net|{{AUR|handyoutliner-bin}}}}<br />
* {{App|jPDF Tweak|Java Swing application that can combine, split, rotate, reorder, watermark, encrypt, sign, and otherwise tweak PDF files.|https://jpdftweak.sourceforge.net/|{{AUR|jpdftweak}}}}<br />
* {{App|PDF Arranger|Helps merge or split pdf documents and rotate, crop and rearrange pages. It is a maintained fork of PDF-Shuffler.|https://github.com/jeromerobert/pdfarranger|{{Pkg|pdfarranger}}}}<br />
* {{App|PDF Chain|GTK front-end for [[#PDF tools|PDFtk]], written in C++, supporting concatenation, burst, watermarks, attaching files and more.|http://pdfchain.sourceforge.net/|{{AUR|pdfchain}}}}<br />
* {{App|PdfJumbler|Simple tool to rearrange, merge, delete and rotate pages in PDF files.|https://github.com/mgropp/pdfjumbler|{{AUR|pdfjumbler}}}}<br />
* {{App|PDF Mix Tool|Qt front-end for [[#Libraries|PoDoFo]], written in C++, supports splitting, merging, rotating and mixing PDF files.|https://scarpetta.eu/pdfmixtool/|{{Pkg|pdfmixtool}}}}<br />
* {{App|PDFsam|Open source application, written in Java, supports merging, splitting and rotating.|https://pdfsam.org/|{{AUR|pdfsam}}}}<br />
* {{App|PDF Slicer|Simple application to extract, merge, rotate and reorder pages of PDF documents.|https://junrrein.github.io/pdfslicer/|{{Pkg|pdfslicer}}}}<br />
* {{App|PDF Tricks|Simple, efficient application for small manipulations in PDF files using Ghostscript.|https://github.com/muriloventuroso/pdftricks|{{Pkg|pdftricks}}}}<br />
<br />
=== Cropping tools ===<br />
<br />
* {{App|briss|Java GUI to crop pages of PDF documents to one or more regions selected.|https://sourceforge.net/projects/briss/|{{AUR|briss}}}}<br />
* {{App|krop|Simple graphical tool to crop the pages of PDF files.|https://arminstraub.com/software/krop|{{AUR|krop}}}}<br />
* {{App|pdfCropMargins|Automatically crops the margins of PDF files.|https://github.com/abarker/pdfCropMargins|{{AUR|pdfcropmargins}}}}<br />
* {{App|PdfHandoutCrop|Tool to crop pdf handout with multiple pages per sheet.|https://cges30901.github.io/pdfhandoutcrop/|{{AUR|pdfhandoutcrop}}}}<br />
<br />
=== Advanced editors ===<br />
<br />
* {{App|Master PDF Editor|Functional proprietary PDF editor. Latest version free for non-commercial use. The ''-free'' package is outdated but lacks a watermark.|https://code-industry.net/free-pdf-editor/|{{AUR|masterpdfeditor}}, {{AUR|masterpdfeditor-free}}}}<br />
* {{App|PDF Studio|All-in-one proprietary PDF editor similar to Adobe Acrobat.|https://www.qoppa.com/pdfstudio/|{{AUR|pdfstudio-bin}}}}<br />
<br />
==== Comparison of advanced editors ====<br />
<br />
{| class="wikitable sortable" style="text-align:center;"<br />
! Name !! Cost (USD, lifetime) !! Page Labels !! Form Designer !! Content Editing (Text and Images) !! Optimize PDFs !! Digitally Sign PDFs !! License<br />
|-<br />
! Master PDF Editor<br />
| 85.34 || {{No}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{V|proprietary}}<br />
|- <br />
! Qoppa PDF Studio Standard<br />
| 99 || {{Yes}} || {{No}} || {{No}} || {{No}} || {{No}} || {{V|proprietary}}<br />
|-<br />
! Qoppa PDF Studio Pro<br />
| 139 || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}} || {{V|proprietary}}<br />
|}<br />
<br />
== PDF tools ==<br />
<br />
See also [[#Engines|Ghostscript]].<br />
<br />
* {{App|Camelot|Camelot: PDF Table Extraction for Humans.|https://github.com/atlanhq/camelot|{{AUR|python-camelot}}, {{AUR|python-camelot-git}}}}<br />
* {{App|Coherent PDF|Proprietary non-free command line tools to manipulate PDF files including merge, encrypt, decrypt, scale, crop, rotate, bookmarks, stamp, logos, page numbers.|https://community.coherentpdf.com/|{{AUR|cpdf}}}}<br />
* {{App|DiffPDF|Compare the text or the visual appearance of each page in two PDF files.|https://gitlab.com/eang/diffpdf|{{Pkg|diffpdf}}}}<br />
* {{App|mupdf-tools|Tools developed as part of MuPDF, contains {{man|1|mutool}} and ''muraster''.|https://mupdf.com|{{Pkg|mupdf-tools}}}}<br />
* {{App|pdfcpu|Command-line tool to create and modify PDFs.|https://github.com/pdfcpu/pdfcpu|{{AUR|pdfcpu-bin}}}}<br />
* {{App|pdfgrep|Commandline utility to search text in PDF files.|https://pdfgrep.org/|{{Pkg|pdfgrep}}}}<br />
* {{App|pdfjam|Can be used to n-up, join, rotate and flip PDFs and arrange them into a format suitable for book binding.|https://github.com/DavidFirth/pdfjam|{{Pkg|texlive-binextra}}}}<br />
* {{App|PDFMiner|PDFMiner is a text extraction tool for PDF documents. Not actively maintained as of 2020.|https://github.com/euske/pdfminer|{{AUR|pdfminer}}}}<br />
* {{App|pdfminer.six|Community maintained fork of pdfminer.|https://github.com/pdfminer/pdfminer.six|{{Pkg|python-pdfminer}}}}<br />
* {{App|pdf2svg|Convert PDF files to SVG files.|http://www.cityinthesky.co.uk/opensource/pdf2svg/|{{Pkg|pdf2svg}}}}<br />
* {{App|[[Wikipedia:PDFtk|PDFtk]]|Simple tool for doing everyday things with PDF documents.|https://gitlab.com/pdftk-java/pdftk|{{pkg|pdftk}}}}<br />
* {{App|[[Wikipedia:QPDF|QPDF]]|Content-preserving PDF transformation system.|https://github.com/qpdf/qpdf|{{Pkg|qpdf}}}}<br />
* {{App|Stapler|Light alternative to PDFtk using the [[#Python|PyPDF2]] library.|https://github.com/hellerbarde/stapler|{{AUR|stapler}}, {{AUR|stapler-git}}}}<br />
* {{App|Tabula|Tabula is a tool for liberating data tables trapped inside PDF files.|https://tabula.technology|{{AUR|tabula}}, {{AUR|tabula-java}}}}<br />
* {{App|verapdf|A purpose-built, open source, file-format validator covering all PDF/A and PDF/UA parts and conformance levels.|https://verapdf.org|{{AUR|verapdf}}}}<br />
<br />
== Command snippets ==<br />
<br />
=== Create a PDF from images ===<br />
<br />
With [[GraphicsMagick]]:<br />
<br />
$ gm convert 1.jpg 2.jpg 3.jpg out.pdf<br />
<br />
With [[ImageMagick]]:<br />
<br />
$ magick convert 1.jpg 2.jpg 3.jpg out.pdf<br />
<br />
Note that ImageMagick's output is lossy. For lossless PDF creation from jpeg, use {{pkg|img2pdf}}.<br />
<br />
One can also insert the images into a [[libreoffice]] document, and use [[libreoffice]] facility to export a document into pdf.<br />
<br />
=== Concatenate PDFs ===<br />
<br />
With Ghostscript:<br />
<br />
$ gs -dNOPAUSE -sDEVICE=pdfwrite -sOUTPUTFILE=out.pdf -dBATCH 1.pdf 2.pdf 3.pdf<br />
<br />
With PDFtk:<br />
<br />
$ pdftk 1.pdf 2.pdf 3.pdf cat output out.pdf<br />
<br />
With Poppler:<br />
<br />
$ pdfunite 1.pdf 2.pdf 3.pdf out.pdf<br />
<br />
With QPDF:<br />
<br />
$ qpdf --empty --pages 1.pdf 2.pdf 3.pdf -- out.pdf<br />
<br />
=== Extract text from PDF ===<br />
<br />
With Poppler and maintaining the layout:<br />
<br />
$ pdftotext -layout in.pdf out.txt<br />
<br />
See also {{man|1|pdftotext}}.<br />
<br />
=== Decrypt a PDF ===<br />
<br />
This section lists commands to decrypt a PDF to an unencrypted file. Note that most [[#Viewers|PDF viewers]] also support encrypted PDFs.<br />
<br />
With PDFtk:<br />
<br />
$ pdftk in.pdf input_pw ''password'' output out.pdf<br />
<br />
With Poppler to PostScript:<br />
<br />
$ pdftops -upw ''password'' in.pdf out.ps<br />
<br />
With QPDF:<br />
<br />
$ qpdf --decrypt --password=''password'' in.pdf out.pdf<br />
<br />
{{Tip|Forgotten passwords might be recovered with {{Pkg|pdfcrack}}, see {{man|1|pdfcrack}}.}}<br />
<br />
=== Encrypt a PDF ===<br />
<br />
The ''user password'' is used for encryption, the ''owner password'' to restrict operations once the document is decrypted, for more information, see [[Wikipedia:PDF#Encryption and signatures]].<br />
<br />
With PDFtk:<br />
<br />
$ pdftk in.pdf output out.pdf user_pw ''password''<br />
<br />
With [[#Libraries|PoDoFo]]:<br />
<br />
$ podofoencrypt -u ''user_password'' -o ''owner_password'' in.pdf out.pdf<br />
<br />
With QPDF:<br />
<br />
$ qpdf --encrypt ''user_password'' ''owner_password'' ''key_length'' -- in.pdf out.pdf<br />
<br />
where {{ic|''key_length''}} can be 40, 128 or 256.<br />
<br />
=== Extract images from a PDF ===<br />
<br />
With {{Pkg|poppler}}, saving images as JPEG:<br />
<br />
$ pdfimages ''infile''.pdf -j ''outfileroot''<br />
<br />
=== Extract page range from PDF, split multipage PDF document ===<br />
<br />
With Ghostscript as a single file[https://forums.freebsd.org/threads/split-pdf-file.58902/#post-336971]<br />
<br />
$ gs -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -dSAFER -dFirstPage=''first'' -dLastPage=''last'' -sOutputFile=''outfile''.pdf ''infile''.pdf<br />
<br />
With PDFtk as a single file:<br />
<br />
$ pdftk ''infile''.pdf cat ''first''-''last'' output ''outfile''.pdf<br />
<br />
With Poppler as separate files:<br />
<br />
$ pdfseparate -f ''first'' -l ''last'' ''infile''.pdf ''outfileroot''-%d.pdf<br />
<br />
With QPDF as a single file:<br />
<br />
$ qpdf --empty --pages ''infile''.pdf ''first''-''last'' -- ''outfile''.pdf<br />
<br />
With mutool as a single file:<br />
<br />
$ mutool clean -g ''infile''.pdf ''outfile''.pdf ''first''-''last''<br />
<br />
=== Impose a PDF (nup) ===<br />
<br />
PDF [[Wikipedia:Imposition|Imposition]] is the process by which multiple input pages are combined into one output page, layed out into a ''rows''x''columns'' grid.<br />
<br />
It can be done with [[#PDF tools|pdfjam]] (notice that wrapper scripts such as ''pdfnup'' and ''pdfbook'' are deprecated): <br />
<br />
$ pdfjam --nup ''rows''x''columns'' ''input.pdf'' --outfile ''output.pdf''<br />
<br />
or with [https://github.com/raffaem/pdfsak pdfsak]:<br />
<br />
$ pdfsak --input-file ''input.pdf'' --output ''output.pdf'' --nup ''rows'' ''columns''<br />
<br />
=== Inspect metadata ===<br />
<br />
With [[ExifTool]]:<br />
<br />
$ exiftool -All file.pdf<br />
<br />
With Poppler:<br />
<br />
$ pdfinfo file.pdf<br />
<br />
=== Remove metadata ===<br />
<br />
==== Using ExifTool ====<br />
<br />
With [[ExifTool]]:<br />
<br />
$ exiftool -All= -overwrite_original input.pdf<br />
$ mv input.pdf /tmp/temp.pdf<br />
$ qpdf --linearize /tmp/temp.pdf input.pdf<br />
<br />
The linearize step is needed to prevent recovery of deleted metadata. See [https://superuser.com/q/1482619/400542 this SuperUser question] and the related [https://exiftool.org/forum/index.php/topic,3943.msg54610.html#msg54610 ExifTool forum thread].<br />
<br />
==== Using pdftk ====<br />
<br />
Many PDFs store document metadata using both an Info dictionary (old school) and an XMP stream (new school). This pdftk command remove the XMP stream from the PDF altogether. It does not remove the Info dictionary.<br />
<br />
Note that objects inside the PDF might have their own, separate XMP metadata streams, and that this command does not remove those. It only removes the PDF’s document‐level XMP stream.<br />
<br />
$ pdftk ''input.pdf'' drop_xmp output ''output.pdf''<br />
<br />
=== Reduce size of a PDF ===<br />
<br />
PDF size can be reduced by setting an appropriate optimization or compression level.<br />
<br />
With Ghostscript one of:<br />
<br />
$ ps2pdf -dPDFSETTINGS=/screen in.pdf out.pdf<br />
<br />
or<br />
<br />
$ gs -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/printer -sOutputFile=out.pdf in.pdf<br />
<br />
For different settings see the [https://ghostscript.readthedocs.io/en/latest/VectorDevices.html#controls-and-features-specific-to-postscript-and-pdf-input documentation].<br />
<br />
There is also {{AUR|shrinkpdf}}, a script wrapping gs.<br />
<br />
=== Rasterize a PDF ===<br />
<br />
These commands will convert your PDF into images.<br />
<br />
With [[GraphicsMagick]] to convert a specific page into an image file:<br />
<br />
$ gm convert -density ''dpi'' ''infile''.pdf[''page''] ''outfile''.jpg<br />
<br />
With [[ImageMagick]] to convert a specific page into an image file:<br />
<br />
$ magick convert -density ''dpi'' ''infile''.pdf[''page''] ''outfile''.jpg<br />
<br />
With [[ImageMagick]] to convert all pages into another PDF file composed by an image file per page:<br />
<br />
$ magick convert -density ''dpi'' ''infile''.pdf ''outfile''.pdf<br />
<br />
{{Warning|This will increase the file size of your PDF substantially. Use it for example if your printer is not able to print your PDF correctly.}}<br />
<br />
With Poppler to convert all pages into one image file per page:<br />
<br />
$ pdftoppm -jpeg -r ''dpi'' ''infile''.pdf ''outfileroot''<br />
<br />
With Poppler to convert a specific page into an image file:<br />
<br />
$ pdftoppm -jpeg -r ''dpi'' -f ''page'' -singlefile ''infile''.pdf ''outfileroot''<br />
<br />
=== Split PDF pages ===<br />
<br />
With mupdf-tools to split every page vertically into two pages:<br />
<br />
$ mutool poster -y 2 in.pdf out.pdf<br />
<br />
Can be used to undo simple [[#Impose a PDF (nup)|imposition]].<br />
<br />
=== Add an image ===<br />
<br />
Adding an image to any location in a PDF can be done<br />
<br />
* with [[ImageMagick]] (convert), {{Aur|xv}} and {{pkg|pdftk}}. ([http://emmanuel.branlard.free.fr/work/linux/dev/SignPDF/SignPDF Wrapper script])<br />
* with {{Aur|xournal}}<br />
* with [[LibreOffice]]<br />
<br />
Details on these and other solutions can be found [https://unix.stackexchange.com/questions/85873/how-can-i-add-a-signature-png-to-a-pdf-in-linux on StackExchange].<br />
<br />
=== Add digital signature to PDF ===<br />
<br />
{{Aur|jsignpdf}} can digitally sign PDF files with X.509 certificates in GUI and CLI.<br />
<br />
Readers such as Okular and MuPDF can sign PDFs with digital signatures. This requires a PFX certificate, which can be created with an [[OpenSSL#Generate a self-signed certificate with private key in a single command|OpenSSL command]]:<br />
<br />
$ openssl req -x509 -days 365 -newkey rsa:2048 -keyout ''cert.pem'' -out ''cert.pem''<br />
$ openssl pkcs12 -export -in ''cert.pem'' -out ''cert.pfx''<br />
<br />
MuPDF users can then sign PDFs with the {{ic|''cert.pfx''}} using the graphical interface, or its [https://mupdf.readthedocs.io/en/latest/mutool-sign.html mutool-sign] tool.<br />
<br />
Okular users must import {{ic|''cert.pfx''}} into a certificate store such as the one in the default Firefox profile.[https://docs.kde.org/trunk5/en/okular/okular/signatures.html]{{Dead link|2024|01|13|status=404}} With Firefox this is done through ''Settings > Privacy & Security > View Certificates > Your Certificates > Import'' and selecting ''cert.pfx''. Afterwards Okular will offer this certificate to be used when signing PDFs.<br />
<br />
Libreoffice can also sign PDFs.[https://help.libreoffice.org/6.3/en-US/text/shared/guide/digital_signatures.html]<br />
<br />
=== Removing annotations from a PDF ===<br />
<br />
With {{Pkg|pdftk}} [https://stackoverflow.com/questions/49598797/remove-pdf-annotations-via-command-line/49614525#49614525]:<br />
<br />
$ pdftk in.pdf output - uncompress | sed '/^\/Annots/d' | pdftk - output out.pdf compress<br />
<br />
With {{AUR|perl-cam-pdf}}:<br />
<br />
$ rewritepdf.pl -C in.pdf out.pdf<br />
<br />
See https://superuser.com/a/1051543 for more information.<br />
<br />
=== Add page numbers ===<br />
<br />
With [https://github.com/raffaem/pdfsak pdfsak]:<br />
<br />
$ pdfsak --input-file input.pdf --output output.pdf --text "\large \$page/\$pages" br 0.99 0.99 --latex-engine xelatex --font "Noto Regular"<br />
<br />
=== Add page labels ===<br />
<br />
Page labels are logical page numbers shown in the navigation bar of your PDF reader. They are useful for example if the first pages of the PDF are indices numbered with roman numbers (I, II, etc.), while the page numbered "1" corresponds to a PDF page greater than 1, and you want the page number shown in the navigation bar to corresponds to the page number shown in the physical page. <br />
<br />
This should not be confused with adding page numbers into a physical page. See [https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf#page=382 section 12.4.2 of PDF reference] to better understand page labels.<br />
<br />
# Using [https://github.com/lovasoa/pagelabels-py pagelabels-py], let's say we have a PDF named {{ic|my_document.pdf}}, that has 12 pages.<br />
#* Pages 1 to 4 should be labelled {{ic|Intro I}} to {{ic|Intro IV}}.<br />
#* Pages 5 to 9 should be labelled {{ic|2}} to {{ic|6}}.<br />
#* Pages 10 to 12 should be labelled {{ic|Appendix A}} to {{ic|Appendix C}}<br />
#* We can issue the following list of commands: {{bc|<nowiki>$ python3 -m pagelabels --delete "my_document.pdf"<br />
$ python3 -m pagelabels --startpage 1 --prefix "Intro " --type "roman uppercase" "my_document.pdf"<br />
$ python3 -m pagelabels --startpage 5 --firstpagenum 2 "my_document.pdf"<br />
$ python3 -m pagelabels --startpage 10 --prefix "Appendix " --type "letters uppercase" "my_document.pdf" </nowiki>}}<br />
#* {{Note|pagelabels-py will convert your file to PDF 1.3 specification}}<br />
# Using {{Pkg|pdftk}}, create a {{ic|metadata.txt}} file with labels: {{bc|<nowiki>PageLabelBegin<br />
PageLabelNewIndex: 1<br />
PageLabelStart: 1<br />
PageLabelPrefix: Cover<br />
PageLabelNumStyle: NoNumber<br />
PageLabelBegin<br />
PageLabelNewIndex: 2<br />
PageLabelStart: 1<br />
PageLabelPrefix: Back Cover<br />
PageLabelNumStyle: NoNumber<br />
PageLabelBegin<br />
PageLabelNewIndex: 3<br />
PageLabelStart: 1<br />
PageLabelNumStyle: LowercaseRomanNumerals<br />
PageLabelBegin<br />
PageLabelNewIndex: 27<br />
PageLabelStart: 1<br />
PageLabelNumStyle: DecimalArabicNumerals </nowiki>}}<br />
#* Where:<br />
#*;PageLabelBegin: signal a new page label definition will follow<br />
#*;PageLabelNewIndex: is the PDF page index from which the numbering style applies, counting from one. The numbering style will continue until the next page label or, if there are no more page labels, until the end of the document.<br />
#*;PageLabelStart: is the starting number. For example, if you specify 5 here, the pages will be numbered 5, 6, 7, ...<br />
#*;PageLabelPrefix: a text to put before the number in page labels.<br />
#*;PageLabelNumStyle: can be {{ic|DecimalArabicNumerals}}, {{ic|UppercaseRomanNumerals}}, {{ic|LowercaseRomanNumerals}}, {{ic|UppercaseLetters}}, {{ic|LowercaseLetters}} or {{ic|NoNumber}}.<br />
#* Then use: {{bc|<nowiki>pdftk book.pdf update_info_utf8 metadata.txt output book-with-metadata.pdf</nowiki>}}<br />
<br />
See [https://superuser.com/questions/232553/how-to-change-internal-page-numbers-in-the-meta-data-of-a-pdf this SuperUser question] for more details.<br />
<br />
=== Extract bookmarks ===<br />
<br />
With pdftk:<br />
<br />
$ pdftk file.pdf dump_data_utf8 | grep '^Bookmark'<br />
<br />
With qpdf:<br />
<br />
$ qpdf --json --json-key=outlines file.pdf<br />
<br />
See https://unix.stackexchange.com/questions/143886/how-to-extract-bookmarks-from-a-pdf-file for more information.<br />
<br />
=== Add bookmarks ===<br />
<br />
==== With pdftk ====<br />
<br />
Create a text file {{ic|bookmark_definitions.txt}} with bookmark definitions in the following format:<br />
<br />
{{bc|<nowiki><br />
BookmarkBegin<br />
BookmarkTitle: Chapter 1<br />
BookmarkLevel: 1<br />
BookmarkPageNumber: 1<br />
BookmarkBegin<br />
BookmarkTitle: Chapter 1.1<br />
BookmarkLevel: 2<br />
BookmarkPageNumber: 2<br />
BookmarkBegin<br />
BookmarkTitle: Chapter 1.2<br />
BookmarkLevel: 2<br />
BookmarkPageNumber: 3<br />
BookmarkBegin<br />
BookmarkTitle: Chapter 1.3<br />
BookmarkLevel: 2<br />
BookmarkPageNumber: 4<br />
BookmarkBegin<br />
BookmarkTitle: Chapter 1.3.1<br />
BookmarkLevel: 3<br />
BookmarkPageNumber: 5<br />
BookmarkBegin<br />
BookmarkTitle: Chapter 2<br />
BookmarkLevel: 1<br />
BookmarkPageNumber: 6<br />
</nowiki>}}<br />
<br />
Where<br />
;BookmarkBegin: signal a new bookmark definition<br />
;BookmarkTitle: the title of the bookmark<br />
;BookmarkLevel: the level of the bookmark in the hierarchy<br />
;BookmarkPageNumber: the page number the bookmark redirects to<br />
<br />
In this example, the above file will create the following bookmark structure:<br />
<br />
*Chapter 1<br />
**Chapter 1.1<br />
**Chapter 1.2<br />
**Chapter 1.3<br />
***Chapter 1.3.1<br />
*Chapter 2<br />
<br />
Apply the bookmarks with the following command:<br />
<br />
$ pdftk ''input.pdf'' update_info_utf8 ''bookmark_definitions.txt'' output ''output.pdf''<br />
<br />
=== Extract pages contained within a bookmark ===<br />
<br />
To extract the pages contained within a bookmark, use the following script:<br />
{{bc|<nowiki><br />
#!/usr/bin/env python3<br />
<br />
import subprocess<br />
import sys<br />
import tempfile<br />
import os<br />
<br />
cmd = ["pdftk", sys.argv[1], "dump_data_utf8"]<br />
bl = subprocess.run(cmd, text=True, capture_output=True).stdout.splitlines()<br />
bl = [x for x in bl if x.startswith("Bookmark")]<br />
<br />
tag_title = "BookmarkTitle: "<br />
tag_level = "BookmarkLevel: "<br />
tag_page = "BookmarkPageNumber: "<br />
<br />
titles = [x[len(tag_title):] for x in bl if x.startswith(tag_title)]<br />
with tempfile.NamedTemporaryFile("w") as input_file:<br />
with tempfile.NamedTemporaryFile("r") as output_file:<br />
input_file.write("\n".join(titles))<br />
input_file.flush()<br />
os.system(<br />
"fzf --reverse "<br />
f"< \"{input_file.name}\" "<br />
f"> \"{output_file.name}\"")<br />
choice = output_file.read().strip()<br />
<br />
pos = bl.index(f"{tag_title}{choice}")<br />
level = int(bl[pos+1].replace(tag_level, ""))<br />
start_page = int(bl[pos+2].replace(tag_page, ""))<br />
<br />
try:<br />
next_level = bl.index(f"{tag_level}{level}", pos+2)<br />
end_page = int(bl[next_level+1].replace(tag_page, ""))-1<br />
except ValueError:<br />
# we are extracting the last bookmark<br />
# The letter z represents the last page and is the same as r1.<br />
end_page = "z"<br />
<br />
outfp = input("Output file: ")<br />
cmd = [<br />
"qpdf",<br />
"--empty",<br />
"--pages",<br />
sys.argv[1],<br />
str(start_page)+"-"+str(end_page),<br />
"--",<br />
outfp,<br />
]<br />
subprocess.run(cmd)<br />
</nowiki>}}<br />
<br />
=== Remove blank pages ===<br />
<br />
One can use the following script to remove blank pages form a PDF file (credit: [https://superuser.com/a/1307895 SuperUser post]):<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
<br />
IN="$1"<br />
filename=$(basename "${IN}")<br />
filename="${filename%.*}"<br />
PAGES=$(pdfinfo "$IN" | grep ^Pages: | tr -dc '0-9')<br />
<br />
non_blank() {<br />
for i in $(seq 1 $PAGES); do<br />
PERCENT=$(gs -o - -dFirstPage=${i} -dLastPage=${i} -sDEVICE=ink_cov "$IN" | grep CMYK | nawk 'BEGIN { sum=0; } {sum += $1 + $2 + $3 + $4;} END { printf "%.5f\n", sum } ')<br />
if [ $(echo "$PERCENT > 0.001" | bc) -eq 1 ]; then<br />
echo $i<br />
#echo $i 1>&2<br />
fi<br />
echo -n . 1>&2<br />
done | tee "$filename.tmp"<br />
echo 1>&2<br />
}<br />
<br />
set +x<br />
pdftk "${IN}" cat $(non_blank) output "${filename}_noblanks.pdf"<br />
</nowiki>}}<br />
<br />
Use it like {{ic|pdf_remove_blank_pages input.pdf}}.<br />
<br />
The script needs {{Pkg|pdftk}}, {{Pkg|nawk}} and {{Pkg|ghostscript}}.<br />
<br />
=== Find fonts used in a PDF ===<br />
<br />
The {{man|1|pdffonts}} command (from {{Pkg|poppler}}), can be used to find which fonts a PDF uses and if they have been embedded in it or not: <br />
<br />
{{hc|$ pdffonts ''file''.pdf|<nowiki><br />
name type encoding emb sub uni object ID<br />
------------------------------------ ----------------- ---------------- --- --- --- ---------<br />
Times-Roman Type 1 Custom no no no 8 0<br />
Times-Italic Type 1 Standard no no no 9 0<br />
Times-Bold Type 1 Standard no no no 7 0<br />
Helvetica Type 1 Standard no no no 34 0<br />
Helvetica-Bold Type 1 Standard no no no 35 0<br />
</nowiki>}}<br />
<br />
This can be used when having issues displaying properly the text in a PDF, to determine if missing [[fonts]] or their [[Metric-compatible fonts|metric-compatible equivalent]] need to be installed.<br />
<br />
=== Repair broken PDF file ===<br />
<br />
With {{Pkg|ghostscript}}:<br />
<br />
$ gs -o ''repaired.pdf'' -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress ''corrupted.pdf''<br />
<br />
With {{Pkg|poppler}}:<br />
<br />
$ pdftocairo -pdf ''corrupted.pdf'' ''repaired.pdf''<br />
<br />
With {{Pkg|mupdf-tools}}:<br />
<br />
$ mutool clean ''corrupted.pdf'' ''repaired.pdf''<br />
<br />
Reference: https://superuser.com/q/278562<br />
<br />
=== Convert PDF to PDF/A standard ===<br />
<br />
With {{Pkg|ghostscript}}:<br />
<br />
$ gs -dPDFA -dBATCH -dNOPAUSE -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -dPDFACompatibilityPolicy=2 -sOutputFile=''document_pdfa.pdf'' ''document.pdf''<br />
<br />
Reference: https://stackoverflow.com/a/56459053<br />
<br />
=== Validate PDF/A compliance ===<br />
<br />
Using {{AUR|verapdf}} you can validate the compliance of your PDF to different flavours of the PDF/A standard:<br />
<br />
$ verapdf --flavour 1a --format text ''document.pdf''<br />
<br />
== DjVu tools ==<br />
<br />
* [[#Engines|DjVuLibre]] provides many command-line tools, like {{man|1|ddjvu}} for example.<br />
* {{App|img2djvu|Single-pass DjVu encoder based on DjVu Libre and ImageMagick.|https://github.com/ashipunov/img2djvu|{{AUR|img2djvu-git}}}}<br />
* {{App|pdf2djvu|Creates DjVu files from PDF files.|https://jwilk.net/software/pdf2djvu|{{AUR|pdf2djvu}}}}<br />
<br />
=== Convert DjVu to images ===<br />
<br />
Break Djvu into separate pages:<br />
<br />
$ djvmcvt -i input.djvu /path/to/out/dir output-index.djvu<br />
<br />
Convert Djvu pages into images:<br />
<br />
$ ddjvu --format=tiff page.djvu page.tiff<br />
<br />
Convert Djvu pages into PDF:<br />
<br />
$ ddjvu --format=pdf inputfile.djvu ouputfile.pdf<br />
<br />
You can also use ''--page'' to export specific pages:<br />
<br />
$ ddjvu --format=tiff --page=1-10 input.djvu output.tiff<br />
<br />
this will convert pages from 1 to 10 into one tiff file.<br />
<br />
=== Processing images ===<br />
<br />
You can use {{Pkg|scantailor-advanced}} to:<br />
<br />
* fix orientation<br />
* split pages<br />
* deskew<br />
* crop<br />
* adjust margins<br />
<br />
=== Make DjVu from images ===<br />
<br />
There is a useful script {{AUR|img2djvu-git}}.<br />
<br />
$ img2djvu -c1 -d600 -v1 ./out<br />
<br />
it will create 600 DPI {{ic|out.djvu}} from all files in {{ic|./out}} directory.<br />
<br />
Alternatively, you can try {{AUR|didjvu}}, which seems to create smaller files especially on images with well defined background.<br />
<br />
== PostScript tools ==<br />
<br />
* {{App|pstotext|Converts PostScript files to text.|https://www.cs.wisc.edu/~ghost/doc/pstotext.htm|{{AUR|pstotext}}}}<br />
* [[#Engines|Ghostscript]]<br />
<br />
=== ps2pdf ===<br />
<br />
''ps2pdf'' is a wrapper around ghostscript to convert PostScript to PDF:<br />
<br />
$ ps2pdf -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true YourPSFile.ps<br />
<br />
Explanation:<br />
<br />
* with {{ic|1=-sPAPERSIZE=something}} you define the paper size. For valid PAPERSIZE values, see [https://ghostscript.com/doc/current/Use.htm#Known_paper_sizes]{{Dead link|2022|09|22|status=404}}.<br />
* {{ic|1=-dOptimize=true}} lets the created PDF be optimised for loading.<br />
* {{ic|1=-dEmbedAllFonts=true}} makes the fonts look always nice.<br />
<br />
{{Note|You cannot choose the paper orientation in ps2pdf. If your input PS file is healthy, it already contains the orientation information. If you are trying to use an Encapsulated PS file, you will have problems, if it does not fit in the {{ic|1=-sPAPERSIZE}} you specified, because EPS files usually do not contain paper orientation information. A workaround is creating a new paper in ghostscript settings (call it e.g. "slide") and use it as {{ic|1=-sPAPERSIZE=slide}}.}}<br />
<br />
== Libraries ==<br />
<br />
=== C/C++ ===<br />
<br />
* {{App|libharu|C library for generating PDF documents.|https://github.com/libharu/libharu|{{Pkg|libharu}}, Lua binding: {{AUR|lua-hpdf}}}}<br />
* {{App|PoDoFo|A C++ library to work with the PDF file format.|https://podofo.sourceforge.net|{{Pkg|podofo}}}}<br />
<br />
=== Python ===<br />
<br />
* {{App|borb|borb is a library for reading, creating and manipulating PDF files in python.|https://borbpdf.com/, https://github.com/jorisschellekens/borb}}<br />
* {{App|pdfrw|A pure Python library that reads and writes PDFs.|https://github.com/pmaupin/pdfrw|{{Pkg|python-pdfrw}}}}<br />
* {{App|PyPDF|A pure-Python library built as a PDF toolkit.|https://github.com/py-pdf/pypdf|{{Pkg|python-pypdf}}}}<br />
* {{App|PyX|Python library for the creation of PostScript and PDF files.|http://pyx.sourceforge.net|{{Pkg|python-pyx}}}}<br />
* {{App|ReportLab|A proven industry-strength PDF generating solution|https://www.reportlab.com/|{{Pkg|python-reportlab}}}}<br />
<br />
=== Java ===<br />
<br />
* {{App|iText Core|iText is a more versatile, programmable and enterprise-grade PDF solution that allows you to embed its functionalities within your own software for digital transformation.|https://itextpdf.com/products/itext-core|{{AUR|itext-rups-bin}}}}<br />
* {{App|OpenPDF|OpenPDF is a free Java library for creating and editing PDF files with a LGPL and MPL open source license. OpenPDF is based on a fork of iText.|https://github.com/LibrePDF/OpenPDF}}<br />
<br />
== See also ==<br />
<br />
* [[List of applications/Documents#OCR software]]<br />
* [[List of applications/Documents#Readers and viewers]]<br />
* [[List of applications/Documents#Stylus note-taking]]<br />
* [[Wikipedia:List of PDF software]]<br />
* PDF References<br />
** [https://opensource.adobe.com/dc-acrobat-sdk-docs/pdfstandards/PDF32000_2008.pdf PDF Reference and Adobe Extensions to the PDF Specification]<br />
** [[Wikipedia:PDF#Further reading]]</div>Regidhttps://wiki.archlinux.org/index.php?title=ImageMagick&diff=803972ImageMagick2024-03-19T18:43:01Z<p>Regid: Rather common operation, or so I think. Not sure if it should, or shouldn't, be added to the common operations section. It looks like imagemagick can do that, but is not the better tool for the job. In any case, duplicating an existing wiki thread looks to me wrong. Still, a reference is in place.</p>
<hr />
<div>[[Category:Multimedia]]<br />
[[de:ImageMagick]]<br />
[[es:ImageMagick]]<br />
[[ja:ImageMagick]]<br />
According to [[Wikipedia:ImageMagick|Wikipedia]]:<br />
<br />
:ImageMagick is a free and open-source software suite for displaying, converting, and editing raster image and vector image files. It can read and write over 200 image file formats.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|imagemagick}} package. Alternatively install {{Pkg|graphicsmagick}} for [[Wikipedia:GraphicsMagick|GraphicsMagick]], a fork of ImageMagick, emphasizing stability of the API and command-line interface.<br />
<br />
== Usage ==<br />
<br />
See {{man|1|ImageMagick}}, or {{man|1|gm}} for GraphicsMagick.<br />
<br />
{{Tip|The official HTML documentation is available locally when the packages are installed:<br />
* ImageMagick at {{ic|/usr/share/doc/ImageMagick-7/www/index.html}}<br />
* GraphicsMagick at {{ic|/usr/share/doc/GraphicsMagick/www/index.html}}}}<br />
<br />
=== Common operations ===<br />
<br />
{{Note|The sign before an option is important. Opposite operations can be performed by using a ''plus'' instead of a ''minus''.}}<br />
<br />
==== Convert between image formats ====<br />
<br />
The basic usage of this facility is to specify the existing, and desired, image formats as the filename extension. For example, to get the ''.jpg'' representation of a given ''.png'' image, use: <br />
<br />
$ convert image.png image.jpg<br />
<br />
==== Append ====<br />
<br />
Combining multiple pictures into one:<br />
<br />
$ convert -append ''input.pngs'' ''output.png''<br />
<br />
==== Crop, chop ====<br />
<br />
To crop part of multiple images and convert them to another format:<br />
<br />
$ mogrify -crop ''WIDTH''x''HEIGHT''+''X''+''Y'' -format jpg *.png<br />
<br />
Where ''WIDTH'' and ''HEIGHT'' is the cropped output image size, and ''X'' and ''Y'' is the offset from the input image size.<br />
<br />
One can also {{ic|-chop}} to cut of a single edge from an image, using gravity to select that edge. Which is easier as less numbers, or trial and error, is involved.<br />
<br />
$ magick frame_red.gif -gravity South -chop 0x10 chop_bottom.gif<br />
<br />
==== Limit the storage size ====<br />
<br />
To achieve reasonable quality for a given storage size:<br />
<br />
$ convert image.jpg -define jpeg:extent=3000KB image_small.jpg<br />
<br />
Hopefully, this will shorten the transmission time. Note that {{ic|-quality}}, as in <br />
<br />
$ convert image.jpg -quality 85% image_small.jpg<br />
<br />
is harder to use when the correlation between quality and storage size is not clear.<br />
<br />
=== Screenshot taking ===<br />
<br />
An easy way to take a screenshot of your current system is using the {{man|1|import}} command:<br />
<br />
$ import -window root screenshot.jpg<br />
<br />
Running {{ic|import}} without the {{ic|-window}} option allows selecting a window or an arbitrary region interactively. With {{ic|-pause}} you can specify a delay in which you can, for example, lower some windows. <br />
<br />
{{Note|If you prefer '''graphicsmagick''' alternative, just prepend "gm", e.g. {{ic|$ gm import -window root screenshot.jpg}}.}}<br />
<br />
==== Screenshot of multiple X screens ====<br />
<br />
If you run twinview or dualhead, simply take the screenshot twice and use {{ic|imagemagick}} to paste them together:<br />
<br />
{{bc|<br />
$ import -window root -display :0.0 -screen /tmp/0.png<br />
$ import -window root -display :0.1 -screen /tmp/1.png<br />
$ convert +append /tmp/0.png /tmp/1.png screenshot.png<br />
$ rm /tmp/{0,1}.png<br />
}}<br />
<br />
==== Screenshot of individual Xinerama heads ====<br />
<br />
Xinerama-based multi-head setups have only one virtual screen. If the physical screens are different in height, you will find dead space in the screenshot. In this case, you may want to take screenshot of each physical screen individually. As long as Xinerama information is available from the X server, the following will work:<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
xdpyinfo -ext XINERAMA | sed '/^ head #/!d;s///' |<br />
while IFS=' :x@,' read i w h x y; do<br />
import -window root -crop ${w}x$h+$x+$y head_$i.png<br />
done<br />
</nowiki>}}<br />
<br />
==== Screenshot of the active/focused window ====<br />
<br />
The following script takes a screenshot of the currently focused window. It works with EWMH/NetWM compatible X Window Managers. To avoid overwriting previous screenshots, the current date is used as the filename.<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
activeWinLine=$(xprop -root | grep "_NET_ACTIVE_WINDOW(WINDOW)")<br />
activeWinId=${activeWinLine:40}<br />
import -window "$activeWinId" /tmp/$(date +%F_%H%M%S_%N).png<br />
</nowiki>}}<br />
<br />
Alternatively, the following should work regardless of EWMH support:<br />
<br />
$ import -window "$(xdotool getwindowfocus -f)" /tmp/$(date +%F_%H%M%S_%N).png<br />
<br />
{{Note|If screenshots of some programs (e.g. [[zathura]]) appear blank, try appending {{ic|-frame}} or removing {{ic|-f}} from the {{ic|xdotool}} command.}}<br />
<br />
=== Encryption of image data ===<br />
<br />
To encrypt:<br />
<br />
$ echo ''pass_phrase'' | magick ''image.jpg'' -encipher - -depth 8 png24:''image.png''<br />
<br />
This can be decrypted by:<br />
<br />
$ echo ''pass_phrase'' | magick ''image.png'' -decipher - ''image.jpg''<br />
<br />
It is highly advised to read the discussion at [https://imagemagick.org/Usage/transform/#encipher Encrypting Images] for all sorts of issues, and suggestions, for such commands.<br />
<br />
Metadata of image formats that have the {{ic|cipher}} tag can be used to test for encryption. However, it could be removed or spoofed by an EXIF editing program.<br />
<br />
$ identify -verbose image.png<br />
<br />
In general, testing if a raster image was encrypted can be done by checking the distribution of the pixel components. If it exceeds a certain threshold, the data could be considered random and a possible candidate for encryption. However, an example for false positives are images created with the [[wikipedia:Diamond-square algorithm|Diamond-square algorithm]].<br />
<br />
== Create a PDF from images ==<br />
See [[PDF, PS and DjVu#Create a PDF from images]]. For some background, [https://unix.stackexchange.com/questions/42856/how-can-i-convert-a-png-to-a-pdf-in-high-quality-so-its-not-blurry-or-fuzzy a stackexchange thread].<br />
<br />
== See also ==<br />
<br />
* [https://www.imagemagick.org/ ImageMagick website] for an extensive list of options, [https://imagemagick.org/Usage/ examples] and [https://imagemagick.org/script/examples.php showcase].<br />
* [[List of applications/Multimedia#Image processing]]<br />
* [http://www.fmwconcepts.com/imagemagick/index.php Fred's ImageMagick Scripts] for large collection of ImageMagic scripts</div>Regidhttps://wiki.archlinux.org/index.php?title=Bug_reporting_guidelines&diff=803205Bug reporting guidelines2024-03-15T02:44:51Z<p>Regid: /* Creating an account */ I login infrequently. I forgot about all that, and where it is written down. Hopefully, it will help other users. As an aside, an email I got from support told me that, and other related details. Perhaps gitlab.archlinux.org login page shuld have a link to similar instructions/explanation, or to the Initiative for Open Authentication article.</p>
<hr />
<div>[[Category:Arch development]]<br />
[[es:Bug reporting guidelines]]<br />
[[ja:バグ報告ガイドライン]]<br />
[[pt:Bug reporting guidelines]]<br />
[[ru:Bug reporting guidelines]]<br />
[[zh-hans:Bug reporting guidelines]]<br />
{{Related articles start}}<br />
{{Related|General guidelines#GitLab}}<br />
{{Related|General troubleshooting}}<br />
{{Related|Step-by-step debugging guide}}<br />
{{Related|Debugging/Getting traces}}<br />
{{Related articles end}}<br />
<br />
Opening (and closing) bug reports on the [https://gitlab.archlinux.org/groups/archlinux/packaging/packages/-/issues Arch Linux bug tracker in Gitlab] is one of many possible ways to [[Getting involved|help the community]]. However, poorly-formed bug reports can be counter-productive. When bugs are incorrectly reported, developers waste time investigating and closing invalid reports. This document will guide anyone wanting to help the community by efficiently reporting and hunting bugs.<br />
<br />
See also: [https://www.chiark.greenend.org.uk/~sgtatham/bugs.html How to Report Bugs Effectively] by Simon Tatham<br />
<br />
== Before reporting ==<br />
<br />
Preparing a detailed and well-formed bug report is not difficult, but requires an effort on behalf of the reporter. '''The work done before reporting a bug is arguably the most useful part of the job.''' Unfortunately, few people take the time to do this work properly.<br />
<br />
The following steps will guide you in preparing your bug report or feature request.<br />
<br />
=== Search for duplicates ===<br />
<br />
If you encounter a problem or desire a new feature, there is a high probability that someone else already had this problem or idea. If so, an appropriate bug report may already exist. In this case, please do not create a duplicate report; see [[#Following up on bugs]] instead.<br />
<br />
Search thoroughly for existing information, including:<br />
<br />
* [https://bbs.archlinux.org/ Arch Linux Forums]: The forums are often the first stop for users looking for help or sharing ideas. While a solution may not yet exist, additional background information and discussion can steer you in the right direction.<br />
* [https://gitlab.archlinux.org/groups/archlinux/packaging/packages/-/issues Arch Linux bug tracker]: Your problem may have already been reported to Arch Linux developers. Duplicate bug reports are unhelpful and promptly closed. Search both closed bugs as well as open reports by choosing 'All Statuses' under Advanced. Remember to mark 'search details' and/or 'search comments' under Advanced, the bug title may not contain the text you are searching for.<br />
* [https://www.google.com Google] or your favorite search engine: Search using the program's name, version, and a relevant part of the error message, if any.<br />
* '''Upstream''' forum, mailing list and bug tracker: If Arch Linux is not responsible for a bug, it should be reported upstream rather than the Arch Linux bug tracker. Search both recently closed bugs as well as open reports. Bugs may have already been fixed in the program's development version.<br />
* '''Other distribution forums''': The free software community is vast; Archers are not the only users with ideas! Consider searching the [https://forums.gentoo.org/ Gentoo Forums], [https://forums.fedoraforum.org/ FedoraForum.org], and [https://ubuntuforums.org/ Ubuntu Forums], for example.<br />
<br />
=== Upstream or Arch? ===<br />
<br />
Arch Linux is a GNU/Linux ''distribution''. Arch developers and Trusted Users are responsible for compiling, packaging, and distributing software from a wide range of sources. '''Upstream''' refers to these ''sources'' &ndash; the original authors or maintainers of software that is distributed in Arch Linux. For example, the popular Firefox web browser is developed by the Mozilla Project.<br />
<br />
'''If Arch is not responsible for a bug, the problem will not be solved by reporting the bug to Arch developers.''' Responsibility for a bug is said to lie upstream when it is not caused through the distribution's porting and integration efforts.<br />
<br />
By reporting bugs upstream, you will not only help Archers and Arch developers, but you will also help other people in the free software community as the solution will trickle down to all distributions.<br />
<br />
Once you have reported a bug upstream or have found other relevant information from upstream, it might be helpful to post this in the Arch bug tracker, so both Arch developers and users are made aware of it.<br />
<br />
So what is Arch Linux responsible for?<br />
<br />
* '''Arch Linux Projects''': [[pacman]], [[AUR]], [[mkinitcpio]], Arch Websites. If you have a doubt about if the project belongs to Arch or not, display the package information ({{ic|pacman -Qi ''package_name''}} or using the website) and look at the upstream URL. {{Note|Report issues for [[Getting involved#Software projects|Arch Linux software projects]] in the project's upstream issue tracker on [https://gitlab.archlinux.org/ gitlab.archlinux.org] or [https://github.com/archlinux GitHub] instead of the respective package issues.}}<br />
* '''Packaging''': Packaging basically consists of fetching the source code from upstream, compiling it with relevant options, making sure that it will be correctly installed on an Arch system, and checking that the main functionality works. Packaging at Arch does not consist of adding new functionality or patches for existing bugs; this is the job of the upstream developer.<br />
<br />
If a bug/feature is not under Arch's responsibility, report it upstream. See also [[#Reasons for not being a bug]].<br />
<br />
=== Bug or feature? ===<br />
<br />
; bug: something that should work but does not work, contrary to the developer's intentions.<br />
; feature: something which software does or would do if somebody coded it.<br />
<br />
==== Reasons for not being a bug ====<br />
<br />
* Something you would like a piece of software to do, which is not implemented by the upstream developers. In short: '''a new feature'''.<br />
* A bug already reported upstream.<br />
* A bug already fixed upstream but not in Arch because the package is not up-to-date.<br />
* '''A package which is not-up-to-date'''. Use the '''Flag Package Out-of-Date''' feature on [https://archlinux.org/packages/ Arch's packages website].<br />
* A package which does not use Fedora, Ubuntu or some other community patch. '''Patches should be submitted ''upstream'''''.<br />
* A package where '''non essential function''' X or function Y is not activated. This is a feature request.<br />
* A package which does not include a '''.desktop file''' or '''icons''' or other [https://www.freedesktop.org freedesktop] stuff. This is not a bug if such files are not included in the source tarball, and this must be requested as a feature request ''upstream''. If such files are provided by ''upstream'' but not used in the package then this is a bug.<br />
<br />
==== Reasons for not being a feature ====<br />
<br />
* When it is a bug...<br />
* When it is not under Arch responsibility to implement the feature, i.e. an '''upstream feature'''.<br />
* A package is not up-to-date. Use the '''Flag Package Out-of-Date''' feature on [https://archlinux.org/packages/ Arch's packages website].<br />
* A package which does not use Fedora, Ubuntu or some other community patch. '''Patches should be submitted ''upstream'''''.<br />
<br />
=== Gather useful information ===<br />
<br />
Here is a list of useful information that should be mentioned in your bug report:<br />
<br />
* '''Version of the package''' being used. '''Always specify package version'''. Saying "the latest", "todays", or "the package in extra" have absolutely no meaning. Especially if the bug is not about to get fixed right away.<br />
* Version of the main libraries used by the package (available in the ''depends'' variable in the PKGBUILD), when they are involved in the problem. If you do not know exactly what information to provide then wait for a bug hunter to ask you for it...<br />
* Version of the kernel used if you are having hardware related problems.<br />
* Indicate whether or not '''the functionality worked at one time or not'''. If so, indicate since when it stopped working.<br />
* Indicate your '''hardware brand''' when you are having hardware related problems<br />
* Add '''relevant log information''' when any is available. This can be obtained in the following places depending on the problem:<br />
** The [[systemd journal]]. If using {{Pkg|syslog-ng}}, {{ic|/var/log/messages}} contains logs related to kernel and hardware related issues.<br />
** {{ic|~/.local/share/xorg/Xorg.0.log}} or {{ic|/var/log/Xorg.0.log}} or {{ic|/var/log/Xorg.2.log}} or any Xorg like log files if video related problems (nvidia, ati, xorg...)<br />
** Run your program in a '''console''' and use '''verbose''' and/or '''debug''' mode if available (see your program documentation), and copy the output in a file. When running an application in a terminal make sure relevant information will be displayed in '''English''' so that many people can understand it. This can be done by using {{ic|1=export LC_ALL=C.UTF-8}}. Example with a software named ''foobar'' from which you would like to have relevant information at runtime and provided that ''foobar'' has a {{ic|--verbose}} option: {{bc|<nowiki>$ export LC_ALL=C.UTF-8<br />
$ foobar --verbose<br />
</nowiki>}} This will affect only the current terminal and will stop taking effect when the terminal is closed.<br />
<br />
If you have to paste a lot of text, like the output of [[dmesg]], or an Xorg log, is it preferred to save it as a file on your computer and attach it to your bug report. Attaching a file rather than using a pastebin to present relevant information is preferable in general due to the fact that pastebined content may suffer by expired links or any other potential problems. '''Attaching a file guarantees the provided information will always be available'''.<br />
<br />
* '''Indicate how to reproduce the bug'''. This is very important, it will help people test the bug and potential patches on their own computer.<br />
* '''The stack trace'''. It is a list of calls made by the program during its execution, and helps in finding part of the program where the bug is located, especially if bug involves the program crashing. You can obtain a stack trace using {{Pkg|gdb}} (The GNU Debugger) as explained in [[Debugging/Getting traces#Getting the trace]].<br />
<br />
== Opening a bug ==<br />
<br />
When you are sure it is a bug or a feature and you gathered all useful information, then you are ready to open a bug report or feature request.<br />
<br />
=== Creating an account ===<br />
<br />
You have to create an account on [https://gitlab.archlinux.org/ Arch's GitLab], which manages its login via [https://accounts.archlinux.org Arch Linux SSO].<br />
<br />
{{Note|Due to an influx of spam, we have had to temporarily disable account registrations there. Please send an email to &#097;&#099;&#099;&#111;&#117;&#110;&#116;&#115;&#117;&#112;&#112;&#111;&#114;&#116;&#064;&#097;&#114;&#099;&#104;&#108;&#105;&#110;&#117;&#120;&#046;&#111;&#114;&#103;, with your desired username, if you want to get access.}}<br />
After the account is created, and depending on the application you are using to login, you may be explicitly asked for a one-time code each time you are trying to login. A possible command line tool for that is [[Initiative for Open Authentication#Generate OTPs from the command line]].<br />
<br />
=== Where to open the bug ===<br />
<br />
Once you have determined your feature or bug is related to Arch and not an upstream issue, you will need to file your problem in the correct project. This is most easily done via '''Add new bug''' on the respective packages page on [https://archlinux.org archlinux.org].<br />
<br />
You can alternatively also get to the correct page using pkgctl from {{pkg|devtools}}:<br />
$ pkgctl repo web ''pkgname''<br />
<br />
Problems with packages in the [[AUR]] are not reported in the bug tracker. The AUR allows you to add comments to a package, which you should use to report bugs to the package maintainer.<br />
<br />
=== Title ===<br />
<br />
Please write a concise and descriptive title for your bug/feature request.<br />
<br />
Here is a list of recommendations:<br />
<br />
* '''Do not''' name your report "''pkgname'' is broken after the last update" - it is non-descriptive and "after last update" has no meaning in Arch.<br />
* Do not write too much text in the title. Excessive text will not be visible in reports list.<br />
<br />
=== Severity ===<br />
<br />
{{Out of date|Users themselves can't assign labels to GitLab issues.}}<br />
<br />
Choosing a ''critical'' severity will not help to solve the bug faster. It will only make truly critical problems less visible and probably make the developer assigned to your bug a bit less open to fixing it.<br />
<br />
Here is a general usage of severities:<br />
<br />
* '''Critical''' - System crash, severe boot failure that is likely to affect more than just you, or an exploitable security issue in either a core or outward-facing service package.<br />
* '''High''' - The main functionality of the application does not work, less critical security issues, etc.<br />
* '''Medium''' - A non-essential functionality does not work, UNIX standards not respected, etc.<br />
* '''Low''' - An optional functionality (plugin or compilation activated) does not work.<br />
* '''Very Low''' - Translation or documentation mistake. Something that really does not matter much but should be noticed for a future release.<br />
<br />
=== Including relevant information ===<br />
<br />
This is maybe one of the most difficult parts of bug reporting. You have to choose from the section [[#Gather useful information]] which information you will add to your bug report. This will depend on which your problem is. If you do not know what the relevant pieces of information are, do not be shy: '''it is better to give more information than needed than not enough'''.<br />
<br />
A good tutorial on reporting bugs can be found at https://www.chiark.greenend.org.uk/~sgtatham/bugs.html.<br />
<br />
However, developers or bug hunters will ask you for more information if needed. Fortunately after a few bug reports you will know what information should be given.<br />
<br />
Short information can be inlined in your bug report, whereas '''long information (logs, screenshots...) should be attached'''.<br />
<br />
== Following up on bugs ==<br />
<br />
'''Do not think the work is done once you have reported a bug'''!<br />
<br />
Developers or other users will probably ask you for more details and give you some potential fixes to try. Without continued feedback, bugs cannot be closed and the end result is both angry users and developers.<br />
<br />
=== Voting and Watching ===<br />
<br />
You can '''vote''' for your favourite bugs via [https://gitlab.archlinux.org/help/user/emoji_reactions.html reactions] on the issue. The number of reactions indicates to the developers how many people are impacted by the bug without creating too much noise. However, this is not a very effective way of getting the bug solved. Much more important would be posting any additional information you know about the bug if you were not the original reporter.<br />
<br />
'''Watching''' a bug is important: you will receive an email when new comments are added or the bug status has changed. This can be done via the "..." menu in the upper right corner by toggling the Notification switch there.<br />
If you opened a issue or commented on it you will automatically be subscribed to changes.<br />
<br />
=== Answering additional information requests ===<br />
<br />
People will take the time to look at your bug report and will try to help you. You need to continue to help them resolve your bug. Not answering to their questions will keep your bug unresolved and likely hamper enthusiasm to fix it.<br />
<br />
'''Please take the time to give people more information if requested and try the solutions proposed'''.<br />
<br />
Developers or bug hunters will close your bug if you do not answer questions after a few weeks or a month.<br />
<br />
=== Updating the bug report when a new package version is out ===<br />
<br />
Sometimes, a bug is only present in certain version(s) of a given package, and the bug is fixed in a new version of the package. If this is the case, say so in the bug report comments, and request that the bug be closed.<br />
<br />
=== Closing when solved ===<br />
<br />
Sometimes people report a bug but do not notify when they have solved it on their own, leaving people searching for a solution that has already been found. Please close the bug if you found a solution, and give the solution in the bug report comments.<br />
<br />
== Bug status ==<br />
<br />
During its life, a bug may go through several states:<br />
<br />
* '''Unconfirmed''' - This is the default state. You have just reported it and nobody managed to reproduce the problem or confirmed that it is actually a bug.<br />
* '''New''' - The bug is confirmed but it has not been assigned to the developer responsible for the related software. It is usually the case when more investigation is needed to determine which software is responsible for the bug.<br />
* '''Assigned''' - The bug has been assigned to a developer responsible for the software involved in the bug. It does not mean that the developer will be the one who will fix the bug. It does not even mean that the developer will work on a solution. It just means that the developer will take care of the life cycle of the bug, including reviewing patches if any, releasing a fix and closing the bug when required. It is unwise to contact a developer directly and to ask them to fix it more quickly; they will certainly not like this.<br />
* '''Researching''' - Somebody is looking for a solution. This status is '''rarely used at Arch''', for good reason. The ''researching'' status could make people believe they do not need to get interested in the bug report. But usually we need more than one person to fix a bug: having several experienced people on a bug helps a lot.<br />
* '''Waiting on Response''' and '''Requires testing''' - The one who reported a bug has been asked to provide more information or to try a proposed solution, but they did not reply yet. These statuses are '''rarely used at Arch''', but should be used more often. Still, it is important that you '''watch the bug''' (see [[#Voting and Watching]]), as developers or bug hunters usually ask questions in the comments.<br />
* '''A task closure has been requested''' - This is not exactly a status, but you may find some bug reports with such a notification. This indicates that somebody requested a closure for the bug. A reason is added to the request most of the time. It is upon the assignee developer to decide whether they will accept the closure or not.<br />
* '''Closed''' - Either this is not a valid bug (see [[#Reasons for not being a bug]]) or a solution has been found and released.<br />
<br />
Some people (e.g. developers, TUs) are responsible for dispatching bugs and setting their status.</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=799905CURL2024-02-07T12:29:00Z<p>Regid: Following the curl site and the stackoverflow user answer, I think it worth emphasizing.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
{{Note|Despite superficially equivalent to [[wget]], this is not the case. See [https://curl.se/docs/faq.html#Can_I_do_recursive_fetches_with Can_I_do_recursive_fetches_with], [https://superuser.com/a/972282 run the equivalent curl command to a given wget command] and [https://curl.se/docs/faq.html#What_is_curl_not What_is_curl_not].}}<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl --output ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl --remote-name ''URL''<br />
<br />
Similarly, you can use {{ic|-J/--remote-header-name}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O/--remote-name}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl --data ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl --data @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl --data ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU, curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl --progress-bar ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. You can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=Wget&diff=799873Wget2024-02-07T00:09:33Z<p>Regid: Following Help:Style#Spelling to `prefer using the long form of uncommon command option', which, I think wget falls under</p>
<hr />
<div>[[Category:Download utilities]]<br />
[[Category:GNU]]<br />
[[es:Wget]]<br />
[[ja:Wget]]<br />
[[pl:Wget]]<br />
[https://www.gnu.org/software/wget/ GNU Wget] is a free software package for retrieving files using [[HTTP]], HTTPS, [[FTP]] and FTPS ''(FTPS since version 1.18)''. It is a non-interactive commandline tool, so it may easily be called from scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|wget}} package. The [[git]] version is present in the [[AUR]] by the name {{AUR|wget-git}}.<br />
<br />
== Configuration ==<br />
<br />
Configuration is performed in {{ic|/etc/wgetrc}}. Not only is the default configuration file well documented; altering it is seldom necessary. See {{man|1|wget|OPTIONS}} for more intricate options.<br />
<br />
=== FTP automation ===<br />
<br />
Normally, [[SSH]] is used to securely transfer files among a network. However, FTP is lighter on resources compared to scp and [[rsync]]ing over SSH. FTP is not secure, but when transfering large amounts of data inside a firewall protected environment on CPU-bound systems, using FTP can prove beneficial.<br />
<br />
wget <nowiki>ftp://root:somepassword@10.13.X.Y//ifs/home/test/big/"*.tar"</nowiki><br />
<br />
3,562,035,200 74.4M/s in 47s<br />
<br />
In this case, Wget transfered a 3.3 GiB file at 74.4MB/second rate.<br />
<br />
In short, this procedure is:<br />
*scriptable<br />
*faster than ssh<br />
*easily used by languages than can substitute string variables<br />
*[[Wikipedia:glob (programming)|globbing]] capable<br />
<br />
=== Proxy ===<br />
<br />
Wget uses the standard proxy environment variables. See [[Proxy settings]].<br />
<br />
To use the proxy authentication feature:<br />
$ wget --proxy-user "DOMAIN\USER" --proxy-password "PASSWORD" URL<br />
<br />
Proxies that use HTML authentication forms are not covered.<br />
<br />
=== pacman integration ===<br />
<br />
To have [[pacman]] automatically use Wget and a proxy with authentication, place the Wget command into {{ic|/etc/pacman.conf}}, in the {{Ic|[options]}} section:<br />
XferCommand = /usr/bin/wget --proxy-user "domain\user" --proxy-password="password" --passive-ftp --quiet --show-progress --continue --output-document=%o %u<br />
<br />
{{Warning|Be aware that storing passwords in plain text is not safe. Make sure that only root can read this file with {{Ic|chmod 600 /etc/pacman.conf}}.}}<br />
<br />
== Usage ==<br />
<br />
This section explains some of the use case scenarios for Wget.<br />
<br />
=== Basic usage ===<br />
<br />
One of the most basic and common use cases for Wget is to download a file from the internet.<br />
<br />
$ wget <url><br />
<br />
When you already know the URL of a file to download, this can be much faster than the usual routine downloading it on your browser and moving it to the correct directory manually. Needless to say, just from the simplest usage, you can probably see a few ways of utilising this for some automated downloading if that's what you want.<br />
<br />
=== Archive a complete website ===<br />
<br />
Wget can archive a complete website whilst preserving the correct link destinations by changing absolute links to relative links.<br />
<br />
$ wget --recursive --no-parent --convert-links '<nowiki>target-url-here</nowiki>'<br />
<br />
In case of a dynamic website, some additional options for conversion into static HTML are available.<br />
<br />
$ wget --recursive --no-parent --page-requisites --adjust-extension --convert-links --backup-converted '<nowiki>target-url-here</nowiki>'<br />
<br />
''wget'' also provides options for bypassing download-prevention mechanisms.<br />
<br />
$ wget --recursive --no-parent --convert-links --random-wait --execute robots=off --user-agent "Mozilla/5.0" '<nowiki>target-url-here</nowiki>'<br />
<br />
And if third-party content is to be included in the download, {{ic|-H/--span-hosts}} switch can be used alongside {{ic|-r/--recursive}} to recurse to linked hosts.</div>Regidhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=798205GnuPG2024-01-25T11:33:40Z<p>Regid: /* Configuration */ IMHO, this falls under Help:Style#Spelling's 2nd bullet `prefer using the long form of uncommon command options instead of their single-character counterpart'</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:OpenPGP]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/dir''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Warning| When using {{ic|--full-gen-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular some newer [[Wikipedia:Elliptic-curve cryptography|elliptic curves]] like [[Wikipedia:Curve448|Curve448]].<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''ECC (sign and encrypt)'' for signing and encryption keys.<br />
* The default ''Curve 25519'' to use [[Wikipedia:Curve25519|Curve25519]] and [[Wikipedia:Ed25519|Ed25519]].<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public-key''.asc}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public-key''.asc ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your {{ic|gpg.conf}}.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use OpenPGP with external GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public-key''.asc}} to your public key ring:<br />
<br />
$ gpg --import ''public-key''.asc<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|There are keyserver where submitted keys cannot be deleted. Some of the reasons are explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --receive-keys ''key-id''<br />
<br />
To refresh/update the keychain with the latest version from a key server:<br />
<br />
$ gpg --refresh-keys<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to the [[#Configuration files|GPG configuration file]] will automatically fetch keys from the key server as needed. This is not a compromise on security, but it can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg|auto-key-retrieve}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver ''hkps://keys.openpgp.org/'' --search-keys ''user-id''<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<br />
* If connecting to a keyserver fails with {{ic|gpg: keyserver receive failed: Server indicated a failure}}, you may need to configure gpg to use an alternate port. For example, to use port 80 on Ubuntu's keyserver, use {{ic|keyserver hkp://keyserver.ubuntu.com:80}}.<br />
}}<br />
<br />
=== Web Key Directory ===<br />
<br />
{{Move| OpenPGP | Although the Web Key Directory (WKD) is an IETF draft by gnupg author Werner Koch, it is relevant for all implementations of [[OpenPGP]] and in fact already used by some.}}<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''private-key''.asc ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''private-key''.asc<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert''.asc ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.asc<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.asc<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.asc<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.asc}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver ''pgp.mit.edu'' --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert''.asc<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses the recipient public key to encrypt a document, signatures are created with the sender's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
{{Expansion|Document {{ic|keyboxd.socket}} and {{ic|keyboxd.service}}.[https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/commit/1551c66631a28501a677d16d5fef9a37fadf2b95]}}<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] the {{ic|ListenStream}} (see {{man|5|systemd.socket|options}}) of all the socket files to be consistent with {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip --list-secret-keys}}. 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 />
It is necessary to allow this passphrase presetting by starting gpg-agent with the {{ic|--allow-preset-passphrase}} or setting {{ic|allow-preset-passphrase}} in {{ic|~/.gnupg/gpg-agent.conf}}.<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/}}. You may need to install the relevant [[pacman#Installing packages|optional dependencies]] for your chosen pinentry program.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* The pinentry programs {{ic|/usr/bin/pinentry-gnome3}} (GNOME) and {{ic|/usr/bin/pinentry-gtk-2}} (generic) [https://avaldes.co/2020/01/28/secret-service-keepassxc.html] support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]], [[KeePass#Secret Service|KeePassXC]] or [[KDE Wallet]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disabling|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
=== Forwarding gpg-agent and ssh-agent to remote ===<br />
<br />
{{Expansion|What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]?}}<br />
<br />
It is possible to forward one's gpg-agent to a remote machine by forwarding gpg sockets to the remote machine, as explained by the [https://wiki.gnupg.org/AgentForwarding GnuPG wiki].<br />
<br />
First, add the following line to {{ic|/etc/ssh/sshd_config}} on the remote machine to enable automatic removal of stale sockets on connect. Without this, the socket(s) on the remote machine will need to removed manually before connecting with forwarding enabled for agent forwarding to work:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
StreamLocalBindUnlink yes<br />
...<br />
}}<br />
<br />
{{Note|You will have to [[reload]] {{ic|sshd.service}} on the remote machine for the new configuration to be loaded by sshd.}}<br />
<br />
On the client, use the {{ic|RemoteForward}} SSH directive to forward traffic destined for a remote port, to a port on your local host. As described in {{Man|5|ssh_config|RemoteForward}}, this directive's parameters are the listening socket path on the remote, and then the destination socket path on the local host. Your configuration should look something like this:<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''remote_name''<br />
...<br />
RemoteForward ''remote_agent_socket'' ''local_agent_extra_socket''<br />
RemoteForward ''remote_agent_ssh_socket'' ''local_agent_ssh_socket''<br />
}}<br />
<br />
The first line configures gpg-agent forwarding:<br />
<br />
* ''remote_agent_socket'' is the output of {{ic|gpgconf --list-dir agent-socket}} on the remote host.<br />
* ''local_agent_extra_socket'' is {{ic|gpgconf --list-dir agent-extra-socket}} on the local host.<br />
<br />
The second line is optional. It configures ssh-agent forwarding:<br />
<br />
* ''local_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the remote host.<br />
* ''remote_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the local host.<br />
<br />
{{Note|If using ssh-agent forwarding, the remote should have {{ic|SSH_AUTH_SOCK}} set to the output of {{ic|gpgconf --list-dir agent-ssh-socket}} as mentioned in [[#SSH agent]]).}}<br />
<br />
So, with the default paths, it would be:<br />
<br />
{{bc|<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh<br />
}}<br />
<br />
With this configuration in place, invoking {{ic|ssh ''remote_name''}} should automatically forward the gpg-agent to the remote, and allow the use of your gpg key(s) for both decryption/signing (and allows the use of ssh-agent with gpg if the second {{ic|RemoteForward}} line is included).<br />
<br />
== Smartcards ==<br />
<br />
{{Expansion|GnuPG 2.3+ has a {{man|1|gpg-card}} tool.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). In earlier versions, if GnuPG's scdaemon failed to connect to the smartcard directly (e.g. by using its integrated CCID support), it fell back and tried to find a smartcard using the PCSC Lite driver. [https://dev.gnupg.org/rG6b93b92111cb8ce6d06c6f71bd62cfb314663b8c Since version 2.4] however, you will have to add the {{Ic|disable-ccid}} option in {{ic|~/.gnupg/scdaemon.conf}}, to be able to use pcscd.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
===== Using a smart card on a remote client via SSH =====<br />
<br />
If you log into a machine via SSH and try to use an attached device via pcscd, you will notice errors such as:<br />
<br />
gpg: selecting card failed: No such device<br />
gpg: OpenPGP card not available: No such device<br />
<br />
This is due to [[Polkit]] restricting access to local clients. To fix this, you can add a rule to allow certain users in all cases. The below rule allows all users in the {{ic|wheel}} group to access devices via {{ic|pcscd}}:<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-pcscd.rules|2=<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_card" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_pcsc" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
After creating the file, make sure to [[restart]] {{ic|polkit.service}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable unsupported AEAD mechanism ===<br />
<br />
With {{pkg|gnupg}} 2.4, {{ic|gpg}} generates keys, which advertise support for a GnuPG specific [[Wikipedia:Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) | AEAD]] encryption mechanism (based on [[Wikipedia:OCB_mode | OCB]]). However, this flavor of AEAD is not supported by other [[OpenPGP]] implementations!<br />
<br />
Although many downstreams attempt to remove this new default by [https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/blob/cfc8f931ee3167a3673b249018dbba527d7428f8/gnupg-2.4-revert_default_rfc4880bis.patch patching the GnuPG sources], when using {{ic|--full-gen-key}} the OCB based custom AEAD encryption mechanism is nonetheless set for the new key.<br />
<br />
Whether GnuPG's custom AEAD is set for a key can be inspected with the help of {{ic|gpg}} itself:<br />
<br />
$ gpg --expert --edit-key ''<FINGERPRINT>''<br />
gpg> showpref<br />
[ultimate] (1). Foobar McFooface (test) <foobar@mcfooface.com><br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD: '''OCB'''<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, '''AEAD''', Keyserver no-modify<br />
<br />
This mechanism can be disabled:<br />
<br />
gpg> setpref AES256 AES192 AES SHA512 SHA384 SHA256 SHA224 ZLIB BZIP2 ZIP<br />
Set preference list to:<br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD:<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, Keyserver no-modify<br />
Really update the preferences? (y/N) y<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis (i.e. using a little social engineering, anyone who is able to decrypt the message can check whether one of the other recipients is the one they suspect). On the receiving side, it may slow down the decryption process because all available secret keys must be tried (e.g. with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
{{Warning| When using {{ic|--full-generate-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<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 />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disabling]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
=== Keyblock resource does not exist ===<br />
<br />
If you get an error like this when trying to import keys<br />
<br />
gpg: keyblock resource '''gnupg_home''/pubring.kbx': No such file or directory<br />
<br />
it is because GnuPG will not create its home directory if it does not yet exist. Simply create it manually<br />
<br />
$ mkdir -m 700 ''gnupg_home''<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=798061Talk:GnuPG2024-01-24T12:31:17Z<p>Regid: /* Which keyserver or keyservers are recommeneded? */ Reply</p>
<hr />
<div>== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=poldi.git poldi] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:27, 4 August 2016 (UTC)<br />
<br />
== User configuration files not created ==<br />
<br />
Per the wiki, it states, "You will find skeleton files in /usr/share/gnupg. These files are copied to ~/.gnupg the first time gpg is run if they do not exist there."<br />
<br />
I could very well be doing something wrong so I'd ask that this could be verified. If we need to copy skel configuration files, it should be clearly explained in the wiki shouldn't it?<br />
<br />
I was unable to import public keys until I manually created a blank ~/.gnupg/gpg.conf with just keyserver pgp.mit.edu in it. <br />
<br />
I also found this when searching for info, https://manned.org/gpgv2/2862e42d. It states: There are no configuration files and only a few options are implemented.<br />
<br />
[[User:NuSkool|NuSkool]] ([[User talk:NuSkool|talk]]) 04:09, 26 September 2016 (UTC)<br />
<br />
:On the same topic but on a different note, update [[GnuPG#Configuration_files]] to remove ''out of date warning'' and add the following informtion:<br />
:1) '''~/.gnupg/gpg.conf''' and '''~/.gnupg/dirmngr.conf''' are not created by default. So, the user can create them to implement the changes.<br />
:2) global config file is located at '''/etc/gnupg/gpgconf.conf''' shown by command '''gpgconf --list-config'''. This is also not created by default. The example file is <br />
:at '''/usr/share/doc/gnupg/examples/gpgconf.conf'''<br />
:--[[User:RaZorr|RaZorr]] ([[User talk:RaZorr|talk]]) 12:51, 16 January 2022 (UTC)<br />
<br />
:I've used gpg and I don't have the configuration files. The wiki is wrong. [[User:Pound Hash|Pound Hash]] ([[User talk:Pound Hash|talk]])<br />
<br />
:I am having difficulty corroborating the existence of this functionality. There is no "default" {{ic|gpg.conf}} in the GnuPG repository, and I'm not sure if it even makes sense to have one. This file is for ''overriding'' defaults. For instance, this is what mine looks like:<br />
{{hc|gnupg.conf|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
default-key ''default-key''<br />
}}<br />
:It shouldn't be a complicated configuration file, just command line options that you want to use all the time. {{ic|dirmngr.conf}} is exactly the same way, as far as I can tell. So, [[User:RaZorr|RaZorr]] got it totally right with 1). With 2), though, {{ic|/etc/gnupg/gpgconf.conf}} is actually not the global version of {{ic|~/.gnupg/gpg.conf}}. {{ic|/etc/gnupg/gpgconf.conf}} is a "legacy mechanism" for setting up defaults using the ''gpgconf'' progrma. The modern way for configuring system-wide GnuPG defaults is {{ic|~/.gnupg/gpg.conf}}'s ''actual'' global analog: {{ic|/etc/gnupg/gpg.conf}}, which was introduced in 2020 [https://dev.gnupg.org/T4788].<br />
:I gave a shot at fixing this part of the page. Thanks, [[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 08:21, 20 May 2022 (UTC)<br />
::I am trying to use <code>/etc/gnupg/gpg.conf</code> But seems like it is not respected by gpg at all. Doesn't matter what I put there, it just doesn't effect. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:06, 10 January 2024 (UTC)<br />
::The problem was from setting permission of <code>/etc/gnupg/</code> files to <code>600</code>, making them unreadable to user's <code>gpg</code>. Changing file permissions back to <code>644</code> resolved the issue.</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:43, 10 January 2024 (UTC)<br />
<br />
== Recommendation to add ==<br />
<br />
By default, no skeleton files exist (as mentioned above) but in my case the lack of a dirmngr.conf meant that any --recv-keys failed with useful(?) errors like "gpg: keyserver receive failed: Server indicated a failure" or "gpg: error searching keyserver: Server indicated a failure". Route to get here was via makepkg, and so I skipped all the installation steps etc since gpg was already installed and went straight for a recv.<br />
<br />
echo > $HOME/.gnupg/dirmngr.conf 'standard-resolver'<br />
[[User:Beepboo|Beepboo]] ([[User talk:Beepboo|talk]]) 17:09, 22 March 2020 (UTC)<br />
:also requires to restart dirmngr.service [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:32, 25 April 2022 (UTC)<br />
:but the problem is probably on the /etc/resolv.conf file. Are you using systemd-resolved ? Then check [[Systemd-resolved#DNS]] [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:46, 25 April 2022 (UTC)<br />
<br />
== A comment on provided code snippet ==<br />
<br />
The test from [[GnuPG#Set_SSH_AUTH_SOCK|Set_SSH_AUTH_SOCK]] : <br />
<br />
[ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]<br />
<br />
would probably always fail, since [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307] sets {{ic|gnupg_SSH_AUTH_SOCK_by}} to the process id of {{ic|gpg-agent}}, and the line above tests it for the process id of the {{ic|bash}} process.<br />
<br />
Therefore, <br />
<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)" <br />
<br />
will probably get executed every time. However, it most likely wouldn't break anything since at worst it will reset {{ic|SSH_AUTH_SOCK}} to the same value.<br />
<br />
{{Unsigned| 11:16, 1 May 2021 (UTC)|Thread13}}<br />
<br />
== Invalid IPC response and Inappropriate ioctl for device ==<br />
I solved this problem simply by removing an {{ic|#}} inside {{ic|/etc/pinentry/preexec}} enabling the desired option and then setting {{ic|/usr/bin/pinentry}} as default.<br />
[[User:Pavlov|Pavlov]] ([[User talk:Pavlov|talk]]) 15:19, 2 May 2021 (UTC)<br />
<br />
== Another suggestion for troubleshooting automatic key fetching from keyservers in case that SRV lookup fails ==<br />
<br />
If the port is not explicitly stated, than GnuPG will try to use a DNS lookup using SRV [1].<br />
This may fail due to various reasons, so troubleshooting will be to explicitly set the keyservers with the ports, e.g. in ~/.gnupg/dirmngr.conf (or where appropriate)<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com:80<br />
</code> instead of just<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com<br />
</code><br />
[1] https://dev.gnupg.org/rGc2cbe2f87c480c62239dc4c2cbb352acd98cd267<br />
--[[User:Tobias.predel|Tobias.predel]] ([[User talk:Tobias.predel|talk]]) 10:09, 10 June 2022 (UTC)<br />
<br />
== pgp.mit.edu is not resolving ==<br />
pgp.mit.edu is not resolving, but is used many times within this documenation. Anyone have an ideas on an alternative? [[User:Jahway603|Jahway603]] ([[User talk:Jahway603|talk]]) 17:11, 9 March 2023 (UTC)!<br />
<br />
:At the time of this writing, it is resolvable here as an alias (CNAME) to {{ic|cryptonomicon.mit.edu}}, with an address of 18.9.60.141. Can it be your query ignored the possibility for a CNAME record? [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:22, 24 January 2024 (UTC)<br />
<br />
== Deprecated --supervised option for gpg-agent ==<br />
<br />
As per https://dev.gnupg.org/T6336#166815, it seems as though {{ic|gpg-agent --supervised}}, and as such systemd-based activation altogether, is deprecated by GnuPG. What would the ideal startup method for gpg-agent be instead in that case?<br />
[[User:90|90]] ([[User talk:90|talk]]) 17:41, 6 June 2023 (UTC)<br />
<br />
:I'd like to drop-in Werner's initial [https://dev.gnupg.org/rGeae28f1bd4a5632e8f8e85b7248d1c4d4a10a5ed#78329 reply], and add the removal applied for >=2.4.1. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:48, 19 September 2023 (UTC)<br />
<br />
== What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]? ==<br />
<br />
I tested the gpg-agent forwarding and the OpenSSH {{ic|ForwardAgent yes}} options. I am able to forward the use of my gpg key on my hardware key with the former, but it doesn't work with the latter. [[User:Seodisparate|Seodisparate]] ([[User talk:Seodisparate|talk]]) 12:23, 24 June 2023 (UTC)<br />
<br />
== Global configuration files should have 644 permission ==<br />
<br />
Setting permission of global configuration files at <code>/etc/gnupg/</code> to <code>600</code> make them unreadable for user's GPG process and thus makes them '''completely ineffective''', unless user invoke <code>gpg</code> as root which is the owner of the files; which in turn is not the proper way to use the <code>gpg</code> command. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:30, 10 January 2024 (UTC)<br />
<br />
:I guess you are right, yet this looks to me irrelevant. It looks to me irrelevant since my understanding of [[GnuPG#Configuration]] is {{ic|0600}} is referring to files under {{ic|~/.gnupg/}}, not to files under {{ic|/etc/gnupg/}}. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:39, 24 January 2024 (UTC)<br />
<br />
== Global GPG config special flags ==<br />
<br />
<p>Even though not well documented, The global GPG config file (and other files in the <code>/etc/gnupg/</code> directory) can have 3 special flags.[https://dev.gnupg.org/T4788#132919]</p><br />
<p>They are <code>[force]</code>To enforce an option to system's gpg users, <code>[-force]</code> To force disable an option and <code>[ignore]</code> to ignore a flag if it is used by users.</p><br />
<p>These flags can't be used in the user's gnuhomedir config files, and are specific to global config files.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:21, 11 January 2024 (UTC)<br />
<br />
:<p>Care must be taken when setting system-wide options in <code>/etc/gnupg/</code> files; particularly, one has to be extra careful when using <code>[force]</code>,<code>[-force]</code> and <code>[ignore]</code> options.</p><br />
:<p>Any flag used in these files, will affect operation of all software programs which are using GPG internally, systemwide. Namely, <code>pacman-key</code>.</p><br />
:<p>As an example, changing <code>trust-model</code> option to any mode other than <code>pgp</code> in <code>/etc/gnupg/gpg.conf</code>, or setting <code>use-keyboxd</code> in <code>/etc/gnupg/common.conf</code> will stop <code>pacman-key</code> and consequently <code>pacman</code> from functioning properly.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 21:19, 12 January 2024 (UTC)<br />
<br />
== Three Outdated "See also" articles ==<br />
<br />
<p>Yesterday, I putted time reading additional documentations introduced in this section.</p><br />
<p>Three of them are pretty old, and their contents are not true (At least in details) or accurate any more.</p><br />
[https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]</br><br />
[https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]</br><br />
[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:37, 11 January 2024 (UTC)<br />
<br />
== Using new "keyboxd" for keyring instead of "pubring.kbx" ==<br />
<br />
<p>A section can be added to this article talking about it. Or, At least, it's good to be mentioned in some part of this document.</p><br />
<br />
<p>As per recommendation of GnuPG[https://github.com/gpg/gnupg/blob/6ddaf2be9f484eb7a38f2bda0bb70f2d7b4c4511/README#L119], one can use ''key database daemon'' (keyboxd), with SQLite database, instead of <code>keyring.kbx</code> file for storing public keys.</p><br />
<br />
<p>This is currently the default since version 2.4.1 and will be in effect for any fresh home directory.</br><br />
Also, this can be enabled with <code>use-keyboxd</code> option in the <code>common.conf</code> file (One has to be created if it does not exist yet.) for older home directories.</p> <br />
<p>For a fresh keyring, nothing needs to be done. But for a current keyring, they have to be imported to the new database.</p><br />
<p>Nevertheless, it's as simple as:<br />
<pre><br />
gpg --export --export-options backup > allkeys.gpg<br />
gpgsm --export --armor > allcerts.gpg<br />
</pre><br />
To export current public keys. And:<br />
<pre><br />
gpg --import --import-options restore < allkeys.gpg<br />
gpgsm --import < allcerts.crt<br />
</pre><br />
<p>To import them to the new keyboxd, then adding <code>use-keyboxd</code> option to the <code>common.conf</code> to enable the new keyring format.</p><br />
<p>However, It may not be compatible with software programs that expect GPG to have a <code>pubring.kbx</code> to import it.[https://github.com/microsoft/vscode-remote-release/issues/9217] Even though it can be created easily in a reverse process in case.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 01:39, 12 January 2024 (UTC)<br />
<br />
== Which keyserver or keyservers are recommeneded? ==<br />
<br />
Section 3.5.3 Keyservers mentions three keyservers, each with slightly different capabilities. I would find it helpful if a brief explanation (for keyserver novices) were included with a recommendation, of which ones to use, in what order, and why. [[User:Vgivanovic|vgivanovic]] ([[User talk:Vgivanovic|talk]]) 18:09, 15 January 2024 (UTC)<br />
<br />
:Well, 3 distinct differences between [https://keyserver.ubuntu.com/ Ubuntu Keyserver] and {[https://keys.mailvelope.com/ Mailvelope Keyserver], [https://keys.openpgp.org/ keys.openpgp.org]} are already mentioned at [[GnuPG#Key servers]]: federated or centralized, verification and deletion. According to [https://github.com/mailvelope/keyserver/blob/master/README.md#why-not-use-web-of-trust Mailveleope], deletion adds to compliance with the [[w:Data_Protection_Directive|EU Data protection Directive]]. Mail verification can lead to spamming. Absence of Web of Trust is a matter of better privacy while makes it more difficult to trust the key holder. [https://github.com/mailvelope Mailvelope] seems to have several related open source projects. I did not check about the source of the other two key servers. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 12:31, 24 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=798057Talk:GnuPG2024-01-24T11:50:09Z<p>Regid: /* Global configuration files should have 644 permission */ Probably wrong case in internal links</p>
<hr />
<div>== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=poldi.git poldi] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:27, 4 August 2016 (UTC)<br />
<br />
== User configuration files not created ==<br />
<br />
Per the wiki, it states, "You will find skeleton files in /usr/share/gnupg. These files are copied to ~/.gnupg the first time gpg is run if they do not exist there."<br />
<br />
I could very well be doing something wrong so I'd ask that this could be verified. If we need to copy skel configuration files, it should be clearly explained in the wiki shouldn't it?<br />
<br />
I was unable to import public keys until I manually created a blank ~/.gnupg/gpg.conf with just keyserver pgp.mit.edu in it. <br />
<br />
I also found this when searching for info, https://manned.org/gpgv2/2862e42d. It states: There are no configuration files and only a few options are implemented.<br />
<br />
[[User:NuSkool|NuSkool]] ([[User talk:NuSkool|talk]]) 04:09, 26 September 2016 (UTC)<br />
<br />
:On the same topic but on a different note, update [[GnuPG#Configuration_files]] to remove ''out of date warning'' and add the following informtion:<br />
:1) '''~/.gnupg/gpg.conf''' and '''~/.gnupg/dirmngr.conf''' are not created by default. So, the user can create them to implement the changes.<br />
:2) global config file is located at '''/etc/gnupg/gpgconf.conf''' shown by command '''gpgconf --list-config'''. This is also not created by default. The example file is <br />
:at '''/usr/share/doc/gnupg/examples/gpgconf.conf'''<br />
:--[[User:RaZorr|RaZorr]] ([[User talk:RaZorr|talk]]) 12:51, 16 January 2022 (UTC)<br />
<br />
:I've used gpg and I don't have the configuration files. The wiki is wrong. [[User:Pound Hash|Pound Hash]] ([[User talk:Pound Hash|talk]])<br />
<br />
:I am having difficulty corroborating the existence of this functionality. There is no "default" {{ic|gpg.conf}} in the GnuPG repository, and I'm not sure if it even makes sense to have one. This file is for ''overriding'' defaults. For instance, this is what mine looks like:<br />
{{hc|gnupg.conf|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
default-key ''default-key''<br />
}}<br />
:It shouldn't be a complicated configuration file, just command line options that you want to use all the time. {{ic|dirmngr.conf}} is exactly the same way, as far as I can tell. So, [[User:RaZorr|RaZorr]] got it totally right with 1). With 2), though, {{ic|/etc/gnupg/gpgconf.conf}} is actually not the global version of {{ic|~/.gnupg/gpg.conf}}. {{ic|/etc/gnupg/gpgconf.conf}} is a "legacy mechanism" for setting up defaults using the ''gpgconf'' progrma. The modern way for configuring system-wide GnuPG defaults is {{ic|~/.gnupg/gpg.conf}}'s ''actual'' global analog: {{ic|/etc/gnupg/gpg.conf}}, which was introduced in 2020 [https://dev.gnupg.org/T4788].<br />
:I gave a shot at fixing this part of the page. Thanks, [[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 08:21, 20 May 2022 (UTC)<br />
::I am trying to use <code>/etc/gnupg/gpg.conf</code> But seems like it is not respected by gpg at all. Doesn't matter what I put there, it just doesn't effect. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:06, 10 January 2024 (UTC)<br />
::The problem was from setting permission of <code>/etc/gnupg/</code> files to <code>600</code>, making them unreadable to user's <code>gpg</code>. Changing file permissions back to <code>644</code> resolved the issue.</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:43, 10 January 2024 (UTC)<br />
<br />
== Recommendation to add ==<br />
<br />
By default, no skeleton files exist (as mentioned above) but in my case the lack of a dirmngr.conf meant that any --recv-keys failed with useful(?) errors like "gpg: keyserver receive failed: Server indicated a failure" or "gpg: error searching keyserver: Server indicated a failure". Route to get here was via makepkg, and so I skipped all the installation steps etc since gpg was already installed and went straight for a recv.<br />
<br />
echo > $HOME/.gnupg/dirmngr.conf 'standard-resolver'<br />
[[User:Beepboo|Beepboo]] ([[User talk:Beepboo|talk]]) 17:09, 22 March 2020 (UTC)<br />
:also requires to restart dirmngr.service [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:32, 25 April 2022 (UTC)<br />
:but the problem is probably on the /etc/resolv.conf file. Are you using systemd-resolved ? Then check [[Systemd-resolved#DNS]] [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:46, 25 April 2022 (UTC)<br />
<br />
== A comment on provided code snippet ==<br />
<br />
The test from [[GnuPG#Set_SSH_AUTH_SOCK|Set_SSH_AUTH_SOCK]] : <br />
<br />
[ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]<br />
<br />
would probably always fail, since [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307] sets {{ic|gnupg_SSH_AUTH_SOCK_by}} to the process id of {{ic|gpg-agent}}, and the line above tests it for the process id of the {{ic|bash}} process.<br />
<br />
Therefore, <br />
<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)" <br />
<br />
will probably get executed every time. However, it most likely wouldn't break anything since at worst it will reset {{ic|SSH_AUTH_SOCK}} to the same value.<br />
<br />
{{Unsigned| 11:16, 1 May 2021 (UTC)|Thread13}}<br />
<br />
== Invalid IPC response and Inappropriate ioctl for device ==<br />
I solved this problem simply by removing an {{ic|#}} inside {{ic|/etc/pinentry/preexec}} enabling the desired option and then setting {{ic|/usr/bin/pinentry}} as default.<br />
[[User:Pavlov|Pavlov]] ([[User talk:Pavlov|talk]]) 15:19, 2 May 2021 (UTC)<br />
<br />
== Another suggestion for troubleshooting automatic key fetching from keyservers in case that SRV lookup fails ==<br />
<br />
If the port is not explicitly stated, than GnuPG will try to use a DNS lookup using SRV [1].<br />
This may fail due to various reasons, so troubleshooting will be to explicitly set the keyservers with the ports, e.g. in ~/.gnupg/dirmngr.conf (or where appropriate)<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com:80<br />
</code> instead of just<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com<br />
</code><br />
[1] https://dev.gnupg.org/rGc2cbe2f87c480c62239dc4c2cbb352acd98cd267<br />
--[[User:Tobias.predel|Tobias.predel]] ([[User talk:Tobias.predel|talk]]) 10:09, 10 June 2022 (UTC)<br />
<br />
== pgp.mit.edu is not resolving ==<br />
pgp.mit.edu is not resolving, but is used many times within this documenation. Anyone have an ideas on an alternative? [[User:Jahway603|Jahway603]] ([[User talk:Jahway603|talk]]) 17:11, 9 March 2023 (UTC)!<br />
<br />
:At the time of this writing, it is resolvable here as an alias (CNAME) to {{ic|cryptonomicon.mit.edu}}, with an address of 18.9.60.141. Can it be your query ignored the possibility for a CNAME record? [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:22, 24 January 2024 (UTC)<br />
<br />
== Deprecated --supervised option for gpg-agent ==<br />
<br />
As per https://dev.gnupg.org/T6336#166815, it seems as though {{ic|gpg-agent --supervised}}, and as such systemd-based activation altogether, is deprecated by GnuPG. What would the ideal startup method for gpg-agent be instead in that case?<br />
[[User:90|90]] ([[User talk:90|talk]]) 17:41, 6 June 2023 (UTC)<br />
<br />
:I'd like to drop-in Werner's initial [https://dev.gnupg.org/rGeae28f1bd4a5632e8f8e85b7248d1c4d4a10a5ed#78329 reply], and add the removal applied for >=2.4.1. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:48, 19 September 2023 (UTC)<br />
<br />
== What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]? ==<br />
<br />
I tested the gpg-agent forwarding and the OpenSSH {{ic|ForwardAgent yes}} options. I am able to forward the use of my gpg key on my hardware key with the former, but it doesn't work with the latter. [[User:Seodisparate|Seodisparate]] ([[User talk:Seodisparate|talk]]) 12:23, 24 June 2023 (UTC)<br />
<br />
== Global configuration files should have 644 permission ==<br />
<br />
Setting permission of global configuration files at <code>/etc/gnupg/</code> to <code>600</code> make them unreadable for user's GPG process and thus makes them '''completely ineffective''', unless user invoke <code>gpg</code> as root which is the owner of the files; which in turn is not the proper way to use the <code>gpg</code> command. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:30, 10 January 2024 (UTC)<br />
<br />
:I guess you are right, yet this looks to me irrelevant. It looks to me irrelevant since my understanding of [[GnuPG#Configuration]] is {{ic|0600}} is referring to files under {{ic|~/.gnupg/}}, not to files under {{ic|/etc/gnupg/}}. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:39, 24 January 2024 (UTC)<br />
<br />
== Global GPG config special flags ==<br />
<br />
<p>Even though not well documented, The global GPG config file (and other files in the <code>/etc/gnupg/</code> directory) can have 3 special flags.[https://dev.gnupg.org/T4788#132919]</p><br />
<p>They are <code>[force]</code>To enforce an option to system's gpg users, <code>[-force]</code> To force disable an option and <code>[ignore]</code> to ignore a flag if it is used by users.</p><br />
<p>These flags can't be used in the user's gnuhomedir config files, and are specific to global config files.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:21, 11 January 2024 (UTC)<br />
<br />
:<p>Care must be taken when setting system-wide options in <code>/etc/gnupg/</code> files; particularly, one has to be extra careful when using <code>[force]</code>,<code>[-force]</code> and <code>[ignore]</code> options.</p><br />
:<p>Any flag used in these files, will affect operation of all software programs which are using GPG internally, systemwide. Namely, <code>pacman-key</code>.</p><br />
:<p>As an example, changing <code>trust-model</code> option to any mode other than <code>pgp</code> in <code>/etc/gnupg/gpg.conf</code>, or setting <code>use-keyboxd</code> in <code>/etc/gnupg/common.conf</code> will stop <code>pacman-key</code> and consequently <code>pacman</code> from functioning properly.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 21:19, 12 January 2024 (UTC)<br />
<br />
== Three Outdated "See also" articles ==<br />
<br />
<p>Yesterday, I putted time reading additional documentations introduced in this section.</p><br />
<p>Three of them are pretty old, and their contents are not true (At least in details) or accurate any more.</p><br />
[https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]</br><br />
[https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]</br><br />
[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:37, 11 January 2024 (UTC)<br />
<br />
== Using new "keyboxd" for keyring instead of "pubring.kbx" ==<br />
<br />
<p>A section can be added to this article talking about it. Or, At least, it's good to be mentioned in some part of this document.</p><br />
<br />
<p>As per recommendation of GnuPG[https://github.com/gpg/gnupg/blob/6ddaf2be9f484eb7a38f2bda0bb70f2d7b4c4511/README#L119], one can use ''key database daemon'' (keyboxd), with SQLite database, instead of <code>keyring.kbx</code> file for storing public keys.</p><br />
<br />
<p>This is currently the default since version 2.4.1 and will be in effect for any fresh home directory.</br><br />
Also, this can be enabled with <code>use-keyboxd</code> option in the <code>common.conf</code> file (One has to be created if it does not exist yet.) for older home directories.</p> <br />
<p>For a fresh keyring, nothing needs to be done. But for a current keyring, they have to be imported to the new database.</p><br />
<p>Nevertheless, it's as simple as:<br />
<pre><br />
gpg --export --export-options backup > allkeys.gpg<br />
gpgsm --export --armor > allcerts.gpg<br />
</pre><br />
To export current public keys. And:<br />
<pre><br />
gpg --import --import-options restore < allkeys.gpg<br />
gpgsm --import < allcerts.crt<br />
</pre><br />
<p>To import them to the new keyboxd, then adding <code>use-keyboxd</code> option to the <code>common.conf</code> to enable the new keyring format.</p><br />
<p>However, It may not be compatible with software programs that expect GPG to have a <code>pubring.kbx</code> to import it.[https://github.com/microsoft/vscode-remote-release/issues/9217] Even though it can be created easily in a reverse process in case.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 01:39, 12 January 2024 (UTC)<br />
<br />
== Which keyserver or keyservers are recommeneded? ==<br />
<br />
Section 3.5.3 Keyservers mentions three keyservers, each with slightly different capabilities. I would find it helpful if a brief explanation (for keyserver novices) were included with a recommendation, of which ones to use, in what order, and why. [[User:Vgivanovic|vgivanovic]] ([[User talk:Vgivanovic|talk]]) 18:09, 15 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=798056Talk:GnuPG2024-01-24T11:39:21Z<p>Regid: /* Global configuration files should have 644 permission */ Reply</p>
<hr />
<div>== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=poldi.git poldi] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:27, 4 August 2016 (UTC)<br />
<br />
== User configuration files not created ==<br />
<br />
Per the wiki, it states, "You will find skeleton files in /usr/share/gnupg. These files are copied to ~/.gnupg the first time gpg is run if they do not exist there."<br />
<br />
I could very well be doing something wrong so I'd ask that this could be verified. If we need to copy skel configuration files, it should be clearly explained in the wiki shouldn't it?<br />
<br />
I was unable to import public keys until I manually created a blank ~/.gnupg/gpg.conf with just keyserver pgp.mit.edu in it. <br />
<br />
I also found this when searching for info, https://manned.org/gpgv2/2862e42d. It states: There are no configuration files and only a few options are implemented.<br />
<br />
[[User:NuSkool|NuSkool]] ([[User talk:NuSkool|talk]]) 04:09, 26 September 2016 (UTC)<br />
<br />
:On the same topic but on a different note, update [[GnuPG#Configuration_files]] to remove ''out of date warning'' and add the following informtion:<br />
:1) '''~/.gnupg/gpg.conf''' and '''~/.gnupg/dirmngr.conf''' are not created by default. So, the user can create them to implement the changes.<br />
:2) global config file is located at '''/etc/gnupg/gpgconf.conf''' shown by command '''gpgconf --list-config'''. This is also not created by default. The example file is <br />
:at '''/usr/share/doc/gnupg/examples/gpgconf.conf'''<br />
:--[[User:RaZorr|RaZorr]] ([[User talk:RaZorr|talk]]) 12:51, 16 January 2022 (UTC)<br />
<br />
:I've used gpg and I don't have the configuration files. The wiki is wrong. [[User:Pound Hash|Pound Hash]] ([[User talk:Pound Hash|talk]])<br />
<br />
:I am having difficulty corroborating the existence of this functionality. There is no "default" {{ic|gpg.conf}} in the GnuPG repository, and I'm not sure if it even makes sense to have one. This file is for ''overriding'' defaults. For instance, this is what mine looks like:<br />
{{hc|gnupg.conf|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
default-key ''default-key''<br />
}}<br />
:It shouldn't be a complicated configuration file, just command line options that you want to use all the time. {{ic|dirmngr.conf}} is exactly the same way, as far as I can tell. So, [[User:RaZorr|RaZorr]] got it totally right with 1). With 2), though, {{ic|/etc/gnupg/gpgconf.conf}} is actually not the global version of {{ic|~/.gnupg/gpg.conf}}. {{ic|/etc/gnupg/gpgconf.conf}} is a "legacy mechanism" for setting up defaults using the ''gpgconf'' progrma. The modern way for configuring system-wide GnuPG defaults is {{ic|~/.gnupg/gpg.conf}}'s ''actual'' global analog: {{ic|/etc/gnupg/gpg.conf}}, which was introduced in 2020 [https://dev.gnupg.org/T4788].<br />
:I gave a shot at fixing this part of the page. Thanks, [[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 08:21, 20 May 2022 (UTC)<br />
::I am trying to use <code>/etc/gnupg/gpg.conf</code> But seems like it is not respected by gpg at all. Doesn't matter what I put there, it just doesn't effect. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:06, 10 January 2024 (UTC)<br />
::The problem was from setting permission of <code>/etc/gnupg/</code> files to <code>600</code>, making them unreadable to user's <code>gpg</code>. Changing file permissions back to <code>644</code> resolved the issue.</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:43, 10 January 2024 (UTC)<br />
<br />
== Recommendation to add ==<br />
<br />
By default, no skeleton files exist (as mentioned above) but in my case the lack of a dirmngr.conf meant that any --recv-keys failed with useful(?) errors like "gpg: keyserver receive failed: Server indicated a failure" or "gpg: error searching keyserver: Server indicated a failure". Route to get here was via makepkg, and so I skipped all the installation steps etc since gpg was already installed and went straight for a recv.<br />
<br />
echo > $HOME/.gnupg/dirmngr.conf 'standard-resolver'<br />
[[User:Beepboo|Beepboo]] ([[User talk:Beepboo|talk]]) 17:09, 22 March 2020 (UTC)<br />
:also requires to restart dirmngr.service [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:32, 25 April 2022 (UTC)<br />
:but the problem is probably on the /etc/resolv.conf file. Are you using systemd-resolved ? Then check [[Systemd-resolved#DNS]] [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:46, 25 April 2022 (UTC)<br />
<br />
== A comment on provided code snippet ==<br />
<br />
The test from [[GnuPG#Set_SSH_AUTH_SOCK|Set_SSH_AUTH_SOCK]] : <br />
<br />
[ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]<br />
<br />
would probably always fail, since [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307] sets {{ic|gnupg_SSH_AUTH_SOCK_by}} to the process id of {{ic|gpg-agent}}, and the line above tests it for the process id of the {{ic|bash}} process.<br />
<br />
Therefore, <br />
<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)" <br />
<br />
will probably get executed every time. However, it most likely wouldn't break anything since at worst it will reset {{ic|SSH_AUTH_SOCK}} to the same value.<br />
<br />
{{Unsigned| 11:16, 1 May 2021 (UTC)|Thread13}}<br />
<br />
== Invalid IPC response and Inappropriate ioctl for device ==<br />
I solved this problem simply by removing an {{ic|#}} inside {{ic|/etc/pinentry/preexec}} enabling the desired option and then setting {{ic|/usr/bin/pinentry}} as default.<br />
[[User:Pavlov|Pavlov]] ([[User talk:Pavlov|talk]]) 15:19, 2 May 2021 (UTC)<br />
<br />
== Another suggestion for troubleshooting automatic key fetching from keyservers in case that SRV lookup fails ==<br />
<br />
If the port is not explicitly stated, than GnuPG will try to use a DNS lookup using SRV [1].<br />
This may fail due to various reasons, so troubleshooting will be to explicitly set the keyservers with the ports, e.g. in ~/.gnupg/dirmngr.conf (or where appropriate)<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com:80<br />
</code> instead of just<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com<br />
</code><br />
[1] https://dev.gnupg.org/rGc2cbe2f87c480c62239dc4c2cbb352acd98cd267<br />
--[[User:Tobias.predel|Tobias.predel]] ([[User talk:Tobias.predel|talk]]) 10:09, 10 June 2022 (UTC)<br />
<br />
== pgp.mit.edu is not resolving ==<br />
pgp.mit.edu is not resolving, but is used many times within this documenation. Anyone have an ideas on an alternative? [[User:Jahway603|Jahway603]] ([[User talk:Jahway603|talk]]) 17:11, 9 March 2023 (UTC)!<br />
<br />
:At the time of this writing, it is resolvable here as an alias (CNAME) to {{ic|cryptonomicon.mit.edu}}, with an address of 18.9.60.141. Can it be your query ignored the possibility for a CNAME record? [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:22, 24 January 2024 (UTC)<br />
<br />
== Deprecated --supervised option for gpg-agent ==<br />
<br />
As per https://dev.gnupg.org/T6336#166815, it seems as though {{ic|gpg-agent --supervised}}, and as such systemd-based activation altogether, is deprecated by GnuPG. What would the ideal startup method for gpg-agent be instead in that case?<br />
[[User:90|90]] ([[User talk:90|talk]]) 17:41, 6 June 2023 (UTC)<br />
<br />
:I'd like to drop-in Werner's initial [https://dev.gnupg.org/rGeae28f1bd4a5632e8f8e85b7248d1c4d4a10a5ed#78329 reply], and add the removal applied for >=2.4.1. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:48, 19 September 2023 (UTC)<br />
<br />
== What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]? ==<br />
<br />
I tested the gpg-agent forwarding and the OpenSSH {{ic|ForwardAgent yes}} options. I am able to forward the use of my gpg key on my hardware key with the former, but it doesn't work with the latter. [[User:Seodisparate|Seodisparate]] ([[User talk:Seodisparate|talk]]) 12:23, 24 June 2023 (UTC)<br />
<br />
== Global configuration files should have 644 permission ==<br />
<br />
Setting permission of global configuration files at <code>/etc/gnupg/</code> to <code>600</code> make them unreadable for user's GPG process and thus makes them '''completely ineffective''', unless user invoke <code>gpg</code> as root which is the owner of the files; which in turn is not the proper way to use the <code>gpg</code> command. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:30, 10 January 2024 (UTC)<br />
<br />
:I guess you are right, yet this looks to me irrelevant. It looks to me irrelevant since my understanding of [[gnupg#configuration]] is {{ic|0600}} is referring to files under {{ic|~/.gnupg/}}, not to files under {{ic|/etc/gnupg/}}. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:39, 24 January 2024 (UTC)<br />
<br />
== Global GPG config special flags ==<br />
<br />
<p>Even though not well documented, The global GPG config file (and other files in the <code>/etc/gnupg/</code> directory) can have 3 special flags.[https://dev.gnupg.org/T4788#132919]</p><br />
<p>They are <code>[force]</code>To enforce an option to system's gpg users, <code>[-force]</code> To force disable an option and <code>[ignore]</code> to ignore a flag if it is used by users.</p><br />
<p>These flags can't be used in the user's gnuhomedir config files, and are specific to global config files.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:21, 11 January 2024 (UTC)<br />
<br />
:<p>Care must be taken when setting system-wide options in <code>/etc/gnupg/</code> files; particularly, one has to be extra careful when using <code>[force]</code>,<code>[-force]</code> and <code>[ignore]</code> options.</p><br />
:<p>Any flag used in these files, will affect operation of all software programs which are using GPG internally, systemwide. Namely, <code>pacman-key</code>.</p><br />
:<p>As an example, changing <code>trust-model</code> option to any mode other than <code>pgp</code> in <code>/etc/gnupg/gpg.conf</code>, or setting <code>use-keyboxd</code> in <code>/etc/gnupg/common.conf</code> will stop <code>pacman-key</code> and consequently <code>pacman</code> from functioning properly.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 21:19, 12 January 2024 (UTC)<br />
<br />
== Three Outdated "See also" articles ==<br />
<br />
<p>Yesterday, I putted time reading additional documentations introduced in this section.</p><br />
<p>Three of them are pretty old, and their contents are not true (At least in details) or accurate any more.</p><br />
[https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]</br><br />
[https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]</br><br />
[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:37, 11 January 2024 (UTC)<br />
<br />
== Using new "keyboxd" for keyring instead of "pubring.kbx" ==<br />
<br />
<p>A section can be added to this article talking about it. Or, At least, it's good to be mentioned in some part of this document.</p><br />
<br />
<p>As per recommendation of GnuPG[https://github.com/gpg/gnupg/blob/6ddaf2be9f484eb7a38f2bda0bb70f2d7b4c4511/README#L119], one can use ''key database daemon'' (keyboxd), with SQLite database, instead of <code>keyring.kbx</code> file for storing public keys.</p><br />
<br />
<p>This is currently the default since version 2.4.1 and will be in effect for any fresh home directory.</br><br />
Also, this can be enabled with <code>use-keyboxd</code> option in the <code>common.conf</code> file (One has to be created if it does not exist yet.) for older home directories.</p> <br />
<p>For a fresh keyring, nothing needs to be done. But for a current keyring, they have to be imported to the new database.</p><br />
<p>Nevertheless, it's as simple as:<br />
<pre><br />
gpg --export --export-options backup > allkeys.gpg<br />
gpgsm --export --armor > allcerts.gpg<br />
</pre><br />
To export current public keys. And:<br />
<pre><br />
gpg --import --import-options restore < allkeys.gpg<br />
gpgsm --import < allcerts.crt<br />
</pre><br />
<p>To import them to the new keyboxd, then adding <code>use-keyboxd</code> option to the <code>common.conf</code> to enable the new keyring format.</p><br />
<p>However, It may not be compatible with software programs that expect GPG to have a <code>pubring.kbx</code> to import it.[https://github.com/microsoft/vscode-remote-release/issues/9217] Even though it can be created easily in a reverse process in case.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 01:39, 12 January 2024 (UTC)<br />
<br />
== Which keyserver or keyservers are recommeneded? ==<br />
<br />
Section 3.5.3 Keyservers mentions three keyservers, each with slightly different capabilities. I would find it helpful if a brief explanation (for keyserver novices) were included with a recommendation, of which ones to use, in what order, and why. [[User:Vgivanovic|vgivanovic]] ([[User talk:Vgivanovic|talk]]) 18:09, 15 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:GnuPG&diff=798055Talk:GnuPG2024-01-24T11:22:37Z<p>Regid: /* pgp.mit.edu is not resolving */ Reply</p>
<hr />
<div>== System login with gnupg smartcard (yubikey, p-card, rsa token, etc) ==<br />
gnupg with [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=poldi.git poldi] can be used for system login. There is a [https://bbs.archlinux.org/viewtopic.php?id=215554 thread] asking whether it is possible to use gpg for system login.<br />
A new tip section explaining gnupg smartcard for logging into Arch Linux system is a nice addition here.<br />
<br />
[[User:Alive4ever|Alive4ever]] ([[User talk:Alive4ever|talk]]) 02:27, 4 August 2016 (UTC)<br />
<br />
== User configuration files not created ==<br />
<br />
Per the wiki, it states, "You will find skeleton files in /usr/share/gnupg. These files are copied to ~/.gnupg the first time gpg is run if they do not exist there."<br />
<br />
I could very well be doing something wrong so I'd ask that this could be verified. If we need to copy skel configuration files, it should be clearly explained in the wiki shouldn't it?<br />
<br />
I was unable to import public keys until I manually created a blank ~/.gnupg/gpg.conf with just keyserver pgp.mit.edu in it. <br />
<br />
I also found this when searching for info, https://manned.org/gpgv2/2862e42d. It states: There are no configuration files and only a few options are implemented.<br />
<br />
[[User:NuSkool|NuSkool]] ([[User talk:NuSkool|talk]]) 04:09, 26 September 2016 (UTC)<br />
<br />
:On the same topic but on a different note, update [[GnuPG#Configuration_files]] to remove ''out of date warning'' and add the following informtion:<br />
:1) '''~/.gnupg/gpg.conf''' and '''~/.gnupg/dirmngr.conf''' are not created by default. So, the user can create them to implement the changes.<br />
:2) global config file is located at '''/etc/gnupg/gpgconf.conf''' shown by command '''gpgconf --list-config'''. This is also not created by default. The example file is <br />
:at '''/usr/share/doc/gnupg/examples/gpgconf.conf'''<br />
:--[[User:RaZorr|RaZorr]] ([[User talk:RaZorr|talk]]) 12:51, 16 January 2022 (UTC)<br />
<br />
:I've used gpg and I don't have the configuration files. The wiki is wrong. [[User:Pound Hash|Pound Hash]] ([[User talk:Pound Hash|talk]])<br />
<br />
:I am having difficulty corroborating the existence of this functionality. There is no "default" {{ic|gpg.conf}} in the GnuPG repository, and I'm not sure if it even makes sense to have one. This file is for ''overriding'' defaults. For instance, this is what mine looks like:<br />
{{hc|gnupg.conf|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
default-key ''default-key''<br />
}}<br />
:It shouldn't be a complicated configuration file, just command line options that you want to use all the time. {{ic|dirmngr.conf}} is exactly the same way, as far as I can tell. So, [[User:RaZorr|RaZorr]] got it totally right with 1). With 2), though, {{ic|/etc/gnupg/gpgconf.conf}} is actually not the global version of {{ic|~/.gnupg/gpg.conf}}. {{ic|/etc/gnupg/gpgconf.conf}} is a "legacy mechanism" for setting up defaults using the ''gpgconf'' progrma. The modern way for configuring system-wide GnuPG defaults is {{ic|~/.gnupg/gpg.conf}}'s ''actual'' global analog: {{ic|/etc/gnupg/gpg.conf}}, which was introduced in 2020 [https://dev.gnupg.org/T4788].<br />
:I gave a shot at fixing this part of the page. Thanks, [[User:CodingKoopa|CodingKoopa]] ([[User talk:CodingKoopa|talk]]) 08:21, 20 May 2022 (UTC)<br />
::I am trying to use <code>/etc/gnupg/gpg.conf</code> But seems like it is not respected by gpg at all. Doesn't matter what I put there, it just doesn't effect. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:06, 10 January 2024 (UTC)<br />
::The problem was from setting permission of <code>/etc/gnupg/</code> files to <code>600</code>, making them unreadable to user's <code>gpg</code>. Changing file permissions back to <code>644</code> resolved the issue.</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:43, 10 January 2024 (UTC)<br />
<br />
== Recommendation to add ==<br />
<br />
By default, no skeleton files exist (as mentioned above) but in my case the lack of a dirmngr.conf meant that any --recv-keys failed with useful(?) errors like "gpg: keyserver receive failed: Server indicated a failure" or "gpg: error searching keyserver: Server indicated a failure". Route to get here was via makepkg, and so I skipped all the installation steps etc since gpg was already installed and went straight for a recv.<br />
<br />
echo > $HOME/.gnupg/dirmngr.conf 'standard-resolver'<br />
[[User:Beepboo|Beepboo]] ([[User talk:Beepboo|talk]]) 17:09, 22 March 2020 (UTC)<br />
:also requires to restart dirmngr.service [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:32, 25 April 2022 (UTC)<br />
:but the problem is probably on the /etc/resolv.conf file. Are you using systemd-resolved ? Then check [[Systemd-resolved#DNS]] [[User:Louson|Louson]] ([[User talk:Louson|talk]]) 13:46, 25 April 2022 (UTC)<br />
<br />
== A comment on provided code snippet ==<br />
<br />
The test from [[GnuPG#Set_SSH_AUTH_SOCK|Set_SSH_AUTH_SOCK]] : <br />
<br />
[ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]<br />
<br />
would probably always fail, since [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307] sets {{ic|gnupg_SSH_AUTH_SOCK_by}} to the process id of {{ic|gpg-agent}}, and the line above tests it for the process id of the {{ic|bash}} process.<br />
<br />
Therefore, <br />
<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)" <br />
<br />
will probably get executed every time. However, it most likely wouldn't break anything since at worst it will reset {{ic|SSH_AUTH_SOCK}} to the same value.<br />
<br />
{{Unsigned| 11:16, 1 May 2021 (UTC)|Thread13}}<br />
<br />
== Invalid IPC response and Inappropriate ioctl for device ==<br />
I solved this problem simply by removing an {{ic|#}} inside {{ic|/etc/pinentry/preexec}} enabling the desired option and then setting {{ic|/usr/bin/pinentry}} as default.<br />
[[User:Pavlov|Pavlov]] ([[User talk:Pavlov|talk]]) 15:19, 2 May 2021 (UTC)<br />
<br />
== Another suggestion for troubleshooting automatic key fetching from keyservers in case that SRV lookup fails ==<br />
<br />
If the port is not explicitly stated, than GnuPG will try to use a DNS lookup using SRV [1].<br />
This may fail due to various reasons, so troubleshooting will be to explicitly set the keyservers with the ports, e.g. in ~/.gnupg/dirmngr.conf (or where appropriate)<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com:80<br />
</code> instead of just<br />
<code><br />
keyserver hkps://keyserver.ubuntu.com<br />
</code><br />
[1] https://dev.gnupg.org/rGc2cbe2f87c480c62239dc4c2cbb352acd98cd267<br />
--[[User:Tobias.predel|Tobias.predel]] ([[User talk:Tobias.predel|talk]]) 10:09, 10 June 2022 (UTC)<br />
<br />
== pgp.mit.edu is not resolving ==<br />
pgp.mit.edu is not resolving, but is used many times within this documenation. Anyone have an ideas on an alternative? [[User:Jahway603|Jahway603]] ([[User talk:Jahway603|talk]]) 17:11, 9 March 2023 (UTC)!<br />
<br />
:At the time of this writing, it is resolvable here as an alias (CNAME) to {{ic|cryptonomicon.mit.edu}}, with an address of 18.9.60.141. Can it be your query ignored the possibility for a CNAME record? [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 11:22, 24 January 2024 (UTC)<br />
<br />
== Deprecated --supervised option for gpg-agent ==<br />
<br />
As per https://dev.gnupg.org/T6336#166815, it seems as though {{ic|gpg-agent --supervised}}, and as such systemd-based activation altogether, is deprecated by GnuPG. What would the ideal startup method for gpg-agent be instead in that case?<br />
[[User:90|90]] ([[User talk:90|talk]]) 17:41, 6 June 2023 (UTC)<br />
<br />
:I'd like to drop-in Werner's initial [https://dev.gnupg.org/rGeae28f1bd4a5632e8f8e85b7248d1c4d4a10a5ed#78329 reply], and add the removal applied for >=2.4.1. --[[User:Indigo|Indigo]] ([[User talk:Indigo|talk]]) 18:48, 19 September 2023 (UTC)<br />
<br />
== What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]? ==<br />
<br />
I tested the gpg-agent forwarding and the OpenSSH {{ic|ForwardAgent yes}} options. I am able to forward the use of my gpg key on my hardware key with the former, but it doesn't work with the latter. [[User:Seodisparate|Seodisparate]] ([[User talk:Seodisparate|talk]]) 12:23, 24 June 2023 (UTC)<br />
<br />
== Global configuration files should have 644 permission ==<br />
<br />
Setting permission of global configuration files at <code>/etc/gnupg/</code> to <code>600</code> make them unreadable for user's GPG process and thus makes them '''completely ineffective''', unless user invoke <code>gpg</code> as root which is the owner of the files; which in turn is not the proper way to use the <code>gpg</code> command. [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 18:30, 10 January 2024 (UTC)<br />
<br />
== Global GPG config special flags ==<br />
<br />
<p>Even though not well documented, The global GPG config file (and other files in the <code>/etc/gnupg/</code> directory) can have 3 special flags.[https://dev.gnupg.org/T4788#132919]</p><br />
<p>They are <code>[force]</code>To enforce an option to system's gpg users, <code>[-force]</code> To force disable an option and <code>[ignore]</code> to ignore a flag if it is used by users.</p><br />
<p>These flags can't be used in the user's gnuhomedir config files, and are specific to global config files.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:21, 11 January 2024 (UTC)<br />
<br />
:<p>Care must be taken when setting system-wide options in <code>/etc/gnupg/</code> files; particularly, one has to be extra careful when using <code>[force]</code>,<code>[-force]</code> and <code>[ignore]</code> options.</p><br />
:<p>Any flag used in these files, will affect operation of all software programs which are using GPG internally, systemwide. Namely, <code>pacman-key</code>.</p><br />
:<p>As an example, changing <code>trust-model</code> option to any mode other than <code>pgp</code> in <code>/etc/gnupg/gpg.conf</code>, or setting <code>use-keyboxd</code> in <code>/etc/gnupg/common.conf</code> will stop <code>pacman-key</code> and consequently <code>pacman</code> from functioning properly.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 21:19, 12 January 2024 (UTC)<br />
<br />
== Three Outdated "See also" articles ==<br />
<br />
<p>Yesterday, I putted time reading additional documentations introduced in this section.</p><br />
<p>Three of them are pretty old, and their contents are not true (At least in details) or accurate any more.</p><br />
[https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]</br><br />
[https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]</br><br />
[https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]</br> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:37, 11 January 2024 (UTC)<br />
<br />
== Using new "keyboxd" for keyring instead of "pubring.kbx" ==<br />
<br />
<p>A section can be added to this article talking about it. Or, At least, it's good to be mentioned in some part of this document.</p><br />
<br />
<p>As per recommendation of GnuPG[https://github.com/gpg/gnupg/blob/6ddaf2be9f484eb7a38f2bda0bb70f2d7b4c4511/README#L119], one can use ''key database daemon'' (keyboxd), with SQLite database, instead of <code>keyring.kbx</code> file for storing public keys.</p><br />
<br />
<p>This is currently the default since version 2.4.1 and will be in effect for any fresh home directory.</br><br />
Also, this can be enabled with <code>use-keyboxd</code> option in the <code>common.conf</code> file (One has to be created if it does not exist yet.) for older home directories.</p> <br />
<p>For a fresh keyring, nothing needs to be done. But for a current keyring, they have to be imported to the new database.</p><br />
<p>Nevertheless, it's as simple as:<br />
<pre><br />
gpg --export --export-options backup > allkeys.gpg<br />
gpgsm --export --armor > allcerts.gpg<br />
</pre><br />
To export current public keys. And:<br />
<pre><br />
gpg --import --import-options restore < allkeys.gpg<br />
gpgsm --import < allcerts.crt<br />
</pre><br />
<p>To import them to the new keyboxd, then adding <code>use-keyboxd</code> option to the <code>common.conf</code> to enable the new keyring format.</p><br />
<p>However, It may not be compatible with software programs that expect GPG to have a <code>pubring.kbx</code> to import it.[https://github.com/microsoft/vscode-remote-release/issues/9217] Even though it can be created easily in a reverse process in case.</p> [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 01:39, 12 January 2024 (UTC)<br />
<br />
== Which keyserver or keyservers are recommeneded? ==<br />
<br />
Section 3.5.3 Keyservers mentions three keyservers, each with slightly different capabilities. I would find it helpful if a brief explanation (for keyserver novices) were included with a recommendation, of which ones to use, in what order, and why. [[User:Vgivanovic|vgivanovic]] ([[User talk:Vgivanovic|talk]]) 18:09, 15 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=798019GnuPG2024-01-24T01:25:37Z<p>Regid: /* Signatures */ Change looks to me clearer and more accurate</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:OpenPGP]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/dir''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Warning| When using {{ic|--full-gen-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular some newer [[Wikipedia:Elliptic-curve cryptography|elliptic curves]] like [[Wikipedia:Curve448|Curve448]].<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''ECC (sign and encrypt)'' for signing and encryption keys.<br />
* The default ''Curve 25519'' to use [[Wikipedia:Curve25519|Curve25519]] and [[Wikipedia:Ed25519|Ed25519]].<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public-key''.asc}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public-key''.asc ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your {{ic|gpg.conf}}.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use OpenPGP with external GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public-key''.asc}} to your public key ring:<br />
<br />
$ gpg --import ''public-key''.asc<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|There are keyserver where submitted keys cannot be deleted. Some of the reasons are explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --receive-keys ''key-id''<br />
<br />
To refresh/update the keychain with the latest version from a key server:<br />
<br />
$ gpg --refresh-keys<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to the [[#Configuration files|GPG configuration file]] will automatically fetch keys from the key server as needed. This is not a compromise on security, but it can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg|auto-key-retrieve}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver ''hkps://keys.openpgp.org/'' --search-keys ''user-id''<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<br />
* If connecting to a keyserver fails with {{ic|gpg: keyserver receive failed: Server indicated a failure}}, you may need to configure gpg to use an alternate port. For example, to use port 80 on Ubuntu's keyserver, use {{ic|keyserver hkp://keyserver.ubuntu.com:80}}.<br />
}}<br />
<br />
=== Web Key Directory ===<br />
<br />
{{Move| OpenPGP | Although the Web Key Directory (WKD) is an IETF draft by gnupg author Werner Koch, it is relevant for all implementations of [[OpenPGP]] and in fact already used by some.}}<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''private-key''.asc ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''private-key''.asc<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert''.asc ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.asc<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.asc<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.asc<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.asc}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver ''pgp.mit.edu'' --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert''.asc<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses the recipient public key to encrypt a document, signatures are created with the sender's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
{{Expansion|Document {{ic|keyboxd.socket}} and {{ic|keyboxd.service}}.[https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/commit/1551c66631a28501a677d16d5fef9a37fadf2b95]}}<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] the {{ic|ListenStream}} (see {{man|5|systemd.socket|options}}) of all the socket files to be consistent with {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
<br />
It is necessary to allow this passphrase presetting by starting gpg-agent with the {{ic|--allow-preset-passphrase}} or setting {{ic|allow-preset-passphrase}} in {{ic|~/.gnupg/gpg-agent.conf}}.<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/}}. You may need to install the relevant [[pacman#Installing packages|optional dependencies]] for your chosen pinentry program.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* The pinentry programs {{ic|/usr/bin/pinentry-gnome3}} (GNOME) and {{ic|/usr/bin/pinentry-gtk-2}} (generic) [https://avaldes.co/2020/01/28/secret-service-keepassxc.html] support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]], [[KeePass#Secret Service|KeePassXC]] or [[KDE Wallet]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disabling|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
=== Forwarding gpg-agent and ssh-agent to remote ===<br />
<br />
{{Expansion|What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]?}}<br />
<br />
It is possible to forward one's gpg-agent to a remote machine by forwarding gpg sockets to the remote machine, as explained by the [https://wiki.gnupg.org/AgentForwarding GnuPG wiki].<br />
<br />
First, add the following line to {{ic|/etc/ssh/sshd_config}} on the remote machine to enable automatic removal of stale sockets on connect. Without this, the socket(s) on the remote machine will need to removed manually before connecting with forwarding enabled for agent forwarding to work:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
StreamLocalBindUnlink yes<br />
...<br />
}}<br />
<br />
{{Note|You will have to [[reload]] {{ic|sshd.service}} on the remote machine for the new configuration to be loaded by sshd.}}<br />
<br />
On the client, use the {{ic|RemoteForward}} SSH directive to forward traffic destined for a remote port, to a port on your local host. As described in {{Man|5|ssh_config|RemoteForward}}, this directive's parameters are the listening socket path on the remote, and then the destination socket path on the local host. Your configuration should look something like this:<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''remote_name''<br />
...<br />
RemoteForward ''remote_agent_socket'' ''local_agent_extra_socket''<br />
RemoteForward ''remote_agent_ssh_socket'' ''local_agent_ssh_socket''<br />
}}<br />
<br />
The first line configures gpg-agent forwarding:<br />
<br />
* ''remote_agent_socket'' is the output of {{ic|gpgconf --list-dir agent-socket}} on the remote host.<br />
* ''local_agent_extra_socket'' is {{ic|gpgconf --list-dir agent-extra-socket}} on the local host.<br />
<br />
The second line is optional. It configures ssh-agent forwarding:<br />
<br />
* ''local_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the remote host.<br />
* ''remote_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the local host.<br />
<br />
{{Note|If using ssh-agent forwarding, the remote should have {{ic|SSH_AUTH_SOCK}} set to the output of {{ic|gpgconf --list-dir agent-ssh-socket}} as mentioned in [[#SSH agent]]).}}<br />
<br />
So, with the default paths, it would be:<br />
<br />
{{bc|<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh<br />
}}<br />
<br />
With this configuration in place, invoking {{ic|ssh ''remote_name''}} should automatically forward the gpg-agent to the remote, and allow the use of your gpg key(s) for both decryption/signing (and allows the use of ssh-agent with gpg if the second {{ic|RemoteForward}} line is included).<br />
<br />
== Smartcards ==<br />
<br />
{{Expansion|GnuPG 2.3+ has a {{man|1|gpg-card}} tool.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). In earlier versions, if GnuPG's scdaemon failed to connect to the smartcard directly (e.g. by using its integrated CCID support), it fell back and tried to find a smartcard using the PCSC Lite driver. [https://dev.gnupg.org/rG6b93b92111cb8ce6d06c6f71bd62cfb314663b8c Since version 2.4] however, you will have to add the {{Ic|disable-ccid}} option in {{ic|~/.gnupg/scdaemon.conf}}, to be able to use pcscd.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
===== Using a smart card on a remote client via SSH =====<br />
<br />
If you log into a machine via SSH and try to use an attached device via pcscd, you will notice errors such as:<br />
<br />
gpg: selecting card failed: No such device<br />
gpg: OpenPGP card not available: No such device<br />
<br />
This is due to [[Polkit]] restricting access to local clients. To fix this, you can add a rule to allow certain users in all cases. The below rule allows all users in the {{ic|wheel}} group to access devices via {{ic|pcscd}}:<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-pcscd.rules|2=<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_card" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_pcsc" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
After creating the file, make sure to [[restart]] {{ic|polkit.service}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable unsupported AEAD mechanism ===<br />
<br />
With {{pkg|gnupg}} 2.4, {{ic|gpg}} generates keys, which advertise support for a GnuPG specific [[Wikipedia:Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) | AEAD]] encryption mechanism (based on [[Wikipedia:OCB_mode | OCB]]). However, this flavor of AEAD is not supported by other [[OpenPGP]] implementations!<br />
<br />
Although many downstreams attempt to remove this new default by [https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/blob/cfc8f931ee3167a3673b249018dbba527d7428f8/gnupg-2.4-revert_default_rfc4880bis.patch patching the GnuPG sources], when using {{ic|--full-gen-key}} the OCB based custom AEAD encryption mechanism is nonetheless set for the new key.<br />
<br />
Whether GnuPG's custom AEAD is set for a key can be inspected with the help of {{ic|gpg}} itself:<br />
<br />
$ gpg --expert --edit-key ''<FINGERPRINT>''<br />
gpg> showpref<br />
[ultimate] (1). Foobar McFooface (test) <foobar@mcfooface.com><br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD: '''OCB'''<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, '''AEAD''', Keyserver no-modify<br />
<br />
This mechanism can be disabled:<br />
<br />
gpg> setpref AES256 AES192 AES SHA512 SHA384 SHA256 SHA224 ZLIB BZIP2 ZIP<br />
Set preference list to:<br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD:<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, Keyserver no-modify<br />
Really update the preferences? (y/N) y<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis (i.e. using a little social engineering, anyone who is able to decrypt the message can check whether one of the other recipients is the one they suspect). On the receiving side, it may slow down the decryption process because all available secret keys must be tried (e.g. with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
{{Warning| When using {{ic|--full-generate-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<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 />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disabling]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
=== Keyblock resource does not exist ===<br />
<br />
If you get an error like this when trying to import keys<br />
<br />
gpg: keyblock resource '''gnupg_home''/pubring.kbx': No such file or directory<br />
<br />
it is because GnuPG will not create its home directory if it does not yet exist. Simply create it manually<br />
<br />
$ mkdir -m 700 ''gnupg_home''<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Regidhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=797859GnuPG2024-01-22T19:12:57Z<p>Regid: /* Key servers */ [https://keys.openpgp.org/manage] has a statement for this at the main frame</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:OpenPGP]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/dir''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Warning| When using {{ic|--full-gen-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular some newer [[Wikipedia:Elliptic-curve cryptography|elliptic curves]] like [[Wikipedia:Curve448|Curve448]].<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''ECC (sign and encrypt)'' for signing and encryption keys.<br />
* The default ''Curve 25519'' to use [[Wikipedia:Curve25519|Curve25519]] and [[Wikipedia:Ed25519|Ed25519]].<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public-key''.asc}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public-key''.asc ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your {{ic|gpg.conf}}.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use OpenPGP with external GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public-key''.asc}} to your public key ring:<br />
<br />
$ gpg --import ''public-key''.asc<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|There are keyserver where submitted keys cannot be deleted. Some of the reasons are explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --receive-keys ''key-id''<br />
<br />
To refresh/update the keychain with the latest version from a key server:<br />
<br />
$ gpg --refresh-keys<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to the [[#Configuration files|GPG configuration file]] will automatically fetch keys from the key server as needed. This is not a compromise on security, but it can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg|auto-key-retrieve}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver ''hkps://keys.openpgp.org/'' --search-keys ''user-id''<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<br />
* If connecting to a keyserver fails with {{ic|gpg: keyserver receive failed: Server indicated a failure}}, you may need to configure gpg to use an alternate port. For example, to use port 80 on Ubuntu's keyserver, use {{ic|keyserver hkp://keyserver.ubuntu.com:80}}.<br />
}}<br />
<br />
=== Web Key Directory ===<br />
<br />
{{Move| OpenPGP | Although the Web Key Directory (WKD) is an IETF draft by gnupg author Werner Koch, it is relevant for all implementations of [[OpenPGP]] and in fact already used by some.}}<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''private-key''.asc ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''private-key''.asc<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert''.asc ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.asc<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.asc<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.asc<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.asc}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver ''pgp.mit.edu'' --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert''.asc<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
{{Expansion|Document {{ic|keyboxd.socket}} and {{ic|keyboxd.service}}.[https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/commit/1551c66631a28501a677d16d5fef9a37fadf2b95]}}<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] the {{ic|ListenStream}} (see {{man|5|systemd.socket|options}}) of all the socket files to be consistent with {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
<br />
It is necessary to allow this passphrase presetting by starting gpg-agent with the {{ic|--allow-preset-passphrase}} or setting {{ic|allow-preset-passphrase}} in {{ic|~/.gnupg/gpg-agent.conf}}.<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/}}. You may need to install the relevant [[pacman#Installing packages|optional dependencies]] for your chosen pinentry program.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* The pinentry programs {{ic|/usr/bin/pinentry-gnome3}} (GNOME) and {{ic|/usr/bin/pinentry-gtk-2}} (generic) [https://avaldes.co/2020/01/28/secret-service-keepassxc.html] support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]], [[KeePass#Secret Service|KeePassXC]] or [[KDE Wallet]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disabling|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
=== Forwarding gpg-agent and ssh-agent to remote ===<br />
<br />
{{Expansion|What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]?}}<br />
<br />
It is possible to forward one's gpg-agent to a remote machine by forwarding gpg sockets to the remote machine, as explained by the [https://wiki.gnupg.org/AgentForwarding GnuPG wiki].<br />
<br />
First, add the following line to {{ic|/etc/ssh/sshd_config}} on the remote machine to enable automatic removal of stale sockets on connect. Without this, the socket(s) on the remote machine will need to removed manually before connecting with forwarding enabled for agent forwarding to work:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
StreamLocalBindUnlink yes<br />
...<br />
}}<br />
<br />
{{Note|You will have to [[reload]] {{ic|sshd.service}} on the remote machine for the new configuration to be loaded by sshd.}}<br />
<br />
On the client, use the {{ic|RemoteForward}} SSH directive to forward traffic destined for a remote port, to a port on your local host. As described in {{Man|5|ssh_config|RemoteForward}}, this directive's parameters are the listening socket path on the remote, and then the destination socket path on the local host. Your configuration should look something like this:<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''remote_name''<br />
...<br />
RemoteForward ''remote_agent_socket'' ''local_agent_extra_socket''<br />
RemoteForward ''remote_agent_ssh_socket'' ''local_agent_ssh_socket''<br />
}}<br />
<br />
The first line configures gpg-agent forwarding:<br />
<br />
* ''remote_agent_socket'' is the output of {{ic|gpgconf --list-dir agent-socket}} on the remote host.<br />
* ''local_agent_extra_socket'' is {{ic|gpgconf --list-dir agent-extra-socket}} on the local host.<br />
<br />
The second line is optional. It configures ssh-agent forwarding:<br />
<br />
* ''local_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the remote host.<br />
* ''remote_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the local host.<br />
<br />
{{Note|If using ssh-agent forwarding, the remote should have {{ic|SSH_AUTH_SOCK}} set to the output of {{ic|gpgconf --list-dir agent-ssh-socket}} as mentioned in [[#SSH agent]]).}}<br />
<br />
So, with the default paths, it would be:<br />
<br />
{{bc|<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh<br />
}}<br />
<br />
With this configuration in place, invoking {{ic|ssh ''remote_name''}} should automatically forward the gpg-agent to the remote, and allow the use of your gpg key(s) for both decryption/signing (and allows the use of ssh-agent with gpg if the second {{ic|RemoteForward}} line is included).<br />
<br />
== Smartcards ==<br />
<br />
{{Expansion|GnuPG 2.3+ has a {{man|1|gpg-card}} tool.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). In earlier versions, if GnuPG's scdaemon failed to connect to the smartcard directly (e.g. by using its integrated CCID support), it fell back and tried to find a smartcard using the PCSC Lite driver. [https://dev.gnupg.org/rG6b93b92111cb8ce6d06c6f71bd62cfb314663b8c Since version 2.4] however, you will have to add the {{Ic|disable-ccid}} option in {{ic|~/.gnupg/scdaemon.conf}}, to be able to use pcscd.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
===== Using a smart card on a remote client via SSH =====<br />
<br />
If you log into a machine via SSH and try to use an attached device via pcscd, you will notice errors such as:<br />
<br />
gpg: selecting card failed: No such device<br />
gpg: OpenPGP card not available: No such device<br />
<br />
This is due to [[Polkit]] restricting access to local clients. To fix this, you can add a rule to allow certain users in all cases. The below rule allows all users in the {{ic|wheel}} group to access devices via {{ic|pcscd}}:<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-pcscd.rules|2=<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_card" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_pcsc" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
After creating the file, make sure to [[restart]] {{ic|polkit.service}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable unsupported AEAD mechanism ===<br />
<br />
With {{pkg|gnupg}} 2.4, {{ic|gpg}} generates keys, which advertise support for a GnuPG specific [[Wikipedia:Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) | AEAD]] encryption mechanism (based on [[Wikipedia:OCB_mode | OCB]]). However, this flavor of AEAD is not supported by other [[OpenPGP]] implementations!<br />
<br />
Although many downstreams attempt to remove this new default by [https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/blob/cfc8f931ee3167a3673b249018dbba527d7428f8/gnupg-2.4-revert_default_rfc4880bis.patch patching the GnuPG sources], when using {{ic|--full-gen-key}} the OCB based custom AEAD encryption mechanism is nonetheless set for the new key.<br />
<br />
Whether GnuPG's custom AEAD is set for a key can be inspected with the help of {{ic|gpg}} itself:<br />
<br />
$ gpg --expert --edit-key ''<FINGERPRINT>''<br />
gpg> showpref<br />
[ultimate] (1). Foobar McFooface (test) <foobar@mcfooface.com><br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD: '''OCB'''<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, '''AEAD''', Keyserver no-modify<br />
<br />
This mechanism can be disabled:<br />
<br />
gpg> setpref AES256 AES192 AES SHA512 SHA384 SHA256 SHA224 ZLIB BZIP2 ZIP<br />
Set preference list to:<br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD:<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, Keyserver no-modify<br />
Really update the preferences? (y/N) y<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis (i.e. using a little social engineering, anyone who is able to decrypt the message can check whether one of the other recipients is the one they suspect). On the receiving side, it may slow down the decryption process because all available secret keys must be tried (e.g. with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
{{Warning| When using {{ic|--full-generate-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<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 />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disabling]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
=== Keyblock resource does not exist ===<br />
<br />
If you get an error like this when trying to import keys<br />
<br />
gpg: keyblock resource '''gnupg_home''/pubring.kbx': No such file or directory<br />
<br />
it is because GnuPG will not create its home directory if it does not yet exist. Simply create it manually<br />
<br />
$ mkdir -m 700 ''gnupg_home''<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Regidhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=797857GnuPG2024-01-22T19:08:38Z<p>Regid: /* Key servers */ That is how I understand [https://github.com/mailvelope/keyserver/blob/master/README.md#verify-key-removal-via-link-in-email]</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:OpenPGP]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/dir''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Warning| When using {{ic|--full-gen-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular some newer [[Wikipedia:Elliptic-curve cryptography|elliptic curves]] like [[Wikipedia:Curve448|Curve448]].<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''ECC (sign and encrypt)'' for signing and encryption keys.<br />
* The default ''Curve 25519'' to use [[Wikipedia:Curve25519|Curve25519]] and [[Wikipedia:Ed25519|Ed25519]].<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public-key''.asc}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public-key''.asc ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your {{ic|gpg.conf}}.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use OpenPGP with external GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public-key''.asc}} to your public key ring:<br />
<br />
$ gpg --import ''public-key''.asc<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|There are keyserver where submitted keys cannot be deleted. Some of the reasons are explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --receive-keys ''key-id''<br />
<br />
To refresh/update the keychain with the latest version from a key server:<br />
<br />
$ gpg --refresh-keys<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to the [[#Configuration files|GPG configuration file]] will automatically fetch keys from the key server as needed. This is not a compromise on security, but it can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg|auto-key-retrieve}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted provided one has access to the mail box the key was registered by, no third-party signatures (i.e. no Web of Trust support).<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver ''hkps://keys.openpgp.org/'' --search-keys ''user-id''<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<br />
* If connecting to a keyserver fails with {{ic|gpg: keyserver receive failed: Server indicated a failure}}, you may need to configure gpg to use an alternate port. For example, to use port 80 on Ubuntu's keyserver, use {{ic|keyserver hkp://keyserver.ubuntu.com:80}}.<br />
}}<br />
<br />
=== Web Key Directory ===<br />
<br />
{{Move| OpenPGP | Although the Web Key Directory (WKD) is an IETF draft by gnupg author Werner Koch, it is relevant for all implementations of [[OpenPGP]] and in fact already used by some.}}<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''private-key''.asc ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''private-key''.asc<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert''.asc ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.asc<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.asc<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.asc<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.asc}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver ''pgp.mit.edu'' --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert''.asc<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
{{Expansion|Document {{ic|keyboxd.socket}} and {{ic|keyboxd.service}}.[https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/commit/1551c66631a28501a677d16d5fef9a37fadf2b95]}}<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] the {{ic|ListenStream}} (see {{man|5|systemd.socket|options}}) of all the socket files to be consistent with {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
<br />
It is necessary to allow this passphrase presetting by starting gpg-agent with the {{ic|--allow-preset-passphrase}} or setting {{ic|allow-preset-passphrase}} in {{ic|~/.gnupg/gpg-agent.conf}}.<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/}}. You may need to install the relevant [[pacman#Installing packages|optional dependencies]] for your chosen pinentry program.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* The pinentry programs {{ic|/usr/bin/pinentry-gnome3}} (GNOME) and {{ic|/usr/bin/pinentry-gtk-2}} (generic) [https://avaldes.co/2020/01/28/secret-service-keepassxc.html] support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]], [[KeePass#Secret Service|KeePassXC]] or [[KDE Wallet]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disabling|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
=== Forwarding gpg-agent and ssh-agent to remote ===<br />
<br />
{{Expansion|What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]?}}<br />
<br />
It is possible to forward one's gpg-agent to a remote machine by forwarding gpg sockets to the remote machine, as explained by the [https://wiki.gnupg.org/AgentForwarding GnuPG wiki].<br />
<br />
First, add the following line to {{ic|/etc/ssh/sshd_config}} on the remote machine to enable automatic removal of stale sockets on connect. Without this, the socket(s) on the remote machine will need to removed manually before connecting with forwarding enabled for agent forwarding to work:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
StreamLocalBindUnlink yes<br />
...<br />
}}<br />
<br />
{{Note|You will have to [[reload]] {{ic|sshd.service}} on the remote machine for the new configuration to be loaded by sshd.}}<br />
<br />
On the client, use the {{ic|RemoteForward}} SSH directive to forward traffic destined for a remote port, to a port on your local host. As described in {{Man|5|ssh_config|RemoteForward}}, this directive's parameters are the listening socket path on the remote, and then the destination socket path on the local host. Your configuration should look something like this:<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''remote_name''<br />
...<br />
RemoteForward ''remote_agent_socket'' ''local_agent_extra_socket''<br />
RemoteForward ''remote_agent_ssh_socket'' ''local_agent_ssh_socket''<br />
}}<br />
<br />
The first line configures gpg-agent forwarding:<br />
<br />
* ''remote_agent_socket'' is the output of {{ic|gpgconf --list-dir agent-socket}} on the remote host.<br />
* ''local_agent_extra_socket'' is {{ic|gpgconf --list-dir agent-extra-socket}} on the local host.<br />
<br />
The second line is optional. It configures ssh-agent forwarding:<br />
<br />
* ''local_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the remote host.<br />
* ''remote_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the local host.<br />
<br />
{{Note|If using ssh-agent forwarding, the remote should have {{ic|SSH_AUTH_SOCK}} set to the output of {{ic|gpgconf --list-dir agent-ssh-socket}} as mentioned in [[#SSH agent]]).}}<br />
<br />
So, with the default paths, it would be:<br />
<br />
{{bc|<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh<br />
}}<br />
<br />
With this configuration in place, invoking {{ic|ssh ''remote_name''}} should automatically forward the gpg-agent to the remote, and allow the use of your gpg key(s) for both decryption/signing (and allows the use of ssh-agent with gpg if the second {{ic|RemoteForward}} line is included).<br />
<br />
== Smartcards ==<br />
<br />
{{Expansion|GnuPG 2.3+ has a {{man|1|gpg-card}} tool.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). In earlier versions, if GnuPG's scdaemon failed to connect to the smartcard directly (e.g. by using its integrated CCID support), it fell back and tried to find a smartcard using the PCSC Lite driver. [https://dev.gnupg.org/rG6b93b92111cb8ce6d06c6f71bd62cfb314663b8c Since version 2.4] however, you will have to add the {{Ic|disable-ccid}} option in {{ic|~/.gnupg/scdaemon.conf}}, to be able to use pcscd.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
===== Using a smart card on a remote client via SSH =====<br />
<br />
If you log into a machine via SSH and try to use an attached device via pcscd, you will notice errors such as:<br />
<br />
gpg: selecting card failed: No such device<br />
gpg: OpenPGP card not available: No such device<br />
<br />
This is due to [[Polkit]] restricting access to local clients. To fix this, you can add a rule to allow certain users in all cases. The below rule allows all users in the {{ic|wheel}} group to access devices via {{ic|pcscd}}:<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-pcscd.rules|2=<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_card" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_pcsc" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
After creating the file, make sure to [[restart]] {{ic|polkit.service}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable unsupported AEAD mechanism ===<br />
<br />
With {{pkg|gnupg}} 2.4, {{ic|gpg}} generates keys, which advertise support for a GnuPG specific [[Wikipedia:Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) | AEAD]] encryption mechanism (based on [[Wikipedia:OCB_mode | OCB]]). However, this flavor of AEAD is not supported by other [[OpenPGP]] implementations!<br />
<br />
Although many downstreams attempt to remove this new default by [https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/blob/cfc8f931ee3167a3673b249018dbba527d7428f8/gnupg-2.4-revert_default_rfc4880bis.patch patching the GnuPG sources], when using {{ic|--full-gen-key}} the OCB based custom AEAD encryption mechanism is nonetheless set for the new key.<br />
<br />
Whether GnuPG's custom AEAD is set for a key can be inspected with the help of {{ic|gpg}} itself:<br />
<br />
$ gpg --expert --edit-key ''<FINGERPRINT>''<br />
gpg> showpref<br />
[ultimate] (1). Foobar McFooface (test) <foobar@mcfooface.com><br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD: '''OCB'''<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, '''AEAD''', Keyserver no-modify<br />
<br />
This mechanism can be disabled:<br />
<br />
gpg> setpref AES256 AES192 AES SHA512 SHA384 SHA256 SHA224 ZLIB BZIP2 ZIP<br />
Set preference list to:<br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD:<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, Keyserver no-modify<br />
Really update the preferences? (y/N) y<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis (i.e. using a little social engineering, anyone who is able to decrypt the message can check whether one of the other recipients is the one they suspect). On the receiving side, it may slow down the decryption process because all available secret keys must be tried (e.g. with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
{{Warning| When using {{ic|--full-generate-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<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 />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disabling]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
=== Keyblock resource does not exist ===<br />
<br />
If you get an error like this when trying to import keys<br />
<br />
gpg: keyblock resource '''gnupg_home''/pubring.kbx': No such file or directory<br />
<br />
it is because GnuPG will not create its home directory if it does not yet exist. Simply create it manually<br />
<br />
$ mkdir -m 700 ''gnupg_home''<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Regidhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=797855GnuPG2024-01-22T18:59:01Z<p>Regid: /* Key servers */ As stated at their site [https://keys.mailvelope.com Mailvelope Keyserver]</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:OpenPGP]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/dir''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Warning| When using {{ic|--full-gen-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular some newer [[Wikipedia:Elliptic-curve cryptography|elliptic curves]] like [[Wikipedia:Curve448|Curve448]].<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''ECC (sign and encrypt)'' for signing and encryption keys.<br />
* The default ''Curve 25519'' to use [[Wikipedia:Curve25519|Curve25519]] and [[Wikipedia:Ed25519|Ed25519]].<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public-key''.asc}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public-key''.asc ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your {{ic|gpg.conf}}.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use OpenPGP with external GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public-key''.asc}} to your public key ring:<br />
<br />
$ gpg --import ''public-key''.asc<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|There are keyserver where submitted keys cannot be deleted. Some of the reasons are explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --receive-keys ''key-id''<br />
<br />
To refresh/update the keychain with the latest version from a key server:<br />
<br />
$ gpg --refresh-keys<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to the [[#Configuration files|GPG configuration file]] will automatically fetch keys from the key server as needed. This is not a compromise on security, but it can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg|auto-key-retrieve}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver ''hkps://keys.openpgp.org/'' --search-keys ''user-id''<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<br />
* If connecting to a keyserver fails with {{ic|gpg: keyserver receive failed: Server indicated a failure}}, you may need to configure gpg to use an alternate port. For example, to use port 80 on Ubuntu's keyserver, use {{ic|keyserver hkp://keyserver.ubuntu.com:80}}.<br />
}}<br />
<br />
=== Web Key Directory ===<br />
<br />
{{Move| OpenPGP | Although the Web Key Directory (WKD) is an IETF draft by gnupg author Werner Koch, it is relevant for all implementations of [[OpenPGP]] and in fact already used by some.}}<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''private-key''.asc ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''private-key''.asc<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert''.asc ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.asc<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.asc<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.asc<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.asc}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver ''pgp.mit.edu'' --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert''.asc<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
{{Expansion|Document {{ic|keyboxd.socket}} and {{ic|keyboxd.service}}.[https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/commit/1551c66631a28501a677d16d5fef9a37fadf2b95]}}<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] the {{ic|ListenStream}} (see {{man|5|systemd.socket|options}}) of all the socket files to be consistent with {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
<br />
It is necessary to allow this passphrase presetting by starting gpg-agent with the {{ic|--allow-preset-passphrase}} or setting {{ic|allow-preset-passphrase}} in {{ic|~/.gnupg/gpg-agent.conf}}.<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/}}. You may need to install the relevant [[pacman#Installing packages|optional dependencies]] for your chosen pinentry program.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* The pinentry programs {{ic|/usr/bin/pinentry-gnome3}} (GNOME) and {{ic|/usr/bin/pinentry-gtk-2}} (generic) [https://avaldes.co/2020/01/28/secret-service-keepassxc.html] support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]], [[KeePass#Secret Service|KeePassXC]] or [[KDE Wallet]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disabling|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
=== Forwarding gpg-agent and ssh-agent to remote ===<br />
<br />
{{Expansion|What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]?}}<br />
<br />
It is possible to forward one's gpg-agent to a remote machine by forwarding gpg sockets to the remote machine, as explained by the [https://wiki.gnupg.org/AgentForwarding GnuPG wiki].<br />
<br />
First, add the following line to {{ic|/etc/ssh/sshd_config}} on the remote machine to enable automatic removal of stale sockets on connect. Without this, the socket(s) on the remote machine will need to removed manually before connecting with forwarding enabled for agent forwarding to work:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
StreamLocalBindUnlink yes<br />
...<br />
}}<br />
<br />
{{Note|You will have to [[reload]] {{ic|sshd.service}} on the remote machine for the new configuration to be loaded by sshd.}}<br />
<br />
On the client, use the {{ic|RemoteForward}} SSH directive to forward traffic destined for a remote port, to a port on your local host. As described in {{Man|5|ssh_config|RemoteForward}}, this directive's parameters are the listening socket path on the remote, and then the destination socket path on the local host. Your configuration should look something like this:<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''remote_name''<br />
...<br />
RemoteForward ''remote_agent_socket'' ''local_agent_extra_socket''<br />
RemoteForward ''remote_agent_ssh_socket'' ''local_agent_ssh_socket''<br />
}}<br />
<br />
The first line configures gpg-agent forwarding:<br />
<br />
* ''remote_agent_socket'' is the output of {{ic|gpgconf --list-dir agent-socket}} on the remote host.<br />
* ''local_agent_extra_socket'' is {{ic|gpgconf --list-dir agent-extra-socket}} on the local host.<br />
<br />
The second line is optional. It configures ssh-agent forwarding:<br />
<br />
* ''local_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the remote host.<br />
* ''remote_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the local host.<br />
<br />
{{Note|If using ssh-agent forwarding, the remote should have {{ic|SSH_AUTH_SOCK}} set to the output of {{ic|gpgconf --list-dir agent-ssh-socket}} as mentioned in [[#SSH agent]]).}}<br />
<br />
So, with the default paths, it would be:<br />
<br />
{{bc|<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh<br />
}}<br />
<br />
With this configuration in place, invoking {{ic|ssh ''remote_name''}} should automatically forward the gpg-agent to the remote, and allow the use of your gpg key(s) for both decryption/signing (and allows the use of ssh-agent with gpg if the second {{ic|RemoteForward}} line is included).<br />
<br />
== Smartcards ==<br />
<br />
{{Expansion|GnuPG 2.3+ has a {{man|1|gpg-card}} tool.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). In earlier versions, if GnuPG's scdaemon failed to connect to the smartcard directly (e.g. by using its integrated CCID support), it fell back and tried to find a smartcard using the PCSC Lite driver. [https://dev.gnupg.org/rG6b93b92111cb8ce6d06c6f71bd62cfb314663b8c Since version 2.4] however, you will have to add the {{Ic|disable-ccid}} option in {{ic|~/.gnupg/scdaemon.conf}}, to be able to use pcscd.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
===== Using a smart card on a remote client via SSH =====<br />
<br />
If you log into a machine via SSH and try to use an attached device via pcscd, you will notice errors such as:<br />
<br />
gpg: selecting card failed: No such device<br />
gpg: OpenPGP card not available: No such device<br />
<br />
This is due to [[Polkit]] restricting access to local clients. To fix this, you can add a rule to allow certain users in all cases. The below rule allows all users in the {{ic|wheel}} group to access devices via {{ic|pcscd}}:<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-pcscd.rules|2=<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_card" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_pcsc" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
After creating the file, make sure to [[restart]] {{ic|polkit.service}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable unsupported AEAD mechanism ===<br />
<br />
With {{pkg|gnupg}} 2.4, {{ic|gpg}} generates keys, which advertise support for a GnuPG specific [[Wikipedia:Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) | AEAD]] encryption mechanism (based on [[Wikipedia:OCB_mode | OCB]]). However, this flavor of AEAD is not supported by other [[OpenPGP]] implementations!<br />
<br />
Although many downstreams attempt to remove this new default by [https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/blob/cfc8f931ee3167a3673b249018dbba527d7428f8/gnupg-2.4-revert_default_rfc4880bis.patch patching the GnuPG sources], when using {{ic|--full-gen-key}} the OCB based custom AEAD encryption mechanism is nonetheless set for the new key.<br />
<br />
Whether GnuPG's custom AEAD is set for a key can be inspected with the help of {{ic|gpg}} itself:<br />
<br />
$ gpg --expert --edit-key ''<FINGERPRINT>''<br />
gpg> showpref<br />
[ultimate] (1). Foobar McFooface (test) <foobar@mcfooface.com><br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD: '''OCB'''<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, '''AEAD''', Keyserver no-modify<br />
<br />
This mechanism can be disabled:<br />
<br />
gpg> setpref AES256 AES192 AES SHA512 SHA384 SHA256 SHA224 ZLIB BZIP2 ZIP<br />
Set preference list to:<br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD:<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, Keyserver no-modify<br />
Really update the preferences? (y/N) y<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis (i.e. using a little social engineering, anyone who is able to decrypt the message can check whether one of the other recipients is the one they suspect). On the receiving side, it may slow down the decryption process because all available secret keys must be tried (e.g. with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
{{Warning| When using {{ic|--full-generate-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<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 />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disabling]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
=== Keyblock resource does not exist ===<br />
<br />
If you get an error like this when trying to import keys<br />
<br />
gpg: keyblock resource '''gnupg_home''/pubring.kbx': No such file or directory<br />
<br />
it is because GnuPG will not create its home directory if it does not yet exist. Simply create it manually<br />
<br />
$ mkdir -m 700 ''gnupg_home''<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Regidhttps://wiki.archlinux.org/index.php?title=GnuPG&diff=797851GnuPG2024-01-22T18:52:53Z<p>Regid: /* Sending keys */ According to #Key servers, there are key servers from which keys can be deleted. Possibly one can delete from a centralized server, which is consistent with the reason at [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ]. I find it worth noting that [https://pgp.mit.edu/] has a `Remove the key' button at the bottom of the page. Could it be this button only iterates the inability to remove keys?</p>
<hr />
<div>[[Category:Encryption]]<br />
[[Category:OpenPGP]]<br />
[[Category:Email]]<br />
[[Category:GNU]]<br />
[[de:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[pl:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Data-at-rest encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
<br />
According to the [https://www.gnupg.org/ official website]:<br />
<br />
:GnuPG is a complete and free implementation of the [https://openpgp.org/about/ OpenPGP] standard as defined by [[RFC:4880|RFC 4880]] (also known as PGP). GnuPG allows you to encrypt and sign your data and communications; it features a versatile key management system, along with access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. The shell script {{ic|/usr/bin/pinentry}} determines which ''pinentry'' dialog is used, in the order described at [[#pinentry]].<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Home directory ===<br />
<br />
The GnuPG home directory is where the GnuPG suite stores its keyrings and private keys, and reads configurations from. By default, the path used is {{ic|~/.gnupg}}. There are two ways to override this:<br />
<br />
* Set the {{ic|$GNUPGHOME}} [[environment variable]].<br />
* Use the {{ic|--homedir}} argument, e.g. {{ic|$ gpg --homedir ''path/to/dir''}} [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Configuration-Options.html].<br />
<br />
By default, the home directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
=== Configuration files ===<br />
<br />
All of GnuPG's behavior is configurable via command line arguments. For arguments you would like to be the default, you can add them to the respective configuration file:<br />
<br />
* ''gpg'' checks {{ic|''gnupg_home''/gpg.conf}} (user) and {{ic|/etc/gnupg/gpg.conf}} (global) [https://dev.gnupg.org/T4788]. Since ''gpg'' is the main entrypoint for GnuPG, most configuration of interest will be here. See [https://www.gnupg.org/documentation/manuals/gnupg/GPG-Options.html GPG Options] for possible options.<br />
* ''dirmngr'' checks {{ic|''gnupg_home''/dirmngr.conf}} and {{ic|/etc/gnupg/dirmngr.conf}}. ''dirmngr'' is a program internally invoked by {{ic|gpg}} to access PGP keyservers [https://www.gnupg.org/documentation/manuals/gnupg/Invoking-DIRMNGR.html]. See [https://www.gnupg.org/documentation/manuals/gnupg/Dirmngr-Options.html Dirmngr Options] for possible options.<br />
<br />
These two configuration files cover the common usecases, but there are more auxiliary programs in the GnuPG suite with their own options. See the [https://www.gnupg.org/documentation/manuals/gnupg/index.html GnuPG manual] for a comprehensive list.<br />
<br />
Create the desired file(s), and set their permissions to {{ic|600}} as discussed in [[#Home directory]].<br />
<br />
Add to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. For example, to make GnuPG always use a keyring at a specific path, as if it was invoked as {{ic|gpg --no-default-keyring --keyring ''keyring-path'' ...}}:<br />
<br />
{{hc|''gnupg_home''/gpg.conf (or /etc/gnupg/gpg.conf)|<br />
no-default-keyring<br />
keyring ''keyring-path''<br />
}}<br />
<br />
Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg/}} and {{ic|/home/user2/.gnupg/}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|<br />
* Whenever a ''{{ic|user-id}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
* Whenever a {{ic|''key-id''}} is needed, it can be found adding the {{ic|1=--keyid-format=long}} flag to the command. To show the master secret key for example, run {{ic|1=gpg --list-secret-keys --keyid-format=long ''user-id''}}, the ''key-id'' is the hexadecimal hash provided on the same line as ''sec''.<br />
}}<br />
<br />
=== Create a key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Warning| When using {{ic|--full-gen-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<br />
<br />
Also add the {{ic|--expert}} option to the command line to access more ciphers and in particular some newer [[Wikipedia:Elliptic-curve cryptography|elliptic curves]] like [[Wikipedia:Curve448|Curve448]].<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* The default ''ECC (sign and encrypt)'' for signing and encryption keys.<br />
* The default ''Curve 25519'' to use [[Wikipedia:Curve25519|Curve25519]] and [[Wikipedia:Ed25519|Ed25519]].<br />
* An expiration date: a period of one year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. At a later stage, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* Your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* A secure passphrase, find some guidelines in [[Security#Choosing secure passwords]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
{{Tip|The simpler {{ic|--gen-key}} option uses default parameters for the key cipher, size and expiry and only asks for ''real name'' and ''email address''.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
GnuPG's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[Wikipedia:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of a user's public key to file {{ic|''public-key''.asc}} (e.g. to distribute it by e-mail):<br />
<br />
$ gpg --export --armor --output ''public-key''.asc ''user-id''<br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your {{ic|gpg.conf}}.<br />
* You can omit the {{ic|user-id}} to export all public keys within your keyring. This is useful if you want to share multiple identities at once, or for importing in another application, e.g. [[Thunderbird#Use OpenPGP with external GnuPG|Thunderbird]].<br />
}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public-key''.asc}} to your public key ring:<br />
<br />
$ gpg --import ''public-key''.asc<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
If you wish to import a key ID to install a specific Arch Linux package, see [[pacman/Package signing#Managing the keyring]] and [[Makepkg#Signature checking]].<br />
<br />
=== Use a keyserver ===<br />
<br />
==== Sending keys ====<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve it without having to contact you directly:<br />
<br />
$ gpg --send-keys ''key-id''<br />
<br />
{{Warning|There are keyserver where submitted keys cannot be deleted. Some of the reasons are explained in the [https://pgp.mit.edu/faq.html MIT PGP Public Key Server FAQ].}}<br />
{{Note|The associated email address, once published publicly, could be the target of spammers and in this case anti-spam filtering may be necessary.}}<br />
<br />
==== Searching and receiving keys ====<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --receive-keys ''key-id''<br />
<br />
To refresh/update the keychain with the latest version from a key server:<br />
<br />
$ gpg --refresh-keys<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (e.g., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* It is recommended to use the long key ID or the full fingerprint when receiving a key. Using a short ID may encounter collisions. All keys will be imported that have the short ID, see [https://lore.kernel.org/lkml/20160815153401.9EC2BADC2C@smtp.postman.i2p/ fake keys found in the wild] for such example.<br />
}}<br />
<br />
{{Tip|Adding {{ic|auto-key-retrieve}} to the [[#Configuration files|GPG configuration file]] will automatically fetch keys from the key server as needed. This is not a compromise on security, but it can be considered a '''privacy violation'''; see "web bug" in {{man|1|gpg|auto-key-retrieve}}.}}<br />
<br />
==== Key servers ====<br />
<br />
The most common keyservers are:<br />
<br />
* [https://keyserver.ubuntu.com Ubuntu Keyserver]: federated, no verification, keys cannot be deleted.<br />
* [https://keys.mailvelope.com Mailvelope Keyserver]: central, verification of email IDs, keys can be deleted.<br />
* [https://keys.openpgp.org keys.openpgp.org]: central, verification of email IDs, keys can be deleted, no third-party signatures (i.e. no Web of Trust support).<br />
<br />
More are listed at [[Wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
<br />
An alternative key server can be specified with the {{ic|keyserver}} option in one of the [[#Configuration files]], for instance:<br />
{{hc|~/.gnupg/dirmngr.conf|<br />
keyserver hkp://keyserver.ubuntu.com<br />
}}<br />
A temporary use of another server is handy when the regular one does not work as it should. It can be achieved by, for example,<br />
<br />
$ gpg --keyserver ''hkps://keys.openpgp.org/'' --search-keys ''user-id''<br />
<br />
{{Tip|<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: General error}}, and you use the default hkps keyserver pool, make sure you set the HKPS pool verification certificate with {{ic|hkp-cacert /usr/share/gnupg/sks-keyservers.netCA.pem}} in your {{ic|dirmngr.conf}} and kill the old dirmngr process.<br />
* If receiving fails with the message {{ic|gpg: keyserver receive failed: Connection refused}}, try using a different DNS server.<br />
* You can connect to the keyserver over [[Tor]] with [[Tor#Torsocks]]. Or using the {{ic|--use-tor}} command line option. See [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} [[environment variable]] and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in the configuration file to override the environment variable of the same name. [[Restart]] the {{ic|dirmngr.service}} [[systemd/User|user service]] for the changes to take effect.<br />
* If connecting to a keyserver fails with {{ic|gpg: keyserver receive failed: Server indicated a failure}}, you may need to configure gpg to use an alternate port. For example, to use port 80 on Ubuntu's keyserver, use {{ic|keyserver hkp://keyserver.ubuntu.com:80}}.<br />
}}<br />
<br />
=== Web Key Directory ===<br />
<br />
{{Move| OpenPGP | Although the Web Key Directory (WKD) is an IETF draft by gnupg author Werner Koch, it is relevant for all implementations of [[OpenPGP]] and in fact already used by some.}}<br />
<br />
The Web Key Service (WKS) protocol is a new [https://datatracker.ietf.org/doc/draft-koch-openpgp-webkey-service/ standard] for key distribution, where the email domain provides its own key server called [https://wiki.gnupg.org/WKD Web Key Directory (WKD)]. When encrypting to an email address (e.g. {{ic|user@example.com}}), GnuPG (>=2.1.16) will query the domain ({{ic|example.com}}) via HTTPS for the public OpenPGP key if it is not already in the local keyring. The option {{ic|auto-key-locate}} will locate a key using the WKD protocol if there is no key on the local keyring for this email address.<br />
<br />
# gpg --recipient ''user@example.org'' --auto-key-locate --encrypt ''doc''<br />
<br />
See the [https://wiki.gnupg.org/WKD#Implementations GnuPG Wiki] for a list of email providers that support WKD. If you control the domain of your email address yourself, you can follow [https://wiki.gnupg.org/WKDHosting this guide] to enable WKD for your domain. To check if your key can be found in the WKD you can use [https://metacode.biz/openpgp/web-key-directory this webinterface].<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (option {{ic|-e}}/{{ic|--encrypt}}) a file or message to that recipient (option {{ic|-r}}/{{ic|--recipient}}). Additionally you need to [[#Create a key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|-d}}/{{ic|--decrypt}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}}/{{ic|--output}} option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor, suitable for copying and pasting a message in text format.<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use GnuPG to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Data-at-rest encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|-c}}/{{ic|--symmetric}} to perform symmetric encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the data<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase and generate the encryption key<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
==== Directory ====<br />
<br />
Encrypting/decrypting a directory can be done with {{man|1|gpgtar}}.<br />
<br />
Encrypt:<br />
$ gpgtar -c -o ''dir''.gpg ''dir''<br />
<br />
Decrypt:<br />
$ gpgtar -d ''dir''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor --output ''private-key''.asc ''user-id''<br />
<br />
Note the above command will require that you enter the passphrase for the key. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|<br />
* The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.<br />
* This method of backing up key has some security limitations. See https://web.archive.org/web/20210803213236/https://habd.as/post/moving-gpg-keys-privately/ for a more secure way to back up and import key using ''gpg''.<br />
}}<br />
<br />
To import the backup of your private key:<br />
<br />
$ gpg --import ''private-key''.asc<br />
<br />
{{Tip|[[Paperkey]] can be used to export private keys as human readable text or machine readable barcodes that can be printed on paper and archived.}}<br />
<br />
=== Backup your revocation certificate ===<br />
<br />
Revocation certificates are automatically generated for newly generated keys. These are by default located in {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
The revocation certificates can also be generated manually by the user later using:<br />
<br />
$ gpg --gen-revoke --armor --output ''revcert''.asc ''user-id''<br />
<br />
This certificate can be used to [[#Revoke a key]] if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.<br />
<br />
{{Warning|Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.}}<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''user-id''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Type {{ic|help}} in the edit key sub menu to show the complete list of commands. Some useful ones:<br />
<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
> adduid # add additional names, comments, and email addresses<br />
> addphoto # add photo to key (must be JPG, 240x288 recommended, enter full path to image when prompted)<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg --list-secret-keys --with-subkey-fingerprint<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.asc<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.asc<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.asc<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.asc}} on your other devices.<br />
<br />
=== Extending expiration date ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
It is good practice to set an expiration date on your subkeys, so that if you lose access to the key (e.g. you forget the passphrase) the key will not continue to be used indefinitely by others. When the key expires, it is relatively straight-forward to extend the expiration date:<br />
<br />
$ gpg --edit-key ''user-id''<br />
> expire<br />
<br />
You will be prompted for a new expiration date, as well as the passphrase for your secret key, which is used to sign the new expiration date.<br />
<br />
Repeat this for any further subkeys that have expired:<br />
<br />
> key 1<br />
> expire<br />
<br />
Finally, save the changes and quit:<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver keyserver.ubuntu.com --send-keys ''key-id''<br />
<br />
Alternatively, if you use this key on multiple computers, you can export the public key (with new signed expiration dates) and import it on those machines:<br />
<br />
$ gpg --export --output pubkey.gpg ''user-id''<br />
$ gpg --import pubkey.gpg<br />
<br />
There is no need to re-export your secret key or update your backups: the master secret key itself never expires, and the signature of the expiration date left on the public key and subkeys is all that is needed.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
Alternatively, if you prefer to stop using subkeys entirely once they have expired, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Tip|You do not need to create a new key simply because it is expired. You can extend the expiration date, see the section [[#Extending expiration date]].}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''user-id''<br />
> addkey<br />
<br />
And answer the following questions it asks (see [[#Create a key pair]] for suggested settings).<br />
<br />
Save changes<br />
<br />
> save<br />
<br />
Update it to a keyserver.<br />
<br />
$ gpg --keyserver ''pgp.mit.edu'' --send-keys ''user-id''<br />
<br />
You will also need to export a fresh copy of your secret keys for backup purposes. See the section [[#Backup your private key]] for details on how to do this.<br />
<br />
{{Tip|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
=== Revoke a key ===<br />
<br />
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.<br />
<br />
If you have no longer access to your keypair, first [[#Import a public key]] to import your own key.<br />
Then, to revoke the key, import the file saved in [[#Backup your revocation certificate]]:<br />
<br />
$ gpg --import ''revcert''.asc<br />
<br />
Now the revocation needs to be made public. [[#Use a keyserver]] to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|-s}}/{{ic|--sign}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file has been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
{{Expansion|Document {{ic|keyboxd.socket}} and {{ic|keyboxd.service}}.[https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/commit/1551c66631a28501a677d16d5fef9a37fadf2b95]}}<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client. {{Pkg|gnupg}} comes with [[systemd/User|systemd user]] sockets which are enabled by default. These sockets are {{ic|gpg-agent.socket}}, {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}}, {{ic|gpg-agent-ssh.socket}}, and {{ic|dirmngr.socket}}.<br />
<br />
* The main {{ic|gpg-agent.socket}} is used by ''gpg'' to connect to the ''gpg-agent'' daemon.<br />
* The intended use for the {{ic|gpg-agent-extra.socket}} on a local system is to set up a Unix domain socket forwarding from a remote system. This enables to use ''gpg'' on the remote system without exposing the private keys to the remote system. See {{man|1|gpg-agent}} for details.<br />
* The {{ic|gpg-agent-browser.socket}} allows web browsers to access the ''gpg-agent'' daemon.<br />
* The {{ic|gpg-agent-ssh.socket}} can be used by [[SSH]] to cache [[SSH keys]] added by the ''ssh-add'' program. See [[#SSH agent]] for the necessary configuration.<br />
* The {{ic|dirmngr.socket}} starts a GnuPG daemon handling connections to keyservers.<br />
<br />
{{Note|If you use non-default GnuPG [[#Home directory]], you will need to [[edit]] the {{ic|ListenStream}} (see {{man|5|systemd.socket|options}}) of all the socket files to be consistent with {{ic|gpgconf --list-dirs}}. The socket names use the hash of the non-default GnuPG home directory [https://github.com/gpg/gnupg/blob/260bbb4ab27eab0a8d4fb68592b0d1c20d80179c/common/homedir.c#L710-L713], so you can hardcode it without worrying about it changing.}}<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{man|1|gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|1=<br />
To cache your passphrase for the whole session, please run the following command:<br />
<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXX<br />
<br />
where XXXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. The passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
<br />
It is necessary to allow this passphrase presetting by starting gpg-agent with the {{ic|--allow-preset-passphrase}} or setting {{ic|allow-preset-passphrase}} in {{ic|~/.gnupg/gpg-agent.conf}}.<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/}}. You may need to install the relevant [[pacman#Installing packages|optional dependencies]] for your chosen pinentry program.<br />
<br />
{{Tip|<br />
* In order to use {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{AUR|kwalletcli}} package.<br />
* The pinentry programs {{ic|/usr/bin/pinentry-gnome3}} (GNOME) and {{ic|/usr/bin/pinentry-gtk-2}} (generic) [https://avaldes.co/2020/01/28/secret-service-keepassxc.html] support the [https://specifications.freedesktop.org/secret-service/ DBus Secret Service API], which allows for remembering passwords via a compliant manager such as [[GNOME Keyring]], [[KeePass#Secret Service|KeePassXC]] or [[KDE Wallet]].<br />
}}<br />
<br />
Remember to [[#Reload the agent|reload the agent]] after making changes to the configuration.<br />
<br />
=== Cache passwords ===<br />
<br />
{{ic|max-cache-ttl}} and {{ic|default-cache-ttl}} defines how many seconds gpg-agent should cache the passwords. To enter a password once a session, set them to something very high, for instance:<br />
<br />
{{hc|gpg-agent.conf|<br />
max-cache-ttl 60480000<br />
default-cache-ttl 60480000<br />
}}<br />
<br />
For password caching in SSH emulation mode, set {{ic|default-cache-ttl-ssh}} and {{ic|max-cache-ttl-ssh}} instead, for example:<br />
<br />
{{hc|gpg-agent.conf|<br />
default-cache-ttl-ssh 60480000<br />
max-cache-ttl-ssh 60480000<br />
}}<br />
<br />
=== Unattended passphrase ===<br />
<br />
Starting with GnuPG 2.1.0 the use of gpg-agent and pinentry is required, which may break backwards compatibility for passphrases piped in from STDIN using the {{ic|--passphrase-fd 0}} commandline option. In order to have the same type of functionality as the older releases two things must be done:<br />
<br />
First, edit the gpg-agent configuration to allow ''loopback'' pinentry mode:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
allow-loopback-pinentry<br />
}}<br />
<br />
[[#Reload the agent|Reload the agent]] if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://dev.gnupg.org/T1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your [[SSH keys]]. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
==== Set SSH_AUTH_SOCK ====<br />
<br />
<br />
[[Environment variables#Per user|Set]] the following variables to communicate with ''gpg-agent'' instead of the default ''ssh-agent''.<br />
<br />
{{bc|1=<br />
SSH_AGENT_PID=""<br />
SSH_AUTH_SOCK="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|<br />
* If you are using a script to manage your variables, you may also unset {{ic|SSH_AGENT_PID}} rather than setting it to {{ic|""}}, via {{ic|unset SSH_AGENT_PID}}.<br />
* If you set your {{ic|SSH_AUTH_SOCK}} manually, keep in mind that your socket location may be different if you are using a custom {{ic|GNUPGHOME}}. You can use the following bash example, or change {{ic|SSH_AUTH_SOCK}} to the value of {{ic|gpgconf --list-dirs agent-ssh-socket}}.<br />
* If GNOME Keyring is installed, it is necessary to [[GNOME/Keyring#Disabling|deactivate]] its ssh component. Otherwise, it will overwrite {{ic|SSH_AUTH_SOCK}}.<br />
}}<br />
<br />
Alternatively, depend on Bash. This works for non-standard socket locations as well:<br />
<br />
{{hc|~/.bashrc|2=<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"<br />
fi<br />
}}<br />
<br />
{{Note|1=The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [https://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].}}<br />
<br />
==== Configure pinentry to use the correct TTY ====<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{man|1|gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|2=<br />
export GPG_TTY=$(tty)<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
}}<br />
<br />
If you use multiple terminals simultaneously and want ''gpg-agent'' to ask for passphrase via ''pinentry-curses'' from the same terminal where the ''ssh'' command was run, add the following to the SSH configuration file. This will make the TTY to be refreshed every time an ''ssh'' command is run [https://unix.stackexchange.com/a/499133]:<br />
<br />
{{hc|~/.ssh/config|2=<br />
Match host * exec "gpg-connect-agent UPDATESTARTUPTTY /bye"<br />
}}<br />
<br />
Note that GPG_TTY environment variable has to be set for this to work.<br />
<br />
==== Add SSH keys ====<br />
<br />
Once ''gpg-agent'' is running you can use ''ssh-add'' to approve keys, following the same steps as for [[SSH keys#ssh-agent|ssh-agent]]. The list of approved keys is stored in the {{ic|~/.gnupg/sshcontrol}} file. <br />
<br />
Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. For password caching see [[#Cache passwords]].<br />
<br />
==== Using a PGP key for SSH authentication ====<br />
<br />
You can also use your PGP key as an SSH key. This requires a key with the {{ic|Authentication}} capability (see [[#Custom capabilities]]). There are various benefits gained by using a PGP key for SSH authentication, including:<br />
<br />
* Reduced key maintenance, as you will no longer need to maintain an SSH key.<br />
* The ability to store the authentication key on a smartcard. GnuPG will automatically detect the key when the card is available, and add it to the agent (check with {{ic|ssh-add -l}} or {{ic|ssh-add -L}}). The comment for the key should be something like: {{ic|openpgp:''key-id''}} or {{ic|cardno:''card-id''}}. <br />
<br />
To retrieve the public key part of your GPG/SSH key, run {{ic|gpg --export-ssh-key ''gpg-key''}}. If your key is authentication-capable but this command still fails with "Unusable public key", add a {{ic|!}} suffix ([https://dev.gnupg.org/T2957]). <br />
<br />
Unless you have your GPG key on a keycard, you need to add your key to {{ic|$GNUPGHOME/sshcontrol}} to be recognized as a SSH key. If your key is on a keycard, its keygrip is added to {{ic|sshcontrol}} implicitly. If not, get the keygrip of your key this way:<br />
<br />
{{hc|$ gpg --list-keys --with-keygrip|2=<br />
sub rsa4096 2018-07-25 [A]<br />
Keygrip = ''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
Then edit {{ic|sshcontrol}} like this. Adding the keygrip is a one-time action; you will not need to edit the file again, unless you are adding additional keys.<br />
<br />
{{hc|$GNUPGHOME/sshcontrol|<br />
''1531C8084D16DC4C36911F1585AF0ACE7AAFD7E7''<br />
}}<br />
<br />
=== Forwarding gpg-agent and ssh-agent to remote ===<br />
<br />
{{Expansion|What about setting {{ic|ForwardAgent yes}} as shown in [[OpenSSH#Agent forwarding]]?}}<br />
<br />
It is possible to forward one's gpg-agent to a remote machine by forwarding gpg sockets to the remote machine, as explained by the [https://wiki.gnupg.org/AgentForwarding GnuPG wiki].<br />
<br />
First, add the following line to {{ic|/etc/ssh/sshd_config}} on the remote machine to enable automatic removal of stale sockets on connect. Without this, the socket(s) on the remote machine will need to removed manually before connecting with forwarding enabled for agent forwarding to work:<br />
<br />
{{hc|/etc/ssh/sshd_config|<br />
...<br />
StreamLocalBindUnlink yes<br />
...<br />
}}<br />
<br />
{{Note|You will have to [[reload]] {{ic|sshd.service}} on the remote machine for the new configuration to be loaded by sshd.}}<br />
<br />
On the client, use the {{ic|RemoteForward}} SSH directive to forward traffic destined for a remote port, to a port on your local host. As described in {{Man|5|ssh_config|RemoteForward}}, this directive's parameters are the listening socket path on the remote, and then the destination socket path on the local host. Your configuration should look something like this:<br />
<br />
{{hc|~/.ssh/config|<br />
Host ''remote_name''<br />
...<br />
RemoteForward ''remote_agent_socket'' ''local_agent_extra_socket''<br />
RemoteForward ''remote_agent_ssh_socket'' ''local_agent_ssh_socket''<br />
}}<br />
<br />
The first line configures gpg-agent forwarding:<br />
<br />
* ''remote_agent_socket'' is the output of {{ic|gpgconf --list-dir agent-socket}} on the remote host.<br />
* ''local_agent_extra_socket'' is {{ic|gpgconf --list-dir agent-extra-socket}} on the local host.<br />
<br />
The second line is optional. It configures ssh-agent forwarding:<br />
<br />
* ''local_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the remote host.<br />
* ''remote_agent_ssh_socket'' is {{ic|gpgconf --list-dir agent-ssh-socket}} on the local host.<br />
<br />
{{Note|If using ssh-agent forwarding, the remote should have {{ic|SSH_AUTH_SOCK}} set to the output of {{ic|gpgconf --list-dir agent-ssh-socket}} as mentioned in [[#SSH agent]]).}}<br />
<br />
So, with the default paths, it would be:<br />
<br />
{{bc|<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent /run/user/1000/gnupg/S.gpg-agent.extra<br />
RemoteForward /run/user/1000/gnupg/S.gpg-agent.ssh /run/user/1000/gnupg/S.gpg-agent.ssh<br />
}}<br />
<br />
With this configuration in place, invoking {{ic|ssh ''remote_name''}} should automatically forward the gpg-agent to the remote, and allow the use of your gpg key(s) for both decryption/signing (and allows the use of ssh-agent with gpg if the second {{ic|RemoteForward}} line is included).<br />
<br />
== Smartcards ==<br />
<br />
{{Expansion|GnuPG 2.3+ has a {{man|1|gpg-card}} tool.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] {{man|1|scdaemon}} for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smartcard readers the optional dependency {{Pkg|libusb-compat}} must be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with pcscd (PCSC Lite) ===<br />
<br />
{{man|8|pcscd}} is a daemon which handles access to smartcard (SCard API). In earlier versions, if GnuPG's scdaemon failed to connect to the smartcard directly (e.g. by using its integrated CCID support), it fell back and tried to find a smartcard using the PCSC Lite driver. [https://dev.gnupg.org/rG6b93b92111cb8ce6d06c6f71bd62cfb314663b8c Since version 2.4] however, you will have to add the {{Ic|disable-ccid}} option in {{ic|~/.gnupg/scdaemon.conf}}, to be able to use pcscd.<br />
<br />
To use pscsd [[install]] {{Pkg|pcsclite}} and {{Pkg|ccid}}. Then [[start]] and/or [[enable]] {{ic|pcscd.service}}. Alternatively start and/or enable {{ic|pcscd.socket}} to activate the daemon when needed.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{man|1|scdaemon}} if you do not use OpenSC.<br />
<br />
==== Shared access with pcscd ====<br />
<br />
GnuPG {{ic|scdaemon}} is the only popular {{ic|pcscd}} client that uses {{ic|PCSC_SHARE_EXCLUSIVE}} flag when connecting to {{ic|pcscd}}. Other clients like OpenSC PKCS#11 that are used by browsers and programs listed in [[Electronic identification]] are using {{ic|PCSC_SHARE_SHARED}} that allows simultaneous access to single smartcard. {{ic|pcscd}} will not give exclusive access to smartcard while there are other clients connected. This means that to use GnuPG smartcard features you must before have to close all your open browser windows or do some other inconvenient operations. Starting from version 2.2.28 LTS and 2.3.0 you can enable shared access by modifying your {{ic|scdaemon.conf}} file and adding {{ic|pcsc-shared}} line end of it.<br />
<br />
===== Multi applet smart cards =====<br />
<br />
When using [[YubiKey]]s or other multi applet USB dongles with OpenSC PKCS#11 may run into problems where OpenSC switches your Yubikey from OpenPGP to PIV applet, breaking the {{ic|scdaemon}}. <br />
<br />
You can hack around the problem by forcing OpenSC to also use the OpenPGP applet. Open {{ic|/etc/opensc.conf}} file, search for Yubikey and change the {{ic|1=driver = "PIV-II";}} line to {{ic|1=driver = "openpgp";}}. If there is no such entry, use {{ic|pcsc_scan}}. Search for the Answer to Reset {{ic|ATR: 12 34 56 78 90 AB CD ...}}. Then create a new entry.<br />
<br />
{{hc|/etc/opensc.conf|2=<br />
...<br />
card_atr 12:23:34:45:67:89:ab:cd:... {<br />
name = "YubiKey Neo";<br />
driver = "openpgp"<br />
}<br />
...<br />
}}<br />
<br />
After that you can test with {{ic|pkcs11-tool -O --login}} that the OpenPGP applet is selected by default. Other PKCS#11 clients like browsers may need to be restarted for that change to be applied.<br />
<br />
===== Using a smart card on a remote client via SSH =====<br />
<br />
If you log into a machine via SSH and try to use an attached device via pcscd, you will notice errors such as:<br />
<br />
gpg: selecting card failed: No such device<br />
gpg: OpenPGP card not available: No such device<br />
<br />
This is due to [[Polkit]] restricting access to local clients. To fix this, you can add a rule to allow certain users in all cases. The below rule allows all users in the {{ic|wheel}} group to access devices via {{ic|pcscd}}:<br />
<br />
{{hc|/etc/polkit-1/rules.d/99-pcscd.rules|2=<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_card" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
polkit.addRule(function(action, subject) {<br />
if (action.id == "org.debian.pcsc-lite.access_pcsc" &&<br />
subject.isInGroup("wheel")) {<br />
return polkit.Result.YES;<br />
}<br />
});<br />
}}<br />
<br />
After creating the file, make sure to [[restart]] {{ic|polkit.service}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Disable unsupported AEAD mechanism ===<br />
<br />
With {{pkg|gnupg}} 2.4, {{ic|gpg}} generates keys, which advertise support for a GnuPG specific [[Wikipedia:Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) | AEAD]] encryption mechanism (based on [[Wikipedia:OCB_mode | OCB]]). However, this flavor of AEAD is not supported by other [[OpenPGP]] implementations!<br />
<br />
Although many downstreams attempt to remove this new default by [https://gitlab.archlinux.org/archlinux/packaging/packages/gnupg/-/blob/cfc8f931ee3167a3673b249018dbba527d7428f8/gnupg-2.4-revert_default_rfc4880bis.patch patching the GnuPG sources], when using {{ic|--full-gen-key}} the OCB based custom AEAD encryption mechanism is nonetheless set for the new key.<br />
<br />
Whether GnuPG's custom AEAD is set for a key can be inspected with the help of {{ic|gpg}} itself:<br />
<br />
$ gpg --expert --edit-key ''<FINGERPRINT>''<br />
gpg> showpref<br />
[ultimate] (1). Foobar McFooface (test) <foobar@mcfooface.com><br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD: '''OCB'''<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, '''AEAD''', Keyserver no-modify<br />
<br />
This mechanism can be disabled:<br />
<br />
gpg> setpref AES256 AES192 AES SHA512 SHA384 SHA256 SHA224 ZLIB BZIP2 ZIP<br />
Set preference list to:<br />
Cipher: AES256, AES192, AES, 3DES<br />
AEAD:<br />
Digest: SHA512, SHA384, SHA256, SHA224, SHA1<br />
Compression: ZLIB, BZIP2, ZIP, Uncompressed<br />
Features: MDC, Keyserver no-modify<br />
Really update the preferences? (y/N) y<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''user-id'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
{{Tip|[[pass]] automates this process.}}<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on first use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''user-id''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis (i.e. using a little social engineering, anyone who is able to decrypt the message can check whether one of the other recipients is the one they suspect). On the receiving side, it may slow down the decryption process because all available secret keys must be tried (e.g. with {{ic|--try-secret-key ''user-id''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses the [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together at a physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [https://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-git}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
=== Custom capabilities ===<br />
<br />
For further customization also possible to set custom capabilities to your keys. The following capabilities are available:<br />
<br />
* Certify (only for master keys) - allows the key to create subkeys, mandatory for master keys.<br />
* Sign - allows the key to create cryptographic signatures that others can verify with the public key.<br />
* Encrypt - allows anyone to encrypt data with the public key, that only the private key can decrypt.<br />
* Authenticate - allows the key to authenticate with various non-GnuPG programs. The key can be used as e.g. an SSH key. <br />
<br />
It is possible to specify the capabilities of the master key, by running: <br />
<br />
$ gpg --full-generate-key --expert<br />
<br />
{{Warning| When using {{ic|--full-generate-key}} the generated key will advertise an AEAD mechanism, which is not understood by other [[OpenPGP]] implementations. To disable this after key creation see [[GnuPG#Disable_unsupported_AEAD_mechanism]].}}<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 />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail with a {{ic|Permission denied}} error, even as root. If this happens when attempting to use ssh, an error like {{ic|sign_and_send_pubkey: signing failed: agent refused operation}} will be returned. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
# chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
If the pinentry program is {{ic|/usr/bin/pinentry-gnome3}}, it needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use a variety of different options described in [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kgpg}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set elsewhere.<br />
<br />
See [[GNOME/Keyring#Disabling]] on how to disable this behavior.<br />
<br />
=== mutt ===<br />
<br />
Mutt might not use ''gpg-agent'' correctly, you need to set an [[environment variable]] {{ic|GPG_AGENT_INFO}} (the content does not matter) when running mutt. Be also sure to enable password caching correctly, see [[#Cache passwords]].<br />
<br />
See [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [https://web.archive.org/web/20160502052025/http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commands:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use [[udev rules]], similar to the following:<br />
<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
=== server 'gpg-agent' is older than us (x < y) ===<br />
<br />
This warning appears if {{ic|gnupg}} is upgraded and the old gpg-agent is still running. [[Restart]] the ''user'''s {{ic|gpg-agent.socket}} (i.e., use the {{ic|--user}} flag when restarting).<br />
<br />
=== IPC connect call failed ===<br />
<br />
Make sure {{ic|gpg-agent}} and {{ic|dirmngr}} are not running with {{ic|killall gpg-agent dirmngr}} and the {{ic|$GNUPGHOME/crls.d/}} folder has permission set to {{ic|700}}.<br />
<br />
By default, the {{Pkg|gnupg}} package uses the directory {{ic|/run/user/$UID/gnupg/}} for sockets. [https://github.com/gpg/gnupg/blob/25ae80b8eb6e9011049d76440ad7d250c1d02f7c/README#L121-L122 GnuPG documentation] states this is the preferred directory (not all file systems are supported for sockets). Validate that your {{ic|agent-socket}} configuration specifies a path that has an appropriate file system. You can find the your path settings for {{ic|agent-socket}} by running {{ic|gpgconf --list-dirs agent-socket}}.<br />
<br />
Test that {{ic|gpg-agent}} starts successfully with {{ic|gpg-agent --daemon}}.<br />
<br />
=== Mitigating Poisoned PGP Certificates ===<br />
<br />
In June 2019, an unknown attacker spammed several high-profile PGP certificates with tens of thousands (or hundreds of thousands) of signatures (CVE-2019-13050) and uploaded these signatures to the SKS keyservers.<br />
The existence of these poisoned certificates in a keyring causes gpg to hang with the following message:<br />
<br />
gpg: removing stale lockfile (created by 7055)<br />
<br />
Possible mitigation involves removing the poisoned certificate as per this [https://tech.michaelaltfield.net/2019/07/14/mitigating-poisoned-pgp-certificates/ blog post].<br />
<br />
=== Invalid IPC response and Inappropriate ioctl for device ===<br />
<br />
The default pinentry program is {{ic|/usr/bin/pinentry-gtk-2}}. If {{Pkg|gtk2}} is unavailable, pinentry falls back to {{ic|/usr/bin/pinentry-curses}} and causes signing to fail:<br />
<br />
gpg: signing failed: Inappropriate ioctl for device<br />
gpg: [stdin]: clear-sign failed: Inappropriate ioctl for device<br />
<br />
You need to set the {{ic|GPG_TTY}} environment variable for the pinentry programs {{ic|/usr/bin/pinentry-tty}} and {{ic|/usr/bin/pinentry-curses}}.<br />
<br />
$ export GPG_TTY=$(tty)<br />
<br />
=== Keyblock resource does not exist ===<br />
<br />
If you get an error like this when trying to import keys<br />
<br />
gpg: keyblock resource '''gnupg_home''/pubring.kbx': No such file or directory<br />
<br />
it is because GnuPG will not create its home directory if it does not yet exist. Simply create it manually<br />
<br />
$ mkdir -m 700 ''gnupg_home''<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://futureboy.us/pgp.html Alan Eliasen's GPG Tutorial]<br />
* [[RFC:4880|RFC 4880]] — "OpenPGP Message Format"<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [[Fedora:Creating GPG Keys]]<br />
* [[Debian:Subkeys]]<br />
* [https://github.com/lfit/itpol/blob/master/protecting-code-integrity.md Protecting code integrity with PGP]<br />
* [https://sanctum.geek.nz/arabesque/series/gnu-linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Regidhttps://wiki.archlinux.org/index.php?title=Pacman/Package_signing&diff=797280Pacman/Package signing2024-01-16T22:35:33Z<p>Regid: When reading the article, I needed to refresh my memory about pacman-key. Some link would have saved me the search. I assume other readers face similar situations.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:OpenPGP]]<br />
[[Category:Package manager]]<br />
[[de:Pacman-key]]<br />
[[es:Pacman (Español)/Package signing]]<br />
[[fr:Pacman (Français)/Package signing]]<br />
[[it:Pacman (Italiano)/Package signing]]<br />
[[ja:Pacman/パッケージの署名]]<br />
[[pt:Pacman (Português)/Package signing]]<br />
[[ru:Pacman (Русский)/Package signing]]<br />
[[zh-hans:Pacman/Package signing]]<br />
{{Related articles start}}<br />
{{Related|GnuPG}}<br />
{{Related|OpenPGP}}<br />
{{Related articles end}}<br />
To determine if packages are authentic, ''pacman'' uses [[OpenPGP]] keys in a [https://www.gnupg.org/gph/en/manual.html#AEN385 web of trust] model. The current Master Signing Keys are found [https://archlinux.org/master-keys/ here]. At least three of these Master Signing Keys are used to sign the Developers' and Package Maintainers' own keys. They are then used to sign their packages. Each user also has a unique OpenPGP key, which is generated when you configure {{man|8|pacman-key}}. It is this web of trust that links the user's key to the master keys.<br />
<br />
Examples of webs of trust:<br />
<br />
* '''Custom packages''': Packages made and signed with a local key.<br />
* '''Unofficial packages''': Packages made and signed by a developer. Then, a local key was used to sign the developer's key.<br />
* '''Official packages''': Packages made and signed by a developer. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.<br />
<br />
{{Note|The HKP protocol uses 11371/tcp for communication. In order to get the signed keys from the servers (using ''pacman-key''), this port is required for communication.}}<br />
<br />
== Setup ==<br />
<br />
=== Configuring pacman ===<br />
<br />
The {{ic|SigLevel}} option in {{ic|/etc/pacman.conf}} determines the level of trust required to install a package with {{ic|pacman -S}}. For a detailed explanation of {{ic|SigLevel}}, see {{man|5|pacman.conf|PACKAGE AND DATABASE SIGNATURE CHECKING}}, and the file comments. One can set signature checking globally, or per repository. If {{ic|SigLevel}} is set globally in the {{ic|[options]}} section, all packages installed with {{ic|pacman -S}} will require signing. With the {{ic|LocalFileSigLevel}} setting from the default {{ic|pacman.conf}}, any packages you build, and install with {{ic|pacman -U}}, will not need to be signed using ''makepkg''.<br />
<br />
{{Note|1=Although all official packages are now signed, as of November 2018 signing of the databases is a [https://bbs.archlinux.org/viewtopic.php?id=242258 work in progress]. If {{ic|Required}} is set then {{ic|DatabaseOptional}} should also be set.}}<br />
<br />
For remote packages, the default configuration will only support the installation of packages signed by trusted keys:<br />
<br />
{{hc|1=/etc/pacman.conf|<br />
output=SigLevel = Required DatabaseOptional<br />
}}<br />
<br />
{{ic|TrustedOnly}} is a default compiled-in ''pacman'' parameter. The default configuration is identical to using the global option of:<br />
<br />
SigLevel = Required DatabaseOptional TrustedOnly<br />
<br />
The above can be achieved too on a repository level further below in the configuration, e.g.:<br />
<br />
[core]<br />
SigLevel = PackageRequired<br />
Include = /etc/pacman.d/mirrorlist<br />
<br />
explicitly adds signature checking for the packages of the repository, but does not require the database to be signed. {{ic|Optional}} here would turn off a global {{ic|Required}} for this repository.<br />
<br />
{{Warning|The SigLevel {{ic|TrustAll}} option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use {{ic|TrustedOnly}} for all official repositories.}}<br />
<br />
=== Initializing the keyring ===<br />
<br />
To initialize the ''pacman'' keyring run:<br />
<br />
# pacman-key --init<br />
<br />
== Managing the keyring ==<br />
<br />
=== Verifying the master keys ===<br />
<br />
The initial setup of keys is achieved using:<br />
<br />
# pacman-key --populate<br />
<br />
Take time to verify the [https://archlinux.org/master-keys/ Master Signing Keys] when prompted as these are used to co-sign (and therefore trust) all other packager's keys.<br />
<br />
OpenPGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the '(short) key ID' (the last ''sixteen'' digits of the fingerprint would be the 'long key ID').<br />
<br />
=== Adding developer keys ===<br />
<br />
The official Developers' and [[Package Maintainers]]' keys are signed by the master keys, so you do not need to use ''pacman-key'' to sign them yourself. Whenever ''pacman'' encounters a key it does not recognize, it will prompt you to download it from a {{ic|keyserver}} configured in {{ic|/etc/pacman.d/gnupg/gpg.conf}} (or by using the {{ic|--keyserver}} option on the command line). Wikipedia maintains a [[wikipedia:Key server (cryptographic)|list of keyservers]].<br />
<br />
Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.<br />
<br />
{{Note|The {{Pkg|archlinux-keyring}} package, which is a dependency of {{Pkg|pacman}}, contains the latest keys. However keys can also be updated manually using {{ic|pacman-key --refresh-keys}} (as root). While doing {{ic|--refresh-keys}}, your local key will also be looked up on the remote keyserver, and you will receive a message about it not being found. This is nothing to be concerned about.}}<br />
<br />
=== Adding unofficial keys ===<br />
<br />
{{Expansion|Explain how to roll out custom keyring packages following {{Pkg|archlinux-keyring}}.|Talk:Pacman/Package_signing#Addition_of_guide_to_create_unofficial_keyrings}}<br />
<br />
This method can be utilized to add a key to the ''pacman'' keyring, or to enable signed [[unofficial user repositories]].<br />
<br />
First, get the '''key ID''' ({{ic|''keyid''}}) from its owner. Then add it to the keyring using one of the two methods:<br />
<br />
# If the key is found on a keyserver, import it with: {{bc|# pacman-key --recv-keys ''keyid''}}<br />
# If otherwise a link to a keyfile is provided, download it and then run: {{bc|# pacman-key --add ''/path/to/downloaded/keyfile''}}<br />
<br />
It is recommended to verify the fingerprint, as with any master key or any other key you are going to sign:<br />
<br />
$ pacman-key --finger ''keyid''<br />
<br />
Finally, you must locally sign the imported key:<br />
<br />
# pacman-key --lsign-key ''keyid''<br />
<br />
You now trust this key to sign packages.<br />
<br />
=== Debugging with gpg ===<br />
<br />
For debugging purposes, you can access ''pacman'''s keyring directly with ''gpg'', e.g.:<br />
<br />
# gpg --homedir /etc/pacman.d/gnupg --list-keys<br />
<br />
== Tips and tricks ==<br />
<br />
=== Upgrade system regularly ===<br />
<br />
Upgrading the system regularly via [[pacman#Upgrading packages]] prevents most signing errors. If delay is unavoidable and system upgrade gets delayed for an extended period, manually sync the package database and upgrade the {{Pkg|archlinux-keyring}} package before system upgrade:<br />
<br />
# pacman -Sy archlinux-keyring && pacman -Su<br />
<br />
This command is not considered a [[partial upgrade]] since it syncs the package database and upgrades the keyring package first. Both must be processed just before starting system upgrade to ensure signatures of all upgraded packages can be properly verified.<br />
<br />
{{Note|1=Since [https://gitlab.archlinux.org/archlinux/archlinux-keyring/-/commit/ad8698e96c423dfc68405b547f310f2e1075a95d 2022-07-29], the {{ic|archlinux-keyring-wkd-sync.service}} and the associated [[systemd timer]] have been created and enabled by default, solving {{ic|signature from "''Some Developer'' <''developer_email''@archlinux.org>" is marginal trust}} issues (e.g. [https://bbs.archlinux.org/viewtopic.php?id=278332 BBS#278332]) without requiring any user intervention, by fetching new signatures of already trusted keys once a week.}}<br />
<br />
=== Update system time regularly ===<br />
<br />
When the [[system time]] is faulty, signing keys could be considered expired (or invalid) and signature checks on packages will fail. Synchronize the system clock regularly by using the [[Network Time Protocol daemon]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Invalid signature errors ===<br />
<br />
''pacman-key'' depends on [[system time]]. If your system clock is not synchronized, system installation/upgrade may fail with:<br />
<br />
error: PackageName: signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occurred, no packages were upgraded.<br />
<br />
If using ntpd, correct the system time (as root) with {{ic|ntpd -qg}} followed by {{ic|hwclock -w}}.<br />
<br />
Other NTP clients can be used. See [[time synchronization]].<br />
<br />
If correction of the system clock does not resolve the failure, try one of the following approaches:<br />
<br />
==== Removing packages from cache ====<br />
<br />
Some packages could be corrupted or may be unsigned, causing failure. Remove each offending package from the system cache {{ic|rm /var/cache/pacman/pkg/''pkgname''}} so it gets freshly downloaded, or [[pacman#Cleaning the package cache|clear the entire cache]].<br />
<br />
==== Resetting all the keys ====<br />
<br />
Remove or reset all the keys installed in your system by removing the {{ic|/etc/pacman.d/gnupg}} directory (as root) and by rerunning {{ic|pacman-key --init}} followed by {{ic|pacman-key --populate}} to re-add the default keys.<br />
<br />
==== Disabling signature checking ====<br />
<br />
{{Warning|Use with caution. Disabling package signing will allow ''pacman'' to install untrusted packages.}}<br />
<br />
If you are not concerned about package signing, you can disable OpenPGP signature checking completely. Edit {{ic|/etc/pacman.conf}} to have the following lines under {{ic|[options]}}:<br />
<br />
SigLevel = Never<br />
#LocalFileSigLevel = Optional<br />
#RemoteFileSigLevel = Required<br />
<br />
You need to comment out any repository-specific {{ic|SigLevel}} settings because they override the global settings. This will result in no signature checking, which was the behavior before pacman 4. If you do this, you do not need to set up a keyring with ''pacman-key''. You can change those options later if you decide to enable package verification.<br />
<br />
=== Cannot import keys ===<br />
<br />
{{Style|Instructions could be clearer. Not clear how this section is different from the preceding one. Redundant information.}}<br />
<br />
There are multiple possible sources of this problem:<br />
<br />
* An outdated {{Pkg|archlinux-keyring}} package.<br />
* The clock being set to an incorrect date.<br />
* Your ISP blocked the port used to import OpenPGP keys.<br />
* Your ''pacman'' cache contains copies of unsigned packages from previous attempts.<br />
* {{ic|dirmngr}} is not correctly configured.<br />
<br />
You might be stuck because of an outdated {{Pkg|archlinux-keyring}} package when doing an upgrade synchronization.<br />
<br />
Below are a few solutions that could work depending on your case.<br />
<br />
==== Upgrade the system ====<br />
<br />
See if [[Pacman#Upgrading packages|upgrading the system]] can fix it first.<br />
<br />
==== Change keyserver ====<br />
<br />
If you suspect that something is not working right with the keyserver, you could try to switch to the Ubuntu keyserver. To do this, edit {{ic|/etc/pacman.d/gnupg/gpg.conf}} and change the {{ic|keyserver}} line to:<br />
<br />
keyserver hkp://keyserver.ubuntu.com<br />
<br />
==== Clean cached packages ====<br />
<br />
If you suspect that your pacman cache at {{ic|/var/cache/pacman/pkg/}} might contain unsigned packages, try cleaning the cache manually or run:<br />
<br />
# pacman -Sc<br />
<br />
which removes all cached packages that have not been installed.<br />
<br />
=== Signature is unknown trust ===<br />
<br />
Sometimes when running {{ic|pacman -Syu}} you might encounter this error:<br />
<br />
error: ''package-name'': signature from "''packager''" is unknown trust<br />
<br />
This occurs because the {{ic|''packager''}}'s key used in the package {{ic|''package-name''}} is not present and/or not trusted in the local pacman-key gpg database. Pacman does not seem to always be able to check if the key was received and marked as trusted before continuing. This could also be because a key has expired since it was added to your keychain.<br />
<br />
Mitigate by:<br />
<br />
* [[#Upgrade system regularly|Manually upgrading the archlinux-keyring package prior to the system upgrade]], or<br />
* refreshing your keys with {{ic|pacman-key --refresh-keys}}, or<br />
* [[#Resetting all the keys|resetting all the keys]], or<br />
* [[#Adding unofficial keys|manually signing the untrusted key locally]] (not recommended), or<br />
* setting temporarily {{ic|SigLevel}} to {{ic|TrustAll}} (not recommended).<br />
<br />
The last two options above break the chain of trust, and should be used with care.<br />
<br />
=== Updating keys via proxy ===<br />
<br />
In order to use a proxy when updating keys the {{ic|honor-http-proxy}} option must be set in both {{ic|/etc/gnupg/dirmngr.conf}} and {{ic|/etc/pacman.d/gnupg/dirmngr.conf}}. See [[GnuPG#Use a keyserver]] for more information.<br />
<br />
{{Note|If ''pacman-key'' is used without the {{ic|honor-http-proxy}} option and fails, a reboot may solve the issue.}}<br />
<br />
== See also ==<br />
<br />
* [[DeveloperWiki:Package Signing Proposal for Pacman]]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-1-makepkg-and-repo-add/ Pacman Package Signing – 1: Makepkg and Repo-add]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-2-pacman-key/ Pacman Package Signing – 2: Pacman-key]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-3-pacman/ Pacman Package Signing – 3: Pacman]<br />
* [http://allanmcrae.com/2011/12/pacman-package-signing-4-arch-linux/ Pacman Package Signing – 4: Arch Linux]</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Systemd-timesyncd&diff=796160Talk:Systemd-timesyncd2024-01-06T03:44:36Z<p>Regid: /* {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length */ Clarifying in a way that does not change Hanabishi comment</p>
<hr />
<div>== {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length ==<br />
<br />
Quoting [[Systemd-timesyncd#Configuration]]:<br />
:{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
For me, it is a zero (0) length file. Seems reasonable, but I haven't verified, it is using {{man|1|touch}}, or an equivalent. My point is the file is actually used, even though it is of zero (0) length. No real data is actually stored within it, as someone may naively expect. Not sure it is trivial, or worth pointing out. Is it acceptable to change to:<br />
:{{Note|The service uses the times ({{man|1|touch}}) of the zero (0) length local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
[[User:Regid|Regid]] ([[User talk:Regid|talk]]) 02:34, 5 January 2024 (UTC)<br />
<br />
:The file is actually used. And yes, systemd-timesyncd service relies on the modified time metadata.<br />
:[[User:Hanabishi|Hanabishi]] ([[User talk:Hanabishi|talk]]) 04:05, 5 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Systemd-timesyncd&diff=796076Talk:Systemd-timesyncd2024-01-05T02:40:10Z<p>Regid: /* {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length */ typing error</p>
<hr />
<div>== {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length ==<br />
<br />
Quoting [[Systemd-timesyncd#Configuration]]:<br />
:{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
For me, it is a zero (0) length file. Seems reasonable, but I haven't verified, it is using {{man|1|touch}}, or an equivalent. My point is the file is actually used, even though it is of zero (0) length. It is not written to as someone may naively expect. Not sure it is trivial, or worth pointing out. Is it acceptable to change to:<br />
:{{Note|The service uses the times ({{man|1|touch}}) of the zero (0) length local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
[[User:Regid|Regid]] ([[User talk:Regid|talk]]) 02:34, 5 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Systemd-timesyncd&diff=796075Talk:Systemd-timesyncd2024-01-05T02:39:25Z<p>Regid: /* {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length */ touch could be a better choice.</p>
<hr />
<div>== {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length ==<br />
<br />
Quoting [[Systemd-timesyncd#Configuration]]:<br />
:{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
For me, it is a zero (0) length file. Seems reasonable, but I haven't verified, it is using {{man|1|touch}}, or an equivalent. My point is the file is actually used, even though it is of zero (0) length. It is not written to as someone may naively expect. Not sure it is trivial, or worth pointing out. Is it acceptable to change to:<br />
:{{Note|The service uses the times ({{man|1|toucht}}) of the zero (0) length local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
[[User:Regid|Regid]] ([[User talk:Regid|talk]]) 02:34, 5 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Systemd-timesyncd&diff=796074Talk:Systemd-timesyncd2024-01-05T02:36:42Z<p>Regid: /* {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length */ Clarifying</p>
<hr />
<div>== {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length ==<br />
<br />
Quoting [[Systemd-timesyncd#Configuration]]:<br />
:{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
For me, it is a zero (0) length file. Seems reasonable, but I haven't verified, that it is using {{man|1|stat}}, or an equivalent. My point is the file is actually used, even though it is of zero (0) length. It is not written to as someone may naively expect. Not sure it is trivial, or worth pointing out. Is it acceptable to change to:<br />
:{{Note|The service uses the times ({{man|1|stat}}) of the zero (0) length local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
[[User:Regid|Regid]] ([[User talk:Regid|talk]]) 02:34, 5 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Systemd-timesyncd&diff=796073Talk:Systemd-timesyncd2024-01-05T02:34:59Z<p>Regid: /* /var/lib/systemd/timesync/clock is used even though it is of zero (0) length */ new section</p>
<hr />
<div>== {{ic|/var/lib/systemd/timesync/clock}} is used even though it is of zero (0) length ==<br />
<br />
Quoting [[Systemd-timesyncd#Configuration]]:<br />
:{{Note|The service writes to a local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
For me, it is a zero (0) length file. Seems reasonable, but I haven't verified, that it is using {{man|1|stat}}, or an equivalent. My point is the file is actually used, even though it is of zero (0) length. Not sure it is trivial, or worth pointing out. Is it acceptable to change to:<br />
:{{Note|The service uses the times ({{man|1|stat}}) of the zero (0) length local file {{ic|/var/lib/systemd/timesync/clock}} with every synchronization.}}<br />
[[User:Regid|Regid]] ([[User talk:Regid|talk]]) 02:34, 5 January 2024 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Extended_attributes&diff=795983Talk:Extended attributes2024-01-04T02:13:39Z<p>Regid: /* Gnome/Nautilus support for xfattr through Eiciel */ Following Help:Discussion#Closing a discussion and deleting this exhausted discussion</p>
<hr />
<div></div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Extended_attributes&diff=795982Talk:Extended attributes2024-01-04T02:12:32Z<p>Regid: /* NFS supports extended file attributes */ Following Help:Discussion#Closing a discussion and deleting this exhausted discussion</p>
<hr />
<div>== <s>Gnome/Nautilus support for xfattr through Eiciel</s> ==<br />
<br />
Seems like nautilus doesn't remove xattrs, it just doesn't show them to uesrs or allow them to edit/add xfattrs by default. <br />
<br />
But full extended file attributes support can be added to Nautilus through Eiciel[https://aur.archlinux.org/packages/eiciel] and Eiciel Nautilus extension. Found in AUR.<br />
Eiciel is well-maintained and is working well on my system and is coherent with Gnome interface.<br />
<br />
Should we add this to the main extended attributes page?<br />
<br />
:: [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:25, 13 December 2023 (UTC)<br />
:Article was amended at {{special:diff/794793}}, by adding this information to the main [[extended attributes]] page. Following [[Help:Discussion#Closing a discussion]]. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:35, 20 December 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Extended_attributes&diff=795981Talk:Extended attributes2024-01-04T02:10:43Z<p>Regid: /* Date column */ Following request in topic and Help:Discussion#Closing a discussion to delete this exhausted discussion</p>
<hr />
<div>== <s>NFS supports extended file attributes</s> ==<br />
<br />
https://www.phoronix.com/news/Linux-5.9-NFS-Server-User-Xattr<br />
<br />
I have also tested that with NFSv4 and it worked correctly. xattrs of my file didn't go anywhere after moving or copying it to nfs mounted storage. <br />
</br><br />
[[User:Arash|Arash]] ([[User talk:Arash|talk]]) 12:57, 13 December 2023 (UTC)<br />
:Fixed the article at {{special:Diff/794739}}. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 09:45, 18 December 2023 (UTC)<br />
<br />
== <s>Gnome/Nautilus support for xfattr through Eiciel</s> ==<br />
<br />
Seems like nautilus doesn't remove xattrs, it just doesn't show them to uesrs or allow them to edit/add xfattrs by default. <br />
<br />
But full extended file attributes support can be added to Nautilus through Eiciel[https://aur.archlinux.org/packages/eiciel] and Eiciel Nautilus extension. Found in AUR.<br />
Eiciel is well-maintained and is working well on my system and is coherent with Gnome interface.<br />
<br />
Should we add this to the main extended attributes page?<br />
<br />
:: [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:25, 13 December 2023 (UTC)<br />
:Article was amended at {{special:diff/794793}}, by adding this information to the main [[extended attributes]] page. Following [[Help:Discussion#Closing a discussion]]. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:35, 20 December 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Intel_graphics&diff=795790Intel graphics2024-01-01T19:55:32Z<p>Regid: /* Installation */ Less then 10 years is a moving target, which is not the intention here.</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[de:Intel]]<br />
[[es:Intel graphics]]<br />
[[ja:Intel graphics]]<br />
[[ru:Intel graphics]]<br />
[[zh-hans:Intel graphics]]<br />
{{Related articles start}}<br />
{{Related|Intel GMA 3600}}<br />
{{Related|Xorg}}<br />
{{Related|Kernel mode setting}}<br />
{{Related|Xrandr}}<br />
{{Related|Hybrid graphics}}<br />
{{Related|Vulkan}}<br />
{{Related|GPGPU}}<br />
{{Related articles end}}<br />
<br />
Since Intel provides and supports open source drivers, Intel graphics are essentially plug-and-play.<br />
<br />
For a comprehensive list of Intel GPU models and corresponding chipsets and CPUs, see [[Wikipedia:Intel Graphics Technology]] and [[Gentoo:Intel#Feature support]].<br />
<br />
{{Note|<br />
* PowerVR-based graphics ([[Intel GMA 3600|GMA 3600]] series) are not supported by open source drivers.<br />
* Intel's Gen''N'' hardware does not refer to the generation of the CPU, it refers to the [[Wikipedia:List of Intel graphics processing units|generation of the GPU]], which is different from the generation of the CPU. <br />
* See [[Xorg#Driver installation]] to identify your card. <br />
}}<br />
<br />
== Installation ==<br />
<br />
* [[Install]] one of the following packages, which provide the [[wikipedia:Direct Rendering Infrastructure|DRI]] driver for 3D acceleration.<br />
** {{Pkg|mesa}} is the up-to-date [[Mesa]] package which includes the modern Gallium3D drivers for Gen 3 hardware and later. This is the recommended choice.<br />
** {{Pkg|mesa-amber}} is the legacy Mesa package which includes the classic (non-Gallium3D) drivers from Gen 2 to Gen 11 hardware. This driver might have better performance or stability for Gen 7 and older hardware, but is unmaintained.<br />
* For 32-bit application support, also install the {{Pkg|lib32-mesa}} or {{Pkg|lib32-mesa-amber}} package from the [[multilib]] repository.<br />
* For the [[wikipedia:X.Org_Server#DDX|DDX]] driver which provides 2D acceleration in [[Xorg]] use one of the following drivers:<br />
** The ''modesetting'' driver included in the {{Pkg|xorg-server}} package is the recommended choice for Gen 4 hardware and later. It uses the DRI driver for acceleration via ''glamor''. As a rule of thumb, if you have a very old system, you can use the intel ddx along with mesa-amber (NOT mesa!), for hardware from after 2013, you should be using the modesetting ddx with mesa.[https://gitlab.archlinux.org/archlinux/packaging/packages/mesa/-/issues/5#note_152917][https://bbs.archlinux.org/viewtopic.php?pid=1731412#p1731412] To iterate, using modesetting ddx can be achieved by not installing any xf86-video package.<br />
** The {{Pkg|xf86-video-intel}} package provides the legacy intel DDX driver from Gen 2 to Gen 9 hardware. This package is generally not recommended, see note below.<br />
* For [[Vulkan]] support (Haswell and newer; support for earlier chips is [https://gitlab.freedesktop.org/mesa/mesa/-/issues/8249#note_1758622 incomplete or missing]), install the {{Pkg|vulkan-intel}} package. For 32-bit [[Vulkan]] support, install the {{Pkg|lib32-vulkan-intel}} package.<br />
<br />
Also see [[Hardware video acceleration]].<br />
<br />
{{Note|1=<nowiki/><br />
* Some ([https://www.phoronix.com/scan.php?page=news_item&px=Ubuntu-Debian-Abandon-Intel-DDX Debian & Ubuntu], [https://www.phoronix.com/scan.php?page=news_item&px=Fedora-Xorg-Intel-DDX-Switch Fedora], [https://community.kde.org/Plasma/5.9_Errata#Intel_GPUs KDE], [https://bugzilla.mozilla.org/show_bug.cgi?id=1710400 Mozilla]) recommend not installing the {{Pkg|xf86-video-intel}} driver, and instead falling back on the modesetting driver. See [https://web.archive.org/web/20160714232204/https://www.reddit.com/r/archlinux/comments/4cojj9/it_is_probably_time_to_ditch_xf86videointel/], [https://www.phoronix.com/scan.php?page=article&item=intel-modesetting-2017&num=1], [[Xorg#Installation]], and {{man|4|modesetting}}. However, the modesetting driver can cause problems such as [https://gitlab.freedesktop.org/xorg/xserver/-/issues/1364 screen tearing and mouse jittering on XFCE], [https://bugs.chromium.org/p/chromium/issues/detail?id=370022 artifacts when switching virtual desktops in Chromium], and [https://gitlab.freedesktop.org/xorg/xserver/-/issues/928 vsync jitter/video stutter in mpv].<br />
* The {{Pkg|xf86-video-intel}} driver does not have proper support for Gen 11 and newer hardware, causing lack of acceleration and rendering issues that make Plasma Desktop almost unusable. See [https://gitlab.freedesktop.org/xorg/driver/xf86-video-intel/-/commit/7181c5a41c3f00eaf996caa156523c708a18081e].<br />
* There have been couple reports [https://bbs.archlinux.org/viewtopic.php?id=263323] [https://github.com/qutebrowser/qutebrowser/issues/4641] where the whole graphics stack hard freezes when {{Pkg|xf86-video-intel}} is installed, not even switching to a different virtual console works (by pressing {{ic|Ctrl+Alt+F''n''}}), only killing the user processes with [[SysRq]] works.<br />
}}<br />
<br />
== Loading ==<br />
<br />
The Intel kernel module should load fine automatically on system boot.<br />
<br />
If it does not happen, then:<br />
<br />
* Make sure you do '''not''' have {{ic|nomodeset}} as a [[kernel parameter]], since Intel requires kernel mode-setting.<br />
* Also, check that you have not disabled Intel by using any modprobe blacklisting within {{ic|/etc/modprobe.d/}} or {{ic|/usr/lib/modprobe.d/}}.<br />
<br />
=== Enable early KMS ===<br />
<br />
{{Remove|Since [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/releases/v32 mkinitcpio v32], the {{ic|kms}} hook is included by default, therefore most setups will have early loading enabled by default.}}<br />
<br />
[[Kernel mode setting]] (KMS) is supported by Intel chipsets that use the i915 DRM driver and is mandatory and enabled by default.<br />
<br />
Early KMS should already be enabled for typical setups since [[mkinitcpio]] v32, as the {{ic|kms}} hook is included by default. For other setups, see [[Kernel mode setting#Early KMS start]] for instructions on how to enable KMS as soon as possible at the boot process.<br />
<br />
=== Enable GuC / HuC firmware loading ===<br />
<br />
{{Accuracy|Despite Intel's documentation, Tiger Lake and Rocket Lake GPUs may actually support {{ic|1=enable_guc=3}}, and have a default of {{ic|1=enable_guc=1}}.|Talk:Intel graphics#TGL/RKL GuC Submission}}<br />
<br />
Starting with Gen9 (Skylake and onwards), Intel GPUs include a ''Graphics micro (μ) Controller'' (GuC) which provides the following functionality [https://01.org/linuxgraphics/downloads/firmware]{{Dead link|2023|09|16|status=404}}:<br />
* Offloading some media decoding functionality from the CPU to the ''HEVC/H.265 micro (µ) Controller'' (HuC). Only applicable if using {{Pkg|intel-media-driver}} for [[hardware video acceleration]]. Introduced with Gen9.<br />
* Using the GuC for scheduling, context submission, and power management. Introduced with Alder Lake-P (Mobile), within Gen12.<br />
<br />
To use this functionality, the GuC firmware must be loaded. With regards to HuC support, some video features (e.g. CBR rate control on SKL low-power encoding mode) require loading the HuC firmware as well [https://github.com/intel/media-driver#known-issues-and-limitations]. The GuC and HuC firmware files are both provided by {{Pkg|linux-firmware}}.<br />
<br />
GuC functionality is controlled by the {{ic|1=i915.enable_guc}} [[kernel parameter]]. Its usage is as follows:<br />
<br />
{| class="wikitable"<br />
! enable_guc value !! GuC Submission !! HuC Firmware Loading !! Default for platforms !! Supported on platforms<br />
|-<br />
|0 || {{No}} || {{No}} || Tiger Lake, Rocket Lake, and Pre-Gen12 [https://github.com/torvalds/linux/blob/b3454ce0b2c8a56e760e6baa88ed10278585072b/drivers/gpu/drm/i915/gt/uc/intel_uc.c#L26-L36] || All<br />
|-<br />
|1 || {{Yes}} || {{No}} || {{-}} || Alder Lake-P (Mobile) and newer<br />
|-<br />
|2 || {{No}} || {{Yes}} || Alder Lake-S (Desktop) [https://github.com/torvalds/linux/blob/b3454ce0b2c8a56e760e6baa88ed10278585072b/drivers/gpu/drm/i915/gt/uc/intel_uc.c#L38-L42] [https://lore.kernel.org/all/87ee6wit2r.fsf@intel.com/T/] || Gen9 and newer<br />
|-<br />
|3 || {{Yes}} || {{Yes}} || colspan="2" {{C|Alder Lake-P (Mobile) and newer}}<br />
|}<br />
<br />
If GuC submission or HuC firmware loading is not enabled by default for your GPU, you can manually enable it.<br />
<br />
{{Warning|1=Manually enabling GuC / HuC firmware loading taints the kernel [https://bugs.freedesktop.org/show_bug.cgi?id=111918 even when the feature is not supported]. Moreover, enabling GuC/HuC firmware loading can cause issues on some systems; disable it if you experience freezing (for example, after resuming from hibernation).}}<br />
<br />
First, ensure that {{Pkg|linux-firmware}} is [[install]]ed.<br />
<br />
Set the {{ic|1=i915.enable_guc}} [[kernel parameter]], for example with:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 enable_guc=2<br />
}}<br />
<br />
[[Regenerate the initramfs]], on next boot you can verify both GuC and HuC are enabled by using [[dmesg]]:<br />
<br />
{{hc|# dmesg|2=<br />
[30130.586970] i915 0000:00:02.0: [drm] GuC firmware i915/icl_guc_33.0.0.bin version 33.0 submission:disabled<br />
[30130.586973] i915 0000:00:02.0: [drm] HuC firmware i915/icl_huc_9.0.0.bin version 9.0 authenticated:yes<br />
}}<br />
<br />
If they are not supported by your graphics adapter you will see:<br />
<br />
{{hc|# dmesg|2=<br />
[ 0.571339] i915 0000:00:02.0: [drm] Incompatible option enable_guc=2 - GuC is not supported!<br />
[ 0.571340] i915 0000:00:02.0: [drm] Incompatible option enable_guc=2 - HuC is not supported!<br />
}}<br />
<br />
Alternatively, check using:<br />
<br />
# cat /sys/kernel/debug/dri/0/gt/uc/guc_info<br />
# cat /sys/kernel/debug/dri/0/gt/uc/huc_info<br />
<br />
{{Note|1=Using [[Intel GVT-g|GVT-g graphics virtualization]] by setting {{ic|1=enable_gvt=1}} is not supported as of linux 4.20.11 when GuC/HuC is also enabled. The i915 module would fail to initialize as shown in system journal.<br />
<br />
{{hc|# journalctl|<br />
... kernel: [drm:intel_gvt_init [i915]] *ERROR* i915 GVT-g loading failed due to Graphics virtualization is not yet supported with GuC submission<br />
... kernel: i915 0000:00:02.0: [drm:i915_driver_load [i915]] Device initialization failed (-5)<br />
... kernel: i915: probe of 0000:00:02.0 failed with error -5<br />
... kernel: snd_hda_intel 0000:00:1f.3: failed to add i915 component master (-19)<br />
}}<br />
<br />
Note that the related warning is not fatal, as explained in [https://github.com/intel/gvt-linux/issues/77#issuecomment-707541069]:<br />
<br />
{{hc|# journalctl -b |<br />
... kernel: i915 0000:00:02.0: Direct firmware load for i915/gvt/vid_0x8086_did_0x5916_rid_0x02.golden_hw_state failed with error -2<br />
}}<br />
}}<br />
<br />
== Xorg configuration ==<br />
<br />
There is generally no need for any configuration to run [[Xorg]].<br />
<br />
However, to take advantage of some driver options or if [[Xorg]] does not start, you can create an Xorg configuration file.<br />
<br />
=== With the modesetting driver ===<br />
<br />
If you have installed {{Pkg|xf86-video-intel}} but want to load the modesetting driver explicitly instead of letting the DDX driver take priority, for example when trying to compare them:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "modesetting"<br />
EndSection<br />
}}<br />
<br />
=== With the Intel driver ===<br />
<br />
{{Note|The following requires {{Pkg|xf86-video-intel}}.}}<br />
<br />
Create an Xorg configuration file similar to the one below:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
EndSection<br />
}}<br />
<br />
Additional options are added by the user on new lines below {{ic|Driver}}.<br />
For the full list of options, see the {{man|4|intel}} man page.<br />
<br />
{{Note|You might need to add more device sections than the one listed above. This will be indicated where necessary.}}<br />
<br />
==== AccelMethod ====<br />
<br />
You may need to indicate {{ic|Option "AccelMethod"}} when creating a configuration file, the classical options are {{ic|UXA}}, {{ic|SNA}} (default) and {{ic|BLT}}.<br />
<br />
If you experience issues with default {{ic|SNA}} (e.g. pixelated graphics, corrupt text, etc.), try using {{ic|UXA}} instead, which can be done by adding the following line to your [[#Xorg configuration|configuration file]]:<br />
<br />
Option "AccelMethod" "uxa"<br />
<br />
See the "AccelMethod" option under {{man|4|intel|CONFIGURATION DETAILS}}.<br />
<br />
==== Using Intel DDX driver with recent GPUs ====<br />
<br />
For Intel GPUs starting from Gen8 (Broadwell), the Iris Mesa driver is needed:<br />
<br />
Option "DRI" "iris"<br />
<br />
==== Disabling TearFree, TripleBuffer, SwapbuffersWait ====<br />
<br />
If you use a compositor (the default in modern desktop environment like GNOME, KDE Plasma, Xfce, etc.), then TearFree, TripleBuffer and SwapbuffersWait can usually be disabled to improve performance and decrease power consumption.<br />
<br />
Option "TearFree" "false"<br />
Option "TripleBuffer" "false"<br />
Option "SwapbuffersWait" "false"<br />
<br />
== Module-based options ==<br />
<br />
The {{ic|i915}} kernel module allows for configuration via [[Kernel modules#Setting module options|module options]]. Some of the module options impact power saving.<br />
<br />
A list of all options along with short descriptions and default values can be generated with the following command:<br />
<br />
$ modinfo -p i915<br />
<br />
To check which options are currently enabled, run<br />
<br />
# systool -m i915 -av<br />
<br />
You will note that many options default to -1, resulting in per-chip powersaving defaults. It is however possible to configure more aggressive powersaving by using [[Kernel modules#Setting module options|module options]].<br />
<br />
{{Note|1=Diverting from the defaults will mark the kernel as [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=fc9740cebc3ab7c65f3c5f6ce0caf3e4969013ca tainted] from Linux 3.18 onwards. This basically implies using other options than the per-chip defaults is considered experimental and not supported by the developers. }}<br />
<br />
=== Framebuffer compression (enable_fbc) ===<br />
<br />
Framebuffer compression (FBC) is a feature that can reduce power consumption and memory bandwidth during screen refreshes.<br />
<br />
The feature will be automatically enabled if supported by the hardware. You can use the command below to verify whether it is is enabled:<br />
<br />
{{hc|$ modinfo i915 {{!}} grep enable_fbc|<br />
parm: enable_fbc:Enable frame buffer compression for power savings (default: -1 (use per-chip default)) (int)<br />
}}<br />
<br />
If the parm is set to {{ic|-1}}, you do not need to do anything. Otherwise, to force-enable FBC, use {{ic|1=i915.enable_fbc=1}} as [[kernel parameter]] or set in {{ic|/etc/modprobe.d/i915.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 enable_fbc=1<br />
}}<br />
<br />
{{Note|Framebuffer compression may be unreliable or unavailable on Intel GPU generations before Sandy Bridge (generation 6). This results in messages logged to the system journal similar to this one:<br />
<br />
kernel: drm: not enough stolen space for compressed buffer, disabling.<br />
<br />
Enabling frame buffer compression on pre-Sandy Bridge CPUs results in endless error messages:<br />
<br />
{{hc|# dmesg|<br />
[ 2360.475430] [drm] not enough stolen space for compressed buffer (need 4325376 bytes), disabling<br />
[ 2360.475437] [drm] hint: you may be able to increase stolen memory size in the BIOS to avoid this<br />
}}<br />
<br />
The solution is to disable frame buffer compression which will imperceptibly increase power consumption (around 0.06 W). In order to disable it add {{ic|1=i915.enable_fbc=0}} to the kernel line parameters. More information on the results of disabled compression can be found [https://web.archive.org/web/20200228230053/https://kernel.ubuntu.com/~cking/power-benchmarking/background-colour-and-framebuffer-compression/ here].}}<br />
<br />
=== Fastboot ===<br />
<br />
{{Note|1=This parameter is enabled by default for Skylake and newer[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=3d6535cbed4a4b029602ff83efb2adec7cb8d28b] as well as Bay- and Cherry-Trail (VLV/CHV)[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=7360c9f6b857e22a48e545f4e99c79630994e932] since Linux 5.1.[https://kernelnewbies.org/Linux_5.1#Graphics]}}<br />
<br />
The goal of Intel Fastboot is to preserve the frame-buffer as setup by the BIOS or [[boot loader]] to avoid any flickering until [[Xorg]] has started.[https://lists.freedesktop.org/archives/intel-gfx/2012-May/017653.html][https://www.phoronix.com/scan.php?page=news_item&px=MTEwNzc]<br />
<br />
To force enable fastboot on platforms where it is not the default already, set {{ic|1=i915.fastboot=1}} as [[kernel parameter]] or set in {{ic|/etc/modprobe.d/i915.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 fastboot=1<br />
}}<br />
<br />
=== Intel GVT-g graphics virtualization support ===<br />
<br />
See [[Intel GVT-g]] for details.<br />
<br />
=== Enable performance support ===<br />
<br />
{{Expansion|What does Mesa actually do using the performance counters? What's the effect of this? Some report drastic performance increases on Intel Tiger Lake, attributing it to a support for Dynamic Tuning [https://www.reddit.com/r/linux/comments/u7zxa0/psa_for_intel_tiger_lake_dynamic_tuning_laptops/].|section=Potential performance gains via Observation Architecture}}<br />
<br />
Starting with Gen6 (Sandy Bridge and onwards), Intel GPUs provide performance counters used for exposing internal performance data to drivers. The drivers and hardware registers refer to this infrastructure as the ''Observation Architecture'' (internally "OA") [https://www.phoronix.com/scan.php?page=news_item&px=Intel-HSW-Observation-Arch], but Intel's documentation also more generally refers to this functionality as providing ''Observability Performance Counters'' [https://01.org/sites/default/files/documentation/observability_performance_counters_haswell.pdf]{{Dead link|2023|09|16|status=404}} [https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol14-observability.pdf]{{Dead link|2023|09|16|status=404}}.<br />
<br />
By default, only programs running with the [https://lwn.net/Articles/486306/ CAP_SYS_ADMIN] (equivalent to root) or [https://lwn.net/Articles/812719/ CAP_PERFMON] [[capabilities]] can utilize the observation architecture [https://github.com/torvalds/linux/blob/b14ffae378aa1db993e62b01392e70d1e585fb23/drivers/gpu/drm/i915/i915_perf.c#L267] [https://github.com/torvalds/linux/blob/b14ffae378aa1db993e62b01392e70d1e585fb23/drivers/gpu/drm/i915/i915_perf.c#L3481-L3484]. Most applications will be running without either of these, resulting in the following warning:<br />
<br />
MESA-INTEL: warning: Performance support disabled, consider sysctl dev.i915.perf_stream_paranoid=0<br />
<br />
To enable performance support without using the capabilities (or root), set the kernel parameter as described in [[sysctl]].<br />
<br />
{{Warning|The restrictive defaults of the {{ic|perf_event_paranoid}} family of options exists because there is risk associated with allowing applications to access performance data [https://docs.kernel.org/admin-guide/perf-security.html]. With this being said, {{ic|dev.i915.perf_stream_paranoid}} only influences access to GPU performance counters, which carry less risk than e.g. CPU architectural execution context registers.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Setting scaling mode ===<br />
<br />
This can be useful for some full screen applications:<br />
<br />
$ xrandr --output LVDS1 --set PANEL_FITTING ''param''<br />
<br />
where {{ic|''param''}} can be:<br />
<br />
* {{ic|center}}: resolution will be kept exactly as defined, no scaling will be made,<br />
* {{ic|full}}: scale the resolution so it uses the entire screen or<br />
* {{ic|full_aspect}}: scale the resolution to the maximum possible but keep the aspect ratio.<br />
<br />
If it does not work, try:<br />
<br />
$ xrandr --output LVDS1 --set "scaling mode" ''param''<br />
<br />
where {{ic|''param''}} is one of {{ic|"Full"}}, {{ic|"Center"}} or {{ic|"Full aspect"}}.<br />
<br />
{{Note|1=This option currently does not work for external displays (e.g. VGA, DVI, HDMI, DP). [https://bugs.freedesktop.org/show_bug.cgi?id=90989]}}<br />
<br />
=== Hardware accelerated H.264 decoding on GMA 4500 ===<br />
<br />
The {{Pkg|libva-intel-driver}} package only provides hardware accelerated MPEG-2 decoding – and not H.264 decoding – for some GMA 4500 series GPUs. To check whether that affects your particular GPU, install both that driver and the {{Pkg|libva-utils}} package, then check the output of the {{ic|vainfo}} tool for the presence of entries that start with {{ic|VAProfileH264}}.<br />
<br />
The H.264 decoding support is maintained in a separated g45-h264 branch, which can be used by installing {{AUR|libva-intel-driver-g45-h264}} package. Note, however, that this support is experimental and its development has been abandoned. Using the VA-API with this driver on a GMA 4500 series GPU will offload the CPU but may not result in as smooth a playback as non-accelerated playback. Tests using mplayer showed that using vaapi to play back an H.264 encoded 1080p video halved the CPU load (compared to the XV overlay) but resulted in very choppy playback, while 720p worked reasonably well [https://bbs.archlinux.org/viewtopic.php?id=150550]. This is echoed by other experiences [https://web.archive.org/web/20160325142959/http://www.emmolution.org/?p=192&cpage=1#comment-12292]. Setting the preallocated video ram size higher in BIOS results in much better hardware decoded playback. Even 1080p h264 works well if this is done[https://lists.libreplanet.org/archive/html/guix-patches/2019-11/msg00652.html]. Smooth playback (1080p/720p) works also with {{AUR|mpv-git}} in combination with {{AUR|ffmpeg-git}} and {{AUR|libva-intel-driver-g45-h264}}. With MPV and the Firefox plugin "Send to MPV player"[https://addons.mozilla.org/firefox/addon/send-to-mpv-player/] it is possible to watch hardware accelerated YouTube videos.<br />
<br />
=== Overriding reported OpenGL version ===<br />
<br />
The {{ic|MESA_GL_VERSION_OVERRIDE}} [[environment variable]] can be used to override the reported OpenGL version to any application. For example, setting {{ic|1=MESA_GL_VERSION_OVERRIDE=4.5}} will report OpenGL 4.5.<br />
<br />
{{Note|You can use this variable to report any known OpenGL version, even if it is not supported by the GPU. Some applications might no longer crash, some may start crashing - you probably do not want to set this variable globally.}}<br />
<br />
=== Monitoring ===<br />
<br />
{{Merge|Hardware video acceleration#Verification|This overlaps the content at the previously linked page and would probably be a better fit in a generic page instead of this one dedicated to Intel GPUs. Otherwise, [[Hardware video acceleration#Verification]] should be modified to link to each dedicated page instead of duplicating content.}}<br />
<br />
* {{App|intel_gpu_top|A top-like task monitor for Intel GPUs (requires root permissions).|https://gitlab.freedesktop.org/drm/igt-gpu-tools|{{Pkg|intel-gpu-tools}}}}<br />
* {{App|nvtop|GPUs process monitoring for AMD, Intel and NVIDIA (currently has very basic support for Intel GPUs).|https://github.com/Syllo/nvtop|{{Pkg|nvtop}}}}<br />
<br />
=== Setting brightness and gamma ===<br />
<br />
See [[Backlight]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Tearing ===<br />
<br />
==== With the Intel driver ====<br />
<br />
The SNA acceleration method causes tearing on some machines. To fix this, enable the {{ic|TearFree}} option in the {{Pkg|xf86-video-intel}} driver by adding the following line to your [[#Xorg configuration|configuration file]]:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "TearFree" "true"<br />
EndSection}}<br />
<br />
See the [https://bugs.freedesktop.org/show_bug.cgi?id=37686 original bug report] for more info.<br />
<br />
{{Note|1=<nowiki/><br />
* This option may not work when {{ic|SwapbuffersWait}} is {{ic|false}}.<br />
* This option may increase memory allocation considerably and reduce performance. [https://bugs.freedesktop.org/show_bug.cgi?id=37686#c123]<br />
* This option is problematic for applications that are very picky about vsync timing, like [[Wikipedia:Super Meat Boy|Super Meat Boy]].<br />
* This option does not work with UXA acceleration method, only with SNA.<br />
* For Intel UHD 620 or 630 you will need to add {{ic|Option "TripleBuffer" "true"}} in order for {{ic|TearFree}} to work.<br />
* It might be necessary to disable DRI3 by adding {{ic|Option "DRI" "2"}}, otherwise any fullsceen app (such as video playback) can break TearFree. [https://bugs.freedesktop.org/show_bug.cgi?id=96847#c7]<br />
}}<br />
<br />
==== With the modesetting driver ====<br />
<br />
TearFree support [https://gitlab.freedesktop.org/xorg/xserver/-/merge_requests/1006 was recently added] to the modesetting driver [https://www.phoronix.com/news/xf86-video-modesetting-TearFree][https://www.phoronix.com/news/Modesetting-TearFree-Merged]. As of November 2023, this patch has yet to reach a stable release, so you will need {{AUR|xorg-server-git}} until then.<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "modesetting"<br />
Option "TearFree" "true"<br />
EndSection}}<br />
<br />
=== Disable Vertical Synchronization (VSYNC) ===<br />
<br />
Useful when:<br />
<br />
* Chromium/Chrome has lags and slow performance due to GPU and runs smoothly with --disable-gpu switch<br />
* glxgears test does not show desired performance<br />
<br />
The intel-driver uses [https://www.intel.com/content/www/us/en/support/articles/000006930/graphics.html Triple Buffering] for vertical synchronization; this allows for full performance and avoids tearing. To turn vertical synchronization off (e.g. for benchmarking) use this {{ic|.drirc}} in your home directory:<br />
<br />
{{hc|~/.drirc|2=<br />
<device screen="0" driver="dri2"><br />
<application name="Default"><br />
<option name="vblank_mode" value="0"/><br />
</application><br />
</device><br />
}}<br />
<br />
{{Note|Do not use {{AUR|driconf}} to create this file. It is buggy and will set the wrong driver.}}<br />
<br />
=== DRI3 issues ===<br />
<br />
''DRI3'' is the default DRI version in {{Pkg|xf86-video-intel}}. On some systems this can cause issues such as [https://bugs.chromium.org/p/chromium/issues/detail?id=370022 this]. To switch back to ''DRI2'' add the following line to your [[#Xorg configuration|configuration file]]:<br />
<br />
Option "DRI" "2"<br />
<br />
For the {{ic|modesetting}} driver, this method of disabling DRI3 does not work. Instead, one can set the environment variable {{ic|1=LIBGL_DRI3_DISABLE=1}}.<br />
<br />
=== Font and screen corruption in GTK applications (missing glyphs after suspend/resume) ===<br />
<br />
Should you experience missing font glyphs in GTK applications, the following workaround might help. [[textedit|Edit]] {{ic|/etc/environment}} to add the following line:<br />
<br />
{{hc|/etc/environment|output=<br />
COGL_ATLAS_DEFAULT_BLIT_MODE=framebuffer<br />
}}<br />
<br />
See also [https://bugs.freedesktop.org/show_bug.cgi?id=88584 FreeDesktop bug 88584].<br />
<br />
=== Blank screen during boot, when "Loading modules" ===<br />
<br />
{{Remove|Since [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/releases/v32 mkinitcpio v32], the {{ic|kms}} hook is included by default, therefore most setups will have early loading enabled by default.}}<br />
<br />
If using "late start" KMS and the screen goes blank when "Loading modules", it may help to add {{ic|i915}} and {{ic|intel_agp}} to the initramfs. See [[Kernel mode setting#Early KMS start]] section.<br />
<br />
Alternatively, appending the following [[kernel parameter]] seems to work as well:<br />
<br />
video=SVIDEO-1:d<br />
<br />
If you need to output to VGA then try this:<br />
<br />
video=VGA-1:1280x800<br />
<br />
=== X freeze/crash with intel driver ===<br />
<br />
Some issues with X crashing, GPU hanging, or problems with X freezing, can be fixed by disabling the GPU usage with the {{ic|NoAccel}} option - add the following lines to your [[#Xorg configuration|configuration file]]:<br />
<br />
Option "NoAccel" "True"<br />
<br />
Alternatively, try to disable the 3D acceleration only with the {{ic|DRI}} option:<br />
<br />
Option "DRI" "False"<br />
<br />
=== Adding undetected resolutions ===<br />
<br />
This issue is covered on the [[Xrandr#Adding undetected resolutions|Xrandr page]].<br />
<br />
=== Backlight is not adjustable ===<br />
<br />
If after resuming from suspend, the hotkeys for changing the screen brightness do not take effect, check your configuration against the [[Backlight]] article.<br />
<br />
If the problem persists, try one of the following [[kernel parameters]]:<br />
<br />
acpi_osi=Linux<br />
acpi_osi="!Windows 2012"<br />
acpi_osi=<br />
<br />
Also make sure you are not using fastboot mode ({{ic|i915.fastboot}} kernel parameter), it is [https://www.phoronix.com/forums/forum/software/mobile-linux/1066447-arch-linux-users-with-intel-graphics-can-begin-enjoying-a-flicker-free-boot known] for breaking backlight controls.<br />
<br />
=== Corruption or unresponsiveness in Chromium and Firefox ===<br />
<br />
If you experience corruption, unresponsiveness, lags or slow performance in Chromium and/or Firefox some possible solutions are:<br />
<br />
* [[#AccelMethod|Set the AccelMethod to "uxa"]]<br />
* [[#Disable Vertical Synchronization (VSYNC)|Disable VSYNC]]<br />
* [[#Tearing|Enable the TearFree option]]<br />
* Disable "DRI" and acceleration method (tested on Intel Iris 10th generation): {{bc|<nowiki><br />
Option "NoAccel" "True"<br />
Option "DRI" "False"<br />
</nowiki>}}<br />
<br />
=== Kernel crashing w/kernels 4.0+ on Broadwell/Core-M chips ===<br />
<br />
A few seconds after X/Wayland loads the machine will freeze and [[journalctl]] will log a kernel crash referencing the Intel graphics as below:<br />
<br />
Jun 16 17:54:03 hostname kernel: BUG: unable to handle kernel NULL pointer dereference at (null)<br />
Jun 16 17:54:03 hostname kernel: IP: [< (null)>] (null)<br />
...<br />
Jun 16 17:54:03 hostname kernel: CPU: 0 PID: 733 Comm: gnome-shell Tainted: G U O 4.0.5-1-ARCH #1<br />
...<br />
Jun 16 17:54:03 hostname kernel: Call Trace:<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa055cc27>] ? i915_gem_object_sync+0xe7/0x190 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0579634>] intel_execlists_submission+0x294/0x4c0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa05539fc>] i915_gem_do_execbuffer.isra.12+0xabc/0x1230 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa055d349>] ? i915_gem_object_set_to_cpu_domain+0xa9/0x1f0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ba2ae>] ? __kmalloc+0x2e/0x2a0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0555471>] i915_gem_execbuffer2+0x141/0x2b0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa042fcab>] drm_ioctl+0x1db/0x640 [drm]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0555330>] ? i915_gem_execbuffer+0x450/0x450 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff8122339b>] ? eventfd_ctx_read+0x16b/0x200<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ebc36>] do_vfs_ioctl+0x2c6/0x4d0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811f6452>] ? __fget+0x72/0xb0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ebec1>] SyS_ioctl+0x81/0xa0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff8157a589>] system_call_fastpath+0x12/0x17<br />
Jun 16 17:54:03 hostname kernel: Code: Bad RIP value.<br />
Jun 16 17:54:03 hostname kernel: RIP [< (null)>] (null)<br />
<br />
This can be fixed by disabling execlist support which was changed to default on with kernel 4.0. Add the following [[kernel parameter]]:<br />
<br />
i915.enable_execlists=0<br />
<br />
This is known to be broken to at least kernel 4.0.5.<br />
<br />
=== Lag in Windows guests ===<br />
<br />
The video output of a Windows guest in VirtualBox sometimes hangs until the host forces a screen update (e.g. by moving the mouse cursor). Removing the {{ic|1=enable_fbc=1}} option fixes this issue.<br />
<br />
=== Screen flickering ===<br />
<br />
Panel Self Refresh (PSR), a power saving feature used by Intel iGPUs is known to cause flickering in some instances {{Bug|49628}} {{Bug|49371}} {{Bug|50605}}. A temporary solution is to disable this feature using the [[kernel parameter]] {{ic|1=i915.enable_psr=0}}.<br />
<br />
=== OpenGL 2.1 with i915 driver ===<br />
<br />
The classic mesa driver for Gen 3 GPUs included in the {{Pkg|mesa-amber}} package reports OpenGL 2.0 by default, because the hardware is not fully compatible with OpenGL 2.1.[https://www.phoronix.com/scan.php?page=news_item&px=Mesa-i915-OpenGL-2-Drop] OpenGL 2.1 support can be enabled manually by setting {{ic|/etc/drirc}} or {{ic|~/.drirc}} options like:<br />
<br />
{{hc|/etc/drirc|output=<br />
<driconf><br />
...<br />
<device driver="i915"><br />
<application name="Default"><br />
<option name="'''stub_occlusion_query'''" value="'''true'''" /><br />
<option name="'''fragment_shader'''" value="'''true'''" /><br />
</application><br />
</device><br />
...<br />
</driconf><br />
}}<br />
<br />
{{Note|<br />
* The reason of this step back was Chromium and other applications' bad experience. If needed, you might edit the drirc file in a "app-specific" style, see [https://dri.freedesktop.org/wiki/ConfigurationInfrastructure/ here], to disable OpenGL 2.1 on executable {{ic|chromium}} for instance.<br />
* The new Gallium based i915 driver included in {{Pkg|mesa}} package always reports OpenGL 2.1, so this setting is not needed for that driver.}}<br />
<br />
=== KMS Issue: console is limited to small area ===<br />
<br />
One of the low-resolution video ports may be enabled on boot which is causing the terminal to utilize a small area of the screen. To fix, explicitly disable the port with an i915 module setting with {{ic|1=video=SVIDEO-1:d}} in the kernel command line parameter in the boot loader. See [[Kernel parameters]] for more info.<br />
<br />
If that does not work, try disabling TV1 or VGA1 instead of SVIDEO-1. Video port names can be listed with [[xrandr]].<br />
<br />
=== No sound through HDMI on a Haswell CPU ===<br />
<br />
According to a [https://bugzilla.kernel.org/show_bug.cgi?id=60769 Linux kernel issue], sound will not be output through HDMI if {{ic|1=intel_iommu=on}}. To fix this problem, use the following [[kernel parameter]]:<br />
<br />
intel_iommu=on,igfx_off<br />
<br />
Or alternatively, disable IOMMU:<br />
<br />
intel_iommu=off<br />
<br />
=== Crash/freeze on low power Intel CPUs ===<br />
<br />
{{Accuracy|{{ic|1=enable_dc=0}} may not impede on power management to the extent claimed here.|section=Incorrect statements regarding power usage penalty of enable_dc=0}}<br />
<br />
Low-powered Intel processors and/or laptop processors have a tendency to randomly hang or crash due to the problems with the power management features found in low-power Intel chips. If such a crash happens, you will not see any logs reporting this problem. Adding the following [[Kernel parameters]] may help to resolve the problem.<br />
<br />
{{Note|It is not advised to use all three of the below kernel parameters together.}}<br />
<br />
intel_idle.max_cstate=1 i915.enable_dc=0 ahci.mobile_lpm_policy=1<br />
<br />
{{ic|1=ahci.mobile_lpm_policy=1}} fixes a hang on several Lenovo laptops and some Acer notebooks due to problematic SATA controller power management. That workaround is strictly not related to Intel graphics but it does solve related issues. Adding this kernel parameter sets the ''l''ink ''p''ower ''m''anagement from firmware default to maximum performance and will also solve hangs when you change display brightness on certain Lenovo machines but increases idle power consumption by 1-1.5 W on modern ultrabooks. For further information, especially about the other states, see the [https://lore.kernel.org/lkml/20171211165216.5604-1-hdegoede@redhat.com/ Linux kernel mailing list] and [https://access.redhat.com/documentation/en-en/red_hat_enterprise_linux/6/html/power_management_guide/alpm Red Hat documentation].<br />
<br />
{{ic|1=i915.enable_dc=0}} disables GPU power management. This does solve random hangs on certain Intel systems, notably Goldmount and Kaby Lake Refresh chips. Using this parameter does result in higher power use and shorter battery life on laptops/notebooks.<br />
<br />
{{ic|1=intel_idle.max_cstate=1}} limits the processors sleep states, it prevents the processor from going into deep sleep states. That is absolutely not ideal and does result in higher power use and lower battery life. However, it does solve random hangs on many Intel systems. Use this if you have a Intel Baytrail or a Kaby Lake Refresh chip. Intel "Baytrail" chips were known to randomly hang without this kernel parameter due to a [https://bugzilla.kernel.org/show_bug.cgi?id=109051#c752 hardware flaw], theoretically fixed [https://cgit.freedesktop.org/drm-intel/commit/?id=a75d035fedbdecf83f86767aa2e4d05c8c4ffd95 2019-04-26].<br />
More information about the max_cstate parameter can be found in the [https://docs.kernel.org/admin-guide/pm/intel_idle.html#kernel-command-line-options-and-module-parameters kernel documentation] and about the cstates in general on a [https://gist.github.com/wmealing/2dd2b543c4d3cff6cab7 writeup on GitHub].<br />
<br />
If you try adding {{ic|1=intel_idle.max_cstate=1 i915.enable_dc=0 ahci.mobile_lpm_policy=1}} in the hope of fixing frequent hangs and that solves the issue you should later remove one by one to see which of them actually helped you solve the issue. Running with cstates and display power management disabled is not advisable if the actual problem is related to SATA power management and {{ic|1=ahci.mobile_lpm_policy=1}} is the one that actually solves it.<br />
<br />
Check [https://linuxreviews.org/Intel_graphics#Kernel_Parameters Linux Reviews] for more details.<br />
<br />
=== Add support for 165Hz monitor ===<br />
<br />
{{Merge|Kernel mode setting#Forcing modes and EDID|This technique does not appear to be specific to i915. Before merging, one should verify that the install script is necessary, and that there is not an easier way to add the EDID BIN to the initramfs.}}<br />
<br />
For some 165Hz monitors, ''xrandr'' might not display the 165Hz option, and the fix in [[#Adding undetected resolutions]] does not solve this. In this case, see [https://unix.stackexchange.com/questions/680356/i915-driver-stuck-at-40hz-on-165hz-screen i915-driver-stuck-at-40hz-on-165hz-screen].<br />
<br />
{{Note|Other than creating {{ic|/etc/initramfs-tools/hooks/edid}}, a [[mkinitcpio]] hook should be made:<br />
<br />
{{hc|/etc/initcpio/install/edid|<br />
#!/bin/bash<br />
<br />
build() {<br />
add_file /lib/firmware/edid/edid.bin<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook add support for 165Hz<br />
HELPEOF<br />
}<br />
}}<br />
<br />
Then append ''edid'' in HOOKS of {{ic|/etc/mkinitcpio.conf}}, Just like this:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
HOOKS=(... fsck edid)<br />
}}<br />
<br />
Then [[regenerate the initramfs]]. <br />
}}<br />
<br />
=== Freeze after wake from sleep/suspend with Alder Lake-P ===<br />
<br />
{{Expansion|What does "recent firmware" mean? See [[Help:Style#Language register]].}}<br />
{{Note|As of 25-Sep-2022, this has been fixed with a recent firmware update from [[fwupd]]. For others with no BIOS-fix, there is likely an [https://gitlab.freedesktop.org/drm/intel/-/issues/7402 upcoming fix in the kernel].<br />
}}<br />
<br />
Users with Alder Lake-P 12th gen mobile processor laptops from various vendors experienced freeze and black-screen after waking up from suspending. It is because many laptop vendors ship an incorrect VBT (Video BIOS Table) that wrongly describe the actual ports connected to the iGPU. Considering most vendors will not publish a BIOS update for a laptop with a properly working Windows OS, Linux users could only address the issue on the kernel side. You can mitigate the issue by patching and rebuilding the kernel as a temporary remedy:<br />
<br />
{{hc|drivers/gpu/drm/i915/display/intel_display.c.patch|<nowiki><br />
--- a/drivers/gpu/drm/i915/display/intel_display.c<br />
+++ b/drivers/gpu/drm/i915/display/intel_display.c<br />
@@ -8835,7 +8835,7 @@ static void intel_setup_outputs(struct drm_i915_private *dev_priv)<br />
intel_ddi_init(dev_priv, PORT_TC1);<br />
} else if (IS_ALDERLAKE_P(dev_priv)) {<br />
intel_ddi_init(dev_priv, PORT_A);<br />
- intel_ddi_init(dev_priv, PORT_B);<br />
+ // intel_ddi_init(dev_priv, PORT_B);<br />
intel_ddi_init(dev_priv, PORT_TC1);<br />
intel_ddi_init(dev_priv, PORT_TC2);<br />
intel_ddi_init(dev_priv, PORT_TC3);<br />
<br />
</nowiki>}}<br />
<br />
as described in freedesktop issues [https://gitlab.freedesktop.org/drm/intel/-/issues/5531 5531] [https://gitlab.freedesktop.org/drm/intel/-/issues/6401 6401] which have not been solved for months.<br />
<br />
=== Arc GPU hardware video acceleration ===<br />
<br />
Hardware video acceleration is not available in kernel versions below 6.2. Loading and initializing the required HuC/GuC firmware blob fails. <br />
<br />
{{hc|# dmesg|2=<br />
[drm] Incompatible option enable_guc=3 - HuC is not supported!<br />
}}<br />
<br />
{{Style|This section now links to [[hardware video acceleration]], which is already linked in [[#Installation]] and duplicates a part of the instructions from the target page.}}<br />
<br />
{{Accuracy|No explanations or references are given for the need of having {{ic|CONFIG_DRM_I915_CAPTURE_ERROR}} disabled, which is [https://github.com/archlinux/svntogit-packages/blob/227caf8f1a66e00e3a4ecf9bc8e7a98d4d257c11/trunk/config#L6579 set to enabled] in {{Pkg|linux}} as of 2022-12-05.}}<br />
<br />
For [[hardware video acceleration]], you must install {{Pkg|intel-media-driver}} and have a kernel with {{ic|CONFIG_DRM_I915_CAPTURE_ERROR}} disabled.<br />
<br />
== See also ==<br />
<br />
* [https://www.intel.com/content/www/us/en/support/articles/000005520/graphics.html?wapkw=linux%20graphics linux graphics] (includes a list of 106 related products)<br />
* [https://www.intel.com/content/www/us/en/developer/articles/guide/intel-graphics-developers-guides.html?wapkw=linux%20graphics Intel® Processor Graphics] (includes a table of processor series, former code name, launch date and graphics technology)</div>Regidhttps://wiki.archlinux.org/index.php?title=Intel_graphics&diff=795789Intel graphics2024-01-01T19:47:25Z<p>Regid: /* Installation */ The URLs mentioned in the edit can imply Gen 4 hardware and glamor could be terms readers are less familiar with.</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[de:Intel]]<br />
[[es:Intel graphics]]<br />
[[ja:Intel graphics]]<br />
[[ru:Intel graphics]]<br />
[[zh-hans:Intel graphics]]<br />
{{Related articles start}}<br />
{{Related|Intel GMA 3600}}<br />
{{Related|Xorg}}<br />
{{Related|Kernel mode setting}}<br />
{{Related|Xrandr}}<br />
{{Related|Hybrid graphics}}<br />
{{Related|Vulkan}}<br />
{{Related|GPGPU}}<br />
{{Related articles end}}<br />
<br />
Since Intel provides and supports open source drivers, Intel graphics are essentially plug-and-play.<br />
<br />
For a comprehensive list of Intel GPU models and corresponding chipsets and CPUs, see [[Wikipedia:Intel Graphics Technology]] and [[Gentoo:Intel#Feature support]].<br />
<br />
{{Note|<br />
* PowerVR-based graphics ([[Intel GMA 3600|GMA 3600]] series) are not supported by open source drivers.<br />
* Intel's Gen''N'' hardware does not refer to the generation of the CPU, it refers to the [[Wikipedia:List of Intel graphics processing units|generation of the GPU]], which is different from the generation of the CPU. <br />
* See [[Xorg#Driver installation]] to identify your card. <br />
}}<br />
<br />
== Installation ==<br />
<br />
* [[Install]] one of the following packages, which provide the [[wikipedia:Direct Rendering Infrastructure|DRI]] driver for 3D acceleration.<br />
** {{Pkg|mesa}} is the up-to-date [[Mesa]] package which includes the modern Gallium3D drivers for Gen 3 hardware and later. This is the recommended choice.<br />
** {{Pkg|mesa-amber}} is the legacy Mesa package which includes the classic (non-Gallium3D) drivers from Gen 2 to Gen 11 hardware. This driver might have better performance or stability for Gen 7 and older hardware, but is unmaintained.<br />
* For 32-bit application support, also install the {{Pkg|lib32-mesa}} or {{Pkg|lib32-mesa-amber}} package from the [[multilib]] repository.<br />
* For the [[wikipedia:X.Org_Server#DDX|DDX]] driver which provides 2D acceleration in [[Xorg]] use one of the following drivers:<br />
** The ''modesetting'' driver included in the {{Pkg|xorg-server}} package is the recommended choice for Gen 4 hardware and later. It uses the DRI driver for acceleration via ''glamor''. As a rule of thumb, if you have a very old system, you can use the intel ddx along with mesa-amber (NOT mesa!), for setups less than 10 years old, you should be using the modesetting ddx with mesa.[https://gitlab.archlinux.org/archlinux/packaging/packages/mesa/-/issues/5#note_152917][https://bbs.archlinux.org/viewtopic.php?pid=1731412#p1731412] To iterate, using modesetting ddx can be achieved by not installing any xf86-video package.<br />
** The {{Pkg|xf86-video-intel}} package provides the legacy intel DDX driver from Gen 2 to Gen 9 hardware. This package is generally not recommended, see note below.<br />
* For [[Vulkan]] support (Haswell and newer; support for earlier chips is [https://gitlab.freedesktop.org/mesa/mesa/-/issues/8249#note_1758622 incomplete or missing]), install the {{Pkg|vulkan-intel}} package. For 32-bit [[Vulkan]] support, install the {{Pkg|lib32-vulkan-intel}} package.<br />
<br />
Also see [[Hardware video acceleration]].<br />
<br />
{{Note|1=<nowiki/><br />
* Some ([https://www.phoronix.com/scan.php?page=news_item&px=Ubuntu-Debian-Abandon-Intel-DDX Debian & Ubuntu], [https://www.phoronix.com/scan.php?page=news_item&px=Fedora-Xorg-Intel-DDX-Switch Fedora], [https://community.kde.org/Plasma/5.9_Errata#Intel_GPUs KDE], [https://bugzilla.mozilla.org/show_bug.cgi?id=1710400 Mozilla]) recommend not installing the {{Pkg|xf86-video-intel}} driver, and instead falling back on the modesetting driver. See [https://web.archive.org/web/20160714232204/https://www.reddit.com/r/archlinux/comments/4cojj9/it_is_probably_time_to_ditch_xf86videointel/], [https://www.phoronix.com/scan.php?page=article&item=intel-modesetting-2017&num=1], [[Xorg#Installation]], and {{man|4|modesetting}}. However, the modesetting driver can cause problems such as [https://gitlab.freedesktop.org/xorg/xserver/-/issues/1364 screen tearing and mouse jittering on XFCE], [https://bugs.chromium.org/p/chromium/issues/detail?id=370022 artifacts when switching virtual desktops in Chromium], and [https://gitlab.freedesktop.org/xorg/xserver/-/issues/928 vsync jitter/video stutter in mpv].<br />
* The {{Pkg|xf86-video-intel}} driver does not have proper support for Gen 11 and newer hardware, causing lack of acceleration and rendering issues that make Plasma Desktop almost unusable. See [https://gitlab.freedesktop.org/xorg/driver/xf86-video-intel/-/commit/7181c5a41c3f00eaf996caa156523c708a18081e].<br />
* There have been couple reports [https://bbs.archlinux.org/viewtopic.php?id=263323] [https://github.com/qutebrowser/qutebrowser/issues/4641] where the whole graphics stack hard freezes when {{Pkg|xf86-video-intel}} is installed, not even switching to a different virtual console works (by pressing {{ic|Ctrl+Alt+F''n''}}), only killing the user processes with [[SysRq]] works.<br />
}}<br />
<br />
== Loading ==<br />
<br />
The Intel kernel module should load fine automatically on system boot.<br />
<br />
If it does not happen, then:<br />
<br />
* Make sure you do '''not''' have {{ic|nomodeset}} as a [[kernel parameter]], since Intel requires kernel mode-setting.<br />
* Also, check that you have not disabled Intel by using any modprobe blacklisting within {{ic|/etc/modprobe.d/}} or {{ic|/usr/lib/modprobe.d/}}.<br />
<br />
=== Enable early KMS ===<br />
<br />
{{Remove|Since [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/releases/v32 mkinitcpio v32], the {{ic|kms}} hook is included by default, therefore most setups will have early loading enabled by default.}}<br />
<br />
[[Kernel mode setting]] (KMS) is supported by Intel chipsets that use the i915 DRM driver and is mandatory and enabled by default.<br />
<br />
Early KMS should already be enabled for typical setups since [[mkinitcpio]] v32, as the {{ic|kms}} hook is included by default. For other setups, see [[Kernel mode setting#Early KMS start]] for instructions on how to enable KMS as soon as possible at the boot process.<br />
<br />
=== Enable GuC / HuC firmware loading ===<br />
<br />
{{Accuracy|Despite Intel's documentation, Tiger Lake and Rocket Lake GPUs may actually support {{ic|1=enable_guc=3}}, and have a default of {{ic|1=enable_guc=1}}.|Talk:Intel graphics#TGL/RKL GuC Submission}}<br />
<br />
Starting with Gen9 (Skylake and onwards), Intel GPUs include a ''Graphics micro (μ) Controller'' (GuC) which provides the following functionality [https://01.org/linuxgraphics/downloads/firmware]{{Dead link|2023|09|16|status=404}}:<br />
* Offloading some media decoding functionality from the CPU to the ''HEVC/H.265 micro (µ) Controller'' (HuC). Only applicable if using {{Pkg|intel-media-driver}} for [[hardware video acceleration]]. Introduced with Gen9.<br />
* Using the GuC for scheduling, context submission, and power management. Introduced with Alder Lake-P (Mobile), within Gen12.<br />
<br />
To use this functionality, the GuC firmware must be loaded. With regards to HuC support, some video features (e.g. CBR rate control on SKL low-power encoding mode) require loading the HuC firmware as well [https://github.com/intel/media-driver#known-issues-and-limitations]. The GuC and HuC firmware files are both provided by {{Pkg|linux-firmware}}.<br />
<br />
GuC functionality is controlled by the {{ic|1=i915.enable_guc}} [[kernel parameter]]. Its usage is as follows:<br />
<br />
{| class="wikitable"<br />
! enable_guc value !! GuC Submission !! HuC Firmware Loading !! Default for platforms !! Supported on platforms<br />
|-<br />
|0 || {{No}} || {{No}} || Tiger Lake, Rocket Lake, and Pre-Gen12 [https://github.com/torvalds/linux/blob/b3454ce0b2c8a56e760e6baa88ed10278585072b/drivers/gpu/drm/i915/gt/uc/intel_uc.c#L26-L36] || All<br />
|-<br />
|1 || {{Yes}} || {{No}} || {{-}} || Alder Lake-P (Mobile) and newer<br />
|-<br />
|2 || {{No}} || {{Yes}} || Alder Lake-S (Desktop) [https://github.com/torvalds/linux/blob/b3454ce0b2c8a56e760e6baa88ed10278585072b/drivers/gpu/drm/i915/gt/uc/intel_uc.c#L38-L42] [https://lore.kernel.org/all/87ee6wit2r.fsf@intel.com/T/] || Gen9 and newer<br />
|-<br />
|3 || {{Yes}} || {{Yes}} || colspan="2" {{C|Alder Lake-P (Mobile) and newer}}<br />
|}<br />
<br />
If GuC submission or HuC firmware loading is not enabled by default for your GPU, you can manually enable it.<br />
<br />
{{Warning|1=Manually enabling GuC / HuC firmware loading taints the kernel [https://bugs.freedesktop.org/show_bug.cgi?id=111918 even when the feature is not supported]. Moreover, enabling GuC/HuC firmware loading can cause issues on some systems; disable it if you experience freezing (for example, after resuming from hibernation).}}<br />
<br />
First, ensure that {{Pkg|linux-firmware}} is [[install]]ed.<br />
<br />
Set the {{ic|1=i915.enable_guc}} [[kernel parameter]], for example with:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 enable_guc=2<br />
}}<br />
<br />
[[Regenerate the initramfs]], on next boot you can verify both GuC and HuC are enabled by using [[dmesg]]:<br />
<br />
{{hc|# dmesg|2=<br />
[30130.586970] i915 0000:00:02.0: [drm] GuC firmware i915/icl_guc_33.0.0.bin version 33.0 submission:disabled<br />
[30130.586973] i915 0000:00:02.0: [drm] HuC firmware i915/icl_huc_9.0.0.bin version 9.0 authenticated:yes<br />
}}<br />
<br />
If they are not supported by your graphics adapter you will see:<br />
<br />
{{hc|# dmesg|2=<br />
[ 0.571339] i915 0000:00:02.0: [drm] Incompatible option enable_guc=2 - GuC is not supported!<br />
[ 0.571340] i915 0000:00:02.0: [drm] Incompatible option enable_guc=2 - HuC is not supported!<br />
}}<br />
<br />
Alternatively, check using:<br />
<br />
# cat /sys/kernel/debug/dri/0/gt/uc/guc_info<br />
# cat /sys/kernel/debug/dri/0/gt/uc/huc_info<br />
<br />
{{Note|1=Using [[Intel GVT-g|GVT-g graphics virtualization]] by setting {{ic|1=enable_gvt=1}} is not supported as of linux 4.20.11 when GuC/HuC is also enabled. The i915 module would fail to initialize as shown in system journal.<br />
<br />
{{hc|# journalctl|<br />
... kernel: [drm:intel_gvt_init [i915]] *ERROR* i915 GVT-g loading failed due to Graphics virtualization is not yet supported with GuC submission<br />
... kernel: i915 0000:00:02.0: [drm:i915_driver_load [i915]] Device initialization failed (-5)<br />
... kernel: i915: probe of 0000:00:02.0 failed with error -5<br />
... kernel: snd_hda_intel 0000:00:1f.3: failed to add i915 component master (-19)<br />
}}<br />
<br />
Note that the related warning is not fatal, as explained in [https://github.com/intel/gvt-linux/issues/77#issuecomment-707541069]:<br />
<br />
{{hc|# journalctl -b |<br />
... kernel: i915 0000:00:02.0: Direct firmware load for i915/gvt/vid_0x8086_did_0x5916_rid_0x02.golden_hw_state failed with error -2<br />
}}<br />
}}<br />
<br />
== Xorg configuration ==<br />
<br />
There is generally no need for any configuration to run [[Xorg]].<br />
<br />
However, to take advantage of some driver options or if [[Xorg]] does not start, you can create an Xorg configuration file.<br />
<br />
=== With the modesetting driver ===<br />
<br />
If you have installed {{Pkg|xf86-video-intel}} but want to load the modesetting driver explicitly instead of letting the DDX driver take priority, for example when trying to compare them:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "modesetting"<br />
EndSection<br />
}}<br />
<br />
=== With the Intel driver ===<br />
<br />
{{Note|The following requires {{Pkg|xf86-video-intel}}.}}<br />
<br />
Create an Xorg configuration file similar to the one below:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
EndSection<br />
}}<br />
<br />
Additional options are added by the user on new lines below {{ic|Driver}}.<br />
For the full list of options, see the {{man|4|intel}} man page.<br />
<br />
{{Note|You might need to add more device sections than the one listed above. This will be indicated where necessary.}}<br />
<br />
==== AccelMethod ====<br />
<br />
You may need to indicate {{ic|Option "AccelMethod"}} when creating a configuration file, the classical options are {{ic|UXA}}, {{ic|SNA}} (default) and {{ic|BLT}}.<br />
<br />
If you experience issues with default {{ic|SNA}} (e.g. pixelated graphics, corrupt text, etc.), try using {{ic|UXA}} instead, which can be done by adding the following line to your [[#Xorg configuration|configuration file]]:<br />
<br />
Option "AccelMethod" "uxa"<br />
<br />
See the "AccelMethod" option under {{man|4|intel|CONFIGURATION DETAILS}}.<br />
<br />
==== Using Intel DDX driver with recent GPUs ====<br />
<br />
For Intel GPUs starting from Gen8 (Broadwell), the Iris Mesa driver is needed:<br />
<br />
Option "DRI" "iris"<br />
<br />
==== Disabling TearFree, TripleBuffer, SwapbuffersWait ====<br />
<br />
If you use a compositor (the default in modern desktop environment like GNOME, KDE Plasma, Xfce, etc.), then TearFree, TripleBuffer and SwapbuffersWait can usually be disabled to improve performance and decrease power consumption.<br />
<br />
Option "TearFree" "false"<br />
Option "TripleBuffer" "false"<br />
Option "SwapbuffersWait" "false"<br />
<br />
== Module-based options ==<br />
<br />
The {{ic|i915}} kernel module allows for configuration via [[Kernel modules#Setting module options|module options]]. Some of the module options impact power saving.<br />
<br />
A list of all options along with short descriptions and default values can be generated with the following command:<br />
<br />
$ modinfo -p i915<br />
<br />
To check which options are currently enabled, run<br />
<br />
# systool -m i915 -av<br />
<br />
You will note that many options default to -1, resulting in per-chip powersaving defaults. It is however possible to configure more aggressive powersaving by using [[Kernel modules#Setting module options|module options]].<br />
<br />
{{Note|1=Diverting from the defaults will mark the kernel as [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=fc9740cebc3ab7c65f3c5f6ce0caf3e4969013ca tainted] from Linux 3.18 onwards. This basically implies using other options than the per-chip defaults is considered experimental and not supported by the developers. }}<br />
<br />
=== Framebuffer compression (enable_fbc) ===<br />
<br />
Framebuffer compression (FBC) is a feature that can reduce power consumption and memory bandwidth during screen refreshes.<br />
<br />
The feature will be automatically enabled if supported by the hardware. You can use the command below to verify whether it is is enabled:<br />
<br />
{{hc|$ modinfo i915 {{!}} grep enable_fbc|<br />
parm: enable_fbc:Enable frame buffer compression for power savings (default: -1 (use per-chip default)) (int)<br />
}}<br />
<br />
If the parm is set to {{ic|-1}}, you do not need to do anything. Otherwise, to force-enable FBC, use {{ic|1=i915.enable_fbc=1}} as [[kernel parameter]] or set in {{ic|/etc/modprobe.d/i915.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 enable_fbc=1<br />
}}<br />
<br />
{{Note|Framebuffer compression may be unreliable or unavailable on Intel GPU generations before Sandy Bridge (generation 6). This results in messages logged to the system journal similar to this one:<br />
<br />
kernel: drm: not enough stolen space for compressed buffer, disabling.<br />
<br />
Enabling frame buffer compression on pre-Sandy Bridge CPUs results in endless error messages:<br />
<br />
{{hc|# dmesg|<br />
[ 2360.475430] [drm] not enough stolen space for compressed buffer (need 4325376 bytes), disabling<br />
[ 2360.475437] [drm] hint: you may be able to increase stolen memory size in the BIOS to avoid this<br />
}}<br />
<br />
The solution is to disable frame buffer compression which will imperceptibly increase power consumption (around 0.06 W). In order to disable it add {{ic|1=i915.enable_fbc=0}} to the kernel line parameters. More information on the results of disabled compression can be found [https://web.archive.org/web/20200228230053/https://kernel.ubuntu.com/~cking/power-benchmarking/background-colour-and-framebuffer-compression/ here].}}<br />
<br />
=== Fastboot ===<br />
<br />
{{Note|1=This parameter is enabled by default for Skylake and newer[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=3d6535cbed4a4b029602ff83efb2adec7cb8d28b] as well as Bay- and Cherry-Trail (VLV/CHV)[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=7360c9f6b857e22a48e545f4e99c79630994e932] since Linux 5.1.[https://kernelnewbies.org/Linux_5.1#Graphics]}}<br />
<br />
The goal of Intel Fastboot is to preserve the frame-buffer as setup by the BIOS or [[boot loader]] to avoid any flickering until [[Xorg]] has started.[https://lists.freedesktop.org/archives/intel-gfx/2012-May/017653.html][https://www.phoronix.com/scan.php?page=news_item&px=MTEwNzc]<br />
<br />
To force enable fastboot on platforms where it is not the default already, set {{ic|1=i915.fastboot=1}} as [[kernel parameter]] or set in {{ic|/etc/modprobe.d/i915.conf}}:<br />
<br />
{{hc|/etc/modprobe.d/i915.conf|2=<br />
options i915 fastboot=1<br />
}}<br />
<br />
=== Intel GVT-g graphics virtualization support ===<br />
<br />
See [[Intel GVT-g]] for details.<br />
<br />
=== Enable performance support ===<br />
<br />
{{Expansion|What does Mesa actually do using the performance counters? What's the effect of this? Some report drastic performance increases on Intel Tiger Lake, attributing it to a support for Dynamic Tuning [https://www.reddit.com/r/linux/comments/u7zxa0/psa_for_intel_tiger_lake_dynamic_tuning_laptops/].|section=Potential performance gains via Observation Architecture}}<br />
<br />
Starting with Gen6 (Sandy Bridge and onwards), Intel GPUs provide performance counters used for exposing internal performance data to drivers. The drivers and hardware registers refer to this infrastructure as the ''Observation Architecture'' (internally "OA") [https://www.phoronix.com/scan.php?page=news_item&px=Intel-HSW-Observation-Arch], but Intel's documentation also more generally refers to this functionality as providing ''Observability Performance Counters'' [https://01.org/sites/default/files/documentation/observability_performance_counters_haswell.pdf]{{Dead link|2023|09|16|status=404}} [https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol14-observability.pdf]{{Dead link|2023|09|16|status=404}}.<br />
<br />
By default, only programs running with the [https://lwn.net/Articles/486306/ CAP_SYS_ADMIN] (equivalent to root) or [https://lwn.net/Articles/812719/ CAP_PERFMON] [[capabilities]] can utilize the observation architecture [https://github.com/torvalds/linux/blob/b14ffae378aa1db993e62b01392e70d1e585fb23/drivers/gpu/drm/i915/i915_perf.c#L267] [https://github.com/torvalds/linux/blob/b14ffae378aa1db993e62b01392e70d1e585fb23/drivers/gpu/drm/i915/i915_perf.c#L3481-L3484]. Most applications will be running without either of these, resulting in the following warning:<br />
<br />
MESA-INTEL: warning: Performance support disabled, consider sysctl dev.i915.perf_stream_paranoid=0<br />
<br />
To enable performance support without using the capabilities (or root), set the kernel parameter as described in [[sysctl]].<br />
<br />
{{Warning|The restrictive defaults of the {{ic|perf_event_paranoid}} family of options exists because there is risk associated with allowing applications to access performance data [https://docs.kernel.org/admin-guide/perf-security.html]. With this being said, {{ic|dev.i915.perf_stream_paranoid}} only influences access to GPU performance counters, which carry less risk than e.g. CPU architectural execution context registers.}}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Setting scaling mode ===<br />
<br />
This can be useful for some full screen applications:<br />
<br />
$ xrandr --output LVDS1 --set PANEL_FITTING ''param''<br />
<br />
where {{ic|''param''}} can be:<br />
<br />
* {{ic|center}}: resolution will be kept exactly as defined, no scaling will be made,<br />
* {{ic|full}}: scale the resolution so it uses the entire screen or<br />
* {{ic|full_aspect}}: scale the resolution to the maximum possible but keep the aspect ratio.<br />
<br />
If it does not work, try:<br />
<br />
$ xrandr --output LVDS1 --set "scaling mode" ''param''<br />
<br />
where {{ic|''param''}} is one of {{ic|"Full"}}, {{ic|"Center"}} or {{ic|"Full aspect"}}.<br />
<br />
{{Note|1=This option currently does not work for external displays (e.g. VGA, DVI, HDMI, DP). [https://bugs.freedesktop.org/show_bug.cgi?id=90989]}}<br />
<br />
=== Hardware accelerated H.264 decoding on GMA 4500 ===<br />
<br />
The {{Pkg|libva-intel-driver}} package only provides hardware accelerated MPEG-2 decoding – and not H.264 decoding – for some GMA 4500 series GPUs. To check whether that affects your particular GPU, install both that driver and the {{Pkg|libva-utils}} package, then check the output of the {{ic|vainfo}} tool for the presence of entries that start with {{ic|VAProfileH264}}.<br />
<br />
The H.264 decoding support is maintained in a separated g45-h264 branch, which can be used by installing {{AUR|libva-intel-driver-g45-h264}} package. Note, however, that this support is experimental and its development has been abandoned. Using the VA-API with this driver on a GMA 4500 series GPU will offload the CPU but may not result in as smooth a playback as non-accelerated playback. Tests using mplayer showed that using vaapi to play back an H.264 encoded 1080p video halved the CPU load (compared to the XV overlay) but resulted in very choppy playback, while 720p worked reasonably well [https://bbs.archlinux.org/viewtopic.php?id=150550]. This is echoed by other experiences [https://web.archive.org/web/20160325142959/http://www.emmolution.org/?p=192&cpage=1#comment-12292]. Setting the preallocated video ram size higher in BIOS results in much better hardware decoded playback. Even 1080p h264 works well if this is done[https://lists.libreplanet.org/archive/html/guix-patches/2019-11/msg00652.html]. Smooth playback (1080p/720p) works also with {{AUR|mpv-git}} in combination with {{AUR|ffmpeg-git}} and {{AUR|libva-intel-driver-g45-h264}}. With MPV and the Firefox plugin "Send to MPV player"[https://addons.mozilla.org/firefox/addon/send-to-mpv-player/] it is possible to watch hardware accelerated YouTube videos.<br />
<br />
=== Overriding reported OpenGL version ===<br />
<br />
The {{ic|MESA_GL_VERSION_OVERRIDE}} [[environment variable]] can be used to override the reported OpenGL version to any application. For example, setting {{ic|1=MESA_GL_VERSION_OVERRIDE=4.5}} will report OpenGL 4.5.<br />
<br />
{{Note|You can use this variable to report any known OpenGL version, even if it is not supported by the GPU. Some applications might no longer crash, some may start crashing - you probably do not want to set this variable globally.}}<br />
<br />
=== Monitoring ===<br />
<br />
{{Merge|Hardware video acceleration#Verification|This overlaps the content at the previously linked page and would probably be a better fit in a generic page instead of this one dedicated to Intel GPUs. Otherwise, [[Hardware video acceleration#Verification]] should be modified to link to each dedicated page instead of duplicating content.}}<br />
<br />
* {{App|intel_gpu_top|A top-like task monitor for Intel GPUs (requires root permissions).|https://gitlab.freedesktop.org/drm/igt-gpu-tools|{{Pkg|intel-gpu-tools}}}}<br />
* {{App|nvtop|GPUs process monitoring for AMD, Intel and NVIDIA (currently has very basic support for Intel GPUs).|https://github.com/Syllo/nvtop|{{Pkg|nvtop}}}}<br />
<br />
=== Setting brightness and gamma ===<br />
<br />
See [[Backlight]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Tearing ===<br />
<br />
==== With the Intel driver ====<br />
<br />
The SNA acceleration method causes tearing on some machines. To fix this, enable the {{ic|TearFree}} option in the {{Pkg|xf86-video-intel}} driver by adding the following line to your [[#Xorg configuration|configuration file]]:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "intel"<br />
Option "TearFree" "true"<br />
EndSection}}<br />
<br />
See the [https://bugs.freedesktop.org/show_bug.cgi?id=37686 original bug report] for more info.<br />
<br />
{{Note|1=<nowiki/><br />
* This option may not work when {{ic|SwapbuffersWait}} is {{ic|false}}.<br />
* This option may increase memory allocation considerably and reduce performance. [https://bugs.freedesktop.org/show_bug.cgi?id=37686#c123]<br />
* This option is problematic for applications that are very picky about vsync timing, like [[Wikipedia:Super Meat Boy|Super Meat Boy]].<br />
* This option does not work with UXA acceleration method, only with SNA.<br />
* For Intel UHD 620 or 630 you will need to add {{ic|Option "TripleBuffer" "true"}} in order for {{ic|TearFree}} to work.<br />
* It might be necessary to disable DRI3 by adding {{ic|Option "DRI" "2"}}, otherwise any fullsceen app (such as video playback) can break TearFree. [https://bugs.freedesktop.org/show_bug.cgi?id=96847#c7]<br />
}}<br />
<br />
==== With the modesetting driver ====<br />
<br />
TearFree support [https://gitlab.freedesktop.org/xorg/xserver/-/merge_requests/1006 was recently added] to the modesetting driver [https://www.phoronix.com/news/xf86-video-modesetting-TearFree][https://www.phoronix.com/news/Modesetting-TearFree-Merged]. As of November 2023, this patch has yet to reach a stable release, so you will need {{AUR|xorg-server-git}} until then.<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-intel.conf|<br />
Section "Device"<br />
Identifier "Intel Graphics"<br />
Driver "modesetting"<br />
Option "TearFree" "true"<br />
EndSection}}<br />
<br />
=== Disable Vertical Synchronization (VSYNC) ===<br />
<br />
Useful when:<br />
<br />
* Chromium/Chrome has lags and slow performance due to GPU and runs smoothly with --disable-gpu switch<br />
* glxgears test does not show desired performance<br />
<br />
The intel-driver uses [https://www.intel.com/content/www/us/en/support/articles/000006930/graphics.html Triple Buffering] for vertical synchronization; this allows for full performance and avoids tearing. To turn vertical synchronization off (e.g. for benchmarking) use this {{ic|.drirc}} in your home directory:<br />
<br />
{{hc|~/.drirc|2=<br />
<device screen="0" driver="dri2"><br />
<application name="Default"><br />
<option name="vblank_mode" value="0"/><br />
</application><br />
</device><br />
}}<br />
<br />
{{Note|Do not use {{AUR|driconf}} to create this file. It is buggy and will set the wrong driver.}}<br />
<br />
=== DRI3 issues ===<br />
<br />
''DRI3'' is the default DRI version in {{Pkg|xf86-video-intel}}. On some systems this can cause issues such as [https://bugs.chromium.org/p/chromium/issues/detail?id=370022 this]. To switch back to ''DRI2'' add the following line to your [[#Xorg configuration|configuration file]]:<br />
<br />
Option "DRI" "2"<br />
<br />
For the {{ic|modesetting}} driver, this method of disabling DRI3 does not work. Instead, one can set the environment variable {{ic|1=LIBGL_DRI3_DISABLE=1}}.<br />
<br />
=== Font and screen corruption in GTK applications (missing glyphs after suspend/resume) ===<br />
<br />
Should you experience missing font glyphs in GTK applications, the following workaround might help. [[textedit|Edit]] {{ic|/etc/environment}} to add the following line:<br />
<br />
{{hc|/etc/environment|output=<br />
COGL_ATLAS_DEFAULT_BLIT_MODE=framebuffer<br />
}}<br />
<br />
See also [https://bugs.freedesktop.org/show_bug.cgi?id=88584 FreeDesktop bug 88584].<br />
<br />
=== Blank screen during boot, when "Loading modules" ===<br />
<br />
{{Remove|Since [https://gitlab.archlinux.org/archlinux/mkinitcpio/mkinitcpio/-/releases/v32 mkinitcpio v32], the {{ic|kms}} hook is included by default, therefore most setups will have early loading enabled by default.}}<br />
<br />
If using "late start" KMS and the screen goes blank when "Loading modules", it may help to add {{ic|i915}} and {{ic|intel_agp}} to the initramfs. See [[Kernel mode setting#Early KMS start]] section.<br />
<br />
Alternatively, appending the following [[kernel parameter]] seems to work as well:<br />
<br />
video=SVIDEO-1:d<br />
<br />
If you need to output to VGA then try this:<br />
<br />
video=VGA-1:1280x800<br />
<br />
=== X freeze/crash with intel driver ===<br />
<br />
Some issues with X crashing, GPU hanging, or problems with X freezing, can be fixed by disabling the GPU usage with the {{ic|NoAccel}} option - add the following lines to your [[#Xorg configuration|configuration file]]:<br />
<br />
Option "NoAccel" "True"<br />
<br />
Alternatively, try to disable the 3D acceleration only with the {{ic|DRI}} option:<br />
<br />
Option "DRI" "False"<br />
<br />
=== Adding undetected resolutions ===<br />
<br />
This issue is covered on the [[Xrandr#Adding undetected resolutions|Xrandr page]].<br />
<br />
=== Backlight is not adjustable ===<br />
<br />
If after resuming from suspend, the hotkeys for changing the screen brightness do not take effect, check your configuration against the [[Backlight]] article.<br />
<br />
If the problem persists, try one of the following [[kernel parameters]]:<br />
<br />
acpi_osi=Linux<br />
acpi_osi="!Windows 2012"<br />
acpi_osi=<br />
<br />
Also make sure you are not using fastboot mode ({{ic|i915.fastboot}} kernel parameter), it is [https://www.phoronix.com/forums/forum/software/mobile-linux/1066447-arch-linux-users-with-intel-graphics-can-begin-enjoying-a-flicker-free-boot known] for breaking backlight controls.<br />
<br />
=== Corruption or unresponsiveness in Chromium and Firefox ===<br />
<br />
If you experience corruption, unresponsiveness, lags or slow performance in Chromium and/or Firefox some possible solutions are:<br />
<br />
* [[#AccelMethod|Set the AccelMethod to "uxa"]]<br />
* [[#Disable Vertical Synchronization (VSYNC)|Disable VSYNC]]<br />
* [[#Tearing|Enable the TearFree option]]<br />
* Disable "DRI" and acceleration method (tested on Intel Iris 10th generation): {{bc|<nowiki><br />
Option "NoAccel" "True"<br />
Option "DRI" "False"<br />
</nowiki>}}<br />
<br />
=== Kernel crashing w/kernels 4.0+ on Broadwell/Core-M chips ===<br />
<br />
A few seconds after X/Wayland loads the machine will freeze and [[journalctl]] will log a kernel crash referencing the Intel graphics as below:<br />
<br />
Jun 16 17:54:03 hostname kernel: BUG: unable to handle kernel NULL pointer dereference at (null)<br />
Jun 16 17:54:03 hostname kernel: IP: [< (null)>] (null)<br />
...<br />
Jun 16 17:54:03 hostname kernel: CPU: 0 PID: 733 Comm: gnome-shell Tainted: G U O 4.0.5-1-ARCH #1<br />
...<br />
Jun 16 17:54:03 hostname kernel: Call Trace:<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa055cc27>] ? i915_gem_object_sync+0xe7/0x190 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0579634>] intel_execlists_submission+0x294/0x4c0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa05539fc>] i915_gem_do_execbuffer.isra.12+0xabc/0x1230 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa055d349>] ? i915_gem_object_set_to_cpu_domain+0xa9/0x1f0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ba2ae>] ? __kmalloc+0x2e/0x2a0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0555471>] i915_gem_execbuffer2+0x141/0x2b0 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa042fcab>] drm_ioctl+0x1db/0x640 [drm]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffffa0555330>] ? i915_gem_execbuffer+0x450/0x450 [i915]<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff8122339b>] ? eventfd_ctx_read+0x16b/0x200<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ebc36>] do_vfs_ioctl+0x2c6/0x4d0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811f6452>] ? __fget+0x72/0xb0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff811ebec1>] SyS_ioctl+0x81/0xa0<br />
Jun 16 17:54:03 hostname kernel: [<ffffffff8157a589>] system_call_fastpath+0x12/0x17<br />
Jun 16 17:54:03 hostname kernel: Code: Bad RIP value.<br />
Jun 16 17:54:03 hostname kernel: RIP [< (null)>] (null)<br />
<br />
This can be fixed by disabling execlist support which was changed to default on with kernel 4.0. Add the following [[kernel parameter]]:<br />
<br />
i915.enable_execlists=0<br />
<br />
This is known to be broken to at least kernel 4.0.5.<br />
<br />
=== Lag in Windows guests ===<br />
<br />
The video output of a Windows guest in VirtualBox sometimes hangs until the host forces a screen update (e.g. by moving the mouse cursor). Removing the {{ic|1=enable_fbc=1}} option fixes this issue.<br />
<br />
=== Screen flickering ===<br />
<br />
Panel Self Refresh (PSR), a power saving feature used by Intel iGPUs is known to cause flickering in some instances {{Bug|49628}} {{Bug|49371}} {{Bug|50605}}. A temporary solution is to disable this feature using the [[kernel parameter]] {{ic|1=i915.enable_psr=0}}.<br />
<br />
=== OpenGL 2.1 with i915 driver ===<br />
<br />
The classic mesa driver for Gen 3 GPUs included in the {{Pkg|mesa-amber}} package reports OpenGL 2.0 by default, because the hardware is not fully compatible with OpenGL 2.1.[https://www.phoronix.com/scan.php?page=news_item&px=Mesa-i915-OpenGL-2-Drop] OpenGL 2.1 support can be enabled manually by setting {{ic|/etc/drirc}} or {{ic|~/.drirc}} options like:<br />
<br />
{{hc|/etc/drirc|output=<br />
<driconf><br />
...<br />
<device driver="i915"><br />
<application name="Default"><br />
<option name="'''stub_occlusion_query'''" value="'''true'''" /><br />
<option name="'''fragment_shader'''" value="'''true'''" /><br />
</application><br />
</device><br />
...<br />
</driconf><br />
}}<br />
<br />
{{Note|<br />
* The reason of this step back was Chromium and other applications' bad experience. If needed, you might edit the drirc file in a "app-specific" style, see [https://dri.freedesktop.org/wiki/ConfigurationInfrastructure/ here], to disable OpenGL 2.1 on executable {{ic|chromium}} for instance.<br />
* The new Gallium based i915 driver included in {{Pkg|mesa}} package always reports OpenGL 2.1, so this setting is not needed for that driver.}}<br />
<br />
=== KMS Issue: console is limited to small area ===<br />
<br />
One of the low-resolution video ports may be enabled on boot which is causing the terminal to utilize a small area of the screen. To fix, explicitly disable the port with an i915 module setting with {{ic|1=video=SVIDEO-1:d}} in the kernel command line parameter in the boot loader. See [[Kernel parameters]] for more info.<br />
<br />
If that does not work, try disabling TV1 or VGA1 instead of SVIDEO-1. Video port names can be listed with [[xrandr]].<br />
<br />
=== No sound through HDMI on a Haswell CPU ===<br />
<br />
According to a [https://bugzilla.kernel.org/show_bug.cgi?id=60769 Linux kernel issue], sound will not be output through HDMI if {{ic|1=intel_iommu=on}}. To fix this problem, use the following [[kernel parameter]]:<br />
<br />
intel_iommu=on,igfx_off<br />
<br />
Or alternatively, disable IOMMU:<br />
<br />
intel_iommu=off<br />
<br />
=== Crash/freeze on low power Intel CPUs ===<br />
<br />
{{Accuracy|{{ic|1=enable_dc=0}} may not impede on power management to the extent claimed here.|section=Incorrect statements regarding power usage penalty of enable_dc=0}}<br />
<br />
Low-powered Intel processors and/or laptop processors have a tendency to randomly hang or crash due to the problems with the power management features found in low-power Intel chips. If such a crash happens, you will not see any logs reporting this problem. Adding the following [[Kernel parameters]] may help to resolve the problem.<br />
<br />
{{Note|It is not advised to use all three of the below kernel parameters together.}}<br />
<br />
intel_idle.max_cstate=1 i915.enable_dc=0 ahci.mobile_lpm_policy=1<br />
<br />
{{ic|1=ahci.mobile_lpm_policy=1}} fixes a hang on several Lenovo laptops and some Acer notebooks due to problematic SATA controller power management. That workaround is strictly not related to Intel graphics but it does solve related issues. Adding this kernel parameter sets the ''l''ink ''p''ower ''m''anagement from firmware default to maximum performance and will also solve hangs when you change display brightness on certain Lenovo machines but increases idle power consumption by 1-1.5 W on modern ultrabooks. For further information, especially about the other states, see the [https://lore.kernel.org/lkml/20171211165216.5604-1-hdegoede@redhat.com/ Linux kernel mailing list] and [https://access.redhat.com/documentation/en-en/red_hat_enterprise_linux/6/html/power_management_guide/alpm Red Hat documentation].<br />
<br />
{{ic|1=i915.enable_dc=0}} disables GPU power management. This does solve random hangs on certain Intel systems, notably Goldmount and Kaby Lake Refresh chips. Using this parameter does result in higher power use and shorter battery life on laptops/notebooks.<br />
<br />
{{ic|1=intel_idle.max_cstate=1}} limits the processors sleep states, it prevents the processor from going into deep sleep states. That is absolutely not ideal and does result in higher power use and lower battery life. However, it does solve random hangs on many Intel systems. Use this if you have a Intel Baytrail or a Kaby Lake Refresh chip. Intel "Baytrail" chips were known to randomly hang without this kernel parameter due to a [https://bugzilla.kernel.org/show_bug.cgi?id=109051#c752 hardware flaw], theoretically fixed [https://cgit.freedesktop.org/drm-intel/commit/?id=a75d035fedbdecf83f86767aa2e4d05c8c4ffd95 2019-04-26].<br />
More information about the max_cstate parameter can be found in the [https://docs.kernel.org/admin-guide/pm/intel_idle.html#kernel-command-line-options-and-module-parameters kernel documentation] and about the cstates in general on a [https://gist.github.com/wmealing/2dd2b543c4d3cff6cab7 writeup on GitHub].<br />
<br />
If you try adding {{ic|1=intel_idle.max_cstate=1 i915.enable_dc=0 ahci.mobile_lpm_policy=1}} in the hope of fixing frequent hangs and that solves the issue you should later remove one by one to see which of them actually helped you solve the issue. Running with cstates and display power management disabled is not advisable if the actual problem is related to SATA power management and {{ic|1=ahci.mobile_lpm_policy=1}} is the one that actually solves it.<br />
<br />
Check [https://linuxreviews.org/Intel_graphics#Kernel_Parameters Linux Reviews] for more details.<br />
<br />
=== Add support for 165Hz monitor ===<br />
<br />
{{Merge|Kernel mode setting#Forcing modes and EDID|This technique does not appear to be specific to i915. Before merging, one should verify that the install script is necessary, and that there is not an easier way to add the EDID BIN to the initramfs.}}<br />
<br />
For some 165Hz monitors, ''xrandr'' might not display the 165Hz option, and the fix in [[#Adding undetected resolutions]] does not solve this. In this case, see [https://unix.stackexchange.com/questions/680356/i915-driver-stuck-at-40hz-on-165hz-screen i915-driver-stuck-at-40hz-on-165hz-screen].<br />
<br />
{{Note|Other than creating {{ic|/etc/initramfs-tools/hooks/edid}}, a [[mkinitcpio]] hook should be made:<br />
<br />
{{hc|/etc/initcpio/install/edid|<br />
#!/bin/bash<br />
<br />
build() {<br />
add_file /lib/firmware/edid/edid.bin<br />
}<br />
<br />
help() {<br />
cat <<HELPEOF<br />
This hook add support for 165Hz<br />
HELPEOF<br />
}<br />
}}<br />
<br />
Then append ''edid'' in HOOKS of {{ic|/etc/mkinitcpio.conf}}, Just like this:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
HOOKS=(... fsck edid)<br />
}}<br />
<br />
Then [[regenerate the initramfs]]. <br />
}}<br />
<br />
=== Freeze after wake from sleep/suspend with Alder Lake-P ===<br />
<br />
{{Expansion|What does "recent firmware" mean? See [[Help:Style#Language register]].}}<br />
{{Note|As of 25-Sep-2022, this has been fixed with a recent firmware update from [[fwupd]]. For others with no BIOS-fix, there is likely an [https://gitlab.freedesktop.org/drm/intel/-/issues/7402 upcoming fix in the kernel].<br />
}}<br />
<br />
Users with Alder Lake-P 12th gen mobile processor laptops from various vendors experienced freeze and black-screen after waking up from suspending. It is because many laptop vendors ship an incorrect VBT (Video BIOS Table) that wrongly describe the actual ports connected to the iGPU. Considering most vendors will not publish a BIOS update for a laptop with a properly working Windows OS, Linux users could only address the issue on the kernel side. You can mitigate the issue by patching and rebuilding the kernel as a temporary remedy:<br />
<br />
{{hc|drivers/gpu/drm/i915/display/intel_display.c.patch|<nowiki><br />
--- a/drivers/gpu/drm/i915/display/intel_display.c<br />
+++ b/drivers/gpu/drm/i915/display/intel_display.c<br />
@@ -8835,7 +8835,7 @@ static void intel_setup_outputs(struct drm_i915_private *dev_priv)<br />
intel_ddi_init(dev_priv, PORT_TC1);<br />
} else if (IS_ALDERLAKE_P(dev_priv)) {<br />
intel_ddi_init(dev_priv, PORT_A);<br />
- intel_ddi_init(dev_priv, PORT_B);<br />
+ // intel_ddi_init(dev_priv, PORT_B);<br />
intel_ddi_init(dev_priv, PORT_TC1);<br />
intel_ddi_init(dev_priv, PORT_TC2);<br />
intel_ddi_init(dev_priv, PORT_TC3);<br />
<br />
</nowiki>}}<br />
<br />
as described in freedesktop issues [https://gitlab.freedesktop.org/drm/intel/-/issues/5531 5531] [https://gitlab.freedesktop.org/drm/intel/-/issues/6401 6401] which have not been solved for months.<br />
<br />
=== Arc GPU hardware video acceleration ===<br />
<br />
Hardware video acceleration is not available in kernel versions below 6.2. Loading and initializing the required HuC/GuC firmware blob fails. <br />
<br />
{{hc|# dmesg|2=<br />
[drm] Incompatible option enable_guc=3 - HuC is not supported!<br />
}}<br />
<br />
{{Style|This section now links to [[hardware video acceleration]], which is already linked in [[#Installation]] and duplicates a part of the instructions from the target page.}}<br />
<br />
{{Accuracy|No explanations or references are given for the need of having {{ic|CONFIG_DRM_I915_CAPTURE_ERROR}} disabled, which is [https://github.com/archlinux/svntogit-packages/blob/227caf8f1a66e00e3a4ecf9bc8e7a98d4d257c11/trunk/config#L6579 set to enabled] in {{Pkg|linux}} as of 2022-12-05.}}<br />
<br />
For [[hardware video acceleration]], you must install {{Pkg|intel-media-driver}} and have a kernel with {{ic|CONFIG_DRM_I915_CAPTURE_ERROR}} disabled.<br />
<br />
== See also ==<br />
<br />
* [https://www.intel.com/content/www/us/en/support/articles/000005520/graphics.html?wapkw=linux%20graphics linux graphics] (includes a list of 106 related products)<br />
* [https://www.intel.com/content/www/us/en/developer/articles/guide/intel-graphics-developers-guides.html?wapkw=linux%20graphics Intel® Processor Graphics] (includes a table of processor series, former code name, launch date and graphics technology)</div>Regidhttps://wiki.archlinux.org/index.php?title=Vi&diff=795405Vi2023-12-28T01:18:21Z<p>Regid: /* Installation */ I couldn't find a reference to those 4 applications in the whole wiki. Which looks to me unfortunate. I am not familiar with vedit. Which is why I am not sure if {{man|1|vedit}} refers to it as a novice {{man|1|view}}, or something else.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Text editors]]<br />
[[de:Vi]]<br />
[[es:Vi]]<br />
[[fr:Vi]]<br />
[[pt:Vi]]<br />
[[zh-hans:Vi]]<br />
According to [[Wikipedia:Vi|Wikipedia]]:<br />
<br />
:vi is a screen-oriented text editor originally created for the Unix operating system. The portable subset of the behavior of vi and programs based on it, and the ex editor language supported within these programs, is described by (and thus standardized by) the Single Unix Specification and POSIX.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|vi}} package.<br />
<br />
The line-oriented [[text editor]]s {{ic|edit}} and {{ic|ex}}, as well as the [[terminal pager]]s, with vi like commands, {{ic|vedit}} and {{ic|view}}, are also supplied by the {{pkg|vi}} package.<br />
<br />
== Vi-style software ==<br />
<br />
The key bindings and modes of vi have been recreated in various other software:<br />
<br />
* [[List of applications/Documents#Vi-style text editors|text editors]], the most popular of which being [[Vim]]<br />
* [[List of applications/Utilities#File managers|file managers]] like [[ranger]] and [[Vifm]]<br />
* the [[Readline#Editing mode|Readline]] input library (used by [[Bash]])<br />
* [[shell]]s like [[Zsh#Key bindings|Zsh]]<br />
* [[web browser]]s like [[Luakit]], [[qutebrowser]] or {{Pkg|vimb}}; for [[Firefox]] and [[Chromium]] there are [[Browser extensions#Keyboard shortcuts|browser extensions]] available.<br />
* most [[tiling window manager]]s can be configured for vi-style control<br />
<br />
== See also ==<br />
<br />
* {{man|1|vi}}<br />
* [https://web.archive.org/web/20140822135551/http://usalug.com/vi.html vi Tutorial and Reference Guide]</div>Regidhttps://wiki.archlinux.org/index.php?title=Vim&diff=795403Vim2023-12-28T00:51:00Z<p>Regid: /* Vim as a pager */ Turns out {{ic|view}} is part of {{pkg|vi}}, and behaves in accordance. Reference: https://archlinux.org/packages/extra/x86_64/vim/files/ , https://archlinux.org/packages/core/x86_64/vi/files/</p>
<hr />
<div>[[Category:Text editors]]<br />
[[Category:Console applications]]<br />
[[de:Vim]]<br />
[[es:Vim]]<br />
[[ja:Vim]]<br />
[[pt:Vim]]<br />
[[ru:Vim]]<br />
[[zh-hans:Vim]]<br />
{{Related articles start}}<br />
{{Related|List of applications/Documents#Vi-style text editors}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Vim (text editor)|Vim]] is a terminal text editor. It is an extended version of [[vi]] with additional features, including syntax highlighting, a comprehensive help system, native scripting (Vim script), a visual mode for text selection, comparison of files ({{man|1|vimdiff|pkg=vim}}), and tools with restricted capabilities such as {{man|1|rview|pkg=vim}} and {{man|1|rvim|pkg=vim}}.<br />
<br />
== Installation ==<br />
<br />
[[Install]] one of the following packages:<br />
<br />
* {{Pkg|vim}} — with [[Python]], [[Lua]], [[Ruby]] and [[Perl]] interpreters support but without [[GTK]]/[[X]] support.<br />
* {{Pkg|gvim}} — which also provides the same as the above ''vim'' package with GTK/X support.<br />
<br />
{{Note|<br />
* The ''vim'' package is built without [[Xorg]] support; specifically the {{ic|+clipboard}} feature is missing, so Vim will not be able to operate with the ''primary'' and ''clipboard'' [[Clipboard|selection buffers]]. The ''gvim'' package provides also the CLI version of Vim with the {{ic|+clipboard}} feature.<br />
* The unofficial repository [[Unofficial user repositories#herecura|herecura]] also provides a number of Vim/gVim variants: {{ic|vim-cli}}, {{ic|vim-gvim-common}}, {{ic|vim-gvim-gtk3}}, {{ic|vim-rt}} and {{ic|vim-tiny}}.<br />
}}<br />
<br />
== Usage ==<br />
<br />
For a basic overview on how to use Vim, follow the vim tutorial by running either ''vimtutor'' (for the terminal version) or ''gvimtutor'' (for the graphical version).<br />
<br />
Vim includes a broad help system that can be accessed with the {{ic|:h ''subject''}} command. Subjects include commands, configuration options, key bindings, plugins etc. Use the {{ic|:h}} command (without any subject) for information about the help system and jumping between subjects.<br />
<br />
== Configuration ==<br />
<br />
Vim's user-specific configuration file is located in the home directory: {{ic|~/.vimrc}}, and Vim files of current user are located inside {{ic|~/.vim/}}. The global configuration file is located at {{ic|/etc/vimrc}}. Global Vim files such as {{ic|defaults.vim}} and {{ic|archlinux.vim}} are located inside {{ic|/usr/share/vim/}}.<br />
<br />
For gVim, the user-specific configuration file is located at {{ic|~/.gvimrc}} and the global configuration file is located at {{ic|/etc/gvimrc}}.<br />
<br />
{{Note|<br />
* Commonly expected behavior such as syntax highlighting is enabled in {{ic|defaults.vim}}, which is loaded when no {{ic|~/.vimrc}} is present. Add {{ic|1=let skip_defaults_vim=1}} to {{ic|/etc/vimrc}} to disable loading of {{ic|defaults.vim}} completely. [https://github.com/vim/vim/issues/1033]. Alternatively, to enable {{ic|defaults.vim}} even when {{ic|~/.vimrc}} is present, see {{ic|:h defaults}} in vim.<br />
* gVim loads both Vim's and gVim's configuration file, while Vim only loads Vim's configuration file.<br />
}}<br />
<br />
=== Clipboard ===<br />
<br />
Vim commands such as {{ic|:yank}} or {{ic|:put}} normally operate with the unnamed register {{ic|""}}. If the {{ic|+clipboard}} feature is available and its value includes {{ic|unnamed}}, then Vim yank, delete, change and put operations which would normally go to the unnamed register will use the clipboard register {{ic|"*}} instead, which is the {{ic|PRIMARY}} buffer in X.<br />
<br />
To change the default register, you can {{ic|1=:set clipboard=unnamedplus}} to use the {{ic|"+}} register instead. The {{ic|"+}} clipboard register corresponds to the {{ic|CLIPBOARD}} buffer in X. It should be noted that the {{ic|clipboard}} option can be set to a comma-delimited value. If you {{ic|1=:set clipboard=unnamedplus,unnamed}}, then yank operations will also copy the yanked text to the {{ic|"*}} register in addition to the {{ic|"+}} register (however, delete, change and put operations will still only operate on the {{ic|"+}} register).<br />
<br />
For more information, see {{ic|:help 'clipboard'}}. There are other values which can be set for the {{ic|clipboard}} feature. You can use {{ic|:help clipboard-unnamed}} to take you to the help topic for the first valid value which can be set for this feature, followed by help for all other valid values.<br />
<br />
{{Tip|<br />
* Custom shortcuts for copy and paste operations can be created. See e.g. [https://superuser.com/a/189198] for binding {{ic|Ctrl+c}}, {{ic|Ctrl+v}} and {{ic|Ctrl+x}}.<br />
* The X clipboard gets flushed when vim exits. To make the vim selection persistent within X clipboard, you need a [[clipboard manager]]. Alternatively, you can add {{ic|autocmd VimLeave * call system("echo -n $'" . escape(getreg(), "'") . "' {{!}} xsel --input --clipboard")}} to your {{ic|.vimrc}} (requires the {{Pkg|xsel}} package).<br />
}}<br />
<br />
=== Syntax highlighting ===<br />
<br />
To enable syntax highlighting for many programming languages:<br />
<br />
:filetype plugin on<br />
:syntax on<br />
<br />
=== Indentation ===<br />
<br />
{{Expansion|Describe the {{ic|autoindent}} and {{ic|smartindent}} options.}}<br />
<br />
The indent file for specific file types can be loaded with:<br />
<br />
:filetype indent on<br />
<br />
=== Visual wrapping ===<br />
<br />
The {{ic|wrap}} option is on by default, which instructs Vim to wrap lines longer than the width of the window, so that the rest of the line is displayed on the next line. The {{ic|wrap}} option only affects how text is displayed, the text itself is not modified.<br />
<br />
The wrapping normally occurs after the last character that fits the window, even when it is in the middle of a word. More intelligent wrapping can be controlled with the {{ic|linebreak}} option. When it is enabled with {{ic|set linebreak}}, the wrapping occurs after characters listed in the {{ic|breakat}} string option, which by default contains a space and some punctuation marks (see {{ic|:help breakat}}).<br />
<br />
Wrapped lines are normally displayed at the beginning of the next line, regardless of any indentation. The [https://retracile.net/wiki/VimBreakIndent breakindent] option instructs Vim to take indentation into account when wrapping long lines, so that the wrapped lines keep the same indentation of the previously displayed line. The behaviour of {{ic|breakindent}} can be fine-tuned with the {{ic|breakindentopt}} option, for example to shift the wrapped line another four spaces to the right for Python files (see {{ic|:help breakindentopt}} for details):<br />
<br />
autocmd FileType python set breakindentopt=shift:4<br />
<br />
=== Using the mouse ===<br />
<br />
Vim has the ability to make use of the mouse, but it only works for certain terminals:<br />
<br />
* [[xterm]]/[[urxvt]]-based terminal emulators<br />
* Linux console with {{Pkg|gpm}} (see [[Console mouse support]] for details)<br />
* [[PuTTY]]<br />
<br />
To enable this feature, add this line into {{ic|~/.vimrc}}:<br />
<br />
set mouse=a<br />
<br />
The {{ic|1=mouse=a}} option is set in {{ic|defaults.vim}}.<br />
<br />
{{Note|Copy/paste will use the {{ic|"*}} register if there is access to an X server, see the [[#Clipboard]] section. The xterm handling of the mouse buttons can still be used by keeping the {{ic|shift key}} pressed.}}<br />
<br />
=== Traverse line breaks with arrow keys ===<br />
<br />
By default, pressing {{ic|Left}} at the beginning of a line, or pressing {{ic|Right}} at the end of a line, will not let the cursor traverse to the previous, or following, line.<br />
<br />
The default behavior can be changed by adding {{ic|1=set whichwrap=b,s,<,>,[,]}} to your {{ic|~/.vimrc}} file.<br />
<br />
== Merging files ==<br />
<br />
Vim includes a diff editor (a program that shows differences between two or more files and aids to conveniently merge them). Use ''vimdiff'' to run the diff editor — just specify some couple of files to it: {{ic|vimdiff ''file1'' ''file2''}}. Here is the list of ''vimdiff''-specific commands.<br />
<br />
{| class="wikitable"<br />
! Action !! Shortcut<br />
|-<br />
| next change || {{ic|]c}}<br />
|-<br />
| previous change || {{ic|[c}}<br />
|-<br />
| diff obtain || {{ic|do}}<br />
|-<br />
| diff put || {{ic|dp}}<br />
|-<br />
| fold open || {{ic|zo}}<br />
|-<br />
| fold close || {{ic|zc}}<br />
|-<br />
| rescan files || {{ic|:diffupdate}}<br />
|}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Line numbers ===<br />
<br />
To show the line number column, use {{ic|:set number}}. By default absolute line numbers are shown, relative numbers can be enabled with {{ic|:set relativenumber}}. Setting both enables hybrid line numbers—the current line is absolute, while the others are relative.<br />
<br />
Jumping to a specific line is possible with {{ic|:''line number''}} or {{ic|''line number''gg}}. Jumps are remembered in a jump list, see {{ic|:h jump-motions}} for details.<br />
<br />
=== Spell checking ===<br />
<br />
Vim has the ability to do spell checking, enable by entering:<br />
<br />
set spell<br />
<br />
By default, only English language dictionaries are installed (in {{ic|/usr/share/vim/vim82/spell/}}). More dictionaries can be found in the [[official repositories]] by searching for {{ic|vim-spell}}. Additional dictionaries can be found in the [http://ftp.vim.org/vim/runtime/spell/ Vim's FTP archive]. Additional dictionaries can be put in the folder {{ic|~/.vim/spell/}} and enabled with the command: {{ic|1=:setlocal spell spelllang=''en_us''}} (replacing the {{ic|''en_us''}} with the name of the needed dictionary).<br />
<br />
{| class="wikitable"<br />
! Action !! Shortcut<br />
|-<br />
| next spelling || {{ic|]s}}<br />
|-<br />
| previous spelling || {{ic|[s}}<br />
|-<br />
| spelling suggestions || {{ic|1=z=}}<br />
|-<br />
| spelling good, add || {{ic|zg}}<br />
|-<br />
| spelling good, session || {{ic|zG}}<br />
|-<br />
| spelling wrong, add || {{ic|zw}}<br />
|-<br />
| spelling wrong, session || {{ic|zW}}<br />
|-<br />
| spelling repeat all in file || {{ic|:spellr}}<br />
|}<br />
<br />
{{Tip|<br />
* To enable spelling in two languages (for instance English and German), add {{ic|1=set spelllang=''en,de''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim.<br />
* You can enable spell checking for arbitrary file types (e.g. ''.txt'') by using the FileType plugin and a custom rule for file type detection. To enable spell checking for any file ending with ''.txt'', create the file {{ic|/usr/share/vim/vimfiles/ftdetect/plaintext.vim}}, and insert the line {{ic|1=autocmd BufRead,BufNewFile *.txt set filetype=plaintext}} into that file. Next, insert the line {{ic|1=autocmd FileType plaintext setlocal spell spelllang=''en_us''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim. Alternatively, one can simply insert the line {{ic|autocmd BufRead,BufNewFile *.txt setlocal spell}} into their {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim. Be sure to edit this line (specifically {{ic|*.txt}}) to include the filetype(s) intended for spell checking.<br />
* To enable spell checking for LaTeX (or TeX) documents only, add {{ic|1=autocmd FileType '''tex''' setlocal spell spelllang=''en_us''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim.<br />
}}<br />
<br />
=== Saving runtime state ===<br />
<br />
Normally, exiting {{ic|vim}} discards all unessential information such as opened files, command line history, yanked text etc. Preserving this information can be configured in the following ways.<br />
<br />
==== viminfo files ====<br />
<br />
The {{ic|viminfo}} file may also be used to store command line history, search string history, input-line history, registers' content, marks for files, location marks within files, last search/substitute pattern (to be used in search mode with {{ic|n}} and {{ic|&}} within the session), buffer list, and any global variables you may have defined. For the {{ic|viminfo}} modality to be available, the version of {{ic|vim}} you installed must have been compiled with the {{ic|+viminfo}} feature.<br />
<br />
Configure what is kept in your {{ic|viminfo}} file, by adding (for example) the following to your {{ic|~/.vimrc}} file:<br />
<br />
set viminfo='10,<100,:100,%,n~/.vim/.viminfo<br />
<br />
where each parameter is preceded by an identifier:<br />
<br />
'q : q, number of edited file remembered<br />
<m : m, number of lines saved for each register<br />
:p : p, number of history cmd lines remembered<br />
% : saves and restore the buffer list<br />
n...: fully qualified path to the viminfo files (note that this is a literal "''n''")<br />
<br />
See the official [https://vimdoc.sourceforge.net/htmldoc/options.html#'viminfo' viminfo documentation] for particulars on how a pre-existing {{ic|viminfo}} file is modified as it is updated with current session information, say from several buffers in the current session you are in the process of exiting.<br />
<br />
==== Session files ====<br />
<br />
Session files can be used to save the state of any number of particular sessions over time. One distinct session file may be used for each session or project of your interest. For that modality to be available, the version of {{ic|vim}} you installed must have been compiled with the {{ic|+mksession}} feature.<br />
<br />
Within a session, {{ic|:mksession[!] [''my_session_name.vim'']}} will write a vim-script to {{ic|''my_session_name.vim''}} in the current directory, or {{ic|Session.vim}} by default if you choose ''not'' to provide a file name. The optional {{ic|!}} will clobber a pre-existing session file with the same name and path.<br />
<br />
A {{ic|vim}} session can be resumed either when starting ''vim'' from terminal:<br />
<br />
$ vim -S [''my_session_name.vim'']<br />
<br />
Or in an already opened session buffer by running the vim command:<br />
<br />
:source ''my_session_name.vim''<br />
<br />
Exactly what is saved and additional details on session files options are extensively covered in the [https://vimdoc.sourceforge.net/htmldoc/usr_21.html#21.4 vim documentation]. Commented examples are found [https://vim.wikia.com/wiki/Go_away_and_come_back here].<br />
<br />
==== Saving cursor position ====<br />
<br />
See [https://vim.wikia.com/wiki/Restore_cursor_to_file_position_in_previous_editing_session Restore cursor to file position in previous editing session] on the Vim wiki.<br />
<br />
=== Replace vi command with Vim ===<br />
<br />
Create an [[alias]] for {{ic|vi}} to {{ic|vim}}.<br />
<br />
Alternatively, if you want to be able to type {{ic|sudo vi}} and get {{ic|vim}}, install {{AUR|vi-vim-symlink}} which will remove {{ic|vi}} and replace it with a symlink to {{ic|vim}}. You could also create this symlink yourself and place it somewhere higher in your path than {{ic|/usr/bin}} to have it take precedence.<br />
<br />
=== DOS/Windows carriage returns ===<br />
<br />
If there is a {{ic|^M}} at the end of each line then this means you are editing a text file which was created in MS-DOS or Windows. This is because in Linux only a single line feed character (LF) used for line break, but in Windows/MS DOS systems they are using a sequence of a carriage return (CR) and a line feed (LF) for the same. And this carriage returns are displayed as {{ic|^M}}.<br />
<br />
To remove all carriage returns from a file do:<br />
<br />
:%s/^M//g<br />
<br />
Note that there {{ic|^}} is a control letter. To enter the control sequence {{ic|^M}} press {{ic|Ctrl+v,Ctrl+m}}.<br />
<br />
Alternatively install the package {{Pkg|dos2unix}} and run {{ic|dos2unix ''file''}} to fix the file.<br />
<br />
{{Note|Another simple way is by changing {{ic|fileformat}} setting. {{ic|1=set ff=unix}} to convert files with DOS/Windows line ending to Unix line ending. To do the reverse, just issue {{ic|1=set ff=dos}} to convert files with Unix line ending to DOS/Windows line ending.}}<br />
<br />
=== Empty space at the bottom of gVim windows ===<br />
<br />
When using a [[window manager]] configured to ignore window size hints, gVim will fill the non-functional area with the GTK theme background color.<br />
<br />
The solution is to adjust how much space gVim reserves at the bottom of the window. Put the following line in {{ic|~/.vimrc}}:<br />
<br />
set guiheadroom=0<br />
<br />
{{Note|If you set it to zero, you will not be able to see the bottom horizontal scrollbar.}}<br />
<br />
=== Vim as a pager ===<br />
<br />
Scripts allow Vim to be used as a [[terminal pager]], with the benefit of various vim features such as color schemes. To change the default pager, [[export]] the {{ic|PAGER}} environment variable.<br />
<br />
Vim comes with the {{ic|/usr/share/vim/vim90/macros/less.sh}} script, for which you can create an [[alias]]. Note that this script does not support any command-line flags mentioned in {{man|1|less|OPTIONS}}.<br />
<br />
Alternatively, there is also the {{Pkg|vimpager}} Vim script. Note that not all command-line flags are supported; the list of supported flags is [https://github.com/rkitover/vimpager#command-line-options available on GitHub].<br />
<br />
A middle way between a pager and an editor are {{ic|[g]vim -R}} ({{ic|gvim -R}} is equivalent to {{ic|gview}}). This will cause the editor to open files in a {{ic|readonly}} mode. Every editor feature that does not involve modifying the files is available as usual. In fact, the {{ic|readonly}} mode can be explicitly overridden, to enable modification as well.<br />
<br />
=== Highlighting search results ===<br />
<br />
In order to highlight the first string that will be matched in a search while typing the search, add the following line to your {{ic|~/.vimrc}}:<br />
<br />
set incsearch<br />
<br />
In order to highlight all strings that will be matched in a search while typing the search, and after the search has been executed, add the following line to your {{ic|~/.vimrc}}:<br />
<br />
set hlsearch<br />
<br />
{{Note|<br />
* Setting {{ic|hlsearch}} will keep all matches highlighted until a further search is made. This behaviour may be undesired, so to temporarily disable the highlighting until the next search, run {{ic|:nohlsearch}}. If you find yourself running this command often, consider binding it to a key.<br />
* This behaviour will also be observed when matching regex during other commands that involve them like {{ic|s}} or {{ic|g}}.<br />
}}<br />
<br />
=== Workaround for XDG Base Directory specification ===<br />
<br />
Since [https://github.com/vim/vim/commit/6a459902592e2a4ba68 7.3.1178] vim will search for {{ic|~/.vim/vimrc}} if {{ic|~/.vimrc}} is not found.<br />
<br />
{{hc|"$XDG_CONFIG_HOME"/vim/vimrc|<nowiki><br />
set runtimepath^=$XDG_CONFIG_HOME/vim<br />
set runtimepath+=$XDG_DATA_HOME/vim<br />
set runtimepath+=$XDG_CONFIG_HOME/vim/after<br />
<br />
set packpath^=$XDG_DATA_HOME/vim,$XDG_CONFIG_HOME/vim<br />
set packpath+=$XDG_CONFIG_HOME/vim/after,$XDG_DATA_HOME/vim/after<br />
<br />
let g:netrw_home = $XDG_DATA_HOME."/vim"<br />
call mkdir($XDG_DATA_HOME."/vim/spell", 'p')<br />
<br />
set backupdir=$XDG_STATE_HOME/vim/backup | call mkdir(&backupdir, 'p')<br />
set directory=$XDG_STATE_HOME/vim/swap | call mkdir(&directory, 'p')<br />
set undodir=$XDG_STATE_HOME/vim/undo | call mkdir(&undodir, 'p')<br />
set viewdir=$XDG_STATE_HOME/vim/view | call mkdir(&viewdir, 'p')<br />
<br />
if !has('nvim') | set viminfofile=$XDG_STATE_HOME/vim/viminfo | endif<br />
</nowiki>}}<br />
<br />
{{hc|~/.profile|2=<br />
export GVIMINIT='let $MYGVIMRC="$XDG_CONFIG_HOME/vim/gvimrc" {{!}} source $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC="$XDG_CONFIG_HOME/vim/vimrc" {{!}} source $MYVIMRC'<br />
}}<br />
<br />
{{ic|[G]VIMINIT}} environment variable will also affect Neovim. If separate configs for Vim and Neovim are desired then the following will be a better choice:<br />
export GVIMINIT='let $MYGVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/gvimrc" : "$XDG_CONFIG_HOME/nvim/init.gvim" | so $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/vimrc" : "$XDG_CONFIG_HOME/nvim/init.vim" | so $MYVIMRC'<br />
<br />
* https://jorengarenar.github.io/blog/vim-xdg<br />
* https://tlvince.com/vim-respect-xdg<br />
<br />
== Plugins ==<br />
<br />
Adding plugins to Vim can increase your productivity by extending Vim's features. Plugins can alter Vim's UI, add new commands, enable code completion support, integrate other programs and utilities with Vim, add support for additional languages and more.<br />
<br />
{{Tip|For a list of popular plugins, see [https://vimawesome.com/ Vim Awesome].}}<br />
<br />
=== Installation ===<br />
<br />
==== Using the built-in package manager ====<br />
<br />
Vim 8 added the possibility to load third-party plugins natively. This functionality can be used by storing third-party packages in the {{ic|~/.vim/pack}} folder. The structure of this folder differs slightly from that of typical plugin managers which will usually have a single directory per plugin. What follows is a typical installation procedure and directory structure (using [https://github.com/tpope/vim-surround Tim Pope's vim-surround plugin] as an example):<br />
<br />
$ mkdir -p ~/.vim/pack/tpope/start<br />
<br />
It is important to note that {{ic|~/.vim/pack/tpope}} is a ''package directory'' which is loosely defined as directory containing one or more plugins in the [https://vimhelp.org/repeat.txt.html#packages Vim documentation]. Plugin repositories should not be downloaded to this directory though. The name of the package directory is also arbitrary. You can choose to keep all your plugins in a single package directory or, as in our example, use the author's GitHub name, {{ic|tpope}}.<br />
<br />
The package directory can contain the following subfolders:<br />
<br />
* {{ic|start}} - plugins from this subfolder will be loaded automatically when Vim starts. This is the most frequently used location.<br />
* {{ic|opt}} - plugins from this subfolder can be loaded on-demand by issuing {{ic|:packadd}} command inside Vim.<br />
<br />
Now change into the {{ic|start}} folder and checkout the plugin repository:<br />
<br />
$ cd ~/.vim/pack/tpope/start<br />
$ git clone https://tpope.io/vim/surround.git<br />
<br />
This creates an additional subfolder, {{ic|~/.vim/pack/tpope/start/surround}}, where the plugin files are placed.<br />
<br />
Next, update the help index if the plugin contains help files:<br />
<br />
$ vim -u NONE -c "helptags surround/doc" -c q<br />
<br />
The plugin will now be loaded automatically when starting Vim. No changes to {{ic|~/.vimrc}} are required, barring plugin-specific options.<br />
<br />
==== Using a plugin manager ====<br />
<br />
A plugin manager is a plugin that installs, manages and updates Vim plugins. This can be useful if you are also using Vim on platforms other than Arch Linux and want a consistent method of updating plugins.<br />
<br />
* [https://github.com/junegunn/vim-plug Vim-plug] is a minimalist Vim plugin manager with many features like on-demand plugin loading and parallel updating, available as {{AUR|vim-plug}} or {{AUR|vim-plug-git}}.<br />
* [https://github.com/gmarik/Vundle.vim Vundle] is available as {{AUR|vundle}} or {{AUR|vundle-git}}.<br />
* [https://github.com/tpope/vim-pathogen pathogen.vim] is a simple plugin for managing Vim's runtimepath, available as {{AUR|vim-pathogen}} or {{AUR|vim-pathogen-git}}.<br />
* [https://github.com/Shougo/dein.vim Dein.vim] is a plugin manager replacing [https://github.com/Shougo/neobundle.vim NeoBundle], available as {{AUR|vim-dein}} or {{AUR|vim-dein-git}}.<br />
<br />
==== From Arch repositories ====<br />
<br />
The {{Grp|vim-plugins}} group provides various plugins. Use {{ic|pacman -Sg vim-plugins}} command to list available packages which you can then [[install]] with pacman.<br />
<br />
=== Notable plugins ===<br />
<br />
==== cscope ====<br />
<br />
[https://cscope.sourceforge.net/ Cscope] is a tool for browsing a project. By navigating to a word/symbol/function and calling cscope (usually with shortcut keys) it can find: functions calling the function, the function definition, and more.<br />
<br />
[[Install]] the {{Pkg|cscope}} package.<br />
<br />
Copy the cscope default file where it will be automatically read by Vim:<br />
<br />
mkdir -p ~/.vim/plugin<br />
wget -P ~/.vim/plugin https://cscope.sourceforge.net/cscope_maps.vim<br />
<br />
{{Note|You will probably need to uncomment these lines in {{ic|~/.vim/plugin/cscope_maps.vim}} in order to enable cscope shortcuts in Vim 7.x:<br />
{{bc|1=<br />
set timeoutlen=4000<br />
set ttimeout<br />
}}}}<br />
<br />
Create a file which contains the list of files you wish cscope to index (cscope can handle many languages but this example finds ''.c'', ''.cpp'' and ''.h'' files, specific for C/C++ project):<br />
<br />
$ cd ''/path/to/project/dir''<br />
$ find . -type f -print | grep -E '\.(c(pp)?|h)$' > cscope.files<br />
<br />
Create database files that cscope will read:<br />
<br />
$ cscope -bq<br />
<br />
{{Note|You must browse your project files from this location or set and export the {{ic|$CSCOPE_DB}} variable, pointing it to the {{ic|cscope.out}} file.}}<br />
<br />
Default keyboard shortcuts:<br />
<br />
Ctrl-\ and<br />
c: Find functions calling this function<br />
d: Find functions called by this function<br />
e: Find this egrep pattern<br />
f: Find this file<br />
g: Find this definition<br />
i: Find files #including this file<br />
s: Find this C symbol<br />
t: Find assignments to<br />
<br />
Feel free to change the shortcuts.<br />
<br />
#Maps ctrl-c to find functions calling the function<br />
nnoremap <C-c> :cs find c <C-R>=expand("<cword>")<CR><CR><br />
<br />
==== Taglist ====<br />
<br />
[https://vim-taglist.sourceforge.net/ Taglist] provides an overview of the structure of source code files and allows you to efficiently browse through source code files in different programming languages.<br />
<br />
[[Install]] the {{AUR|vim-taglist}} package.<br />
<br />
Useful options to be put in {{ic|~/.vimrc}}:<br />
<br />
let Tlist_Compact_Format = 1<br />
let Tlist_GainFocus_On_ToggleOpen = 1<br />
let Tlist_Close_On_Select = 1<br />
nnoremap <C-l> :TlistToggle<CR><br />
<br />
== Troubleshooting ==<br />
<br />
=== gVim is slow ===<br />
<br />
Vim's GTK 3 GUI may be slower than the GTK 2 version (see {{Bug|51366}}). {{AUR|gvim-gtk2}} can be installed as a workaround.<br />
<br />
== See also ==<br />
<br />
=== Official ===<br />
<br />
* [https://www.vim.org/ Homepage]<br />
* [https://vimdoc.sourceforge.net/ Documentation]<br />
* [https://vim.wikia.com Vim Wiki]<br />
* [https://www.vim.org/scripts/ Vim Scripts]<br />
<br />
=== Tutorials ===<br />
<br />
* [https://danielmiessler.com/study/vim/ vim Tutorial and Primer]<br />
* [https://web.archive.org/web/20140822135551/http://usalug.com/vi.html vi Tutorial and Reference Guide]<br />
* [http://www.viemu.com/a_vi_vim_graphical_cheat_sheet_tutorial.html Graphical vi-Vim Cheat Sheet and Tutorial]<br />
* [https://archive.today/2012.12.20-221858/http://blog.interlinked.org/tutorials/vim_tutorial.html Vim Introduction and Tutorial]<br />
* [https://www.openvim.com/ Open Vim] — collection of Vim learning tools<br />
* [https://yannesposito.com/Scratch/en/blog/Learn-Vim-Progressively/ Learn Vim Progressively]<br />
* [https://benmccormick.org/learning-vim-in-2014/ Learning Vim in 2014]<br />
* [https://www.moolenaar.net/habits.html Seven habits of effective text editing]<br />
* [https://bencrowder.net/files/vim-fu/ Basic Vim Tips]<br />
<br />
==== Videos ====<br />
<br />
* [http://vimcasts.org/ Vimcasts] — screencasts in ''.ogg'' format.<br />
* [http://derekwyatt.org/vim/tutorials/ Vim Tutorial Videos] — covering the basics up to advanced topics.<br />
<br />
==== Cheat sheets ====<br />
<br />
* https://devhints.io/vim<br />
* https://vim.rtorr.com/ - A mobile friendly Vim cheat sheet - [https://github.com/rtorr/vim-cheat-sheet Sources]<br />
<br />
==== Games ====<br />
<br />
* [https://vim-adventures.com/ Vim Adventures]<br />
* [https://vimgolf.com/ VimGolf]<br />
<br />
=== Configuration ===<br />
<br />
* [https://web.archive.org/web/20131020125020/http://nion.modprobe.de/setup/vimrc nion's]<br />
* [https://github.com/amix/vimrc A detailed configuration from Amir Salihefendic]<br />
* [https://web.archive.org/web/20131004071740/http://www.jukie.net/~bart/conf/vimrc Bart Trojanowski]<br />
* [https://github.com/spf13/spf13-vim Steve Francia's Vim Distribution]<br />
* [https://vimawesome.com/ Vim Awesome] - Vim Plugins<br />
* [https://github.com/W4RH4WK/dotVim W4RH4WK's Vim configuration]<br />
* [https://www.askapache.com/linux/fast-vimrc/ Fast vimrc/colorscheme from askapache]<br />
* [https://gist.github.com/anonymous/c966c0757f62b451bffa Basic vimrc]<br />
<br />
==== Colors ====<br />
<br />
* [http://bytefluent.com/vivify/ Vivify]<br />
* [https://linuxtidbits.wordpress.com/2014/10/14/vim-customize-installed-colorschemes/ Vim colorscheme customization]</div>Regidhttps://wiki.archlinux.org/index.php?title=List_of_applications/Documents&diff=795381List of applications/Documents2023-12-27T19:53:14Z<p>Regid: /* Console */ As far as I can see, {{pkg|ed}} is not mentioned. I can't see why not. Is it because it is tied to the core group? Should this tie be mentioned in template:app description?</p>
<hr />
<div><noinclude><br />
[[Category:Applications]]<br />
[[Category:Lists of software]]<br />
[[es:List of applications (Español)/Documents]]<br />
[[ja:アプリケーション一覧/ドキュメント]]<br />
[[zh-hans:List of applications/Documents]]<br />
{{List of applications navigation}}<br />
</noinclude><br />
== Documents and texts ==<br />
<br />
=== Text editors ===<br />
<br />
See also [[Wikipedia:Comparison of text editors]].<br />
<br />
Some of the lighter-weight [[List of applications/Utilities#Integrated development environments|Integrated development environments]] can also serve as text editors.<br />
<br />
==== Vi-style text editors ====<br />
<br />
* {{App|Amp|Text editor written in Rust, that aims to take the core interaction model of Vim, simplify it, and bundle in the essential features required for a modern text editor.|https://amp.rs/|{{AUR|amp}}}}<br />
* {{App|Aretext|Minimalist text editor with vim-compatible key bindings.|https://aretext.org/|{{AUR|aretext}}}}<br />
* {{App|[[BusyBox]] vi|Provides "a small 'vi' clone". Can be invoked with {{ic|busybox vi}}.|https://git.busybox.net/busybox/tree/editors/vi.c|{{Pkg|busybox}}}}<br />
* {{App|[[Kakoune]]|Modal editor. Fewer keystrokes. Selection based, multi-cursor editing. Orthogonal design.|https://github.com/mawww/kakoune|{{Pkg|kakoune}}}}<br />
* {{App|[[Helix]]| A post-modern modal text editor.|https://helix-editor.com/|{{Pkg|helix}}}}<br />
* {{App|[[Neovim]]|Vim's rebirth for the 21st century.|https://neovim.io/|{{Pkg|neovim}}}}<br />
* {{App|Neovim-Qt|Qt GUI for Neovim.|https://github.com/equalsraf/neovim-qt|{{Pkg|neovim-qt}}}}<br />
* {{App|[[Wikipedia:vi|vi]]|The original ex/vi text editor.|https://ex-vi.sourceforge.net/|{{Pkg|vi}}}}<br />
* {{App|[[Vim]]|Advanced text editor that seeks to provide the power of the de-facto Unix editor 'vi', with a more complete feature set.|https://www.vim.org/|with GUI: {{Pkg|gvim}}, without GUI: {{Pkg|vim}}}}<br />
* {{App|Vis|Modern, legacy free, simple yet efficient vim-like editor.|https://github.com/martanne/vis|{{Pkg|vis}}}}<br />
<br />
==== Emacs-style text editors ====<br />
<br />
* {{App|[[Emacs]]|The extensible, customizable, self-documenting real-time display editor by GNU.|https://www.gnu.org/software/emacs/emacs.html|with GUI: {{Pkg|emacs}}, without GUI: {{Pkg|emacs-nox}}}}<br />
* {{App|[[Wikipedia:mg (editor)|mg]]|Small, fast, and portable Emacs-like editor.|https://github.com/hboetes/mg|{{Pkg|mg}}}}<br />
* {{App|[[Wikipedia:Vile (editor)|vile]]|Lightweight Emacs clone with ''vi''-like key bindings.|https://invisible-island.net/vile/vile.html|{{AUR|vile}}}}<br />
* {{App|Zile|Lightweight Emacs clone.|https://www.gnu.org/software/zile/|{{AUR|zile}}}}<br />
<br />
==== Console ====<br />
<br />
* {{App|dte|Small, easy to use editor with multi-tabbed interface, syntax highlighting, ctags navigation, etc.|https://craigbarnes.gitlab.io/dte/|{{AUR|dte}}}}<br />
* {{App|e3|Tiny editor without dependencies, written in assembly.|https://sites.google.com/site/e3editor/|{{Pkg|e3}}}}<br />
* {{App|ed|A POSIX-compliant line-oriented text editor. Useful for shell scripts, less so for manual usage. Original editor for Unix.|https://www.gnu.org/software/ed/ed.html|{{Pkg|ed}}}}<br />
* {{App|ee|Classic curse-based text editor. Born in HP-UX, used in FreeBSD.|https://web.archive.org/web/20160719002816/http://www.users.qwest.net/~hmahon/|{{aur|ee-editor}}}}<br />
* {{App|[[Wikipedia:JED (text editor)|JED]]|Text editor that makes extensive use of the [[Wikipedia:S-Lang|S-Lang library]]. Includes a console version (jed) and an X-window version (xjed).|http://jedsoft.org/jed/|{{AUR|jed}}}}<br />
* {{App|[[Wikipedia:Joe's Own Editor|JOE (Joe's Own Editor)]]|Terminal-based text editor designed to be easy to use.|https://joe-editor.sourceforge.io/|{{AUR|joe}}}}<br />
* {{App|[[Wikipedia:Midnight Commander|mcedit]]|Useful text editor that comes with Midnight Commander file manager.|https://www.ibiblio.org/mc/|{{Pkg|mc}}}}<br />
* {{App|micro|Modern and intuitive terminal-based text editor, written in go and extensible through plugins.|https://micro-editor.github.io/|{{Pkg|micro}}}}<br />
* {{App|Minimum Profit|Text editor for programmers.|https://triptico.com/software/mp.html|{{AUR|mp}}}}<br />
* {{App|[[nano]]|Console text editor based on pico with on-screen key bindings help.|https://nano-editor.org/|{{Pkg|nano}}}}<br />
* {{App|ne|Minimalist text editor with Windows-like key-bindings.|http://ne.di.unimi.it/|{{AUR|ne}}}}<br />
* {{App|slap|Sublime-like terminal-based text editor.|https://github.com/slap-editor/slap|{{AUR|slap}}}}<br />
* {{App|Tilde|Intuitive text editor with Windows-like key bindings.|https://os.ghalkes.nl/tilde/|{{AUR|tilde}}}}<br />
* {{App|jove|Jonathan's Own Version of Emacs is an Emacs-like editor without Lisp.|https://github.com/jonmacs/jove|{{AUR|jove}}}}<br />
<br />
==== Graphical ====<br />
<br />
* {{App|[[Wikipedia:Acme (text editor)|Acme]]|Minimalist and flexible programming environment developed by Rob Pike for the Plan 9 operating system.|http://acme.cat-v.org/|{{Pkg|plan9port}}}}<br />
* {{App|Adie|Fast and convenient programming text editor.|http://fox-toolkit.org/|{{Pkg|fox}}}}<br />
* {{App|[[Atom]]|Promising text editor developed by GitHub. With support for plug-ins written in Node.js and embedded [[Git]] Control.|https://atom.io/|{{AUR|atom}}}}<br />
* {{App|Beaver|GTK editor designed to be modular, lightweight and stylish.|http://beaver-editor.sourceforge.net/|{{AUR|beaver}}}}<br />
* {{App|[[w:Brackets (text editor)|Brackets]]|Code editor for the web, written in JavaScript, HTML and CSS.|https://brackets.io/|{{AUR|brackets-extract}}}}<br />
* {{App|CorePad|Simple lightweight but powerful text editor with syntax-highlighting support for a dozen or more languages. Part of C-Suite.|https://cubocore.org/{{Dead link|2023|06|17|status=SSL error}}|{{AUR|corepad}}}}<br />
* {{App|Deepin Text Editor|Simple text editor for Deepin desktop.|https://www.deepin.org/en/original/deepin-editor/|{{Pkg|deepin-editor}}}}<br />
* {{App|Ecrire|Simple text editor based on EFL.|https://git.enlightenment.org/apps/ecrire.git/{{Dead link|2022|09|20|status=404}}|{{AUR|ecrire-git}}}}<br />
* {{App|Enki|Text editor for programmers.|http://enki-editor.org/|{{AUR|enki-editor}}}}<br />
* {{App|FeatherPad|Minimal Qt5 plain text editor featuring a native dark theme and support for tabs, printing and syntax highlighting.|https://github.com/tsujan/FeatherPad|{{Pkg|featherpad}}}}<br />
* {{App|FLTK Editor|Simple text editor application for FLTK.|https://www.fltk.org/|{{AUR|fltk-editor}}}}<br />
* {{App|gCSVedit|Simple text editor for CSV, TSV and other kinds of delimiter-separated values (DSV) files.|https://github.com/swilmet/gCSVedit{{Dead link|2022|09|20|status=404}}|{{AUR|gcsvedit}}}}<br />
* {{App|[[Wikipedia:gedit|gedit]]|GTK editor for the GNOME desktop with syntax highlighting, automatic indentation, matching brackets, etc., and a number of add-ons to increase functionality. Part of {{Grp|gnome-extra}}.|https://wiki.gnome.org/Apps/Gedit|{{Pkg|gedit}}}}<br />
* {{App|GNOME Text Editor|Simple text editor for GNOME focused on a pleasing default experience. Part of {{Grp|gnome}}.|https://gitlab.gnome.org/GNOME/gnome-text-editor|{{Pkg|gnome-text-editor}}}}<br />
* {{App|Gobby|Collaborative editor supporting multiple documents in one session and a multi-user chat.|https://gobby.github.io/|{{Pkg|gobby}}}}<br />
* {{App|Howl|General purpose, fast and lightweight editor with a keyboard-centric minimalistic user interface.|https://howl.io/|{{Pkg|howl}}}}<br />
* {{App|[[Wikipedia:jEdit|jEdit]]|Text editor for programmers, written in Java.|https://www.jedit.org/|{{AUR|jedit}}}}<br />
* {{App|[[Wikipedia:JuffEd|JuffEd]]|Simple tabbed text editor with syntax highlighting, written in Qt.|http://juffed.com/en/index.html|{{AUR|juffed}}}}<br />
* {{App|[[Wikipedia:Kate (text editor)|Kate]]|Full-featured programmer's editor for the KDE desktop with MDI and a filesystem browser.|https://kate-editor.org/|{{Pkg|kate}}}}<br />
* {{App|[[Wikipedia:KWrite|KWrite]]|Lightweight text editor for the KDE desktop that uses the same editor widget as Kate, now provided by the kate package.|https://apps.kde.org/kwrite/|{{Pkg|kate}}}}<br />
* {{App|L3afpad|Simple text editor forked from Leafpad, supports GTK 3.|https://github.com/stevenhoneyman/l3afpad|{{Pkg|l3afpad}}}}<br />
* {{App|Lapce|Lightning-fast and Powerful Code Editor written in Rust.|https://lapce.dev/|{{Pkg|lapce}}}}<br />
* {{App|[[Wikipedia:Leafpad|Leafpad]]|Notepad clone for GTK that emphasizes simplicity.|http://tarot.freeshell.org/leafpad/|{{Pkg|leafpad}}}}<br />
* {{App|[[w:Light Table (software)|Light Table]]|Next generation code editor that connects you to your creation with instant feedback.|http://lighttable.com/|{{AUR|lighttable-bin}}{{Broken package link|package not found}}}}<br />
* {{App|Liri Text|Text editor for Liri.|https://github.com/lirios/text|{{Pkg|liri-text}}}}<br />
* {{App|Lite XL|A lightweight, simple, fast, feature-filled, and extremely extensible text editor written in C, and Lua, adapted from lite.|https://lite-xl.com/|{{AUR|lite-xl}}}}<br />
* {{App|medit|Programming and around-programming text editor.|http://mooedit.sourceforge.net|{{AUR|medit}}}}<br />
* {{App|[[Wikipedia:Xfce#Mousepad|Mousepad]]|Fast text editor for the Xfce Desktop Environment.|https://www.xfce.org|{{Pkg|mousepad}}}}<br />
* {{App|[[Wikipedia:NEdit|NEdit]]|Text editor for the Motif environment.|https://sourceforge.net/projects/nedit/|{{AUR|nedit}}}}<br />
* {{App|Notepadqq|Qt-based, Notepad++-like text editor with support for syntax highlighting for more than 100 languages.|https://notepadqq.com/s/|{{Pkg|notepadqq}}}}<br />
* {{App|Nota|Easy to use text editor with a simple interface with support for tabbed documents, syntax highlighting for various languages, Focus mode, annotations, configurable fonts, and colors, a side panel with an integrated file browser, and more.|https://mauikit.org/|{{Pkg|maui-nota}}}}<br />
* {{App|Pantheon Code|Code editor for elementaryOS. It auto-saves your files, meaning they are always up-to-date. Plus it remembers your tabs so you never lose your spot, even in between sessions.|https://github.com/elementary/code|{{Pkg|pantheon-code}}}}<br />
* {{App|[[MATE|Pluma]]|Powerful text editor for MATE.|https://mate-desktop.org/|{{Pkg|pluma}}}}<br />
* {{App|QSciTE|Qt clone of the SciTE text and code editor.|https://code.google.com/archive/p/qscite/|{{AUR|qscite}}}}<br />
* {{App|[[Wikipedia:Sam (text editor)|Sam]]|Minimalist text editor with a graphical user interface, a very powerful command language and remote editing capabilities, developed by Rob Pike.|http://sam.cat-v.org|{{Pkg|plan9port}} or {{Pkg|9base}}}}<br />
* {{App|[[Wikipedia:SciTE|SciTE]]|Generally useful editor with facilities for building and running programs.|https://scintilla.org/SciTE.html|{{Pkg|scite}}}}<br />
* {{App|[[Wikipedia:Sublime Text|Sublime Text]]|Proprietary C++ and Python-based editor with many advanced features and plugins while staying lightweight and pretty.|https://www.sublimetext.com/|version 3: {{AUR|sublime-text-dev}}, version 4: {{AUR|sublime-text-4}}}}<br />
* {{App|Tau|Minimal GTK front end to the xi editor core written in Rust.|https://gitlab.gnome.org/World/Tau|{{AUR|tau-editor}}}}<br />
* {{App|[[Wikipedia:TEA (text editor)|TEA]]|Qt-based feature-rich text editor.|http://semiletov.org/tea/|{{AUR|tea-qt}}}}<br />
* {{App|[[Textadept]]|Lua-extensible feature rich text editor based on Scintilla and written in C.|https://foicica.com/textadept/|{{AUR|textadept}}}}<br />
* {{App|Textosaurus|Simple cross-platform text editor based on Qt and QScintilla.|https://github.com/martinrotter/textosaurus|{{AUR|textosaurus}}}}<br />
* {{App|[[Visual Studio Code]]|Editor for building and debugging modern web and cloud applications.|https://code.visualstudio.com|{{Pkg|code}}}}<br />
* {{App|[[Visual Studio Code|VSCodium]]|Visual Studio Code, but compiled without telemetry.|https://vscodium.com/|{{AUR|vscodium}}}}<br />
* {{App|xed|Text editor based on Pluma developed for Linux Mint.|https://github.com/linuxmint/xed|{{Pkg|xed}}}}<br />
* {{App|XEdit|Simple text editor for the X Window System.|https://www.x.org/wiki|{{Pkg|xorg-xedit}}}}<br />
* {{App|wxMEdit|Text/Hex editor written in C++ and wxWidgets.|https://wxmedit.github.io/|{{AUR|wxmedit}}}}<br />
<br />
==== Optimized for large files ====<br />
<br />
* {{App|glogg|A fast, advanced log explorer.|https://github.com/nickbnf/glogg|{{AUR|glogg}}}}<br />
* {{App|Klogg|Really fast log explorer based on glogg project.|https://github.com/variar/klogg|{{AUR|klogg}}}}<br />
<br />
=== Office ===<br />
<br />
==== Office suites ====<br />
<br />
See also [[Wikipedia:Comparison of office suites]].<br />
<br />
* {{App|[[Wikipedia:Calligra Suite|Calligra]]|Actively developed fork of KOffice, the [[KDE]] office suite. It offers most of the features of OpenOffice while also having versions for smartphones (Calligra Mobile) and tablets (Calligra Active).|https://calligra.org/|{{Pkg|calligra}}}}<br />
* {{App|[[LibreOffice]]|The office productivity suite compatible to the open and standardized ODF document format. Fork of OpenOffice, supported by The Document Foundation.|https://www.libreoffice.org/|{{Pkg|libreoffice-still}} or {{Pkg|libreoffice-fresh}}}}<br />
* {{App|[[Wikipedia:OnlyOffice|OnlyOffice]]|Office suite that combines text, spreadsheet and presentation editors.|https://www.onlyoffice.com/|{{AUR|onlyoffice-bin}}}}<br />
* {{App|[[OpenOffice]]|Open-source office software suite for word processing, spreadsheets, presentations, graphics, databases and more, under the Apache Licence.|https://www.openoffice.org/|{{AUR|openoffice-bin}}}}<br />
* {{App|[[Wikipedia:SoftMaker Office|SoftMaker Office]]|Complete, reliable, lightning-fast and Microsoft Office-compatible proprietary office suite with a word processor, spreadsheet, and presentation graphics software.|https://www.freeoffice.com/|{{AUR|freeoffice}}}}<br />
* {{App|[[WPS Office]]|Proprietary office productivity suite, previously known as Kingsoft Office.|https://www.wps.com/|{{AUR|wps-office}}}}<br />
* {{App|Yozo Office|Proprietary office suite, compatible with MS Office.|https://www.yozosoft.com/product-officelinux.html|{{AUR|yozo-office}}}}<br />
<br />
==== Word processors ====<br />
<br />
See also [[Wikipedia:Comparison of word processors]].<br />
<br />
* {{App|[[AbiWord]]|Full-featured word processor.|https://www.abisource.com/|{{Pkg|abiword}}}}<br />
* {{App|[[Wikipedia:Calligra Words|Calligra Words]]|Powerful word processor included in the Calligra Suite.|https://www.calligra.org/words/|{{Pkg|calligra}}}}<br />
* {{App|[[LibreOffice|LibreOffice Writer]]|Full-featured word processor included in the LibreOffice suite.|https://www.libreoffice.org/discover/writer|{{Pkg|libreoffice-still}} or {{Pkg|libreoffice-fresh}}}}<br />
* {{App|[[OpenOffice|OpenOffice Writer]]|Full-featured word processor included in the OpenOffice suite.|https://www.openoffice.org/product/writer.html|{{AUR|openoffice-bin}}}}<br />
* {{App|[[Wikipedia:Ted (word processor)|Ted]]|Easy to use GTK-based rich text processor (with footnote support).|https://nllgg.nl/Ted/|{{AUR|ted}}}}<br />
* {{App|[[Wikipedia:WordGrinder|WordGrinder]]|Word processor for the console.|https://cowlark.com/wordgrinder/|{{AUR|wordgrinder}}}}<br />
<br />
===== WYSIWYG HTML editors =====<br />
<br />
* {{App|PageEdit|ePub visual XHTML editor.|https://github.com/Sigil-Ebook/PageEdit|{{Pkg|pageedit}}}}<br />
* {{App|[[Wikipedia:SeaMonkey#Composer|SeaMonkey Composer]]|Powerful yet simple HTML editor included in the SeaMonkey suite.|https://www.seamonkey-project.org/|{{AUR|seamonkey}}}}<br />
<br />
===== Desktop publishing =====<br />
<br />
* {{App|gLabels|Program for creating labels, business cards and media covers.|http://glabels.org/|{{Pkg|glabels}}}}<br />
* {{App|[[Wikipedia:Scribus|Scribus]]|Desktop publishing program. Uses {{Pkg|hyphen}} and its language packs for hyphenation. |https://www.scribus.net/|{{Pkg|scribus}}}}<br />
<br />
==== Presentations ====<br />
<br />
* {{App|[[Wikipedia:Calligra Stage|Calligra Stage]]|Easy to use yet still flexible presentation application included in the Calligra Suite.|https://www.calligra.org/stage/|{{Pkg|calligra}}}}<br />
* {{App|[[LibreOffice|LibreOffice Impress]]|Presentation program included in the LibreOffice suite.|https://www.libreoffice.org/discover/writer|{{Pkg|libreoffice-still}} or {{Pkg|libreoffice-fresh}}}}<br />
* {{App|MDP|A command-line based markdown presentation tool.|https://github.com/visit1985/mdp|{{Pkg|mdp}}}}<br />
* {{App|[[OpenOffice|OpenOffice Impress]]|Presentation program included in the OpenOffice suite.|https://www.openoffice.org/product/impress.html|{{AUR|openoffice-bin}}}}<br />
* {{App|sent|Simple plaintext presentation tool.|https://git.suckless.org/sent/|{{AUR|sent}}}}<br />
* {{App|Sozi|Zooming presentation editor and player. Based on the [https://electronjs.org/ Electron] platform.|https://sozi.baierouge.fr/|{{AUR|sozi}}}}<br />
* {{App|Spice-Up|Create simple and beautiful presentations.|https://github.com/Philip-Scott/Spice-up|{{Pkg|spice-up}}}}<br />
<br />
==== Spreadsheets ====<br />
<br />
See also [[Wikipedia:Comparison of spreadsheet software]].<br />
<br />
* {{App|[[Wikipedia:Calligra Sheets|Calligra Sheets]]|Powerful spreadsheet application included in the Calligra Suite.|https://www.calligra.org/sheets/|{{Pkg|calligra}}}}<br />
* {{App|Gnumeric|Spreadsheet program for the GNOME desktop.|http://www.gnumeric.org/|{{Pkg|gnumeric}}}}<br />
* {{App|[[LibreOffice|LibreOffice Calc]]|Full-featured spreadsheet application included in the LibreOffice suite.|https://www.libreoffice.org/discover/calc/|{{Pkg|libreoffice-still}} or {{Pkg|libreoffice-fresh}}}}<br />
* {{App|[[OpenOffice|OpenOffice Calc]]|Full-featured spreadsheet application included in the OpenOffice suite.|https://www.openoffice.org/product/calc.html|{{AUR|openoffice-bin}}}}<br />
* {{App|[[Wikipedia:Pyspread|Pyspread]]|Pyspread is a non-traditional spreadsheet application that is based on and written in the programming language Python.|https://pyspread.gitlab.io|{{AUR|pyspread}}}}<br />
* {{App|[[Wikipedia:sc (spreadsheet calculator)|sc]]|Curses-based lightweight spreadsheet.|https://ibiblio.org/pub/linux/apps/financial/spreadsheet/!INDEX.html|{{Pkg|sc}}}}<br />
* {{App|sc-im|Spreadsheet program based on sc.|https://github.com/andmarti1424/sc-im/|{{AUR|sc-im}}}}<br />
<br />
==== Database tools ====<br />
<br />
For DBMS-specific tools, see:<br />
<br />
* [[MySQL#Graphical tools]]<br />
* [[PostgreSQL#Graphical tools]]<br />
* [[SQLite#Software]]<br />
* [[MongoDB#Tools]]<br />
<br />
See also [[Wikipedia:Comparison of database tools]].<br />
<br />
* {{App|[[Adminer]]|Full-featured database management webapp with support for many database types.|https://www.adminer.org/|{{AUR|adminer}}}}<br />
* {{App|beekeeper-studio|A modern, easy to use, and good looking SQL client for MySQL, Postgres, SQLite, SQL Server, and more.|https://www.beekeeperstudio.io/|{{AUR|beekeeper-studio}}}}<br />
* {{App|[[Wikipedia:DBeaver|DBeaver]]|Java-based graphical database editor with support for many database types.|https://dbeaver.io/|{{Pkg|dbeaver}}}}<br />
* {{App|DbVisualizer|The Universal Database Tool|https://www.dbvis.com/|{{AUR|dbvis}}}}<br />
* {{App|GdaBrowser|Graphical tool to get a quick access to a database's structure and contents.|https://www.gnome-db.org/GdaBrowser|{{Pkg|libgda}}}}<br />
* {{App|GSQL|Integrated database development tool for GNOME. Last released in 2010.|http://gsql.org/|{{AUR|gsql}}}}<br />
* {{App|[[Wikipedia:Kexi|Kexi]]|Visual database applications creator tool by KDE, designed to fill the gap between spreadsheets and database solutions requiring more sophisticated development.|http://kexi-project.org/|{{Pkg|kexi}}}}<br />
* {{App|[[LibreOffice|LibreOffice Base]]|Full-featured desktop database front end included in the LibreOffice suite, designed to meet the needs of a broad array of users.|https://www.libreoffice.org/discover/base/|{{Pkg|libreoffice-still}} or {{Pkg|libreoffice-fresh}}}}<br />
* {{App|[[OpenOffice|OpenOffice Base]]|Full-featured desktop database front end included in the OpenOffice suite, designed to meet the needs of a broad array of users.|https://www.openoffice.org/product/base.html|{{AUR|openoffice-bin}}}}<br />
* {{App|[[Wikipedia:Orbada|Orbada]]|Excellent tool for database developers, SQL developers, DBA administrators, as well as for users who wish to broaden their knowledge and skills in SQL.|https://orbada.sourceforge.io/|{{AUR|orbada}}}}<br />
* {{App|Sequeler|SQL client built in Vala and Gtk. It allows you to connect to your local and remote databases, write SQL in a handy text editor with language recognition, and visualize SELECT results in a Gtk.Grid Widget.|https://github.com/Alecaddd/sequeler|{{AUR|sequeler}}}}<br />
* {{App|[[Wikipedia:SQuirreL SQL Client|SQuirreL SQL Client]]|Graphical Java program that will allow you to view the structure of a JDBC compliant database, browse the data in tables, issue SQL commands etc.|http://www.squirrelsql.org/|{{AUR|squirrel-sql}}}}<br />
* {{App|[[Wikipedia:TOra|TOra]]|Database management GUI that supports accessing most of the common database platforms in use, including Oracle, MySQL, and PostgreSQL, as well as limited support for any target that can be accessed through Qt's ODBC support.|https://github.com/tora-tool/tora/wiki|{{AUR|tora}}}}<br />
<br />
===== Plain-text database utilities =====<br />
<br />
These kinds of software are in a substance somewhat between [[awk|text processing core utilities like awk]], [[#Spreadsheets|spreadsheets]] and production-level [[DBMS|database system]]. And they usually come with a non-SQL command-line interface.<br />
* {{app|recutils|GNU utilities to work with human-editable, plaintext database files (in a simple format called "recfile")|https://gnu.org/s/recutils/|{{aur|recutils}}}}<br />
<br />
===== "Simplified" database software (beginner-friendly database tools) =====<br />
<br />
* {{App|Glom|Easy-to-use database designer and user interface.|https://gitlab.gnome.org/GNOME/glom/|{{Pkg|glom}}}}<br />
* {{App|Symphytum|Personal database software for everyone who desires to manage and organize data in an easy and intuitive way, without having to study complex database languages and software user interfaces.|https://github.com/giowck/symphytum|{{Pkg|symphytum}}}}<br />
* {{App|TreeLine|Store almost any kind of information in a tree structure, which makes it easy to keep things organized.|https://treeline.bellz.org/|{{AUR|treeline}}}}<br />
<br />
==== Formula editors ====<br />
<br />
See also [[#TeX formula editors]] and [[Wikipedia:Formula editor]].<br />
<br />
* {{App|[[LibreOffice|LibreOffice Math]]|Create and edit scientific formulas and equations. Included in the LibreOffice suite.|https://www.libreoffice.org/discover/math/|{{Pkg|libreoffice-still}} or {{Pkg|libreoffice-fresh}}}}<br />
* {{App|[[OpenOffice|OpenOffice Math]]|Create equations and formulas for your documents. Included in the OpenOffice suite.|https://www.openoffice.org/product/math.html|{{AUR|openoffice-bin}}}}<br />
<br />
=== Markup languages ===<br />
<br />
See also [[Wikipedia:Comparison of document markup languages]].<br />
<br />
* {{App|[[Wikipedia:Txt2tags|txt2tags]]|Dead-simple, KISS-compliant lightweight, human-readable markup language to produce rich format content out of plain text files.|https://txt2tags.org/|{{Pkg|txt2tags}}}}<br />
<br />
==== AsciiDoc ====<br />
<br />
See also [[Wikipedia:AsciiDoc]].<br />
<br />
* {{App|AsciiDoc|The original implementation, written in Python. Used by Arch for generating <i>pacman</i>'s man pages.[https://archlinux.org/pacman/pacman.8.html].|https://asciidoc.org/|{{Pkg|asciidoc}}}}<br />
* {{App|Asciidoctor|An implementation written in Ruby, with [https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/ many extra features].|https://asciidoctor.org/|{{Pkg|asciidoctor}}}}<br />
<br />
==== Markdown ====<br />
<br />
See also the [https://daringfireball.net/projects/markdown/ official website] and [[Wikipedia:Markdown]].<br />
<br />
* {{App|cmark|CommonMark parsing and rendering library and program in C.|https://github.com/commonmark/cmark|{{Pkg|cmark}}}}<br />
* {{App|Discount|A Markdown implementation written in C.|https://www.pell.portland.or.us/~orc/Code/discount/|{{Pkg|discount}}, Ruby wrapper library: {{Pkg|ruby-rdiscount}}}}<br />
* {{App|lowdown|Markdown translator producing HTML5 and roff documents in the ms and man formats.|https://kristaps.bsd.lv/lowdown/|{{Pkg|lowdown}}}}<br />
* {{App|Marked|Markdown parser and compiler built for speed.|https://marked.js.org/|{{Pkg|marked}}}}<br />
* {{App|md2html|C Markdown parser.|https://github.com/mity/md4c|{{Pkg|md4c}}}}<br />
* [[Pandoc]] also supports Markdown.<br />
<br />
===== Python implementations =====<br />
<br />
* {{App|CommonMark-py|Python parser for the CommonMark Markdown specification.|https://github.com/rtfd/CommonMark-py|{{Pkg|python-commonmark}}}}<br />
* {{App|M2R|Markdown to reStructuredText converter.|https://github.com/miyakogi/m2r|{{AUR|python-m2r}}{{Broken package link|package not found}}}}<br />
* {{App|Mistune|The fastest markdown parser in pure Python with renderer feature.|https://github.com/lepture/mistune|{{Pkg|python-mistune}}}}<br />
* {{App|Python-Markdown|Extensible Python implementation of John Gruber's Markdown.|https://github.com/Python-Markdown/markdown|{{Pkg|python-markdown}}}}<br />
* {{App|PyMdown Extensions|Extensions for Python-Markdown.|https://facelessuser.github.io/pymdown-extensions/|{{AUR|pymdown-extensions}}}}<br />
* {{App|[[Wikipedia:MkDocs|MkDocs]]|Project documentation with Markdown.|https://www.mkdocs.org/|{{AUR|mkdocs}}}}<br />
* {{App|[[Wikipedia:MkDocs#Themes|Material for MkDocs]]|[[Wikipedia:Material Design|Material design]] theme for MkDocs.|https://squidfunk.github.io/mkdocs-material/|{{AUR|mkdocs-material}}}}<br />
* {{App|MkDocs Material Extensions|Markdown extension resources for MkDocs Material.|https://github.com/facelessuser/mkdocs-material-extensions|{{AUR|mkdocs-material-extensions}}}}<br />
<br />
===== Ruby implementations =====<br />
<br />
* {{App|kramdown|Fast, pure Ruby Markdown superset converter, using a strict syntax definition.|https://kramdown.gettalong.org/|{{Pkg|ruby-kramdown}}}}<br />
* {{App|Maruku|Pure Ruby Markdown-superset interpreter.|https://github.com/bhollis/maruku|{{Pkg|ruby-maruku}}}}<br />
* {{App|mdless|Pure Ruby terminal-based markdown viewer/interpeter.|https://github.com/ttscoff/mdless|{{AUR|ruby-mdless}}}}<br />
<br />
===== Markdown editors =====<br />
<br />
* {{App|Abricotine|Markdown editor built for desktop. Based on the [https://electronjs.org/ Electron] platform.|https://github.com/brrd/Abricotine|{{AUR|abricotine}}}}<br />
* {{App|[[Wikipedia:Apostrophe (text editor)|Apostrophe]]|Distraction free Markdown editor made with GTK.|https://gitlab.gnome.org/World/apostrophe|{{AUR|apostrophe}}}}<br />
* {{App|CuteMarkEd|Qt-based Markdown editor with live HTML preview, math expressions, code and markdown syntax highlighting. Discontinued since 2016.|https://cloose.github.io/CuteMarkEd/|{{AUR|cutemarked-git}}}}<br />
* {{App|Formiko|reStructuredText and Markdown editor and live previewer written in Python with GTK.|https://github.com/ondratu/formiko|{{AUR|formiko}}}}<br />
* {{App|ghostwriter|Distraction-free Markdown editor.|https://ghostwriter.kde.org|{{Pkg|ghostwriter}}}}<br />
* {{App|Marker|Simple yet robust Markdown editor.|https://fabiocolacio.github.io/Marker/|{{Pkg|marker}}}}<br />
* {{App|Mark My Words|Minimal markdown editor.|https://github.com/voldyman/MarkMyWords|{{AUR|markmywords}}}}<br />
* {{App|Mark Text|Next generation markdown editor. Based on the [https://electronjs.org/ Electron] platform.|https://github.com/marktext/marktext|{{AUR|marktext}}}}<br />
* {{App|Remarkable|Fully featured Markdown editor.|https://remarkableapp.github.io/|{{AUR|remarkable}}}}<br />
* {{App|ReText|Simple text editor for Markdown and reStructuredText.|https://github.com/retext-project/retext|{{Pkg|retext}}}}<br />
* {{App|ThiefMD|Markdown and Fountain editor inspired by Ulysses.|https://thiefmd.com/|{{AUR|thiefmd}}}}<br />
* {{App|Typora|Proprietary, minimalist Markdown editor.|https://typora.io/|{{AUR|typora}}}}<br />
* {{App|[[Zettlr]]|A cross-platform markdown editor, inspired by the [[Wikipedia:Zettelkasten|Zettelkasten]] system for note-taking and personal knowledge management. Based on the [https://electronjs.org/ Electron] platform.|https://www.zettlr.com/|{{Pkg|zettlr}}}}<br />
<br />
==== reStructuredText ====<br />
<br />
See also [[Wikipedia:ReStructuredText|reStructuredText]].<br />
<br />
* {{App|Docutils|Set of tools for processing plaintext (reStructuredText) docs into formats such as HTML, XML, or LaTeX.|https://docutils.sourceforge.io/|{{Pkg|python-docutils}}}}<br />
* {{App|rstcheck|Checks syntax of reStructuredText and code blocks nested within it.|https://github.com/rstcheck/rstcheck|{{Pkg|rstcheck}}}}<br />
* {{App|[[Wikipedia:Sphinx_(documentation_generator)|Sphinx]]| A documentation generation system using reStructuredText to generate output in multiple formats (primary documentation system for the Python project).|https://www.sphinx-doc.org/|{{Pkg|python-sphinx}}}}<br />
<br />
==== Typesetting systems ====<br />
<br />
* {{App|[[Wikipedia:groff (software)|groff]]|[[GNU]] implementation of troff, a heirloom Unix document processing system and the default formatter for [[man page]]s.|https://www.gnu.org/software/groff/groff.html|{{Pkg|groff}}}}<br />
* {{App|[[Lout]]|A lightware document formatting system. Reads a high-level description of a document similar in style to LaTeX and produces a PostScript.|https://savannah.nongnu.org/projects/lout|{{pkg|lout}}}}<br />
* {{App|SILE|Modern typesetting system inspired by TeX.|https://sile-typesetter.org/|{{Pkg|sile}}}}<br />
* {{App|[[TeX]]|A high-quality typesetting system popular in academia.|https://tug.org/|{{Pkg|texlive-basic}}}}<br />
* {{App|[[Texinfo]]|Typesetting syntax for software manuals used by the [[GNU Project]].|https://www.gnu.org/software/texinfo/|{{Pkg|texinfo}}}}<br />
* {{App|Typst|A markup-based typesetting system for the sciences.|https://github.com/typst/typst|{{Pkg|typst}}}}<br />
<br />
==== TeX editors ====<br />
<br />
With [[TeX Live|TeX, LaTeX and friends]], creation of any scientific document, article, journal, etc. is made commonplace.<br />
<br />
See also [[Wikipedia:Comparison of TeX editors]] and [[Wikibooks:LaTeX/Installation#Editors]].<br />
<br />
* {{App|[[Wikipedia:AUCTeX|AUCTeX]]|Together with RefTex, AUCTeX provices an extensible environment for writing and formatting TeX files in [[Emacs]].|https://www.gnu.org/software/auctex/|{{AUR|auctex}}}}<br />
* {{App|[[gedit]] LaTeX Plugin|Add code-completion to gedit and allows for compiling LaTeX documents and managing BibTeX bibliographies.|https://wiki.gnome.org/Apps/Gedit/LaTeXPlugin|{{AUR|gedit-latex}}}}<br />
* {{App|[[Wikipedia:GNOME-LaTeX|GNOME LaTeX]]|LaTeX editor for the GNOME Desktop including support for code completion, compiling and project management.|https://wiki.gnome.org/Apps/GNOME-LaTeX|{{Pkg|gnome-latex}}}}<br />
* {{App|[[Wikipedia:Gummi (software)|Gummi]]|Lightweight TeX/LaTeX GTK-based editor. It features a continuous preview mode, integrated BibTeX support, extendable snippet interface and multi-document support.|https://github.com/alexandervdm/gummi/|{{Pkg|gummi}}}}<br />
* {{App|[[Wikipedia:Kile|Kile]]|User-friendly TeX/LaTeX editor for the KDE desktop with many features.|https://apps.kde.org/kile/|{{Pkg|kile}}}}<br />
* {{App|Ktikz|Small application helping you to create [[Wikipedia:PGF/TikZ|PGF/TikZ]] diagrams for your publications.|http://www.hackenberger.at/blog/ktikz-editor-for-the-tikz-language/|KDE: {{Pkg|ktikz}}, Qt: {{Pkg|qtikz}}}}<br />
* {{App|[[Wikipedia:LyX|LyX]]|Document processor that encourages an approach to writing based on the structure of your documents (WYSIWYM) and not simply their appearance (WYSIWYG).|https://www.lyx.org/|{{AUR|lyx}}}}<br />
* {{App|Setzer|LaTeX editor written in Python with GTK.|https://www.cvfosammmm.org/setzer/|{{AUR|setzer}}}}<br />
* {{App|[[Wikipedia:GNU TeXmacs|TeXmacs]]|WYSIWYW (what you see is what you want) editing platform with special features for scientists.|https://www.texmacs.org/|{{AUR|texmacs}}}}<br />
* {{App|[[Wikipedia:Texmaker|Texmaker]]|Cross-platform, light and easy-to-use LaTeX IDE. It integrates many tools needed to develop documents with LaTeX, in just one application|https://www.xm1math.net/texmaker/|{{Pkg|texmaker}}}}<br />
* {{App|[[TeXstudio]]|Fork of TeXMaker including support for code completion of bibtex items, grammar check and automatic detection of the need for multiple LaTeX runs.|https://texstudio.sourceforge.net/|{{Pkg|texstudio}}}}<br />
* {{App|[[Wikipedia:TeXworks|TeXworks]]|Simple TeX front-end program modeled after TeXShop.|https://tug.org/texworks/|{{Pkg|texworks}}}}<br />
* {{App|TikZiT|Graphical tool for rapidly creating graphs and diagrams using [[Wikipedia:PGF/TikZ|PGF/TikZ]].|https://tikzit.github.io/|{{AUR|tikzit}}}}<br />
* {{App|[[Vim|Vim-LaTeX-suite]]|Customizable LaTeX environment for Vim.|https://vim-latex.sourceforge.net/|{{Pkg|vim-latexsuite}}}}<br />
<br />
==== TeX formula editors ====<br />
<br />
* {{App|EqualX|LaTeX equation editor with real time preview.|http://equalx.sourceforge.net/|{{AUR|equalx}}}}<br />
* {{App|KLatexFormula|GUI for generating images from LaTeX equations.|https://klatexformula.sourceforge.io/|{{AUR|klatexformula}}}}<br />
* {{App|[[LibreOffice]] TexMaths extension|LaTeX equation editor for LibreOffice.|http://roland65.free.fr/texmaths/|{{Pkg|libreoffice-extension-texmaths}}}}<br />
<br />
==== XML editors ====<br />
<br />
See also [[Wikipedia:Comparison of XML editors]].<br />
<br />
* {{App|QXmlEdit|Simple Qt XML editor and XSD viewer.|https://qxmledit.org/|{{Pkg|qxmledit}}}}<br />
* {{App|XML Copy Editor|Fast, validating XML editor.|https://xml-copy-editor.sourceforge.io/|{{AUR|xmlcopyeditor}}}}<br />
* {{App|XML Tree Editor|Displays XML files as tree views and allows basic operations: adding, editing and deleting text nodes and their attributes.|https://sourceforge.net/projects/xmltreeeditor/|{{AUR|xmltreeedit-bin}}}}<br />
<br />
=== Document converters ===<br />
<br />
See also [[#Markup languages]] and [[PDF, PS and DjVu]].<br />
<br />
* {{App|[[Wikipedia:Antiword|Antiword]]|MS Word to text converter.|http://www.winfield.demon.nl/{{Dead link|2023|04|25|status=404}}|{{Pkg|antiword}}}}<br />
* {{App|catdoc|Converter for Microsoft Word, Excel, PowerPoint and RTF files to text.|https://wagner.pp.ru/~vitus/software/catdoc/|{{Pkg|catdoc}}}}<br />
* {{App|docx2txt|MS Word Docx to text converter.|http://docx2txt.sourceforge.net/|{{Pkg|docx2txt}}}}<br />
* {{App|HTMLDOC|Reads HTML and Markdown source files or web pages and generates corresponding EPUB, HTML, PostScript, or PDF files with an optional table of contents.|https://www.msweet.org/htmldoc/|{{Pkg|htmldoc}}}}<br />
* {{App|[[MuPDF|mutool]]|All purpose tool based on MuPDF for dealing with document files in various manners.|https://mupdf.com/|{{Pkg|mupdf-tools}}}}<br />
* {{App|[[Wikipedia:Pandoc|Pandoc]]|Swiss-army knife for converting markup and document formats.|https://pandoc.org/|{{Pkg|pandoc-cli}}}}<br />
* {{App|unoconv|Libreoffice-based document converter.|http://dag.wiee.rs/home-made/unoconv/|{{Pkg|unoconv}}}}<br />
* {{App|UnRTF|Command-line program which converts RTF documents to other formats.|https://www.gnu.org/software/unrtf/unrtf.html|{{Pkg|unrtf}}}}<br />
<br />
=== Bibliographic reference managers ===<br />
<br />
See also [[Wikipedia:Comparison of reference management software]].<br />
<br />
* {{App|[[Wikipedia:Bibus|Bibus]]|A bibliographic database that can directly insert references in OpenOffice.org/LibreOffice and generate the bibliographic index.|https://sourceforge.net/projects/bibus-biblio/|{{AUR|bibus}}{{Broken package link|package not found}}}}<br />
* {{App|DocEar|Docear is an academic literature suite for searching, organizing and creating academic literature, built upon the mind mapping software Freeplane and the reference manager JabRef.|https://www.docear.org/|{{AUR|docear}}}}<br />
* {{App|[[Wikipedia:JabRef|JabRef]]|Java GUI frontend for managing BibTeX and other bibliographies.|https://www.jabref.org/|{{AUR|jabref}}}}<br />
* {{App|[[Wikipedia:KBibTeX|KBibTeX]]|BibTeX editor by KDE to edit bibliographies used with LaTeX.|https://apps.kde.org/kbibtex/|{{Pkg|kbibtex}}}}<br />
* {{App|[[Wikipedia:Mendeley|Mendeley Desktop]]|Proprietary reference manager and academic social network.|https://www.mendeley.com/|{{AUR|mendeleydesktop}}}}<br />
* {{App|Papis|A command-line based document and bibliography manager.|https://github.com/papis/papis|{{AUR|papis}}}}<br />
* {{App|[[Wikipedia:Pybliographer|Pybliographer]]|Tool for managing bibliographic databases.|https://pybliographer.org/|{{AUR|pybliographer}}}}<br />
* {{App|[[Wikipedia:Referencer|Referencer]]|GNOME application to organize documents or references, and ultimately generate a BibTeX bibliography file.|https://launchpad.net/referencer/|{{AUR|referencer}}}}<br />
* {{App|[[Wikipedia:Zotero|Zotero]]|An easy-to-use tool to help you collect, organize, cite, and share your research sources. Can import and export BibTeX and has browser extensions.|https://www.zotero.org/|{{AUR|zotero}}}}<br />
<br />
=== Readers and viewers ===<br />
<br />
* {{App|NFO Viewer|Simple viewer for NFO files.|https://otsaloma.io/nfoview/|{{Pkg|nfoview}}}}<br />
<br />
==== PDF and DjVu ====<br />
<br />
See [[PDF, PS and DjVu]].<br />
<br />
==== E-book ====<br />
<br />
* {{App|Bookworm|Simple, focused e-book reader for Elementary OS with EPUB, PDF, Mobipocket and Comicbook support.|https://babluboy.github.io/bookworm/|{{Pkg|bookworm}}}}<br />
* {{App|[[Wikipedia:Calibre (software)|Calibre]]|E-book library management application that can also edit EPUB files, convert between different formats and sync with a variety of e-book readers. Supported formats include CHM, Comicbook, DjVu, DOCX, EPUB, FictionBook, HTML, HTMLZ, Kindle, LIT, LRF, Mobipocket, ODT, PDF, PRC, PDB, PML, RB, RTF, SNB, TCR, TXT and TXTZ.|https://calibre-ebook.com/|{{Pkg|calibre}}}}<br />
* {{App|Cool Reader|E-book viewer with many supported formats such as EPUB (non-DRM), FictionBook, TXT, RTF, HTML, CHM and TCR.|https://sourceforge.net/projects/crengine/|{{Pkg|coolreader}}}}<br />
* {{App|[[Wikipedia:FBReader|FBReader]]|E-book viewer with many supported formats such as EPUB, FictionBook, HTML, plucker, PalmDoc, zTxt, TCR, CHM, RTF, OEB, Mobipocket (non-DRM) and TXT.|https://fbreader.org/|{{Pkg|fbreader}}}}<br />
* {{App|Foliate|Simple and modern GTK eBook reader. Supports EPUB, Mobipocket, Kindle, FictionBook, and Comicbook formats.|https://johnfactotum.github.io/foliate/|{{Pkg|foliate}}}}<br />
* {{App|GNOME Books|E-book manager application for GNOME with EPUB, Mobipocket, FictionBook, DjVu and Comicbook support.|https://wiki.gnome.org/Apps/Books|{{AUR|gnome-books-git}}}}<br />
* {{App|Lector|Qt based e-book reader with PDF, EPUB, Kindle, Mobipocket and Comicbook support.|https://github.com/BasioMeusPuga/Lector|{{AUR|lector}}}}<br />
* {{App|[[Wikipedia:Sigil (application)|Sigil]]|WYSIWYG EPUB e-book editor.|https://sigil-ebook.com/|{{pkg|sigil}}}}<br />
<br />
Some [[PDF, PS and DjVu#Viewers|PDF viewers]] like apvlv, Atril, [[MuPDF]], [[Wikipedia:Okular|Okular]] and Xreader also support the EPUB format.<br />
<br />
==== Comic book ====<br />
<br />
* {{App|Automedia|A very small downloader for manga and anime from various websites. Designed to be a much more lightweight alternative to HakuNeko. Written primarly in C.|https://git.dec05eba.com/AutoMedia/about/|{{AUR|automedia-git}}}}<br />
* {{App|HakuNeko|Downloader for manga and anime from various websites. Based on the [https://electronjs.org/ Electron] platform.|https://github.com/manga-download/hakuneko|{{AUR|hakuneko-desktop-bin}}}}<br />
* {{App|Kindle Comic Converter|Allows you to transform your PNG, JPG, GIF, CBZ, CBR and CB7 files into EPUB or MOBI format e-books.|https://github.com/ciromattia/kcc/|{{AUR|kcc}}}}<br />
* {{App|Komikku|Online/offline manga reader for GNOME.|https://gitlab.com/valos/Komikku|{{AUR|komikku}}}}<br />
* {{App|Manga Reader|Manga reader for local files. Supports zip, rar, tar, 7z, cbz, cbr, cbt, cb7 files and also folders.|https://github.com/g-fb/mangareader|{{AUR|mangareader}}}}<br />
* {{App|MComix|GTK3 image viewer specifically designed to handle comic book archives (fork of Comix). Also includes library manager.|https://github.com/multiSnow/mcomix3|{{AUR|mcomix}}}}<br />
* {{App|Peruse|Comic book reader by KDE.|https://peruse.kde.org/|{{AUR|peruse}}}}<br />
* {{App|QComicBook| Viewer for comic book archives that aims at convenience and simplicity.|https://github.com/stolowski/QComicBook|{{AUR|qcomicbook}}}}<br />
* {{App|QuickMedia|Online manga reader. Supports automatically upscaling pages with {{Pkg|waifu2x-ncnn-vulkan}}|https://git.dec05eba.com/QuickMedia/about/|{{AUR|quickmedia-git}}}}<br />
* {{App|YACReader|Comic book viewer written in C++ and Qt5. Comes with YACReaderLibrary for managing comics.|https://yacreader.com/|{{AUR|yacreader}}}}<br />
<br />
Some [[PDF, PS and DjVu#Viewers|PDF]] and E-book viewers like Atril, Bookworm, [[Wikipedia:Calibre (software)|Calibre]], [[Wikipedia:Evince|Evince]], Foliate, Lector, [[MuPDF]], [[Wikipedia:Okular|Okular]], Xreader and [[Zathura]] also support the Comicbook format.<br />
<br />
==== CHM ====<br />
<br />
See also [[Wikipedia:Microsoft Compiled HTML Help]].<br />
<br />
* {{App|Archmage|Extensible reader and decompiler for files in the CHM format.|https://github.com/dottedmag/archmage|{{AUR|archmage}}}}<br />
* {{App|Kchmviewer|Qt-based CHM viewer that uses chmlib and borrows some ideas from xchm. It does not depend on [[KDE]], but it can be compiled to integrate with it.|http://www.ulduzsoft.com/linux/kchmviewer/|{{Pkg|kchmviewer}}}}<br />
* {{App|[[Wikipedia:xCHM|xCHM]]|Lightweight CHM viewer, based on chmlib.|https://github.com/rzvncj/xCHM|{{Pkg|xchm}}}}<br />
<br />
Some [[PDF, PS and DjVu#Viewers|PDF]] and E-book viewers like Cool Reader, [[Wikipedia:FBReader|FBReader]] and [[Wikipedia:Okular|Okular]] also support the CHM format.<br />
<br />
=== Document managers ===<br />
<br />
* {{App|Paperwork|Personal document manager. It manages scanned documents and PDFs.|https://openpaper.work/|{{Pkg|paperwork}}}}<br />
* {{App|Shelf|Document and EBook collection manager that supports PDF and EPUB files.|https://mauikit.org/apps/shelf/|{{Pkg|maui-shelf}}}}<br />
<br />
=== Scanning software ===<br />
<br />
See [[SANE#Frontends]]<br />
<br />
* {{App|ScanTailor Advanced|Interactive post-processing tool for scanned pages. Fork of Scan Tailor with additional features and fixes.|https://github.com/ScanTailor-Advanced/scantailor-advanced|{{Pkg|scantailor-advanced}}}}<br />
<br />
=== OCR software ===<br />
<br />
==== Console ====<br />
<br />
See also [[Wikipedia:Comparison of optical character recognition software]].<br />
<br />
* {{App|[[Wikipedia:CuneiForm (software)|CuneiForm]]|Command line OCR system originally developed and open sourced by Cognitive technologies. Supported languages: eng, ger, fra, rus, swe, spa, ita, ruseng, ukr, srp, hrv, pol, dan, por, dut, cze, rum, hun, bul, slo, lav, lit, est, tur.|https://launchpad.net/cuneiform-linux|{{Pkg|cuneiform}}}}<br />
* {{App|[[Wikipedia:GOCR|GOCR]]|OCR engine which also supports barcode recognition.|https://www-e.uni-magdeburg.de/jschulen/ocr/|{{Pkg|gocr}}}}<br />
* {{App|[[Wikipedia:Ocrad|Ocrad]]|OCR program based on a feature extraction method.|https://www.gnu.org/software/ocrad/|{{Pkg|ocrad}}}}<br />
* {{App|OCRmyPDF|Adds an OCR text layer to scanned PDF files, allowing them to be searched.|https://github.com/jbarlow83/OCRmyPDF|{{AUR|ocrmypdf}}}}<br />
* {{App|[[Wikipedia:OCRopus|OCRopus]]|OCR ''platform'', modules exist for document layout analysis, OCR engines (it can use Tesseract or its own engine), natural language modeling, etc.|https://github.com/tmbdev/ocropy|{{AUR|ocropy-git}}}}<br />
* {{App|[[Wikipedia:Tesseract (software)|Tesseract]]|Accurate open source OCR engine. Package splitted, you need install some datafiles for each language ({{Pkg|tesseract-data-eng}} for example).|https://github.com/tesseract-ocr|{{Pkg|tesseract}}}}<br />
<br />
==== Graphical ====<br />
<br />
* {{App|gImageReader|Graphical GTK/Qt frontend to Tesseract.|https://github.com/manisandro/gImageReader|GTK: {{Pkg|gimagereader-gtk}}, Qt: {{Pkg|gimagereader-qt}}}}<br />
* {{App|[[Wikipedia:Scanner Access Now Easy#gscan2pdf|gscan2pdf]]|Scans, runs an OCR engine, minor post-processing, creates a document.|https://gscan2pdf.sourceforge.net/|{{Pkg|gscan2pdf}}}}<br />
* {{App|Linux-Intelligent-Ocr-Solution|Easy-OCR solution and Tesseract trainer for converting print into text using either scanner or a camera.|https://sourceforge.net/projects/lios/|{{AUR|lios-git}}}}<br />
* {{App|[[Wikipedia:OCRFeeder|OCRFeeder]]|Python GUI for Gnome which performs document analysis and rendition, and can use either CuneiForm, GOCR, Ocrad or Tesseract as OCR engines. It can import from PDF or image files, and export to HTML or OpenDocument.|https://wiki.gnome.org/Apps/OCRFeeder|{{Pkg|ocrfeeder}}}}<br />
* {{App|Paperwork|Personal document manager. It manages scanned documents and PDFs.|https://openpaper.work/|{{Pkg|paperwork}}}}<br />
* {{App|Scans to PDF|Create small, searchable PDFs from scanned documents.|https://github.com/Unrud/djpdf|{{AUR|djpdf}}}}<br />
* {{App|YAGF|Graphical interface for the CuneiForm text recognition program on the Linux platform.|https://sourceforge.net/projects/yagf-ocr/|{{AUR|yagf}}}}<br />
<br />
=== Notes ===<br />
<br />
==== Note-taking software ====<br />
<br />
See also [[Wikipedia:Comparison of notetaking software]].<br />
<br />
===== Console =====<br />
<br />
* {{App|dnote|A simple command line notebook for programmers|https://github.com/dnote/dnote|{{AUR|dnote-cli-bin}}}}<br />
* {{App|[[Wikipedia:org-mode|Org mode]]|[[Emacs]] mode for notes, project planning and authoring.|https://orgmode.org/|{{AUR|emacs-org-mode}}}}<br />
* {{App|[[eureka]]|CLI tool to input and store your ideas without leaving the terminal|https://github.com/simeg/eureka|{{AUR|eureka-notes}}}}<br />
* {{App|hierarchical notebook|Program to organize many kinds of data (addresses, to-do lists, ideas, book reviews, etc.) in one place using the XML format.|http://hnb.sourceforge.net/|{{AUR|hnb}}}}<br />
* {{App|kb|A minimalist terminal-based knowledge manager.|https://github.com/gnebbia/kb|{{AUR|kb}}}}<br />
* {{App|nb|A command line and local web note‑taking, bookmarking, archiving, and knowledge base application.|https://xwmx.github.io/nb/|{{AUR|nb}}}}<br />
* {{App|tnote|Small note taking program for the terminal.|https://sourceforge.net/projects/tnote/|{{AUR|tnote}}}}<br />
* {{App|Vimwiki|Personal wiki for [[Vim]] – interlinked, plain text files written in a markup language.|https://vimwiki.github.io/|{{AUR|vim-vimwiki}}}}<br />
<br />
===== Graphical =====<br />
<br />
* {{App|[[Wikipedia:BasKet Note Pads|BasKet]]|Application for organizing, sharing, and taking notes. It can manage various types of information such as to-do lists, links, pictures, and other types, similar to a scrapbook.|https://basket-notepads.github.io/|{{AUR|basket}}}}<br />
* {{App|Boostnote|Note-taking application for programmers that focuses on markdown, snippets, and customizability. Based on the [https://electronjs.org/ Electron] platform.|https://boostnote.io/|{{AUR|boost-note-bin}}}}<br />
* {{App|Buho|Task and note keeper to save links, write quick notes and organize pages as books.|https://mauikit.org/apps/buho/|{{Pkg|buho}}}}<br />
* {{App|Cherrytree|Hierarchical note taking application, featuring rich text and syntax highlighting, storing data in a single xml or sqlite file.|https://www.giuspen.com/cherrytree/|{{Pkg|cherrytree}}}}<br />
* {{App|Deepin Voice Notes|Lightweight memo tool to make text notes and voice recordings.|https://github.com/linuxdeepin/deepin-voice-note|{{Pkg|deepin-voice-note}}}}<br />
* {{App|Encryptic|JavaScript note taking application with Markdown editor and encryption support. Based on the [https://electronjs.org/ Electron] platform.|https://www.encryptic.org/|{{AUR|encryptic}}}}<br />
* {{App|FeatherNotes|Lightweight Qt hierarchical notes-manager.|https://github.com/tsujan/feathernotes|{{Pkg|feathernotes}}}}<br />
* {{App|FromScratch|Simple but smart note-taking application that you can use as a quick note taking or todo app. Based on the [https://electronjs.org/ Electron] platform.|https://fromscratch.rocks/|{{AUR|fromscratch-bin}}}}<br />
* {{App|GNOME Notes|Note editor for GNOME designed to remain simple to use. Part of {{Grp|gnome-extra}}.|https://wiki.gnome.org/Apps/Notes|{{Pkg|gnome-notes}}}}<br />
* {{App|[[Wikipedia:Gnote|Gnote]]|Port of Tomboy to C++. It is the same note taking application, including most of the add-ins.|https://wiki.gnome.org/Apps/Gnote|{{Pkg|gnote}}}}<br />
* {{App|Joplin|Note taking and to-do application, which can handle a large number of notes organized into notebooks on desktop or mobile devices. It synchronizes with WebDAV, Dropbox, OneDrive, NextCloud, S3 (beta) and other backends. Based on the [https://electronjs.org/ Electron] platform.|https://joplinapp.org/|CLI app: {{AUR|joplin}}, desktop app: {{AUR|joplin-desktop}}}}<br />
* {{App|KeepNote|Cross-platform GTK note-taking application with rich text formatting.|http://keepnote.org|{{AUR|keepnote}}}}<br />
* {{App|KJots|Note taking application for KDE.|https://userbase.kde.org/KJots|{{Pkg|kjots}}}}<br />
* {{App|Logseq|A local-first, non-linear, outliner notebook for organizing and sharing your personal knowledge base.|https://logseq.com/|{{AUR|logseq-desktop}}}}<br />
* {{App|Mikidown|Note taking application featuring markdown syntax.|https://shadowkyogre.github.io/mikidown/|{{AUR|mikidown}}}}<br />
* {{App|[[Wikipedia:MyNotex|MyNotex]]|Note-taking, document file and activity manager.|https://sites.google.com/site/mynotex/|{{AUR|mynotex}}}}<br />
* {{App|[[Nextcloud]] Notes|Simple notes app for Nextcloud.|https://github.com/nextcloud/notes|{{Pkg|nextcloud-app-notes}}}}<br />
* {{App|NixNote|Helps you take notes and stay organized. Create text notes, attach files or images, and even synchronize with Evernote. Formerly called Nevernote.|http://nixnote.org/|{{aur|nixnote2}}}}<br />
* {{App|Norka|Note-taking software with Markdown support designed for Pantheon.|https://tenderowl.com/work/norka/|{{AUR|norka}}}}<br />
* {{App|Notejot|Stupidly simple sticky notes applet for elementaryOS.|https://github.com/lainsce/notejot|{{AUR|notejot}}}}<br />
* {{App|Notes|Note-taking application, write down your thoughts.|https://www.get-notes.com/|{{AUR|notes}}}}<br />
* {{App|Notes-Up|Markdown notes editor and manager for elementaryOS.|https://github.com/Philip-Scott/Notes-up|{{Pkg|notes-up}}}}<br />
* {{App|Notion|Note-taking, task management, project management, knowledge management software|https://www.notion.so|{{AUR|notion-app}}}}<br />
* {{App|Notorious|Keyboard centric note-taking application with Markdown syntax highlighting support.|https://notorious.gabmus.org/|{{AUR|notorious-git}}}}<br />
* {{App|nvPY|Simplenote syncing note-taking application, inspired by Notational Velocity and ResophNotes, but uglier and cross-platformerer.|https://github.com/cpbotha/nvpy|{{AUR|nvpy}}}}<br />
* {{App|Obsidian|Personal knowledge base that uses markdown text files to organize notes in a format that mirrors the human brain.|https://obsidian.md/|{{Pkg|obsidian}}}}<br />
* {{App|OutWiker|Store notes in a tree.|https://jenyay.net/Outwiker/English|{{AUR|outwiker}}}}<br />
* {{App|[[Wikipedia:QOwnNotes|QOwnNotes]]|Notepad and todo list manager with markdown support and optional ownCloud integration built on Qt5.|https://www.qownnotes.org/|{{AUR|qownnotes}}}}<br />
* {{App|[[Wikipedia:Simplenote|Simplenote]]|The simplest way to keep notes. Based on the [https://electronjs.org/ Electron] platform.|https://simplenote.com/|{{AUR|simplenote-electron-bin}}}}<br />
* {{App|Standard Notes|Simple and private notes application which focuses on simplicity, and encrypts data locally before it ever touches a cloud. Based on the [https://electronjs.org/ Electron] platform.|https://standardnotes.com/|{{AUR|standardnotes-desktop}}}}<br />
* {{App|[[Wikipedia:TagSpaces|TagSpaces]]|Offline personal data manager for managing of your local files. Based on the [https://electronjs.org/ Electron] platform.|https://www.tagspaces.org/|{{AUR|tagspaces}}}}<br />
* {{App|[[Wikipedia:TiddlyWiki|TiddlyWiki]]|Unique non-linear notebook for capturing, organizing and sharing complex information.|https://tiddlywiki.com/|{{AUR|tiddlywiki}}}}<br />
* {{App|[[Wikipedia:Tomboy (software)|Tomboy]]|Desktop note-taking application for Linux and Unix with a wiki-like linking system to connect notes together.|https://wiki.gnome.org/Apps/Tomboy|{{AUR|tomboy}}{{Broken package link|package not found}}}}<br />
* {{App|Trilium|Build your personal knowledge base with Trilium Notes.|https://github.com/zadam/trilium|{{AUR|trilium}}, {{AUR|trilium-server}}}}<br />
* {{App|TuxCards|Hierarchical notebook to enter and manage ever every kind of notes and ideas in a structured manner.|https://tuxcards.de/|{{Pkg|tuxcards}}}}<br />
* {{App|VNote|Vim-inspired note-taking application that knows programmers and Markdown better.|https://vnotex.github.io/vnote|{{AUR|vnote}}}}<br />
* {{App|WikidPad|Wiki-like notebook for storing your thoughts, ideas, todo lists, contacts, or anything else you can think of to write down.|https://wikidpad.sourceforge.net/|{{AUR|wikidpad}}}}<br />
* {{App|WizNote|Cloud based note-taking client.|https://github.com/WizTeam/WizQTClient|{{Pkg|wiznote}}}}<br />
* {{App|[[Zim]]|WYSIWYG text editor that aims at bringing the concept of a wiki to the desktop.|https://zim-wiki.org/|{{Pkg|zim}}}}<br />
* {{App|zNotes|Lightweight application for notes management with simple interface.|https://sourceforge.net/projects/znotes/|{{AUR|znotes}}}}<br />
* {{App|μPad|Note-taking app that helps you organise + take notes without restrictions. Based on the [https://electronjs.org/ Electron] platform.|https://getmicropad.com|{{AUR|micropad}}}}<br />
<br />
==== Stylus note-taking ====<br />
<br />
* {{App|Cournal|Collaborative note taking and journal application using a stylus. It allows multiple users to annotate PDF files in real-time.|https://github.com/flyser/cournal|{{AUR|cournal}}}}<br />
* {{App|[[Saber]]|Open source libre cross platform note taking app|https://github.com/adil192/saber|{{AUR|saber}}}}<br />
* {{App|Write|A proprietary word processor for handwriting.|http://www.styluslabs.com/|{{AUR|write_stylus}}}}<br />
* {{App|Xournal|Application for notetaking, sketching and keeping a journal using a stylus. Capable of annotating existing PDF files as well.|https://xournal.sourceforge.net/|{{AUR|xournal}}}}<br />
* {{App|[[Xournal++]]|Notetaking software designed around a tablet. C++ rewrite of Xournal with PDF annotation support.|https://github.com/xournalpp/xournalpp|{{Pkg|xournalpp}}}}<br />
* {{App|Rnote|A simple note taking application written in Rust and GTK4.|https://github.com/flxzt/rnote|{{Pkg|rnote}}}}<br />
<br />
==== Diary ====<br />
<br />
* {{App|Almanah|Small GTK application to allow you to keep a diary of your life.|https://wiki.gnome.org/Apps/Almanah_Diary|{{Pkg|almanah}}}}<br />
* {{App|Hazama|Simple and highly customizable application for keeping diary. There is no calendar but a big list that contains preview of diaries.|https://hazama.cc/|{{AUR|hazama}}}}<br />
* {{App|Lifeograph|Off-line and private journal and note taking application. It offers a rich feature set presented in a clean and simple user interface.|https://lifeograph.sourceforge.net/|{{Pkg|lifeograph}}}}<br />
* {{App|RedNotebook|Modern journal, which lets you format, tag and search your entries.|https://rednotebook.sourceforge.io/|{{Pkg|rednotebook}}}}<br />
* {{App|Simple Diary|Simple and lightweight diary app with Markdown support.|https://github.com/johan-bjareholt/simple-diary-gtk|{{AUR|simple-diary-gtk}}}}<br />
<br />
==== Mind-mapping ====<br />
<br />
See also [[Wikipedia:List of concept- and mind-mapping software]].<br />
<br />
* {{App|[[Wikipedia:FreeMind|FreeMind]]|Mind-mapping software written in Java.|https://freemind.sourceforge.net|{{AUR|freemind}}}}<br />
* {{App|[[Wikipedia:Freeplane|Freeplane]]|Fork of FreeMind, supports thinking, sharing information and getting things done at work. The software can be used for mind mapping and analyzing the information contained in mind maps.|https://www.freeplane.org/|{{Pkg|freeplane}}}}<br />
* {{App|Minder|Mind-mapping application designed for Pantheon.|https://github.com/phase1geo/Minder|{{Pkg|minder}}}}<br />
* {{App|MindMaster|Proprietary mindmap and brainstorm software with modern UI and beautiful template. It also provides online mindmap service and cross-platform sharing.|https://www.edrawsoft.com/mindmaster/|{{AUR|mindmaster_en}}{{Broken package link|package not found}}}}<br />
* {{App|Semantik|Mind-mapping application for KDE.|https://waf.io/semantik.html|{{AUR|semantik}}}}<br />
* {{App|TreeSheets|A "hierarchical spreadsheet" that is a great replacement for spreadsheets, mind mappers, outliners, PIMs, text editors and small databases.|https://strlen.com/treesheets/|{{AUR|treesheets-git}}}}<br />
* {{App|View Your Mind|Tool to generate and manipulate maps which show your thoughts. Such maps can help you to improve your creativity and effectivity. You can use them for time management, to organize tasks, to get an overview over complex contexts, to sort your ideas etc.|https://sourceforge.net/projects/vym/|{{Pkg|vym}}}}<br />
* {{App|[[Wikipedia:Visual Understanding Environment|Visual Understanding Environment]]|Flexible tools for managing and integrating digital resources in support of teaching, learning and research.|https://vue.tufts.edu/ |{{AUR|vue}}}}<br />
* {{App|[[Wikipedia:XMind|XMind]]|Brainstorming and mind mapping application. It provides a rich set of different visualization styles, and allows sharing of created mind maps via their website.|https://www.xmind.net/|{{AUR|xmind}}}}<br />
<br />
==== Sticky notes ====<br />
<br />
* {{App|GloboNote|Easy to use desktop note taking application. You can use it to create sticky notes, to-do lists, personal journals, reminders and other notes all in one application.|https://globonote.info/|{{AUR|globonote}}}}<br />
* {{App|KNotes|Program that lets you write the computer equivalent of sticky notes. Part of {{Grp|kde-pim}}.|https://kontact.kde.org/components/knotes.html{{Dead link|2022|09|20|status=404}}|{{Pkg|knotes}}}}<br />
* {{App|MyNotes|Sticky note application. An icon appears in the system tray and from it you can create and manage your sticky notes.|https://github.com/j4321/MyNotes|{{AUR|mynotes}}}}<br />
* {{App|Notes|Provides you a quick way to paste text, to write down a list of things, to leave a note to your friend, or whatever you had do with Post-It's.|https://goodies.xfce.org/projects/panel-plugins/xfce4-notes-plugin|{{Pkg|xfce4-notes-plugin}}}}<br />
* {{App|PrimeNote|Most polished, cross-platform sticky note application (PyQt5). Provides support for Cloud, Vim, CSS styling and more !|https://gitlab.com/william.belanger/primenote|{{AUR|primenote-git}}}}<br />
* {{App|xNots|Desktop post-it/sticky note system for the Unix geek.|https://github.com/thePalindrome/xnots|{{AUR|xnots-git}}}}<br />
* {{App|Xpad|Sticky note application for jotting down things to remember.|https://launchpad.net/xpad|{{Pkg|xpad}}}}<br />
<br />
=== Special writing environments ===<br />
<br />
==== Distraction-free writing ====<br />
<br />
See also [[#Markdown editors]] and [[Wikipedia:Full-screen writing program]].<br />
<br />
* {{App|FocusWriter|Simple, distraction-free writing environment. It utilizes a hide-away interface that you access by moving your mouse to the edges of the screen, allowing the program to have a familiar look and feel to it while still getting out of the way so that you can immerse yourself in your work.|https://gottcode.org/focuswriter/|{{Pkg|focuswriter}}}}<br />
* {{App|[[Wikipedia:PyRoom|PyRoom]]|Fullscreen editor without buttons, widgets, formatting options, menus and with only the minimum of required dialog windows, it does not have any distractions and lets you focus on writing and only writing.|https://pyroom.org/|{{AUR|pyroom}}}}<br />
* {{App|Quilter|Focus on your writing and write beautiful solid stories with the Focus Mode in tow in this Markdown editor.|https://github.com/lainsce/quilter|{{AUR|quilter}}}}<br />
* {{App|TextRoom|Fullscreen text editor for writers.|https://github.com/dbuksbaum/TextRoom|{{AUR|textroom}}}}<br />
<br />
==== Story writing ====<br />
<br />
* {{App|Manuskript|Provides a rich environment to help writers create their first draft and then further refine and edit their masterpiece.|http://www.theologeek.ch/manuskript/|{{Pkg|manuskript}}}}<br />
* {{App|NovProg|Tool to graph your progress in writing a NaNoWriMo style novel.|https://gottcode.org/novprog/|{{AUR|novprog}}}}<br />
* {{App|oStorybook|Tool for writers, essayists, authors from the draft to the final work.|https://ostorybook.tuxfamily.org/?lng&#61;en|{{AUR|ostorybook}}}}<br />
<br />
==== Screenwriting ====<br />
<br />
* {{App|KIT Scenarist|Simple and powerful application for creating screenplays.|https://kitscenarist.ru/en/|{{Pkg|scenarist}}}}<br />
* {{App|Magic Fountain|Fountain syntax editor and viewer for writing screenplays.|https://aztorius.github.io/magicfountain/|{{AUR|magicfountain}}}}<br />
* {{App|[[Wikipedia:Trelby|Trelby]]|Simple, fast and elegantly laid out to make screenwriting simple.|https://www.trelby.org/|{{AUR|trelby-git}}}}<br />
* {{App|Fade In|Fade In Professional Screenwriting Software is the most advanced software used by professionals writing for motion pictures, television, video games, the stage, radio, and more.|https://www.fadeinpro.com/|{{AUR|fadein}}}}<br />
<br />
=== Language ===<br />
<br />
==== Dictionary and thesaurus ====<br />
<br />
See also [[Wikipedia:Category:Dictionary software]] and [[Wikipedia:DICT#DICT clients]].<br />
<br />
===== Console =====<br />
<br />
* {{App|[[dictd]]|Client/server software for the DICT protocol.|https://sourceforge.net/projects/dict/|{{Pkg|dictd}}}}<br />
* {{App|[[sdcv]]|Command line dictionary. It provides access to dictionaries in StarDict's format.|https://dushistov.github.io/sdcv/|{{Pkg|sdcv}}}}<br />
* {{App|thesauromatic|Static, offline, command-line thesaurus written in Rust.|https://github.com/cjrh/thesauromatic|{{AUR|thesauromatic-git}}}}<br />
<br />
===== Graphical =====<br />
<br />
* {{App|Artha|English thesaurus that works completely off-line and is based on WordNet.|https://artha.sourceforge.net/|{{AUR|artha}}}}<br />
* {{App|Gjiten Kai|Rewrite of Gjiten, a GTK Japanese dictionary.|https://github.com/odrevet/gjiten-kai|{{AUR|gjitenkai-git}}}}<br />
* {{App|GNOME Dictionary|GNOME application to check word definitions and spellings in an online dictionary. Part of {{Grp|gnome-extra}}.|https://wiki.gnome.org/Apps/Dictionary|{{Pkg|gnome-dictionary}}}}<br />
* {{App|[[GoldenDict]]|Feature-rich dictionary lookup program.|http://www.goldendict.org/|{{AUR|goldendict-ng-git}}}}<br />
* {{App|Kiten|Japanese reference and study tool. Part of {{Grp|kde-education}}.|https://apps.kde.org/kiten/|{{Pkg|kiten}}}}<br />
* {{App|MATE Dictionary|MATE application to look up words in dictionary sources.|https://github.com/mate-desktop/mate-utils|{{Pkg|mate-utils}}}}<br />
* {{App|OpenDict|Computer dictionary, which supports popular computer dictionary formats including Slowo and Mova. It also acts as a client for DICT servers.|http://opendict.sourceforge.net/|{{AUR|opendict}}}}<br />
* {{App|Palaura|Handy dictionary to find any word's definition.|https://github.com/lainsce/palaura|{{AUR|palaura}}}}<br />
* {{App|PowerWord|Proprietary Chinese-English dictionary tool.|https://www.iciba.com|{{AUR|powerword-bin}}}}<br />
* {{App|QStarDict|Dictionary program written using Qt. The user interface is similar to StarDict.|http://qstardict.ylsoftware.com/|{{Pkg|qstardict}}}}<br />
* {{App|Quick Lookup|Simple GTK dictionary application powered by Wiktionary.|https://github.com/johnfactotum/quick-lookup|{{AUR|quick-lookup}}}}<br />
* {{App|StarDict|International dictionary software.|https://stardict-4.sourceforge.net/|{{Pkg|stardict}}}}<br />
* {{App|Xfce4 Dictionary|Search different kinds of dictionary services for words or phrases.|https://goodies.xfce.org/projects/applications/xfce4-dict|{{Pkg|xfce4-dict}}}}<br />
<br />
==== Spell checkers ====<br />
<br />
See [[Language checking]].<br />
<br />
==== Translation and localization ====<br />
<br />
See also [[Wikipedia:Comparison of computer-assisted translation tools]].<br />
* {{App|[[Wikipedia:Apertium|Apertium]]|Free and open source rule-based machine translation platform with available language data. It supports the following formats: HTML, Microsoft Office 2007 XML, OpenDocument, TMX, MediaWiki and others.|https://www.apertium.org/|{{AUR|apertium}}}}<br />
* {{App|Crow Translate|Simple and lightweight translator that allows to translate and speak text using Google, Yandex and Bing.|https://crow-translate.github.io/|{{AUR|crow-translate}}}}<br />
* {{App|Dialect|A translation app for GNOME based on Google Translate.|https://github.com/dialect-app/dialect|{{AUR|dialect}}}}<br />
* {{App|[[Wikipedia:Gtranslator|Gtranslator]]|Enhanced gettext po file editor for the GNOME. It handles all forms of gettext po files and includes very useful features.|https://wiki.gnome.org/Apps/Gtranslator|{{Pkg|gtranslator}}}}<br />
* {{App|Lokalize|Standard [[KDE]] tool for software translation. It includes basic editing of PO files, support for glossary, translation memory, project managing, etc. It belongs to {{Grp|kdesdk}}|https://apps.kde.org/lokalize/|{{Pkg|lokalize}}}}<br />
* {{App|[[Wikipedia:Moses (machine translation)|Moses]]|Statistical machine translation tool (language data not included).|http://statmt.org/moses/|{{AUR|mosesdecoder}}}}<br />
* {{App|[[Wikipedia:OmegaT|OmegaT]]|General translator's tool which contains a lot of translation memory features and can give suggestions from Google Translate. It supports the following formats: HTML, Microsoft Office 2007 XML, OpenDocument, XLIFF/Okapi, MediaWiki, plain text, TMX and others.|https://omegat.org/|{{AUR|omegat}}}}<br />
* {{App|[[Wikipedia:Poedit|Poedit]]|Simple translation editor for gettext (PO, POT) and XLIFF.|https://poedit.net|{{Pkg|poedit}}}}<br />
* {{App|Pology|Set of Python tools for dealing with gettext/po-files.|https://techbase.kde.org/Localization/Tools/Pology|{{AUR|pology-git}}}}<br />
* {{App|[[Qt]] Linguist|Translating Qt C++ and Qt Quick applications into local languages.|https://doc.qt.io/qt-5/qtlinguist-index.html|{{Pkg|qt5-tools}}}}<br />
* {{App|Translate Shell|Command-line interface and interactive shell for Google Translate.|https://www.soimort.org/translate-shell/|{{Pkg|translate-shell}}}}<br />
* {{App|[[Wikipedia:Translate Toolkit|Translate Toolkit]]|Localization and translation toolkit, which provides a set of tools for working with localization file formats and files that might need localization.|https://toolkit.translatehouse.org/|{{Pkg|translate-toolkit}}}}<br />
<br />
=== Barcode generators and readers ===<br />
<br />
==== Console ====<br />
<br />
* {{App|barcode|A tool to convert text strings to printed bars.|https://www.gnu.org/software/barcode/|{{Pkg|barcode}}}}<br />
* {{App|iec16022|Produce 2D barcodes often also referenced as DataMatrix.|https://datenfreihafen.org/projects/iec16022.html|{{Pkg|iec16022}}}}<br />
* {{App|qrencode|C library and command line tool for encoding data in a QR Code symbol.|https://fukuchi.org/works/qrencode/|{{Pkg|qrencode}}}}<br />
* {{App|[[Wikipedia:ZBar|ZBar]]|Application and library for reading bar codes from various sources.|https://zbar.sourceforge.net/|{{Pkg|zbar}}}}<br />
* {{App|Zint|Barcode encoding library and command line tool supporting over 50 symbologies.|http://zint.org.uk/|{{Pkg|zint}}}}<br />
<br />
==== Graphical ====<br />
<br />
* {{App|CoBang|QR Code scanner application.|https://github.com/hongquan/CoBang|{{AUR|cobang}}}}<br />
* {{App|gLabels|Program for creating labels and business cards. It also supports creating barcodes.|http://glabels.org/|{{Pkg|glabels}}}}<br />
* {{App|QRab|Simply grabs QR code from screen and copies decoded text into clipboard.|https://qrab.sourceforge.io/|{{AUR|qrab}}}}<br />
* {{App|Qreator|Graphical utility for creating QR codes.|https://davidplanella.org/qreator/|{{Pkg|qreator}}}}<br />
* {{App|QtQR|QR Code generator and decoder.|https://launchpad.net/qr-tools|{{Pkg|qtqr}}}}<br />
* {{App|ZBarCam GUI|Simple GUI for ZBar to read bar codes from various sources.|https://zbar.sourceforge.net/|{{Pkg|zbar}}}}<br />
* {{App|Zint Barcode Studio|Barcode generator GUI.|http://zint.org.uk/|{{Pkg|zint-qt}}}}</div>Regidhttps://wiki.archlinux.org/index.php?title=Vi&diff=794966Vi2023-12-23T00:45:11Z<p>Regid: Copied from vim#tutorials since this is a vi tutorial. I haven't deleted the URL from vim#tutorials because most vi commands should work within vim too.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Text editors]]<br />
[[de:Vi]]<br />
[[es:Vi]]<br />
[[fr:Vi]]<br />
[[pt:Vi]]<br />
[[zh-hans:Vi]]<br />
According to [[Wikipedia:Vi|Wikipedia]]:<br />
<br />
:vi is a screen-oriented text editor originally created for the Unix operating system. The portable subset of the behavior of vi and programs based on it, and the ex editor language supported within these programs, is described by (and thus standardized by) the Single Unix Specification and POSIX.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|vi}} package.<br />
<br />
== Vi-style software ==<br />
<br />
The key bindings and modes of vi have been recreated in various other software:<br />
<br />
* [[List of applications/Documents#Vi-style text editors|text editors]], the most popular of which being [[Vim]]<br />
* [[List of applications/Utilities#File managers|file managers]] like [[ranger]] and [[Vifm]]<br />
* the [[Readline#Editing mode|Readline]] input library (used by [[Bash]])<br />
* [[shell]]s like [[Zsh#Key bindings|Zsh]]<br />
* [[web browser]]s like [[Luakit]], [[qutebrowser]] or {{Pkg|vimb}}; for [[Firefox]] and [[Chromium]] there are [[Browser extensions#Keyboard shortcuts|browser extensions]] available.<br />
* most [[tiling window manager]]s can be configured for vi-style control<br />
<br />
== See also ==<br />
<br />
* {{man|1|vi}}<br />
* [https://web.archive.org/web/20140822135551/http://usalug.com/vi.html vi Tutorial and Reference Guide]</div>Regidhttps://wiki.archlinux.org/index.php?title=Vim&diff=794965Vim2023-12-22T23:45:53Z<p>Regid: /* Vim as a pager */ A bit more compact, as already done in vim#Workaround for XDG Base Directory specification.</p>
<hr />
<div>[[Category:Text editors]]<br />
[[Category:Console applications]]<br />
[[de:Vim]]<br />
[[es:Vim]]<br />
[[ja:Vim]]<br />
[[pt:Vim]]<br />
[[ru:Vim]]<br />
[[zh-hans:Vim]]<br />
{{Related articles start}}<br />
{{Related|List of applications/Documents#Vi-style text editors}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Vim (text editor)|Vim]] is a terminal text editor. It is an extended version of [[vi]] with additional features, including syntax highlighting, a comprehensive help system, native scripting (Vim script), a visual mode for text selection, comparison of files ({{man|1|vimdiff|pkg=vim}}), and tools with restricted capabilities such as {{man|1|rview|pkg=vim}} and {{man|1|rvim|pkg=vim}}.<br />
<br />
== Installation ==<br />
<br />
[[Install]] one of the following packages:<br />
<br />
* {{Pkg|vim}} — with [[Python]], [[Lua]], [[Ruby]] and [[Perl]] interpreters support but without [[GTK]]/[[X]] support.<br />
* {{Pkg|gvim}} — which also provides the same as the above ''vim'' package with GTK/X support.<br />
<br />
{{Note|<br />
* The ''vim'' package is built without [[Xorg]] support; specifically the {{ic|+clipboard}} feature is missing, so Vim will not be able to operate with the ''primary'' and ''clipboard'' [[Clipboard|selection buffers]]. The ''gvim'' package provides also the CLI version of Vim with the {{ic|+clipboard}} feature.<br />
* The unofficial repository [[Unofficial user repositories#herecura|herecura]] also provides a number of Vim/gVim variants: {{ic|vim-cli}}, {{ic|vim-gvim-common}}, {{ic|vim-gvim-gtk3}}, {{ic|vim-rt}} and {{ic|vim-tiny}}.<br />
}}<br />
<br />
== Usage ==<br />
<br />
For a basic overview on how to use Vim, follow the vim tutorial by running either ''vimtutor'' (for the terminal version) or ''gvimtutor'' (for the graphical version).<br />
<br />
Vim includes a broad help system that can be accessed with the {{ic|:h ''subject''}} command. Subjects include commands, configuration options, key bindings, plugins etc. Use the {{ic|:h}} command (without any subject) for information about the help system and jumping between subjects.<br />
<br />
== Configuration ==<br />
<br />
Vim's user-specific configuration file is located in the home directory: {{ic|~/.vimrc}}, and Vim files of current user are located inside {{ic|~/.vim/}}. The global configuration file is located at {{ic|/etc/vimrc}}. Global Vim files such as {{ic|defaults.vim}} and {{ic|archlinux.vim}} are located inside {{ic|/usr/share/vim/}}.<br />
<br />
For gVim, the user-specific configuration file is located at {{ic|~/.gvimrc}} and the global configuration file is located at {{ic|/etc/gvimrc}}.<br />
<br />
{{Note|<br />
* Commonly expected behavior such as syntax highlighting is enabled in {{ic|defaults.vim}}, which is loaded when no {{ic|~/.vimrc}} is present. Add {{ic|1=let skip_defaults_vim=1}} to {{ic|/etc/vimrc}} to disable loading of {{ic|defaults.vim}} completely. [https://github.com/vim/vim/issues/1033]. Alternatively, to enable {{ic|defaults.vim}} even when {{ic|~/.vimrc}} is present, see {{ic|:h defaults}} in vim.<br />
* gVim loads both Vim's and gVim's configuration file, while Vim only loads Vim's configuration file.<br />
}}<br />
<br />
=== Clipboard ===<br />
<br />
Vim commands such as {{ic|:yank}} or {{ic|:put}} normally operate with the unnamed register {{ic|""}}. If the {{ic|+clipboard}} feature is available and its value includes {{ic|unnamed}}, then Vim yank, delete, change and put operations which would normally go to the unnamed register will use the clipboard register {{ic|"*}} instead, which is the {{ic|PRIMARY}} buffer in X.<br />
<br />
To change the default register, you can {{ic|1=:set clipboard=unnamedplus}} to use the {{ic|"+}} register instead. The {{ic|"+}} clipboard register corresponds to the {{ic|CLIPBOARD}} buffer in X. It should be noted that the {{ic|clipboard}} option can be set to a comma-delimited value. If you {{ic|1=:set clipboard=unnamedplus,unnamed}}, then yank operations will also copy the yanked text to the {{ic|"*}} register in addition to the {{ic|"+}} register (however, delete, change and put operations will still only operate on the {{ic|"+}} register).<br />
<br />
For more information, see {{ic|:help 'clipboard'}}. There are other values which can be set for the {{ic|clipboard}} feature. You can use {{ic|:help clipboard-unnamed}} to take you to the help topic for the first valid value which can be set for this feature, followed by help for all other valid values.<br />
<br />
{{Tip|<br />
* Custom shortcuts for copy and paste operations can be created. See e.g. [https://superuser.com/a/189198] for binding {{ic|Ctrl+c}}, {{ic|Ctrl+v}} and {{ic|Ctrl+x}}.<br />
* The X clipboard gets flushed when vim exits. To make the vim selection persistent within X clipboard, you need a [[clipboard manager]]. Alternatively, you can add {{ic|autocmd VimLeave * call system("echo -n $'" . escape(getreg(), "'") . "' {{!}} xsel --input --clipboard")}} to your {{ic|.vimrc}} (requires the {{Pkg|xsel}} package).<br />
}}<br />
<br />
=== Syntax highlighting ===<br />
<br />
To enable syntax highlighting for many programming languages:<br />
<br />
:filetype plugin on<br />
:syntax on<br />
<br />
=== Indentation ===<br />
<br />
{{Expansion|Describe the {{ic|autoindent}} and {{ic|smartindent}} options.}}<br />
<br />
The indent file for specific file types can be loaded with:<br />
<br />
:filetype indent on<br />
<br />
=== Visual wrapping ===<br />
<br />
The {{ic|wrap}} option is on by default, which instructs Vim to wrap lines longer than the width of the window, so that the rest of the line is displayed on the next line. The {{ic|wrap}} option only affects how text is displayed, the text itself is not modified.<br />
<br />
The wrapping normally occurs after the last character that fits the window, even when it is in the middle of a word. More intelligent wrapping can be controlled with the {{ic|linebreak}} option. When it is enabled with {{ic|set linebreak}}, the wrapping occurs after characters listed in the {{ic|breakat}} string option, which by default contains a space and some punctuation marks (see {{ic|:help breakat}}).<br />
<br />
Wrapped lines are normally displayed at the beginning of the next line, regardless of any indentation. The [https://retracile.net/wiki/VimBreakIndent breakindent] option instructs Vim to take indentation into account when wrapping long lines, so that the wrapped lines keep the same indentation of the previously displayed line. The behaviour of {{ic|breakindent}} can be fine-tuned with the {{ic|breakindentopt}} option, for example to shift the wrapped line another four spaces to the right for Python files (see {{ic|:help breakindentopt}} for details):<br />
<br />
autocmd FileType python set breakindentopt=shift:4<br />
<br />
=== Using the mouse ===<br />
<br />
Vim has the ability to make use of the mouse, but it only works for certain terminals:<br />
<br />
* [[xterm]]/[[urxvt]]-based terminal emulators<br />
* Linux console with {{Pkg|gpm}} (see [[Console mouse support]] for details)<br />
* [[PuTTY]]<br />
<br />
To enable this feature, add this line into {{ic|~/.vimrc}}:<br />
<br />
set mouse=a<br />
<br />
The {{ic|1=mouse=a}} option is set in {{ic|defaults.vim}}.<br />
<br />
{{Note|Copy/paste will use the {{ic|"*}} register if there is access to an X server, see the [[#Clipboard]] section. The xterm handling of the mouse buttons can still be used by keeping the {{ic|shift key}} pressed.}}<br />
<br />
=== Traverse line breaks with arrow keys ===<br />
<br />
By default, pressing {{ic|Left}} at the beginning of a line, or pressing {{ic|Right}} at the end of a line, will not let the cursor traverse to the previous, or following, line.<br />
<br />
The default behavior can be changed by adding {{ic|1=set whichwrap=b,s,<,>,[,]}} to your {{ic|~/.vimrc}} file.<br />
<br />
== Merging files ==<br />
<br />
Vim includes a diff editor (a program that shows differences between two or more files and aids to conveniently merge them). Use ''vimdiff'' to run the diff editor — just specify some couple of files to it: {{ic|vimdiff ''file1'' ''file2''}}. Here is the list of ''vimdiff''-specific commands.<br />
<br />
{| class="wikitable"<br />
! Action !! Shortcut<br />
|-<br />
| next change || {{ic|]c}}<br />
|-<br />
| previous change || {{ic|[c}}<br />
|-<br />
| diff obtain || {{ic|do}}<br />
|-<br />
| diff put || {{ic|dp}}<br />
|-<br />
| fold open || {{ic|zo}}<br />
|-<br />
| fold close || {{ic|zc}}<br />
|-<br />
| rescan files || {{ic|:diffupdate}}<br />
|}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Line numbers ===<br />
<br />
To show the line number column, use {{ic|:set number}}. By default absolute line numbers are shown, relative numbers can be enabled with {{ic|:set relativenumber}}. Setting both enables hybrid line numbers—the current line is absolute, while the others are relative.<br />
<br />
Jumping to a specific line is possible with {{ic|:''line number''}} or {{ic|''line number''gg}}. Jumps are remembered in a jump list, see {{ic|:h jump-motions}} for details.<br />
<br />
=== Spell checking ===<br />
<br />
Vim has the ability to do spell checking, enable by entering:<br />
<br />
set spell<br />
<br />
By default, only English language dictionaries are installed (in {{ic|/usr/share/vim/vim82/spell/}}). More dictionaries can be found in the [[official repositories]] by searching for {{ic|vim-spell}}. Additional dictionaries can be found in the [http://ftp.vim.org/vim/runtime/spell/ Vim's FTP archive]. Additional dictionaries can be put in the folder {{ic|~/.vim/spell/}} and enabled with the command: {{ic|1=:setlocal spell spelllang=''en_us''}} (replacing the {{ic|''en_us''}} with the name of the needed dictionary).<br />
<br />
{| class="wikitable"<br />
! Action !! Shortcut<br />
|-<br />
| next spelling || {{ic|]s}}<br />
|-<br />
| previous spelling || {{ic|[s}}<br />
|-<br />
| spelling suggestions || {{ic|1=z=}}<br />
|-<br />
| spelling good, add || {{ic|zg}}<br />
|-<br />
| spelling good, session || {{ic|zG}}<br />
|-<br />
| spelling wrong, add || {{ic|zw}}<br />
|-<br />
| spelling wrong, session || {{ic|zW}}<br />
|-<br />
| spelling repeat all in file || {{ic|:spellr}}<br />
|}<br />
<br />
{{Tip|<br />
* To enable spelling in two languages (for instance English and German), add {{ic|1=set spelllang=''en,de''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim.<br />
* You can enable spell checking for arbitrary file types (e.g. ''.txt'') by using the FileType plugin and a custom rule for file type detection. To enable spell checking for any file ending with ''.txt'', create the file {{ic|/usr/share/vim/vimfiles/ftdetect/plaintext.vim}}, and insert the line {{ic|1=autocmd BufRead,BufNewFile *.txt set filetype=plaintext}} into that file. Next, insert the line {{ic|1=autocmd FileType plaintext setlocal spell spelllang=''en_us''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim. Alternatively, one can simply insert the line {{ic|autocmd BufRead,BufNewFile *.txt setlocal spell}} into their {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim. Be sure to edit this line (specifically {{ic|*.txt}}) to include the filetype(s) intended for spell checking.<br />
* To enable spell checking for LaTeX (or TeX) documents only, add {{ic|1=autocmd FileType '''tex''' setlocal spell spelllang=''en_us''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim.<br />
}}<br />
<br />
=== Saving runtime state ===<br />
<br />
Normally, exiting {{ic|vim}} discards all unessential information such as opened files, command line history, yanked text etc. Preserving this information can be configured in the following ways.<br />
<br />
==== viminfo files ====<br />
<br />
The {{ic|viminfo}} file may also be used to store command line history, search string history, input-line history, registers' content, marks for files, location marks within files, last search/substitute pattern (to be used in search mode with {{ic|n}} and {{ic|&}} within the session), buffer list, and any global variables you may have defined. For the {{ic|viminfo}} modality to be available, the version of {{ic|vim}} you installed must have been compiled with the {{ic|+viminfo}} feature.<br />
<br />
Configure what is kept in your {{ic|viminfo}} file, by adding (for example) the following to your {{ic|~/.vimrc}} file:<br />
<br />
set viminfo='10,<100,:100,%,n~/.vim/.viminfo<br />
<br />
where each parameter is preceded by an identifier:<br />
<br />
'q : q, number of edited file remembered<br />
<m : m, number of lines saved for each register<br />
:p : p, number of history cmd lines remembered<br />
% : saves and restore the buffer list<br />
n...: fully qualified path to the viminfo files (note that this is a literal "''n''")<br />
<br />
See the official [https://vimdoc.sourceforge.net/htmldoc/options.html#'viminfo' viminfo documentation] for particulars on how a pre-existing {{ic|viminfo}} file is modified as it is updated with current session information, say from several buffers in the current session you are in the process of exiting.<br />
<br />
==== Session files ====<br />
<br />
Session files can be used to save the state of any number of particular sessions over time. One distinct session file may be used for each session or project of your interest. For that modality to be available, the version of {{ic|vim}} you installed must have been compiled with the {{ic|+mksession}} feature.<br />
<br />
Within a session, {{ic|:mksession[!] [''my_session_name.vim'']}} will write a vim-script to {{ic|''my_session_name.vim''}} in the current directory, or {{ic|Session.vim}} by default if you choose ''not'' to provide a file name. The optional {{ic|!}} will clobber a pre-existing session file with the same name and path.<br />
<br />
A {{ic|vim}} session can be resumed either when starting ''vim'' from terminal:<br />
<br />
$ vim -S [''my_session_name.vim'']<br />
<br />
Or in an already opened session buffer by running the vim command:<br />
<br />
:source ''my_session_name.vim''<br />
<br />
Exactly what is saved and additional details on session files options are extensively covered in the [https://vimdoc.sourceforge.net/htmldoc/usr_21.html#21.4 vim documentation]. Commented examples are found [https://vim.wikia.com/wiki/Go_away_and_come_back here].<br />
<br />
==== Saving cursor position ====<br />
<br />
See [https://vim.wikia.com/wiki/Restore_cursor_to_file_position_in_previous_editing_session Restore cursor to file position in previous editing session] on the Vim wiki.<br />
<br />
=== Replace vi command with Vim ===<br />
<br />
Create an [[alias]] for {{ic|vi}} to {{ic|vim}}.<br />
<br />
Alternatively, if you want to be able to type {{ic|sudo vi}} and get {{ic|vim}}, install {{AUR|vi-vim-symlink}} which will remove {{ic|vi}} and replace it with a symlink to {{ic|vim}}. You could also create this symlink yourself and place it somewhere higher in your path than {{ic|/usr/bin}} to have it take precedence.<br />
<br />
=== DOS/Windows carriage returns ===<br />
<br />
If there is a {{ic|^M}} at the end of each line then this means you are editing a text file which was created in MS-DOS or Windows. This is because in Linux only a single line feed character (LF) used for line break, but in Windows/MS DOS systems they are using a sequence of a carriage return (CR) and a line feed (LF) for the same. And this carriage returns are displayed as {{ic|^M}}.<br />
<br />
To remove all carriage returns from a file do:<br />
<br />
:%s/^M//g<br />
<br />
Note that there {{ic|^}} is a control letter. To enter the control sequence {{ic|^M}} press {{ic|Ctrl+v,Ctrl+m}}.<br />
<br />
Alternatively install the package {{Pkg|dos2unix}} and run {{ic|dos2unix ''file''}} to fix the file.<br />
<br />
{{Note|Another simple way is by changing {{ic|fileformat}} setting. {{ic|1=set ff=unix}} to convert files with DOS/Windows line ending to Unix line ending. To do the reverse, just issue {{ic|1=set ff=dos}} to convert files with Unix line ending to DOS/Windows line ending.}}<br />
<br />
=== Empty space at the bottom of gVim windows ===<br />
<br />
When using a [[window manager]] configured to ignore window size hints, gVim will fill the non-functional area with the GTK theme background color.<br />
<br />
The solution is to adjust how much space gVim reserves at the bottom of the window. Put the following line in {{ic|~/.vimrc}}:<br />
<br />
set guiheadroom=0<br />
<br />
{{Note|If you set it to zero, you will not be able to see the bottom horizontal scrollbar.}}<br />
<br />
=== Vim as a pager ===<br />
<br />
Using scripts Vim can be used as a [[terminal pager]], so that you get various vim features such as color schemes.<br />
Vim comes with the {{ic|/usr/share/vim/vim90/macros/less.sh}} script, for which you can create an [[alias]]. Note that this script does not support any command-line flags mentioned in {{man|1|less|OPTIONS}}.<br />
<br />
Alternatively there is also the {{Pkg|vimpager}} Vim script. To change the default pager, [[export]] the {{ic|PAGER}} environment variable. Note that not all command-line flags are supported; the list of supported flags is [https://github.com/rkitover/vimpager#command-line-options available on GitHub].<br />
<br />
A middle way between a pager and an editor are {{ic|[g]view}}, which is equivalent to {{ic|[g]vim -R}}. This will cause the editor to open files in a {{ic|readonly}} mode. Every editor feature that does not involve modifying the files is available as usual. In fact, the {{ic|readonly}} mode can be explicitly overridden, to enable modification as well.<br />
<br />
=== Highlighting search results ===<br />
<br />
In order to highlight the first string that will be matched in a search while typing the search, add the following line to your {{ic|~/.vimrc}}:<br />
<br />
set incsearch<br />
<br />
In order to highlight all strings that will be matched in a search while typing the search, and after the search has been executed, add the following line to your {{ic|~/.vimrc}}:<br />
<br />
set hlsearch<br />
<br />
{{Note|<br />
* Setting {{ic|hlsearch}} will keep all matches highlighted until a further search is made. This behaviour may be undesired, so to temporarily disable the highlighting until the next search, run {{ic|:nohlsearch}}. If you find yourself running this command often, consider binding it to a key.<br />
* This behaviour will also be observed when matching regex during other commands that involve them like {{ic|s}} or {{ic|g}}.<br />
}}<br />
<br />
=== Workaround for XDG Base Directory specification ===<br />
<br />
Since [https://github.com/vim/vim/commit/6a459902592e2a4ba68 7.3.1178] vim will search for {{ic|~/.vim/vimrc}} if {{ic|~/.vimrc}} is not found.<br />
<br />
{{hc|"$XDG_CONFIG_HOME"/vim/vimrc|<nowiki><br />
set runtimepath^=$XDG_CONFIG_HOME/vim<br />
set runtimepath+=$XDG_DATA_HOME/vim<br />
set runtimepath+=$XDG_CONFIG_HOME/vim/after<br />
<br />
set packpath^=$XDG_DATA_HOME/vim,$XDG_CONFIG_HOME/vim<br />
set packpath+=$XDG_CONFIG_HOME/vim/after,$XDG_DATA_HOME/vim/after<br />
<br />
let g:netrw_home = $XDG_DATA_HOME."/vim"<br />
call mkdir($XDG_DATA_HOME."/vim/spell", 'p')<br />
<br />
set backupdir=$XDG_STATE_HOME/vim/backup | call mkdir(&backupdir, 'p')<br />
set directory=$XDG_STATE_HOME/vim/swap | call mkdir(&directory, 'p')<br />
set undodir=$XDG_STATE_HOME/vim/undo | call mkdir(&undodir, 'p')<br />
set viewdir=$XDG_STATE_HOME/vim/view | call mkdir(&viewdir, 'p')<br />
<br />
if !has('nvim') | set viminfofile=$XDG_STATE_HOME/vim/viminfo | endif<br />
</nowiki>}}<br />
<br />
{{hc|~/.profile|2=<br />
export GVIMINIT='let $MYGVIMRC="$XDG_CONFIG_HOME/vim/gvimrc" {{!}} source $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC="$XDG_CONFIG_HOME/vim/vimrc" {{!}} source $MYVIMRC'<br />
}}<br />
<br />
{{ic|[G]VIMINIT}} environment variable will also affect Neovim. If separate configs for Vim and Neovim are desired then the following will be a better choice:<br />
export GVIMINIT='let $MYGVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/gvimrc" : "$XDG_CONFIG_HOME/nvim/init.gvim" | so $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/vimrc" : "$XDG_CONFIG_HOME/nvim/init.vim" | so $MYVIMRC'<br />
<br />
* https://jorengarenar.github.io/blog/vim-xdg<br />
* https://tlvince.com/vim-respect-xdg<br />
<br />
== Plugins ==<br />
<br />
Adding plugins to Vim can increase your productivity by extending Vim's features. Plugins can alter Vim's UI, add new commands, enable code completion support, integrate other programs and utilities with Vim, add support for additional languages and more.<br />
<br />
{{Tip|For a list of popular plugins, see [https://vimawesome.com/ Vim Awesome].}}<br />
<br />
=== Installation ===<br />
<br />
==== Using the built-in package manager ====<br />
<br />
Vim 8 added the possibility to load third-party plugins natively. This functionality can be used by storing third-party packages in the {{ic|~/.vim/pack}} folder. The structure of this folder differs slightly from that of typical plugin managers which will usually have a single directory per plugin. What follows is a typical installation procedure and directory structure (using [https://github.com/tpope/vim-surround Tim Pope's vim-surround plugin] as an example):<br />
<br />
$ mkdir -p ~/.vim/pack/tpope/start<br />
<br />
It is important to note that {{ic|~/.vim/pack/tpope}} is a ''package directory'' which is loosely defined as directory containing one or more plugins in the [https://vimhelp.org/repeat.txt.html#packages Vim documentation]. Plugin repositories should not be downloaded to this directory though. The name of the package directory is also arbitrary. You can choose to keep all your plugins in a single package directory or, as in our example, use the author's GitHub name, {{ic|tpope}}.<br />
<br />
The package directory can contain the following subfolders:<br />
<br />
* {{ic|start}} - plugins from this subfolder will be loaded automatically when Vim starts. This is the most frequently used location.<br />
* {{ic|opt}} - plugins from this subfolder can be loaded on-demand by issuing {{ic|:packadd}} command inside Vim.<br />
<br />
Now change into the {{ic|start}} folder and checkout the plugin repository:<br />
<br />
$ cd ~/.vim/pack/tpope/start<br />
$ git clone https://tpope.io/vim/surround.git<br />
<br />
This creates an additional subfolder, {{ic|~/.vim/pack/tpope/start/surround}}, where the plugin files are placed.<br />
<br />
Next, update the help index if the plugin contains help files:<br />
<br />
$ vim -u NONE -c "helptags surround/doc" -c q<br />
<br />
The plugin will now be loaded automatically when starting Vim. No changes to {{ic|~/.vimrc}} are required, barring plugin-specific options.<br />
<br />
==== Using a plugin manager ====<br />
<br />
A plugin manager is a plugin that installs, manages and updates Vim plugins. This can be useful if you are also using Vim on platforms other than Arch Linux and want a consistent method of updating plugins.<br />
<br />
* [https://github.com/junegunn/vim-plug Vim-plug] is a minimalist Vim plugin manager with many features like on-demand plugin loading and parallel updating, available as {{AUR|vim-plug}} or {{AUR|vim-plug-git}}.<br />
* [https://github.com/gmarik/Vundle.vim Vundle] is available as {{AUR|vundle}} or {{AUR|vundle-git}}.<br />
* [https://github.com/tpope/vim-pathogen pathogen.vim] is a simple plugin for managing Vim's runtimepath, available as {{AUR|vim-pathogen}} or {{AUR|vim-pathogen-git}}.<br />
* [https://github.com/Shougo/dein.vim Dein.vim] is a plugin manager replacing [https://github.com/Shougo/neobundle.vim NeoBundle], available as {{AUR|vim-dein}} or {{AUR|vim-dein-git}}.<br />
<br />
==== From Arch repositories ====<br />
<br />
The {{Grp|vim-plugins}} group provides various plugins. Use {{ic|pacman -Sg vim-plugins}} command to list available packages which you can then [[install]] with pacman.<br />
<br />
=== Notable plugins ===<br />
<br />
==== cscope ====<br />
<br />
[https://cscope.sourceforge.net/ Cscope] is a tool for browsing a project. By navigating to a word/symbol/function and calling cscope (usually with shortcut keys) it can find: functions calling the function, the function definition, and more.<br />
<br />
[[Install]] the {{Pkg|cscope}} package.<br />
<br />
Copy the cscope default file where it will be automatically read by Vim:<br />
<br />
mkdir -p ~/.vim/plugin<br />
wget -P ~/.vim/plugin https://cscope.sourceforge.net/cscope_maps.vim<br />
<br />
{{Note|You will probably need to uncomment these lines in {{ic|~/.vim/plugin/cscope_maps.vim}} in order to enable cscope shortcuts in Vim 7.x:<br />
{{bc|1=<br />
set timeoutlen=4000<br />
set ttimeout<br />
}}}}<br />
<br />
Create a file which contains the list of files you wish cscope to index (cscope can handle many languages but this example finds ''.c'', ''.cpp'' and ''.h'' files, specific for C/C++ project):<br />
<br />
$ cd ''/path/to/project/dir''<br />
$ find . -type f -print | grep -E '\.(c(pp)?|h)$' > cscope.files<br />
<br />
Create database files that cscope will read:<br />
<br />
$ cscope -bq<br />
<br />
{{Note|You must browse your project files from this location or set and export the {{ic|$CSCOPE_DB}} variable, pointing it to the {{ic|cscope.out}} file.}}<br />
<br />
Default keyboard shortcuts:<br />
<br />
Ctrl-\ and<br />
c: Find functions calling this function<br />
d: Find functions called by this function<br />
e: Find this egrep pattern<br />
f: Find this file<br />
g: Find this definition<br />
i: Find files #including this file<br />
s: Find this C symbol<br />
t: Find assignments to<br />
<br />
Feel free to change the shortcuts.<br />
<br />
#Maps ctrl-c to find functions calling the function<br />
nnoremap <C-c> :cs find c <C-R>=expand("<cword>")<CR><CR><br />
<br />
==== Taglist ====<br />
<br />
[https://vim-taglist.sourceforge.net/ Taglist] provides an overview of the structure of source code files and allows you to efficiently browse through source code files in different programming languages.<br />
<br />
[[Install]] the {{AUR|vim-taglist}} package.<br />
<br />
Useful options to be put in {{ic|~/.vimrc}}:<br />
<br />
let Tlist_Compact_Format = 1<br />
let Tlist_GainFocus_On_ToggleOpen = 1<br />
let Tlist_Close_On_Select = 1<br />
nnoremap <C-l> :TlistToggle<CR><br />
<br />
== Troubleshooting ==<br />
<br />
=== gVim is slow ===<br />
<br />
Vim's GTK 3 GUI may be slower than the GTK 2 version (see {{Bug|51366}}). {{AUR|gvim-gtk2}} can be installed as a workaround.<br />
<br />
== See also ==<br />
<br />
=== Official ===<br />
<br />
* [https://www.vim.org/ Homepage]<br />
* [https://vimdoc.sourceforge.net/ Documentation]<br />
* [https://vim.wikia.com Vim Wiki]<br />
* [https://www.vim.org/scripts/ Vim Scripts]<br />
<br />
=== Tutorials ===<br />
<br />
* [https://danielmiessler.com/study/vim/ vim Tutorial and Primer]<br />
* [https://web.archive.org/web/20140822135551/http://usalug.com/vi.html vi Tutorial and Reference Guide]<br />
* [http://www.viemu.com/a_vi_vim_graphical_cheat_sheet_tutorial.html Graphical vi-Vim Cheat Sheet and Tutorial]<br />
* [https://archive.today/2012.12.20-221858/http://blog.interlinked.org/tutorials/vim_tutorial.html Vim Introduction and Tutorial]<br />
* [https://www.openvim.com/ Open Vim] — collection of Vim learning tools<br />
* [https://yannesposito.com/Scratch/en/blog/Learn-Vim-Progressively/ Learn Vim Progressively]<br />
* [https://benmccormick.org/learning-vim-in-2014/ Learning Vim in 2014]<br />
* [https://www.moolenaar.net/habits.html Seven habits of effective text editing]<br />
* [https://bencrowder.net/files/vim-fu/ Basic Vim Tips]<br />
<br />
==== Videos ====<br />
<br />
* [http://vimcasts.org/ Vimcasts] — screencasts in ''.ogg'' format.<br />
* [http://derekwyatt.org/vim/tutorials/ Vim Tutorial Videos] — covering the basics up to advanced topics.<br />
<br />
==== Cheat sheets ====<br />
<br />
* https://devhints.io/vim<br />
* https://vim.rtorr.com/ - A mobile friendly Vim cheat sheet - [https://github.com/rtorr/vim-cheat-sheet Sources]<br />
<br />
==== Games ====<br />
<br />
* [https://vim-adventures.com/ Vim Adventures]<br />
* [https://vimgolf.com/ VimGolf]<br />
<br />
=== Configuration ===<br />
<br />
* [https://web.archive.org/web/20131020125020/http://nion.modprobe.de/setup/vimrc nion's]<br />
* [https://github.com/amix/vimrc A detailed configuration from Amir Salihefendic]<br />
* [https://web.archive.org/web/20131004071740/http://www.jukie.net/~bart/conf/vimrc Bart Trojanowski]<br />
* [https://github.com/spf13/spf13-vim Steve Francia's Vim Distribution]<br />
* [https://vimawesome.com/ Vim Awesome] - Vim Plugins<br />
* [https://github.com/W4RH4WK/dotVim W4RH4WK's Vim configuration]<br />
* [https://www.askapache.com/linux/fast-vimrc/ Fast vimrc/colorscheme from askapache]<br />
* [https://gist.github.com/anonymous/c966c0757f62b451bffa Basic vimrc]<br />
<br />
==== Colors ====<br />
<br />
* [http://bytefluent.com/vivify/ Vivify]<br />
* [https://linuxtidbits.wordpress.com/2014/10/14/vim-customize-installed-colorschemes/ Vim colorscheme customization]</div>Regidhttps://wiki.archlinux.org/index.php?title=Vim&diff=794964Vim2023-12-22T22:46:48Z<p>Regid: /* Vim as a pager */ There is also a middle way, of a pager that can be explicitly overridden to an editor. One benefit, for those familiar with vim, is the use of a known environment.</p>
<hr />
<div>[[Category:Text editors]]<br />
[[Category:Console applications]]<br />
[[de:Vim]]<br />
[[es:Vim]]<br />
[[ja:Vim]]<br />
[[pt:Vim]]<br />
[[ru:Vim]]<br />
[[zh-hans:Vim]]<br />
{{Related articles start}}<br />
{{Related|List of applications/Documents#Vi-style text editors}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:Vim (text editor)|Vim]] is a terminal text editor. It is an extended version of [[vi]] with additional features, including syntax highlighting, a comprehensive help system, native scripting (Vim script), a visual mode for text selection, comparison of files ({{man|1|vimdiff|pkg=vim}}), and tools with restricted capabilities such as {{man|1|rview|pkg=vim}} and {{man|1|rvim|pkg=vim}}.<br />
<br />
== Installation ==<br />
<br />
[[Install]] one of the following packages:<br />
<br />
* {{Pkg|vim}} — with [[Python]], [[Lua]], [[Ruby]] and [[Perl]] interpreters support but without [[GTK]]/[[X]] support.<br />
* {{Pkg|gvim}} — which also provides the same as the above ''vim'' package with GTK/X support.<br />
<br />
{{Note|<br />
* The ''vim'' package is built without [[Xorg]] support; specifically the {{ic|+clipboard}} feature is missing, so Vim will not be able to operate with the ''primary'' and ''clipboard'' [[Clipboard|selection buffers]]. The ''gvim'' package provides also the CLI version of Vim with the {{ic|+clipboard}} feature.<br />
* The unofficial repository [[Unofficial user repositories#herecura|herecura]] also provides a number of Vim/gVim variants: {{ic|vim-cli}}, {{ic|vim-gvim-common}}, {{ic|vim-gvim-gtk3}}, {{ic|vim-rt}} and {{ic|vim-tiny}}.<br />
}}<br />
<br />
== Usage ==<br />
<br />
For a basic overview on how to use Vim, follow the vim tutorial by running either ''vimtutor'' (for the terminal version) or ''gvimtutor'' (for the graphical version).<br />
<br />
Vim includes a broad help system that can be accessed with the {{ic|:h ''subject''}} command. Subjects include commands, configuration options, key bindings, plugins etc. Use the {{ic|:h}} command (without any subject) for information about the help system and jumping between subjects.<br />
<br />
== Configuration ==<br />
<br />
Vim's user-specific configuration file is located in the home directory: {{ic|~/.vimrc}}, and Vim files of current user are located inside {{ic|~/.vim/}}. The global configuration file is located at {{ic|/etc/vimrc}}. Global Vim files such as {{ic|defaults.vim}} and {{ic|archlinux.vim}} are located inside {{ic|/usr/share/vim/}}.<br />
<br />
For gVim, the user-specific configuration file is located at {{ic|~/.gvimrc}} and the global configuration file is located at {{ic|/etc/gvimrc}}.<br />
<br />
{{Note|<br />
* Commonly expected behavior such as syntax highlighting is enabled in {{ic|defaults.vim}}, which is loaded when no {{ic|~/.vimrc}} is present. Add {{ic|1=let skip_defaults_vim=1}} to {{ic|/etc/vimrc}} to disable loading of {{ic|defaults.vim}} completely. [https://github.com/vim/vim/issues/1033]. Alternatively, to enable {{ic|defaults.vim}} even when {{ic|~/.vimrc}} is present, see {{ic|:h defaults}} in vim.<br />
* gVim loads both Vim's and gVim's configuration file, while Vim only loads Vim's configuration file.<br />
}}<br />
<br />
=== Clipboard ===<br />
<br />
Vim commands such as {{ic|:yank}} or {{ic|:put}} normally operate with the unnamed register {{ic|""}}. If the {{ic|+clipboard}} feature is available and its value includes {{ic|unnamed}}, then Vim yank, delete, change and put operations which would normally go to the unnamed register will use the clipboard register {{ic|"*}} instead, which is the {{ic|PRIMARY}} buffer in X.<br />
<br />
To change the default register, you can {{ic|1=:set clipboard=unnamedplus}} to use the {{ic|"+}} register instead. The {{ic|"+}} clipboard register corresponds to the {{ic|CLIPBOARD}} buffer in X. It should be noted that the {{ic|clipboard}} option can be set to a comma-delimited value. If you {{ic|1=:set clipboard=unnamedplus,unnamed}}, then yank operations will also copy the yanked text to the {{ic|"*}} register in addition to the {{ic|"+}} register (however, delete, change and put operations will still only operate on the {{ic|"+}} register).<br />
<br />
For more information, see {{ic|:help 'clipboard'}}. There are other values which can be set for the {{ic|clipboard}} feature. You can use {{ic|:help clipboard-unnamed}} to take you to the help topic for the first valid value which can be set for this feature, followed by help for all other valid values.<br />
<br />
{{Tip|<br />
* Custom shortcuts for copy and paste operations can be created. See e.g. [https://superuser.com/a/189198] for binding {{ic|Ctrl+c}}, {{ic|Ctrl+v}} and {{ic|Ctrl+x}}.<br />
* The X clipboard gets flushed when vim exits. To make the vim selection persistent within X clipboard, you need a [[clipboard manager]]. Alternatively, you can add {{ic|autocmd VimLeave * call system("echo -n $'" . escape(getreg(), "'") . "' {{!}} xsel --input --clipboard")}} to your {{ic|.vimrc}} (requires the {{Pkg|xsel}} package).<br />
}}<br />
<br />
=== Syntax highlighting ===<br />
<br />
To enable syntax highlighting for many programming languages:<br />
<br />
:filetype plugin on<br />
:syntax on<br />
<br />
=== Indentation ===<br />
<br />
{{Expansion|Describe the {{ic|autoindent}} and {{ic|smartindent}} options.}}<br />
<br />
The indent file for specific file types can be loaded with:<br />
<br />
:filetype indent on<br />
<br />
=== Visual wrapping ===<br />
<br />
The {{ic|wrap}} option is on by default, which instructs Vim to wrap lines longer than the width of the window, so that the rest of the line is displayed on the next line. The {{ic|wrap}} option only affects how text is displayed, the text itself is not modified.<br />
<br />
The wrapping normally occurs after the last character that fits the window, even when it is in the middle of a word. More intelligent wrapping can be controlled with the {{ic|linebreak}} option. When it is enabled with {{ic|set linebreak}}, the wrapping occurs after characters listed in the {{ic|breakat}} string option, which by default contains a space and some punctuation marks (see {{ic|:help breakat}}).<br />
<br />
Wrapped lines are normally displayed at the beginning of the next line, regardless of any indentation. The [https://retracile.net/wiki/VimBreakIndent breakindent] option instructs Vim to take indentation into account when wrapping long lines, so that the wrapped lines keep the same indentation of the previously displayed line. The behaviour of {{ic|breakindent}} can be fine-tuned with the {{ic|breakindentopt}} option, for example to shift the wrapped line another four spaces to the right for Python files (see {{ic|:help breakindentopt}} for details):<br />
<br />
autocmd FileType python set breakindentopt=shift:4<br />
<br />
=== Using the mouse ===<br />
<br />
Vim has the ability to make use of the mouse, but it only works for certain terminals:<br />
<br />
* [[xterm]]/[[urxvt]]-based terminal emulators<br />
* Linux console with {{Pkg|gpm}} (see [[Console mouse support]] for details)<br />
* [[PuTTY]]<br />
<br />
To enable this feature, add this line into {{ic|~/.vimrc}}:<br />
<br />
set mouse=a<br />
<br />
The {{ic|1=mouse=a}} option is set in {{ic|defaults.vim}}.<br />
<br />
{{Note|Copy/paste will use the {{ic|"*}} register if there is access to an X server, see the [[#Clipboard]] section. The xterm handling of the mouse buttons can still be used by keeping the {{ic|shift key}} pressed.}}<br />
<br />
=== Traverse line breaks with arrow keys ===<br />
<br />
By default, pressing {{ic|Left}} at the beginning of a line, or pressing {{ic|Right}} at the end of a line, will not let the cursor traverse to the previous, or following, line.<br />
<br />
The default behavior can be changed by adding {{ic|1=set whichwrap=b,s,<,>,[,]}} to your {{ic|~/.vimrc}} file.<br />
<br />
== Merging files ==<br />
<br />
Vim includes a diff editor (a program that shows differences between two or more files and aids to conveniently merge them). Use ''vimdiff'' to run the diff editor — just specify some couple of files to it: {{ic|vimdiff ''file1'' ''file2''}}. Here is the list of ''vimdiff''-specific commands.<br />
<br />
{| class="wikitable"<br />
! Action !! Shortcut<br />
|-<br />
| next change || {{ic|]c}}<br />
|-<br />
| previous change || {{ic|[c}}<br />
|-<br />
| diff obtain || {{ic|do}}<br />
|-<br />
| diff put || {{ic|dp}}<br />
|-<br />
| fold open || {{ic|zo}}<br />
|-<br />
| fold close || {{ic|zc}}<br />
|-<br />
| rescan files || {{ic|:diffupdate}}<br />
|}<br />
<br />
== Tips and tricks ==<br />
<br />
=== Line numbers ===<br />
<br />
To show the line number column, use {{ic|:set number}}. By default absolute line numbers are shown, relative numbers can be enabled with {{ic|:set relativenumber}}. Setting both enables hybrid line numbers—the current line is absolute, while the others are relative.<br />
<br />
Jumping to a specific line is possible with {{ic|:''line number''}} or {{ic|''line number''gg}}. Jumps are remembered in a jump list, see {{ic|:h jump-motions}} for details.<br />
<br />
=== Spell checking ===<br />
<br />
Vim has the ability to do spell checking, enable by entering:<br />
<br />
set spell<br />
<br />
By default, only English language dictionaries are installed (in {{ic|/usr/share/vim/vim82/spell/}}). More dictionaries can be found in the [[official repositories]] by searching for {{ic|vim-spell}}. Additional dictionaries can be found in the [http://ftp.vim.org/vim/runtime/spell/ Vim's FTP archive]. Additional dictionaries can be put in the folder {{ic|~/.vim/spell/}} and enabled with the command: {{ic|1=:setlocal spell spelllang=''en_us''}} (replacing the {{ic|''en_us''}} with the name of the needed dictionary).<br />
<br />
{| class="wikitable"<br />
! Action !! Shortcut<br />
|-<br />
| next spelling || {{ic|]s}}<br />
|-<br />
| previous spelling || {{ic|[s}}<br />
|-<br />
| spelling suggestions || {{ic|1=z=}}<br />
|-<br />
| spelling good, add || {{ic|zg}}<br />
|-<br />
| spelling good, session || {{ic|zG}}<br />
|-<br />
| spelling wrong, add || {{ic|zw}}<br />
|-<br />
| spelling wrong, session || {{ic|zW}}<br />
|-<br />
| spelling repeat all in file || {{ic|:spellr}}<br />
|}<br />
<br />
{{Tip|<br />
* To enable spelling in two languages (for instance English and German), add {{ic|1=set spelllang=''en,de''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim.<br />
* You can enable spell checking for arbitrary file types (e.g. ''.txt'') by using the FileType plugin and a custom rule for file type detection. To enable spell checking for any file ending with ''.txt'', create the file {{ic|/usr/share/vim/vimfiles/ftdetect/plaintext.vim}}, and insert the line {{ic|1=autocmd BufRead,BufNewFile *.txt set filetype=plaintext}} into that file. Next, insert the line {{ic|1=autocmd FileType plaintext setlocal spell spelllang=''en_us''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim. Alternatively, one can simply insert the line {{ic|autocmd BufRead,BufNewFile *.txt setlocal spell}} into their {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim. Be sure to edit this line (specifically {{ic|*.txt}}) to include the filetype(s) intended for spell checking.<br />
* To enable spell checking for LaTeX (or TeX) documents only, add {{ic|1=autocmd FileType '''tex''' setlocal spell spelllang=''en_us''}} into your {{ic|~/.vimrc}} or {{ic|/etc/vimrc}}, and then restart Vim.<br />
}}<br />
<br />
=== Saving runtime state ===<br />
<br />
Normally, exiting {{ic|vim}} discards all unessential information such as opened files, command line history, yanked text etc. Preserving this information can be configured in the following ways.<br />
<br />
==== viminfo files ====<br />
<br />
The {{ic|viminfo}} file may also be used to store command line history, search string history, input-line history, registers' content, marks for files, location marks within files, last search/substitute pattern (to be used in search mode with {{ic|n}} and {{ic|&}} within the session), buffer list, and any global variables you may have defined. For the {{ic|viminfo}} modality to be available, the version of {{ic|vim}} you installed must have been compiled with the {{ic|+viminfo}} feature.<br />
<br />
Configure what is kept in your {{ic|viminfo}} file, by adding (for example) the following to your {{ic|~/.vimrc}} file:<br />
<br />
set viminfo='10,<100,:100,%,n~/.vim/.viminfo<br />
<br />
where each parameter is preceded by an identifier:<br />
<br />
'q : q, number of edited file remembered<br />
<m : m, number of lines saved for each register<br />
:p : p, number of history cmd lines remembered<br />
% : saves and restore the buffer list<br />
n...: fully qualified path to the viminfo files (note that this is a literal "''n''")<br />
<br />
See the official [https://vimdoc.sourceforge.net/htmldoc/options.html#'viminfo' viminfo documentation] for particulars on how a pre-existing {{ic|viminfo}} file is modified as it is updated with current session information, say from several buffers in the current session you are in the process of exiting.<br />
<br />
==== Session files ====<br />
<br />
Session files can be used to save the state of any number of particular sessions over time. One distinct session file may be used for each session or project of your interest. For that modality to be available, the version of {{ic|vim}} you installed must have been compiled with the {{ic|+mksession}} feature.<br />
<br />
Within a session, {{ic|:mksession[!] [''my_session_name.vim'']}} will write a vim-script to {{ic|''my_session_name.vim''}} in the current directory, or {{ic|Session.vim}} by default if you choose ''not'' to provide a file name. The optional {{ic|!}} will clobber a pre-existing session file with the same name and path.<br />
<br />
A {{ic|vim}} session can be resumed either when starting ''vim'' from terminal:<br />
<br />
$ vim -S [''my_session_name.vim'']<br />
<br />
Or in an already opened session buffer by running the vim command:<br />
<br />
:source ''my_session_name.vim''<br />
<br />
Exactly what is saved and additional details on session files options are extensively covered in the [https://vimdoc.sourceforge.net/htmldoc/usr_21.html#21.4 vim documentation]. Commented examples are found [https://vim.wikia.com/wiki/Go_away_and_come_back here].<br />
<br />
==== Saving cursor position ====<br />
<br />
See [https://vim.wikia.com/wiki/Restore_cursor_to_file_position_in_previous_editing_session Restore cursor to file position in previous editing session] on the Vim wiki.<br />
<br />
=== Replace vi command with Vim ===<br />
<br />
Create an [[alias]] for {{ic|vi}} to {{ic|vim}}.<br />
<br />
Alternatively, if you want to be able to type {{ic|sudo vi}} and get {{ic|vim}}, install {{AUR|vi-vim-symlink}} which will remove {{ic|vi}} and replace it with a symlink to {{ic|vim}}. You could also create this symlink yourself and place it somewhere higher in your path than {{ic|/usr/bin}} to have it take precedence.<br />
<br />
=== DOS/Windows carriage returns ===<br />
<br />
If there is a {{ic|^M}} at the end of each line then this means you are editing a text file which was created in MS-DOS or Windows. This is because in Linux only a single line feed character (LF) used for line break, but in Windows/MS DOS systems they are using a sequence of a carriage return (CR) and a line feed (LF) for the same. And this carriage returns are displayed as {{ic|^M}}.<br />
<br />
To remove all carriage returns from a file do:<br />
<br />
:%s/^M//g<br />
<br />
Note that there {{ic|^}} is a control letter. To enter the control sequence {{ic|^M}} press {{ic|Ctrl+v,Ctrl+m}}.<br />
<br />
Alternatively install the package {{Pkg|dos2unix}} and run {{ic|dos2unix ''file''}} to fix the file.<br />
<br />
{{Note|Another simple way is by changing {{ic|fileformat}} setting. {{ic|1=set ff=unix}} to convert files with DOS/Windows line ending to Unix line ending. To do the reverse, just issue {{ic|1=set ff=dos}} to convert files with Unix line ending to DOS/Windows line ending.}}<br />
<br />
=== Empty space at the bottom of gVim windows ===<br />
<br />
When using a [[window manager]] configured to ignore window size hints, gVim will fill the non-functional area with the GTK theme background color.<br />
<br />
The solution is to adjust how much space gVim reserves at the bottom of the window. Put the following line in {{ic|~/.vimrc}}:<br />
<br />
set guiheadroom=0<br />
<br />
{{Note|If you set it to zero, you will not be able to see the bottom horizontal scrollbar.}}<br />
<br />
=== Vim as a pager ===<br />
<br />
Using scripts Vim can be used as a [[terminal pager]], so that you get various vim features such as color schemes.<br />
Vim comes with the {{ic|/usr/share/vim/vim90/macros/less.sh}} script, for which you can create an [[alias]]. Note that this script does not support any command-line flags mentioned in {{man|1|less|OPTIONS}}.<br />
<br />
Alternatively there is also the {{Pkg|vimpager}} Vim script. To change the default pager, [[export]] the {{ic|PAGER}} environment variable. Note that not all command-line flags are supported; the list of supported flags is [https://github.com/rkitover/vimpager#command-line-options available on GitHub].<br />
<br />
A middle way between a pager and an editor are {{ic|view}}, which is equivalent to {{ic|vim -R}}. Or {{ic|gview}}, which is equivalent to {{ic|gvim -R}}. This will cause the editor to open files in a {{ic|readonly}} mode. Every editor feature that does not involve modifying the files is available as usual. In fact, the {{ic|readonly}} mode can be explicitly overridden, to enable modification as well.<br />
<br />
=== Highlighting search results ===<br />
<br />
In order to highlight the first string that will be matched in a search while typing the search, add the following line to your {{ic|~/.vimrc}}:<br />
<br />
set incsearch<br />
<br />
In order to highlight all strings that will be matched in a search while typing the search, and after the search has been executed, add the following line to your {{ic|~/.vimrc}}:<br />
<br />
set hlsearch<br />
<br />
{{Note|<br />
* Setting {{ic|hlsearch}} will keep all matches highlighted until a further search is made. This behaviour may be undesired, so to temporarily disable the highlighting until the next search, run {{ic|:nohlsearch}}. If you find yourself running this command often, consider binding it to a key.<br />
* This behaviour will also be observed when matching regex during other commands that involve them like {{ic|s}} or {{ic|g}}.<br />
}}<br />
<br />
=== Workaround for XDG Base Directory specification ===<br />
<br />
Since [https://github.com/vim/vim/commit/6a459902592e2a4ba68 7.3.1178] vim will search for {{ic|~/.vim/vimrc}} if {{ic|~/.vimrc}} is not found.<br />
<br />
{{hc|"$XDG_CONFIG_HOME"/vim/vimrc|<nowiki><br />
set runtimepath^=$XDG_CONFIG_HOME/vim<br />
set runtimepath+=$XDG_DATA_HOME/vim<br />
set runtimepath+=$XDG_CONFIG_HOME/vim/after<br />
<br />
set packpath^=$XDG_DATA_HOME/vim,$XDG_CONFIG_HOME/vim<br />
set packpath+=$XDG_CONFIG_HOME/vim/after,$XDG_DATA_HOME/vim/after<br />
<br />
let g:netrw_home = $XDG_DATA_HOME."/vim"<br />
call mkdir($XDG_DATA_HOME."/vim/spell", 'p')<br />
<br />
set backupdir=$XDG_STATE_HOME/vim/backup | call mkdir(&backupdir, 'p')<br />
set directory=$XDG_STATE_HOME/vim/swap | call mkdir(&directory, 'p')<br />
set undodir=$XDG_STATE_HOME/vim/undo | call mkdir(&undodir, 'p')<br />
set viewdir=$XDG_STATE_HOME/vim/view | call mkdir(&viewdir, 'p')<br />
<br />
if !has('nvim') | set viminfofile=$XDG_STATE_HOME/vim/viminfo | endif<br />
</nowiki>}}<br />
<br />
{{hc|~/.profile|2=<br />
export GVIMINIT='let $MYGVIMRC="$XDG_CONFIG_HOME/vim/gvimrc" {{!}} source $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC="$XDG_CONFIG_HOME/vim/vimrc" {{!}} source $MYVIMRC'<br />
}}<br />
<br />
{{ic|[G]VIMINIT}} environment variable will also affect Neovim. If separate configs for Vim and Neovim are desired then the following will be a better choice:<br />
export GVIMINIT='let $MYGVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/gvimrc" : "$XDG_CONFIG_HOME/nvim/init.gvim" | so $MYGVIMRC'<br />
export VIMINIT='let $MYVIMRC = !has("nvim") ? "$XDG_CONFIG_HOME/vim/vimrc" : "$XDG_CONFIG_HOME/nvim/init.vim" | so $MYVIMRC'<br />
<br />
* https://jorengarenar.github.io/blog/vim-xdg<br />
* https://tlvince.com/vim-respect-xdg<br />
<br />
== Plugins ==<br />
<br />
Adding plugins to Vim can increase your productivity by extending Vim's features. Plugins can alter Vim's UI, add new commands, enable code completion support, integrate other programs and utilities with Vim, add support for additional languages and more.<br />
<br />
{{Tip|For a list of popular plugins, see [https://vimawesome.com/ Vim Awesome].}}<br />
<br />
=== Installation ===<br />
<br />
==== Using the built-in package manager ====<br />
<br />
Vim 8 added the possibility to load third-party plugins natively. This functionality can be used by storing third-party packages in the {{ic|~/.vim/pack}} folder. The structure of this folder differs slightly from that of typical plugin managers which will usually have a single directory per plugin. What follows is a typical installation procedure and directory structure (using [https://github.com/tpope/vim-surround Tim Pope's vim-surround plugin] as an example):<br />
<br />
$ mkdir -p ~/.vim/pack/tpope/start<br />
<br />
It is important to note that {{ic|~/.vim/pack/tpope}} is a ''package directory'' which is loosely defined as directory containing one or more plugins in the [https://vimhelp.org/repeat.txt.html#packages Vim documentation]. Plugin repositories should not be downloaded to this directory though. The name of the package directory is also arbitrary. You can choose to keep all your plugins in a single package directory or, as in our example, use the author's GitHub name, {{ic|tpope}}.<br />
<br />
The package directory can contain the following subfolders:<br />
<br />
* {{ic|start}} - plugins from this subfolder will be loaded automatically when Vim starts. This is the most frequently used location.<br />
* {{ic|opt}} - plugins from this subfolder can be loaded on-demand by issuing {{ic|:packadd}} command inside Vim.<br />
<br />
Now change into the {{ic|start}} folder and checkout the plugin repository:<br />
<br />
$ cd ~/.vim/pack/tpope/start<br />
$ git clone https://tpope.io/vim/surround.git<br />
<br />
This creates an additional subfolder, {{ic|~/.vim/pack/tpope/start/surround}}, where the plugin files are placed.<br />
<br />
Next, update the help index if the plugin contains help files:<br />
<br />
$ vim -u NONE -c "helptags surround/doc" -c q<br />
<br />
The plugin will now be loaded automatically when starting Vim. No changes to {{ic|~/.vimrc}} are required, barring plugin-specific options.<br />
<br />
==== Using a plugin manager ====<br />
<br />
A plugin manager is a plugin that installs, manages and updates Vim plugins. This can be useful if you are also using Vim on platforms other than Arch Linux and want a consistent method of updating plugins.<br />
<br />
* [https://github.com/junegunn/vim-plug Vim-plug] is a minimalist Vim plugin manager with many features like on-demand plugin loading and parallel updating, available as {{AUR|vim-plug}} or {{AUR|vim-plug-git}}.<br />
* [https://github.com/gmarik/Vundle.vim Vundle] is available as {{AUR|vundle}} or {{AUR|vundle-git}}.<br />
* [https://github.com/tpope/vim-pathogen pathogen.vim] is a simple plugin for managing Vim's runtimepath, available as {{AUR|vim-pathogen}} or {{AUR|vim-pathogen-git}}.<br />
* [https://github.com/Shougo/dein.vim Dein.vim] is a plugin manager replacing [https://github.com/Shougo/neobundle.vim NeoBundle], available as {{AUR|vim-dein}} or {{AUR|vim-dein-git}}.<br />
<br />
==== From Arch repositories ====<br />
<br />
The {{Grp|vim-plugins}} group provides various plugins. Use {{ic|pacman -Sg vim-plugins}} command to list available packages which you can then [[install]] with pacman.<br />
<br />
=== Notable plugins ===<br />
<br />
==== cscope ====<br />
<br />
[https://cscope.sourceforge.net/ Cscope] is a tool for browsing a project. By navigating to a word/symbol/function and calling cscope (usually with shortcut keys) it can find: functions calling the function, the function definition, and more.<br />
<br />
[[Install]] the {{Pkg|cscope}} package.<br />
<br />
Copy the cscope default file where it will be automatically read by Vim:<br />
<br />
mkdir -p ~/.vim/plugin<br />
wget -P ~/.vim/plugin https://cscope.sourceforge.net/cscope_maps.vim<br />
<br />
{{Note|You will probably need to uncomment these lines in {{ic|~/.vim/plugin/cscope_maps.vim}} in order to enable cscope shortcuts in Vim 7.x:<br />
{{bc|1=<br />
set timeoutlen=4000<br />
set ttimeout<br />
}}}}<br />
<br />
Create a file which contains the list of files you wish cscope to index (cscope can handle many languages but this example finds ''.c'', ''.cpp'' and ''.h'' files, specific for C/C++ project):<br />
<br />
$ cd ''/path/to/project/dir''<br />
$ find . -type f -print | grep -E '\.(c(pp)?|h)$' > cscope.files<br />
<br />
Create database files that cscope will read:<br />
<br />
$ cscope -bq<br />
<br />
{{Note|You must browse your project files from this location or set and export the {{ic|$CSCOPE_DB}} variable, pointing it to the {{ic|cscope.out}} file.}}<br />
<br />
Default keyboard shortcuts:<br />
<br />
Ctrl-\ and<br />
c: Find functions calling this function<br />
d: Find functions called by this function<br />
e: Find this egrep pattern<br />
f: Find this file<br />
g: Find this definition<br />
i: Find files #including this file<br />
s: Find this C symbol<br />
t: Find assignments to<br />
<br />
Feel free to change the shortcuts.<br />
<br />
#Maps ctrl-c to find functions calling the function<br />
nnoremap <C-c> :cs find c <C-R>=expand("<cword>")<CR><CR><br />
<br />
==== Taglist ====<br />
<br />
[https://vim-taglist.sourceforge.net/ Taglist] provides an overview of the structure of source code files and allows you to efficiently browse through source code files in different programming languages.<br />
<br />
[[Install]] the {{AUR|vim-taglist}} package.<br />
<br />
Useful options to be put in {{ic|~/.vimrc}}:<br />
<br />
let Tlist_Compact_Format = 1<br />
let Tlist_GainFocus_On_ToggleOpen = 1<br />
let Tlist_Close_On_Select = 1<br />
nnoremap <C-l> :TlistToggle<CR><br />
<br />
== Troubleshooting ==<br />
<br />
=== gVim is slow ===<br />
<br />
Vim's GTK 3 GUI may be slower than the GTK 2 version (see {{Bug|51366}}). {{AUR|gvim-gtk2}} can be installed as a workaround.<br />
<br />
== See also ==<br />
<br />
=== Official ===<br />
<br />
* [https://www.vim.org/ Homepage]<br />
* [https://vimdoc.sourceforge.net/ Documentation]<br />
* [https://vim.wikia.com Vim Wiki]<br />
* [https://www.vim.org/scripts/ Vim Scripts]<br />
<br />
=== Tutorials ===<br />
<br />
* [https://danielmiessler.com/study/vim/ vim Tutorial and Primer]<br />
* [https://web.archive.org/web/20140822135551/http://usalug.com/vi.html vi Tutorial and Reference Guide]<br />
* [http://www.viemu.com/a_vi_vim_graphical_cheat_sheet_tutorial.html Graphical vi-Vim Cheat Sheet and Tutorial]<br />
* [https://archive.today/2012.12.20-221858/http://blog.interlinked.org/tutorials/vim_tutorial.html Vim Introduction and Tutorial]<br />
* [https://www.openvim.com/ Open Vim] — collection of Vim learning tools<br />
* [https://yannesposito.com/Scratch/en/blog/Learn-Vim-Progressively/ Learn Vim Progressively]<br />
* [https://benmccormick.org/learning-vim-in-2014/ Learning Vim in 2014]<br />
* [https://www.moolenaar.net/habits.html Seven habits of effective text editing]<br />
* [https://bencrowder.net/files/vim-fu/ Basic Vim Tips]<br />
<br />
==== Videos ====<br />
<br />
* [http://vimcasts.org/ Vimcasts] — screencasts in ''.ogg'' format.<br />
* [http://derekwyatt.org/vim/tutorials/ Vim Tutorial Videos] — covering the basics up to advanced topics.<br />
<br />
==== Cheat sheets ====<br />
<br />
* https://devhints.io/vim<br />
* https://vim.rtorr.com/ - A mobile friendly Vim cheat sheet - [https://github.com/rtorr/vim-cheat-sheet Sources]<br />
<br />
==== Games ====<br />
<br />
* [https://vim-adventures.com/ Vim Adventures]<br />
* [https://vimgolf.com/ VimGolf]<br />
<br />
=== Configuration ===<br />
<br />
* [https://web.archive.org/web/20131020125020/http://nion.modprobe.de/setup/vimrc nion's]<br />
* [https://github.com/amix/vimrc A detailed configuration from Amir Salihefendic]<br />
* [https://web.archive.org/web/20131004071740/http://www.jukie.net/~bart/conf/vimrc Bart Trojanowski]<br />
* [https://github.com/spf13/spf13-vim Steve Francia's Vim Distribution]<br />
* [https://vimawesome.com/ Vim Awesome] - Vim Plugins<br />
* [https://github.com/W4RH4WK/dotVim W4RH4WK's Vim configuration]<br />
* [https://www.askapache.com/linux/fast-vimrc/ Fast vimrc/colorscheme from askapache]<br />
* [https://gist.github.com/anonymous/c966c0757f62b451bffa Basic vimrc]<br />
<br />
==== Colors ====<br />
<br />
* [http://bytefluent.com/vivify/ Vivify]<br />
* [https://linuxtidbits.wordpress.com/2014/10/14/vim-customize-installed-colorschemes/ Vim colorscheme customization]</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=794859CURL2023-12-20T22:34:37Z<p>Regid: /* config file */ A capital letter at the beginning of a sentence.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl --output ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl --remote-name ''URL''<br />
<br />
Similarly, you can use {{ic|-J/--remote-header-name}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O/--remote-name}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl --data ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl --data @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl --data ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU, curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl --progress-bar ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. You can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=794858CURL2023-12-20T22:32:49Z<p>Regid: /* ProgressBar */ Following Help:Style#Spelling to prefer the long option instead of its single-character counterpart.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl --output ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl --remote-name ''URL''<br />
<br />
Similarly, you can use {{ic|-J/--remote-header-name}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O/--remote-name}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl --data ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl --data @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl --data ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU, curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl --progress-bar ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. you can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=794857CURL2023-12-20T22:30:13Z<p>Regid: /* Downloading */ Following Help:Style#Spelling to prefer long options instead of their single-character counterpart.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl --output ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl --remote-name ''URL''<br />
<br />
Similarly, you can use {{ic|-J/--remote-header-name}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O/--remote-name}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl --data ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl --data @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl --data ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU, curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl '-#' ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. you can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=794856CURL2023-12-20T22:26:35Z<p>Regid: /* HTTP POST */ Following Help:Style#Spelling to prefer the long option instead of its single-character counterpart.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl -o ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl -O ''URL''<br />
<br />
Similarly, you can use {{ic|-J}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl --data ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl --data @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl --data ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU, curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl '-#' ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. you can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=794855CURL2023-12-20T22:22:07Z<p>Regid: /* Compression */ missing white space ' '</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl -o ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl -O ''URL''<br />
<br />
Similarly, you can use {{ic|-J}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl -d ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl -d @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl -d ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU, curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl '-#' ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. you can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=CURL&diff=794854CURL2023-12-20T22:21:36Z<p>Regid: /* Following redirects */ Following Help:Style#Spelling to prefer the long option instead of their single-character counterpart.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Download utilities]]<br />
[[ja:CURL]]<br />
[[ru:CURL]]<br />
[https://curl.haxx.se/ cURL] is a command line tool and library for transferring data with URLs. The command supports a number of different protocols, including [[HTTP]], HTTPS, [[FTP]], [[SCP]], and SFTP. It is also designed to work without user interaction, like in scripts.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|curl}} package.<br />
<br />
== Usage ==<br />
<br />
=== Downloading ===<br />
<br />
A common use case for cURL is to download the resource to a specified file:<br />
<br />
$ curl -o ''file name'' ''URL''<br />
<br />
If the URL contains the file name, you can save the resource directly to a file of that name:<br />
<br />
$ curl -O ''URL''<br />
<br />
Similarly, you can use {{ic|-J}} to accept a hint from an HTTP server (from the {{ic|Content-Disposition}} header) for what the file should be named. If combined with {{ic|-O}}, curl will use the file name specified by the URL if the HTTP server does not return a file name hint in its response.<br />
<br />
Alternatively you can print the resource to stdout by omitting the output options:<br />
<br />
$ curl ''URL''<br />
<br />
=== HTTP POST ===<br />
<br />
You can use cURL to make HTTP POST requests:<br />
<br />
$ curl -d ''<nowiki>'request body'</nowiki>'' ''URL''<br />
<br />
If the request body cannot fit on the command line, cURL can read it from a file:<br />
<br />
$ curl -d @''file name'' ''URL''<br />
<br />
Sometimes, you may need to specify a custom value for the {{ic|Content-Type}} header (cURL's default is {{ic|application/x-www-form-urlencoded}}). You can do this with {{ic|-H}}. For example, if you wanted to make a POST request with a JSON body:<br />
<br />
$ curl -d ''<nowiki>'json body'</nowiki>'' -H 'Content-Type: application/json' ''URL''<br />
note that curl also has a option to write post data in json and change those headers automatically: {{ic|--json}}:<br />
$ curl --json '{"key":"value"}' ''URL''<br />
== Tips and tricks ==<br />
<br />
=== Following redirects ===<br />
<br />
To follow redirects (e.g. an HTTP to HTTPS redirect):<br />
<br />
$ curl --location ''URL''<br />
<br />
=== Show download errors ===<br />
<br />
By default curl would ignore errors (e.g. when downloading to a file, if there is a error curl would not notify you, and the file would be created empty) so use {{ic|--fail}} to make it show a message on error:<br />
<br />
$ curl --fail ''URL''<br />
<br />
=== Compression ===<br />
<br />
If you want to transfer the data [https://everything.curl.dev/usingcurl/downloads/compression compressed], (e.g. in situations where bandwidth is more limited than CPU,curl would download the data compressed then uncompressed it after the downlod):<br />
<br />
$ curl --compressed ''URL''<br />
=== ProgressBar ===<br />
curl has option to a normal ProgressBar when it download files (e.g. {{ic|[##### ] 80%}} )<br />
$ curl '-#' ''URL''<br />
<br />
=== Globbing ===<br />
<br />
You can also use [https://everything.curl.dev/cmdline/globbing globing] in curl:<br />
<br />
$ curl "example.com/images/[1-9].png"<br />
$ curl "example.com/{first_page,second_page,third_page}"<br />
<br />
== config file ==<br />
curl also search for a [https://everything.curl.dev/cmdline/configfile config file] called {{ic|.curlrc}} in home directory and in {{ic|$XDG_CONFIG_HOME}}. you can just put the command line argument you want to use with curl by default, for example :<br />
{{hc|$HOME/.curlrc|2=<br />
# this is a comment, the next line would be the option for progressbar:<br />
-#<br />
# to make curl always compress:<br />
--compressed<br />
# or just<br />
compressed<br />
}}<br />
<br />
== See also ==<br />
<br />
* [[Wikipedia:cURL]]<br />
* [https://everything.curl.dev/ Everything curl] - Extensive guide to using cURL<br />
* {{man|1|curl}}</div>Regidhttps://wiki.archlinux.org/index.php?title=Extended_attributes&diff=794815Extended attributes2023-12-20T07:55:00Z<p>Regid: /* Software */ Is that slightly clearer?</p>
<hr />
<div>[[Category:File systems]]<br />
[[ja:拡張属性]]<br />
[[ru:Extended attributes]]<br />
{{Related articles start}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Capabilities}}<br />
{{Related articles end}}<br />
<br />
From {{man|7|xattr}}: "Extended attributes are name:value pairs associated permanently with files and directories". There are four extended attribute classes: security, system, trusted and user.<br />
<br />
{{Warning|By default, extended attributes are not preserved by [[cp]], [[rsync]], and other similar programs, see [[#Preserving extended attributes]].}}<br />
<br />
Extended attributes are also used to set [[Capabilities]].<br />
<br />
== User extended attributes ==<br />
<br />
User extended attributes can be used to store arbitrary information about a file. To create one:<br />
<br />
$ setfattr --name=user.checksum --value="3baf9ebce4c664ca8d9e5f6314fb47fb" file.txt<br />
<br />
Use getfattr to display extended attributes:<br />
<br />
{{hc|1= $ getfattr --encoding=text --dump file.txt|2=<br />
# file: file.txt<br />
user.checksum="3baf9ebce4c664ca8d9e5f6314fb47fb"<br />
}}<br />
<br />
To remove an extended attribute:<br />
<br />
$ setfattr --remove=user.checksum file.txt<br />
<br />
To find files with certain extended attributes use {{AUR|rawhide}}:<br />
<br />
$ rh ''/path/to/dir'' '"''XATTR_REGEX''".reea'<br />
<br />
Some other user extended attributes include:<br />
<br />
* {{ic|user.mime_type}}: helps programs know mimetype and set it with less guesswork.<br />
* {{ic|user.charset}}: used by the Apache httpd module [http://0pointer.de/lennart/projects/mod_mime_xattr mod_mime_xattr].<br />
* {{ic|user.creator}}: The name of the application that created the file.<br />
<br />
XDG also proposes a set of standardized extended attributes to be used by programs:<br />
<br />
* {{ic|user.xdg.comment}}: supported by Dolphin and other file managers.<br />
* {{ic|user.xdg.origin.url}}: for files downloaded from a url.<br />
* {{ic|user.xdg.robots.index}}: "true" if a file is included in indexing, "false" otherwise<br />
* {{ic|user.xdg.robots.backup}}: "true" if a file is included in backup, "false" otherwise<br />
* {{ic|user.xdg.language}}<br />
* {{ic|user.xdg.creator}}<br />
* {{ic|user.xdg.publisher}}<br />
* {{ic|user.xdg.origin.email.subject}}<br />
* {{ic|user.xdg.origin.email.from}}<br />
* {{ic|user.xdg.origin.email.message-id}}<br />
<br />
{{ic|user.xdg.tags}} is not part of the official standard, but it has become a "de facto" standard as several popular programs have implemented support for it (see [[#Software]]). It is implemented as a [[w:Comma-separated values|CSV]] list of user-specified tags for each file.<br />
<br />
== Preserving extended attributes ==<br />
<br />
{| class=wikitable<br />
! Command || Preserves by default?/Required flag<br />
|-<br />
| {{ic|cp}} || {{ic|--archive}}/{{ic|1=--preserve=all}}/{{ic|1=--preserve=xattr}}<br />
|-<br />
| {{ic|mv}} || {{Yes}}<sup>1</sup><br />
|-<br />
| {{ic|tar}} || {{ic|--xattrs}} for creation and {{ic|1=--xattrs-include='*'}} for extraction<br />
|-<br />
| {{ic|bsdtar}} || {{ic|-p}} for extraction<br />
|-<br />
| [[rsync]] || {{ic|-X, --xattrs}}<br />
|-<br />
| {{pkg|cpio}} || {{No}}<br />
|-<br />
| {{pkg|gzip}} || {{No}}<br />
|-<br />
| {{pkg|pax}} || {{No}}<br />
|-<br />
| [[syncthing]] || by enabling [https://docs.syncthing.net/advanced/folder-sync-xattrs syncXattrs]<br />
|}<br />
<br />
# mv silently discards extended attributes when the target file system does not support them.<br />
<br />
To preserve extended attributes with [[text editor]]s you need to configure them to truncate files on saving instead of using {{man|2|rename}}. [https://unix.stackexchange.com/questions/45407]<br />
<br />
Just like you should do for any other data you do not want to lose, you should make regular [[System maintenance#Backup|backups]] of your extended attributes. To make a full backup of the extended attributes of all files in the current directory (recursively):<br />
<br />
$ getfattr --dump --recursive . > backup.txt<br />
<br />
To restore a backup:<br />
$ setfattr --restore=backup.txt<br />
<br />
== Support ==<br />
<br />
=== File systems ===<br />
<br />
All major Linux [[file systems]] including [[Ext4]], [[Btrfs]], [[ZFS]], and [[XFS]] support extended attributes. The kernel allows to have extended attribute names of up to 255 bytes and values of up to 64 KiB, but [[Ext4]] and [[Btrfs]] might impose smaller limits, requiring extended attributes to be within a "filesystem block".<br />
<br />
[[NTFS]] uses Alternative Data Streams to store user. The mount option {{ic|user_xattr}} or {{ic|streams_interface{{=}}xattr}} should be used by default. However, it might not be supported if mount option {{ic|streams_interface{{=}}windows}} is used. {{pkg|ntfs-3g}} supports mapping Alternative Data Streams to extended attributes in FUSE.<br />
<br />
[[NFS]] supports extended attributes [https://www.phoronix.com/news/Linux-5.9-NFS-Server-User-Xattr since Linux 5.9].<br />
<br />
=== Software ===<br />
<br />
{| class="wikitable"<br />
! Application<br />
! Supported extended attributes<br />
! Notes<br />
|-<br />
| [[baloo]]<br />
| {{bc|<br />
user.xdg.tags<br />
user.baloo.rating<br />
}}<br />
|<br />
|-<br />
| {{pkg|caja}}<br />
| {{Yes}}<br />
| Supported by caja-xattr-tags and caja.eiciel extensions.<br />
|-<br />
| [[Chromium]]<br />
| {{No|1=https://chromium.googlesource.com/chromium/src/+/a9b4fb70b4318b220deee0da7b1693d16b8ed071}}<br />
| Used to support referrer and url, but was disabled due to privacy and security concerns. See also [https://cve.circl.lu/cve/CVE-2018-20483 CVE-2018-20483].<br />
|-<br />
| {{AUR|brave}}<br />
| {{No|1=https://github.com/brave/brave-browser/issues/2766}}<br />
|<br />
|-<br />
| [[CURL]]<br />
| {{bc|<br />
user.xdg.origin.url<br />
user.xdg.referrer.url<br />
}}<br />
| Enabled with {{ic|--xattrs}} flag.<br />
|-<br />
| [[Dolphin]]<br />
| {{bc|<br />
user.baloo.rating<br />
user.xdg.comment<br />
user.xdg.tags<br />
}}<br />
| Dolphin provides comprehensive support for file tagging, including the ability to add tags to files through the context menu, and support for searching by file tags. Tags are stored as CSV in the {{ic|user.xdg.tags}} attribute. See also [[Dolphin#File tagging]].<br />
<br />
[https://bugs.kde.org/show_bug.cgi?id=473808]<br />
|-<br />
| [[Dropbox]]<br />
| {{ic|user.com.dropbox.attributes}}<br />
|<br />
|-<br />
| [[emacs|emacs-vm]]<br />
| {{No}}<br />
| Resets mbox xattrs.<br />
|-<br />
| [[Epiphany]]<br />
| {{No|1=https://gitlab.gnome.org/GNOME/epiphany/-/issues/2165}}<br />
|<br />
|-<br />
| [[Exiftool]]<br />
| {{No|1=https://exiftool.org/forum/index.php?topic=12762}}<br />
|<br />
|-<br />
| {{pkg|fd}}<br />
| {{No|1=https://github.com/sharkdp/fd/issues/830}}<br />
|<br />
|-<br />
| {{pkg|findutils}}<br />
| {{No|1=https://savannah.gnu.org/bugs/?64605}}<br />
|<br />
|-<br />
| [[Firefox]]<br />
| {{No|1=https://bugzilla.mozilla.org/show_bug.cgi?id=665531}}<br />
|<br />
|-<br />
| {{AUR|gallery-dl}}<br />
| {{No|1=https://github.com/mikf/gallery-dl/issues/4472}}<br />
|<br />
|-<br />
| [[Gwenview]]<br />
| {{ic|user.xdg.tags}}<br />
|<br />
|-<br />
| {{pkg|kfind}}<br />
| {{No|1=https://bugs.kde.org/show_bug.cgi?id=473864}}<br />
|<br />
|-<br />
| {{pkg|konqueror}}<br />
| {{No|1=https://bugs.kde.org/show_bug.cgi?id=473809}}<br />
|<br />
|-<br />
| kio<br />
| [https://bugs.kde.org/show_bug.cgi?id=116617]<br />
|<br />
|-<br />
| [[Nautilus]]<br />
| {{No|1=https://discourse.gnome.org/t/16892}}<br />
| Full extended file attributes support can be added by the Nautilus extension from {{aur|Eiciel}}. Which is well-maintained, working well, and coherent with [[Gnome]] interface. Based on [[special:diff/794451|exhausted talk page comment]].<br />
|-<br />
| {{pkg|recoll}}<br />
| {{ic|user.xdg.tags}}<br />
|<br />
|-<br />
| {{AUR|tagspaces}}<br />
| {{No|1=https://trello.com/c/iapsXZZe/64-option-to-store-tags-in-file-using-extended-attributes-xattr}}<br />
|<br />
|-<br />
| {{AUR|tmsu}}<br />
| {{No|1=https://github.com/oniony/TMSU/issues/10}}<br />
|<br />
|-<br />
| [[Thunar]]<br />
| {{No|1=https://gitlab.xfce.org/xfce/thunar/-/issues/1195}}<br />
|<br />
|-<br />
| {{AUR|youtube-dl}}, [[yt-dlp]]<br />
| {{bc|<br />
user.xdg.referrer.url<br />
user.dublincore.title<br />
user.dublincore.date<br />
user.dublincore.description<br />
user.dublincore.contributor<br />
user.dublincore.format<br />
}}<br />
| Enabled with {{ic|--xattrs}} flag.<br />
|-<br />
| [[Wget]]<br />
| {{bc|<br />
user.xdg.origin.url<br />
user.xdg.referrer.url<br />
}}<br />
| Enabled with {{ic|--xattrs}} flag.<br />
|-<br />
| [[w:webkit|webkit]]<br />
| {{No|1=https://bugs.webkit.org/show_bug.cgi?id=260778}}<br />
|<br />
|}<br />
<br />
== Other tagging systems ==<br />
<br />
It might not be possible to use extended attributes due to lack of support of either the file system or software. For this reason, many media formats store metadata included in the file format that can be viewed using programs like [[Exiftool]] or more specified ones like {{AUR|id3}} for audio.<br />
<br />
* For all files: [[Exiftool]]<br />
* For audio: [[List of applications/Multimedia#Audio tag editors|Audio tag editors]]<br />
* For video: {{man|1|ffprobe}} from [[ffmpeg]]<br />
<br />
=== gvfs ===<br />
<br />
Another filesystem-independent workaround is Gnome virtual filesystem: {{pkg|gvfs}} which is used to store metadata (gvfsd-metadata). For example, Firefox [https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/downloads/DownloadPlatform.cpp stores metadata] this way and can be viewed with:<br />
<br />
$ gio info --attributes=metadata:: ''downloaded.html''<br />
<br />
Other programs that use this approach include:<br />
* [[Thunar]]: to save file color highlights.<br />
<br />
== See also ==<br />
<br />
* [https://www.freedesktop.org/wiki/CommonExtendedAttributes XDG guidelines for extended attributes]<br />
* [[wikipedia:Extended file attributes#Linux]]<br />
* [https://www.lesbonscomptes.com/pages/extattrs.html Extended attributes: the good, the not so good, the bad.]</div>Regidhttps://wiki.archlinux.org/index.php?title=Extended_attributes&diff=794814Extended attributes2023-12-20T07:53:50Z<p>Regid: /* Software */ As far as I tried, the curly brackets form {{special:diff}} template that does not allow to specify a custom tag. Since the information is solely based on a single user report, I do believe there should be a reference to the source.</p>
<hr />
<div>[[Category:File systems]]<br />
[[ja:拡張属性]]<br />
[[ru:Extended attributes]]<br />
{{Related articles start}}<br />
{{Related|File permissions and attributes}}<br />
{{Related|Capabilities}}<br />
{{Related articles end}}<br />
<br />
From {{man|7|xattr}}: "Extended attributes are name:value pairs associated permanently with files and directories". There are four extended attribute classes: security, system, trusted and user.<br />
<br />
{{Warning|By default, extended attributes are not preserved by [[cp]], [[rsync]], and other similar programs, see [[#Preserving extended attributes]].}}<br />
<br />
Extended attributes are also used to set [[Capabilities]].<br />
<br />
== User extended attributes ==<br />
<br />
User extended attributes can be used to store arbitrary information about a file. To create one:<br />
<br />
$ setfattr --name=user.checksum --value="3baf9ebce4c664ca8d9e5f6314fb47fb" file.txt<br />
<br />
Use getfattr to display extended attributes:<br />
<br />
{{hc|1= $ getfattr --encoding=text --dump file.txt|2=<br />
# file: file.txt<br />
user.checksum="3baf9ebce4c664ca8d9e5f6314fb47fb"<br />
}}<br />
<br />
To remove an extended attribute:<br />
<br />
$ setfattr --remove=user.checksum file.txt<br />
<br />
To find files with certain extended attributes use {{AUR|rawhide}}:<br />
<br />
$ rh ''/path/to/dir'' '"''XATTR_REGEX''".reea'<br />
<br />
Some other user extended attributes include:<br />
<br />
* {{ic|user.mime_type}}: helps programs know mimetype and set it with less guesswork.<br />
* {{ic|user.charset}}: used by the Apache httpd module [http://0pointer.de/lennart/projects/mod_mime_xattr mod_mime_xattr].<br />
* {{ic|user.creator}}: The name of the application that created the file.<br />
<br />
XDG also proposes a set of standardized extended attributes to be used by programs:<br />
<br />
* {{ic|user.xdg.comment}}: supported by Dolphin and other file managers.<br />
* {{ic|user.xdg.origin.url}}: for files downloaded from a url.<br />
* {{ic|user.xdg.robots.index}}: "true" if a file is included in indexing, "false" otherwise<br />
* {{ic|user.xdg.robots.backup}}: "true" if a file is included in backup, "false" otherwise<br />
* {{ic|user.xdg.language}}<br />
* {{ic|user.xdg.creator}}<br />
* {{ic|user.xdg.publisher}}<br />
* {{ic|user.xdg.origin.email.subject}}<br />
* {{ic|user.xdg.origin.email.from}}<br />
* {{ic|user.xdg.origin.email.message-id}}<br />
<br />
{{ic|user.xdg.tags}} is not part of the official standard, but it has become a "de facto" standard as several popular programs have implemented support for it (see [[#Software]]). It is implemented as a [[w:Comma-separated values|CSV]] list of user-specified tags for each file.<br />
<br />
== Preserving extended attributes ==<br />
<br />
{| class=wikitable<br />
! Command || Preserves by default?/Required flag<br />
|-<br />
| {{ic|cp}} || {{ic|--archive}}/{{ic|1=--preserve=all}}/{{ic|1=--preserve=xattr}}<br />
|-<br />
| {{ic|mv}} || {{Yes}}<sup>1</sup><br />
|-<br />
| {{ic|tar}} || {{ic|--xattrs}} for creation and {{ic|1=--xattrs-include='*'}} for extraction<br />
|-<br />
| {{ic|bsdtar}} || {{ic|-p}} for extraction<br />
|-<br />
| [[rsync]] || {{ic|-X, --xattrs}}<br />
|-<br />
| {{pkg|cpio}} || {{No}}<br />
|-<br />
| {{pkg|gzip}} || {{No}}<br />
|-<br />
| {{pkg|pax}} || {{No}}<br />
|-<br />
| [[syncthing]] || by enabling [https://docs.syncthing.net/advanced/folder-sync-xattrs syncXattrs]<br />
|}<br />
<br />
# mv silently discards extended attributes when the target file system does not support them.<br />
<br />
To preserve extended attributes with [[text editor]]s you need to configure them to truncate files on saving instead of using {{man|2|rename}}. [https://unix.stackexchange.com/questions/45407]<br />
<br />
Just like you should do for any other data you do not want to lose, you should make regular [[System maintenance#Backup|backups]] of your extended attributes. To make a full backup of the extended attributes of all files in the current directory (recursively):<br />
<br />
$ getfattr --dump --recursive . > backup.txt<br />
<br />
To restore a backup:<br />
$ setfattr --restore=backup.txt<br />
<br />
== Support ==<br />
<br />
=== File systems ===<br />
<br />
All major Linux [[file systems]] including [[Ext4]], [[Btrfs]], [[ZFS]], and [[XFS]] support extended attributes. The kernel allows to have extended attribute names of up to 255 bytes and values of up to 64 KiB, but [[Ext4]] and [[Btrfs]] might impose smaller limits, requiring extended attributes to be within a "filesystem block".<br />
<br />
[[NTFS]] uses Alternative Data Streams to store user. The mount option {{ic|user_xattr}} or {{ic|streams_interface{{=}}xattr}} should be used by default. However, it might not be supported if mount option {{ic|streams_interface{{=}}windows}} is used. {{pkg|ntfs-3g}} supports mapping Alternative Data Streams to extended attributes in FUSE.<br />
<br />
[[NFS]] supports extended attributes [https://www.phoronix.com/news/Linux-5.9-NFS-Server-User-Xattr since Linux 5.9].<br />
<br />
=== Software ===<br />
<br />
{| class="wikitable"<br />
! Application<br />
! Supported extended attributes<br />
! Notes<br />
|-<br />
| [[baloo]]<br />
| {{bc|<br />
user.xdg.tags<br />
user.baloo.rating<br />
}}<br />
|<br />
|-<br />
| {{pkg|caja}}<br />
| {{Yes}}<br />
| Supported by caja-xattr-tags and caja.eiciel extensions.<br />
|-<br />
| [[Chromium]]<br />
| {{No|1=https://chromium.googlesource.com/chromium/src/+/a9b4fb70b4318b220deee0da7b1693d16b8ed071}}<br />
| Used to support referrer and url, but was disabled due to privacy and security concerns. See also [https://cve.circl.lu/cve/CVE-2018-20483 CVE-2018-20483].<br />
|-<br />
| {{AUR|brave}}<br />
| {{No|1=https://github.com/brave/brave-browser/issues/2766}}<br />
|<br />
|-<br />
| [[CURL]]<br />
| {{bc|<br />
user.xdg.origin.url<br />
user.xdg.referrer.url<br />
}}<br />
| Enabled with {{ic|--xattrs}} flag.<br />
|-<br />
| [[Dolphin]]<br />
| {{bc|<br />
user.baloo.rating<br />
user.xdg.comment<br />
user.xdg.tags<br />
}}<br />
| Dolphin provides comprehensive support for file tagging, including the ability to add tags to files through the context menu, and support for searching by file tags. Tags are stored as CSV in the {{ic|user.xdg.tags}} attribute. See also [[Dolphin#File tagging]].<br />
<br />
[https://bugs.kde.org/show_bug.cgi?id=473808]<br />
|-<br />
| [[Dropbox]]<br />
| {{ic|user.com.dropbox.attributes}}<br />
|<br />
|-<br />
| [[emacs|emacs-vm]]<br />
| {{No}}<br />
| Resets mbox xattrs.<br />
|-<br />
| [[Epiphany]]<br />
| {{No|1=https://gitlab.gnome.org/GNOME/epiphany/-/issues/2165}}<br />
|<br />
|-<br />
| [[Exiftool]]<br />
| {{No|1=https://exiftool.org/forum/index.php?topic=12762}}<br />
|<br />
|-<br />
| {{pkg|fd}}<br />
| {{No|1=https://github.com/sharkdp/fd/issues/830}}<br />
|<br />
|-<br />
| {{pkg|findutils}}<br />
| {{No|1=https://savannah.gnu.org/bugs/?64605}}<br />
|<br />
|-<br />
| [[Firefox]]<br />
| {{No|1=https://bugzilla.mozilla.org/show_bug.cgi?id=665531}}<br />
|<br />
|-<br />
| {{AUR|gallery-dl}}<br />
| {{No|1=https://github.com/mikf/gallery-dl/issues/4472}}<br />
|<br />
|-<br />
| [[Gwenview]]<br />
| {{ic|user.xdg.tags}}<br />
|<br />
|-<br />
| {{pkg|kfind}}<br />
| {{No|1=https://bugs.kde.org/show_bug.cgi?id=473864}}<br />
|<br />
|-<br />
| {{pkg|konqueror}}<br />
| {{No|1=https://bugs.kde.org/show_bug.cgi?id=473809}}<br />
|<br />
|-<br />
| kio<br />
| [https://bugs.kde.org/show_bug.cgi?id=116617]<br />
|<br />
|-<br />
| [[Nautilus]]<br />
| {{No|1=https://discourse.gnome.org/t/16892}}<br />
| Full extended file attributes support can be added by the Nautilus extension from {{aur|Eiciel}}. Which is well-maintained, working well, and coherent with [[Gnome]] interface. Based on [[special:diff/794451|exhausted talk comment]].<br />
|-<br />
| {{pkg|recoll}}<br />
| {{ic|user.xdg.tags}}<br />
|<br />
|-<br />
| {{AUR|tagspaces}}<br />
| {{No|1=https://trello.com/c/iapsXZZe/64-option-to-store-tags-in-file-using-extended-attributes-xattr}}<br />
|<br />
|-<br />
| {{AUR|tmsu}}<br />
| {{No|1=https://github.com/oniony/TMSU/issues/10}}<br />
|<br />
|-<br />
| [[Thunar]]<br />
| {{No|1=https://gitlab.xfce.org/xfce/thunar/-/issues/1195}}<br />
|<br />
|-<br />
| {{AUR|youtube-dl}}, [[yt-dlp]]<br />
| {{bc|<br />
user.xdg.referrer.url<br />
user.dublincore.title<br />
user.dublincore.date<br />
user.dublincore.description<br />
user.dublincore.contributor<br />
user.dublincore.format<br />
}}<br />
| Enabled with {{ic|--xattrs}} flag.<br />
|-<br />
| [[Wget]]<br />
| {{bc|<br />
user.xdg.origin.url<br />
user.xdg.referrer.url<br />
}}<br />
| Enabled with {{ic|--xattrs}} flag.<br />
|-<br />
| [[w:webkit|webkit]]<br />
| {{No|1=https://bugs.webkit.org/show_bug.cgi?id=260778}}<br />
|<br />
|}<br />
<br />
== Other tagging systems ==<br />
<br />
It might not be possible to use extended attributes due to lack of support of either the file system or software. For this reason, many media formats store metadata included in the file format that can be viewed using programs like [[Exiftool]] or more specified ones like {{AUR|id3}} for audio.<br />
<br />
* For all files: [[Exiftool]]<br />
* For audio: [[List of applications/Multimedia#Audio tag editors|Audio tag editors]]<br />
* For video: {{man|1|ffprobe}} from [[ffmpeg]]<br />
<br />
=== gvfs ===<br />
<br />
Another filesystem-independent workaround is Gnome virtual filesystem: {{pkg|gvfs}} which is used to store metadata (gvfsd-metadata). For example, Firefox [https://hg.mozilla.org/mozilla-central/file/tip/toolkit/components/downloads/DownloadPlatform.cpp stores metadata] this way and can be viewed with:<br />
<br />
$ gio info --attributes=metadata:: ''downloaded.html''<br />
<br />
Other programs that use this approach include:<br />
* [[Thunar]]: to save file color highlights.<br />
<br />
== See also ==<br />
<br />
* [https://www.freedesktop.org/wiki/CommonExtendedAttributes XDG guidelines for extended attributes]<br />
* [[wikipedia:Extended file attributes#Linux]]<br />
* [https://www.lesbonscomptes.com/pages/extattrs.html Extended attributes: the good, the not so good, the bad.]</div>Regidhttps://wiki.archlinux.org/index.php?title=Talk:Extended_attributes&diff=794812Talk:Extended attributes2023-12-20T01:36:25Z<p>Regid: /* Gnome/Nautilus support for xfattr through Eiciel */ I assume {{special:diff/794793}} was approved by the editors.</p>
<hr />
<div>== <s>Date column</s> ==<br />
<br />
What is the point of the "Date" column in the table in [[Extended attributes#Software]]? — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 13:04, 28 August 2023 (UTC)<br />
<br />
:It was removed. It would be nice if you also replied or closed this. — [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 15:14, 28 August 2023 (UTC)<br />
<br />
== <s>NFS supports extended file attributes</s> ==<br />
<br />
https://www.phoronix.com/news/Linux-5.9-NFS-Server-User-Xattr<br />
<br />
I have also tested that with NFSv4 and it worked correctly. xattrs of my file didn't go anywhere after moving or copying it to nfs mounted storage. <br />
</br><br />
[[User:Arash|Arash]] ([[User talk:Arash|talk]]) 12:57, 13 December 2023 (UTC)<br />
:Fixed the article at {{special:Diff/794739}}. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 09:45, 18 December 2023 (UTC)<br />
<br />
== <s>Gnome/Nautilus support for xfattr through Eiciel</s> ==<br />
<br />
Seems like nautilus doesn't remove xattrs, it just doesn't show them to uesrs or allow them to edit/add xfattrs by default. <br />
<br />
But full extended file attributes support can be added to Nautilus through Eiciel[https://aur.archlinux.org/packages/eiciel] and Eiciel Nautilus extension. Found in AUR.<br />
Eiciel is well-maintained and is working well on my system and is coherent with Gnome interface.<br />
<br />
Should we add this to the main extended attributes page?<br />
<br />
:: [[User:Arash|Arash]] ([[User talk:Arash|talk]]) 13:25, 13 December 2023 (UTC)<br />
:Article was amended at {{special:diff/794793}}, by adding this information to the main [[extended attributes]] page. Following [[Help:Discussion#Closing a discussion]]. [[User:Regid|Regid]] ([[User talk:Regid|talk]]) 01:35, 20 December 2023 (UTC)</div>Regidhttps://wiki.archlinux.org/index.php?title=Capabilities&diff=794811Capabilities2023-12-20T01:26:37Z<p>Regid: /* Running a program with temporary capabilities */ Following Help:Style#Spelling to prefer the long option instead of its single-character counterpart.</p>
<hr />
<div>[[Category:Security]]<br />
[[ja:ケイパビリティ]]<br />
[[pt:Capabilities]]<br />
[[ru:Capabilities]]<br />
[[zh-hans:Capabilities]]<br />
Capabilities (POSIX 1003.1e, {{man|7|capabilities}}) provide fine-grained control over superuser permissions, allowing use of the root user to be avoided. Software developers are encouraged to replace uses of the powerful [[wikipedia:Setuid|setuid]] attribute in a system binary with a more minimal set of capabilities. Many packages make use of capabilities, such as {{ic|CAP_NET_RAW}} being used for {{Pkg|fping}}. This enables {{ic|fping}} to be run by a normal user (as with the '''setuid''' method), while at the same time limiting the security consequences of a potential vulnerability in {{ic|fping}}.<br />
<br />
== Implementation ==<br />
<br />
Capabilities are implemented on Linux using [[extended attributes]] ({{man|7|xattr}}) in the ''security'' namespace. Extended attributes are supported by all major Linux [[file systems]], including Ext2, [[Ext3]], [[Ext4]], [[Btrfs]], [[JFS]], [[XFS]], and Reiserfs. The following example prints the capabilities of fping with {{ic|getcap}}, and then prints the same data in its encoded form using {{ic|getfattr}}:<br />
<br />
{{hc|$ getcap /usr/bin/fping|2=<br />
/usr/bin/fping cap_net_raw=ep<br />
}}<br />
<br />
{{hc|1=$ getfattr --dump --match="^security\\." /usr/bin/fping|2=<br />
# file: usr/bin/fping<br />
security.capability=0sAQAAAgAgAAAAAAAAAAAAAAAAAAA=<br />
}}<br />
<br />
Some programs copy extended attributes automatically, while others require a special flag. Examples for both classes are at [[extended attributes#Preserving extended attributes]].<br />
<br />
Capabilities are set by [[PKGBUILD#install|packages install script]] on Arch. For example, [https://gitlab.archlinux.org/archlinux/packaging/packages/fping/-/blob/main/fping.install fping.install] will be installed at {{ic|/var/lib/pacman/local/fping/install}}.<br />
<br />
== Administration and maintenance ==<br />
<br />
It is considered a bug if a package has overly permissive capabilities, so these cases should be reported rather than listed here. A capability essentially equivalent to root access ({{ic|CAP_SYS_ADMIN}}) or trivially allowing root access ({{ic|CAP_DAC_OVERRIDE}}) does not count as a bug since Arch does not support any [[Security#Mandatory access control|MAC]]/[[w:Role-based access control|RBAC]] systems.<br />
<br />
{{Warning|1=Many capabilities enable trivial privilege escalation. For examples and explanations see Brad Spengler's post [https://forums.grsecurity.net/viewtopic.php?f=7&t=2522&sid=c6fbcf62fd5d3472562540a7e608ce4e#p10271 False Boundaries and Arbitrary Code Execution].}}<br />
<br />
== Other programs that benefit from capabilities ==<br />
<br />
The following packages do not have files with the setuid attribute but require root privileges to work. By enabling some capabilities, regular users can use the program without privilege elevation.<br />
<br />
The {{ic|+ep}} behind the capabilities indicate the capability sets ''effective'' and ''permitted'', more information can be found at {{man|7|capabilities|File capabilities}}.<br />
<br />
{| class=wikitable<br />
! program || Command<br />
|-<br />
| [[Beep]] || {{ic|# setcap cap_dac_override,cap_sys_tty_config+ep /usr/bin/beep}}<br />
|-<br />
| {{man|1|chvt}} || {{ic|# setcap cap_dac_read_search,cap_sys_tty_config+ep /usr/bin/chvt}}<br />
|-<br />
| {{man|8|iftop}} || {{ic|# setcap cap_net_raw+ep /usr/bin/iftop}}<br />
|-<br />
| {{man|8|mii-tool}} || {{ic|# setcap cap_net_admin+ep /usr/bin/mii-tool}}<br />
|-<br />
| {{man|8|mtr}} || {{ic|# setcap cap_net_raw+ep /usr/bin/mtr-packet}}<br />
|-<br />
| {{man|8|nethogs}} || {{ic|# setcap cap_net_admin,cap_net_raw+ep /usr/bin/nethogs}}<br />
|-<br />
| {{man|1|wavemon}} || {{ic|# setcap cap_net_admin+ep /usr/bin/wavemon}}<br />
|}<br />
<br />
== Useful commands ==<br />
<br />
Find setuid-root files:<br />
<br />
$ find /usr/bin /usr/lib -perm /4000 -user root<br />
<br />
Find setgid-root files:<br />
<br />
$ find /usr/bin /usr/lib -perm /2000 -group root<br />
<br />
== Running a program with temporary capabilities ==<br />
<br />
Using {{man|1|capsh}} it is possible to run a program with some specific capabilities without modifying the extended attributes of the binary. The following example shows how to attach to a process using [[GDB]] using the {{ic|CAP_SYS_PTRACE}} capability:<br />
<br />
$ sudo --preserve-env capsh --caps="cap_setpcap,cap_setuid,cap_setgid+ep cap_sys_ptrace+eip" --keep=1 --user="$USER" --addamb="cap_sys_ptrace" --shell=/usr/bin/gdb -- -p <pid><br />
<br />
The {{ic|-E/--preserve-env}} is supplied to {{ic|sudo}} above to pass the current user's login environment, ''e.g.,'' the {{ic|PATH}} variable and so on, to the child process(es).<br />
<br />
An example of binding to a low port using [[netcat]], in this case 123:<br />
<br />
$ sudo --preserve-env capsh --caps="cap_setpcap,cap_setuid,cap_setgid+ep cap_net_bind_service+eip" --keep=1 --user="$USER" --addamb="cap_net_bind_service" --shell=/usr/bin/nc -- -lvtn 123<br />
Listening on 0.0.0.0 123<br />
<br />
Both of the above examples are really just for illustrative purposes, as (on most systems) you would be able to attach debugger to a process owned by any user, or open a port < 1024 as the root user, regardless. The use of {{ic|capsh}} may provide some security benefits, though, as {{ic|capsh --user}} runs as the named user, with all the normal kernel capabilities (''i.e.'', restrictions) in place.<br />
<br />
== See also ==<br />
<br />
* Man pages: {{man|7|capabilities}}, {{man|8|setcap}}, {{man|8|getcap}}<br />
* [[Wikibooks:Grsecurity/Appendix/Capability Names and Descriptions]]<br />
* [https://docs.kernel.org/userspace-api/seccomp_filter.html Seccomp BPF (SECure COMPuting with filters)]</div>Regid