https://wiki.archlinux.org/api.php?action=feedcontributions&user=Sander+Maijers&feedformat=atomArchWiki - User contributions [en]2024-03-29T15:52:37ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=500050User talk:Sander Maijers2017-11-29T08:52:43Z<p>Sander Maijers: </p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)<br />
<br />
:::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:44, 16 July 2016 (UTC)<br />
<br />
::::Today I had time to test again, and it works for me now without `--options`. I will correct the Wiki page now. Good catch!<br />
::::[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 11:42, 25 July 2016 (UTC)<br />
<br />
== Windows 10 ISO ==<br />
I have looked at a few ISOs and they all have the install.esd, I haven't seen the install.wim in recent versions. In which Windows 10 ISO have you seen the wim format?<br />
<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 20:16, 28 November 2017 (UTC)<br />
<br />
:Win10_1709_EnglishInternational_x64.iso<br />
<br />
:[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]])<br />
<br />
::Then both esd and wim exist in recent Windows10 ISOs, I would remove the explicit reference to Windows 10 in the wiki <br />
<br />
::[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 07:45, 29 November 2017 (UTC)<br />
<br />
:::Why do you believe install.esd exists? It doesn't in that ISO. If you have evidence this is true for more ISOs, feel free to specify that.<br />
<br />
:::[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]])</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=500049User talk:Sander Maijers2017-11-29T08:52:22Z<p>Sander Maijers: </p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)<br />
<br />
:::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:44, 16 July 2016 (UTC)<br />
<br />
::::Today I had time to test again, and it works for me now without `--options`. I will correct the Wiki page now. Good catch!<br />
::::[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 11:42, 25 July 2016 (UTC)<br />
<br />
== Windows 10 ISO ==<br />
I have looked at a few ISOs and they all have the install.esd, I haven't seen the install.wim in recent versions. In which Windows 10 ISO have you seen the wim format?<br />
<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 20:16, 28 November 2017 (UTC)<br />
<br />
:Win10_1709_EnglishInternational_x64.iso<br />
<br />
:[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]])<br />
<br />
::Then both esd and wim exist in recent Windows10 ISOs, I would remove the explicit reference to Windows 10 in the wiki <br />
<br />
::[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 07:45, 29 November 2017 (UTC)<br />
<br />
:::[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]])<br />
<br />
:::Why do you believe install.esd exists? It doesn't in that ISO. If you have evidence this is true for more ISOs, feel free to specify that.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=500026User talk:Sander Maijers2017-11-28T20:54:23Z<p>Sander Maijers: /* Windows 10 ISO */</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)<br />
<br />
:::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:44, 16 July 2016 (UTC)<br />
<br />
::::Today I had time to test again, and it works for me now without `--options`. I will correct the Wiki page now. Good catch!<br />
::::[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 11:42, 25 July 2016 (UTC)<br />
<br />
== Windows 10 ISO ==<br />
I have looked at a few ISOs and they all have the install.esd, I haven't seen the install.wim in recent versions. In which Windows 10 ISO have you seen the wim format?<br />
<br />
<br />
[[User:Kewl|Kewl]] ([[User talk:Kewl|talk]]) 20:16, 28 November 2017 (UTC)<br />
<br />
Win10_1709_EnglishInternational_x64.iso<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]])</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=Microsoft_fonts&diff=499906Microsoft fonts2017-11-28T11:25:49Z<p>Sander Maijers: Update for Windows 10, clarify</p>
<hr />
<div>[[Category:Fonts]]<br />
[[ar:Microsoft fonts]]<br />
[[ja:MS フォント]]<br />
[[ru:Microsoft fonts]]<br />
[[sr:Microsoft fonts]]<br />
[[zh-hans:Microsoft fonts]]<br />
{{Related articles start}}<br />
{{Related|Metric-compatible fonts}}<br />
{{Related|Fonts}}<br />
{{Related|Font configuration}}<br />
{{Related|Java Runtime Environment Fonts}}<br />
{{Related articles end}}<br />
This article explains how to install TrueType Microsoft fonts and emulate Windows' font rendering.<br />
<br />
{{Tip|See [[Metric-compatible fonts]] for alternatives.}}<br />
<br />
== Installation ==<br />
<br />
=== Using fonts from a Windows partition ===<br />
<br />
If there is a Windows partition mounted, its fonts can be used by linking to them.<br />
<br />
''For example, if the Windows C:\ partition is mounted at {{ic|/windows}}:''<br />
<br />
# ln -s /windows/Windows/Fonts /usr/share/fonts/WindowsFonts<br />
<br />
Then regenerate the fontconfig cache:<br />
<br />
# fc-cache -f<br />
<br />
Alternatively, copy the Windows fonts to {{ic|/usr/share/fonts}}:<br />
<br />
# mkdir /usr/share/fonts/WindowsFonts<br />
# cp /windows/Windows/Fonts/* /usr/share/fonts/WindowsFonts<br />
# chmod 755 /usr/share/fonts/WindowsFonts/*<br />
<br />
Then regenerate the fontconfig cache:<br />
<br />
# fc-cache -f<br />
<br />
=== Extracting fonts from a Windows ISO ===<br />
<br />
The fonts can also be found in a Windows ISO file.<br />
<br />
Extract the {{ic|sources/install.esd}} or the {{ic|sources/install.wim}} (Windows 10) file in the ISO and look for a {{ic|Windows/Fonts}} directory within this file. The format of this file is ESD ''(Windows Electronic Software Download)'' and it can be extracted with [[p7zip]]:<br />
<br />
$ 7z x install.wim<br />
<br />
=== Current packages ===<br />
<br />
{{Note|These packages do '''require access to a Windows 7/8/10 and/or a Office 2007''' setup or installation media, consult corresponding [[PKGBUILD]] for details.}}<br />
* {{AUR|ttf-office-2007-fonts}} — Office 2007 fonts<br />
* {{AUR|ttf-win7-fonts}} — Windows 7 fonts<br />
* {{AUR|ttf-ms-win8}} — Windows 8.1 fonts<br />
* {{AUR|ttf-ms-win10}} — Windows 10 fonts<br />
<br />
=== Legacy packages ===<br />
<br />
{{Note|The fonts provided by these packages are out-of-date and are missing modern hinting instructions and the full character sets. It is recommended to use the above packages.}}<br />
<br />
{{AUR|ttf-ms-fonts}} includes:<br />
<br />
* [[Wikipedia:Andalé Mono|Andalé Mono]]<br />
* [[Wikipedia:Arial|Arial]]<br />
* [[Wikipedia:Arial Black|Arial Black]]<br />
* [[Wikipedia:Comic Sans|Comic Sans]]<br />
* [[Wikipedia:Courier New|Courier New]]<br />
* [[Wikipedia:Georgia (typeface)|Georgia]]<br />
* [[Wikipedia:Impact (typeface)|Impact]]<br />
* [[Wikipedia:Lucida Sans|Lucida Sans]]<br />
* [[Wikipedia:Lucida Console|Lucida Console]]<br />
* [[Wikipedia:Microsoft Sans Serif|Microsoft Sans Serif]]<br />
* <s>[[Wikipedia:Symbol (typeface)|Symbol]]</s><br />
* [[Wikipedia:Times New Roman|Times New Roman]]<br />
* [[Wikipedia:Trebuchet MS|Trebuchet]]<br />
* [[Wikipedia:Verdana|Verdana]]<br />
* [[Wikipedia:Webdings|Webdings]]<br />
* [[Wikipedia:Wingdings|Wingdings]]<br />
<br />
{{Warning|According to [http://web.archive.org/web/20020227054122/www.microsoft.com/typography/fontpack/eula.htm original Microsoft's End User License Agreement], there are ''some'' legal limitations when using the above fonts.}}<br />
<br />
You can also obtain {{AUR|ttf-tahoma}} which, as you might expect, contains [[Wikipedia:Tahoma (typeface)|Tahoma]].<br />
<br />
{{AUR|ttf-vista-fonts}} includes: <br />
<br />
* [[Wikipedia:Calibri|Calibri]]<br />
* [[Wikipedia:Cambria (typeface)|Cambria]]<br />
* [[Wikipedia:Candara|Candara]]<br />
* [[Wikipedia:Consolas|Consolas]]<br />
* [[Wikipedia:Constantia (typeface)|Constantia]]<br />
* [[Wikipedia:Corbel (typeface)|Corbel]]<br />
<br />
== Fontconfig rules useful for MS Fonts ==<br />
<br />
Often websites specify the fonts using generic names (helvetica, courier, times or times new roman) a rule in fontconfig replaces this fonts with (ugly) free fonts: <br />
/etc/fonts/conf.d/30-metric-aliases-free.conf<br />
to make full use of the MS fonts it is necessary to create a rule mapping those generic names to MS specific fonts contained in the various packages above:<br />
<br />
<?xml version="1.0"?><br />
<!DOCTYPE fontconfig SYSTEM "fonts.dtd"><br />
<fontconfig><br />
<!-- Map generics to MS specifics --><br />
<!-- PostScript --><br />
<alias binding="same"><br />
<family>Helvetica</family><br />
<accept><br />
<family>Arial</family><br />
</accept><br />
</alias><br />
<alias binding="same"><br />
<family>Times</family><br />
<accept><br />
<family>Times New Roman</family><br />
</accept><br />
</alias><br />
<alias binding="same"><br />
<family>Courier</family><br />
<accept><br />
<family>Courier New</family><br />
</accept><br />
</alias><br />
</fontconfig><br />
<br />
It is also useful to associate serif,sans-serif,monospace fonts in your favourite browser to MS fonts.<br />
<br />
== Windows 8 ==<br />
<br />
The {{AUR|ttf-ms-win8}} split package is intended as a more up-to-date replacement for<br />
{{AUR|ttf-ms-fonts}}, {{AUR|ttf-vista-fonts}} and {{AUR|ttf-win7-fonts}}.<br />
<br />
Although it provides newer versions of the fonts, it '''cannot automatically download the fonts''' due<br />
to license issues .<br />
<br />
{{Note|usage of Microsoft fonts outside running Windows system is prohibited by EULA (although in certain countries EULA is invalid). Please consult Microsoft license before using fonts.}}<br />
<br />
You can acquire fonts from an installed and fully updated Windows 8.1 system. Any edition of ''Windows 8.1 build '''Windows 8.1 6.3.9600.17238''''' will work.<br />
<br />
On the installed Windows 8.1 system fonts are usually located in {{ic|[http://technet.microsoft.com/en-us/library/hh825266.aspx %WINDIR%]\Fonts}} and license file is {{ic|[http://technet.microsoft.com/en-us/library/hh825266.aspx %SYSTEM32%]\license.rtf}}.<br />
<br />
You need the files listed in the {{ic|1=source=()}} array. Place them in the same directory as this [[PKGBUILD]] file, then run [[makepkg]].<br />
<br />
{{ic|makepkg --pkg ttf-ms-win8}} will make just the Windows 8.1 core fonts package which should cover even more than {{AUR|ttf-ms-fonts}}.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=Tmsu&diff=497254Tmsu2017-11-18T12:38:55Z<p>Sander Maijers: The new project is also deprecated ... Remove extension altogether then.</p>
<hr />
<div>[[Category:Search]]<br />
[[Category:File systems]]<br />
[[ja:Tmsu]]<br />
[http://tmsu.org tmsu] is a tool for tagging your files. It provides a simple command-line tool for applying tags and a virtual file-system so that you can get a tagged based view of your files from within any other program.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{AUR|tmsu}} package.<br />
<br />
== Usage ==<br />
<br />
The tmsu [http://tmsu.org website] provides an excellent short quick tour on the basic usage and it's [https://github.com/oniony/TMSU/wiki wiki] per subject information.<br />
<br />
== Obstacles ==<br />
<br />
tmsu creates symlinks between files, folders and the related tags. That is, it cannot handle file deletions and moves very well although there is a 'repair' command that will detect file moves and renames. It also updates fingerprints for modified files. There is no automatic directory watcher and it is not planned to add this facility as it would not work across all file system types.<br />
<br />
== See also ==<br />
<br />
* [http://en.reddit.com/r/linux/comments/woear/tmsu_is_a_program_that_allows_you_to_organise/ Reddit discussion]<br />
* {{AUR|tagsistant}} (alternative semantic filesystem)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=Tmsu&diff=497253Tmsu2017-11-18T12:37:59Z<p>Sander Maijers: Update link to new project</p>
<hr />
<div>[[Category:Search]]<br />
[[Category:File systems]]<br />
[[ja:Tmsu]]<br />
[http://tmsu.org tmsu] is a tool for tagging your files. It provides a simple command-line tool for applying tags and a virtual file-system so that you can get a tagged based view of your files from within any other program.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{AUR|tmsu}} package.<br />
<br />
== Usage ==<br />
<br />
The tmsu [http://tmsu.org website] provides an excellent short quick tour on the basic usage and it's [https://github.com/oniony/TMSU/wiki wiki] per subject information.<br />
<br />
== Obstacles ==<br />
<br />
tmsu creates symlinks between files, folders and the related tags. That is, it cannot handle file deletions and moves very well although there is a 'repair' command that will detect file moves and renames. It also updates fingerprints for modified files. There is no automatic directory watcher and it is not planned to add this facility as it would not work across all file system types.<br />
<br />
== See also ==<br />
<br />
* [http://en.reddit.com/r/linux/comments/woear/tmsu_is_a_program_that_allows_you_to_organise/ Reddit discussion]<br />
* [https://github.com/Dieterbe/pixie tmsu extensions]<br />
* {{AUR|tagsistant}} (alternative semantic filesystem)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=443122User talk:Sander Maijers2016-07-25T11:42:57Z<p>Sander Maijers: finally fix up indentation</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)<br />
<br />
:::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:44, 16 July 2016 (UTC)<br />
<br />
::::Today I had time to test again, and it works for me now without `--options`. I will correct the Wiki page now. Good catch!<br />
::::[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 11:42, 25 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=443121User talk:Sander Maijers2016-07-25T11:42:35Z<p>Sander Maijers: fix up indentation</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)<br />
<br />
:::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:44, 16 July 2016 (UTC)<br />
<br />
::::Today I had time to test again, and it works for me now without `--options`. I will correct the Wiki page now. Good catch!<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 11:42, 25 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=443120User talk:Sander Maijers2016-07-25T11:42:10Z<p>Sander Maijers: conclude discussion 1</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)<br />
<br />
:::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 12:44, 16 July 2016 (UTC)<br />
<br />
::::gpg-agent seems to behave correctly for me even when {{ic|~/.gnupg}} is a symlink - the config file is still loaded even without an explicit {{ic|--options}} parameter. -- <br />
Today I had time to test again, and it works for me now without `--options`. I will correct the Wiki page now. Good catch!<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 11:42, 25 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=441540User talk:Sander Maijers2016-07-15T14:44:22Z<p>Sander Maijers: style: indent sign-off</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
:: [[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=441539User talk:Sander Maijers2016-07-15T14:43:14Z<p>Sander Maijers: response 2</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)<br />
<br />
:Do you have a non-default {{ic|GNUPGHOME}}? Is the systemd unit exactly the same as on the wiki or can you show the customizations?<br />
:The default socket path changed in 2.1.13, see [[Talk:GnuPG]] and the note added in [https://wiki.archlinux.org/index.php?title=GnuPG&diff=438807&oldid=438806].<br />
:[[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 21:26, 14 July 2016 (UTC)<br />
<br />
::I haven't set {{ic|GNUPGHOME}}, but perhaps the path to the GnuPG home is being normalized by GnuPG. It's a symlink in my setup.<br />
::{{ic|'/home/sanmai/.gnupg' -> '/home/sanmai/secrets/.gnupg'}}<br />
::<br />
::The systemd unit is the same as the one I've contributed to the Arch Wiki, i.e. has a single customization to the original one on the Wiki.<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 14:43, 15 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=441437User talk:Sander Maijers2016-07-14T21:03:50Z<p>Sander Maijers: another cleanup</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore. Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent}} in daemon mode under systemd as user unit.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=441436User talk:Sander Maijers2016-07-14T21:02:19Z<p>Sander Maijers: fix wording</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that with {{ic|--options}} explicitly pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore:<br />
<br />
Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent} in daemon mode under systemd.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=User_talk:Sander_Maijers&diff=441435User talk:Sander Maijers2016-07-14T21:01:48Z<p>Sander Maijers: 1st response in gpg-agent --options discussion</p>
<hr />
<div>== gpg-agent ==<br />
<br />
How do you interpret the {{ic|gpg-agent(1)}} man page? It says<br />
<br />
--options file<br />
Reads configuration from file instead of from the default per-user configuration file. The default configuration file is named ‘gpg-agent.conf’ and expected in the ‘.gnupg’ directory directly below the home directory of the user.<br />
<br />
And later<br />
<br />
gpg-agent.conf<br />
This is the standard configuration file read by gpg-agent on<br />
startup. It may contain any valid long option; the leading<br />
two dashes may not be entered and the option may not be abbreviated.<br />
This file is also read after a SIGHUP however only a few<br />
options will actually have an effect. This default name may be<br />
changed on the command line (see: [option --options]).<br />
You should backup this file.<br />
<br />
Which IMO means that {{ic|~/.gnupg/gpg-agent.conf}} is read by default, even with {{ic|--daemon}}. My experiments support this.<br />
<br />
-- [[User:Lahwaacz|Lahwaacz]] ([[User talk:Lahwaacz|talk]]) 20:39, 14 July 2016 (UTC)<br />
<br />
----<br />
You are correct about the man page, I falsely recollected a specific detail there.<br />
<br />
Regardless, my own practice has learned me that without {{ic|--options}} pointing to the default file, SSH authentication using {{ic|gpg-agent}} works, whereas without it, it does not. I have been testing and configuring this all afternoon, using fresh logouts, reboots and {{ic|systemctl --user daemon-reload}}. This may be related to the circumstance that I'm starting {{ic|gpg-agent}} from a systemd user unit. For example, the standard socket also isn't located in its documented place anymore:<br />
<br />
Reading e.g. [https://www.gnupg.org/faq/whats-new-in-2.1.html]<br />
<br />
{{quote|With GnuPG 2.1 the need of GPG_AGENT_INFO has been completely removed and the variable is ignored. Instead a fixed Unix domain socket named S.gpg-agent in the GnuPG home directory (by default ~/.gnupg) is used. The agent is also started on demand by all tools requiring services from the agent.}}<br />
<br />
In reality, these files are only found under {{ic|"${XDG_RUNTIME_DIR}/gnupg/"}} when starting {{ic|gpg-agent} in daemon mode under systemd.<br />
<br />
[[User:Sander Maijers|Sander Maijers]] ([[User talk:Sander Maijers|talk]]) 21:01, 14 July 2016 (UTC)</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=441431GnuPG2016-07-14T20:41:04Z<p>Sander Maijers: Rewrite broken sentence.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-cn:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|<user-id>}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''<user-id>'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed.<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}.; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jijrk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}).<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''<user-id>'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc.gpg'' encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc.gpg''<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc.gpg'' to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient, but only individual files at a time, though you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --allow-secret-key-import --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a user-specific systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --options '%h/.gnupg/gpg-agent.conf' --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#Directory location|GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''.<br />
To make sure each process can find your gpg-agent instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
# The following line should be used instead of the last if you don't use the systemd unit but e.g. start gpg-agent from your shell.<br />
# SSH_AUTH_SOCK DEFAULT="@{HOME}/.gnupg/S.gpg-agent.ssh"<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
Alternatively, depend on Bash:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|If you use non-default [[#Directory location|GnuPG home directory]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with PSCD-Lite ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pscd.socket}} has to be listening.}}<br />
<br />
PSCD-Lite is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PSCD-Lite driver.<br />
<br />
==== Always use PSCD-Light ====<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=441428GnuPG2016-07-14T20:38:44Z<p>Sander Maijers: Add SSH_AUTH_SOCK instructions with pam_env</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-cn:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|<user-id>}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''<user-id>'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed.<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}.; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jijrk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}).<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''<user-id>'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc.gpg'' encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc.gpg''<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc.gpg'' to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient, but only individual files at a time, though you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --allow-secret-key-import --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a user-specific systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --options '%h/.gnupg/gpg-agent.conf' --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#Directory location|GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent''.<br />
To make sure each process can find your gpg-agent instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
# The following line should be used instead of the last if you don't use the systemd unit but e.g. start gpg-agent from your shell.<br />
# SSH_AUTH_SOCK DEFAULT="@{HOME}/.gnupg/S.gpg-agent.ssh"<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
If you want to do but prefer to depend on Bash:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|If you use non-default [[#Directory location|GnuPG home directory]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with PSCD-Lite ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pscd.socket}} has to be listening.}}<br />
<br />
PSCD-Lite is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PSCD-Lite driver.<br />
<br />
==== Always use PSCD-Light ====<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=441427GnuPG2016-07-14T20:36:03Z<p>Sander Maijers: GPG_TTY should be set, and indeed the user is instructed so in the man page for gpg-agent in gnupg 2.1.13-1.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-cn:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|<user-id>}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''<user-id>'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed.<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}.; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jijrk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}).<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''<user-id>'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc.gpg'' encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc.gpg''<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc.gpg'' to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient, but only individual files at a time, though you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --allow-secret-key-import --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a user-specific systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --options '%h/.gnupg/gpg-agent.conf' --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#Directory location|GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent'':<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|If you use non-default [[#Directory location|GnuPG home directory]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.}}<br />
<br />
Also set the GPG_TTY and refresh the TTY in case user has switched into an X session as stated in {{ic|man gpg-agent}}. For example:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with PSCD-Lite ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pscd.socket}} has to be listening.}}<br />
<br />
PSCD-Lite is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PSCD-Lite driver.<br />
<br />
==== Always use PSCD-Light ====<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=441426GnuPG2016-07-14T20:26:41Z<p>Sander Maijers: Undo revision 441421 by Lahwaacz (talk): testing with 2.1.13-1 as well as interpreting the man page proves that --options *must* be specified for the default options to be applied with --daemon.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-cn:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|<user-id>}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''<user-id>'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed.<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}.; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jijrk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}).<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''<user-id>'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc.gpg'' encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc.gpg''<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc.gpg'' to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient, but only individual files at a time, though you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --allow-secret-key-import --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a user-specific systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --options '%h/.gnupg/gpg-agent.conf' --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#Directory location|GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent'':<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|If you use non-default [[#Directory location|GnuPG home directory]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.}}<br />
<br />
Also set the GPG TTY and refresh the TTY in case user has switched into an X session. Example:<br />
<br />
{{Expansion|Not clear why this is necessary (even tha man page does not explain it).}}<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with PSCD-Lite ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pscd.socket}} has to be listening.}}<br />
<br />
PSCD-Lite is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PSCD-Lite driver.<br />
<br />
==== Always use PSCD-Light ====<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GNOME/Keyring&diff=441424GNOME/Keyring2016-07-14T20:21:09Z<p>Sander Maijers: small wording improvements, clarifications</p>
<hr />
<div>[[Category:GNOME]]<br />
[[ja:GNOME Keyring]]<br />
[https://wiki.gnome.org/Projects/GnomeKeyring GNOME Keyring] is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."<br />
<br />
{{Note|There are some [[#Known issues]].}}<br />
<br />
== Installation ==<br />
<br />
When using GNOME, {{Pkg|gnome-keyring}} is installed automatically as a part of the {{grp|gnome}} group. Otherwise [[install]] the {{Pkg|gnome-keyring}} package.<br />
<br />
Extra utilities related to GNOME keyring include:<br />
* {{App|secret-tool|Access the GNOME keyring (and any other service implementing the [http://standards.freedesktop.org/secret-service/ DBus Secret Service API]) from the command line.|https://wiki.gnome.org/Projects/Libsecret|{{Pkg|libsecret}}}}<br />
* {{App|gnome-keyring-query|Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring.|http://www.gentoo-wiki.info/HOWTO_Use_gnome-keyring_to_store_SSH_passphrases|{{AUR|gnome-keyring-query}}}}<br />
* {{App|gkeyring|Query passwords from the command line, the [[Git]] version can list all passwords without needing to know name or id of the item|https://github.com/kparal/gkeyring|{{AUR|gkeyring}}, {{AUR|gkeyring-git}}}}<br />
<br />
== Manage using GUI ==<br />
<br />
You can manage the contents of GNOME Keyring using Seahorse. [[Install]] it with the package {{Pkg|seahorse}}.<br />
<br />
It is possible to leave the GNOME keyring password blank or change it. In seahorse, in the "View" drop-down menu, select "By Keyring". On the Passwords tab, right click on "Passwords: login" and pick "Change password." Enter the old password and leave empty the new password. You will be warned about using unencrypted storage; continue by pushing "Use Unsafe Storage."<br />
<br />
== Using the keyring outside GNOME ==<br />
<br />
=== Without a display manager ===<br />
<br />
==== Automatic login ====<br />
<br />
If you are using automatic login, then you can disable the keyring manager by setting a blank password on the login keyring.<br />
{{Note| The passwords are stored unencrypted in this case.}}<br />
<br />
==== Console login ====<br />
<br />
When using console-based login, the keyring daemon can be started by either [[PAM]] or [[xinitrc]]. PAM can also unlock the keyring automatically at login.<br />
<br />
===== PAM method =====<br />
<br />
Start the gnome-keyring-daemon from {{ic|/etc/pam.d/login}}:<br />
<br />
Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.<br />
<br />
{{hc|/etc/pam.d/login|<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
auth optional pam_gnome_keyring.so<br />
account include system-local-login<br />
session include system-local-login<br />
session optional pam_gnome_keyring.so auto_start}}<br />
<br />
Next, add {{ic|password optional pam_gnome_keyring.so}} to the end of {{ic|/etc/pam.d/passwd}}.<br />
{{hc|/etc/pam.d/passwd|<br />
<nowiki>#%PAM-1.0<br />
<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
password optional pam_gnome_keyring.so</nowiki>}}<br />
<br />
{{Note|<br />
* To use automatic unlocking, the same password for the user account and the keyring have to be set.<br />
* You will still need the code in {{ic|~/.xinitrc}} below in order to export the environment variables required.}}<br />
<br />
===== xinitrc method =====<br />
<br />
Start the gnome-keyring-daemon from [[xinitrc]]:<br />
<br />
{{hc|~/.xinitrc|<nowiki><br />
eval $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)<br />
export SSH_AUTH_SOCK<br />
</nowiki>}}<br />
<br />
See [[Xfce#SSH agents]] for use in Xfce.<br />
<br />
=== With a display manager ===<br />
<br />
When using a display manager, the keyring works out of the box for most cases. The following display managers automatically unlock the keyring once you log in:<br />
* [[GDM]]<br />
* [[SLiM]]<br />
* [[LightDM]]<br />
* [[LXDM]]<br />
{{Note| You may need to install {{pkg|libgnome-keyring}} }}<br />
For KDM, see [[KDM#KDM and Gnome-keyring]].<br />
<br />
For [[SDDM]], follow the KDM guidelines, but modify {{ic|/etc/pam.d/sddm}} instead of {{ic|/etc/pam.d/kde}}.<br />
<br />
To enable the keyring for applications run through the terminal, such as SSH, add the following to your {{ic|~/.bash_profile}}, {{ic|~/.zshenv}}, or similar:<br />
<br />
{{hc|~/.zshenv|<nowiki><br />
if [ -n "$DESKTOP_SESSION" ];then<br />
eval $(gnome-keyring-daemon --start)<br />
export SSH_AUTH_SOCK<br />
fi</nowiki>}}<br />
<br />
{{Note| 1=The GNOME Keyring Daemon no longer exposes {{ic|GNOME_KEYRING_PID}}. See [https://mail.gnome.org/archives/commits-list/2014-March/msg03864.html commit].}}<br />
<br />
== SSH keys ==<br />
<br />
To add your SSH key:<br />
<br />
$ ssh-add ~/.ssh/id_dsa<br />
Enter passphrase for /home/mith/.ssh/id_dsa:<br />
<br />
To list automatically loaded keys:<br />
<br />
$ ssh-add -L<br />
<br />
To disable all keys;<br />
<br />
$ ssh-add -D<br />
<br />
Now when you connect to a server, the key will be found and a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!<br />
<br />
Alternatively, to permanently save the a passphrase in the keyring, use seahorse-ssh-askpass from package {{pkg|seahorse}}:<br />
<br />
/usr/lib/seahorse/seahorse-ssh-askpass my_key<br />
<br />
{{Note|You have to have a have the corresponding {{ic|.pub}} file in the same directory as the private key ({{ic|~/.ssh/id_dsa.pub}} in the example). Also, make sure that the public key is the file name of the private key plus {{ic|.pub}} (for example, {{ic|my_key.pub}}).}}<br />
=== Start SSH and Secrets components of keyring daemon ===<br />
<br />
If you are starting Gnome Keyring with a display manager or the Pam method described above and you are NOT using Gnome, Unity or Mate as your desktop you may find that the SSH and Secrets components are not being started automatically.<br />
You can fix this by copying the desktop files gnome-keyring-ssh.desktop and gnome-keyring-secrets.desktop from /etc/xdg/autostart/ to ~/.config/autostart/ and deleting the OnlyShowIn line.<br />
<br />
$ cp /etc/xdg/autostart/{gnome-keyring-secrets.desktop,gnome-keyring-ssh.desktop} ~/.config/autostart/<br />
$ sed -i '/^OnlyShowIn.*$/d' ~/.config/autostart/gnome-keyring-secrets.desktop<br />
$ sed -i '/^OnlyShowIn.*$/d' ~/.config/autostart/gnome-keyring-ssh.desktop<br />
<br />
=== Disable keyring daemon components ===<br />
<br />
If you wish to run an alternative SSH agent (e.g. [[SSH keys#ssh-agent|ssh-agent]] or [[GnuPG#gpg-agent|gpg-agent]], you need to disable the {{ic|ssh}} component of GNOME Keyring.<br />
To do so in an account-local way:<br />
{{bc|<nowiki>#!/bin/sh<br />
<br />
mkdir ~/.config/autostart<br />
cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/ &&<br />
printf '%s\n' 'Hidden=true' >> ~/.config/autostart/gnome-keyring-ssh.desktop <br />
</nowiki>}}<br />
<br />
Then log out.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Integration with applications ===<br />
<br />
* [[Firefox#GNOME Keyring integration]]<br />
<br />
=== Flushing passphrases ===<br />
<br />
gnome-keyring-daemon -r -d<br />
<br />
This command starts gnome-keyring-daemon, shutting down previously running instances.<br />
<br />
=== GNOME Keyring and Git ===<br />
<br />
The GNOME keyring is useful in conjuction with [[Git]] when you are pushing over HTTPS.<br />
<br />
First install the package {{pkg|libgnome-keyring}} from the [[official repositories]].<br />
<br />
Next compile the helper:<br />
$ cd /usr/share/git/credential/gnome-keyring<br />
# make<br />
Set Git up to use the helper:<br />
$ git config --global credential.helper /usr/lib/git-core/git-credential-gnome-keyring<br />
Next time you do a ''git push'', you are asked to unlock your keyring, if not unlocked already.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you get a password prompt every time you login, and you find that passwords are not saved, you might need to create/set a default keyring.<br />
<br />
Ensure that the {{pkg|seahorse}} package is installed, open it ("Passwords and Keys" in system settings) and select ''View'' > ''By Keyring'' <br />
If there is no keyring in the left column (it will be marked with a lock icon), go to ''File'' > ''New'' > ''Password Keyring'' and give it a name. You will be asked to enter a password. If you do not give the keyring a password it will be unlocked automatically, even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".<br />
<br />
== Known issues ==<br />
<br />
=== Cannot handle ECDSA and Ed25519 keys ===<br />
<br />
As of March 20, 2016, GNOME Keyring does not handle ECDSA[https://bugzilla.gnome.org/show_bug.cgi?id=641082] and Ed25519[https://bugzilla.gnome.org/show_bug.cgi?id=723274] keys. You can turn to other [[SSH_keys#SSH_agents|SSH agents]] if you need support for those.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GNOME/Keyring&diff=441422GNOME/Keyring2016-07-14T20:19:39Z<p>Sander Maijers: Use standard methods to disable XDG-autostarted desktop files.</p>
<hr />
<div>[[Category:GNOME]]<br />
[[ja:GNOME Keyring]]<br />
[https://wiki.gnome.org/Projects/GnomeKeyring GNOME Keyring] is "a collection of components in GNOME that store secrets, passwords, keys, certificates and make them available to applications."<br />
<br />
{{Note|There are some [[#Known issues]].}}<br />
<br />
== Installation ==<br />
<br />
When using GNOME, {{Pkg|gnome-keyring}} is installed automatically as a part of the {{grp|gnome}} group. Otherwise [[install]] the {{Pkg|gnome-keyring}} package.<br />
<br />
Extra utilities related to GNOME keyring include:<br />
* {{App|secret-tool|Access the GNOME keyring (and any other service implementing the [http://standards.freedesktop.org/secret-service/ DBus Secret Service API]) from the command line.|https://wiki.gnome.org/Projects/Libsecret|{{Pkg|libsecret}}}}<br />
* {{App|gnome-keyring-query|Provides a simple command-line tool for querying passwords from the password store of the GNOME Keyring.|http://www.gentoo-wiki.info/HOWTO_Use_gnome-keyring_to_store_SSH_passphrases|{{AUR|gnome-keyring-query}}}}<br />
* {{App|gkeyring|Query passwords from the command line, the [[Git]] version can list all passwords without needing to know name or id of the item|https://github.com/kparal/gkeyring|{{AUR|gkeyring}}, {{AUR|gkeyring-git}}}}<br />
<br />
== Manage using GUI ==<br />
<br />
You can manage the contents of GNOME Keyring using Seahorse. [[Install]] it with the package {{Pkg|seahorse}}.<br />
<br />
It is possible to leave the GNOME keyring password blank or change it. In seahorse, in the "View" drop-down menu, select "By Keyring". On the Passwords tab, right click on "Passwords: login" and pick "Change password." Enter the old password and leave empty the new password. You will be warned about using unencrypted storage; continue by pushing "Use Unsafe Storage."<br />
<br />
== Using the keyring outside GNOME ==<br />
<br />
=== Without a display manager ===<br />
<br />
==== Automatic login ====<br />
<br />
If you are using automatic login, then you can disable the keyring manager by setting a blank password on the login keyring.<br />
{{Note| The passwords are stored unencrypted in this case.}}<br />
<br />
==== Console login ====<br />
<br />
When using console-based login, the keyring daemon can be started by either [[PAM]] or [[xinitrc]]. PAM can also unlock the keyring automatically at login.<br />
<br />
===== PAM method =====<br />
<br />
Start the gnome-keyring-daemon from {{ic|/etc/pam.d/login}}:<br />
<br />
Add {{ic|auth optional pam_gnome_keyring.so}} at the end of the {{ic|auth}} section and {{ic|session optional pam_gnome_keyring.so auto_start}} at the end of the {{ic|session}} section.<br />
<br />
{{hc|/etc/pam.d/login|<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
auth optional pam_gnome_keyring.so<br />
account include system-local-login<br />
session include system-local-login<br />
session optional pam_gnome_keyring.so auto_start}}<br />
<br />
Next, add {{ic|password optional pam_gnome_keyring.so}} to the end of {{ic|/etc/pam.d/passwd}}.<br />
{{hc|/etc/pam.d/passwd|<br />
<nowiki>#%PAM-1.0<br />
<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
password optional pam_gnome_keyring.so</nowiki>}}<br />
<br />
{{Note|<br />
* To use automatic unlocking, the same password for the user account and the keyring have to be set.<br />
* You will still need the code in {{ic|~/.xinitrc}} below in order to export the environment variables required.}}<br />
<br />
===== xinitrc method =====<br />
<br />
Start the gnome-keyring-daemon from [[xinitrc]]:<br />
<br />
{{hc|~/.xinitrc|<nowiki><br />
eval $(/usr/bin/gnome-keyring-daemon --start --components=pkcs11,secrets,ssh)<br />
export SSH_AUTH_SOCK<br />
</nowiki>}}<br />
<br />
See [[Xfce#SSH agents]] for use in Xfce.<br />
<br />
=== With a display manager ===<br />
<br />
When using a display manager, the keyring works out of the box for most cases. The following display managers automatically unlock the keyring once you log in:<br />
* [[GDM]]<br />
* [[SLiM]]<br />
* [[LightDM]]<br />
* [[LXDM]]<br />
{{Note| You may need to install {{pkg|libgnome-keyring}} }}<br />
For KDM, see [[KDM#KDM and Gnome-keyring]].<br />
<br />
For [[SDDM]], follow the KDM guidelines, but modify {{ic|/etc/pam.d/sddm}} instead of {{ic|/etc/pam.d/kde}}.<br />
<br />
To enable the keyring for applications run through the terminal, such as SSH, add the following to your {{ic|~/.bash_profile}}, {{ic|~/.zshenv}}, or similar:<br />
<br />
{{hc|~/.zshenv|<nowiki><br />
if [ -n "$DESKTOP_SESSION" ];then<br />
eval $(gnome-keyring-daemon --start)<br />
export SSH_AUTH_SOCK<br />
fi</nowiki>}}<br />
<br />
{{Note| 1=The GNOME Keyring Daemon no longer exposes {{ic|GNOME_KEYRING_PID}}. See [https://mail.gnome.org/archives/commits-list/2014-March/msg03864.html commit].}}<br />
<br />
== SSH keys ==<br />
<br />
To add your SSH key:<br />
<br />
$ ssh-add ~/.ssh/id_dsa<br />
Enter passphrase for /home/mith/.ssh/id_dsa:<br />
<br />
To list automatically loaded keys:<br />
<br />
$ ssh-add -L<br />
<br />
To disable all keys;<br />
<br />
$ ssh-add -D<br />
<br />
Now when you connect to a server, the key will be found and a dialog will popup asking you for the passphrase. It has an option to automatically unlock the key when you log in. If you check this, you will not need to enter your passphrase again!<br />
<br />
Alternatively, to permanently save the a passphrase in the keyring, use seahorse-ssh-askpass from package {{pkg|seahorse}}:<br />
<br />
/usr/lib/seahorse/seahorse-ssh-askpass my_key<br />
<br />
{{Note|You have to have a have the corresponding {{ic|.pub}} file in the same directory as the private key ({{ic|~/.ssh/id_dsa.pub}} in the example). Also, make sure that the public key is the file name of the private key plus {{ic|.pub}} (for example, {{ic|my_key.pub}}).}}<br />
=== Start SSH and Secrets components of keyring daemon ===<br />
<br />
If you are starting Gnome Keyring with a display manager or the Pam method described above and you are NOT using Gnome, Unity or Mate as your desktop you may find that the SSH and Secrets components are not being started automatically.<br />
You can fix this by copying the desktop files gnome-keyring-ssh.desktop and gnome-keyring-secrets.desktop from /etc/xdg/autostart/ to ~/.config/autostart/ and deleting the OnlyShowIn line.<br />
<br />
$ cp /etc/xdg/autostart/{gnome-keyring-secrets.desktop,gnome-keyring-ssh.desktop} ~/.config/autostart/<br />
$ sed -i '/^OnlyShowIn.*$/d' ~/.config/autostart/gnome-keyring-secrets.desktop<br />
$ sed -i '/^OnlyShowIn.*$/d' ~/.config/autostart/gnome-keyring-ssh.desktop<br />
<br />
=== Disable keyring daemon components ===<br />
<br />
If you wish to run an alternative SSH agent (e.g. [[SSH keys#ssh-agent|ssh-agent]] or [[GnuPG#gpg-agent|gpg-agent]], you need to disable the {{ic|ssh}} component in GNOME keyring daemon.<br />
To disable the {{ic|ssh}} component of GNOME Keyring:<br />
{{bc|<nowiki>#!/bin/sh<br />
<br />
mkdir ~/.config/autostart<br />
cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/ &&<br />
printf '%s\n' 'Hidden=true' >> ~/.config/autostart/gnome-keyring-ssh.desktop <br />
</nowiki>}}<br />
<br />
Then log out.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Integration with applications ===<br />
<br />
* [[Firefox#GNOME Keyring integration]]<br />
<br />
=== Flushing passphrases ===<br />
<br />
gnome-keyring-daemon -r -d<br />
<br />
This command starts gnome-keyring-daemon, shutting down previously running instances.<br />
<br />
=== GNOME Keyring and Git ===<br />
<br />
The GNOME keyring is useful in conjuction with [[Git]] when you are pushing over HTTPS.<br />
<br />
First install the package {{pkg|libgnome-keyring}} from the [[official repositories]].<br />
<br />
Next compile the helper:<br />
$ cd /usr/share/git/credential/gnome-keyring<br />
# make<br />
Set Git up to use the helper:<br />
$ git config --global credential.helper /usr/lib/git-core/git-credential-gnome-keyring<br />
Next time you do a ''git push'', you are asked to unlock your keyring, if not unlocked already.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Passwords are not remembered ===<br />
<br />
If you get a password prompt every time you login, and you find that passwords are not saved, you might need to create/set a default keyring.<br />
<br />
Ensure that the {{pkg|seahorse}} package is installed, open it ("Passwords and Keys" in system settings) and select ''View'' > ''By Keyring'' <br />
If there is no keyring in the left column (it will be marked with a lock icon), go to ''File'' > ''New'' > ''Password Keyring'' and give it a name. You will be asked to enter a password. If you do not give the keyring a password it will be unlocked automatically, even when using autologin, but passwords will not be stored securely. Finally, right-click on the keyring you just created and select "Set as default".<br />
<br />
== Known issues ==<br />
<br />
=== Cannot handle ECDSA and Ed25519 keys ===<br />
<br />
As of March 20, 2016, GNOME Keyring does not handle ECDSA[https://bugzilla.gnome.org/show_bug.cgi?id=641082] and Ed25519[https://bugzilla.gnome.org/show_bug.cgi?id=723274] keys. You can turn to other [[SSH_keys#SSH_agents|SSH agents]] if you need support for those.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=441420GnuPG2016-07-14T19:29:12Z<p>Sander Maijers: Make systemd unit process configuration file. Add instructions on how to set SSH_AUTH_SOCKET env var outside of shell config, which is necessary.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-cn:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as PGP). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<br />
<br />
If you want to use a graphical frontend or program that integrates with GnuPG, see [[List of applications/Security#Encryption, signing, steganography]].<br />
<br />
== Configuration ==<br />
<br />
=== Directory location ===<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. <br />
<br />
To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or set {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
=== Configuration files ===<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. <br />
<br />
By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.<br />
<br />
Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
=== Default options for new users ===<br />
<br />
If you want to setup some default options for new users, put configuration files in {{ic|/etc/skel/.gnupg/}}. When the new user is added in system, files from here will be copied to its GnuPG home directory. There is also a simple script called ''addgnupghome'' which you can use to create new GnuPG home directories for existing users:<br />
<br />
# addgnupghome user1 user2<br />
<br />
This will add the respective {{ic|/home/user1/.gnupg}} and {{ic|/home/user2/.gnupg}} and copy the files from the skeleton directory to it. Users with existing GnuPG home directory are simply skipped.<br />
<br />
== Usage ==<br />
<br />
{{Note|Whenever a ''{{ic|<user-id>}}'' is required in a command, it can be specified with your key ID, fingerprint, a part of your name or email address, etc. GnuPG is flexible on this.<br />
}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== List keys ===<br />
<br />
To list keys in your public key ring:<br />
<br />
$ gpg --list-keys<br />
<br />
To list keys in your secret key ring:<br />
<br />
$ gpg --list-secret-keys<br />
<br />
=== Export your public key ===<br />
<br />
gpg's main usage is to ensure confidentiality of exchanged messages via public-key cryptography. With it each user distributes the public key of their keyring, which can be be used by others to encrypt messages to the user. The private key must ''always'' be kept private, otherwise confidentiality is broken. See [[w:Public-key cryptography]] for examples about the message exchange. <br />
<br />
So, in order for others to send encrypted messages to you, they need your public key. <br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --output ''public.key'' --armor --export ''<user-id>'' <br />
<br />
Alternatively, or in addition, you can [[#Use a keyserver]] to share your key. <br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a public key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, [[#Use a keyserver]] to find a public key.<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* Adding {{ic|keyserver-options auto-key-retrieve}} to {{ic|gpg.conf}} will automatically fetch keys from the key server as needed.<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|keyserver}} in {{ic|dirmngr.conf}}.; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jijrk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}).<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''<user-id>'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc.gpg'' encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc.gpg''<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc.gpg'' to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient, but only individual files at a time, though you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --allow-secret-key-import --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|Revoking expired subkeys is unnecessary and arguably bad form. If you are constantly revoking keys, it may cause others to lack confidence in you.}}<br />
<br />
== Signatures ==<br />
<br />
Signatures certify and timestamp documents. If the document is modified, verification of the signature will fail. Unlike encryption which uses public keys to encrypt a document, signatures are created with the user's private key. The recipient of a signed document then verifies the signature using the sender's public key.<br />
<br />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a user-specific systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --options '%h/.gnupg/gpg-agent.conf' --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
To make sure each process can find your gpg-agent instance regardless of e.g. the type of shell it is child of use e.g. [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
# The following line should be used instead of the last if you don't use the systemd unit but e.g. start gpg-agent from your shell.<br />
# SSH_AUTH_SOCK DEFAULT="@{HOME}/.gnupg/S.gpg-agent.ssh"<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#Directory location|GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent'':<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="/run/user/$UID/gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
{{Note|If you use non-default [[#Directory location|GnuPG home directory]], run {{ic|gpgconf --create-socketdir}} to create a socket directory under {{ic|/run/user/$UID/gnupg/}}. Otherwise the socket will be placed in the GnuPG home directory.}}<br />
<br />
Also set the GPG TTY and refresh the TTY in case user has switched into an X session. Example:<br />
<br />
{{Expansion|Not clear why this is necessary (even tha man page does not explain it).}}<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
{{Note| To allow scdaemon direct access to USB smarcard readers the optional dependency {{Pkg|libusb-compat}} have to be installed}}<br />
<br />
If you do not plan to use other cards but those based on GnuPG, you should check the {{Ic|reader-port}} parameter in {{ic|~/.gnupg/scdaemon.conf}}. The value '0' refers to the first available serial port reader and a value of '32768' (default) refers to the first USB reader.<br />
<br />
=== GnuPG with PSCD-Lite ===<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|ccid}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running, or the socket {{ic|pscd.socket}} has to be listening.}}<br />
<br />
PSCD-Lite is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PSCD-Lite driver.<br />
<br />
==== Always use PSCD-Light ====<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}}.<br />
<br />
To send the signatures to their owners you need a working [[Wikipedia:Message transfer agent|MTA]]. If you do not have already one, install [[msmtp]].<br />
<br />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="660", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=Dash&diff=435887Dash2016-05-21T10:13:59Z<p>Sander Maijers: fix error in typo fix</p>
<hr />
<div>[[Category:Command shells]]<br />
[[ja:Dash]]<br />
[[wikipedia:Debian_Almquist_shell|Dash]] is a minimalist POSIX-compliant shell. It can be much faster than Bash, and takes up less memory when in use. Most POSIX compliant scripts specify {{ic|/bin/sh}} at the first line of the script, which means it will run {{ic|/bin/sh}} as the shell, which by default in Arch is a symlink to {{ic|/bin/bash}}.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|dash}} from the [[official repositories]].<br />
<br />
== Use DASH as default shell ==<br />
<br />
{{expansion}}<br />
<br />
You can re-symlink {{ic|/bin/sh}} to {{ic|/bin/dash}}, which can improve system performance, but first you must verify that none of the scripts that aren't explicitly {{ic|#!/bin/bash}} scripts are safely POSIX compliant and do not require any of Bash's features.<br />
<br />
=== Identifying bashisms ===<br />
<br />
Features of bash that aren't included in Dash ('bashisms') will not work without being explicitly pointed to {{ic|/bin/bash}}. The following instructions will allow you to find any scripts that may need modification. <br />
<br />
Install {{AUR|checkbashisms}} from the [[AUR]].<br />
<br />
==== Common places to check ====<br />
<br />
* Installed scripts with a {{ic|#!/bin/sh}} shebang:<br />
$ checkbashisms -f -p $(grep -IrlE '^#! ?(/usr)?/bin/(env )?sh' /usr/bin)<br />
<br />
=== Relinking /bin/sh ===<br />
<br />
Once you have verified that it won't break any functionality, it should be safe to relink {{ic|/bin/sh}}. To do so use the following command:<br />
# ln -sfT dash /bin/sh<br />
Updates of Bash could overwrite {{ic|/bin/sh}}. To prevent this, add the following lines to the <code>[options]</code> section of {{ic|/etc/pacman.conf}}:<br />
NoUpgrade = usr/bin/sh<br />
NoExtract = usr/bin/sh<br />
<br />
== See also ==<br />
<br />
http://article.gmane.org/gmane.linux.arch.devel/11418:<br />
* https://mailman.archlinux.org/pipermail/arch-dev-public/2007-November/003053.html<br />
* https://launchpad.net/ubuntu/+spec/dash-as-bin-sh<br />
* https://wiki.ubuntu.com/DashAsBinSh</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=Dash&diff=435886Dash2016-05-21T10:12:55Z<p>Sander Maijers: fix typo</p>
<hr />
<div>[[Category:Command shells]]<br />
[[ja:Dash]]<br />
[[wikipedia:Debian_Almquist_shell|Dash]] is a minimalist POSIX-compliant shell. It can be much faster than Bash, and takes up less memory when in use. Most POSIX compliant scripts specify {{ic|/bin/sh}} at the first line of the script, which means it will run {{ic|/bin/sh}} as the shell, which by default in Arch is a symlink to {{ic|/bin/bash}}.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|dash}} from the [[official repositories]].<br />
<br />
== Use DASH as default shell ==<br />
<br />
{{expansion}}<br />
<br />
You can re-symlink {{ic|/bin/sh}} to {{ic|/bin/dash}}, which can improve system performance, but first you must verify that none of the scripts that aren't explicitly {{ic|#!/bin/bash}} scripts are safely POSIX compliant and do not require any of Bash's features.<br />
<br />
=== Identifying bashisms ===<br />
<br />
Features of bash that aren't included in Dash ('bashisms') will not work without being explicitly pointed to {{ic|/bin/bash}}. The following instructions will allow you to find any scripts that may need modification. <br />
<br />
Install {{AUR|checkbashisms}} from the [[AUR]].<br />
<br />
==== Common places to check ====<br />
<br />
* Installed scripts with a {{ic|#!/bin/sh}} shebang:<br />
$ checkbashisms -f -p $(grep -IrlE '^#! ?(/usr)?/bin/(env )?sh' /usr/bin)<br />
<br />
=== Relinking /bin/sh ===<br />
<br />
Once you have verified that it won't break any functionality, it should be safe to relink {{ic|/bin/sh}}. To do so use the following command:<br />
# ln -sfT dash /bin/sh<br />
Updates of Bash could overwrite {{ic|/bin/sh}}. To prevent this, add the following lines to the {{[options]}} section of {{ic|/etc/pacman.conf}}:<br />
NoUpgrade = usr/bin/sh<br />
NoExtract = usr/bin/sh<br />
<br />
== See also ==<br />
<br />
http://article.gmane.org/gmane.linux.arch.devel/11418:<br />
* https://mailman.archlinux.org/pipermail/arch-dev-public/2007-November/003053.html<br />
* https://launchpad.net/ubuntu/+spec/dash-as-bin-sh<br />
* https://wiki.ubuntu.com/DashAsBinSh</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=X_resources&diff=430154X resources2016-04-08T13:08:53Z<p>Sander Maijers: style: add a few code tags around literal computer input</p>
<hr />
<div>[[Category:Dotfiles]]<br />
[[Category:X server]]<br />
[[de:Xdefaults]]<br />
[[ja:X resources]]<br />
[[ru:X resources]]<br />
'''Xresources''' is a user-level configuration ''dotfile'', typically located at {{ic|~/.Xresources}}. It can be used to set [[Wikipedia:X resources|X resources]], which are configuration parameters for X client applications.<br />
<br />
They can do many operations, including:<br />
<br />
* defining terminal colours<br />
* configuring terminal preferences<br />
* setting DPI, antialiasing, hinting and other X font settings<br />
* changing the Xcursor theme<br />
* theming xscreensaver<br />
* altering preferences on low-level X applications (xclock ({{Pkg|xorg-xclock}}), {{AUR|xpdf}}, {{Pkg|rxvt-unicode}}, etc.)<br />
<br />
{{Note|Using {{ic|~/.Xdefaults}} is deprecated, so this article will only refer to resources loaded with xrdb}}<br />
<br />
== Usage ==<br />
Make sure that {{pkg|xorg-xrdb}} is installed in your system.<br />
<br />
===Parsing .Xresources===<br />
The file {{ic|~/.Xresources}} does not exist by default. It is a plain-text file, so you can create it with any text editor. Once present it will be parsed automatically, by one of:<br />
* Most [[Display manager]]s will load the {{ic|~/.Xresources}} file on login.<br />
* If using {{ic|startx}} you may need to edit {{ic|.xinitrc}}, see below for details. <br />
The resources will be stored in the X server, so the file does not need to be read every time an app is started. The file can be reread to make any changes take effect.<br />
<br />
To reread the <code>.Xresources</code> file and throw away the old resources:<br />
<br />
xrdb ~/.Xresources<br />
<br />
To reread the <code>.Xresources</code> file and keep the old resources:<br />
<br />
xrdb -merge ~/.Xresources<br />
<br />
{{Tip|{{ic|~/.Xresources}} is just a naming convention; <code>xrdb</code> can load any file. If you use <code>xrdb</code> manually, you can put such a file anywhere you want (for example, {{ic|~/.config/Xresources}}).}}<br />
{{Note|Resources loaded with <code>xrdb</code> are also accessible to ''remote'' X11 clients (such as those forwarded over SSH).}}<br />
{{Warning|The older and deprecated {{ic|~/.Xdefaults}} file is read every time you start an X11 program such as {{ic|xterm}}, but '''only''' if {{ic|xrdb}} has not '''ever''' been used in the current X session. [https://groups.google.com/forum/#!msg/comp.windows.x/hQBEdql8l-Q/hF3DETcIHGwJ]<br />
}}<br />
<br />
===Adding to xinitrc===<br />
If you are using a copy of the default [[xinitrc]] as your {{ic|.xinitrc}} it already merges <code>~/.Xresources</code>.<br />
<br />
If you are using a custom {{ic|.xinitrc}} add the following line:<br />
<nowiki>[[ -f ~/.Xresources ]] && xrdb -merge -I$HOME ~/.Xresources</nowiki><br />
<br />
{{Warning|Never background the xrdb command within {{ic|~/.xinitrc}}. Otherwise, programs launched after xrdb may look for resources before it has finished loading them.}}<br />
<br />
===Default settings===<br />
To see the default settings for your installed X11 apps, look in {{ic|/usr/share/X11/app-defaults/}}.<br />
<br />
Detailed information on program-specific resources is usually provided in the man page for the program. xterm's man page is a good example, as it contains a list of X resources and their default values.<br />
<br />
To see the current loaded resources:<br />
xrdb -query -all<br />
<br />
===Xresources syntax===<br />
====Basic syntax====<br />
The syntax of an Xresources file is as follows:<br />
'''name.Class.resource: value'''<br />
and here is a real world example:<br />
xscreensaver.Dialog.headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
;name<br />
:The name of the application, such as xterm, xpdf, etc<br />
<br />
;class<br />
:The classification used to group resources together. Class names are typically uppercase.<br />
<br />
;resource<br />
:The name of the resource whose value is to be changed. Resources are typically lowercase with uppercase concatenation.<br />
<br />
;value<br />
:The actual value of the resource. This can be 1 of 3 types:<br />
:* Integer (whole numbers)<br />
:* Boolean (true/false, yes/no, on/off)<br />
:* String (a string of characters) (for example a word ({{ic|white}}), a color ({{ic|#ffffff}}), or a path ({{ic|/usr/bin/firefox}}))<br />
<br />
;delimiters<br />
:A dot ({{ic|'''.'''}}) is used to signify each step down into the hierarchy — in the above example we start at name, then descend into Class, and finally into the resource itself. A colon ({{ic|''':'''}}) is used to separate the resource declaration from the actual value.<br />
<br />
====Wildcard matching====<br />
<br />
The asterisk can be used as a wildcard, making it easy to write a single rule that can be applied to many different applications or elements. <br />
<br />
Using the previous example, if you want to apply the same font to all programs (not just XScreenSaver) that contain the class name {{ic|Dialog}} which contains the resource name {{ic|headingFont}}, you would write:<br />
<br />
'''*'''Dialog.headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
If you want to apply this same rule to all programs that contain the resource {{ic|headingFont}}, regardless of its class, you would write:<br />
<br />
'''*'''headingFont: -*-fixed-bold-r-*-*-*-100-*-*-*-*-iso8859-1<br />
<br />
==== Commenting ====<br />
To add a comment to your Xresources file, simply prefix it with an exclamation mark ({{ic|!}}), for example:<br />
<br />
! The following rule will be ignored because it has been commented out<br />
!Xft.antialias: true<br />
<br />
==== Include files ====<br />
<br />
To use different files for each application, use {{ic|#include}} in the main file. For example:<br />
<br />
{{hc|~/.Xresources|<br />
#include ".Xresources.d/xterm"<br />
#include ".Xresources.d/rxvt-unicode"<br />
#include ".Xresources.d/fonts"<br />
#include ".Xresources.d/xscreensaver"<br />
}}<br />
<br />
If files fail to load, specify the directory to ''xrdb'' with the {{ic|-I}} parameter. For example:<br />
<br />
{{hc|~/.xinitrc|<br />
xrdb -I''$HOME'' ~/.Xresources<br />
}}<br />
<br />
==Sample usage==<br />
The following samples should provide a good understanding of how application settings can be modified using an Xresources file. See [https://gist.github.com/anonymous/fa98de9fd70b51611303] for more examples. Refer to the man page of the application in question otherwise.<br />
<br />
===Terminal colors===<br />
Most terminals, including [[xterm]] and [[urxvt]], support at least 16 basic colors. The colors 0-7 are the 'normal' colors. Colors 8-15 are their 'bright' counterparts, used for highlighting. <br />
<br />
{{bc|<br />
! Black + DarkGrey<br />
*color0: #000000<br />
*color8: #555753<br />
! DarkRed + Red<br />
*color1: #ff6565<br />
*color9: #ff8d8d<br />
! DarkGreen + Green<br />
*color2: #93d44f<br />
*color10: #c8e7a8<br />
! DarkYellow + Yellow<br />
*color3: #eab93d<br />
*color11: #ffc123<br />
! DarkBlue + Blue<br />
*color4: #204a87<br />
*color12: #3465a4<br />
! DarkMagenta + Magenta<br />
*color5: #ce5c00<br />
*color13: #f57900<br />
!DarkCyan + Cyan (both not tango)<br />
*color6: #89b6e2<br />
*color14: #46a4ff<br />
! LightGrey + White<br />
*color7: #cccccc<br />
*color15: #ffffff<br />
}}<br />
<br />
See [[man page#Colored man pages on xterm or rxvt-unicode]] for how to color bold and underlined text automatically xterm and rxvt.<br />
<br />
{{Warning|Color resources such as {{ic|foreground}} and {{ic|background}} can be read by other applications (such as [https://www.gnu.org/software/emacs/manual/html_node/emacs/Table-of-Resources.html emacs]). This can be avoided by specifiying the class name, for example {{ic|XTerm.foreground}}.}}<br />
<br />
=== Xcursor ===<br />
<br />
See [[Cursor themes#X resources]].<br />
<br />
=== Xft ===<br />
<br />
See [[Font configuration#Applications without fontconfig support]].<br />
<br />
=== Xterm ===<br />
<br />
See [[Xterm#Configuration]].<br />
<br />
=== rxvt-unicode ===<br />
<br />
See [[Rxvt-unicode#Configuration]].<br />
<br />
=== Xpdf ===<br />
<br />
See {{ic|'''Options'''}} in [http://linux.die.net/man/1/xpdf man xpdf].<br />
<br />
==Color scheme commands==<br />
Here are some fast bash commands you can run right in your shell.<br />
<br />
===Display all 256 colors===<br />
Prints all 256 colors across the screen, very quick.<br />
<nowiki>(x=`tput op` y=`printf %76s`;for i in {0..256};do o=00$i;echo -e ${o:${#o}-3:3} `tput setaf $i;tput setab $i`${y// /=}$x;done)</nowiki><br />
<br />
===Display tput escape codes===<br />
Replace {{ic|tput op}} with whatever tput you want to trace. {{ic|op}} is the default foreground and background color.<br />
{{hc<br />
|<nowiki>$ ( strace -s5000 -e write tput op 2>&2 2>&1 ) | tee -a /dev/stderr | grep -o '"[^"]*"'</nowiki><br />
|033[\033[1;34m"\33[39;49m"\033[00m<br />
}}<br />
<br />
===Enumerating colors supported by terminals===<br />
The following command will let you discover all the terminals you have terminfo support for, and the number of colors each terminal supports. The possible values are: 8, 15, 16, 52, 64, 88 and 256.<br />
{{hc<br />
|<nowiki>$ for T in `find /usr/share/terminfo -type f -printf '%f '`;do echo "$T `tput -T $T colors`";done|sort -nk2</nowiki><br />
|Eterm-88color 88<br />
rxvt-88color 88<br />
xterm+88color 88<br />
xterm-88color 88<br />
Eterm-256color 256<br />
gnome-256color 256<br />
konsole-256color 256<br />
putty-256color 256<br />
rxvt-256color 256<br />
screen-256color 256<br />
screen-256color-bce 256<br />
screen-256color-bce-s 256<br />
screen-256color-s 256<br />
xterm+256color 256<br />
xterm-256color 256<br />
}}<br />
<br />
===Enumerating terminal capabilities===<br />
This command is useful to see what features that are supported by your terminal.<br />
{{hc<br />
|<nowiki>$ infocmp -1 | sed -nu 's/^[ \000\t]*//;s/[ \000\t]*$//;/[^ \t\000]\{1,\}/!d;/acsc/d;s/=.*,//p'|column -c80</nowiki><br />
|bel cuu ich kb2 kf15 kf3 kf44 kf59 mc0 rmso smul<br />
blink cuu1 il kbs kf16 kf30 kf45 kf6 mc4 rmul tbc<br />
bold cvvis il1 kcbt kf17 kf31 kf46 kf60 mc5 rs1 u6<br />
cbt dch ind kcub1 kf18 kf32 kf47 kf61 meml rs2 u7<br />
civis dch1 indn kcud1 kf19 kf33 kf48 kf62 memu sc u8<br />
clear dl initc kcuf1 kf2 kf34 kf49 kf63 op setab u9<br />
cnorm dl1 invis kcuu1 kf20 kf35 kf5 kf7 rc setaf vpa<br />
}}<br />
<br />
==Color scheme scripts==<br />
Any of the following scripts will display a chart of your current terminal color scheme. Handy for testing and whatnot.<br />
<br />
=== LUA ===<br />
<br />
{{bc|1=<br />
#!/usr/bin/env lua<br />
<br />
function cl(e)<br />
return string.format('\27[%sm', e)<br />
end<br />
<br />
function print_fg(bg, pre)<br />
for fg = 30,37 do<br />
fg = pre..fg<br />
io.write(cl(bg), cl(fg), string.format(' %6s ', fg), cl(0))<br />
end<br />
end<br />
<br />
for bg = 40,47 do<br />
io.write(cl(0), ' ', bg, ' ')<br />
print_fg(bg, ' ')<br />
io.write('\n ')<br />
print_fg(bg, '1;')<br />
io.write('\n\n')<br />
end<br />
<br />
-- Andres P<br />
}}<br />
<br />
=== Bash ===<br />
<br />
{{bc|1=<br />
#!/usr/bin/bash<br />
#<br />
# ANSI color scheme script featuring Space Invaders<br />
#<br />
# Original: http://crunchbang.org/forums/viewtopic.php?pid=126921%23p126921#p126921<br />
# Modified by lolilolicon<br />
#<br />
<br />
f=3 b=4<br />
for j in f b; do<br />
for i in {0..7}; do<br />
printf -v $j$i %b "\e[${!j}${i}m"<br />
done<br />
done<br />
bld=$'\e[1m'<br />
rst=$'\e[0m'<br />
<br />
cat << EOF<br />
<br />
$f1 ▀▄ ▄▀ $f2 ▄▄▄████▄▄▄ $f3 ▄██▄ $f4 ▀▄ ▄▀ $f5 ▄▄▄████▄▄▄ $f6 ▄██▄ $rst<br />
$f1 ▄█▀███▀█▄ $f2███▀▀██▀▀███ $f3▄█▀██▀█▄ $f4 ▄█▀███▀█▄ $f5███▀▀██▀▀███ $f6▄█▀██▀█▄$rst<br />
$f1█▀███████▀█ $f2▀▀███▀▀███▀▀ $f3▀█▀██▀█▀ $f4█▀███████▀█ $f5▀▀███▀▀███▀▀ $f6▀█▀██▀█▀$rst<br />
$f1▀ ▀▄▄ ▄▄▀ ▀ $f2 ▀█▄ ▀▀ ▄█▀ $f3▀▄ ▄▀ $f4▀ ▀▄▄ ▄▄▀ ▀ $f5 ▀█▄ ▀▀ ▄█▀ $f6▀▄ ▄▀$rst<br />
<br />
$bld$f1▄ ▀▄ ▄▀ ▄ $f2 ▄▄▄████▄▄▄ $f3 ▄██▄ $f4▄ ▀▄ ▄▀ ▄ $f5 ▄▄▄████▄▄▄ $f6 ▄██▄ $rst<br />
$bld$f1█▄█▀███▀█▄█ $f2███▀▀██▀▀███ $f3▄█▀██▀█▄ $f4█▄█▀███▀█▄█ $f5███▀▀██▀▀███ $f6▄█▀██▀█▄$rst<br />
$bld$f1▀█████████▀ $f2▀▀▀██▀▀██▀▀▀ $f3▀▀█▀▀█▀▀ $f4▀█████████▀ $f5▀▀▀██▀▀██▀▀▀ $f6▀▀█▀▀█▀▀$rst<br />
$bld$f1 ▄▀ ▀▄ $f2▄▄▀▀ ▀▀ ▀▀▄▄ $f3▄▀▄▀▀▄▀▄ $f4 ▄▀ ▀▄ $f5▄▄▀▀ ▀▀ ▀▀▄▄ $f6▄▀▄▀▀▄▀▄$rst<br />
<br />
<br />
$f7▌$rst<br />
<br />
$f7▌$rst<br />
<br />
$f7 ▄█▄ $rst<br />
$f7▄█████████▄$rst<br />
$f7▀▀▀▀▀▀▀▀▀▀▀$rst<br />
<br />
EOF<br />
}}<br />
<br />
=== Ruby ===<br />
<br />
{{bc|1= <br />
#!/usr/bin/env ruby<br />
# coding: utf-8<br />
<br />
# ANSI color scheme script <br />
# Author: Ivaylo Kuzev < Ivo ><br />
# Original: http://crunchbang.org/forums/viewtopic.php?pid=134749%23p134749#p134749<br />
# Modified using Ruby.<br />
<br />
CL = "\e[0m"<br />
BO = "\e[1m"<br />
<br />
R = "\e[31m" <br />
G = "\e[32m"<br />
Y = "\e[33m"<br />
B = "\e[34m"<br />
P = "\e[35m"<br />
C = "\e[36m"<br />
<br />
print <<EOF <br />
<br />
#{BO}#{R} ██████ #{CL} #{BO}#{G}██████ #{CL}#{BO}#{Y} ██████#{CL} #{BO}#{B}██████ #{CL} #{BO}#{P} ██████#{CL} #{BO}#{C} ███████#{CL}<br />
#{BO}#{R} ████████#{CL} #{BO}#{G}██ ██ #{CL}#{BO}#{Y}██ #{CL} #{BO}#{B}██ ██#{CL} #{BO}#{P}██████ #{CL} #{BO}#{C} █████████#{CL}<br />
#{R} ██ ████#{CL} #{G}██ ████#{CL}#{Y} ████ #{CL} #{B}████ ██#{CL} #{P}████ #{CL} #{C}█████ #{CL}<br />
#{R} ██ ██#{CL} #{G}██████ #{CL}#{Y} ████████#{CL} #{B}██████ #{CL} #{P}████████#{CL} #{C}██ #{CL}<br />
<br />
EOF<br />
}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Parsing errors ===<br />
<br />
[[Display manager]]s such as [[GDM]] and [[LightDM]] may use the {{ic|--nocpp}} argument for ''xrdb''. See [[LightDM#Xresources not being parsed correctly]].<br />
<br />
==See also==<br />
<br />
* [https://engineering.purdue.edu/ECN/Support/KB/Docs/UsingTheXdefaultsFil Using the Xdefaults File] - An in-depth article on how X interprets the Xdefaults file<br />
* [http://wiki.afterstep.org/index.php?title=Rxvt-Unicode_Configuration_Tutorial Rxvt-unicode Configuration Tutorial] - lots of information for urxvt users<br />
* [http://mkaz.com/solog/system/xterm-colors.html Example Colors and their names] - listing of example colors and their color names for xterm and other X-applications.<br />
* [https://web.archive.org/web/20090130061234/http://phraktured.net/terminal-colors/ Color Themes] - Extensive list of terminal color themes by Phraktured.<br />
* [http://xcolors.net/ Xcolors.net] List of user-contributed terminal color themes.<br />
* [http://beta.andrewrcraig.us/index.php?page=xcolors Xcolors by dkeg]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=ArchWiki:Sandbox&diff=430153ArchWiki:Sandbox2016-04-08T13:01:58Z<p>Sander Maijers: /* Code blocks */</p>
<hr />
<div>[[Category:Sandbox]]<br />
{{Related articles start}}<br />
{{Related|Help:Editing}}<br />
{{Related|Help:Style}}<br />
{{Related articles end}}<br />
''You can use this page to practise editing the wiki.''<br />
<br />
-------------------------------------------------------<br />
<br />
==test <br />
===dl<br />
====dt<br />
=====dd<br />
== test ==<br />
=== 1.1 ===<br />
<br />
this is paragraph 1<br />
<br />
this is another paragraph and another one.<br />
<br />
<dl><br />
<dt><br />
<i>file</i><b>.i</b></dt><br />
<dd><br />
C source code that should not be preprocessed.</dd><br />
</dl><br />
<dl><br />
<dt><br />
<i>file</i><b>.ii</b></dt><br />
<dd><br />
C++ source code that should not be preprocessed.</dd><br />
</dl><br />
<dl><br />
<dt><br />
<i>file</i><b>.m</b></dt><br />
<dd><br />
Objective-C source code. Note that you must link with the <br />
<i>libobjc</i> library to make an Objective-C program <br />
work.</dd><br />
</dl><br />
<br />
==Arch==<br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! test spoiler:<br />
|-<br />
| Cada uno es como Dios le hizo, y aún peor muchas veces.<br />
|}<br />
<br />
test test<br />
I can't live, if living is without 'U'<br />
<br />
== Test < > chars in pre and code ==<br />
<br />
this < is < sparta ><br />
<br />
what is this {{ic|thing <doing> <<< >>>}} here<br />
<br />
==test==<br />
===Third heading===<br />
This is a para also<br />
====Fourth heading====<br />
::Me too<br>New line<br />
<br />
'''''bold and italics'''''<br />
<br />
''''' Bold and italics are in five apostrophes'''''<br />
=====Fifth Level Heading=====<br />
no indent<br />
:indent<br />
::more indent<br />
:::and more<br />
"No andes, Sancho, desceñido y flojo, que el vestido descompuesto da indicios de ánimo desmalazado."<br />
<br />
==Ingredientes, panqueques con manjar!!==<br />
<br />
<br />
{{hc|Ingredientes Arch|<br />
<br />
* 2 Unidades de Huevos<br />
* 1 Taza de Harina<br />
* 1 Taza de Leche<br />
* 1 Cucharadita de Aceite<br />
* 1 Pizca de Sal<br />
* Manjar (dulce de leche)<br />
* 1 Paquete de Azúcar flor para decorar<br />
}}<br />
<br />
== Code block ==<br />
<br />
{{hc|Hello World program|<br />
#include <stdio.h><br />
int main(int argc, char* argv[])<br />
{<br />
printf("Hello World!\n");<br />
return 0;<br />
}<br />
}}<br />
<br />
== cb2 ==<br />
{{hc|asdf|<br />
lkl<br />
}}<br />
<br />
*bullet list<br />
*again<br />
**indent<br />
***more indent<br />
*bullet<br />
Link to pacman<br />
[[pacman]]<br />
'''Bold text'''''Italic text'' [http://www.example.com link title]<br />
<br />
<s>strike out</s><br />
<br />
test: asfd<br />
<br />
{{Note|This is a note.}}<br />
<br />
{{Note|This is another note}}<br />
<br />
:::testing indent<br />
testing indent<br />
{{hc|Lorem Ipsum|{{Lorem Ipsum}}}}<br />
<br />
== Template sandbox ==<br />
<br />
Section for testing [[Template:Sandbox]].<br />
<br />
{{Sandbox|Testing message.}}<br />
<br />
{{Sandbox|Msg|2=Second|talk=Talk|section=Section}}<br />
<br />
== Code blocks ==<br />
<br />
<pre><br />
<i>foo</i> [[bar]]<br />
</pre><br />
<br />
<i>foo</i> [[bar]]<br />
<br />
{{bc|<i>foo</i> [[bar]]}}<br />
<br />
Inline <code>monospace</code>.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=ArchWiki:Sandbox&diff=430152ArchWiki:Sandbox2016-04-08T13:01:45Z<p>Sander Maijers: /* Code blocks */</p>
<hr />
<div>[[Category:Sandbox]]<br />
{{Related articles start}}<br />
{{Related|Help:Editing}}<br />
{{Related|Help:Style}}<br />
{{Related articles end}}<br />
''You can use this page to practise editing the wiki.''<br />
<br />
-------------------------------------------------------<br />
<br />
==test <br />
===dl<br />
====dt<br />
=====dd<br />
== test ==<br />
=== 1.1 ===<br />
<br />
this is paragraph 1<br />
<br />
this is another paragraph and another one.<br />
<br />
<dl><br />
<dt><br />
<i>file</i><b>.i</b></dt><br />
<dd><br />
C source code that should not be preprocessed.</dd><br />
</dl><br />
<dl><br />
<dt><br />
<i>file</i><b>.ii</b></dt><br />
<dd><br />
C++ source code that should not be preprocessed.</dd><br />
</dl><br />
<dl><br />
<dt><br />
<i>file</i><b>.m</b></dt><br />
<dd><br />
Objective-C source code. Note that you must link with the <br />
<i>libobjc</i> library to make an Objective-C program <br />
work.</dd><br />
</dl><br />
<br />
==Arch==<br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! test spoiler:<br />
|-<br />
| Cada uno es como Dios le hizo, y aún peor muchas veces.<br />
|}<br />
<br />
test test<br />
I can't live, if living is without 'U'<br />
<br />
== Test < > chars in pre and code ==<br />
<br />
this < is < sparta ><br />
<br />
what is this {{ic|thing <doing> <<< >>>}} here<br />
<br />
==test==<br />
===Third heading===<br />
This is a para also<br />
====Fourth heading====<br />
::Me too<br>New line<br />
<br />
'''''bold and italics'''''<br />
<br />
''''' Bold and italics are in five apostrophes'''''<br />
=====Fifth Level Heading=====<br />
no indent<br />
:indent<br />
::more indent<br />
:::and more<br />
"No andes, Sancho, desceñido y flojo, que el vestido descompuesto da indicios de ánimo desmalazado."<br />
<br />
==Ingredientes, panqueques con manjar!!==<br />
<br />
<br />
{{hc|Ingredientes Arch|<br />
<br />
* 2 Unidades de Huevos<br />
* 1 Taza de Harina<br />
* 1 Taza de Leche<br />
* 1 Cucharadita de Aceite<br />
* 1 Pizca de Sal<br />
* Manjar (dulce de leche)<br />
* 1 Paquete de Azúcar flor para decorar<br />
}}<br />
<br />
== Code block ==<br />
<br />
{{hc|Hello World program|<br />
#include <stdio.h><br />
int main(int argc, char* argv[])<br />
{<br />
printf("Hello World!\n");<br />
return 0;<br />
}<br />
}}<br />
<br />
== cb2 ==<br />
{{hc|asdf|<br />
lkl<br />
}}<br />
<br />
*bullet list<br />
*again<br />
**indent<br />
***more indent<br />
*bullet<br />
Link to pacman<br />
[[pacman]]<br />
'''Bold text'''''Italic text'' [http://www.example.com link title]<br />
<br />
<s>strike out</s><br />
<br />
test: asfd<br />
<br />
{{Note|This is a note.}}<br />
<br />
{{Note|This is another note}}<br />
<br />
:::testing indent<br />
testing indent<br />
{{hc|Lorem Ipsum|{{Lorem Ipsum}}}}<br />
<br />
== Template sandbox ==<br />
<br />
Section for testing [[Template:Sandbox]].<br />
<br />
{{Sandbox|Testing message.}}<br />
<br />
{{Sandbox|Msg|2=Second|talk=Talk|section=Section}}<br />
<br />
== Code blocks ==<br />
<br />
<pre><br />
<i>foo</i> [[bar]]<br />
</pre><br />
<br />
<i>foo</i> [[bar]]<br />
<br />
{{bc|<i>foo</i> [[bar]]}}<br />
<br />
Inline `monospace`.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=ArchWiki:Sandbox&diff=430151ArchWiki:Sandbox2016-04-08T13:01:32Z<p>Sander Maijers: /* Code blocks */</p>
<hr />
<div>[[Category:Sandbox]]<br />
{{Related articles start}}<br />
{{Related|Help:Editing}}<br />
{{Related|Help:Style}}<br />
{{Related articles end}}<br />
''You can use this page to practise editing the wiki.''<br />
<br />
-------------------------------------------------------<br />
<br />
==test <br />
===dl<br />
====dt<br />
=====dd<br />
== test ==<br />
=== 1.1 ===<br />
<br />
this is paragraph 1<br />
<br />
this is another paragraph and another one.<br />
<br />
<dl><br />
<dt><br />
<i>file</i><b>.i</b></dt><br />
<dd><br />
C source code that should not be preprocessed.</dd><br />
</dl><br />
<dl><br />
<dt><br />
<i>file</i><b>.ii</b></dt><br />
<dd><br />
C++ source code that should not be preprocessed.</dd><br />
</dl><br />
<dl><br />
<dt><br />
<i>file</i><b>.m</b></dt><br />
<dd><br />
Objective-C source code. Note that you must link with the <br />
<i>libobjc</i> library to make an Objective-C program <br />
work.</dd><br />
</dl><br />
<br />
==Arch==<br />
<br />
{| class="wikitable mw-collapsible mw-collapsed"<br />
! test spoiler:<br />
|-<br />
| Cada uno es como Dios le hizo, y aún peor muchas veces.<br />
|}<br />
<br />
test test<br />
I can't live, if living is without 'U'<br />
<br />
== Test < > chars in pre and code ==<br />
<br />
this < is < sparta ><br />
<br />
what is this {{ic|thing <doing> <<< >>>}} here<br />
<br />
==test==<br />
===Third heading===<br />
This is a para also<br />
====Fourth heading====<br />
::Me too<br>New line<br />
<br />
'''''bold and italics'''''<br />
<br />
''''' Bold and italics are in five apostrophes'''''<br />
=====Fifth Level Heading=====<br />
no indent<br />
:indent<br />
::more indent<br />
:::and more<br />
"No andes, Sancho, desceñido y flojo, que el vestido descompuesto da indicios de ánimo desmalazado."<br />
<br />
==Ingredientes, panqueques con manjar!!==<br />
<br />
<br />
{{hc|Ingredientes Arch|<br />
<br />
* 2 Unidades de Huevos<br />
* 1 Taza de Harina<br />
* 1 Taza de Leche<br />
* 1 Cucharadita de Aceite<br />
* 1 Pizca de Sal<br />
* Manjar (dulce de leche)<br />
* 1 Paquete de Azúcar flor para decorar<br />
}}<br />
<br />
== Code block ==<br />
<br />
{{hc|Hello World program|<br />
#include <stdio.h><br />
int main(int argc, char* argv[])<br />
{<br />
printf("Hello World!\n");<br />
return 0;<br />
}<br />
}}<br />
<br />
== cb2 ==<br />
{{hc|asdf|<br />
lkl<br />
}}<br />
<br />
*bullet list<br />
*again<br />
**indent<br />
***more indent<br />
*bullet<br />
Link to pacman<br />
[[pacman]]<br />
'''Bold text'''''Italic text'' [http://www.example.com link title]<br />
<br />
<s>strike out</s><br />
<br />
test: asfd<br />
<br />
{{Note|This is a note.}}<br />
<br />
{{Note|This is another note}}<br />
<br />
:::testing indent<br />
testing indent<br />
{{hc|Lorem Ipsum|{{Lorem Ipsum}}}}<br />
<br />
== Template sandbox ==<br />
<br />
Section for testing [[Template:Sandbox]].<br />
<br />
{{Sandbox|Testing message.}}<br />
<br />
{{Sandbox|Msg|2=Second|talk=Talk|section=Section}}<br />
<br />
== Code blocks ==<br />
<br />
<pre><br />
<i>foo</i> [[bar]]<br />
</pre><br />
<br />
<i>foo</i> [[bar]]<br />
<br />
{{bc|<i>foo</i> [[bar]]}}<br />
<br />
Inline {{monospace}}.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=General_troubleshooting&diff=430017General troubleshooting2016-04-07T10:45:10Z<p>Sander Maijers: contents: initial major rewrite of ‘Attention to detail’ to more grammatical and concise English. I do believe this section is unnecessary, elitist and overly verbose. A one-sentence comment would do.</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:System recovery]]<br />
[[es:General troubleshooting]]<br />
[[ja:一般的なトラブルシューティング]]<br />
[[ru:General troubleshooting]]<br />
{{Related articles start}}<br />
{{Related|Reporting bug guidelines}}<br />
{{Related|Step-by-step debugging guide}}<br />
{{Related|Debug - Getting Traces}}<br />
{{Related|Boot debugging}}<br />
{{Related|IRC Collaborative Debugging}}<br />
{{Related articles end}}<br />
<br />
This article explains some methods for general troubleshooting. For application specific issues, please reference the particular wiki page for that program.<br />
<br />
== General procedures ==<br />
<br />
=== Attention to detail ===<br />
<br />
In order to resolve an issue that you are having, it is ''absolutely crucial'' to have a firm basic understanding of how that specific subsystem functions. How it works, and what does it need to run without error? If you cannot comfortably answer these question then you would best review the [[Table of contents|Archwiki]] article for the subsystem that you are having trouble with. Once you feel like you've understood it, it will be easier for you to pinpoint the cause of the problem. <br />
<br />
=== Questions/checklist ===<br />
<br />
The following gives a number of questions for you whenever dealing with a malfunctioning system. Under each question there are notes explaining how you should be answering each question, followed by some light examples on how to easily gather data output and what tools can be used to review logs and the journal.<br />
<br />
# What is the issue(s)?<br />
#: Be ''as precise as possible''. This will help you not get confused and/or side-tracked when looking up specific information.<br />
# Are there error messages? (if any)<br />
#: Copy and paste ''full outputs'' that contain '''error messages''' related to your issue into a separate file, such as {{ic|$HOME/issue.log}}. For example, to forward the output of the following [[mkinitcpio]] command to {{ic|$HOME/issue.log}}:<br />
#: {{bc|$ mkinitcpio -p linux >> $HOME/issue.log''}}<br />
# Can you reproduce the issue?<br />
#: If so, give ''exact'' '''step-by-step''' instructions/commands needed to do so.<br />
# When did you first encounter these issues and what was changed between then and when the system was operating without error?<br />
#:If it occurred right after an update then, list '''all packages that were updated'''. Include ''version numbers'', also, paste the entire update from [[pacman]].log ({{ic|/var/log/pacman.log}}). Also take note of the statuses of ''any'' service(s) needed to support the malfunctioning application(s) using [[systemd]]'s systemctl tools. For example, to forward the output of the following [[Systemd#Basic_systemctl_usage|systemd]] command to {{ic|$HOME/issue.log}}:<br />
#: {{bc|$ systemctl status dhcpcd@eth0.service >> $HOME/issue.log}}<br />
#: {{Note|Using {{ic|'''>>'''}} will ensure any previous text in {{ic|$HOME/issue.log}} will not be overwritten.}}<br />
<br />
=== Be more specific ===<br />
<br />
When attempting to resolve an issue, '''never''' approach it as: <br />
<br />
''Application X does not work.''<br />
<br />
Instead, look at it in its entirety: <br />
<br />
''Application X produces Y error(s) when performing Z tasks under conditions A and B.<br />
<br />
=== Additional support ===<br />
<br />
With all the information in front of you you should have a good idea as to what is going on with the system and you can now start working on a proper fix.<br />
<br />
If you require any additional support, it can be found on [https://bbs.archlinux.org the forums] or IRC at irc.freenode.net #archlinux<br />
<br />
== Boot problems ==<br />
<br />
See [[Boot debugging]] to retrieve additional information.<br />
<br />
=== Blank screen with Intel video ===<br />
<br />
This is most likely due to a problem with [[kernel mode setting]]. Try [[Kernel mode setting#Disabling modesetting|disabling modesetting]] or changing the [[Intel#KMS Issue: console is limited to small area|video port]].<br />
<br />
=== Stuck while loading the kernel ===<br />
<br />
Try disabling ACPI by adding the {{ic|1=acpi=off}} kernel parameter.<br />
<br />
=== Unbootable system ===<br />
<br />
If your system will not boot at all, simply boot from a [https://www.archlinux.org/download/ live image] and [[change root]] to log into the system and fix the issue.<br />
<br />
=== Debugging kernel modules ===<br />
<br />
See [[Kernel modules#Obtaining information]].<br />
<br />
=== Debugging hardware ===<br />
<br />
See [[udev#Debug output]].<br />
<br />
== Package management ==<br />
<br />
See [[Pacman#Troubleshooting]] for general topics, and [[pacman/Package signing#Troubleshooting]] for issues with PGP keys.<br />
<br />
== fuser ==<br />
<br />
{{Expansion|Write an example how to use it.}}<br />
<br />
''fuser'' is a command-line utility for identifying processes using resources such as files, filesystems and TCP/UDP ports.<br />
<br />
''fuser'' is provided by the {{Pkg|psmisc}} package, which should be already installed as part of the {{Grp|base}} group.<br />
<br />
== Session permissions ==<br />
<br />
{{Note|You must be using [[systemd]] as your init system for local sessions to work.[https://www.archlinux.org/news/d-bus-now-launches-user-buses/] It is required for polkit permissions and ACLs for various devices (see {{ic|/usr/lib/udev/rules.d/70-uaccess.rules}} and [http://enotty.pipebreaker.pl/2012/05/23/linux-automatic-user-acl-management/])}}<br />
<br />
First, make sure you have a valid local session within X:<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
This should contain {{ic|1=Remote=no}} and {{ic|1=Active=yes}} in the output. If it does not, make sure that X runs on the same tty where the login occurred. This is required in order to preserve the logind session. This is handled by the default {{ic|/etc/X11/xinit/xserverrc}}.<br />
<br />
A D-Bus session should also be started along with X. See [[D-Bus#Starting the user session]] for more information on this.<br />
<br />
Basic [[polkit]] actions do not require further set-up. Some polkit actions require further authentication, even with a local session. A polkit authentication agent needs to be running for this to work. See [[polkit#Authentication agents]] for more information on this.<br />
<br />
== error while loading shared libraries ==<br />
<br />
{{Accuracy|Or the program needs to be rebuilt after a [[System_maintenance#Partial_upgrades_are_unsupported|soname bump]].}}<br />
<br />
If, while using a program, you get an error similar to: <br />
<br />
error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory<br />
<br />
Use [[pacman]] or [[pkgfile]] to search for the package that owns the missing library:<br />
<br />
{{hc|$ pacman -Fs libusb-0.1.so.4|<br />
extra/libusb-compat 0.1.5-1<br />
usr/lib/libusb-0.1.so.4<br />
}}<br />
<br />
In this case, the {{Pkg|libusb-compat}} package needs to be [[installed]].<br />
<br />
The error could also mean that the package that you used to install your program does not list the library as a dependency in its [[PKGBUILD]]: if it is an official package, [[report a bug]]; if it is an [[AUR]] package, report it to the maintainer using its page in the AUR website.<br />
<br />
== file: could not find any magic files! ==<br />
<br />
{{Style|See [[Help:Style]] and related articles.}}<br />
<br />
''Example:'' After an every-day routine update or following the installation of a package you are given the following error:<br />
# file: could not find any magic files!<br />
This will most likely leave your system crippled. And, any attempts made to recompile/reinstall the package(s) responsible for the breakage will fail. Also, any attempts made to try to rebuild the [[initramfs]] will result in the following:<br />
# mkinitcpio -p linux<br />
==> Building image from preset: 'default'<br />
-> -k /boot/vmlinuz-linux -c /etc/mkinitcpio.conf -g /boot/initramfs-linux.img<br />
file: could not find any magic files!<br />
==> ERROR: invalid kernel specifier: `/boot/vmlinuz-linux'<br />
==> Building image from preset: 'fallback'<br />
-> -k /boot/vmlinuz-linux -c /etc/mkinitcpio.conf -g /boot/initramfs-linux-fallback.img -S autodetect<br />
file: could not find any magic files!<br />
@==> ERROR: invalid kernel specifier: `/boot/vmlinuz-linux'<br />
<br />
Typically a previously installed application had placed a configuration file within {{ic|/etc/ld.so.conf.d/}} or it had made changes to {{ic|/etc/ld.so.conf}} which are now invalid.<br />
#Boot into the Arch Linux Live CD / Installation Media.<br />
#Mount your root ({{ic|'''/'''}}) partition to {{ic|/mnt}} and using [[Change root#Change_root|arch-chroot]], [[chroot]] into your system.<br />
{{Note|[[Change root#Change_root|arch-chroot]] leaves mounting the {{ic|/boot}} partition up to the user.}}<br />
#Examine {{ic|/etc/ld.so.conf}} and remove any invalid lines found.<br />
#Examine the files located inside the directory {{ic|/etc/ld.so.conf.d/}} and remove all invalid files.<br />
#Rebuild the [[initramfs]].<br />
# mkinitcpio -p linux<br />
#Reboot back to your installed system.<br />
#Once booted, reinstall the package that was responsible for leaving your system inoperable using:<br />
# pacman -S <package><br />
<br />
== Spellcheck is marking all of my text as incorrect! ==<br />
<br />
{{Move|aspell|2=This can't be considered "general", what about creating a new article, since ''aspell'' is mentioned from [https://wiki.archlinux.org/index.php?title=Special%3ASearch&search=aspell many] articles?}}<br />
<br />
Have you installed an {{Pkg|aspell}} dictionary? Use {{ic|pacman -Ss aspell}} to see available dictionaries for downloading.<br />
<br />
If installing the dictionary files did not resolve the problem, it is most likely a problem with {{ic|enchant}}. Check for known dictionary files:<br />
<br />
{{hc|$ aspell dicts|<br />
en<br />
en_GB<br />
...etc}}<br />
<br />
If your respective language dictionary is listed, add it to {{ic|/usr/share/enchant/enchant.ordering}}. From the above example, it would be:<br />
<br />
en_GB:aspell<br />
<br />
== See also ==<br />
<br />
* [http://www.maximumpc.com/article/features/linux_troubleshooting_guide_fix_most_common_problems Fix the Most Common Problems]<br />
* [https://www.reddit.com/r/archlinux/comments/tjjwr/archlinux_a_howto_in_troubleshooting_for_newcomers/ A how-to in troubleshooting for newcomers]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=General_troubleshooting&diff=430016General troubleshooting2016-04-07T10:40:05Z<p>Sander Maijers: contents: remove extraneous and uninformative section on NTFS. It does not belong under ‘General troubleshooting’.</p>
<hr />
<div>[[Category:System administration]]<br />
[[Category:System recovery]]<br />
[[es:General troubleshooting]]<br />
[[ja:一般的なトラブルシューティング]]<br />
[[ru:General troubleshooting]]<br />
{{Related articles start}}<br />
{{Related|Reporting bug guidelines}}<br />
{{Related|Step-by-step debugging guide}}<br />
{{Related|Debug - Getting Traces}}<br />
{{Related|Boot debugging}}<br />
{{Related|IRC Collaborative Debugging}}<br />
{{Related articles end}}<br />
<br />
This article explains some methods for general troubleshooting. For application specific issues, please reference the particular wiki page for that program.<br />
<br />
== General procedures ==<br />
<br />
=== Attention to detail ===<br />
<br />
In order to resolve an issue that you are having, it is ''absolutely crucial'' to have a firm understanding of how that specific system functions. How it works, and what does it need to run without error? If you cannot comfortably answer these question then it is strongly advised that you review the [[Table of contents|Archwiki]] article for the function that you are having troubles with. Once you feel like you've understood the specific system, it will be easier for you to pin-point the problem. <br />
<br />
=== Questions / checklist ===<br />
<br />
The following gives a number of questions for you whenever dealing with a malfunctioning system. Under each question there are notes explaining how you should be answering each question, followed by some light examples on how to easily gather data output and what tools can be used to review logs and the journal.<br />
<br />
# What is the issue(s)?<br />
#: Be ''as precise as possible''. This will help you not get confused and/or side-tracked when looking up specific information.<br />
# Are there error messages? (if any)<br />
#: Copy and paste ''full outputs'' that contain '''error messages''' related to your issue into a separate file, such as {{ic|$HOME/issue.log}}. For example, to forward the output of the following [[mkinitcpio]] command to {{ic|$HOME/issue.log}}:<br />
#: {{bc|$ mkinitcpio -p linux >> $HOME/issue.log''}}<br />
# Can you reproduce the issue?<br />
#: If so, give ''exact'' '''step-by-step''' instructions/commands needed to do so.<br />
# When did you first encounter these issues and what was changed between then and when the system was operating without error?<br />
#:If it occurred right after an update then, list '''all packages that were updated'''. Include ''version numbers'', also, paste the entire update from [[pacman]].log ({{ic|/var/log/pacman.log}}). Also take note of the statuses of ''any'' service(s) needed to support the malfunctioning application(s) using [[systemd]]'s systemctl tools. For example, to forward the output of the following [[Systemd#Basic_systemctl_usage|systemd]] command to {{ic|$HOME/issue.log}}:<br />
#: {{bc|$ systemctl status dhcpcd@eth0.service >> $HOME/issue.log}}<br />
#: {{Note|Using {{ic|'''>>'''}} will ensure any previous text in {{ic|$HOME/issue.log}} will not be overwritten.}}<br />
<br />
=== Be more specific ===<br />
<br />
When attempting to resolve an issue, '''never''' approach it as: <br />
<br />
''Application X does not work.''<br />
<br />
Instead, look at it in its entirety: <br />
<br />
''Application X produces Y error(s) when performing Z tasks under conditions A and B.<br />
<br />
=== Additional support ===<br />
<br />
With all the information in front of you you should have a good idea as to what is going on with the system and you can now start working on a proper fix.<br />
<br />
If you require any additional support, it can be found on [https://bbs.archlinux.org the forums] or IRC at irc.freenode.net #archlinux<br />
<br />
== Boot problems ==<br />
<br />
See [[Boot debugging]] to retrieve additional information.<br />
<br />
=== Blank screen with Intel video ===<br />
<br />
This is most likely due to a problem with [[kernel mode setting]]. Try [[Kernel mode setting#Disabling modesetting|disabling modesetting]] or changing the [[Intel#KMS Issue: console is limited to small area|video port]].<br />
<br />
=== Stuck while loading the kernel ===<br />
<br />
Try disabling ACPI by adding the {{ic|1=acpi=off}} kernel parameter.<br />
<br />
=== Unbootable system ===<br />
<br />
If your system will not boot at all, simply boot from a [https://www.archlinux.org/download/ live image] and [[change root]] to log into the system and fix the issue.<br />
<br />
=== Debugging kernel modules ===<br />
<br />
See [[Kernel modules#Obtaining information]].<br />
<br />
=== Debugging hardware ===<br />
<br />
See [[udev#Debug output]].<br />
<br />
== Package management ==<br />
<br />
See [[Pacman#Troubleshooting]] for general topics, and [[pacman/Package signing#Troubleshooting]] for issues with PGP keys.<br />
<br />
== fuser ==<br />
<br />
{{Expansion|Write an example how to use it.}}<br />
<br />
''fuser'' is a command-line utility for identifying processes using resources such as files, filesystems and TCP/UDP ports.<br />
<br />
''fuser'' is provided by the {{Pkg|psmisc}} package, which should be already installed as part of the {{Grp|base}} group.<br />
<br />
== Session permissions ==<br />
<br />
{{Note|You must be using [[systemd]] as your init system for local sessions to work.[https://www.archlinux.org/news/d-bus-now-launches-user-buses/] It is required for polkit permissions and ACLs for various devices (see {{ic|/usr/lib/udev/rules.d/70-uaccess.rules}} and [http://enotty.pipebreaker.pl/2012/05/23/linux-automatic-user-acl-management/])}}<br />
<br />
First, make sure you have a valid local session within X:<br />
<br />
$ loginctl show-session $XDG_SESSION_ID<br />
<br />
This should contain {{ic|1=Remote=no}} and {{ic|1=Active=yes}} in the output. If it does not, make sure that X runs on the same tty where the login occurred. This is required in order to preserve the logind session. This is handled by the default {{ic|/etc/X11/xinit/xserverrc}}.<br />
<br />
A D-Bus session should also be started along with X. See [[D-Bus#Starting the user session]] for more information on this.<br />
<br />
Basic [[polkit]] actions do not require further set-up. Some polkit actions require further authentication, even with a local session. A polkit authentication agent needs to be running for this to work. See [[polkit#Authentication agents]] for more information on this.<br />
<br />
== error while loading shared libraries ==<br />
<br />
{{Accuracy|Or the program needs to be rebuilt after a [[System_maintenance#Partial_upgrades_are_unsupported|soname bump]].}}<br />
<br />
If, while using a program, you get an error similar to: <br />
<br />
error while loading shared libraries: libusb-0.1.so.4: cannot open shared object file: No such file or directory<br />
<br />
Use [[pacman]] or [[pkgfile]] to search for the package that owns the missing library:<br />
<br />
{{hc|$ pacman -Fs libusb-0.1.so.4|<br />
extra/libusb-compat 0.1.5-1<br />
usr/lib/libusb-0.1.so.4<br />
}}<br />
<br />
In this case, the {{Pkg|libusb-compat}} package needs to be [[installed]].<br />
<br />
The error could also mean that the package that you used to install your program does not list the library as a dependency in its [[PKGBUILD]]: if it is an official package, [[report a bug]]; if it is an [[AUR]] package, report it to the maintainer using its page in the AUR website.<br />
<br />
== file: could not find any magic files! ==<br />
<br />
{{Style|See [[Help:Style]] and related articles.}}<br />
<br />
''Example:'' After an every-day routine update or following the installation of a package you are given the following error:<br />
# file: could not find any magic files!<br />
This will most likely leave your system crippled. And, any attempts made to recompile/reinstall the package(s) responsible for the breakage will fail. Also, any attempts made to try to rebuild the [[initramfs]] will result in the following:<br />
# mkinitcpio -p linux<br />
==> Building image from preset: 'default'<br />
-> -k /boot/vmlinuz-linux -c /etc/mkinitcpio.conf -g /boot/initramfs-linux.img<br />
file: could not find any magic files!<br />
==> ERROR: invalid kernel specifier: `/boot/vmlinuz-linux'<br />
==> Building image from preset: 'fallback'<br />
-> -k /boot/vmlinuz-linux -c /etc/mkinitcpio.conf -g /boot/initramfs-linux-fallback.img -S autodetect<br />
file: could not find any magic files!<br />
@==> ERROR: invalid kernel specifier: `/boot/vmlinuz-linux'<br />
<br />
Typically a previously installed application had placed a configuration file within {{ic|/etc/ld.so.conf.d/}} or it had made changes to {{ic|/etc/ld.so.conf}} which are now invalid.<br />
#Boot into the Arch Linux Live CD / Installation Media.<br />
#Mount your root ({{ic|'''/'''}}) partition to {{ic|/mnt}} and using [[Change root#Change_root|arch-chroot]], [[chroot]] into your system.<br />
{{Note|[[Change root#Change_root|arch-chroot]] leaves mounting the {{ic|/boot}} partition up to the user.}}<br />
#Examine {{ic|/etc/ld.so.conf}} and remove any invalid lines found.<br />
#Examine the files located inside the directory {{ic|/etc/ld.so.conf.d/}} and remove all invalid files.<br />
#Rebuild the [[initramfs]].<br />
# mkinitcpio -p linux<br />
#Reboot back to your installed system.<br />
#Once booted, reinstall the package that was responsible for leaving your system inoperable using:<br />
# pacman -S <package><br />
<br />
== Spellcheck is marking all of my text as incorrect! ==<br />
<br />
{{Move|aspell|2=This can't be considered "general", what about creating a new article, since ''aspell'' is mentioned from [https://wiki.archlinux.org/index.php?title=Special%3ASearch&search=aspell many] articles?}}<br />
<br />
Have you installed an {{Pkg|aspell}} dictionary? Use {{ic|pacman -Ss aspell}} to see available dictionaries for downloading.<br />
<br />
If installing the dictionary files did not resolve the problem, it is most likely a problem with {{ic|enchant}}. Check for known dictionary files:<br />
<br />
{{hc|$ aspell dicts|<br />
en<br />
en_GB<br />
...etc}}<br />
<br />
If your respective language dictionary is listed, add it to {{ic|/usr/share/enchant/enchant.ordering}}. From the above example, it would be:<br />
<br />
en_GB:aspell<br />
<br />
== See also ==<br />
<br />
* [http://www.maximumpc.com/article/features/linux_troubleshooting_guide_fix_most_common_problems Fix the Most Common Problems]<br />
* [https://www.reddit.com/r/archlinux/comments/tjjwr/archlinux_a_howto_in_troubleshooting_for_newcomers/ A how-to in troubleshooting for newcomers]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=428373GnuPG2016-03-28T19:11:39Z<p>Sander Maijers: typo</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as [[Wikipedia:PGP|PGP]]). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<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 />
== Environment variables ==<br />
<br />
=== GNUPGHOME ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. You may change this default by setting {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
{{Note|By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.}}<br />
<br />
== Configuration files ==<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or use the {{ic|$GNUPGHOME}} environment variable. Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
== 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 />
* Some of these steps may be provided by an external program depending on your usage, such as an [[List_of_applications/Internet#Email_clients|email client]]. See also [[List of applications/Security#Encryption, signing, steganography]].}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since the semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Place the private key in a safe place, such as a locked container or encrypted drive.<br />
<br />
{{Warning|Anyone who gains access to the above exported file will be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase.}}<br />
<br />
=== Export your public key ===<br />
<br />
In order for others to send encrypted messages to you, they need your public key.<br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --armor --output ''public.key'' --export ''<user-id>''<br />
<br />
Alternatively, or in addition, you can share your key [[#Use a keyserver|on a keyserver]].<br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, find a public key [[#Use a keyserver|on a keyserver]].<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|--keyserver}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jirk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmgr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
When encrypting or decrypting it is possible to have more than one private key in use. If this occurs you need to select the active key by using the option {{ic|-u ''<user-id>''}} or {{ic|--local-user ''<user-id>''}}.<br />
<br />
To encrypt a file named {{ic|''doc''}} using ASCII armor (suitable for copying and pasting a message in text format), use:<br />
<br />
$ gpg --encrypt --armor ''doc''<br />
<br />
If you want to just encrypt a file, exclude {{ic|--armor}}.<br />
<br />
{{Tip|<br />
* If you want to change recipient this can be done by the option {{ic|-r ''<user-id>''}} (or {{ic|--recipient ''<user-id>''}}).<br />
* Add {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|--recipient}} 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 />
<br />
{{Note|You can use gnupg to encrypt your sensitive documents, but only individual files at a time. If you want to encrypt directories or a whole file-system you should consider using [[TrueCrypt]] or [[EncFS]], though you can always tarball various files and then encrypt them.}}<br />
<br />
To decrypt a file, use:<br />
<br />
$ gpg --decrypt ''doc.asc''<br />
<br />
You will be prompted to enter your passphrase. You will need to have already [[#Import a key|imported]] the sender's public key to decrypt a file or message from them.<br />
<br />
== Key maintenance ==<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|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 />
=== 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 />
== 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 />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third part.<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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent'':<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="${HOME}/.gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
Also set the GPG TTY and refresh the TTY in case user has switched into an X session. Example:<br />
<br />
{{Expansion|Not clear why this is necessary (even tha man page does not explain it).}}<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|libusb-compat}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
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 together with OpenSC ===<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}} or bundled together with other useful tools in the package {{AUR|signing-party-svn}}{{Broken package link|{{aur-mirror|signing-party-svn}}}}.<br />
Either way, there will be a lot of dependencies installing from the AUR. Alternatively you can install them from CPAN with<br />
cpanm Any::Moose<br />
cpanm GnuPG::Interface<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 />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
{{Accuracy|Is {{ic|MODE&#61;"664"}} necessary? Assigning a group, {{ic|MODE&#61;"660"}} may be enough?}}<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="664", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=GnuPG&diff=428372GnuPG2016-03-28T19:11:06Z<p>Sander Maijers: Add source and better motivation of ‘no comment field’ advice.</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
{{Related articles start}}<br />
{{Related|pacman/Package signing}}<br />
{{Related|Disk encryption}}<br />
{{Related|List of applications/Security#Encryption, signing, steganography}}<br />
{{Related articles end}}<br />
<br />
According to the [http://www.gnupg.org official website]:<br />
<br />
:GnuPG is a complete and free implementation of the OpenPGP standard as defined by RFC4880 (also known as [[Wikipedia:PGP|PGP]]). GnuPG allows to encrypt and sign your data and communication, features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. Which ''pinentry'' dialog is used is determined by the symbolic link {{ic|/usr/bin/pinentry}}, which by default points to {{ic|/usr/bin/pinentry-gtk-2}}.<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 />
== Environment variables ==<br />
<br />
=== GNUPGHOME ===<br />
<br />
{{ic|$GNUPGHOME}} is used by GnuPG to point to the directory where its configuration files are stored. By default {{ic|$GNUPGHOME}} is not set and your {{ic|$HOME}} is used instead; thus, you will find a {{ic|~/.gnupg}} directory right after installation. You may change this default by setting {{ic|GNUPGHOME}} in one of your regular [[startup files]].<br />
<br />
{{Note|By default, the gnupg directory has its [[permissions]] set to {{ic|700}} and the files it contains have their permissions set to {{ic|600}}. Only the owner of the directory has permission to read, write, and access the files. This is for security purposes and should not be changed. In case this directory or any file inside it does not follow this security measure, you will get warnings about unsafe file and home directory permissions.}}<br />
<br />
== Configuration files ==<br />
<br />
The default configuration files are {{ic|~/.gnupg/gpg.conf}} and {{ic|~/.gnupg/dirmngr.conf}}. To change the default location, either run gpg this way {{ic|$ gpg --homedir ''path/to/file''}} or use the {{ic|$GNUPGHOME}} environment variable. Append to these files any long options you want. Do not write the two dashes, but simply the name of the option and required arguments. You will find skeleton files in {{ic|/usr/share/gnupg}}. These files are copied to {{ic|~/.gnupg}} the first time gpg is run if they do not exist there. Other examples are found in [[#See also]].<br />
<br />
Additionally, [[pacman]] uses a different set of configuration files for package signature verification. See [[Pacman/Package signing]] for details.<br />
<br />
== 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 />
* Some of these steps may be provided by an external program depending on your usage, such as an [[List_of_applications/Internet#Email_clients|email client]]. See also [[List of applications/Security#Encryption, signing, steganography]].}}<br />
<br />
=== Create key pair ===<br />
<br />
Generate a key pair by typing in a terminal:<br />
<br />
$ gpg --full-gen-key<br />
<br />
{{Tip|Use the {{ic|--expert}} option for getting alternative ciphers like [[wikipedia:Elliptic_curve_cryptography|ECC]].}}<br />
<br />
The command will prompt for answers to several questions. For general use most people will want: <br />
<br />
* the RSA (sign only) and a RSA (encrypt only) key.<br />
* a keysize of the default value (2048). A larger keysize of 4096 "gives us almost nothing, while costing us quite a lot"[https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096].<br />
* an expiration date. A period of a year is good enough for the average user. This way even if access is lost to the keyring, it will allow others to know that it is no longer valid. Later, if necessary, the expiration date can be extended without having to re-issue a new key.<br />
* your name and email address. You can add multiple identities to the same key later (''e.g.'', if you have multiple email addresses you want to associate with this key).<br />
* ''no'' optional comment. Since them semantics of the comment field are [https://lists.gnupg.org/pipermail/gnupg-devel/2015-July/030150.html not well-defined], it has limited value for identification.<br />
* [[Security#Choosing_secure_passwords|a secure passphrase]].<br />
<br />
{{Note|The name and email address you enter here will be seen by anybody who imports your key.}}<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Place the private key in a safe place, such as a locked container or encrypted drive.<br />
<br />
{{Warning|Anyone who gains access to the above exported file will be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase.}}<br />
<br />
=== Export your public key ===<br />
<br />
In order for others to send encrypted messages to you, they need your public key.<br />
<br />
To generate an ASCII version of your public key (''e.g.'' to distribute it by e-mail):<br />
<br />
$ gpg --armor --output ''public.key'' --export ''<user-id>''<br />
<br />
Alternatively, or in addition, you can share your key [[#Use a keyserver|on a keyserver]].<br />
<br />
{{Tip|Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.}}<br />
<br />
=== Import a key ===<br />
<br />
In order to encrypt messages to others, as well as verify their signatures, you need their public key. To import a public key with file name {{ic|''public.key''}} to your public key ring:<br />
<br />
$ gpg --import ''public.key''<br />
<br />
Alternatively, find a public key [[#Use a keyserver|on a keyserver]].<br />
<br />
=== Use a keyserver ===<br />
<br />
You can register your key with a public PGP key server, so that others can retrieve your key without having to contact you directly:<br />
<br />
$ gpg --send-keys ''<key-id>''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''<key-id>''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''<key-id>''<br />
<br />
{{Warning|Anyone can send keys to a keyserver, so you should not trust that the key you download actually belongs to the individual listed. You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source, such as their own blog or website, or contacting them by email, over the phone or in person. Using multiple authentication sources will increase the level of trust you can give to the downloaded key. See [[Wikipedia:Public key fingerprint]] for more information.}}<br />
<br />
{{Tip|<br />
* An alternative key server is {{ic|pool.sks-keyservers.net}} and can be specified with {{ic|--keyserver}}; see also [[wikipedia:Key server (cryptographic)#Keyserver examples]].<br />
* You can connect to the keyserver over [[Tor]] using {{ic|--use-tor}}. {{ic|hkp://jirk5u4osbsr34t5.onion}} is the onion address for the sks-keyservers pool. [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html See this GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmgr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
When encrypting or decrypting it is possible to have more than one private key in use. If this occurs you need to select the active key by using the option {{ic|-u ''<user-id>''}} or {{ic|--local-user ''<user-id>''}}.<br />
<br />
To encrypt a file named {{ic|''doc''}} using ASCII armor (suitable for copying and pasting a message in text format), use:<br />
<br />
$ gpg --encrypt --armor ''doc''<br />
<br />
If you want to just encrypt a file, exclude {{ic|--armor}}.<br />
<br />
{{Tip|<br />
* If you want to change recipient this can be done by the option {{ic|-r ''<user-id>''}} (or {{ic|--recipient ''<user-id>''}}).<br />
* Add {{ic|-R ''<user-id>''}} or {{ic|--hidden-recipient ''<user-id>''}} instead of {{ic|--recipient}} 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 />
<br />
{{Note|You can use gnupg to encrypt your sensitive documents, but only individual files at a time. If you want to encrypt directories or a whole file-system you should consider using [[TrueCrypt]] or [[EncFS]], though you can always tarball various files and then encrypt them.}}<br />
<br />
To decrypt a file, use:<br />
<br />
$ gpg --decrypt ''doc.asc''<br />
<br />
You will be prompted to enter your passphrase. You will need to have already [[#Import a key|imported]] the sender's public key to decrypt a file or message from them.<br />
<br />
== Key maintenance ==<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{Note|You do not need to create a new key simply because it is expired. You can extend the expiration date.}}<br />
<br />
Create new subkey (repeat for both signing and encrypting key)<br />
<br />
$ gpg --edit-key ''<user-id>''<br />
> addkey<br />
<br />
And answer the following questions it asks (see previous section 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 />
{{Note|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 />
=== 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 />
== 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 />
=== Sign a file ===<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc.sig'' --sign ''doc''<br />
<br />
The above also encrypts the file and stores it in binary format.<br />
<br />
=== Clearsign a file or message ===<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --clearsign ''doc''<br />
<br />
This wraps the document into an ASCII-armored signature, but does not modify the document.<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 />
This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third part.<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 signature you wish to verify.<br />
<br />
To verify and decrypt a file at the same time, use the {{ic|--decrypt}} flag as you normally would in decrypting a file.<br />
<br />
If you are verifying a detached signature, both the file and the signature must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify ''archlinux-<version>-dual.iso.sig''<br />
<br />
where {{ic|''archlinux-<version>-dual.iso''}} must be located in the same directory.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<br />
<br />
Starting with GnuPG 2.1.0 the use of ''gpg-agent'' is required. ''gpg-agent'' is started on-demand by the GnuPG tools, so there is usually no reason to start it manually.<br />
<br />
=== Configuration ===<br />
<br />
gpg-agent can be configured via {{ic|~/.gnupg/gpg-agent.conf}} file. The configuration options are listed in {{ic|man gpg-agent}}. For example you can change cache ttl for unused keys:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl 3600<br />
}}<br />
<br />
{{Tip|To cache your passphrase for the whole session, please run the following command:<br />
$ /usr/lib/gnupg/gpg-preset-passphrase --preset XXXXXX<br />
<br />
where XXXX is the keygrip. You can get its value when running {{ic|gpg --with-keygrip -K}}. Passphrase will be stored until {{ic|gpg-agent}} is restarted. If you set up {{ic|default-cache-ttl}} value, it will take precedence.<br />
}}<br />
<br />
=== Reload the agent ===<br />
<br />
After changing the configuration, reload the agent using ''gpg-connect-agent'':<br />
<br />
$ gpg-connect-agent reloadagent /bye<br />
<br />
The command should print {{ic|OK}}.<br />
<br />
=== pinentry ===<br />
<br />
Finally, the agent needs to know how to ask the user for the password. This can be set in the gpg-agent configuration file.<br />
<br />
The default uses a gtk dialog. There are other options - see {{ic|info pinentry}}. To change the dialog implementation set {{ic|pinentry-program}} configuration option:<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
<br />
# PIN entry program<br />
# pinentry-program /usr/bin/pinentry-curses<br />
# pinentry-program /usr/bin/pinentry-qt<br />
# pinentry-program /usr/bin/pinentry-kwallet<br />
<br />
pinentry-program /usr/bin/pinentry-gtk-2<br />
}}<br />
<br />
{{Tip|For using {{ic|/usr/bin/pinentry-kwallet}} you have to install the {{Pkg|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
Create a systemd unit file:<br />
<br />
{{hc|~/.config/systemd/user/gpg-agent.service|2=<br />
[Unit]<br />
Description=GnuPG private key agent<br />
IgnoreOnIsolate=true<br />
<br />
[Service]<br />
Type=forking<br />
ExecStart=/usr/bin/gpg-agent --daemon<br />
Restart=on-abort<br />
<br />
[Install]<br />
WantedBy=default.target<br />
}}<br />
<br />
{{Note|If you use non-default value for the [[#GNUPGHOME]] environment variable, you need to pass it to the service. See [[systemd/User#Environment variables]] for details.}}<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|1=~/.gnupg/gpg-agent.conf|2=<br />
allow-loopback-pinentry<br />
}}<br />
<br />
Restart the gpg-agent process if it is running to let the change take effect.<br />
<br />
Second, either the application needs to be updated to include a commandline parameter to use loopback mode like so:<br />
<br />
$ gpg --pinentry-mode loopback ...<br />
<br />
...or if this is not possible, add the option to the configuration:<br />
<br />
{{hc|1=~/.gnupg/gpg.conf|2=<br />
pinentry-mode loopback<br />
}}<br />
<br />
{{Note|The upstream author indicates setting {{ic|pinentry-mode loopback}} in {{ic|gpg.conf}} may break other usage, using the commandline option should be preferred if at all possible. [https://bugs.g10code.com/gnupg/issue1772]}}<br />
<br />
=== SSH agent ===<br />
<br />
''gpg-agent'' has OpenSSH agent emulation. If you already use the GnuPG suite, you might consider using its agent to also cache your SSH keys. Additionally, some users may prefer the PIN entry dialog GnuPG agent provides as part of its passphrase management.<br />
<br />
To start using GnuPG agent for your SSH keys, enable SSH support in the {{ic|~/.gnupg/gpg-agent.conf}} file:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
enable-ssh-support<br />
}}<br />
<br />
Next, make sure that ''gpg-agent'' is always started. Use either the [[#Start gpg-agent with systemd user|systemd user service]] or add the following to your {{ic|.bashrc}} file:<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Start the gpg-agent if not already running<br />
if ! pgrep -x -u "${USER}" gpg-agent >/dev/null 2>&1; then<br />
gpg-connect-agent /bye >/dev/null 2>&1<br />
fi<br />
</nowiki>}}<br />
<br />
Then set {{ic|SSH_AUTH_SOCK}} so that SSH will use ''gpg-agent'' instead of ''ssh-agent'':<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set SSH to use gpg-agent<br />
unset SSH_AGENT_PID<br />
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then<br />
export SSH_AUTH_SOCK="${HOME}/.gnupg/S.gpg-agent.ssh"<br />
fi<br />
</nowiki>}}<br />
<br />
Also set the GPG TTY and refresh the TTY in case user has switched into an X session. Example:<br />
<br />
{{Expansion|Not clear why this is necessary (even tha man page does not explain it).}}<br />
<br />
{{hc|~/.bashrc|<nowiki><br />
# Set GPG TTY<br />
export GPG_TTY=$(tty)<br />
<br />
# Refresh gpg-agent tty in case user switches into an X session<br />
gpg-connect-agent updatestartuptty /bye >/dev/null<br />
</nowiki>}}<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. Once your key is approved, you will get a ''pinentry'' dialog every time your passphrase is needed. You can control passphrase caching in the {{ic|~/.gnupg/gpg-agent.conf}} file. The following example would have ''gpg-agent'' cache your keys for 3 hours:<br />
<br />
{{hc|~/.gnupg/gpg-agent.conf|<br />
default-cache-ttl-ssh 10800<br />
}}<br />
<br />
== Smartcards ==<br />
<br />
{{Note|{{Pkg|pcsclite}} and {{Pkg|libusb-compat}} have to be installed, and the contained [[systemd#Using units|systemd]] service {{ic|pcscd.service}} has to be running.}}<br />
<br />
GnuPG uses ''scdaemon'' as an interface to your smartcard reader, please refer to the [[man page]] for details.<br />
<br />
=== GnuPG only setups ===<br />
<br />
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 together with OpenSC ===<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 {{Ic|man scdaemon}} if you do not use OpenSC.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Different algorithm ===<br />
<br />
You may want to use stronger algorithms:<br />
<br />
{{hc|~/.gnupg/gpg.conf|<br />
...<br />
<br />
personal-digest-preferences SHA512<br />
cert-digest-algo SHA512<br />
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed<br />
personal-cipher-preferences TWOFISH CAMELLIA256 AES 3DES<br />
}}<br />
<br />
In the latest version of GnuPG, the default algorithms used are SHA256 and AES, both of which are secure enough for most people. However, if you are using a version of GnuPG older than 2.1, or if you want an even higher level of security, then you should follow the above step.<br />
<br />
=== Encrypt a password ===<br />
<br />
It can be useful to encrypt some password, so it will not be written in clear on a configuration file. A good example is your email password.<br />
<br />
First create a file with your password. You '''need''' to leave '''one''' empty line after the password, otherwise gpg will return an error message when evaluating the file.<br />
<br />
Then run:<br />
<br />
$ gpg -e -a -r ''<user-id>'' ''your_password_file''<br />
<br />
{{ic|-e}} is for encrypt, {{ic|-a}} for armor (ASCII output), {{ic|-r}} for recipient user ID.<br />
<br />
You will be left with a new {{ic|''your_password_file''.asc}} file.<br />
<br />
=== 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 />
=== Revoking a key ===<br />
<br />
{{Warning|<br />
*Anybody having access to your revocation certificate can revoke your key, rendering it useless.<br />
*Key revocation should only be performed if your key is compromised or lost, or you forget your passphrase.}}<br />
<br />
Revocation certificates are automatically generated for newly generated keys, although one can be generated manually by the user later. These are located at {{ic|~/.gnupg/openpgp-revocs.d/}}. The filename of the certificate is the fingerprint of the key it will revoke.<br />
<br />
To revoke your key, simply import the revocation certificate:<br />
<br />
$ gpg --import ''<fingerprint>''.rev<br />
<br />
Now update the keyserver:<br />
<br />
$ gpg --keyserver subkeys.pgp.net --send ''<userid>''<br />
<br />
=== Change trust model ===<br />
<br />
By default GnuPG uses the [[Wikipedia::Web of Trust|Web of Trust]] as the trust model. You can change this to [[Wikipedia::Trust on First|Trust on First]] Use by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses he [[Wikipedia::Web of Trust|Web of Trust]]. Keysigning parties allow users to get together in physical location to validate keys. The [[Wikipedia:Zimmermann–Sassaman key-signing protocol|Zimmermann-Sassaman]] key-signing protocol is a way of making these very effective. [http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html Here] you will find a how-to article.<br />
<br />
For an easier process of signing keys and sending signatures to the owners after a keysigning party, you can use the tool ''caff''. It can be installed from the AUR with the package {{AUR|caff-svn}} or bundled together with other useful tools in the package {{AUR|signing-party-svn}}{{Broken package link|{{aur-mirror|signing-party-svn}}}}.<br />
Either way, there will be a lot of dependencies installing from the AUR. Alternatively you can install them from CPAN with<br />
cpanm Any::Moose<br />
cpanm GnuPG::Interface<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 />
== Troubleshooting ==<br />
<br />
=== Not enough random bytes available ===<br />
When generating a key, gpg can run into this error:<br />
Not enough random bytes available. Please do some other work to give the OS a chance to collect more entropy!<br />
To check the available entropy, check the kernel parameters:<br />
cat /proc/sys/kernel/random/entropy_avail<br />
A healthy Linux system with a lot of entropy available will have return close to the full 4,096 bits of entropy. If the value returned is less than 200, the system is running low on entropy. <br />
<br />
To solve it, remember you do not often need to create keys and best just do what the message suggests (e.g. create disk activity, move the mouse, edit the wiki - all will create entropy). If that does not help, check which service is using up the entropy and consider stopping it for the time. If that is no alternative, see [[Random number generation#Faster alternatives]].<br />
<br />
=== su ===<br />
<br />
When using {{Ic|pinentry}}, you must have the proper permissions of the terminal device (e.g. {{Ic|/dev/tty1}}) in use. However, with ''su'' (or ''sudo''), the ownership stays with the original user, not the new one. This means that pinentry will fail, even as root. The fix is to change the permissions of the device at some point before the use of pinentry (i.e. using gpg with an agent). If doing gpg as root, simply change the ownership to root right before using gpg:<br />
<br />
chown root /dev/ttyN # where N is the current tty<br />
<br />
and then change it back after using gpg the first time. The equivalent is likely to be true with {{Ic|/dev/pts/}}.<br />
<br />
{{Note|The owner of tty ''must'' match with the user for which pinentry is running. Being part of the group {{Ic|tty}} '''is not''' enough.}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is pinentry-gtk-2, which needs a DBus session bus to run properly. See [[General troubleshooting#Session permissions]] for details.<br />
<br />
Alternatively, you can use {{ic|pinentry-qt}}. See [[#pinentry]].<br />
<br />
=== KGpg configuration permissions ===<br />
<br />
There have been issues with {{Pkg|kdeutils-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 />
Another user reported that ''KGpg'' failed to start until the {{ic|~/.gnupg}} folder is set to {{ic|drwxr-xr-x}} permissions. If you require this work-around, ensure that the directory contents retain {{ic|-rw-------}} permissions! Further, report it as a bug to the [https://bugs.kde.org/buglist.cgi?quicksearch=kgpg developers].<br />
<br />
=== Conflicts between gnome-keyring and gpg-agent ===<br />
<br />
{{Accuracy|See [[#GPG_AGENT_INFO]]}}<br />
<br />
While the Gnome keyring implements a GPG agent component, as of GnuPG version 2.1, GnuPG ignores the {{ic|GPG_AGENT_INFO}} environment variable, so that Gnome keyring can no longer be used as a GPG agent.<br />
<br />
However, since version 0.9.6 the package {{Pkg|pinentry}} provides the {{Ic|pinentry-gnome3}} program. You may set the following option in your {{Ic|gpg-agent.conf}} file<br />
pinentry-program /usr/bin/pinentry-gnome3<br />
in order to make use of that pinentry program.<br />
<br />
Since version 0.9.2 all pinentry programs can be configured to optionally save a passphrase with libsecret. For example, when the user is asked for a passphrase via {{Ic|pinentry-gnome3}}, a checkbox is shown whether to save the passphrase using a password manager. Unfortunately, the package {{Pkg|pinentry}} does not have this feature enabled (see {{Bug|46059}} for the reasons). You may use {{AUR|pinentry-libsecret}} as a replacement for it, which has support for libsecret enabled.<br />
<br />
=== mutt and gpg ===<br />
<br />
To be asked for your GnuPG password only once per session as of GnuPG 2.1, see [https://bbs.archlinux.org/viewtopic.php?pid=1490821#p1490821 this forum thread].<br />
<br />
=== "Lost" keys, upgrading to gnupg version 2.1 ===<br />
<br />
When {{ic|gpg --list-keys}} fails to show keys that used to be there, and applications complain about missing or invalid keys, some keys may not have been migrated to the new format.<br />
<br />
Please read [http://jo-ke.name/wp/?p=111 GnuPG invalid packet workaround]. Basically, it says that there is a bug with keys in the old {{ic|pubring.gpg}} and {{ic|secring.gpg}} files, which have now been superseded by the new {{ic|pubring.kbx}} file and the {{ic|private-keys-v1.d/}} subdirectory and files. Your missing keys can be recovered with the following commnads:<br />
<br />
$ cd<br />
$ cp -r .gnupg gnupgOLD<br />
$ gpg --export-ownertrust > otrust.txt<br />
$ gpg --import .gnupg/pubring.gpg<br />
$ gpg --import-ownertrust otrust.txt<br />
$ gpg --list-keys<br />
<br />
=== gpg hanged for all keyservers (when trying to receive keys) ===<br />
<br />
If gpg hanged with a certain keyserver when trying to receive keys, you might need to kill dirmngr in order to get access to other keyservers which are actually working, otherwise it might keeping hanging for all of them.<br />
<br />
=== Smartcard not detected ===<br />
<br />
Your user might not have the permission to access the smartcard which results in a {{ic|card error}} to be thrown, even though the card is correctly set up and inserted.<br />
<br />
One possible solution is to add a new group {{ic|scard}} including the users who need access to the smartcard.<br />
{{Accuracy|Is {{ic|MODE&#61;"664"}} necessary? Assigning a group, {{ic|MODE&#61;"660"}} may be enough?}}<br />
Then use an [[Udev#Writing_udev_rules|udev]] rule, similar to the following:<br />
{{hc|/etc/udev/rules.d/71-gnupg-ccid.rules|<nowiki><br />
ACTION=="add", SUBSYSTEM=="usb", ENV{ID_VENDOR_ID}=="1050", ENV{ID_MODEL_ID}=="0116|0111", MODE="664", GROUP="scard"<br />
</nowiki>}}<br />
One needs to adapt VENDOR and MODEL according to the {{ic|lsusb}} output, the above example is for a YubikeyNEO.<br />
<br />
== See also ==<br />
<br />
* [https://gnupg.org/ GNU Privacy Guard Homepage]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [http://blog.sanctum.geek.nz/series/linux-crypto/ A more comprehensive gpg Tutorial]<br />
* [https://help.riseup.net/en/security/message-security/openpgp/gpg-best-practices gpg.conf recommendations and best practices]<br />
* [https://github.com/ioerror/torbirdy/blob/master/gpg.conf Torbirdy gpg.conf]<br />
* [https://www.reddit.com/r/GPGpractice/ /r/GPGpractice - a subreddit to practice using GnuPG.]</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=R&diff=412883R2015-12-20T11:26:16Z<p>Sander Maijers: ENHANCE: Add link discussing under what circumstances installing Intel MKL will cause problems with parallel computing in R.</p>
<hr />
<div>[[Category:Mathematics and science]]<br />
[[Category:Programming languages]]<br />
[[ja:R]]<br />
{{Related articles start}}<br />
{{Related|Intel C++}}<br />
{{Related articles end}}<br />
''R is a free software environment for statistical computing and graphics'' (http://www.r-project.org/).<br />
<br />
== Installation ==<br />
=== Basic package ===<br />
<br />
[[Install]] the {{Pkg|r}} package available in the [[official repositories]]<br />
<br />
Some external packages may require to be compiled in Fortran as well, so [[installing]] the {{Pkg|gcc-fortran}} can be a good idea<br />
<br />
=== Initial configuration ===<br />
<br />
Please refer to [http://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html Initialization at Start of an R Session] to get a detailed understanding of startup process.<br />
The home directory of the {{ic|R}} installation is {{ic|/usr/lib/R}}. Base packages are found in {{ic|/usr/lib/R/library/base}} and '''site''' configuration files in {{ic|/etc/R/}}. Aspects of the [[Locale]] are accessed by the functions {{ic|Sys.getlocale}} and {{ic|Sys.localeconv}} within the {{ic|R}} session. Locales will be the one defined in your system.<br />
<br />
To start a {{ic|R}} session, open your terminal and type this command:<br />
$ R<br />
{{Note|<br />
* Use {{ic|Shift+u}} for the command (some shells use the {{ic|r}} letter to repeat the last entered command). Once in your {{ic|R}} session, the prompt will change to {{ic|>}}<br />
* '''site''' refers to '''system-wide''' in R Documentation}}<br />
Run {{ic|??Startup}} to read the documentation about system file configuration, {{ic|help()}} for the on-line help,{{ic|help.start()}} for the HTML browser interface to help, {{ic|demo()}} for some demos and {{ic|q()}} to close the session and quit.<br />
<br />
When closing the session, you will be prompted : {{ic|Save workspace Image ?[y/n/c]}}. The ''workspace'' is your current working environment and include any user-defined objects, functions. The saved image is stored in {{ic|.RData}} format and will be automatically reloaded the next time {{ic|R}} is started. You can manually save the workspace at any time in the session with the {{ic|save.image(image.RData)}} command, save as many images as you want (eg : ''image1.RData'', ''image2.RData''). You can load image with the {{ic|load.image(image.RData)}} command at any time of your session.<br />
<br />
{{Tip| <br />
* Tired of R's verbose startup message ? Then start {{ic|R}} with the {{ic|--quiet}} command-line option.<br />
{{ic|$ R --quiet}}<br />
You can {{ic|alias R &#61;"R --quiet"}} in one of your [[Startup files]]<br />
* Unless explicitly defined somewhere in your configuration files, {{ic|R}} will start in your $HOME directory. If you want to start in a specific directory. first time you create the directory do this:<br />
$ R<br />
> setwd("path/to/your/directory")<br />
> q()<br />
Save workspace image? [y/n/c]: y<br />
{{ic|R}} will create a '''.RData''' image file of your current environment. Then, when double-clicking this file, {{ic|R}} will automatically change its working directory to the file's directory.<br />
* colorize console output:<br />
> download.file("http://www.lepem.ufc.br/jaa/vimr/colorout_1.1-1.tar.gz", destfile &#61; "colorout_1.1-1.tar.gz")<br />
> install.packages("colorout_1.1-1.tar.gz", type &#61; "source", repos &#61; NULL)<br />
}}<br />
<br />
===Variables===<br />
{{ic|R}} can be confusing when it comes to [[Environment variables]], as they are large and duplicated following the '''site''' or '''user''' sides. There are two sorts of files used in startup: ''environment files'', defined by {{ic|$R_ENVIRON}} and ''profile files'', defined by {{ic|$R_PROFILE}}.<br />
<br />
Most important variables can be found on [http://stat.ethz.ch/R-manual/R-devel/library/base/html/EnvVar.html Environment Variables R Documentation]].<br />
====R_ENVIRON====<br />
At startup, {{ic|R}} search at early stage for '''site''' and '''user''' {{ic|.Renviron}} files to process for setting [[Environment variables]]. The '''site''' file is located in {{ic|/etc/R}}, and generated by configure.<br />
<br />
The name of the user file can be specified by the {{ic|R_ENVIRON_USER}} [[Environment variables]]. <br />
If you do not specify any file, {{ic|R}} will automatically read {{ic|.Renviron}} in your home directory if there is one. In case you want to use another emplacement for this file, append this line {{ic| export R_ENVIRON_USER &#61;"path/to/.Renviron"}} in one of your [[Startup files]]. This is the place to set all kind of environment variables using the '''R syntax'''.<br />
<br />
====R_PROFILE====<br />
Then {{ic|R}} searches for the '''site-wilde''' {{ic|Rprofile.site}} defined by the {{ic|R_PROFILE}} [[Environment variables]]. This file does not exist after a fresh installation.<br />
Finally, {{ic|R}} seraches for '''user''' {{ic|R_PROFILE_USER}}. if unset, a file called {{ic|.Rprofile}} is searched for in the current directory, returned by the {{ic|R}} command {{ic|> getwd()}} or in the user's home directory. This is the place to put all your custom {{ic|R}} code.<br />
<br />
== Installing R packages ==<br />
There are many add-on {{ic|R}} packages, which can be browsed on [http://cran.r-project.org/web/packages/available_packages_by_date.html The R Website.]. They can be installed from within {{ic|R}} using the {{ic|'''install.packages(c("pkgname"))'''}} command. {{ic|R}} can install its packages locally as '''per user''' local settings or '''system wide'''. <br />
<br />
Within your {{ic|R }} session, run this command to check that your user library exists and is set correctly:<br />
{{hc|> Sys.getenv("R_LIBS_USER")|<br />
[1] "/path/to/directory/R/packages"}}<br />
Installation within your {{ic|R}} session is the safest way and will not conflict with the [[pacman]] package management, but there is another method to install packages. Run the following command in your terminal:<br />
<br />
{{bc|$ R CMD INSTALL -l $R_LIBS_USER ''pkg1 pkg2 ...''}}<br />
<br />
=== Upgrading R packages ===<br />
==== Within a R session ====<br />
> update.packages(ask=FALSE)<br />
Or when you also need to rebuild packages which were built for an older version:<br />
> update.packages(ask=FALSE,checkBuilt=TRUE)<br />
{{Tip|upgrading packages from your '''R''' session can quickly be a pain if you have too many loaded packages at start up. For packages to be upgraded, they need to be ''not loaded''. Best practice is to start a new clean R session this way: {{ic| R --vanilla}} then run the upgrade.<br />
}}<br />
==== Within a shell ====<br />
First, [[Install]] {{AUR|littler}} from the [[Arch User Repository]]. This package allows direct execution of '''R''' commands and can be seen as a scripting front-end. Then, visit [http://dirk.eddelbuettel.com/code/littler.examples.html dirk.eddelbuettel] webiste about '''littler'''. Below is the script to run packages updates:<br />
{{bc|<br />
#!/usr/bin/env r <br />
#<br />
# a simple example to update packages in /usr/local/lib/R/site-library<br />
# parameters are easily adjustable<br />
<br />
repos <- "http://cran.rstudio.com"<br />
<br />
lib.loc <- Sys.getenv("R_LIBS_USER")<br />
<br />
update.packages(repos&#61;repos, ask&#61;FALSE, lib.loc&#61;lib.loc)<br />
}}<br />
<br />
Put this script in your favorite place and make it executable. Of course, feel free to modify the repo URL and the library location.<br />
<br />
{{Warning|when using [[zsh]], '''r''' is a builtin command. You will have to either use an explicit path {{ic|/usr/bin/r}} or create an alias under a different name.}}<br />
<br />
==Configuration files==<br />
<br />
The two user configuration files you want in your home folder are {{ic|.Renviron}} and {{ic|Rprofile.r}}. If you want to keep your {{ic|$HOME}} directory as clean as possible, a good practice will be to make the {{ic|~/.config/r}} directory, put the {{ic|Rprofile.r}} file at the root of the directory and append all your {{ic|R}} code in this file.<br />
===.Renviron===<br />
Lines in {{ic|Renviron}} file should be either comment lines starting with '''#''' or lines of the form ''name&#61;value''.Here is a very basic {{ic|.Renviron}} you can start with:<br />
{{hc|.Renviron| <br />
R_HOME_USER &#61; /path/to/your/r/directory<br />
R_PROFILE_USER &#61; ${HOME}/.config/r/Rprofile.r<br />
R_LIBS_USER &#61; /path/to/your/r/library<br />
R_HISTFILE &#61; /path/to/your/filename.Rhistory # Do not forget to append the '''.Rhistory'''<br />
R_DEFAULT_PACKAGES &#61; 'datasets,utils,grDevices,graphics,stats,methods,rJava,colorout' # load some default packages at start up<br />
MYSQL_HOME &#61; /var/lib/mysql <br />
}}<br />
<br />
===Rprofile.r===<br />
For convenient reasons, you can put a specific {{ic|Rprofile.r}} in each of your usual working directories. One facility would be to dedicate one directory per project, with its specific profile. When {{ic|R}} will change to the working directory, it will then read the {{ic|Rprofile.r}} file inside it.<br />
<br />
Here is a very short list of useful options and code:<br />
{{hc|Rprofile.r|<br />
setwd("path/to/startup/directory") # define a start up working directory<br />
.First <- function(){<br />
#welcome message<br />
message("Welcome back ", Sys.getenv("USER"),"!\n","working directory is:", getwd())<br />
} <br />
options(prompt &#61; paste(paste (Sys.info () [c ("user", "nodename")], collapse &#61; "@"),"[R] ")) # customize your R prompt with username and hostname in this format: '''user@hostname [R]'''<br />
options(digits &#61; 12) # number of digits to print. Default is 7, max is 15<br />
options(stringsAsFactors &#61; FALSE)<br />
options(show.signif.stars &#61; FALSE)<br />
error &#61; quote(dump.frames("${R_HOME_USER}/testdump", TRUE)) # post-mortem debugiging facilities<br />
}}<br />
You can add more [http://stat.ethz.ch/R-manual/R-devel/library/base/html/options.html global options] to customize your {{ic|R}} environment.<br />
See this [http://stackoverflow.com/questions/1189759/expert-r-users-whats-in-your-rprofile post] for more user configurations.<br />
<br />
== Adding a graphical frontend to R ==<br />
<br />
The linux version of R does not include a graphical user interface. However, third-party user interfaces for R are available, such as R commander and RKWard. <br />
<br />
=== R Commander frontend ===<br />
R Commander is a popular user interface to R. There is no Arch linux package available to install R commander, but it is an R package so it can be installed easily from within R. R Commander requires {{Pkg|tk}} to be [[installed]].<br />
<br />
To install R Commander, run 'R' from the command line. Then type:<br />
> install.packages("Rcmdr", dependencies=TRUE)<br />
<br />
This can take some time.<br />
<br />
You can then start R Commander from within R using the library command:<br />
<br />
> library("Rcmdr")<br />
<br />
=== RKWard frontend ===<br />
RKWard is an open-source frontend which allows for data import and browsing as well as running common statistical tests and plots. You can install {{AUR|rkward}} from [[AUR]].<br />
<br />
=== Rstudio IDE ===<br />
RStudio an open-source R IDE. It includes many modern conveniences such as parentheses matching, tab-completion, tool-tip help popups, and a spreadsheet-like data viewer.<br />
<br />
Install {{AUR|rstudio-desktop-bin}} (binary version from the Rstudio project website) or {{AUR|rstudio-desktop-git}} (development version) from [[AUR]].<br />
<br />
The R library path is often configured with the R_LIBS environment variable. RStudio ignores this, so the user must set R_LIBS_USER in {{ic|~/.Renviron}}, as documented above.<br />
<br />
=== Rstudio server ===<br />
<br />
RStudio Server enables you to provide a browser based interface to a version of R running on a remote Linux server.<br />
<br />
Install {{AUR|rstudio-server-git}}. The two main configuration files are {{ic|/etc/rstudio/rserver.conf}} and {{ic|/etc/rstudio/rsession.conf}}. They are not created during the install, so you will need to ''create'' and ''edit'' them. For information about configure options, please refer to [https://support.rstudio.com/hc/en-us/articles/200552306-Getting-Started rstudio getting started] documentation.<br />
<br />
To start the server, please [[Systemd#Using_units|enable and start]] the {{ic|rstudio-server.service}} unit file provided with the package.<br />
<br />
=== Emacs Speaks Statistics ===<br />
{{Pkg|emacs}} users can interact with R via the {{AUR|emacs-ess}} package.<br />
<br />
=== Vim-R ===<br />
The {{AUR|vim-r}} package allows {{Pkg|vim}} users to code in R, including editing and rendering of R markdown (Rmd) files, execution of R code in a separate pane, inspection of variables, and integrated help panes.<br />
<br />
== Optimized packages ==<br />
The numerical libraries that comes with the R (generic {{Pkg|blas}}, LAPACK) do not have multithreading capabilities. Replacing the reference {{Pkg|blas}} package with an optimized BLAS can produce dramatic speed increases for many common computations in R. However the available optimized BLAS packages all have drawbacks such as requiring a commercial license or [http://blog.revolutionanalytics.com/2015/10/edge-cases-in-using-the-intel-mkl-and-parallel-programming.html potentially interfering with the standard R functionality for parallel processing]. If you really need faster linear algebra in R you may consider the following options.<br />
<br />
=== OpenBLAS ===<br />
{{AUR|openblas}} can be installed from the [[AUR]], replacing the reference {{Pkg|blas}} from extra. If you are using the regular {{Pkg|r}} package from extra no further configuration is needed; R is configured to use the system BLAS and will use OpenBLAS once it is installed.<br />
=== Intel MKL ===<br />
'''If your processors are Intel''', it is strongly advised to use the [http://software.intel.com/en-us/intel-mkl Intel math Kernel Library]. The '''MKL''', beyond the capabilities of multithreading, also has specific optimizations for Intel processors, with performance far superior to traditional libraries.<br />
<br />
Please first [[Install]] the {{AUR|intel-mkl}} package available from [[AUR]], then the {{AUR|r-mkl}} package.<br />
<br />
{{Note| <br />
* if you install the {{AUR|r-mkl}} with '''R''' already installed, you will be prompted to remove '''R'''. Once '''r-mkl''' is installed, please run on '''R''' console the following command :<br />
{{ic|> update.packages(checkBuilt&#61;TRUE)}}<br />
* here are elapsed time in sec from computing 15 tests with default GCC build and icc/MKL build: ''274.93 sec'' for GCC build, ''21.01 sec'' for icc/MKL build. See [https://stat.ethz.ch/pipermail/r-help/2014-September/421574.html this post] for more information.<br />
}}<br />
<br />
=== intel-parallel-studio-xe ===<br />
[http://software.intel.com/en-us/intel-parallel-studio-xe intel-parallel-studio] delivers top application performance with C, C++ and Fortran compilers, libraries and analysis tools.<br />
<br />
First, install the {{AUR|intel-parallel-studio-xe}}{{Broken package link|{{aur-mirror|intel-parallel-studio-xe}}}} package. You may need to login again for /etc/profile.d/intel_compilers.sh to be loaded (so the compiler bin is in the PATH). Then, modify the {{AUR|r-mkl}} {{ic|PKGBUILD}} file with appending these lines in the {{ic|build()}} section:<br />
<br />
{{bc|<nowiki><br />
# please refer to the intel-parallel-studio-xe package version for path<br />
_omplibpath=/opt/intel/${_parallel_studio_xe_dir}/compiler/lib/${_intel_arch} <br />
export LD_LIBRARY_PATH=${_mkllibpath}:${_omplibpath} <br />
.....................................................<br />
# Build the package using the icc compiler<br />
export CC="icc"<br />
export CXX="icpc"<br />
export AR="xiar"<br />
export LD="xild"<br />
export CFLAGS="-O3 -ipo -openmp -xHost"<br />
export CXXFLAGS="-O3 -ipo -openmp -xHost"<br />
make<br />
</nowiki><br />
}}<br />
{{Note|this package will install the above described '''intel-mkl'''}}<br />
<br />
== See also ==<br />
* [http://www.rseek.org/ RSeek] A search engine for R related material.</div>Sander Maijershttps://wiki.archlinux.org/index.php?title=QEMU&diff=287418QEMU2013-12-09T14:05:44Z<p>Sander Maijers: </p>
<hr />
<div>[[Category:Emulators]]<br />
[[Category:Virtualization]]<br />
[[de:Qemu]]<br />
[[es:Qemu]]<br />
[[fr:Qemu]]<br />
[[zh-CN:QEMU]]<br />
{{Related articles start}}<br />
{{Related|KVM}}<br />
{{Related|Libvirt}}<br />
{{Related|VirtualBox}}<br />
{{Related|Xen}}<br />
{{Related|VMware}}<br />
{{Related articles end}}<br />
From the [http://wiki.qemu.org/Main_Page QEMU about page]:<br />
:''QEMU is a generic and open source machine emulator and virtualizer.''<br />
<br />
When used as a machine emulator, QEMU can run OSes and programs made for one machine (e.g. an ARM board) on a different machine (e.g. your x86 PC). By using dynamic translation, it achieves very good performance.<br />
<br />
QEMU can use other hypervisors like [[Xen]] or [[KVM]] to use CPU extensions ([[Wikipedia:Hardware-assisted virtualization|HVM]]) for virtualization. When used as a virtualizer, QEMU achieves near native performances by executing the guest code directly on the host CPU.<br />
<br />
== Installing QEMU ==<br />
<br />
Install {{Pkg|qemu}} from the [[Official Repositories|official repositories]].<br />
<br />
== Graphical front-ends for QEMU ==<br />
<br />
Unlike other virtualization programs such as [[VirtualBox]] and [[VMware]], QEMU does not provide a GUI to manage virtual machines (other than the window that appears when running a virtual machine), nor does it provide a way to create persistent virtual machines with saved settings. All parameters to run a virtual machine must be specified on the command line at every launch, unless you have created a custom script to start your virtual machine(s). However, there are several GUI front-ends for QEMU:<br />
<br />
* {{Pkg|virt-manager}} (part of [[libvirt]])<br />
* {{Pkg|qemu-launcher}}<br />
* {{Pkg|qtemu}}<br />
From AUR:<br />
* {{AUR|aqemu-git}}<br />
* {{AUR|qemulator}}<br />
* {{AUR|gnome-boxes}}<br />
<br />
== Running virtualized system ==<br />
<br />
{{ic|qemu-system-*}} binaries (for example {{ic|qemu-system-i386}} or {{ic|qemu-system-x86_64}}, depending on emulated architecture) are used to run the virtualized system. The usage is:<br />
<br />
$ qemu-system-i386 ''options'' ''disk_image''<br />
<br />
Options are the same for all {{ic|qemu-system-*}} binaries, see {{ic|qemu(1)}} for documentation of all options.<br />
<br />
By default, QEMU will show the virtual machine's video output in a window. One thing to keep in mind: when you click inside the QEMU window, the mouse pointer is grabbed. To release it, press {{ic|Ctrl+Alt}}.<br />
<br />
{{Warning|QEMU should never be run as root. If you must launch it in a script as root, you should use the {{ic|-runas}} option to make QEMU drop root privileges.}}<br />
<br />
=== Enabling KVM ===<br />
<br />
KVM must be supported by your processor and kernel, and necessary [[kernel modules]] must be loaded. See [[KVM]] for more information.<br />
<br />
To start QEMU in KVM mode, append {{ic|-enable-kvm}} to the additional start options.<br />
<br />
{{Note|If you start your VM with a GUI tool and experience very bad performance, you should check for proper KVM support, as QEMU may be falling back to software emulation.}}<br />
<br />
== Creating new virtualized system ==<br />
<br />
{{Tip|If you are virtualizing Arch Linux, it is possible to create a disk image directly on an existing Arch Linux system, see [[Creating Arch Linux disk image#Install Arch Linux in a disk image without the installation media]] for details.}}<br />
<br />
=== Creating a hard disk image ===<br />
<br />
{{Tip|See the [http://en.wikibooks.org/wiki/QEMU/Images QEMU Wikibook] for more information on QEMU images.}}<br />
<br />
To run QEMU you will need a hard disk image, unless you are booting a live system from CD-ROM or the network (and not doing so to install an operating system to a hard disk image). A hard disk image is a file which stores the contents of the emulated hard disk. <br />
<br />
A hard disk image can be ''raw'', so that it is literally byte-by-byte the same as what the guest sees, and will always use the full capacity of the guest hard drive on the host. This method provides the least I/O overhead, but can waste a lot of space, as not-used space on the guest cannot be used on the host.<br />
<br />
Alternatively, the hard disk image can be in a format such as ''qcow2'' which only allocates space to the image file when the guest operating system actually writes to those sectors on its virtual hard disk. The image appears as the full size to the guest operating system, even though it may take up only a very small amount of space on the host system. Using this format instead of ''raw'' will likely affect performance.<br />
<br />
QEMU provides the {{ic|qemu-img}} command to create hard disk images. For example to create a 4 GB image in the ''raw'' format:<br />
$ qemu-img create -f raw ''image_file'' 4G<br />
<br />
You may use {{ic|-f qcow2}} to create a ''gcow2'' disk instead.<br />
<br />
{{Note|You can also simply create a ''raw'' image by creating a file of the needed size using {{ic|dd}} or {{ic|fallocate}}.}}<br />
<br />
==== Overlay storage images ====<br />
<br />
You can create a storage image once (the 'backing' image) and have QEMU keep mutations to this image in an overlay image. This allows you to revert to a previous state of this storage image. You could revert by creating a new overlay image at the time you wish to revert, based on the original backing image.<br />
<br />
To create an overlay image, issue a command like:<br />
$ qemu-img create -b ''backing_image.qemu.raw'' -f qcow2 ''image.qemu.raw.overlay.1''<br />
<br />
After that you can run your QEMU VM as usual (see [[#Running virtualized system]]):<br />
$ qemu-system-i386 ''image.qemu.raw.overlay.1''<br />
<br />
The backing image will then be left intact and mutations to this storage will be recorded in the overlay image file.<br />
<br />
When the path to the backing image changes, repair is required. <br />
{{Warning|The backing image's absolute filesystem path is stored in the (binary) overlay image file. Changing the backing image's path requires some effort.}}<br />
Make sure that the original backing image's path still leads to this image. If necessary, make a symbolic link at the original path to the new path. Then issue a command like: <br />
$ qemu-img rebase -b ''/new/backing_image.qemu.raw'' ''/new/image.qemu.raw.overlay.1''<br />
<br />
At your discretion, you may alternatively perform an 'unsafe' rebase where the old path to the backing image is not checked: <br />
$ qemu-img rebase -u -b ''/new/backing_image.qemu.raw'' ''/new/image.qemu.raw.overlay.1''<br />
<br />
==== Resizing an image ====<br />
<br />
{{Warning|Resizing an image containing an NTFS boot file system could make the VM installed on it unbootable. One solution, which is really tricky and for expert users only, is shown [http://tjworld.net/wiki/Howto/ResizeQemuDiskImages here] along with a deep explanation of the problem.}}<br />
<br />
The {{ic|qemu-img}} executable has the {{ic|resize}} option, which enables easy resizing of a hard drive image. It works for both ''raw'' and ''qcow2''. For example to increase image space by 10 GB:<br />
$ qemu-img resize ''disk_image'' +10G<br />
<br />
=== Preparing the installation media ===<br />
<br />
To install an operating system into your disk image, you need the installation medium (e.g. optical disk, USB-drive, or ISO image) for the operating system. The installation medium should not be mounted because QEMU accesses the media directly. <br />
<br />
{{Tip|If using an optical disk, it is a good idea to first dump the media to a file because this both improves performance and does not require you to have direct access to the devices (that is, you can run QEMU as a regular user without having to change access permissions on the media's device file). For example, if the CD-ROM device node is named {{ic|/dev/cdrom}}, you can dump it to a file with the command: {{bc|1=$ dd if=/dev/cdrom of=''cd_image.iso''}}}}<br />
<br />
=== Installing the operating system===<br />
<br />
This is the first time you will need to start the emulator. To install the operating system on the disk image, you must attach both the disk image and the installation media to the virtual machine, and have it boot from the installation media.<br />
<br />
For example on i386 systems, to install from a bootable ISO file as CD-ROM:<br />
$ qemu-system-i386 -cdrom ''iso_image'' -boot order=d ''qemu_image''<br />
<br />
See {{ic|qemu(1)}} for information about loading other media types, such as floppy or disk images, or physical drives.<br />
<br />
After the operating system has finished installing, the QEMU image can be booted directly (see [[#Running virtualized system]]).<br />
<br />
{{Tip|<br />
* By default only 128 MB of memory is assigned to the machine. The amount of memory can be adjusted with the {{ic|-m}} switch, for example {{ic|-m 512}}.<br />
* Instead of specifying {{ic|1=-boot order=x}}, some users may feel more comfortable using a boot menu: {{ic|1=-boot menu=on}}, at least during configuration and experimentation.<br />
* If you need to replace floppies or CDs as part of the installation process, you can use the QEMU machine monitor (press {{ic|Ctrl+Alt+2}} in the virtual machine's window) to remove and attach storage devices to a virtual machine. Type {{ic|info block}} to see the block devices, and use the {{ic|change}} command to swap out a device. Press {{ic|Ctrl+Alt+1}} to go back to the virtual machine.}}<br />
<br />
== Moving data between host and guest OS ==<br />
<br />
=== Network ===<br />
<br />
Data can be shared between the host and guest OS using any network protocol that can transfer files, such as [[NFS]], [[Samba|SMB]], [[Wikipedia:Network Block Device|NBD]], HTTP, [[Very Secure FTP Daemon|FTP]], or [[Secure Shell|SSH]], provided that you have set up the network appropriately and enabled the appropriate services.<br />
<br />
The default user-mode networking allows the guest to access the host OS at the IP address 10.0.2.2. Any servers that you are running on your host OS, such as a SSH server or SMB server, will be accessible at this IP address. So on the guests, you can mount directories exported on the host via [[Samba|SMB]] or [[NFS]], or you can access the host's HTTP server, etc. <br />
It will not be possible for the host OS to access servers running on the guest OS, but this can be done with other network configurations (see [[#Tap networking with QEMU]]).<br />
<br />
=== QEMU's built-in SMB server ===<br />
<br />
QEMU's documentation says it has a "built-in" SMB server, but actually it just starts up [[Samba]] with an automatically generated configuration file and makes it accessible to the guest at a different IP address (10.0.2.4 by default). This only works for user networking, and this is not necessarily very useful since the guest can also access the normal [[Samba]] service on the host if you have set up shares on it.<br />
<br />
To enable this feature, start QEMU with a command like:<br />
$ qemu-system-i386 ''disk_image'' -net nic -net user,smb=''shared_dir_path''<br />
<br />
where {{ic|''shared_dir_path''}} is a directory that you want to share between the guest and host.<br />
<br />
Then, in the guest, you will be able to access the shared directory on the host 10.0.2.4 with the share name "qemu". For example, in Windows Explorer you would go to {{ic|\\10.0.2.4\qemu}}.<br />
<br />
=== Mounting a partition inside a raw disk image ===<br />
<br />
When the virtual machine is not running, it is possible to mount partitions that are inside a raw disk image file by setting them up as loopback devices. This does not work with disk images in special formats, such as qcow2, although those can be mounted using {{ic|qemu-nbd}}.<br />
<br />
{{Warning|You must make sure to unmount the partitions before running the virtual machine again. Otherwise data corruption could occur, unless you had mounted the partitions read-only.}}<br />
<br />
==== With manually specifying byte offset ====<br />
<br />
One way to mount a disk image partition is to mount the disk image at a certain offset using a command like the following:<br />
# mount -o loop,offset=32256 ''disk_image'' ''mountpoint''<br />
<br />
The {{ic|1=offset=32256}} option is actually passed to the {{ic|losetup}} program to set up a loopback device that starts at byte offset 32256 of the file and continues to the end. This loopback device is then mounted. You may also use the {{ic|sizelimit}} option to specify the exact size of the partition, but this is usually unnecessary.<br />
<br />
Depending on your disk image, the needed partition may not start at offset 32256. Run {{ic|fdisk -l ''disk_image''}} to see the partitions in the image. fdisk gives the start and end offsets in 512-byte sectors, so multiply by 512 to get the correct offset to pass to {{ic|mount}}.<br />
<br />
==== With loop module autodetecting partitions ====<br />
<br />
The Linux loop driver actually supports partitions in loopback devices, but it is disabled by default. To enable it, do the following:<br />
<br />
* Get rid of all your loopback devices (unmount all mounted images, etc.).<br />
* Unload the loop [[Kernel modules|module]].<br />
# modprobe -r loop<br />
* Load the loop [[Kernel modules|module]] with the {{ic|max_part}} parameter set.<br />
# modprobe loop max_part=15<br />
<br />
{{Tip|You can put an entry in {{ic|/etc/modprobe.d}} to load the loop module with {{ic|1=max_part=15}} every time, or you can put {{ic|1=loop.max_part=15}} on the kernel command-line, depending on whether you have the {{ic|loop.ko}} module built into your kernel or not.}}<br />
<br />
Set up your image as a loopback device:<br />
# losetup -f ''disk_image''<br />
<br />
Then, if the device created was {{ic|/dev/loop0}}, additional devices {{ic|/dev/loop0pX}} will have been automatically created, where X is the number of the partition. These partition loopback devices can be mounted directly. For example:<br />
# mount /dev/loop0p1 ''mountpoint''<br />
<br />
==== With kpartx ====<br />
<br />
'''kpartx''' from the {{AUR|multipath-tools-git}} package from the [[Arch User Repository|AUR]] can read a partition table on a device and create a new device for each partition. For example:<br />
# kpartx -a /dev/loop0<br />
<br />
=== Mounting a partition inside a qcow2 image ===<br />
<br />
You may mount a partition inside a qcow2 image using {{ic|qemu-nbd}}. See [http://en.wikibooks.org/wiki/QEMU/Images#Mounting_an_image_on_the_host Wikibooks].<br />
<br />
=== Using any real partition as the single primary partition of a hard disk image ===<br />
<br />
Sometimes, you may wish to use one of your system partitions from within QEMU. Using a raw partition for a virtual machine will improve performance, as the read and write operations do not go through the file system layer on the physical host. Such a partition also provides a way to share data between the host and guest.<br />
<br />
In Arch Linux, device files for raw partitions are, by default, owned by ''root'' and the ''disk'' group. If you would like to have a non-root user be able to read and write to a raw partition, you need to change the owner of the partition's device file to that user.<br />
<br />
{{Warning|<br />
* Although it is possible, it is not recommended to allow virtual machines to alter critical data on the host system, such as the root partition.<br />
* You must not mount a file system on a partition read-write on both the host and the guest at the same time. Otherwise, data corruption will result.<br />
}}<br />
<br />
After doing so, you can attach the partition to a QEMU virtual machine as a virtual disk.<br />
<br />
However, things are a little more complicated if you want to have the ''entire'' virtual machine contained in a partition. In that case, there would be no disk image file to actually boot the virtual machine since you cannot install a bootloader to a partition that is itself formatted as a file system and not as a partitioned device with a MBR. Such a virtual machine can be booted either by specifying the [[Kernels|kernel]] and [[initramfs|initrd]] manually, or by simulating a disk with a MBR by using linear [[RAID]].<br />
<br />
==== By specifying kernel and initrd manually ====<br />
<br />
QEMU supports loading [[Kernels|Linux kernels]] and [[initramfs|init ramdisks]] directly, thereby circumventing bootloaders such as [[GRUB]]. It then can be launched with the physical partition containing the root file system as the virtual disk, which will not appear to be partitioned. This is done by issuing a command similar to the following:<br />
$ qemu-system-i386 -kernel /boot/vmlinuz-linux -initrd /boot/initramfs-linux.img -append root=/dev/sda /dev/sda3<br />
<br />
In the above example, the physical partition being used for the guest's root file system is {{ic|/dev/sda3}} on the host, but it shows up as {{ic|/dev/sda}} on the guest.<br />
<br />
You may, of course, specify any kernel and initrd that you want, and not just the ones that come with Arch Linux.<br />
<br />
==== Simulate virtual disk with MBR using linear RAID ====<br />
<br />
A more complicated way to have a virtual machine use a physical partition, while keeping that partition formatted as a file system and not just having the guest partition the partition as if it were a disk, is to simulate a MBR for it so that it can boot using a bootloader such as GRUB.<br />
<br />
You can do this using software [[RAID]] in linear mode (you need the {{ic|linear.ko}} kernel driver) and a loopback device: the trick is to dynamically prepend a master boot record (MBR) to the real partition you wish to embed in a QEMU raw disk image.<br />
<br />
Suppose you have a plain, unmounted {{ic|/dev/hdaN}} partition with some file system on it you wish to make part of a QEMU disk image. First, you create some small file to hold the MBR:<br />
$ dd if=/dev/zero of=''/path/to/mbr'' count=32<br />
<br />
Here, a 16 KB (32 * 512 bytes) file is created. It is important not to make it too small (even if the MBR only needs a single 512 bytes block), since the smaller it will be, the smaller the chunk size of the software RAID device will have to be, which could have an impact on performance. Then, you setup a loopback device to the MBR file:<br />
# losetup -f ''/path/to/mbr''<br />
<br />
Let us assume the resulting device is {{ic|/dev/loop0}}, because we would not already have been using other loopbacks. Next step is to create the "merged" MBR + {{ic|/dev/hdaN}} disk image using software RAID:<br />
# modprobe linear<br />
# mdadm --build --verbose /dev/md0 --chunk=16 --level=linear --raid-devices=2 /dev/loop0 /dev/hda''N''<br />
<br />
The resulting {{ic|/dev/md0}} is what you will use as a QEMU raw disk image (do not forget to set the permissions so that the emulator can access it). The last (and somewhat tricky) step is to set the disk configuration (disk geometry and partitions table) so that the primary partition start point in the MBR matches the one of {{ic|/dev/hda''N''}} inside {{ic|/dev/md0}} (an offset of exactly 16 * 512 = 16384 bytes in this example). Do this using {{ic|fdisk}} on the host machine, not in the emulator: the default raw disc detection routine from QEMU often results in non-kilobyte-roundable offsets (such as 31.5 KB, as in the previous section) that cannot be managed by the software RAID code. Hence, from the the host:<br />
# fdisk /dev/md0<br />
<br />
Press {{ic|X}} to enter the expert menu. Set number of 's'ectors per track so that the size of one cylinder matches the size of your MBR file. For two heads and a sector size of 512, the number of sectors per track should be 16, so we get cylinders of size 2x16x512=16k.<br />
<br />
Now, press {{ic|R}} to return to the main menu. <br />
<br />
Press {{ic|P}} and check that the cylinder size is now 16k.<br />
<br />
Now, create a single primary partition corresponding to {{ic|/dev/hda''N''}}. It should start at cylinder 2 and end at the end of the disk (note that the number of cylinders now differs from what it was when you entered fdisk.<br />
<br />
Finally, 'w'rite the result to the file: you are done. You now have a partition you can mount directly from your host, as well as part of a QEMU disk image: <br />
<br />
$ qemu-system-i386 -hdc /dev/md0 ''[...]''<br />
<br />
You can, of course, safely set any bootloader on this disk image using QEMU, provided the original {{ic|/dev/hda''N''}} partition contains the necessary tools.<br />
<br />
== Networking ==<br />
<br />
The performance of virtual networking should be better with tap devices and bridges than with user-mode networking or vde because tap devices and bridges are implemented in-kernel.<br />
<br />
In addition, networking performance can be improved by assigning virtual machines a [http://wiki.libvirt.org/page/Virtio virtio] network device rather than the default emulation of an e1000 NIC. See [[#Installing virtio drivers]] for more information.<br />
<br />
=== Link-level address caveat ===<br />
<br />
By giving the {{ic|-net nic}} argument to QEMU, it will, by default, assign a virtual machine a network interface with the link-level address {{ic|52:54:00:12:34:56}}. However, when using bridged networking with multiple virtual machines, it is essential that each virtual machine has a unique link-level (MAC) address on the virtual machine side of the tap device. Otherwise, the bridge will not work correctly, because it will receive packets from multiple sources that have the same link-level address. This problem occurs even if the tap devices themselves have unique link-level addresses because the source link-level address is not rewritten as packets pass through the tap device.<br />
<br />
Make sure that each virtual machine has a unique link-level address, but it should always start with {{ic|52:54:}}. Use the following option, replace ''X'' with arbitrary hexadecimal digit:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:''XX:XX:XX:XX'' -net vde ''disk_image''<br />
<br />
Generating unique link-level addresses can be done in several ways:<br />
<br />
1. Manually specify unique link-level address for each NIC. The benefit is that the DHCP server will assign the same IP address each time the virtual machine is run, but it is unusable for large number of virtual machines.<br />
<br />
2. Generate random link-level address each time the virtual machine is run. Practically zero probability of collisions, but the downside is that the DHCP server will assign a different IP address each time. You can use the following command in a script to generate random link-level address in a {{ic|macaddr}} variable:<br />
<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
qemu-system-i386 -net nic,macaddr="$macaddr" -net vde ''disk_image''<br />
<br />
3. Use the following script {{ic|qemu-mac-hasher.py}} to generate the link-level address from the virtual machine name using a hashing function. Given that the names of virtual machines are unique, this method combines the benefits of the aforementioned methods: it generates the same link-level address each time the script is run, yet it preserves the practically zero probability of collisions.<br />
<br />
{{hc|qemu-mac-hasher.py|<nowiki><br />
#!/usr/bin/env python<br />
<br />
import sys<br />
import zlib<br />
<br />
if len(sys.argv) != 2:<br />
print("usage: %s <VM Name>" % sys.argv[0])<br />
sys.exit(1)<br />
<br />
crc = zlib.crc32(sys.argv[1].encode("utf-8")) & 0xffffffff<br />
crc = str(hex(crc))[2:]<br />
print("52:54:%s%s:%s%s:%s%s:%s%s" % tuple(crc))<br />
</nowiki>}}<br />
<br />
In a script, you can use for example:<br />
<br />
vm_name="''VM Name''"<br />
qemu-system-i386 -name "$vm_name" -net nic,macaddr=$(qemu-mac-hasher.py "$vm_name") -net vde ''disk_image''<br />
<br />
=== User-mode networking ===<br />
<br />
By default, without any {{ic|-netdev}} arguments, QEMU will use user-mode networking with a built-in DHCP server. Your virtual machines will be assigned an IP address when they run their DHCP client, and they will be able to access the physical host's network through IP masquerading done by QEMU. This only works with the TCP and UDP protocols, so ICMP, including {{ic|ping}}, will not work. <br />
<br />
This default configuration allows your virtual machines to easily access the Internet, provided that the host is connected to it, but the virtual machines will not be directly visible on the external network, nor will virtual machines be able to talk to each other if you start up more than one concurrently.<br />
<br />
QEMU's user-mode networking can offer more capabilities such as built-in TFTP or SMB servers, or attaching guests to VLANs so that they can talk to each other. See the QEMU documentation on the {{ic|-net user}} flag for more details.<br />
<br />
However, user-mode networking has limitations in both utility and performance. More advanced network configurations require the use of tap devices or other methods.<br />
<br />
=== Tap networking with QEMU ===<br />
<br />
[[wikipedia:TUN/TAP|Tap devices]] are a Linux kernel feature that allows you to create virtual network interfaces that appear as real network interfaces. Packets sent to a tap interface are delivered to a userspace program, such as QEMU, that has bound itself to the interface.<br />
<br />
QEMU can use tap networking for a virtual machine so that packets sent to the tap interface will be sent to the virtual machine and appear as coming from a network interface (usually an Ethernet interface) in the virtual machine. Conversely, everything that the virtual machine sends through its network interface will appear on the tap interface.<br />
<br />
Tap devices are supported by the Linux bridge drivers, so it is possible to bridge together tap devices with each other and possibly with other host interfaces such as {{ic|eth0}}. This is desirable if you want your virtual machines to be able to talk to each other, or if you want other machines on your LAN to be able to talk to the virtual machines.<br />
<br />
{{Warning|If you bridge together tap device and some host interface, such as {{ic|eth0}}, your virtual machines will appear directly on the external network, which will expose them to possible attack. Depending on what resources your virtual machines have access to, you may need to take all the precautions you normally would take in securing a computer to secure your virtual machines. If the risk is too great, virtual machines have little resources or you set up multiple virtual machines, better solution might be to use [[#Host-only networking|host-only networking]] and set up NAT. In this case you only need one firewall on the host instead of multiple firewalls for each guest.}}<br />
<br />
==== Host-only networking ====<br />
<br />
If the bridge is given an IP address and traffic destined for it is allowed, but no real interface (e.g. {{ic|eth0}}) is connected to the bridge, then the virtual machines will be able to talk to each other and the host system. However, they will not be able to talk to anything on the external network, provided that you do not set up IP masquerading on the physical host. This configuration is called ''host-only networking'' by other virtualization software such as [[VirtualBox]].<br />
<br />
{{Tip|<br />
* If you want to set up IP masquerading, e.g. NAT for virtual machines, see the [[Internet Sharing#Enable NAT]] page.<br />
* You may want to have a DHCP server running on the bridge interface to service the virtual network. For example, to use the {{ic|172.20.0.1/16}} subnet with [[dnsmasq]] as the DHCP server:<br />
# ip addr add 172.20.0.1/16 dev br0<br />
# ip link set br0 up<br />
# dnsmasq --interface&#61;br0 --bind-interfaces --dhcp-range&#61;172.20.0.2,172.20.255.254<br />
}}<br />
<br />
==== Internal networking ====<br />
<br />
If you do not give the bridge an IP address and add an [[iptables]] rule to drop all traffic to the bridge in the INPUT chain, then the virtual machines will be able to talk to each other, but not to the physical host or to the outside network. This configuration is called ''internal networking'' by other virtualization software such as [[VirtualBox]]. You will need to either assign static IP addresses to the virtual machines or run a DHCP server on one of them.<br />
<br />
==== Bridged networking using qemu-bridge-helper ====<br />
<br />
{{Note|This method is available since QEMU 1.1, see http://wiki.qemu.org/Features/HelperNetworking.}}<br />
<br />
This method does not require a start-up script and readily accommodates multiple taps and multiple bridges. It uses {{ic|/usr/lib/qemu/qemu-bridge-helper}} binary, which allows creating tap devices on an existing bridge.<br />
<br />
{{Tip|See [[Bridge with netctl]] for information on creating bridge.}} <br />
<br />
First, copy {{ic|/etc/qemu/bridge.conf.sample}} to {{ic|/etc/qemu/bridge.conf}}. Now modify {{ic|/etc/qemu/bridge.conf}} to contain the names of all bridges to be used by QEMU: <br />
<br />
{{hc|/etc/qemu/bridge.conf|<br />
allow ''bridge0''<br />
allow ''bridge1''<br />
...}}<br />
<br />
Now start the VM. The most basic usage would be:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' ''[...]''<br />
<br />
With multiple taps, the most basic usage requires specifying the VLAN for all additional NICs:<br />
<br />
$ qemu-system-i386 -net nic -net bridge,br=''bridge0'' -net nic,vlan=1 -net bridge,vlan=1,br=''bridge1'' ''[...]''<br />
<br />
==== Creating bridge manually ====<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
{{Tip|Since QEMU 1.1, the [http://wiki.qemu.org/Features/HelperNetworking network bridge helper] can set tun/tap up for you without the need for additional scripting. See [[#Bridged networking using qemu-bridge-helper]].}}<br />
<br />
The following describes how to bridge a virtual machine to a host interface such as {{ic|eth0}}, which is probably the most common configuration. This configuration makes it appear that the virtual machine is located directly on the external network, on the same Ethernet segment as the physical host machine.<br />
<br />
We will replace the normal Ethernet adapter with a bridge adapter and bind the normal Ethernet adapter to it. See http://en.gentoo-wiki.com/wiki/KVM#Networking_2{{Linkrot|2013|07|23}}.<br />
<br />
* Install {{Pkg|bridge-utils}}, which provides {{ic|brctl}} to manipulate bridges.<br />
<br />
* Enable IPv4 forwarding:<br />
# sysctl net.ipv4.ip_forward=1<br />
<br />
To make the change permanent, change {{ic|1=net.ipv4.ip_forward = 0}} to {{ic|1=net.ipv4.ip_forward = 1}} in {{ic|/etc/sysctl.d/99-sysctl.conf}}.<br />
<br />
* Load the {{ic|tun}} module and configure it to be loaded on boot. See [[Kernel modules]] for details.<br />
<br />
* Now create the bridge. See [[Bridge with netctl]] for details. Remember to name your bridge as {{ic|br0}}, or change the scripts below to your bridge's name.<br />
<br />
* Create the script that QEMU uses to bring up the tap adapter with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifup|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifup"<br />
echo "Bringing up $1 for bridged mode..."<br />
sudo /usr/bin/ip link set $1 up promisc on<br />
echo "Adding $1 to br0..."<br />
sudo /usr/bin/brctl addif br0 $1<br />
sleep 2<br />
</nowiki>}}<br />
<br />
* Create the script that QEMU uses to bring down the tap adapter in {{ic|/etc/qemu-ifdown}} with {{ic|root:kvm}} 750 permissions:<br />
{{hc|/etc/qemu-ifdown|<nowiki><br />
#!/bin/sh<br />
<br />
echo "Executing /etc/qemu-ifdown"<br />
sudo /usr/bin/ip link set $1 down<br />
sudo /usr/bin/brctl delif br0 $1<br />
sudo /usr/bin/ip link delete dev $1<br />
</nowiki>}}<br />
<br />
* Use {{ic|visudo}} to add the following to your {{ic|sudoers}} file:<br />
{{bc|<nowiki><br />
Cmnd_Alias QEMU=/usr/bin/ip,/usr/bin/modprobe,/usr/bin/brctl<br />
%kvm ALL=NOPASSWD: QEMU<br />
</nowiki>}}<br />
<br />
* You launch QEMU using the following {{ic|run-qemu}} script:<br />
{{hc|run-qemu|<nowiki><br />
#!/bin/bash<br />
USERID=$(whoami)<br />
<br />
# Get name of newly created TAP device; see https://bbs.archlinux.org/viewtopic.php?pid=1285079#p1285079<br />
precreationg=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
sudo /usr/bin/ip tuntap add user $USERID mode tap<br />
postcreation=$(/usr/bin/ip tuntap list | /usr/bin/cut -d: -f1 | /usr/bin/sort)<br />
IFACE=$(comm -13 <(echo "$precreationg") <(echo "$postcreation"))<br />
<br />
# This line creates a random MAC address. The downside is the DHCP server will assign a different IP address each time<br />
printf -v macaddr "52:54:%02x:%02x:%02x:%02x" $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff )) $(( $RANDOM & 0xff)) $(( $RANDOM & 0xff ))<br />
# Instead, uncomment and edit this line to set a static MAC address. The benefit is that the DHCP server will assign the same IP address.<br />
# macaddr='52:54:be:36:42:a9'<br />
<br />
qemu-system-i386 -net nic,macaddr=$macaddr -net tap,ifname="$IFACE" $*<br />
<br />
sudo ip link set dev $IFACE down &> /dev/null<br />
sudo ip tuntap del $IFACE mode tap &> /dev/null <br />
</nowiki>}}<br />
<br />
Then to launch a VM, do something like this<br />
$ run-qemu -hda ''myvm.img'' -m 512 -vga std<br />
<br />
{{Tip|If you cannot get a DHCP address in the host, it might be because [[iptables]] is up by default in the bridge.}}<br />
<br />
* It is recommended for performance and security reasons to disable the firewall on the bridge:<br />
{{hc|/etc/sysctl.d/10-disable-firewall-on-bridge.conf|<nowiki><br />
net.bridge.bridge-nf-call-ip6tables = 0<br />
net.bridge.bridge-nf-call-iptables = 0<br />
net.bridge.bridge-nf-call-arptables = 0<br />
</nowiki>}}<br />
Run {{ic|sysctl -p /etc/sysctl.d/10-disable-firewall-on-bridge.conf}} to apply the changes immediately.<br />
<br />
See the [http://wiki.libvirt.org/page/Networking#Creating_network_initscripts libvirt wiki] and [https://bugzilla.redhat.com/show_bug.cgi?id=512206 Fedora bug 512206]. If you get errors by sysctl during boot about non-existing files, make the {{ic|bridge}} module load at boot. See [[Kernel modules#Loading]].<br />
<br />
Alternatively, you can configure [[iptables]] to allow all traffic to be forwarded across the bridge by adding a rule like this:<br />
-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT<br />
<br />
=== Networking with VDE2 ===<br />
<br />
{{Poor writing|This section needs serious cleanup and may contain out-of-date information.}}<br />
<br />
==== What is VDE? ====<br />
<br />
VDE stands for Virtual Distributed Ethernet. It started as an enhancement of [[User-mode Linux|uml]]_switch. It is a toolbox to manage virtual networks.<br />
<br />
The idea is to create virtual switches, which are basically sockets, and to "plug" both physical and virtual machines in them. The configuration we show here is quite simple; However, VDE is much more powerful than this, it can plug virtual switches together, run them on different hosts and monitor the traffic in the switches. You are invited to read [http://wiki.virtualsquare.org/wiki/index.php/Main_Page the documentation of the project].<br />
<br />
The advantage of this method is you do not have to add sudo privileges to your users. Regular users should not be allowed to run modprobe.<br />
<br />
==== Basics ====<br />
<br />
VDE support can be [[pacman|installed]] via the {{Pkg|vde2}} package in the [[Official Repositories|official repositories]].<br />
<br />
In our config, we use tun/tap to create a virtual interface on my host. Load the {{ic|tun}} module (see [[Kernel modules]] for details):<br />
<br />
# modprobe tun<br />
<br />
Now create the virtual switch:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
<br />
This line creates the switch, creates {{ic|tap0}}, "plugs" it, and allows the users of the group {{ic|users}} to use it.<br />
<br />
The interface is plugged in but not configured yet. To configure it, run this command:<br />
<br />
# ip addr add 192.168.100.254/24 dev tap0<br />
<br />
Now, you just have to run KVM with these {{ic|-net}} options as a normal user:<br />
<br />
$ qemu-system-i386 -net nic -net vde -hda ''[...]''<br />
<br />
Configure networking for your guest as you would do in a physical network.<br />
<br />
{{Tip|You might want to set up NAT on tap device to access the internet from the virtual machine. See [[Internet Sharing#Enable NAT]] for more information.}}<br />
<br />
==== Startup scripts ====<br />
<br />
Example of main script starting VDE:<br />
<br />
{{hc|/etc/systemd/scripts/qemu-network-env|<nowiki><br />
#!/bin/sh<br />
# QEMU/VDE network environment preparation script<br />
<br />
# The IP configuration for the tap device that will be used for<br />
# the virtual machine network:<br />
<br />
TAP_DEV=tap0<br />
TAP_IP=192.168.100.254<br />
TAP_MASK=24<br />
TAP_NETWORK=192.168.100.0<br />
<br />
# Host interface<br />
NIC=eth0<br />
<br />
case "$1" in<br />
start)<br />
echo -n "Starting VDE network for QEMU: "<br />
<br />
# If you want tun kernel module to be loaded by script uncomment here <br />
#modprobe tun 2>/dev/null<br />
## Wait for the module to be loaded<br />
#while ! lsmod | grep -q "^tun"; do echo "Waiting for tun device"; sleep 1; done<br />
<br />
# Start tap switch<br />
vde_switch -tap "$TAP_DEV" -daemon -mod 660 -group users<br />
<br />
# Bring tap interface up<br />
ip address add "$TAP_IP"/"$TAP_MASK" dev "$TAP_DEV"<br />
ip link set "$TAP_DEV" up<br />
<br />
# Start IP Forwarding<br />
echo "1" > /proc/sys/net/ipv4/ip_forward<br />
iptables -t nat -A POSTROUTING -s "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
;;<br />
stop)<br />
echo -n "Stopping VDE network for QEMU: "<br />
# Delete the NAT rules<br />
iptables -t nat -D POSTROUTING "$TAP_NETWORK"/"$TAP_MASK" -o "$NIC" -j MASQUERADE<br />
<br />
# Bring tap interface down<br />
ip link set "$TAP_DEV" down<br />
<br />
# Kill VDE switch<br />
pgrep -f vde_switch | xargs kill -TERM <br />
;;<br />
restart|reload)<br />
$0 stop<br />
sleep 1<br />
$0 start<br />
;;<br />
*)<br />
echo "Usage: $0 {start|stop|restart|reload}"<br />
exit 1<br />
esac<br />
exit 0<br />
</nowiki>}}<br />
<br />
Example of systemd service using the above script:<br />
<br />
{{hc|/etc/systemd/system/qemu-network-env.service|<nowiki><br />
[Unit]<br />
Description=Manage VDE Switch<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/etc/systemd/scripts/qemu-network-env start<br />
ExecStop=/etc/systemd/scripts/qemu-network-env stop<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Change permissions for {{ic|qemu-network-env}} to be executable<br />
<br />
# chmod u+x /etc/systemd/scripts/qemu-network-env<br />
<br />
You can start it as usual (see [[systemd#Using units]] for details):<br />
<br />
# systemctl start qemu-network-env<br />
<br />
====Alternative method====<br />
<br />
If the above method does not work or you do not want to mess with kernel configs, TUN, dnsmasq, and iptables you can do the following for the same result.<br />
<br />
# vde_switch -daemon -mod 660 -group users<br />
# slirpvde --dhcp --daemon<br />
<br />
Then, to start the VM with a connection to the network of the host:<br />
<br />
$ qemu-system-i386 -net nic,macaddr=52:54:00:00:EE:03 -net vde ''disk_image''<br />
<br />
=== VDE2 Bridge ===<br />
<br />
Based on [http://selamatpagicikgu.wordpress.com/2011/06/08/quickhowto-qemu-networking-using-vde-tuntap-and-bridge/ quickhowto: qemu networking using vde, tun/tap, and bridge] graphic. Any virtual machine connected to vde is externally exposed. For example, each virtual machine can receive DHCP configuration directly from your ADSL router.<br />
<br />
==== Basics ====<br />
<br />
Remember that you need {{ic|tun}} module and {{Pkg|bridge-utils}} package.<br />
<br />
Create the vde2/tap device:<br />
<br />
# vde_switch -tap tap0 -daemon -mod 660 -group users<br />
# ip link set tap0 up<br />
<br />
Create bridge:<br />
<br />
# brctl addbr br0<br />
<br />
Add devices:<br />
<br />
# brctl addif br0 eth0<br />
# brctl addif br0 tap0<br />
<br />
And configure bridge interface:<br />
<br />
# dhcpcd br0<br />
<br />
==== Startup scripts ====<br />
<br />
All devices must be set up. And only the bridge needs an IP address. For physical devices on the bridge (e.g. {{ic|eth0}}), this can be done with [[netctl]] using a custom Ethernet profile with:<br />
<br />
{{hc|/etc/netctl/ethernet-noip|<nowiki><br />
Description='A more versatile static Ethernet connection'<br />
Interface=eth0<br />
Connection=ethernet<br />
IP=no<br />
</nowiki>}}<br />
<br />
VDE2 tap interface can be activated with the [[systemd/Services#VDE2_interface|VDE2 interface custom systemd service]].<br />
<br />
And finally, you can create the [[Bridge with netctl|bridge interface with netctl]].<br />
<br />
== Graphics ==<br />
<br />
QEMU can use the following different graphic outputs: {{ic|std}}, {{ic|cirrus}}, {{ic|vmware}}, {{ic|qxl}}, and {{ic|none}}.<br />
<br />
=== std ===<br />
<br />
With {{ic|-vga std}} you can get a resolution of up to 2560 x 1600 pixels.<br />
<br />
=== vmware ===<br />
<br />
Although it is a bit buggy, it performs better than std and cirrus. On the guest, install the VMware drivers ({{Pkg|xf86-video-vmware}} and {{Pkg|xf86-input-vmmouse}} for Arch Linux guests).<br />
<br />
=== qxl ===<br />
<br />
QXL is a paravirtual graphics driver with 2D support. To use it, these condition must be met:<br />
<br />
* [[#Spice support|Spice]] has to be enabled on the host system.<br />
* A driver has to be installed on the guest (e.g. {{AUR|xf86-video-qxl}} which is available in the [[AUR]]).<br />
* The virtual machine has to be started with {{ic|-vga qxl}} switch.<br />
<br />
=== none ===<br />
<br />
This is like a PC that has no VGA card at all. You would not even be able to access it with the {{ic|-vnc}} option. Also, this is different from the {{ic|-nographic}} option which lets QEMU emulate a VGA card, but disables the SDL display.<br />
<br />
=== vnc ===<br />
<br />
Given that you used the {{ic|-nographic}} option, you can add the {{ic|-vnc display}} option to have QEMU listen on {{ic|display}} and redirect the VGA display to the VNC session. There is an example of this in the [[#Starting QEMU virtual machines on boot]] section's example configs.<br />
<br />
$ qemu-system-i386 -vga std -nographic -vnc :0<br />
$ gvncviewer :0<br />
<br />
When using VNC, you might experience keyboard problems described (in gory details) [https://www.berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/ here]. The solution is ''not'' to use the {{ic|-k}} option on QEMU, and to use {{ic|gvncviewer}} from {{Pkg|gtk-vnc}}. See also [http://www.mail-archive.com/libvir-list@redhat.com/msg13340.html this] message posted on libvirt's mailing list.<br />
<br />
== Installing virtio drivers ==<br />
<br />
QEMU offers guests the ability to use paravirtualized block and network devices using the [http://wiki.libvirt.org/page/Virtio virtio] drivers, which provide better performance and lower overhead.<br />
<br />
* A virtio block device requires the option {{Ic|-drive}} instead of the simple {{Ic|-hd*}} plus {{Ic|1=if=virtio}}:<br />
$ qemu-system-i386 -boot order=c -drive file=''disk_image'',if=virtio<br />
<br />
{{Note|{{Ic|1=-boot order=c}} is absolutely necessary when you want to boot from it. There is no auto-detection as with {{Ic|-hd*}}.}}<br />
<br />
* Almost the same goes for the network:<br />
$ qemu-system-i386 -net nic,model=virtio<br />
<br />
{{Note|This will only work if the guest machine has drivers for virtio devices. Linux does, and the required drivers are included in Arch Linux, but there is no guarantee that virtio devices will work with other operating systems.}}<br />
<br />
=== Preparing an (Arch) Linux guest ===<br />
<br />
To use virtio devices after an Arch Linux guest has been installed, the following modules must be loaded in the guest: {{Ic|virtio}}, {{Ic|virtio_pci}}, {{Ic|virtio_blk}}, {{Ic|virtio_net}}, and {{Ic|virtio_ring}}. For 32-bit guests, the specific "virtio" module is not necessary.<br />
<br />
If you want to boot from a virtio disk, the initial ramdisk must be [[mkinitcpio|rebuilt]]. Add the appropriate modules in {{ic|/etc/mkinitcpio.conf}} like this:<br />
MODULES="virtio_blk virtio_pci virtio_net"<br />
and rebuild the initial ramdisk:<br />
# mkinitcpio -p linux<br />
<br />
Virtio disks are recognized with the prefix {{ic|'''v'''}} (e.g. {{ic|'''v'''da}}, {{ic|'''v'''db}}, etc.); therefore, changes must be made in at least {{ic|/etc/fstab}} and {{ic|/boot/grub/grub.cfg}} when booting from a virtio disk.<br />
<br />
{{Tip|When referencing to disks by [[Persistent_block_device_naming#By-uuid|UUID]] in both {{ic|/etc/fstab}} and bootloader, nothing has to be done.}}<br />
<br />
Further information on paravirtualization with KVM can be found [http://www.linux-kvm.org/page/Boot_from_virtio_block_device here].<br />
<br />
=== Preparing a Windows guest ===<br />
<br />
==== Block device drivers ====<br />
<br />
Preparing a Windows guest for booting from virtio disk is a bit tricky.<br />
<br />
You can download the virtio disk driver from the [http://www.linux-kvm.org/page/WindowsGuestDrivers/Download_Drivers Fedora repository].<br />
<br />
Now you need to create a new disk image, which fill force Windows to search for the driver. For example:<br />
$ qemu-img create -f qcow2 ''fake.qcow2'' 1G<br />
<br />
Run the original Windows guest (with the boot disk still in IDE mode) with the fake disk (in virtio mode) and a CD-ROM with the driver.<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=ide -drive file=''fake.qcow2'',if=virtio -cdrom virtio-win-0.1-59.iso<br />
<br />
Windows will detect the fake disk and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the SCSI drive with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
When the installation is successful, you can turn off the virtual machine and launch it again, now with the boot disk attached in virtio mode:<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio<br />
<br />
{{Note|If you encounter the Blue Screen of Death, make sure you did not forget the {{ic|-m}} parameter, and that you do not boot with virtio instead of ide for the system drive before drivers are installed.}}<br />
<br />
==== Network drivers ====<br />
<br />
Installing virtio network drivers is a bit easier, simply add the {{ic|-net}} argument as explained above.<br />
$ qemu-system-i386 -m 512 -vga std -drive file=''windows_disk_image'',if=virtio -net nic,model=virtio -cdrom virtio-win-0.1-30.iso<br />
<br />
Windows will detect the network adapter and try to find a driver for it. If it fails, go to the ''Device Manager'', locate the network adapter with an exclamation mark icon (should be open), click ''Update driver'' and select the virtual CD-ROM. Do not forget to select the checkbox which says to search for directories recursively.<br />
<br />
=== Preparing a FreeBSD guest ===<br />
<br />
Install the {{ic|emulators/virtio-kmod}} port if you are using FreeBSD 8.3 or later up until 10.0-CURRENT where they are included into the kernel. After installation, add the following to your {{ic|/boot/loader.conf}} file:<br />
<br />
{{bc|<nowiki><br />
virtio_loader="YES"<br />
virtio_pci_load="YES"<br />
virtio_blk_load="YES"<br />
if_vtnet_load="YES"<br />
virtio_balloon_load="YES"<br />
</nowiki>}}<br />
<br />
Then modify your {{ic|/etc/fstab}} by doing the following:<br />
<br />
{{bc|<nowiki><br />
sed -i/etc/fstab.bak "s/ad/vtbd/g" /etc/fstab<br />
</nowiki>}}<br />
<br />
And verify that {{ic|/etc/fstab}} is consistent. If anything goes wrong, just boot into a rescue CD and copy {{ic|/etc/fstab.bak}} back to {{ic|/etc/fstab}}.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Starting QEMU virtual machines on boot ===<br />
<br />
==== With libvirt ====<br />
<br />
If a virtual machine is set up with [[libvirt]], it can be configured through the virt-manager GUI to start at host boot by going to the Boot Options for the virtual machine and selecting "Start virtual machine on host boot up".<br />
<br />
==== Custom script ====<br />
<br />
To run QEMU VMs on boot, you can use following systemd unit and config.<br />
<br />
{{hc|/etc/systemd/system/qemu@.service|<nowiki><br />
[Unit]<br />
Description=QEMU virtual machine<br />
<br />
[Service]<br />
Environment="type=system-x86_64" "haltcmd=kill -INT $MAINPID"<br />
EnvironmentFile=/etc/conf.d/qemu.d/%i<br />
ExecStart=/usr/bin/env qemu-${type} -name %i -nographic $args<br />
ExecStop=/bin/sh -c ${haltcmd}<br />
TimeoutStopSec=30<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Then create per-VM configuration files, named {{ic|/etc/conf.d/qemu.d/''vm_name''}}, with the following variables set:<br />
<br />
; type<br />
: QEMU binary to call. If specified, will be prepended with {{ic|/usr/bin/qemu-}} and that binary will be used to start the VM. I.e. you can boot e.g. {{ic|qemu-system-arm}} images with {{ic|1=type="system-arm"}}.<br />
; args<br />
: QEMU command line to start with. Will always be prepended with {{ic|-name ${vm} -nographic}}.<br />
; haltcmd<br />
: Command to shut down a VM safely. I am using {{ic|-monitor telnet:..}} and power off my VMs via ACPI by sending {{ic|system_powerdown}} to monitor. You can use SSH or some other ways.<br />
<br />
Example configs:<br />
{{hc|/etc/conf.d/qemu.d/one|<nowiki><br />
type="system-x86_64"<br />
<br />
args="-enable-kvm -m 512 -hda /dev/mapper/vg0-vm1 -net nic,macaddr=DE:AD:BE:EF:E0:00 \<br />
-net tap,ifname=tap0 -serial telnet:localhost:7000,server,nowait,nodelay \<br />
-monitor telnet:localhost:7100,server,nowait,nodelay -vnc :0"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7100" # or netcat/ncat<br />
<br />
# You can use other ways to shut down your VM correctly<br />
#haltcmd="ssh powermanager@vm1 sudo poweroff"<br />
</nowiki>}}<br />
{{hc|/etc/conf.d/qemu.d/two|<nowiki><br />
args="-enable-kvm -m 512 -hda /srv/kvm/vm2.img -net nic,macaddr=DE:AD:BE:EF:E0:01 \<br />
-net tap,ifname=tap1 -serial telnet:localhost:7001,server,nowait,nodelay \<br />
-monitor telnet:localhost:7101,server,nowait,nodelay -vnc :1"<br />
<br />
haltcmd="echo 'system_powerdown' | nc localhost 7101"<br />
</nowiki>}}<br />
<br />
To set which virtual machines will start on boot-up, use<br />
# systemctl enable qemu@''vm_name''<br />
# systemctl disable qemu@''vm_name''<br />
<br />
=== Mouse integration ===<br />
<br />
To prevent the mouse from being grabbed when clicking on the guest operating system's window, add the option {{ic|-usbdevice tablet}}. This means QEMU is able to report the mouse position without having to grab the mouse. This also overrides PS/2 mouse emulation when activated. For example:<br />
$ qemu-system-i386 -hda ''disk_image'' -m 512 -vga std -usbdevice tablet<br />
<br />
=== Pass-through host USB device ===<br />
<br />
To access physical USB device connected to host from VM, you can start QEMU with following option:<br />
<br />
$ qemu-system-i386 -usbdevice host:''vendor_id'':''product_id'' ''disk_image''<br />
<br />
You can find {{ic|vendor_id}} and {{ic|product_id}} of your device with {{ic|lsusb}} command.<br />
<br />
{{Note|If you encounter permission errors when running QEMU, see [[Udev#Writing udev rules]] for information on how to set permissions of the device.}}<br />
<br />
=== Enabling KSM ===<br />
<br />
Kernel Samepage Merging (KSM) is a feature of the Linux kernel that allows for an application to register with the kernel to have its pages merged with other processes that also register to have their pages merged. The KSM mechanism allows for guest virtual machines to share pages with each other. In an environment where many of the guest operating systems are similar, this can result in significant memory savings.<br />
<br />
To enable KSM, simply run<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
<br />
To make it permanent, you can use [[systemd#Temporary files|systemd's temporary files]]:<br />
{{hc|/etc/tmpfiles.d/ksm.conf|<br />
w /sys/kernel/mm/ksm/run - - - - 1<br />
}}<br />
<br />
If KSM is running, and there are pages to be merged (i.e. at least two similar VMs are running), then {{ic|/sys/kernel/mm/ksm/pages_shared}} should be non-zero. See https://www.kernel.org/doc/Documentation/vm/ksm.txt for more information.<br />
<br />
{{Tip|An easy way to see how well KSM is performing is to simply print the contents of all the files in that directory: {{bc|$ grep . /sys/kernel/mm/ksm/*}}}}<br />
<br />
=== Spice support ===<br />
<br />
The [http://spice-space.org/ Spice project] aims to provide a complete, open-source solution for interaction with virtualized desktop devices. Its main focus is to provide high-quality remote access to QEMU virtual machines.<br />
<br />
The official {{Pkg|qemu}} package is built with Spice support.<br />
<br />
You can start your VM:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing<br />
<br />
Then connect with the the spice client<br />
<br />
$ spicec -h 127.0.0.1 -p 5930<br />
<br />
{{Tip|<br />
* Spice guest drivers can be downloaded [http://www.spice-space.org/download.html here] in the ''Guest'' section.<br />
* The key combination to escape mouse and keyboard grab can be configured, the default is {{ic|Shift+F12}}: {{bc|1=$ spicec --hotkeys release-cursor=ctrl+alt}}<br />
* {{Pkg|virt-manager}} has a Spice client built in.<br />
}}<br />
<br />
=== Copy and paste ===<br />
<br />
To have copy and paste between the host and the guest you need to enable the spice agent communication channel. It requires to add a virtio-serial device to the guest, and open a port for the spice vdagent. It is also required to install the spice vdagent in guest ({{AUR|spice-vdagent}} for Arch guests, [http://www.spice-space.org/download.html Windows guest tools] for Windows guests). Make sure the agent is running (and for future, started automatically).<br />
<br />
Start QEMU with the following options:<br />
<br />
$ qemu-system-i386 -vga qxl -spice port=5930,disable-ticketing -device virtio-serial-pci -device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0 -chardev spicevmc,id=spicechannel0,name=vdagent<br />
<br />
The {{ic|-device virtio-serial-pci}} option adds the virtio-serial device, {{ic|1=-device virtserialport,chardev=spicechannel0,name=com.redhat.spice.0}} opens a port for spice vdagent in that device and {{ic|1=-chardev spicevmc,id=spicechannel0,name=vdagent}} adds a spicevmc chardev for that port.<br />
<br />
It is important that the {{ic|1=chardev=}} option of the {{ic|virtserialport}} device matches the {{ic|1=id=}} option given to the {{ic|chardev}} option ({{ic|spicechannel0}} in this example). It is also important that the port name is {{ic|com.redhat.spice.0}}, because that is the namespace where vdagent is looking for in the guest. And finally, specify {{ic|1=name=vdagent}} so that spice knows what this channel is for.<br />
<br />
=== Windows-specific notes ===<br />
<br />
QEMU can run any version of Windows from Windows 95 through Windows 8.<br />
<br />
It is possible to run [[Windows PE]] in QEMU.<br />
<br />
==== Remote Desktop Protocol ====<br />
<br />
If you use a MS Windows guest, you might want to use RDP to connect to your guest VM. If you are using a VLAN or are not in the same network as the guest, use:<br />
<br />
$ qemu-system-i386 -nographic -net user,hostfwd=tcp::5555-:3389<br />
<br />
Then connect with either rdesktop or freerdp to the guest. For example:<br />
<br />
$ xfreerdp -g 2048x1152 localhost:5555 -z -x lan<br />
<br />
== Troubleshooting ==<br />
<br />
=== Mouse cursor is jittery or erratic ===<br />
<br />
If the cursor jumps around the screen uncontrollably, entering this on the terminal before starting QEMU might help:<br />
$ export SDL_VIDEO_X11_DGAMOUSE=0<br />
<br />
If this helps, you can add this to your {{ic|bashrc}} file.<br />
<br />
=== Keyboard seems broken or the arrow keys do not work ===<br />
<br />
Should you find that some of your keys do not work or "press" the wrong key (in particular, the arrow keys), you likely need to specify your keyboard layout as an option. The keyboard layouts can be found in {{ic|/usr/share/qemu/keymaps}}.<br />
$ qemu-system-i386 -k ''keymap'' ''disk_image''<br />
<br />
=== Virtual machine runs too slowly ===<br />
<br />
There are a number of techniques that you can use to improve the performance if your virtual machine. For example:<br />
<br />
* Use the {{ic|-cpu host}} option to make QEMU emulate the host's exact CPU. If you do not do this, it may be trying to emulate a more generic CPU.<br />
* If the host machine has multiple CPUs, assign the guest more CPUs using the {{ic|-smp}} option.<br />
* Make sure you have assigned the virtual machine enough memory. By default, QEMU only assigns 128 MiB of memory to each virtual machine. Use the {{ic|-m}} option to assign more memory. For example, {{ic|-m 1024}} runs a virtual machine with 1024 MiB of memory.<br />
* Use KVM if possible: add {{ic|1=-machine type=pc,accel=kvm}} to the QEMU start command you use.<br />
* If supported by drivers in the guest operating system, use [http://wiki.libvirt.org/page/Virtio virtio] for network and/or block devices. For example:<br />
$ qemu-system-i386 -net nic,model=virtio -net tap,if=tap0,script=no -drive file=''disk_image'',media=disk,if=virtio<br />
* Use TAP devices instead of user-mode networking. See [[#Tap networking with QEMU]].<br />
* If the guest OS is doing heavy writing to its disk, you may benefit from certain mount options on the host's file system. For example, you can mount an [[Ext4|ext4 file system]] with the option {{ic|1=barrier=0}}. You should read the documentation for any options that you change because sometimes performance-enhancing options for file systems come at the cost of data integrity.<br />
* If you have a raw disk image, disable the cache:<br />
$ qemu-system-i386 -drive file=''disk_image'',if=virtio,cache=none<br />
* If you are running multiple virtual machines concurrently that all have the same operating system installed, you can save memory by enabling [[wikipedia:Kernel_SamePage_Merging_(KSM)|kernel same-page merging]]:<br />
# echo 1 > /sys/kernel/mm/ksm/run<br />
* In some cases, memory can be reclaimed from running virtual machines by running a memory ballooning driver in the guest operating system and launching QEMU with the {{ic|-balloon virtio}} option.<br />
<br />
See http://www.linux-kvm.org/page/Tuning_KVM for more information.<br />
<br />
== See also ==<br />
<br />
* [http://qemu.org Official QEMU website]<br />
* [http://www.linux-kvm.org Official KVM website]<br />
* [http://qemu.weilnetz.de/qemu-doc.html QEMU Emulator User Documentation]<br />
* [http://en.wikibooks.org/wiki/QEMU QEMU Wikibook]<br />
* ''[http://alien.slackbook.org/dokuwiki/doku.php?id=slackware:qemu Hardware virtualization with QEMU]'' by AlienBOB<br />
* ''[http://blog.falconindy.com/articles/build-a-virtual-army.html Building a Virtual Army]'' by Falconindy<br />
* ''[http://qemu-buch.de/de/index.php/QEMU-KVM-Book/_Content QEMU, KVM, Xen & libvirt]'' by Robert Warnke and Thomas Ritzau</div>Sander Maijers