https://wiki.archlinux.org/api.php?action=feedcontributions&user=Medicineman25&feedformat=atomArchWiki - User contributions [en]2024-03-29T10:50:57ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=DaVinci_Resolve&diff=711128DaVinci Resolve2022-01-18T08:19:23Z<p>Medicineman25: added links to progl "documentation" and github to help clarify usage</p>
<hr />
<div>[[Category:Audio]]<br />
[[Category:Video]]<br />
[[ja:DaVinci Resolve]]<br />
[[zh-hans:DaVinci Resolve]]<br />
[https://www.blackmagicdesign.com/ru/products/davinciresolve/ Davinci Resolve] is a proprietary video editor, color correction and compositing application.<br />
<br />
== Installation ==<br />
<br />
There is a free version and a paid version (a.k.a. Studio).<br /><br />
For the free version, [[install]] {{AUR|davinci-resolve}} or {{AUR|davinci-resolve-beta}}.<br /><br />
For the Studio version, install {{AUR|davinci-resolve-studio}} or {{AUR|davinci-resolve-studio-beta}}.<br />
<br />
To run DaVinci Resolve, it is required to use suitable OpenGL and OpenCL drivers. Open-source OpenCL drivers are currently unsupported. Please notice that incompatible OpenCL drivers should be uninstalled as they may cause Resolve to crash (e.g. uninstall {{Pkg|opencl-mesa}} if you are using a proprietary equivalent).<br />
<br />
Standalone Intel GPUs are currently unsupported. If using hybrid AMD + Intel setups, you can use the Intel GPU as the primary graphics card and use a proprietary OpenCL driver for the AMD GPU.<br />
<br />
{| class="wikitable" style="text-align:center"<br />
|+Table of OpenGL drivers<br />
|-<br />
! GPU vendor !! Type !! Driver !! OpenGL !! Documentation !! Tested driver version !! Works with DaVinci Resolve !! Tested DR version !! Notes<br />
|-<br />
! rowspan="3" | AMD / ATI<br />
| rowspan="2" | Open source || {{Pkg|xf86-video-amdgpu}} || rowspan="2" | {{Pkg|mesa}} || [[AMDGPU]] || || {{No}} || ||<br />
|-<br />
| {{Pkg|xf86-video-ati}} || [[ATI]] || || Not tested || ||<br />
|-<br />
| Proprietary || {{Pkg|xf86-video-amdgpu}} || {{AUR|amdgpu-pro-libgl}} || [[AMDGPU PRO]] || 21.10_1247438-1 || {{Yes}} || 17.1.1 || Requires running Resolve with the {{ic|progl}} wrapper script. See [[AMDGPU_PRO#Workaround_for_using_proprietary_OpenGL|documentation]] and the [https://github.com/Ashark/archlinux-amdgpu-pro driver github] for usage.<br />
|-<br />
! Intel<br />
| Open source || {{Pkg|xf86-video-intel}} || {{Pkg|mesa}} || [[Intel graphics]] || || {{Yes}} || ||<br />
|-<br />
! rowspan="2" | NVIDIA<br />
| Open source || {{Pkg|xf86-video-nouveau}} || {{Pkg|mesa}} || [[Nouveau]] || || {{No}} || ||<br />
|-<br />
| Proprietary || {{Pkg|nvidia}} || {{Pkg|nvidia-utils}} || [[NVIDIA]] || 460.32.03-1 || {{Yes}} || 17.0b6-1 || Tested on optimus laptop using nvidia-xrun.<br />
|-<br />
|}<br />
<br />
{| class="wikitable" style="text-align:center"<br />
|+Table of tested [[OpenCL]] drivers<br />
! GPU Vendor !! OpenCL driver !! Tested driver version !! Works with DR !! Tested DR version !! Comment<br />
|-<br />
!Neutral<br />
|{{Pkg|opencl-mesa}} || || {{No}} || ||<br />
|-<br />
!rowspan="2"|AMD<br />
|rowspan="2"| {{AUR|opencl-amd}} || 21.10.1247438-1 || {{Yes}} || 17.1.1 || Tested with RX 580<br />
|- <br />
| 20.50.1234664 || {{Yes}} || || Tested on RX 6800 XT<br />
|-<br />
!rowspan="4"|Intel<br />
|{{Pkg|intel-compute-runtime}} || 21.21.19914-1 || {{Y|Partly}} || 17.2.1 || Launches normally, can open a project. But unable to start playing the timeline (even without video tracks) in the Cut and in the Edit pages. However in the Fairlight page it is able to play timeline.<br>Tested with Intel Core i7-8700 CPU.<br />
|-<br />
|{{AUR|beignet}} || 1.3.2+12+gfc5f430c-2 || {{No}} || || Core dumped<br />
|-<br />
|{{AUR|intel-opencl}} || 5.0.r63503-2 || {{No}} || || Core dumped<br />
|-<br />
|{{AUR|intel-opencl-runtime}} || 1:18.1.0.013-2 || {{No}} || || Core dumped<br />
|-<br />
!Nvidia<br />
|{{Pkg|opencl-nvidia}} || 460.32.03-1 || {{Yes}} || || Suitable, but working on cuda instead?<br />
|}<br />
<br />
=== DaVinci Resolve Checker ===<br />
<br />
You can run [https://github.com/Ashark/davinci-resolve-checker davinci-resolve-checker] script, which will tell you if your configuration is suitable for running DR. In good configurations it should output:<br />
All seems good. You should be able to run DaVinci Resolve successfully.<br />
<br />
=== BlackMagic Design Cards ===<br />
<br />
If using DeckLink, UltraStudio or Intensity cards for video capture and playback, install Desktop Video Software with {{AUR|decklink}} package.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Decrease installation time ===<br />
<br />
Compression of a Davinci Resolve package takes significant time, because the binary is quite large. You can avoid compression and decompression by installing Davinci Resolve like this (assuming you use yay):<br />
<br />
$ PKGEXT='.pkg.tar' yay -S davinci-resolve<br />
See [[Makepkg#Use other compression algorithms]] page for more information.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Logs location ===<br />
<br />
DaVinci Resolve creates log file {{ic|'$HOME/.local/share/DaVinciResolve/logs/ResolveDebug.txt'}} at every launch. If are you having problems, try to inspect it for useful messages.<br />
<br />
=== Application window misses title bar ===<br />
<br />
It is a problem of a Linux version of DR There is a workaround for KDE - a window rule to force enable title bar. See [https://forum.blackmagicdesign.com/viewtopic.php?=21&t=56878&p=456990#p456990]<br />
<br />
You can manually create a file describing needed window rule:<br />
{{hc|1=DaVinci_Resolve_main_window_always_with_titlebar_and_frame.kwinrule|2=<br />
[DaVinci Resolve main window always with titlebar and frame]<br />
Description=DaVinci Resolve main window always with titlebar and frame<br />
clientmachinematch=0<br />
noborder=false<br />
noborderrule=2<br />
titlematch=0<br />
types=1<br />
wmclass=resolve<br />
wmclasscomplete=false<br />
wmclassmatch=1<br />
}}<br />
Then go to ''System Settings > Window Management > Window Rules'' and import this file.<br />
<br />
=== My .mp4 clips are shown as audio clips and even its sound is not working ===<br />
<br />
This problem only affects a free version of DR for Linux. MP4 containers are not supported, also AAC audio is not supported. Note, that as of April 2020, even studio version does not support AAC decoding in MP4 files. See supported codecs pdf in [[#See also]].<br />
<br />
To workaround, you may convert your video file to another format or purchase a studio version.<br />
Transcoding command may look like this:<br />
ffmpeg -i input.mp4 -c:v dnxhd -profile:v dnxhr_hq -pix_fmt yuv422p -c:a pcm_s16le -f mov output.mov<br />
<br />
You can automate this task using incron. It will automatically convert files appeared in specified folder. See setup example on [https://passthroughpo.st/painless-linux-video-production-part-3-organization-and-workflow/#:~:text=Auto%2DTranscode%20Your%20Footage this article].<br />
<br />
Another alternative is to write a resolve script for that purpose. See documentation for Resolve Scripting for more information.<br />
<br />
There is no yet (as of April 2021) such a document for DR 17, but DR 17.1 and DR studio 17.1 both supports mp3 files. However, for some reason, integrating mp3 audio to mov file is not playing.<br />
<br />
=== HiDPI ===<br />
<br />
To enable compatibility with high-resolution displays, set the following environment variables accordingly:<br />
<br />
export QT_DEVICE_PIXEL_RATIO=2<br />
export QT_AUTO_SCREEN_SCALE_FACTOR=true<br />
<br />
Source: https://forum.blackmagicdesign.com/viewtopic.php?f=21&t=84614&p=469009&hilit=hidpi#wrapper<br />
<br />
=== Wine version ===<br />
<br />
Some plugins are available for Windows, but not available for Linux, so you may want to use Davinci Resolve via wine. Also, wine version could potentially workaround the linux-only problem of mp4 format issues. Wine 6.5 brings [https://www.phoronix.com/scan.php?page=news_item&px=Wine-6.5-Released OpenCL 1.2 support], which is [https://www.newsshooter.com/2020/11/13/blackmagic-design-davinci-resolve-17-1-released/ required] for DR. Unfortunately, there was no success to start DR via wine. See test results [https://appdb.winehq.org/objectManager.php?sClass=application&iId=17141 here]. In 17.4.1 DR cannot see the list of available gpus (wine 6.21). Probably, need some hack to make wine present gpus to applications.<br />
<br />
=== Wrong OpenCL Version ===<br />
<br />
If the application simply is not starting, even after showing installer and "tour" successfully your OpenCL Version may not match your NVIDIA driver. <br />
If you have installed nvidia-440xx make sure to install opencl-nvidia-440xx as well.<br />
A possible error message:<br />
{{hc|~/.local/share/DaVinciResolve/logs/LogArchive/ResolveDebug_C1.txt|<br />
...<br />
OpenCL error -1001: 'Unspecified Error', GPUPropertiesUtilUnix.cpp:338<br />
...}}<br />
<br />
=== Get back to Onboarding screen ===<br />
<br />
If you are experimenting with driver installation, you may want to start from the welcome tour and onboarding screen, which checks your system and graphics card. You can achieve that by removing configs directory:<br />
<br />
rm -r $HOME/.local/share/DaVinciResolve/configs<br />
<br />
=== Full screen preview function missing ===<br />
<br />
This function is only available in the studio version. It is in menu ''Workspace > Video Clean Feed''.<br />
<br />
=== Audio recording in Fairlight not working ===<br />
{{Out of date|In the linked topic it is said that in 17.3 they fixed the problem.}}<br />
Recording audio tracks with microphone (USB or jack) is currently not working in both Studio and free version. See [https://forum.blackmagicdesign.com/viewtopic.php?f=36&t=126287].<br />
<br />
=== No audio during video preview ===<br />
<br />
DaVinci interfaces the ALSA directly, so you need to redirect it to use PulseAudio by creating {{ic|asound.conf}} in {{ic|/etc/}} with the following content:<br />
{{hc|/etc/asound.conf|<br />
pcm.!default pulse<br />
ctl.!default pulse}}<br />
<br />
=== Error code 999 on intel/nvidia hybrid graphic card ===<br />
<br />
"The GPU failed to perform image processing because of an error. Error Code: 999."<br />
<br />
If nvidia gpu is used in on-demand mode, you have to explicitly demand it. To enable set the following environment variables:<br />
<br />
export __NV_PRIME_RENDER_OFFLOAD=1<br />
export __GLX_VENDOR_LIBRARY_NAME=nvidia<br />
<br />
=== Silent crash related to libcrypto.so.1.0.0 ===<br />
<br />
Possible crash message:<br />
{{hc|~/.local/share/DaVinciResolve/logs/ResolveDebug.txt|<nowiki><br />
<br />
...<br />
<br />
==========[CRASH DUMP]==========<br />
<br />
Please send this to support:<br />
<br />
#TIME Sat Jan 23 19:42:20 2021 - Uptime 00:00:08 (hh:mm:ss)<br />
#PROGRAM_NAME DaVinci Resolve v16.2.8.005 (Linux/Clang)<br />
<br />
/opt/resolve/bin/resolve() [0x550e0a9]<br />
/opt/resolve/bin/resolve() [0x550d89a]<br />
/usr/lib/libpthread.so.0(+0x140f0) [0x7f80d90640f0]<br />
/usr/lib/libc.so.6(+0x15df7e) [0x7f80d6af5f7e]<br />
/opt/resolve/bin/../libs/libcrypto.so.1.0.0(lh_insert+0xad) [0x7f80d8aa2e4d]<br />
/opt/resolve/bin/../libs/libcrypto.so.1.0.0(OBJ_NAME_add+0x65) [0x7f80d89f1855]<br />
...<br />
</nowiki>}}<br />
<br />
Replace {{ic|/opt/resolve/libs/libcrypto.so.1.0.0}} with {{ic|/usr/lib/libcrypto.so.1.0.0}}:<br />
<br />
# cp /usr/lib/libcrypto.so.1.0.0 /opt/resolve/libs/libcrypto.so.1.0.0<br />
<br />
== See also ==<br />
<br />
* [https://forum.blackmagicdesign.com/viewtopic.php?f=21&t=56878&p=456990#p456924 Post] on Davinci Resolve forum with tested configurations.<br />
* PDF with list of [https://documents.blackmagicdesign.com/SupportNotes/DaVinci_Resolve_16_Supported_Codec_List.pdf Supported Formats and Codecs] for DR 16<br>[https://www.blackmagicdesign.com/support/family/davinci-resolve-and-fusion Here] you can check if BMD released a document for a newer version, see in the Latest Support Notes column.</div>Medicineman25https://wiki.archlinux.org/index.php?title=Android&diff=594934Android2020-01-14T04:27:27Z<p>Medicineman25: changed instructions for user created from "Android sdk" to "android-sdk" in line with the rest of the instructions</p>
<hr />
<div>[[Category:Android]]<br />
[[Category:Development]]<br />
[[es:Android]]<br />
[[it:Android]]<br />
[[ja:Android]]<br />
[[zh-hans:Android]]<br />
{{Related articles start}}<br />
{{Related|Android tethering}}<br />
{{Related|Android Debug Bridge}}<br />
{{Related articles end}}<br />
== Transferring files ==<br />
<br />
There are various ways to transfer files between a computer and an Android device:<br />
<br />
* USB cable<br />
** [[Media Transfer Protocol]] for modern Android devices<br />
** [[Wikipedia:USB Mass Storage|USB mass storage]] for older devices<br />
** [[Android Debug Bridge]]<br />
* special USB sticks / regular USB stick with adapter<br />
* [[Bluetooth]]<br />
* Arch Linux software with Android counterparts<br />
** client or server for protocols that can be used to transfer files (eg. [[SSH]], [[FTP]], [[Samba]] or HTTP)<br />
** [[KDE Connect]] ({{Pkg|kdeconnect}}) – integrates your Android device with the KDE desktop (featuring synced notifications & clipboard, multimedia control, and file/URL sharing).<br />
** [[cloud synchronization clients]]<br />
** [[Syncthing]]<br />
** {{AUR|sendanywhere}} – cross-platform file sharing<br />
<br />
== App development ==<br />
<br />
The officially supported way to build Android apps is to use [[#Android Studio]].[https://developer.android.com/training/basics/firstapp/creating-project]<br />
<br />
=== Android Studio ===<br />
<br />
[https://developer.android.com/studio/index.html Android Studio] is the official Android development environment based on [[Wikipedia:IntelliJ IDEA|IntelliJ IDEA]]. It provides integrated Android developer tools for development and debugging.<br />
<br />
You can [[install]] it with the {{AUR|android-studio}} package.<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* Make sure you properly [[Java#Change_default_Java_environment|set the Java environment]] otherwise android-studio will not start.<br />
* If Android Studio shows up as a blank window try [[export]]ing {{ic|1=_JAVA_AWT_WM_NONREPARENTING=1}}, see [https://code.google.com/p/android/issues/detail?id=57675 issue #57675].<br />
}}<br />
<br />
The Android Studio Setup Wizard installs the required [[#SDK packages]] and places the SDK by default in {{ic|~/Android/Sdk}}.<br />
<br />
To build apps from the command-line (using e.g. {{ic|./gradlew assembleDebug}}) set the [https://developer.android.com/studio/command-line/variables#android_sdk_root ANDROID_SDK_ROOT] [[environment variable]] to your SDK location.<br />
<br />
=== SDK packages ===<br />
<br />
Android SDK packages can be installed directly from upstream using [[#Android Studio]]'s [https://developer.android.com/studio/intro/update#sdk-manager SDK Manager] or the [https://developer.android.com/studio/command-line/sdkmanager sdkmanager] command line tool (part of the Android SDK Tools). Some Android SDK packages are also available as [[AUR]] packages, they generally install to {{ic|/opt/android-sdk/}}.<br />
<br />
The [https://developer.android.com/studio/intro/update#recommended required SDK packages] are:<br />
<br />
{| class="wikitable"<br />
! Android SDK Package !! SDK-style path !! AUR package !! AUR dummy !! CLI tools<br />
|-<br />
| [https://developer.android.com/studio/releases/sdk-tools SDK Tools] || tools || {{AUR|android-sdk}} || {{AUR|android-sdk-dummy}} || sdkmanager, apkanalizer, avdmanager, mksdcard, proguard<br />
|-<br />
| [https://developer.android.com/studio/releases/build-tools SDK Build-Tools] || build-tools;''version'' || {{AUR|android-sdk-build-tools}} || {{AUR|android-sdk-build-tools-dummy}} || apksigner, zipalign<br />
|-<br />
| [https://developer.android.com/studio/releases/platform-tools SDK Platform-Tools] || platform-tools || {{AUR|android-sdk-platform-tools}} || {{AUR|android-sdk-platform-tools-dummy}} || [[adb]], [[#Fastboot|#fastboot]] and systrace<br />
|-<br />
| [https://developer.android.com/studio/releases/platforms SDK Platform] || platforms;android-''level'' || {{AUR|android-platform}}, [https://aur.archlinux.org/packages/?K=android-platform- older versions] || unnecessary<br />
|}<br />
<br />
The {{Pkg|android-tools}} package provides [[adb]], [[#Fastboot|#fastboot]], {{ic|e2fsdroid}} and {{ic|mke2fs.android}} from the SDK Platform-Tools along with {{ic|mkbootimg}} and {{ic|ext2simg}}.<br />
<br />
{{Note|1=&nbsp;<br />
* Since the Android SDK contains 32-bit binaries, you must enable the [[multilib]] repository. Otherwise you will get {{ic|error: target not found: lib32-*}} error messages.<br />
* If you choose to directly install SDK packages from upstream, install the AUR packages of the ''AUR dummy'' column to pull in the required dependencies.}}<br />
<br />
==== Android Emulator ====<br />
<br />
The [https://developer.android.com/studio/run/emulator Android Emulator] is available as the {{ic|emulator}} SDK package, the {{AUR|android-emulator}} package. And there's also a dummy package for it: {{AUR|android-emulator-dummy}}.<br />
<br />
To run the Android Emulator you need an Intel or ARM System Image. You can install them through the AUR[https://aur.archlinux.org/packages/?K=android-+system+image], with the sdkmanager or using Android Studio's [https://developer.android.com/studio/run/managing-avds AVD Manager].<br />
<br />
==== Other SDK packages in the AUR ====<br />
<br />
The [https://developer.android.com/topic/libraries/support-library/ Android Support Library] is now available online from [https://developer.android.com/studio/build/dependencies#google-maven Google's Maven repository].<br />
You can also install it offline through the {{ic|extras;android;m2repository}} SDK package (also available as {{AUR|android-support-repository}}).<br />
<br />
==== Making /opt/android-sdk group-writeable ====<br />
<br />
The AUR packages install the SDK in {{ic|/opt/android-sdk/}}. This directory has root [[permissions]], so keep in mind to run sdk manager as root. If you intend to use it as a regular user, create the android-sdk users group, add your user.<br />
<br />
# groupadd android-sdk<br />
# gpasswd -a <user> android-sdk<br />
<br />
Set an access control list to let members of the newly created group write into the android-sdk folder. As running sdkmanager can also create new files, set the ACL as default ACL. the X in the default group entry means "allow execution if executable by the owner (or anyone else)"<br />
<br />
# setfacl -R -m g:android-sdk:rwx /opt/android-sdk<br />
# setfacl -d -m g:android-sdk:rwX /opt/android-sdk <br />
<br />
Re-login or as <user> log your terminal in to the newly created group:<br />
<br />
$ newgrp android-sdk<br />
<br />
=== Other IDEs ===<br />
<br />
Android Studio is the official Android development environment based on IntelliJ IDEA. Alternatively, you can use [[Netbeans]] with the NBAndroid-V2. All are described below.<br />
<br />
==== Netbeans ====<br />
<br />
If you prefer using [[Netbeans]] as your IDE and want to develop Android applications, use [https://github.com/NBANDROIDTEAM/NBANDROID-V2 NBAndroid-V2] .<br />
<br />
Install {{AUR|android-sdk}} package<br />
<br />
Add the following URL by going to ''Tools > Plugins > Settings'':<br />
<br />
{| class="wikitable"<br />
! Netbeans version !! URL<br />
|-<br />
| Netbeans 8.1 || http://server.arsi.sk/nbandroid81/updates.xml<br />
|-<br />
| Netbeans 8.2 || http://server.arsi.sk/nbandroid82/updates.xml<br />
|-<br />
|}<br />
<br />
Then go to ''Available Plugins'' and install the ''Gradle-Android-support'' plugin.<br />
<br />
==== Eclipse ====<br />
<br />
{{Note|The Eclipse ADT plugin is no longer supported. Google recommends to use Android Studio instead.[https://android-developers.googleblog.com/2016/11/support-ended-for-eclipse-android.html]}}<br />
<br />
The official, but deprecated, [http://developer.android.com/sdk/eclipse-adt.html Eclipse ADT] plugin can be installed with the {{AUR|eclipse-android}} package.<br />
<br />
{{Note|<br />
* if you get a message about unresolvable dependencies, install [[Java]] manually and try again.<br />
* as an alternative, you can install the ADT via eclipse's built in "add new software" command (see instructions on ADT site).<br />
* if you are in real trouble, it is also possible to download Android SDK and use the bundled Eclipse. This usually works without problems.<br />
* if you need to install extra SDK plugins not found in the AUR, you must change the file ownership of /opt/android-sdk first. You can do this with {{ic|# chgrp -R users /opt/android-sdk ; chmod -R 0775 /opt/android-sdk}} (see [[File Permissions]] for more details).<br />
}}<br />
<br />
Enter the path to the Android SDK Location in ''Windows > Preferences > Android''.<br />
<br />
{{Note|If the plugins do not show up in Eclipse after the AUR package has been upgraded, then eclipse probably has out-of-date caches. Running {{ic|sudo eclipse -clean}} once should clear them. If the problem persists, uninstall eclipse and all the plugins, delete {{ic|/usr/share/eclipse}}, and reinstall everything.}}<br />
<br />
== Building ==<br />
<br />
Please note that these instructions are based on the [https://source.android.com/source/building official AOSP build instructions]. Other Android-derived systems such as LineageOS will often require extra steps.<br />
<br />
=== Required packages ===<br />
<br />
To build any version of Android, you need to install these packages:<br />
<br />
* {{Pkg|lib32-gcc-libs}} {{Pkg|git}} {{Pkg|gnupg}} {{Pkg|flex}} {{Pkg|bison}} {{Pkg|gperf}} {{Pkg|sdl}} {{Pkg|wxgtk2}} {{Pkg|squashfs-tools}} {{Pkg|curl}} {{Pkg|ncurses}} {{Pkg|zlib}} {{Pkg|schedtool}} {{Pkg|perl-switch}} {{Pkg|zip}} {{Pkg|unzip}} {{Pkg|libxslt}} {{Pkg|python2-virtualenv}} {{Pkg|bc}} {{Pkg|rsync}} {{Aur|ncurses5-compat-libs}} {{Pkg|lib32-zlib}} {{Pkg|lib32-ncurses}} {{Pkg|lib32-readline}} {{Aur|lib32-ncurses5-compat-libs}}<br />
<br />
The {{Aur|aosp-devel}} metapackage provides them all for simple installation.<br />
<br />
Additionally, LineageOS requires the following packages: {{AUR|xml2}}, {{Pkg|lzop}}, {{Pkg|pngcrush}}, {{Pkg|imagemagick}}<br />
<br />
They can be installed with the {{Aur|lineageos-devel}} metapackage.<br />
<br />
{{Accuracy|The note below is not clear and probably incomplete.}}<br />
{{Note|1=Installing both {{Pkg|maven}} and {{Pkg|gradle}} to build LineageOS may result in a build speed improvement as the build process will prefer the system's }}<br />
<br />
=== Java Development Kit ===<br />
<br />
The [https://source.android.com/source/requirements required JDK version] depends on the Android version you are building:<br />
<br />
* For Android 7 and 8 (Nougat and Oreo), OpenJDK 8 is required, which is available with the {{Pkg|jdk8-openjdk}} package. <br />
* For Android 5 and 6 (Lollipop and Marshmallow), OpenJDK 7 is required, which is available with the {{Pkg|jdk7-openjdk}} package.<br />
<br />
Older versions require a working '''Oracle JDK''' installed on your build system. It '''will not''' work with OpenJDK.<br />
<br />
* For Gingerbread through KitKat (2.3 - 4.4), Java 6 is required, which is available as {{AUR|jdk6}} from the AUR.<br />
* For Cupcake through Froyo (1.5 - 2.2), Java 5 is required, which is available as {{AUR|jdk5}} from the AUR.<br />
<br />
{{Note|1=<br />
Android expects Java in {{ic|/usr/lib/jvm/java-''version''-openjdk-amd64}}.<br />
Set JAVA_HOME to avoid this requirement and match the Arch Linux installation path.<br />
Example:<br />
<br />
$ export JAVA_HOME=/usr/lib/jvm/java-''version''-openjdk<br />
<br />
This change will be valid only for the current terminal session.<br />
}}<br />
<br />
=== Setting up the build environment ===<br />
<br />
[[Install]] the {{Pkg|repo}} package. <br />
<br />
Create a directory to build.<br />
<br />
$ mkdir ~/android<br />
$ cd ~/android<br />
<br />
The Android build process expects {{ic|python}} to be python2. Prepend it to the {{ic|PATH}}:<br />
<br />
$ mkdir bin<br />
$ ln -s /bin/python2 bin/python<br />
$ export PATH=$PWD/bin:$PATH<br />
<br />
Alternatively, create a python2 virtual environment and activate it:<br />
<br />
$ virtualenv2 --system-site-packages venv<br />
$ source venv/bin/activate<br />
<br />
{{Note|<br />
* This activation is only active for the current terminal session. The virtual env will be kept in the {{ic|venv}} folder.<br />
* Passing "--system-site-packages" to virtualenv2 points your virtual environment to your installed python2.7 modules. This should give you all python modules you need for the build, assuming you've installed the required dependencies such as python2-mako.<br />
* If during the build you still receive errors pertaining to missing python modules a quick and dirty fix might be to symlink /usr/lib/python2.7/* to ~/android/venv/lib/python2.7/ (Change ~/android to reflect your build directory if different than above).<br />
Example:<br />
<br />
$ ln -s /usr/lib/python2.7/* ~/android/venv/lib/python2.7/<br />
<br />
or (assuming build directory Data/Android_Build):<br />
<br />
$ ln -s /usr/lib/python2.7/* /Data/Android_Build/venv/lib/python2.7/<br />
<br />
}}<br />
<br />
=== Downloading the source code ===<br />
<br />
This will clone the repositories. You '''only''' need to do this the first time you build Android, or if you want to switch branches.<br />
<br />
* The {{ic|repo}} has a {{ic|-j}} switch that operates similarly to the one used with {{ic|make}}. Since it controls the number of simultaneous downloads, you should adjust the value depending on downstream network bandwidth.<br />
<br />
* You will need to specify a '''branch''' (release of Android) to check out with the {{ic|-b}} switch. If you leave the switch out, you will get the so-called '''master branch'''.<br />
<br />
<pre><br />
$ repo init -u https://android.googlesource.com/platform/manifest -b master<br />
$ repo sync -j4<br />
</pre><br />
<br />
{{Note|To further decrease sync times, you can utilize the -c switch with the repo command as such:<br />
<br />
$ repo sync -j8 -c<br />
<br />
The {{ic|-c}} switch will only sync the branch which is specified in the manifest, which in turn is determined by the branch specified with the {{ic|-b}} switch, or the default branch set by the repository maintainer.<br />
}}<br />
<br />
Wait a long time. Just the uncompiled source code, along with the {{ic|.repo}} and {{ic|.git}} directories that are used to keep track of it, are well over 10 GB. As of Android 6.0.1, the entire codebase totals 40 GB.<br />
<br />
{{Note|If you want to update your local copy of the Android source, at a later time, simply enter the build directory, load the Virtualenv, and re-sync:<br />
<br />
$ repo sync<br />
<br />
}}<br />
<br />
=== Building the code ===<br />
<br />
This should do what you need for AOSP:<br />
<br />
$ source build/envsetup.sh<br />
$ lunch full-eng<br />
$ make -j4<br />
<br />
If you run '''lunch''' without arguments, it will ask what build you want to create. Use -j with a number between one and two times number of cores/threads.<br />
<br />
The build takes a very long time.<br />
<br />
{{Note|<br />
* Make sure you have enough RAM. Android will use the {{ic|/tmp}} directory heavily. By default the size of the partition the {{ic|/tmp}} folder is mounted on is half the size of your RAM. If it fills up, the build will fail. 4GB of RAM or more is recommended. Alternatively, you can get rid of the tmpfs from [[fstab]] all together.<br />
* From the [https://source.android.com/source/building#build-the-code Android Building and Running guide]:<br />
"GNU make can handle parallel tasks with a {{ic|-jN}} argument, and it's common to use a number of tasks N that's between 1 and 2 times the number of hardware threads on the computer being used for the build. E.g. on a dual-E5520 machine (2 CPUs, 4 cores per CPU, 2 threads per core), the fastest builds are made with commands between {{ic|make -j16}} and {{ic|make -j32}}."<br />
}}<br />
<br />
=== Testing the build ===<br />
<br />
When finished, run/test the final image(s).<br />
<br />
$ emulator<br />
<br />
=== Creating a flashable Image ===<br />
<br />
To create an image that can be flashed it is necessary to:<br />
<br />
make -j8 updatepackage<br />
<br />
This will create a zip image under {{ic|'''out/target/product/hammerhead'''}} (hammerhead being the device name) that can be flashed.<br />
<br />
== Flashing ==<br />
<br />
In some cases, you want to return to the stock Android after flashing custom ROMs to your Android mobile device. For flashing instructions of your device, please use [http://forum.xda-developers.com/ XDA forums].<br />
<br />
=== Fastboot ===<br />
<br />
Fastboot (as well as [[ADB]]) is included in the {{Pkg|android-tools}} package.<br />
<br />
{{Note|Restoring firmwares using {{ic|fastboot}} can be quite tricky, but you might want to browse [http://www.xda-developers.com/ XDA developers forums] for a stock firmware, which is mostly a {{ic|*.zip}} file, but inside of it, comes with the firmware files and {{ic|flash-all.sh}} script. For example, [https://developers.google.com/android/nexus/images Google Nexus] firmwares include {{ic|flash-all.sh}} script or another example could be for OnePlus One - [http://forum.xda-developers.com/oneplus-one/general/guide-return-opo-to-100-stock-t2826541 XDA thread], where you can find firmwares with included {{ic|flash-all.sh}} script.}}<br />
<br />
{{Note|If you get a {{ic|no permissions}} error or execution just hangs with {{ic|< waiting for any device >}} then you need to run {{ic|fastboot}} with {{ic|sudo}}.}}<br />
<br />
=== Samsung devices ===<br />
<br />
Samsung devices can't be flashed using '''Fastboot''' tool. Alternatives are only '''Heimdall''' and '''Odin''' (by using Windows and VirtualBox).<br />
<br />
==== Heimdall ====<br />
<br />
[http://glassechidna.com.au/heimdall/ Heimdall] is a cross-platform open-source tool suite used to flash firmware (also known as ROMs) onto Samsung mobile devices and is also known as an alternative to [http://odindownload.com/ Odin]. It can be installed as {{Pkg|heimdall}}.<br />
<br />
The flashing instructions can be found on Heimdall's [https://gitlab.com/BenjaminDobell/Heimdall/tree/master/Linux GitLab repository] or on [http://forum.xda-developers.com/showthread.php?t=1922461 XDA forums].<br />
<br />
==== Odin (Virtualbox) ====<br />
<br />
{{Note|1=This section only covers preparation and '''not''' flashing instructions. Search [http://www.xda-developers.com XDA developers forums] to find flashing instructions for a specific device. For example, [https://forum.xda-developers.com/showthread.php?t=2265477 Samsung Galaxy S4].}}<br />
<br />
It is also possible to restore [http://www.sammobile.com/firmwares/ firmware (Android)] on the Samsung devices using [http://odindownload.com/ Odin], but inside the [[VirtualBox]].<br />
<br />
Arch Linux (host) preparation:<br />
<br />
# Install [[VirtualBox]] together with its [[VirtualBox#Extension_pack|extension pack]] and [[VirtualBox#Guest_additions_disc|guest additions]].<br />
# Install your preferred, but compatible with Odin, Windows operating system (with VirtualBox guest additions) into a virtual hard drive using VirtualBox.<br />
# Open VirtualBox settings of your Windows operating system, navigate to ''USB'', then tick (or make sure it is ticked) '''Enable USB 2.0 (EHCI) Controller'''.<br />
# At VirtualBox running Windows operating system, click in the menu bar ''Devices > USB Devices'', then click on your Samsung mobile device from the list, which is connected to your computer via USB.<br />
<br />
Windows (guest) preparation:<br />
<br />
# Install [http://androidxda.com/download-samsung-usb-drivers Samsung drivers].<br />
# Install [http://odindownload.com/ Odin].<br />
# Download required [http://www.sammobile.com/firmwares/ Samsung firmware (Android)] for your smartphone model.<br />
<br />
Check if configuration is working:<br />
<br />
# Turn your device into Download mode and connect to your Linux machine.<br />
# In virtual machine toolbar, select ''Devices > USB > ...Samsung...'' device.<br />
# Open Odin. The white box (a big one at the bottom-left side) named '''Message''', should print a line similar to this:<br />
<br />
<ID:0/003> Added!!<br />
<br />
which means that your device is visible to Odin & Windows operating system and is ready to be flashed.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Android Studio: Android Virtual Devices show 'failed to load'. ===<br />
<br />
Make sure you've exported the variable {{ic|ANDROID_HOME}} as explained in [[#Android Studio]].<br />
<br />
=== Android Studio: 'failed to create the SD card' ===<br />
<br />
If you try to run an AVD (Android Virtual Device) under x86_64 Arch and get the error above, install the {{Pkg|lib32-gcc-libs}} package from the [[multilib]] repository.<br />
<br />
=== Eclipse: During Debugging "Source not found" ===<br />
<br />
Most probably the debugger wants to step into the Java code. As the source code of Android does not come with the Android SDK, this leads to an error. The best solution is to use step filters to not jump into the Java source code. Step filters are not activated by default. To activate them: ''Window > Preferences > Java > Debug > Step Filtering''.<br />
Consider to select them all. If appropriate you can add the android.* package. See the forum post for more information: http://www.eclipsezone.com/eclipse/forums/t83338.rhtml<br />
<br />
=== ValueError: unsupported pickle protocol ===<br />
<br />
One fix is to issue:<br />
<br />
$ rm ~/.repopickle_.gitconfig<br />
<br />
If that does not work, then try this:<br />
<br />
$ find /path/to/android-root -name .repopickle_config -delete<br />
<br />
=== libGL error: failed to load driver: swrast OR AVD doesn't load and no error message displayed ===<br />
<br />
Sometimes, beginning to load an AVD will cause an error message similar to this to be displayed, or the loading process will appear to finish but no AVD will load and no error message will be displayed.<br />
<br />
The AVD loads an incorrect version of libstdc++, you can remove the folder libstdc++ from {{ic|~/.android-sdk/emulator/lib64}} (for 64-bit) or {{ic|~/.android-sdk/emulator/lib}} (for 32-bit) , e.g.:<br />
<br />
$ rm -r ~/.android-sdk/emulator/lib64/libstdc++<br />
<br />
Note that in versions before Android Studio 3.0, this directory was in a different location:<br />
<br />
$ rm -r ~/Android/Sdk/emulator/lib64/libstdc++<br />
<br />
Alternatively you can set and export ANDROID_EMULATOR_USE_SYSTEM_LIBS in ~/.profile as:<br />
<br />
export ANDROID_EMULATOR_USE_SYSTEM_LIBS=1<br />
<br />
Reference: [https://developer.android.com/studio/command-line/variables.html#studio_jdk Android Studio user guide]<br />
<br />
Fix for the .desktop file might be achieved by using env command, prefixing the Exec line [[Desktop entries#Modify environment variables]]<br />
<br />
env ANDROID_EMULATOR_USE_SYSTEM_LIBS=1<br />
<br />
=== sh: glxinfo: command not found===<br />
<br />
Here's the full error:<br />
<br />
Cannot launch AVD in emulator.<br />
Output:<br />
sh: glxinfo: command not found<br />
sh: glxinfo: command not found<br />
libGL error: unable to load driver: swrast_dri.so<br />
libGL error: failed to load driver: swrast<br />
X Error of failed request: BadValue (integer parameter out of range for operation)<br />
Major opcode of failed request: 154 (GLX)<br />
Minor opcode of failed request: 24 (X_GLXCreateNewContext)<br />
Value in failed request: 0x0<br />
Serial number of failed request: 32<br />
Current serial number in output stream: 33<br />
QObject::~QObject: Timers cannot be stopped from another thread<br />
<br />
You can try to install glxinfo ({{Pkg|mesa-demos}}) but if your computer has enough power you could simply use software to render graphics. To do so, go to ''Tools > Android > AVD Manager'', edit the ''AVD'' (click the pencil icon), then select ''Software - GLES 2.0'' for ''Emulated Performance > Graphics''.<br />
<br />
=== Android Emulator: no keyboard input in xfwm4 ===<br />
<br />
In xfwm4, the vertical toolbar buttons window that is on the right of the emulator takes focus from the emulator and consumes keyboard events.<br />
([https://issuetracker.google.com/issues/37094173 bug report])<br />
<br />
You can use the workaround described in [https://stackoverflow.com/a/42720450/1366471 this Stack Overflow answer]:<br />
<br />
# Open the xfwm4 settings.<br />
# Switch to the Focus tab.<br />
# Change the Focus Model to "Focus follow mouse".<br />
# Disable ''Automatically raise windows when they receive focus'' option below.<br />
<br />
=== adb: sideload connection failed: insufficient permissions for device ===<br />
<br />
If you get the error<br />
<br />
adb: sideload connection failed: insufficient permissions for device<br />
See [http://developer.android.com/tools/device.html] for more information<br />
adb: trying pre-KitKat sideload method...<br />
adb: pre-KitKat sideload connection failed: insufficient permissions for device<br />
See [http://developer.android.com/tools/device.html] for more information<br />
<br />
you might solve it by restarting the adb server with sudo:<br />
<br />
$ adb kill-server<br />
$ sudo adb start-server</div>Medicineman25https://wiki.archlinux.org/index.php?title=Python&diff=551549Python2018-10-27T12:20:00Z<p>Medicineman25: /* Package management */ altered link description again</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[de:Python]]<br />
[[es:Python]]<br />
[[ja:Python]]<br />
[[ko:Python]]<br />
[[ru:Python]]<br />
[[zh-hans:Python]]<br />
{{Related articles start}}<br />
{{Related|Python package guidelines}}<br />
{{Related|Python/Virtual environment}}<br />
{{Related|mod_wsgi}}<br />
{{Related|Django}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Python (programming language)|Wikipedia]]:<br />
<br />
:Python is a widely used high-level, general-purpose, interpreted, dynamic programming language. Its design philosophy emphasizes code readability, and its syntax allows programmers to express concepts in fewer lines of code than possible in languages such as C++ or Java. The language provides constructs intended to enable writing clear programs on both a small and large scale.<br />
:Python supports multiple programming paradigms, including object-oriented, imperative and functional programming or procedural styles. It features a dynamic type system and automatic memory management and has a large and comprehensive standard library.<br />
<br />
== Installation ==<br />
<br />
=== Python 3 ===<br />
<br />
Python 3 is the latest version of the language, and is incompatible with Python 2. The language is mostly the same, but many details, especially how built-in objects like dictionaries and strings work, have changed considerably, and a lot of deprecated features have finally been removed. Also, the standard library has been reorganized in a few prominent places. For an overview of the differences, visit [https://wiki.python.org/moin/Python2orPython3 Python2orPython3] and the relevant [http://getpython3.com/diveintopython3/porting-code-to-python-3-with-2to3.html chapter] in Dive into Python 3.<br />
<br />
To install the latest version of Python 3, [[install]] the {{Pkg|python}} package.<br />
<br />
If you would like to build the latest RC/betas from source, visit [https://www.python.org/downloads/ Python Downloads]. The [[Arch User Repository]] also contains good [[PKGBUILD]]s. If you do decide to build the RC, note that the binary (by default) installs to {{ic|/usr/local/bin/python3.x}}.<br />
<br />
=== Python 2 ===<br />
<br />
To get the latest version of Python 2, [[install]] the {{Pkg|python2}} package.<br />
<br />
Python 2 will happily run alongside Python 3. You need to specify {{ic|python2}} in order to run this version.<br />
<br />
Any program requiring Python 2 needs to point to {{ic|/usr/bin/python2}}, instead of {{ic|/usr/bin/python}}, which points to Python 3. To do so, open the program or script in a [[List of applications/Documents#Text editors|text editor]] and change the first line. The line will show one of the following:<br />
<br />
#!/usr/bin/env python<br />
<br />
or<br />
<br />
#!/usr/bin/python<br />
<br />
In both cases, just change {{ic|python}} to {{ic|python2}} and the program will then use Python 2 instead of Python 3.<br />
<br />
Another way to force the use of python2 without altering the scripts is to call it explicitly with {{ic|python2}}:<br />
<br />
$ python2 ''myScript.py''<br />
<br />
Finally, you may not be able to control the script calls, but there is a way to trick the environment. It only works if the scripts use {{ic|#!/usr/bin/env python}}. It will not work with {{ic|#!/usr/bin/python}}. This trick relies on {{ic|env}} searching for the first corresponding entry in the {{ic|PATH}} variable.<br />
<br />
First create a dummy folder:<br />
<br />
$ mkdir ~/bin<br />
<br />
Then add a symlink {{ic|python}} to ''python2'' and the config scripts in it:<br />
<br />
$ ln -s /usr/bin/python2 ~/bin/python<br />
$ ln -s /usr/bin/python2-config ~/bin/python-config<br />
<br />
Finally put the new folder ''at the beginning'' of your {{ic|PATH}} variable:<br />
<br />
$ export PATH=~/bin:$PATH<br />
<br />
{{Note|This method of changing [[environment variables]] is not permanent and is only active in the current terminal session.}}<br />
<br />
To check which python interpreter is being used by {{ic|env}}, use the following command:<br />
<br />
$ which python<br />
<br />
A similar approach in tricking the environment, which also relies on {{ic|#!/usr/bin/env python}} to be called by the script in question, is to use a [[#Virtual environment|virtual environment]].<br />
<br />
=== Alternative implementations ===<br />
<br />
Sections above refer to the reference implementation of Python, called CPython. However, there are also other implementations available - the most popular ones:<br />
<br />
* [[PyPy]] is a Python 2.7/3.5 implementation utilizing a JIT compiler. It is generally faster and uses less memory, but is not fully compatible with CPython (although the majority of packages and code will work without any changes).<br />
* [http://www.jython.org/ Jython] is a Python 2.7 implementation built in Java. It allows easy integration of Python and Java code, but is not fully compatible with CPython libraries. It is often used to provide Python as a scripting language in a bigger Java application.<br />
* [http://ironpython.net/ IronPython] is a Python 2.7 implementation built in .NET - it achieves the same goals as Jython, but for .NET languages (like C#/VB).<br />
* [https://micropython.org/ MicroPython] is a limited Python 3.4 implementation targeting microcontrollers and other embedded environments (like UEFI), but is incompatible with most standard packages due to [http://docs.micropython.org/en/latest/pyboard/genrst/index.html minor syntax changes and severely limited standard library]. It is often used for prototyping in with embedded environments (as it provides a Python REPL).<br />
* [[wikipedia:Python_(programming_language)#Implementations|More implementations are available]], although most are no longer maintained due to improvements in the most popular ones.<br />
<br />
=== Old versions ===<br />
<br />
{{warning|Python versions before 2.7 and 3.4 have not received any updates&mdash;including security patches&mdash;since at least 2014. Using older versions for Internet-facing applications or untrusted code may be dangerous and is not recommended.}}<br />
<br />
Old versions of Python are available via the [[AUR]] and may be useful for historical curiosity, old applications that do not run on current versions, or for testing Python programs intended to run on a distribution that comes with an older version:<br />
<br />
* Python 3.6: {{AUR|python36}}<br />
* Python 3.5: {{AUR|python35}}<br />
* Python 3.4: {{AUR|python34}}<br />
* Python 2.6: {{AUR|python26}}<br />
* Python 2.5: {{AUR|python25}}<br />
* Python 1.5: {{AUR|python15}}<br />
<br />
Extra modules/libraries for old versions of Python may be found on the AUR by searching for {{ic|python<''version without period''>}}, e.g. searching for "python26" for 2.6 modules.<br />
<br />
== Package management ==<br />
<br />
Although a great number of Python packages are readily available in the [[official repositories]] and the [[AUR]], the Python ecosystem provides its own package managers for use with [https://pypi.org/ PyPI], the Python Package Index:<br />
<br />
* {{App|pip|The PyPA tool for installing Python packages.|https://pip.pypa.io/| Manually download [https://bootstrap.pypa.io/#get-pip.py get-pip.py] and run: python get-pip.py }}<br />
* {{App|setuptools|Easily download, build, install, upgrade, and uninstall Python packages.|https://setuptools.readthedocs.io/|{{Pkg|python-setuptools}}, {{Pkg|python2-setuptools}}}}<br />
<br />
For a brief history and feature comparison between the two, see [https://packaging.python.org/pip_easy_install/#pip-vs-easy-install pip vs easy_install]. Authoritative best practices in Python package management are detailed [https://packaging.python.org/ here].<br />
<br />
If you must use ''pip'', use a [[#Virtual environment|virtual environment]], or {{ic|pip install --user}} to avoid conflicts with packages in {{ic|/usr}}. It is always preferred to [[System maintenance#Use the package manager to install software|use pacman to install software]].<br />
<br />
{{Note|There are also tools integrating ''pip'' with ''pacman'' by automatically generating PKGBUILDs for specified pip-packages: see [[Creating packages#PKGBUILD generators]].}}<br />
<br />
{{Tip|[https://docs.pipenv.org/ pipenv] provides a single CLI for [https://github.com/pypa/pipfile Pipfile], ''pip'' and [[virtualenv]]. It is available as {{Pkg|python-pipenv}} and {{Pkg|python2-pipenv}}.}}<br />
<br />
== Widget bindings ==<br />
<br />
The following [[Wikipedia:Widget toolkit|widget toolkit]] bindings are available:<br />
<br />
* {{App|TkInter|Tk bindings|https://wiki.python.org/moin/TkInter|standard module}}<br />
* {{App|pyQt|[[Qt]] bindings|https://riverbankcomputing.com/software/pyqt/intro|{{AUR|python2-pyqt4}} {{Pkg|python2-pyqt5}} {{AUR|python-pyqt4}} {{Pkg|python-pyqt5}}}}<br />
* {{App|pySide|[[Qt]] bindings|https://wiki.qt.io/PySide|{{AUR|python2-pyside}} {{AUR|python-pyside}}}}<br />
* {{App|pyGTK|[[GTK+|GTK+ 2]] bindings|http://www.pygtk.org/|{{Pkg|pygtk}}}}<br />
* {{App|PyGObject|[[GTK+|GTK+ 2/3]] bindings via GObject Introspection|https://wiki.gnome.org/PyGObject/|{{Pkg|python2-gobject2}} {{Pkg|python2-gobject}} {{Pkg|python-gobject2}} {{Pkg|python-gobject}}}}<br />
* {{App|wxPython|wxWidgets bindings|https://wxpython.org/|{{Pkg|python2-wxpython3}} {{Pkg|python-wxpython}}}}<br />
<br />
To use these with Python, you may need to install the associated widget kits.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Alternative shells ===<br />
<br />
* {{App|bpython|Fancy interface for the Python interpreter.|https://bpython-interpreter.org/|{{Pkg|bpython}} {{Pkg|bpython2}}}}<br />
* {{App|[[Wikipedia:IPython|IPython]]|Enhanced interactive Python shell.|https://ipython.org/|{{Pkg|ipython}} {{Pkg|ipython2}}}}<br />
* {{App|[[Jupyter]] Notebook|Web interface to IPython.|https://jupyter.org/|{{Pkg|jupyter-notebook}}}}<br />
* {{App|ptpython|Fancy interface for the Python interpreter based on [https://github.com/jonathanslenders/python-prompt-toolkit prompt-toolkit] input interface.|https://github.com/jonathanslenders/ptpython|{{aur|ptpython}} {{aur|ptpython2}}}}<br />
<br />
=== Virtual environment ===<br />
<br />
Python provides tools to create isolated environments in which you can install packages without interfering with the other virtual environments nor with the system Python's packages. It could change the ''python'' interpreter used for a specific application. <br />
<br />
See [[Python/Virtual environment]] for details.<br />
<br />
=== Tab completion in Python2 shell ===<br />
<br />
Since Python 3.4 [https://docs.python.org/3/tutorial/interactive.html tab completion] is enabled by default, for Python 2 you can manually enable it by adding the following lines to a file referenced by the {{ic|PYTHONSTARTUP}} environment variable: [https://algorithmicallyrandom.blogspot.co.at/2009/09/tab-completion-in-python-shell-how-to.html]<br />
<br />
import rlcompleter<br />
import readline<br />
readline.parse_and_bind("tab: complete")<br />
<br />
== Troubleshooting ==<br />
=== Dealing with version problem in build scripts ===<br />
<br />
{{Style|This is an ugly hack, instead explain how to recursively fix shebangs with {{ic|find}} and {{ic|sed}}.}}<br />
<br />
Many projects' build scripts assume {{ic|python}} to be Python 2, and that would eventually result in an error — typically complaining that {{ic|print 'foo'}} is invalid syntax. Luckily, many of them call ''python'' from the {{ic|PATH}} environment variable instead of hardcoding {{ic|#!/usr/bin/python}} in the shebang line, and the Python scripts are all contained within the project tree. So, instead of modifying the build scripts manually, there is a workaround. Create {{ic|/usr/local/bin/python}} with content like this:<br />
<br />
{{hc|/usr/local/bin/python|<nowiki><br />
#!/bin/bash<br />
script=$(readlink -f -- "$1")<br />
case "$script" in (/path/to/project1/*|/path/to/project2/*|/path/to/project3*)<br />
exec python2 "$@"<br />
;;<br />
esac<br />
<br />
exec python3 "$@"<br />
</nowiki>}}<br />
<br />
Where {{ic|<nowiki>/path/to/project1/*|/path/to/project2/*|/path/to/project3*</nowiki>}} is a list of patterns separated by {{ic|<nowiki>|</nowiki>}} matching all project trees. For some scripts, the path may not be the first parameter, for example Google SDK it sends "-S" as the first parameter. The readlink command should change to {{ic|1=script=$(readlink -f -- "$1")}}.<br />
<br />
Do not forget to make it [[executable]]. Afterwards scripts within the specified project trees will be run with Python 2.<br />
<br />
== See also ==<br />
<br />
* [http://shop.oreilly.com/product/0636920028154.do O'Reilly's Learning Python, 5th edition] commercial<br />
* [http://www.diveintopython.net/ Dive Into Python], [http://getpython3.com/diveintopython3/ Dive Into Python3]<br />
* [https://python.swaroopch.com/ A Byte of Python]<br />
* [https://learnpythonthehardway.org/ Learn Python the Hard Way]<br />
* [https://learnpython.org/ Learn Python]<br />
* [https://stephensugden.com/crash_into_python/ Crash into Python] (assumes familiarity with other programming languages)<br />
* [https://www.apress.com/book/9781590598726 Beginning Game Development with Python and Pygame] commercial<br />
* [http://www.greenteapress.com/thinkpython/ Think Python]<br />
* [https://pythonspot.com Pythonspot]<br />
* [https://overiq.com/python/3.4/intro-to-python/ OverIQ Python Tutorial]<br />
* [https://www.techbeamers.com/python-tutorial-step-by-step/ Python Tutorial to Learn Step by Step]<br />
* [https://github.com/vinta/awesome-python awesome-python] - A curated list of Python frameworks, libraries, software and resources.<br />
* [https://github.com/mahmoud/boltons boltons] - Constructs/recipes/snippets that would be handy in the standard library.</div>Medicineman25https://wiki.archlinux.org/index.php?title=Python&diff=551548Python2018-10-27T12:18:24Z<p>Medicineman25: /* Package management */ altered link description</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[de:Python]]<br />
[[es:Python]]<br />
[[ja:Python]]<br />
[[ko:Python]]<br />
[[ru:Python]]<br />
[[zh-hans:Python]]<br />
{{Related articles start}}<br />
{{Related|Python package guidelines}}<br />
{{Related|Python/Virtual environment}}<br />
{{Related|mod_wsgi}}<br />
{{Related|Django}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Python (programming language)|Wikipedia]]:<br />
<br />
:Python is a widely used high-level, general-purpose, interpreted, dynamic programming language. Its design philosophy emphasizes code readability, and its syntax allows programmers to express concepts in fewer lines of code than possible in languages such as C++ or Java. The language provides constructs intended to enable writing clear programs on both a small and large scale.<br />
:Python supports multiple programming paradigms, including object-oriented, imperative and functional programming or procedural styles. It features a dynamic type system and automatic memory management and has a large and comprehensive standard library.<br />
<br />
== Installation ==<br />
<br />
=== Python 3 ===<br />
<br />
Python 3 is the latest version of the language, and is incompatible with Python 2. The language is mostly the same, but many details, especially how built-in objects like dictionaries and strings work, have changed considerably, and a lot of deprecated features have finally been removed. Also, the standard library has been reorganized in a few prominent places. For an overview of the differences, visit [https://wiki.python.org/moin/Python2orPython3 Python2orPython3] and the relevant [http://getpython3.com/diveintopython3/porting-code-to-python-3-with-2to3.html chapter] in Dive into Python 3.<br />
<br />
To install the latest version of Python 3, [[install]] the {{Pkg|python}} package.<br />
<br />
If you would like to build the latest RC/betas from source, visit [https://www.python.org/downloads/ Python Downloads]. The [[Arch User Repository]] also contains good [[PKGBUILD]]s. If you do decide to build the RC, note that the binary (by default) installs to {{ic|/usr/local/bin/python3.x}}.<br />
<br />
=== Python 2 ===<br />
<br />
To get the latest version of Python 2, [[install]] the {{Pkg|python2}} package.<br />
<br />
Python 2 will happily run alongside Python 3. You need to specify {{ic|python2}} in order to run this version.<br />
<br />
Any program requiring Python 2 needs to point to {{ic|/usr/bin/python2}}, instead of {{ic|/usr/bin/python}}, which points to Python 3. To do so, open the program or script in a [[List of applications/Documents#Text editors|text editor]] and change the first line. The line will show one of the following:<br />
<br />
#!/usr/bin/env python<br />
<br />
or<br />
<br />
#!/usr/bin/python<br />
<br />
In both cases, just change {{ic|python}} to {{ic|python2}} and the program will then use Python 2 instead of Python 3.<br />
<br />
Another way to force the use of python2 without altering the scripts is to call it explicitly with {{ic|python2}}:<br />
<br />
$ python2 ''myScript.py''<br />
<br />
Finally, you may not be able to control the script calls, but there is a way to trick the environment. It only works if the scripts use {{ic|#!/usr/bin/env python}}. It will not work with {{ic|#!/usr/bin/python}}. This trick relies on {{ic|env}} searching for the first corresponding entry in the {{ic|PATH}} variable.<br />
<br />
First create a dummy folder:<br />
<br />
$ mkdir ~/bin<br />
<br />
Then add a symlink {{ic|python}} to ''python2'' and the config scripts in it:<br />
<br />
$ ln -s /usr/bin/python2 ~/bin/python<br />
$ ln -s /usr/bin/python2-config ~/bin/python-config<br />
<br />
Finally put the new folder ''at the beginning'' of your {{ic|PATH}} variable:<br />
<br />
$ export PATH=~/bin:$PATH<br />
<br />
{{Note|This method of changing [[environment variables]] is not permanent and is only active in the current terminal session.}}<br />
<br />
To check which python interpreter is being used by {{ic|env}}, use the following command:<br />
<br />
$ which python<br />
<br />
A similar approach in tricking the environment, which also relies on {{ic|#!/usr/bin/env python}} to be called by the script in question, is to use a [[#Virtual environment|virtual environment]].<br />
<br />
=== Alternative implementations ===<br />
<br />
Sections above refer to the reference implementation of Python, called CPython. However, there are also other implementations available - the most popular ones:<br />
<br />
* [[PyPy]] is a Python 2.7/3.5 implementation utilizing a JIT compiler. It is generally faster and uses less memory, but is not fully compatible with CPython (although the majority of packages and code will work without any changes).<br />
* [http://www.jython.org/ Jython] is a Python 2.7 implementation built in Java. It allows easy integration of Python and Java code, but is not fully compatible with CPython libraries. It is often used to provide Python as a scripting language in a bigger Java application.<br />
* [http://ironpython.net/ IronPython] is a Python 2.7 implementation built in .NET - it achieves the same goals as Jython, but for .NET languages (like C#/VB).<br />
* [https://micropython.org/ MicroPython] is a limited Python 3.4 implementation targeting microcontrollers and other embedded environments (like UEFI), but is incompatible with most standard packages due to [http://docs.micropython.org/en/latest/pyboard/genrst/index.html minor syntax changes and severely limited standard library]. It is often used for prototyping in with embedded environments (as it provides a Python REPL).<br />
* [[wikipedia:Python_(programming_language)#Implementations|More implementations are available]], although most are no longer maintained due to improvements in the most popular ones.<br />
<br />
=== Old versions ===<br />
<br />
{{warning|Python versions before 2.7 and 3.4 have not received any updates&mdash;including security patches&mdash;since at least 2014. Using older versions for Internet-facing applications or untrusted code may be dangerous and is not recommended.}}<br />
<br />
Old versions of Python are available via the [[AUR]] and may be useful for historical curiosity, old applications that do not run on current versions, or for testing Python programs intended to run on a distribution that comes with an older version:<br />
<br />
* Python 3.6: {{AUR|python36}}<br />
* Python 3.5: {{AUR|python35}}<br />
* Python 3.4: {{AUR|python34}}<br />
* Python 2.6: {{AUR|python26}}<br />
* Python 2.5: {{AUR|python25}}<br />
* Python 1.5: {{AUR|python15}}<br />
<br />
Extra modules/libraries for old versions of Python may be found on the AUR by searching for {{ic|python<''version without period''>}}, e.g. searching for "python26" for 2.6 modules.<br />
<br />
== Package management ==<br />
<br />
Although a great number of Python packages are readily available in the [[official repositories]] and the [[AUR]], the Python ecosystem provides its own package managers for use with [https://pypi.org/ PyPI], the Python Package Index:<br />
<br />
* {{App|pip|The PyPA tool for installing Python packages.|https://pip.pypa.io/| Manually download [https://bootstrap.pypa.io/#get-pip.py] and run: python get-pip.py }}<br />
* {{App|setuptools|Easily download, build, install, upgrade, and uninstall Python packages.|https://setuptools.readthedocs.io/|{{Pkg|python-setuptools}}, {{Pkg|python2-setuptools}}}}<br />
<br />
For a brief history and feature comparison between the two, see [https://packaging.python.org/pip_easy_install/#pip-vs-easy-install pip vs easy_install]. Authoritative best practices in Python package management are detailed [https://packaging.python.org/ here].<br />
<br />
If you must use ''pip'', use a [[#Virtual environment|virtual environment]], or {{ic|pip install --user}} to avoid conflicts with packages in {{ic|/usr}}. It is always preferred to [[System maintenance#Use the package manager to install software|use pacman to install software]].<br />
<br />
{{Note|There are also tools integrating ''pip'' with ''pacman'' by automatically generating PKGBUILDs for specified pip-packages: see [[Creating packages#PKGBUILD generators]].}}<br />
<br />
{{Tip|[https://docs.pipenv.org/ pipenv] provides a single CLI for [https://github.com/pypa/pipfile Pipfile], ''pip'' and [[virtualenv]]. It is available as {{Pkg|python-pipenv}} and {{Pkg|python2-pipenv}}.}}<br />
<br />
== Widget bindings ==<br />
<br />
The following [[Wikipedia:Widget toolkit|widget toolkit]] bindings are available:<br />
<br />
* {{App|TkInter|Tk bindings|https://wiki.python.org/moin/TkInter|standard module}}<br />
* {{App|pyQt|[[Qt]] bindings|https://riverbankcomputing.com/software/pyqt/intro|{{AUR|python2-pyqt4}} {{Pkg|python2-pyqt5}} {{AUR|python-pyqt4}} {{Pkg|python-pyqt5}}}}<br />
* {{App|pySide|[[Qt]] bindings|https://wiki.qt.io/PySide|{{AUR|python2-pyside}} {{AUR|python-pyside}}}}<br />
* {{App|pyGTK|[[GTK+|GTK+ 2]] bindings|http://www.pygtk.org/|{{Pkg|pygtk}}}}<br />
* {{App|PyGObject|[[GTK+|GTK+ 2/3]] bindings via GObject Introspection|https://wiki.gnome.org/PyGObject/|{{Pkg|python2-gobject2}} {{Pkg|python2-gobject}} {{Pkg|python-gobject2}} {{Pkg|python-gobject}}}}<br />
* {{App|wxPython|wxWidgets bindings|https://wxpython.org/|{{Pkg|python2-wxpython3}} {{Pkg|python-wxpython}}}}<br />
<br />
To use these with Python, you may need to install the associated widget kits.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Alternative shells ===<br />
<br />
* {{App|bpython|Fancy interface for the Python interpreter.|https://bpython-interpreter.org/|{{Pkg|bpython}} {{Pkg|bpython2}}}}<br />
* {{App|[[Wikipedia:IPython|IPython]]|Enhanced interactive Python shell.|https://ipython.org/|{{Pkg|ipython}} {{Pkg|ipython2}}}}<br />
* {{App|[[Jupyter]] Notebook|Web interface to IPython.|https://jupyter.org/|{{Pkg|jupyter-notebook}}}}<br />
* {{App|ptpython|Fancy interface for the Python interpreter based on [https://github.com/jonathanslenders/python-prompt-toolkit prompt-toolkit] input interface.|https://github.com/jonathanslenders/ptpython|{{aur|ptpython}} {{aur|ptpython2}}}}<br />
<br />
=== Virtual environment ===<br />
<br />
Python provides tools to create isolated environments in which you can install packages without interfering with the other virtual environments nor with the system Python's packages. It could change the ''python'' interpreter used for a specific application. <br />
<br />
See [[Python/Virtual environment]] for details.<br />
<br />
=== Tab completion in Python2 shell ===<br />
<br />
Since Python 3.4 [https://docs.python.org/3/tutorial/interactive.html tab completion] is enabled by default, for Python 2 you can manually enable it by adding the following lines to a file referenced by the {{ic|PYTHONSTARTUP}} environment variable: [https://algorithmicallyrandom.blogspot.co.at/2009/09/tab-completion-in-python-shell-how-to.html]<br />
<br />
import rlcompleter<br />
import readline<br />
readline.parse_and_bind("tab: complete")<br />
<br />
== Troubleshooting ==<br />
=== Dealing with version problem in build scripts ===<br />
<br />
{{Style|This is an ugly hack, instead explain how to recursively fix shebangs with {{ic|find}} and {{ic|sed}}.}}<br />
<br />
Many projects' build scripts assume {{ic|python}} to be Python 2, and that would eventually result in an error — typically complaining that {{ic|print 'foo'}} is invalid syntax. Luckily, many of them call ''python'' from the {{ic|PATH}} environment variable instead of hardcoding {{ic|#!/usr/bin/python}} in the shebang line, and the Python scripts are all contained within the project tree. So, instead of modifying the build scripts manually, there is a workaround. Create {{ic|/usr/local/bin/python}} with content like this:<br />
<br />
{{hc|/usr/local/bin/python|<nowiki><br />
#!/bin/bash<br />
script=$(readlink -f -- "$1")<br />
case "$script" in (/path/to/project1/*|/path/to/project2/*|/path/to/project3*)<br />
exec python2 "$@"<br />
;;<br />
esac<br />
<br />
exec python3 "$@"<br />
</nowiki>}}<br />
<br />
Where {{ic|<nowiki>/path/to/project1/*|/path/to/project2/*|/path/to/project3*</nowiki>}} is a list of patterns separated by {{ic|<nowiki>|</nowiki>}} matching all project trees. For some scripts, the path may not be the first parameter, for example Google SDK it sends "-S" as the first parameter. The readlink command should change to {{ic|1=script=$(readlink -f -- "$1")}}.<br />
<br />
Do not forget to make it [[executable]]. Afterwards scripts within the specified project trees will be run with Python 2.<br />
<br />
== See also ==<br />
<br />
* [http://shop.oreilly.com/product/0636920028154.do O'Reilly's Learning Python, 5th edition] commercial<br />
* [http://www.diveintopython.net/ Dive Into Python], [http://getpython3.com/diveintopython3/ Dive Into Python3]<br />
* [https://python.swaroopch.com/ A Byte of Python]<br />
* [https://learnpythonthehardway.org/ Learn Python the Hard Way]<br />
* [https://learnpython.org/ Learn Python]<br />
* [https://stephensugden.com/crash_into_python/ Crash into Python] (assumes familiarity with other programming languages)<br />
* [https://www.apress.com/book/9781590598726 Beginning Game Development with Python and Pygame] commercial<br />
* [http://www.greenteapress.com/thinkpython/ Think Python]<br />
* [https://pythonspot.com Pythonspot]<br />
* [https://overiq.com/python/3.4/intro-to-python/ OverIQ Python Tutorial]<br />
* [https://www.techbeamers.com/python-tutorial-step-by-step/ Python Tutorial to Learn Step by Step]<br />
* [https://github.com/vinta/awesome-python awesome-python] - A curated list of Python frameworks, libraries, software and resources.<br />
* [https://github.com/mahmoud/boltons boltons] - Constructs/recipes/snippets that would be handy in the standard library.</div>Medicineman25https://wiki.archlinux.org/index.php?title=Python&diff=551547Python2018-10-27T12:16:51Z<p>Medicineman25: /* Package management */ bot pip packages have been flagged as OOD</p>
<hr />
<div>[[Category:Programming languages]]<br />
[[de:Python]]<br />
[[es:Python]]<br />
[[ja:Python]]<br />
[[ko:Python]]<br />
[[ru:Python]]<br />
[[zh-hans:Python]]<br />
{{Related articles start}}<br />
{{Related|Python package guidelines}}<br />
{{Related|Python/Virtual environment}}<br />
{{Related|mod_wsgi}}<br />
{{Related|Django}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Python (programming language)|Wikipedia]]:<br />
<br />
:Python is a widely used high-level, general-purpose, interpreted, dynamic programming language. Its design philosophy emphasizes code readability, and its syntax allows programmers to express concepts in fewer lines of code than possible in languages such as C++ or Java. The language provides constructs intended to enable writing clear programs on both a small and large scale.<br />
:Python supports multiple programming paradigms, including object-oriented, imperative and functional programming or procedural styles. It features a dynamic type system and automatic memory management and has a large and comprehensive standard library.<br />
<br />
== Installation ==<br />
<br />
=== Python 3 ===<br />
<br />
Python 3 is the latest version of the language, and is incompatible with Python 2. The language is mostly the same, but many details, especially how built-in objects like dictionaries and strings work, have changed considerably, and a lot of deprecated features have finally been removed. Also, the standard library has been reorganized in a few prominent places. For an overview of the differences, visit [https://wiki.python.org/moin/Python2orPython3 Python2orPython3] and the relevant [http://getpython3.com/diveintopython3/porting-code-to-python-3-with-2to3.html chapter] in Dive into Python 3.<br />
<br />
To install the latest version of Python 3, [[install]] the {{Pkg|python}} package.<br />
<br />
If you would like to build the latest RC/betas from source, visit [https://www.python.org/downloads/ Python Downloads]. The [[Arch User Repository]] also contains good [[PKGBUILD]]s. If you do decide to build the RC, note that the binary (by default) installs to {{ic|/usr/local/bin/python3.x}}.<br />
<br />
=== Python 2 ===<br />
<br />
To get the latest version of Python 2, [[install]] the {{Pkg|python2}} package.<br />
<br />
Python 2 will happily run alongside Python 3. You need to specify {{ic|python2}} in order to run this version.<br />
<br />
Any program requiring Python 2 needs to point to {{ic|/usr/bin/python2}}, instead of {{ic|/usr/bin/python}}, which points to Python 3. To do so, open the program or script in a [[List of applications/Documents#Text editors|text editor]] and change the first line. The line will show one of the following:<br />
<br />
#!/usr/bin/env python<br />
<br />
or<br />
<br />
#!/usr/bin/python<br />
<br />
In both cases, just change {{ic|python}} to {{ic|python2}} and the program will then use Python 2 instead of Python 3.<br />
<br />
Another way to force the use of python2 without altering the scripts is to call it explicitly with {{ic|python2}}:<br />
<br />
$ python2 ''myScript.py''<br />
<br />
Finally, you may not be able to control the script calls, but there is a way to trick the environment. It only works if the scripts use {{ic|#!/usr/bin/env python}}. It will not work with {{ic|#!/usr/bin/python}}. This trick relies on {{ic|env}} searching for the first corresponding entry in the {{ic|PATH}} variable.<br />
<br />
First create a dummy folder:<br />
<br />
$ mkdir ~/bin<br />
<br />
Then add a symlink {{ic|python}} to ''python2'' and the config scripts in it:<br />
<br />
$ ln -s /usr/bin/python2 ~/bin/python<br />
$ ln -s /usr/bin/python2-config ~/bin/python-config<br />
<br />
Finally put the new folder ''at the beginning'' of your {{ic|PATH}} variable:<br />
<br />
$ export PATH=~/bin:$PATH<br />
<br />
{{Note|This method of changing [[environment variables]] is not permanent and is only active in the current terminal session.}}<br />
<br />
To check which python interpreter is being used by {{ic|env}}, use the following command:<br />
<br />
$ which python<br />
<br />
A similar approach in tricking the environment, which also relies on {{ic|#!/usr/bin/env python}} to be called by the script in question, is to use a [[#Virtual environment|virtual environment]].<br />
<br />
=== Alternative implementations ===<br />
<br />
Sections above refer to the reference implementation of Python, called CPython. However, there are also other implementations available - the most popular ones:<br />
<br />
* [[PyPy]] is a Python 2.7/3.5 implementation utilizing a JIT compiler. It is generally faster and uses less memory, but is not fully compatible with CPython (although the majority of packages and code will work without any changes).<br />
* [http://www.jython.org/ Jython] is a Python 2.7 implementation built in Java. It allows easy integration of Python and Java code, but is not fully compatible with CPython libraries. It is often used to provide Python as a scripting language in a bigger Java application.<br />
* [http://ironpython.net/ IronPython] is a Python 2.7 implementation built in .NET - it achieves the same goals as Jython, but for .NET languages (like C#/VB).<br />
* [https://micropython.org/ MicroPython] is a limited Python 3.4 implementation targeting microcontrollers and other embedded environments (like UEFI), but is incompatible with most standard packages due to [http://docs.micropython.org/en/latest/pyboard/genrst/index.html minor syntax changes and severely limited standard library]. It is often used for prototyping in with embedded environments (as it provides a Python REPL).<br />
* [[wikipedia:Python_(programming_language)#Implementations|More implementations are available]], although most are no longer maintained due to improvements in the most popular ones.<br />
<br />
=== Old versions ===<br />
<br />
{{warning|Python versions before 2.7 and 3.4 have not received any updates&mdash;including security patches&mdash;since at least 2014. Using older versions for Internet-facing applications or untrusted code may be dangerous and is not recommended.}}<br />
<br />
Old versions of Python are available via the [[AUR]] and may be useful for historical curiosity, old applications that do not run on current versions, or for testing Python programs intended to run on a distribution that comes with an older version:<br />
<br />
* Python 3.6: {{AUR|python36}}<br />
* Python 3.5: {{AUR|python35}}<br />
* Python 3.4: {{AUR|python34}}<br />
* Python 2.6: {{AUR|python26}}<br />
* Python 2.5: {{AUR|python25}}<br />
* Python 1.5: {{AUR|python15}}<br />
<br />
Extra modules/libraries for old versions of Python may be found on the AUR by searching for {{ic|python<''version without period''>}}, e.g. searching for "python26" for 2.6 modules.<br />
<br />
== Package management ==<br />
<br />
Although a great number of Python packages are readily available in the [[official repositories]] and the [[AUR]], the Python ecosystem provides its own package managers for use with [https://pypi.org/ PyPI], the Python Package Index:<br />
<br />
* {{App|pip|The PyPA tool for installing Python packages.|https://pip.pypa.io/| Manually download [https://bootstrap.pypa.io/get-pip.py] and run: python get-pip.py }}<br />
* {{App|setuptools|Easily download, build, install, upgrade, and uninstall Python packages.|https://setuptools.readthedocs.io/|{{Pkg|python-setuptools}}, {{Pkg|python2-setuptools}}}}<br />
<br />
For a brief history and feature comparison between the two, see [https://packaging.python.org/pip_easy_install/#pip-vs-easy-install pip vs easy_install]. Authoritative best practices in Python package management are detailed [https://packaging.python.org/ here].<br />
<br />
If you must use ''pip'', use a [[#Virtual environment|virtual environment]], or {{ic|pip install --user}} to avoid conflicts with packages in {{ic|/usr}}. It is always preferred to [[System maintenance#Use the package manager to install software|use pacman to install software]].<br />
<br />
{{Note|There are also tools integrating ''pip'' with ''pacman'' by automatically generating PKGBUILDs for specified pip-packages: see [[Creating packages#PKGBUILD generators]].}}<br />
<br />
{{Tip|[https://docs.pipenv.org/ pipenv] provides a single CLI for [https://github.com/pypa/pipfile Pipfile], ''pip'' and [[virtualenv]]. It is available as {{Pkg|python-pipenv}} and {{Pkg|python2-pipenv}}.}}<br />
<br />
== Widget bindings ==<br />
<br />
The following [[Wikipedia:Widget toolkit|widget toolkit]] bindings are available:<br />
<br />
* {{App|TkInter|Tk bindings|https://wiki.python.org/moin/TkInter|standard module}}<br />
* {{App|pyQt|[[Qt]] bindings|https://riverbankcomputing.com/software/pyqt/intro|{{AUR|python2-pyqt4}} {{Pkg|python2-pyqt5}} {{AUR|python-pyqt4}} {{Pkg|python-pyqt5}}}}<br />
* {{App|pySide|[[Qt]] bindings|https://wiki.qt.io/PySide|{{AUR|python2-pyside}} {{AUR|python-pyside}}}}<br />
* {{App|pyGTK|[[GTK+|GTK+ 2]] bindings|http://www.pygtk.org/|{{Pkg|pygtk}}}}<br />
* {{App|PyGObject|[[GTK+|GTK+ 2/3]] bindings via GObject Introspection|https://wiki.gnome.org/PyGObject/|{{Pkg|python2-gobject2}} {{Pkg|python2-gobject}} {{Pkg|python-gobject2}} {{Pkg|python-gobject}}}}<br />
* {{App|wxPython|wxWidgets bindings|https://wxpython.org/|{{Pkg|python2-wxpython3}} {{Pkg|python-wxpython}}}}<br />
<br />
To use these with Python, you may need to install the associated widget kits.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Alternative shells ===<br />
<br />
* {{App|bpython|Fancy interface for the Python interpreter.|https://bpython-interpreter.org/|{{Pkg|bpython}} {{Pkg|bpython2}}}}<br />
* {{App|[[Wikipedia:IPython|IPython]]|Enhanced interactive Python shell.|https://ipython.org/|{{Pkg|ipython}} {{Pkg|ipython2}}}}<br />
* {{App|[[Jupyter]] Notebook|Web interface to IPython.|https://jupyter.org/|{{Pkg|jupyter-notebook}}}}<br />
* {{App|ptpython|Fancy interface for the Python interpreter based on [https://github.com/jonathanslenders/python-prompt-toolkit prompt-toolkit] input interface.|https://github.com/jonathanslenders/ptpython|{{aur|ptpython}} {{aur|ptpython2}}}}<br />
<br />
=== Virtual environment ===<br />
<br />
Python provides tools to create isolated environments in which you can install packages without interfering with the other virtual environments nor with the system Python's packages. It could change the ''python'' interpreter used for a specific application. <br />
<br />
See [[Python/Virtual environment]] for details.<br />
<br />
=== Tab completion in Python2 shell ===<br />
<br />
Since Python 3.4 [https://docs.python.org/3/tutorial/interactive.html tab completion] is enabled by default, for Python 2 you can manually enable it by adding the following lines to a file referenced by the {{ic|PYTHONSTARTUP}} environment variable: [https://algorithmicallyrandom.blogspot.co.at/2009/09/tab-completion-in-python-shell-how-to.html]<br />
<br />
import rlcompleter<br />
import readline<br />
readline.parse_and_bind("tab: complete")<br />
<br />
== Troubleshooting ==<br />
=== Dealing with version problem in build scripts ===<br />
<br />
{{Style|This is an ugly hack, instead explain how to recursively fix shebangs with {{ic|find}} and {{ic|sed}}.}}<br />
<br />
Many projects' build scripts assume {{ic|python}} to be Python 2, and that would eventually result in an error — typically complaining that {{ic|print 'foo'}} is invalid syntax. Luckily, many of them call ''python'' from the {{ic|PATH}} environment variable instead of hardcoding {{ic|#!/usr/bin/python}} in the shebang line, and the Python scripts are all contained within the project tree. So, instead of modifying the build scripts manually, there is a workaround. Create {{ic|/usr/local/bin/python}} with content like this:<br />
<br />
{{hc|/usr/local/bin/python|<nowiki><br />
#!/bin/bash<br />
script=$(readlink -f -- "$1")<br />
case "$script" in (/path/to/project1/*|/path/to/project2/*|/path/to/project3*)<br />
exec python2 "$@"<br />
;;<br />
esac<br />
<br />
exec python3 "$@"<br />
</nowiki>}}<br />
<br />
Where {{ic|<nowiki>/path/to/project1/*|/path/to/project2/*|/path/to/project3*</nowiki>}} is a list of patterns separated by {{ic|<nowiki>|</nowiki>}} matching all project trees. For some scripts, the path may not be the first parameter, for example Google SDK it sends "-S" as the first parameter. The readlink command should change to {{ic|1=script=$(readlink -f -- "$1")}}.<br />
<br />
Do not forget to make it [[executable]]. Afterwards scripts within the specified project trees will be run with Python 2.<br />
<br />
== See also ==<br />
<br />
* [http://shop.oreilly.com/product/0636920028154.do O'Reilly's Learning Python, 5th edition] commercial<br />
* [http://www.diveintopython.net/ Dive Into Python], [http://getpython3.com/diveintopython3/ Dive Into Python3]<br />
* [https://python.swaroopch.com/ A Byte of Python]<br />
* [https://learnpythonthehardway.org/ Learn Python the Hard Way]<br />
* [https://learnpython.org/ Learn Python]<br />
* [https://stephensugden.com/crash_into_python/ Crash into Python] (assumes familiarity with other programming languages)<br />
* [https://www.apress.com/book/9781590598726 Beginning Game Development with Python and Pygame] commercial<br />
* [http://www.greenteapress.com/thinkpython/ Think Python]<br />
* [https://pythonspot.com Pythonspot]<br />
* [https://overiq.com/python/3.4/intro-to-python/ OverIQ Python Tutorial]<br />
* [https://www.techbeamers.com/python-tutorial-step-by-step/ Python Tutorial to Learn Step by Step]<br />
* [https://github.com/vinta/awesome-python awesome-python] - A curated list of Python frameworks, libraries, software and resources.<br />
* [https://github.com/mahmoud/boltons boltons] - Constructs/recipes/snippets that would be handy in the standard library.</div>Medicineman25https://wiki.archlinux.org/index.php?title=LVM&diff=551231LVM2018-10-26T11:08:38Z<p>Medicineman25: changed the snapshot syntax to reflect using a logical volume in: "# lvcreate --size 100M --snapshot --name snap01 /dev/vg0/lv" instead of "/dev/vg0/pv". Cannot take snapshots of physical volumes.</p>
<hr />
<div>[[Category:Storage virtualization]]<br />
[[cs:LVM]]<br />
[[de:LVM]]<br />
[[es:LVM]]<br />
[[fr:LVM]]<br />
[[it:LVM]]<br />
[[ja:LVM]]<br />
[[ru:LVM]]<br />
[[pl:LVM]]<br />
[[zh-hans:LVM]]<br />
{{Related articles start}}<br />
{{Related|Software RAID and LVM}}<br />
{{Related|dm-crypt/Encrypting an entire system#LVM on LUKS}}<br />
{{Related|dm-crypt/Encrypting an entire system#LUKS on LVM}}<br />
{{Related|Resizing LVM-on-LUKS}}<br />
{{Related|Create root filesystem snapshots with LVM}}<br />
{{Related articles end}}<br />
From [[Wikipedia:Logical Volume Manager (Linux)]]:<br />
:LVM is a [[Wikipedia:logical volume management|logical volume manager]] for the [[Wikipedia:Linux kernel|Linux kernel]]; it manages disk drives and similar mass-storage devices.<br />
<br />
== LVM Building Blocks ==<br />
<br />
Logical Volume Management utilizes the kernel's [http://sources.redhat.com/dm/ device-mapper] feature to provide a system of partitions independent of underlying disk layout. With LVM you abstract your storage and have "virtual partitions", making [[#Resizing volumes|extending/shrinking]] easier (subject to potential filesystem limitations).<br />
<br />
Virtual partitions allow addition and removal without worry of whether you have enough contiguous space on a particular disk, getting caught up fdisking a disk in use (and wondering whether the kernel is using the old or new partition table), or, having to move other partitions out of the way. This is strictly an ease-of-management solution: LVM adds no security.<br />
<br />
Basic building blocks of LVM:<br />
<br />
; Physical volume (PV): Partition on hard disk (or even the disk itself or loopback file) on which you can have volume groups. It has a special header and is divided into physical extents. Think of physical volumes as big building blocks used to build your hard drive.<br />
; Volume group (VG): Group of physical volumes used as a storage volume (as one disk). They contain logical volumes. Think of volume groups as hard drives.<br />
; Logical volume (LV): A "virtual/logical partition" that resides in a volume group and is composed of physical extents. Think of logical volumes as normal partitions.<br />
; Physical extent (PE): The smallest size in the physical volume that can be assigned to a logical volume (default 4 MiB). Think of physical extents as parts of disks that can be allocated to any partition.<br />
<br />
Example:<br />
<br />
{{Text art|<nowiki><br />
Physical disks<br />
<br />
Disk1 (/dev/sda):<br />
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _<br />
|Partition1 50 GiB (Physical volume) |Partition2 80 GiB (Physical volume) |<br />
|/dev/sda1 |/dev/sda2 |<br />
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |<br />
<br />
Disk2 (/dev/sdb):<br />
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _<br />
|Partition1 120 GiB (Physical volume) |<br />
|/dev/sdb1 |<br />
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
</nowiki>}}<br />
<br />
{{Text art|<nowiki><br />
LVM logical volumes<br />
<br />
Volume Group1 (/dev/MyVolGroup/ = /dev/sda1 + /dev/sda2 + /dev/sdb1):<br />
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _<br />
|Logical volume1 15 GiB |Logical volume2 35 GiB |Logical volume3 200 GiB |<br />
|/dev/MyVolGroup/rootvol |/dev/MyVolGroup/homevol |/dev/MyVolGroup/mediavol |<br />
|_ _ _ _ _ _ _ _ _ _ _ _ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
</nowiki>}}<br />
<br />
== Advantages ==<br />
<br />
LVM gives you more flexibility than just using normal hard drive partitions:<br />
<br />
* Use any number of disks as one big disk.<br />
* Have logical volumes stretched over several disks.<br />
* Create small logical volumes and resize them "dynamically" as they get filled up.<br />
* Resize logical volumes regardless of their order on disk. It does not depend on the position of the LV within VG, there is no need to ensure surrounding available space.<br />
* Resize/create/delete logical and physical volumes online. File systems on them still need to be resized, but some (such as ext4) support online resizing.<br />
* Online/live migration of LV being used by services to different disks without having to restart services.<br />
* Snapshots allow you to backup a frozen copy of the file system, while keeping service downtime to a minimum.<br />
* Support for various device-mapper targets, including transparent filesystem encryption and caching of frequently used data. This allows creating a system with (one or more) physical disks (encrypted with LUKS) and [[dm-crypt/Encrypting an entire system#LVM on LUKS|LVM on top]] to allow for easy resizing and management of separate volumes (e.g. for {{ic|/}}, {{ic|/home}}, {{ic|/backup}}, etc.) without the hassle of entering a key multiple times on boot.<br />
<br />
== Disadvantages ==<br />
<br />
* Additional steps in setting up the system, more complicated.<br />
* If dual-booting, note that Windows does not support LVM; you will be unable to access any LVM partitions from Windows.<br />
<br />
== Installing Arch Linux on LVM ==<br />
<br />
You should create your LVM Volumes between the [[partitioning]] and [[File systems#Create a file system|formatting]] steps of the [[Installation guide|installation procedure]]. Instead of directly formatting a partition to be your root file system, the file system will be created inside a logical volume (LV). <br />
<br />
Make sure the {{pkg|lvm2}} package is [[install]]ed.<br />
<br />
Quick overview: <br />
<br />
* Create [[Partitioning|partition(s)]] where your PV(s) will reside.<br />
* Create your physical volumes (PVs). If you have one disk it is best to just create one PV in one large partition. If you have multiple disks you can create partitions on each of them and create a PV on each partition.<br />
* Create your volume group (VG) and add all PVs to it.<br />
* Create logical volumes (LVs) inside that VG.<br />
* Continue with [[Installation guide#Format the partitions]].<br />
* When you reach the “Create initial ramdisk environment” step in the Installation guide, add the {{ic|lvm}} hook to {{ic|/etc/mkinitcpio.conf}} (see below for details).<br />
<br />
{{Warning|{{ic|/boot}} cannot reside in LVM when using a boot loader which does not support LVM; you must create a separate {{ic|/boot}} partition and format it directly. Only [[GRUB]] is known to support LVM.}}<br />
<br />
=== Create partitions ===<br />
<br />
[[Partition]] the device as required before configuring LVM.<br />
<br />
Create the partitions:<br />
<br />
* If you use Master Boot Record partition table, set the [[Wikipedia:Partition type|partition type ID]] to {{ic|8e}} (partition type {{ic|Linux LVM}} in ''fdisk'').<br />
* If you use GUID Partition Table, set the [[Wikipedia:GUID Partition Table#Partition type GUIDs|partition type GUID]] to {{ic|E6D6D379-F507-44C2-A23C-238F2A3DF928}} (partition type {{ic|Linux LVM}} in ''fdisk'' and {{ic|8e00}} in ''gdisk'').<br />
<br />
=== Create physical volumes ===<br />
<br />
To list all your devices capable of being used as a physical volume:<br />
<br />
# lvmdiskscan<br />
<br />
{{Warning|Make sure you target the correct device, or below commands will result in data loss!}}<br />
<br />
Create a physical volume on them:<br />
<br />
# pvcreate ''DEVICE''<br />
<br />
This command creates a header on each device so it can be used for LVM. As defined in [[#LVM Building Blocks]], ''DEVICE'' can be a disk (e.g. {{ic|/dev/sda}}), a partition (e.g. {{ic|/dev/sda2}}) or a loop back device. For example: <br />
<br />
# pvcreate /dev/sda2<br />
<br />
You can track created physical volumes with:<br />
<br />
# pvdisplay<br />
<br />
{{Note|If using a SSD without partitioning it first, use {{ic|pvcreate --dataalignment 1m /dev/sda}} (for erase block size < 1 MiB), see e.g. [http://serverfault.com/questions/356534/ssd-erase-block-size-lvm-pv-on-raw-device-alignment here]}}<br />
<br />
=== Create volume group ===<br />
<br />
The next step is to create a volume group on this physical volume.<br />
<br />
First you need to create a volume group on one of the physical volumes:<br />
<br />
# vgcreate <''volume_group''> <''physical_volume''><br />
<br />
See {{man|8|lvm}} for a list of valid characters for volume group names.<br />
<br />
For example:<br />
<br />
# vgcreate VolGroup00 /dev/sda2<br />
<br />
Then add to it all other physical volumes you want to have in it:<br />
<br />
# vgextend <''volume_group''> <''physical_volume''><br />
# vgextend <''volume_group''> <''another_physical_volume''><br />
# ...<br />
<br />
For example:<br />
<br />
# vgextend VolGroup00 /dev/sdb1<br />
# vgextend VolGroup00 /dev/sdc<br />
<br />
You can track how your volume group grows with:<br />
<br />
# vgdisplay<br />
<br />
{{Note|You can create more than one volume group if you need to, but then you will not have all your storage presented as one disk.}}<br />
<br />
=== Create in one step ===<br />
<br />
LVM allows you to combine the creation of a volume group and the physical volumes in one easy step. For example, to create the group VolGroup00 with the three devices mentioned above, you can run:<br />
<br />
# vgcreate VolGroup00 /dev/sda2 /dev/sdb1 /dev/sdc<br />
<br />
This command will first set up the three partitions as physical volumes (if necessary) and then create the volume group with the three volumes. The command will warn you it detects an existing filesystem on any of the devices.<br />
<br />
=== Create logical volumes ===<br />
<br />
{{Tip|If you wish to use snapshots, logical volume caching, thin provisioned logical volumes or RAID see [[#Logical volume types]].}}<br />
<br />
Now we need to create logical volumes on this volume group. You create a logical volume with the next command by giving the name of a new logical volume, its size, and the volume group it will live on:<br />
<br />
# lvcreate -L <''size''> <''volume_group''> -n <''logical_volume''><br />
<br />
For example:<br />
<br />
# lvcreate -L 10G VolGroup00 -n lvolhome<br />
<br />
This will create a logical volume that you can access later with {{ic|/dev/VolGroup00/lvolhome}}. Just like volume groups, you can use any name you want for your logical volume when creating it besides a few exceptions listed in {{man|8|lvm|VALID_NAMES}}.<br />
<br />
You can also specify one or more physical volumes to restrict where LVM allocates the data. For example, you may wish to create a logical volume for the root filesystem on your small SSD, and your home volume on a slower mechanical drive. Simply add the physical volume devices to the command line, for example:<br />
<br />
# lvcreate -L 10G VolGroup00 -n lvolhome /dev/sdc1<br />
<br />
If you want to fill all the free space left on a volume group, use the next command:<br />
<br />
# lvcreate -l 100%FREE <''volume_group''> -n <''logical_volume''><br />
<br />
You can track created logical volumes with:<br />
<br />
# lvdisplay<br />
<br />
{{Note|You may need to load the ''device-mapper'' kernel module ({{ic|modprobe dm_mod'}}) for the above commands to succeed.}}<br />
<br />
{{Tip|You can start out with relatively small logical volumes and expand them later if needed. For simplicity, leave some free space in the volume group so there is room for expansion.}}<br />
<br />
=== Create file systems and mount logical volumes ===<br />
<br />
Your logical volumes should now be located in {{ic|/dev/''YourVolumeGroupName''/}}. If you cannot find them, use the next commands to bring up the module for creating device nodes and to make volume groups available:<br />
<br />
# modprobe dm_mod<br />
# vgscan<br />
# vgchange -ay<br />
<br />
Now you can create file systems on logical volumes and mount them as normal partitions (if you are installing Arch linux, refer to [[mount|mounting the partitions]] for additional details):<br />
<br />
# mkfs.<''fstype''> /dev/<''volume_group''>/<''logical_volume''><br />
# mount /dev/<''volume_group''>/<''logical_volume''> /<''mountpoint''><br />
<br />
For example:<br />
<br />
# mkfs.ext4 /dev/VolGroup00/lvolhome<br />
# mount /dev/VolGroup00/lvolhome /home<br />
<br />
{{Warning|When choosing mountpoints, just select your newly created logical volumes (use: {{ic|/dev/Volgroup00/lvolhome}}). Do '''not''' select the actual partitions on which logical volumes were created (do not use: {{ic|/dev/sda2}}).}}<br />
<br />
=== Configure mkinitcpio ===<br />
<br />
In case your root filesystem is on LVM, you will need to enable the appropriate [[mkinitcpio]] hooks, otherwise your system might not boot. Enable:<br />
<br />
* {{ic|udev}} and {{ic|lvm2}} for the default busybox based initramfs<br />
* {{ic|systemd}} and {{ic|sd-lvm2}} for systemd based initramfs<br />
<br />
{{ic|udev}} is there by default. Edit the file and insert {{ic|lvm2}} between {{ic|block}} and {{ic|filesystems}} like so:<br />
<br />
{{hc|1=/etc/mkinitcpio.conf|2=<br />
HOOKS=(base '''udev''' ... block '''lvm2''' filesystems)<br />
}}<br />
<br />
For systemd based initramfs:<br />
<br />
{{hc|1=/etc/mkinitcpio.conf|2=<br />
HOOKS=(base '''systemd''' ... block '''sd-lvm2''' filesystems)<br />
}}<br />
<br />
Afterwards, you can continue in normal installation instructions with the [[mkinitcpio#Image creation and activation|create an initial ramdisk]] step.<br />
<br />
{{Tip|<br />
* The {{ic|lvm2}} and {{ic|sd-lvm2}} hooks are installed by {{pkg|lvm2}}, not {{pkg|mkinitcpio}}. If you are running ''mkinitcpio'' in an ''arch-chroot'' for a new installation, {{pkg|lvm2}} must be installed inside the ''arch-chroot'' for ''mkinitcpio'' to find the {{ic|lvm2}} or {{ic|sd-lvm2}} hook. If {{pkg|lvm2}} only exists outside the ''arch-chroot'', ''mkinitcpio'' will output {{ic|Error: Hook 'lvm2' cannot be found}}.<br />
* If your root filesystem is on LVM RAID see [[#Configure mkinitcpio for RAID]].<br />
}}<br />
<br />
=== Kernel options ===<br />
<br />
If the root file system resides in a logical volume, the {{ic|1=root=}} [[kernel parameter]] must be pointed to the mapped device, e.g {{ic|/dev/''vg-name''/''lv-name''}}.<br />
<br />
== Volume operations ==<br />
<br />
=== Advanced options ===<br />
<br />
You can restrict the volumes that are activated automatically by setting the {{ic|auto_activation_volume_list}} in {{ic|/etc/lvm/lvm.conf}}. If in doubt, leave this option commented out.<br />
<br />
=== Resizing volumes ===<br />
<br />
==== Physical volumes ====<br />
<br />
After extending or prior to reducing the size of a device that has a physical volume on it, you need to grow or shrink the PV using {{ic|pvresize}}.<br />
<br />
===== Growing =====<br />
<br />
To expand the PV on {{ic|/dev/sda1}} after enlarging the [[partition]], run:<br />
<br />
# pvresize /dev/sda1<br />
<br />
This will automatically detect the new size of the device and extend the PV to its maximum.<br />
<br />
{{Note|This command can be done while the volume is online.}}<br />
<br />
===== Shrinking =====<br />
<br />
To shrink a physical volume prior to reducing its underlying device, add the {{ic|--setphysicalvolumesize ''size''}} parameters to the command, ''e.g.'':<br />
<br />
# pvresize --setphysicalvolumesize 40G /dev/sda1<br />
<br />
The above command may leave you with this error:<br />
<br />
/dev/sda1: cannot resize to 25599 extents as later ones are allocated.<br />
0 physical volume(s) resized / 1 physical volume(s) not resized<br />
<br />
Indeed {{ic|pvresize}} will refuse to shrink a PV if it has allocated extents after where its new end would be. One needs to run [[#Move physical extents|pvmove]] beforehand to relocate these elsewhere in the volume group if there is sufficient free space.<br />
<br />
====== Move physical extents ======<br />
<br />
Before moving free extents to the end of the volume, one must run {{ic|pvdisplay -v -m}} to see physical segments. In the below example, there is one physical volume on {{ic|/dev/sdd1}}, one volume group {{ic|vg1}} and one logical volume {{ic|backup}}.<br />
<br />
{{hc|# pvdisplay -v -m|<br />
Finding all volume groups.<br />
Using physical volume(s) on command line.<br />
--- Physical volume ---<br />
PV Name /dev/sdd1<br />
VG Name vg1<br />
PV Size 1.52 TiB / not usable 1.97 MiB<br />
Allocatable yes <br />
PE Size 4.00 MiB<br />
Total PE 399669<br />
Free PE 153600<br />
Allocated PE 246069<br />
PV UUID MR9J0X-zQB4-wi3k-EnaV-5ksf-hN1P-Jkm5mW<br />
<br />
--- Physical Segments ---<br />
Physical extent 0 to 153600:<br />
FREE<br />
Physical extent 153601 to 307199:<br />
Logical volume /dev/vg1/backup<br />
Logical extents 1 to 153599<br />
Physical extent 307200 to 307200:<br />
FREE<br />
Physical extent 307201 to 399668:<br />
Logical volume /dev/vg1/backup<br />
Logical extents 153601 to 246068<br />
}}<br />
<br />
One can observe FREE space are split across the volume. To shrink the physical volume, we must first move all used segments to the beginning.<br />
<br />
Here, the first free segment is from 0 to 153600 and leaves us with 153601 free extents. We can now move this segment number from the last physical extent to the first extent. The command will thus be:<br />
<br />
{{hc|# pvmove --alloc anywhere /dev/sdd1:307201-399668 /dev/sdd1:0-92466|<br />
/dev/sdd1: Moved: 0.1 %<br />
/dev/sdd1: Moved: 0.2 %<br />
...<br />
/dev/sdd1: Moved: 99.9 %<br />
/dev/sdd1: Moved: 100,0%<br />
}}<br />
<br />
{{Note|<br />
* this command moves 92468 PEs (399668-307200) '''from''' the last segment '''to''' the first segment. This is possible as the first segment encloses 153600 free PEs, which can contain the 92467 moved PEs.<br />
* the {{ic|--alloc anywhere}} option is used as we move PEs inside the same partition. In case of different partitions, the command would look something like this: {{bc|# pvmove /dev/sdb1:1000-1999 /dev/sdc1:0-999}}<br />
* this command may take a long time (one to two hours) in case of large volumes. It might be a good idea to run this command in a [[Tmux]] or [[GNU Screen]] session. Any unwanted stop of the process could be fatal.<br />
* once the operation is complete, run [[fsck]] to make sure your file system is valid.<br />
}}<br />
<br />
====== Resize physical volume ======<br />
<br />
Once all your free physical segments are on the last physical extent, run {{ic|vgdisplay}} and see your free PE.<br />
<br />
Then you can now run again the command:<br />
<br />
# pvresize --setphysicalvolumesize ''size'' ''PhysicalVolume''<br />
<br />
See the result:<br />
<br />
{{hc|# pvs|<br />
PV VG Fmt Attr PSize PFree <br />
/dev/sdd1 vg1 lvm2 a-- 1t 500g<br />
}}<br />
<br />
====== Resize partition ======<br />
<br />
Last, you need to shrink the partition with your favorite [[Partitioning#Partitioning tools|partitioning tool]].<br />
<br />
==== Logical volumes ====<br />
<br />
{{Note|{{man|8|lvresize}} provides more or less the same options as the specialized {{man|8|lvextend}} and {{man|8|lvreduce}} commands, while allowing to do both types of operation. Notwithstanding this, all those utilities offer a {{ic|-r}}/{{ic|--resizefs}} option which allows to resize the file system together with the LV using {{man|8|fsadm}} (''ext2'', [[ext3]], [[ext4]], ''ReiserFS'' and [[XFS]] supported). Therefore it may be easier to simply use {{ic|lvresize}} for both operations and use {{ic|--resizefs}} to simplify things a bit, except if you have specific needs or want full control over the process.}}<br />
<br />
{{Warning|While enlarging a file system can often be done on-line (''i.e.'' while it is mounted), even for the root partition, shrinking will nearly always require to first unmount the file system so as to prevent data loss. Make sure your FS supports what you are trying to do.}}<br />
<br />
===== Resizing the logical volume and file system in one go =====<br />
<br />
{{Note|Only ''ext2'', [[ext3]], [[ext4]], ''ReiserFS'' and [[XFS]] [[file systems]] are supported. For a different type of file system see [[#Resizing the logical volume and file system separately]].}}<br />
<br />
Extend the logical volume {{ic|mediavol}} in {{ic|MyVolGroup}} by 10 GiB and resize its file system ''all at once'':<br />
<br />
# lvresize -L +10G --resizefs MyVolGroup/mediavol<br />
<br />
Set the size of logical volume {{ic|mediavol}} in {{ic|MyVolGroup}} to 15 GiB and resize its file system ''all at once'':<br />
<br />
# lvresize -L 15G --resizefs MyVolGroup/mediavol<br />
<br />
If you want to fill all the free space on a volume group, use the following command:<br />
<br />
# lvresize -l +100%FREE --resizefs MyVolGroup/mediavol<br />
<br />
See {{man|8|lvresize}} for more detailed options.<br />
<br />
===== Resizing the logical volume and file system separately =====<br />
<br />
For file systems not supported by {{man|8|fsadm}} will need to use the [[File systems#Types of file systems|appropriate utility]] to resize the file system before shrinking the logical volume or after expanding it.<br />
<br />
To extend logical volume {{ic|mediavol}} within volume group {{ic|MyVolGroup}} by 2 GiB ''without'' touching its file system:<br />
<br />
# lvresize -L +2G MyVolGroup/mediavol<br />
<br />
Now expand the file system ([[ext4]] in this example) to the maximum size of the underlying logical volume:<br />
<br />
# resize2fs /dev/MyVolGroup/mediavol<br />
<br />
To reduce the size of logical volume {{ic|mediavol}} in {{ic|MyVolGroup}} by 500 MiB, first calculate the resulting file system size and shrink the file system ([[ext4]] in this example) to the new size:<br />
<br />
# resize2fs /dev/MyVolGroup/mediavol ''NewSize''<br />
<br />
When the file system is shrunk, reduce the size of logical volume:<br />
<br />
# lvresize -L -500M MyVolGroup/mediavol<br />
<br />
See {{man|8|lvresize}} for more detailed options.<br />
<br />
=== Renaming volumes ===<br />
<br />
==== Renaming a Volume Group ====<br />
<br />
Use the {{man|8|vgrename}} command to rename an existing volume group.<br />
<br />
Either of the following commands renames the existing volume group {{ic|vg02}} to {{ic|my_volume_group}}<br />
<br />
# vgrename /dev/vg02 /dev/my_volume_group<br />
<br />
# vgrename vg02 my_volume_group<br />
<br />
==== Renaming Logical Volumes ====<br />
<br />
To rename an existing logical volume, use the {{man|8|lvrename}} command.<br />
<br />
Either of the following commands renames logical volume {{ic|lvold}} in volume group {{ic|vg02}} to {{ic|lvnew}}.<br />
<br />
# lvrename /dev/vg02/lvold /dev/vg02/lvnew<br />
<br />
# lvrename vg02 lvold lvnew<br />
<br />
=== Remove logical volume ===<br />
<br />
{{Warning|Before you remove a logical volume, make sure to move all data that you want to keep somewhere else; otherwise, it will be lost!}}<br />
<br />
First, find out the name of the logical volume you want to remove. You can get a list of all logical volumes with:<br />
<br />
# lvs<br />
<br />
Next, look up the mountpoint of the chosen logical volume:<br />
<br />
$ lsblk<br />
<br />
Then unmount the filesystem on the logical volume:<br />
<br />
# umount /<''mountpoint''><br />
<br />
Finally, remove the logical volume:<br />
<br />
# lvremove <''volume_group''>/<''logical_volume''><br />
<br />
For example:<br />
<br />
# lvremove VolGroup00/lvolhome<br />
<br />
Confirm by typing in {{ic|y}}.<br />
<br />
Update {{ic|/etc/fstab}} as necessary.<br />
<br />
You can verify the removal of the logical volume by typing {{ic|lvs}} as root again (see first step of this section).<br />
<br />
=== Add physical volume to a volume group ===<br />
<br />
You first create a new physical volume on the block device you wish to use, then extend your volume group<br />
<br />
# pvcreate /dev/sdb1<br />
# vgextend VolGroup00 /dev/sdb1<br />
<br />
This of course will increase the total number of physical extents on your volume group, which can be allocated by logical volumes as you see fit.<br />
<br />
{{Note|It is considered good form to have a [[Partitioning|partition table]] on your storage medium below LVM. Use the appropriate type code: {{ic|8e}} for MBR, and {{ic|8e00}} for GPT partitions.}}<br />
<br />
=== Remove partition from a volume group ===<br />
<br />
If you created a logical volume on the partition, [[#Remove logical volume|remove]] it first.<br />
<br />
All of the data on that partition needs to be moved to another partition. Fortunately, LVM makes this easy:<br />
<br />
# pvmove /dev/sdb1<br />
<br />
If you want to have the data on a specific physical volume, specify that as the second argument to {{ic|pvmove}}:<br />
<br />
# pvmove /dev/sdb1 /dev/sdf1<br />
<br />
Then the physical volume needs to be removed from the volume group:<br />
<br />
# vgreduce myVg /dev/sdb1<br />
<br />
Or remove all empty physical volumes:<br />
<br />
# vgreduce --all vg0<br />
<br />
And lastly, if you want to use the partition for something else, and want to avoid LVM thinking that the partition is a physical volume:<br />
<br />
# pvremove /dev/sdb1<br />
<br />
=== Deactivate volume group ===<br />
<br />
Just invoke <br />
<br />
# vgchange -a n my_volume_group<br />
<br />
This will deactivate the volume group and allow you to unmount the container it is stored in.<br />
<br />
== Logical volume types ==<br />
<br />
{{Expansion|Add instructions for thin-provisioned volume creation and RAID volume creation.|section=Logical volume types}}<br />
<br />
Besides simple logical volumes, LVM supports snapshots, logical volume caching, thin provisioned logical volumes and RAID.<br />
<br />
=== Snapshots ===<br />
<br />
LVM allows you to take a snapshot of your system in a much more efficient way than a traditional backup. It does this efficiently by using a COW (copy-on-write) policy. The initial snapshot you take simply contains hard-links to the inodes of your actual data. So long as your data remains unchanged, the snapshot merely contains its inode pointers and not the data itself. Whenever you modify a file or directory that the snapshot points to, LVM automatically clones the data, the old copy referenced by the snapshot, and the new copy referenced by your active system. Thus, you can snapshot a system with 35 GiB of data using just 2 GiB of free space so long as you modify less than 2 GiB (on both the original and snapshot). In order to be able to create snapshots you need to have unallocated space in your volume group. Snapshot like any other volume will take up space in the volume group. So, if you plan to use snapshots for backing up your root partition do not allocate 100% of your volume group for root logical volume.<br />
<br />
==== Configuration ====<br />
<br />
You create snapshot logical volumes just like normal ones.<br />
<br />
# lvcreate --size 100M --snapshot --name snap01 /dev/vg0/lv<br />
<br />
With that volume, you may modify less than 100 MiB of data, before the snapshot volume fills up.<br />
<br />
Reverting the modified 'lv' logical volume to the state when the 'snap01' snapshot was taken can be done with<br />
<br />
# lvconvert --merge /dev/vg0/snap01<br />
<br />
In case the origin logical volume is active, merging will occur on the next reboot (merging can be done even from a LiveCD). <br />
<br />
{{Note|The snapshot will no longer exist after merging.}}<br />
<br />
Also multiple snapshots can be taken and each one can be merged with the origin logical volume at will.<br />
<br />
The snapshot can be mounted and backed up with '''dd''' or '''tar'''. The size of the backup file done with '''dd''' will be the size of the files residing on the snapshot volume. <br />
To restore just create a snapshot, mount it, and write or extract the backup to it. And then merge it with the origin.<br />
<br />
{{Expansion|scripts to automate snapshots of root before updates, to rollback... updating {{ic|menu.lst}} to boot snapshots (separate article?)}}<br />
<br />
Snapshots are primarily used to provide a frozen copy of a file system to make backups; a backup taking two hours provides a more consistent image of the file system than directly backing up the partition.<br />
<br />
See [[Create root filesystem snapshots with LVM]] for automating the creation of clean root file system snapshots during system startup for backup and rollback.<br />
<br />
[[dm-crypt/Encrypting an entire system#LVM on LUKS]] and [[dm-crypt/Encrypting an entire system#LUKS on LVM]].<br />
<br />
If you have LVM volumes not activated via the [[initramfs]], [[enable]] {{ic|lvm-monitoring.service}}, which is provided by the {{pkg|lvm2}} package.<br />
<br />
=== LVM cache ===<br />
<br />
From {{man|7|lvmcache}}:<br />
<br />
: The cache logical volume type uses a small and fast LV to improve the performance of a large and slow LV. It does this by storing the frequently used blocks on the faster LV. LVM refers to the small fast LV as a cache pool LV. The large slow LV is called the origin LV. Due to requirements from dm-cache (the kernel driver), LVM further splits the cache pool LV into two devices - the cache data LV and cache metadata LV. The cache data LV is where copies of data blocks are kept from the origin LV to increase speed. The cache metadata LV holds the accounting information that specifies where data blocks are stored (e.g. on the origin LV or on the cache data LV). Users should be familiar with these LVs if they wish to create the best and most robust cached logical volumes. All of these associated LVs must be in the same VG.<br />
<br />
==== Create cache ====<br />
<br />
The fast method is creating a PV (if necessary) on the fast disk and add it to the existing volume group:<br />
<br />
# vgextend dataVG /dev/sdx<br />
<br />
Create a cache pool with automatic meta data on sdb, and convert the existing logical volume (dataLV) to a cached volume, all in one step:<br />
<br />
# lvcreate --type cache --cachemode writethrough -L 20G -n dataLV_cachepool dataVG/dataLV /dev/sdx<br />
<br />
Obviously, if you want your cache to be bigger, you can change the {{ic|-L}} parameter to a different size.<br />
<br />
{{Note|Cachemode has two possible options:<br />
* {{ic|writethrough}} ensures that any data written will be stored both in the cache pool LV and on the origin LV. The loss of a device associated with the cache pool LV in this case would not mean the loss of any data;<br />
* {{ic|writeback}} ensures better performance, but at the cost of a higher risk of data loss in case the drive used for cache fails.<br />
<br />
If a specific {{ic|--cachemode}} is not indicated, the system will assume {{ic|writethrough}} as default.<br />
}}<br />
<br />
==== Remove cache ====<br />
<br />
If you ever need to undo the one step creation operation above:<br />
<br />
# lvconvert --uncache dataVG/dataLV<br />
<br />
This commits any pending writes still in the cache back to the origin LV, then deletes the cache. Other options are available and described in {{man|7|lvmcache}}.<br />
<br />
=== RAID ===<br />
<br />
From {{man|7|lvmraid}}:<br />
: {{man|8|lvm}} RAID is a way to create a Logical Volume (LV) that uses multiple physical devices to improve performance or tolerate device failures. In LVM, the physical devices are Physical Volumes (PVs) in a single Volume Group (VG).<br />
<br />
LVM RAID supports RAID 0, RAID 1, RAID 4, RAID 5, RAID 6 and RAID 10. See [[Wikipedia:Standard RAID levels]] for details on each level.<br />
<br />
==== Setup RAID ====<br />
<br />
Create physical volumes:<br />
<br />
# pvcreate /dev/sda2 /dev/sdb2<br />
<br />
Create volume group on the physical volumes:<br />
<br />
# vgcreate VolGroup00 /dev/sda2 /dev/sdb2<br />
<br />
Create logical volumes useing {{ic|lvcreate --type ''raidlevel''}}, see {{man|7|lvmraid}} and {{man|8|lvcreate}} for more options.<br />
<br />
# lvcreate --type RaidLevel [OPTIONS] -n Name -L Size VG [PVs]<br />
<br />
For example:<br />
<br />
# lvcreate --type raid1 --mirrors 1 -L 20G -n myraid1vol VolGroup00 /dev/sda2 /dev/sdb2<br />
<br />
will create a 20 GiB mirrored logical volume named "myraid1vol" in VolGroup00 on {{ic|/dev/sda2}} and {{ic|/dev/sdb2}}.<br />
<br />
==== Configure mkinitcpio for RAID ====<br />
<br />
If your root filesystem is on LVM RAID additionally to {{ic|lvm2}} or {{ic|sd-lvm2}} hooks, you need to add {{ic|dm-raid}} and the appropriate RAID modules (e.g. {{ic|raid0}}, {{ic|raid1}}, {{ic|raid10}} and/or {{ic|raid456}}) to the MODULES array in {{ic|mkinitcpio.conf}}.<br />
<br />
For busybox based initramfs:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=('''dm-raid raid0 raid1 raid10 raid456''')<br />
HOOKS=(base '''udev''' ... block '''lvm2''' filesystems)<br />
}}<br />
<br />
For systemd based initramfs:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=('''dm-raid raid0 raid1 raid10 raid456''')<br />
HOOKS=(base '''systemd''' ... block '''sd-lvm2''' filesystems)<br />
}}<br />
<br />
== Graphical configuration ==<br />
<br />
There is no "official" GUI tool for managing LVM volumes, but {{AUR|system-config-lvm}} covers most of the common operations, and provides simple visualizations of volume state. It can automatically resize many file systems when resizing logical volumes.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Boot/Shutdown-problems because of disabled lvmetad ===<br />
<br />
The {{ic|1=use_lvmetad = 1}} '''must''' be set in {{ic|/etc/lvm/lvm.conf}}. This is the default now - if you have a {{ic|lvm.conf.pacnew}} file, you must merge this change.<br />
<br />
=== LVM commands do not work ===<br />
<br />
* Load proper module:<br />
<br />
# modprobe dm_mod<br />
<br />
The {{ic|dm_mod}} module should be automatically loaded. In case it does not, you can try:<br />
{{Accuracy|Should module loading at boot be done using "/etc/modules-load.d" instead?}}<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
MODULES=(dm_mod ...)<br />
}}<br />
<br />
You will need to [[regenerate the initramfs]] to commit any changes you made.<br />
<br />
* Try preceding commands with ''lvm'' like this:<br />
<br />
# lvm pvdisplay<br />
<br />
=== Logical Volumes do not show up ===<br />
<br />
If you are trying to mount existing logical volumes, but they do not show up in {{ic|lvscan}}, you can use the following commands to activate them:<br />
<br />
# vgscan<br />
# vgchange -ay<br />
<br />
=== LVM on removable media ===<br />
<br />
Symptoms:<br />
{{hc|# vgscan|<br />
Reading all physical volumes. This may take a while...<br />
/dev/backupdrive1/backup: read failed after 0 of 4096 at 319836585984: Input/output error<br />
/dev/backupdrive1/backup: read failed after 0 of 4096 at 319836643328: Input/output error<br />
/dev/backupdrive1/backup: read failed after 0 of 4096 at 0: Input/output error<br />
/dev/backupdrive1/backup: read failed after 0 of 4096 at 4096: Input/output error<br />
Found volume group "backupdrive1" using metadata type lvm2<br />
Found volume group "networkdrive" using metadata type lvm2<br />
}}<br />
<br />
Cause:<br />
:Removing an external LVM drive without deactivating the volume group(s) first. Before you disconnect, make sure to:<br />
<br />
# vgchange -an ''volume group name''<br />
<br />
Fix: assuming you already tried to activate the volume group with {{ic|vgchange -ay ''vg''}}, and are receiving the Input/output errors:<br />
<br />
# vgchange -an ''volume group name''<br />
<br />
Unplug the external drive and wait a few minutes:<br />
<br />
# vgscan<br />
# vgchange -ay ''volume group name''<br />
<br />
=== Resizing a contiguous logical volume fails ===<br />
<br />
If trying to extend a logical volume errors with:<br />
<br />
" Insufficient suitable contiguous allocatable extents for logical volume "<br />
<br />
The reason is that the logical volume was created with an explicit contiguous allocation policy (options {{ic|-C y}} or {{ic|--alloc contiguous}}) and no further adjacent contiguous extents are available (see also [http://www.hostatic.ro/2010/02/15/lvm-inherit-and-contiguous-policies/ reference]).<br />
<br />
To fix this, prior to extending the logical volume, change its allocation policy with {{ic|lvchange --alloc inherit <logical_volume>}}. If you need to keep the contiguous allocation policy, an alternative approach is to move the volume to a disk area with sufficient free extents (see [http://superuser.com/questions/435075/how-to-align-logical-volumes-on-contiguous-physical-extents]).<br />
<br />
=== Command "grub-mkconfig" reports "unknown filesystem" errors ===<br />
<br />
Make sure to remove snapshot volumes before [[GRUB#Generate the main configuration file|generating grub.cfg]].<br />
<br />
=== Thinly-provisioned root volume device times out ===<br />
<br />
With a large number of snapshots, {{ic|thin_check}} runs for a long enough time so that waiting for the root device times out. To compensate, add the {{ic|1=rootdelay=60}} kernel boot parameter to your boot loader configuration.<br />
<br />
=== Delay on shutdown ===<br />
<br />
If you use RAID, snapshots or thin provisioning and experience a delay on shutdown, make sure {{ic|lvm2-monitor.service}} is [[started]]. See {{Bug|50420}}.<br />
<br />
== See also ==<br />
<br />
* [http://sourceware.org/lvm2/ LVM2 Resource Page] on SourceWare.org<br />
* [http://wiki.gentoo.org/wiki/LVM LVM] article at Gentoo wiki<br />
* [http://www.tutonics.com/2012/11/ubuntu-lvm-guide-part-1.html Ubuntu LVM Guide Part 1][http://www.tutonics.com/2012/12/lvm-guide-part-2-snapshots.html Part 2 detals snapshots]<br />
* [https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Logical_Volume_Manager_Administration/index.html Red Hat: Logical Volume Manager Administration]</div>Medicineman25https://wiki.archlinux.org/index.php?title=Makepkg&diff=471335Makepkg2017-03-20T07:15:53Z<p>Medicineman25: included quick reference link to makepkg; importing keys to specific package</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package development]]<br />
[[Category:About Arch]]<br />
[[ar:Makepkg]]<br />
[[el:Makepkg]]<br />
[[es:Makepkg]]<br />
[[fa:Makepkg]]<br />
[[fr:makepkg]]<br />
[[it:Makepkg]]<br />
[[ja:Makepkg]]<br />
[[nl:Makepkg]]<br />
[[pt:Makepkg]]<br />
[[ru:Makepkg]]<br />
[[sr:Makepkg]]<br />
[[tr:Makepkg]]<br />
[[zh-hans:Makepkg]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Arch User Repository}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
[https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg] is a script to automate the building of packages. The requirements for using the script are a build-capable Unix platform and a [[PKGBUILD]].<br />
<br />
''makepkg'' is provided by the {{Pkg|pacman}} package.<br />
<br />
== Configuration ==<br />
<br />
See {{ic|man makepkg.conf}} for details on configuration options for makepkg.<br />
<br />
The system configuration is available in {{ic|/etc/makepkg.conf}}, but user-specific changes can be made in {{ic|$XDG_CONFIG_HOME/pacman/makepkg.conf}} or {{ic|~/.makepkg.conf}}. It is recommended to review the configuration prior to building packages.<br />
<br />
=== Packager information ===<br />
<br />
Each package is tagged with metadata identifying amongst others also the ''packager''. By default, user-compiled packages are marked with {{ic|Unknown Packager}}. If multiple users will be compiling packages on a system, or you are otherwise distributing your packages to other users, it is convenient to provide real contact. This can be done by setting the {{ic|PACKAGER}} variable in {{ic|makepkg.conf}}.<br />
<br />
To check this on an installed package:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : John Doe <john@doe.com><br />
[...]<br />
</nowiki>}}<br />
<br />
To automatically produce signed packages, also set the {{ic|GPGKEY}} variable in {{ic|makepkg.conf}}.<br />
<br />
=== Package output ===<br />
<br />
By default, ''makepkg'' creates the package tarballs in the working directory and downloads source data directly to the {{ic|src/}} directory. Custom paths can be configured, for example to keep all built packages in {{ic|~/build/packages/}} and all sources in {{ic|~/build/sources/}}.<br />
<br />
Configure the following {{ic|makepkg.conf}} variables if needed:<br />
<br />
* {{ic|PKGDEST}} &mdash; directory for storing resulting packages<br />
* {{ic|SRCDEST}} &mdash; directory for storing [[PKGBUILD#source|source]] data (symbolic links will be placed to {{ic|src/}} if it points elsewhere)<br />
* {{ic|SRCPKGDEST}} &mdash; directory for storing resulting source packages (built with {{ic|makepkg -S}})<br />
<br />
=== Signature checking ===<br />
<br />
If a signature file in the form of {{ic|.sig}} or {{ic|.asc}} is part of the [[PKGBUILD]] source array, ''makepkg'' automatically attempts to [[GnuPG#Verify a signature|verify]] it. In case the user's keyring does not contain the needed public key for signature verification, ''makepkg'' will abort the installation with a message that the PGP key could not be verified. <br />
<br />
If a needed public key is missing, or if you want to add public keys by other developers, you can [[GnuPG#Import_a_public_key|import]] it manually, or you can find it [[GnuPG#Use_a_keyserver|on a keyserver]] and import it from there. <br />
<br />
{{Note| The [[PKGBUILD]] will most likely, contain a [[PKGBUILD#validpgpkeys|validpgpkeys]] entry with the required key IDs.}}<br />
<br />
{{Note|The signature checking implemented in ''makepkg'' does not use pacman's keyring, instead relying on the user's keyring. [http://allanmcrae.com/2015/01/two-pgp-keyrings-for-package-management-in-arch-linux/] For quick reference, see: [https://wiki.archlinux.org/index.php/GnuPG#Import_keys_for_a_specific_package/]}}<br />
<br />
== Usage ==<br />
Before continuing, [[install]] the {{Grp|base-devel}} group. Packages belonging to this group are '''not''' required to be listed as build-time dependencies (''makedepends'') in [[PKGBUILD]] files. In addition, the {{Grp|base}} group is assumed to be installed on '''all''' Arch systems.<br />
<br />
{{Note|<br />
* Make sure [[sudo]] is configured properly for commands passed to [[pacman]].<br />
* Running ''makepkg'' itself as root is [https://lists.archlinux.org/pipermail/pacman-dev/2014-March/018911.html disallowed].[https://projects.archlinux.org/pacman.git/tree/NEWS] Besides how a {{ic|PKGBUILD}} may contain arbitrary commands, building as root is generally considered unsafe.[https://bbs.archlinux.org/viewtopic.php?id&#61;67561] Users who have no access to a regular user account should run makepkg as the [http://allanmcrae.com/2015/01/replacing-makepkg-asroot/ nobody user].<br />
}}<br />
<br />
To build a package, one must first create a [[PKGBUILD]], or build script, as described in [[Creating packages]]. Existing scripts are available from the [[Arch Build System|ABS tree]] or the [[AUR]]. Once in possession of a {{ic|PKGBUILD}}, change to the directory where it is saved and issue the following command to build the package described by said {{ic|PKGBUILD}}:<br />
<br />
$ makepkg<br />
<br />
If required dependencies are missing, ''makepkg'' will issue a warning before failing. To build the package and install needed dependencies, add the flag {{ic|-s}}/{{ic|--syncdeps}}:<br />
<br />
$ makepkg -s<br />
<br />
Adding the {{ic|-r}}/{{ic|--rmdeps}} flag causes ''makepkg'' to remove the make dependencies later, which are no longer needed. If constantly building packages, consider using [[Pacman/Tips and tricks#Removing unused packages (orphans)]] once in a while instead.<br />
<br />
{{Note|<br />
* These dependencies must be available in the configured repositories; see [[pacman#Repositories and mirrors]] for details. Alternatively, one can manually install dependencies prior to building ({{ic|pacman -S --asdeps ''dep1'' ''dep2''}}).<br />
* Only global values are used when installing dependencies, i.e any override done in a split package's packaging function will not be used. [https://patchwork.archlinux.org/patch/2271/]}}<br />
<br />
Once all dependencies are satisfied and the package builds successfully, a package file ({{ic|''pkgname''-''pkgver''.pkg.tar.xz}}) will be created in the working directory. To install, use {{ic|-i}}/{{ic|--install}} (same as {{ic|pacman -U ''pkgname''-''pkgver''.pkg.tar.xz}}):<br />
<br />
$ makepkg -i<br />
<br />
To clean up leftover files and folders, such as files extracted to the {{ic|$srcdir}}, add the option {{ic|-c}}/{{ic|--clean}}. This is useful for multiple builds of the same package or updating the package version, while using the same build folder. It prevents obsolete and remnant files from carrying over to the new builds:<br />
<br />
$ makepkg -c<br />
<br />
For more, see [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Creating optimized packages ===<br />
<br />
A performance improvement of the packaged software can be achieved by enabling compiler optimizations for the host machine. The downside is that packages compiled for a specific processor architecture will not run correctly on other machines. On x86_64 machines, there are rarely significant enough real world performance gains that would warrant investing the time to rebuild official packages.<br />
<br />
However, it is very easy to reduce performance by using "nonstandard" compiler flags. Many compiler optimizations are only useful in certain situations and should not be indiscriminately applied to every package. Unless you can verify/benchmark that something is faster, there is a very good chance it is not! The Gentoo [http://www.gentoo.org/doc/en/gcc-optimization.xml Compilation Optimization Guide] and [http://wiki.gentoo.org/wiki/Safe_CFLAGS Safe CFLAGS] wiki article provide more in-depth information about compiler optimization.<br />
<br />
The options passed to a C/C++ compiler (e.g. {{Pkg|gcc}} or {{Pkg|clang}}) are controlled by the {{ic|CFLAGS}}, {{ic|CXXFLAGS}}, and {{ic|CPPFLAGS}} environment variables. Similarly, the {{Pkg|make}} build system uses {{ic|MAKEFLAGS}}. For use in the Arch build system, ''makepkg'' exposes these environment variables as configuration options in {{ic|makepkg.conf}}. The default values are configured to produce generic packages that can be installed on a wide range of machines.<br />
<br />
{{Note|Keep in mind that not all build systems use the variables configured in {{ic|makepkg.conf}}. For example, ''cmake'' disregards the preprocessor options environment variable, {{ic|CPPFLAGS}}. Consequently, many [[PKGBUILD]]s contain workarounds with options specific to the build system used by the packaged software.}}<br />
<br />
GCC can automatically detect and enable safe architecture-specific optimizations. To use this feature, first remove any {{ic|-march}} and {{ic|-mtune}} flags, then add {{ic|1=-march=native}}. For example,<br />
<br />
CFLAGS="-march=native -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
<br />
To see what flags this enables on your machine, run:<br />
<br />
$ gcc -march=native -v -Q --help=target<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you specify different value than {{ic|1=-march=native}}, then {{ic|1=-Q --help=target}} '''will not''' work as expected.[https://bbs.archlinux.org/viewtopic.php?pid=1616694#p1616694] You need to go through a compilation phase to find out which options are really enabled. See [https://wiki.gentoo.org/wiki/Safe_CFLAGS#Find_CPU-specific_options Find CPU-specific options] on Gentoo wiki for instructions.<br />
* To find out the optimal options for a '''32 bit''' x86 architecture, you can use the script [https://github.com/pixelb/scripts/blob/master/scripts/gcccpuopt gcccpuopt].<br />
}}<br />
<br />
==== MAKEFLAGS ====<br />
<br />
The {{ic|MAKEFLAGS}} option can be used to specify additional options for make. Users with multi-core/multi-processor systems can specify the number of jobs to run simultaneously. This can be accomplished with the use of ''nproc'' to determine the number of available processors, e.g. {{ic|1=MAKEFLAGS="-j$(nproc)"}}. Some [[PKGBUILD]]s specifically override this with {{ic|-j1}}, because of race conditions in certain versions or simply because it is not supported in the first place. Packages that fail to build because of this should be [[Reporting bug guidelines|reported]] on the bug tracker (or in the case of [[AUR]] packages, to the package maintainer) after making sure that the error is indeed being caused by your {{ic|MAKEFLAGS}}.<br />
<br />
See {{ic|man make}} for a complete list of available options.<br />
<br />
=== Improving compile times ===<br />
<br />
==== tmpfs ====<br />
<br />
As compiling requires many I/O operations and handling of small files, moving the working directory to a [[tmpfs]] may bring improvements in build times. <br />
<br />
The {{ic|BUILDDIR}} variable can be temporarily exported to ''makepkg'' to set the build directory to an existing tmpfs. For example:<br />
<br />
$ BUILDDIR=/tmp/makepkg makepkg<br />
<br />
{{Warning|Avoid compiling larger packages in tmpfs to prevent running out of memory.}}<br />
<br />
Persistent configuration can be done in {{ic|makepkg.conf}} by uncommenting the {{ic|BUILDDIR}} option, which is found at the end of the {{ic|BUILD ENVIRONMENT}} section in the default {{ic|/etc/makepkg.conf}} file. Setting its value to e.g. {{ic|1=BUILDDIR=/tmp/makepkg}} will make use of the Arch's default {{ic|/tmp}} [[tmpfs]].<br />
<br />
{{Note|<br />
* The [[tmpfs]] folder must be mounted without the {{ic|noexec}} option, else it will prevent build scripts or utilities from being executed.<br />
* Keep in mind that any package compiled in [[tmpfs]] will not persist across reboot. Consider setting the [[#Package output|PKGDEST]] option appropriately to move the built package automatically to another (persistent) directory.<br />
}}<br />
<br />
==== ccache ====<br />
<br />
The use of [[ccache]] can improve build times by caching the results of compilations.<br />
<br />
=== Generate new checksums ===<br />
Since [http://allanmcrae.com/2013/04/pacman-4-1-released/ pacman 4.1], {{ic|makepkg -g >> PKGBUILD}} is no longer required because pacman-contrib was [https://projects.archlinux.org/pacman.git/tree/NEWS merged into upstream pacman], including the {{ic|updpkgsums}} script that will generate new checksums and/or replace them in the PKGBUILD. In the same directory as the PKGBUILD file, run the following command:<br />
$ updpkgsums<br />
<br />
=== Create uncompressed packages ===<br />
If you do not mind having larger package files, you can speed up both packaging and installation by having makepkg produce uncompressed packages. Set {{ic|1=PKGEXT='.pkg.tar'}} in {{ic|/etc/makepkg.conf}}.<br />
<br />
=== Utilizing multiple cores on compression ===<br />
{{pkg|xz}} supports [[Wikipedia:Symmetric multiprocessing|symmetric multiprocessing (SMP)]] via the {{ic|--threads}} flag to speed up compression. For example, to let makepkg use as many CPU cores as possible to compress packages, edit {{ic|COMPRESSXZ}} array in {{ic|/etc/makepkg.conf}}:<br />
<br />
COMPRESSXZ=(xz -c -z - '''--threads=0''')<br />
<br />
=== Build 32-bit packages on a 64-bit system ===<br />
{{Warning|Errors have been reported when using this method to build the {{Pkg|linux}} package. The [[Install bundled 32-bit system in 64-bit system|chroot method]] is preferred and has been verified to work for building the kernel packages.}}<br />
<br />
First, enable the [[multilib]] repository and [[install]] {{Grp|multilib-devel}}. Reply yes when asked about removing the conflicting {{ic|gcc}} and {{ic|gcc-libs}} packages; gcc-multilib is capable of building both 64-bit and 32-bit software.<br />
<br />
Then create a 32-bit configuration file<br />
<br />
{{hc|~/.makepkg.i686.conf|<nowiki><br />
CARCH="i686"<br />
CHOST="i686-unknown-linux-gnu"<br />
CFLAGS="-m32 -march=i686 -mtune=generic -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
LDFLAGS="-m32 -Wl,-O1,--sort-common,--as-needed,-z,relro"</nowiki>}}<br />
<br />
and invoke makepkg as such<br />
$ linux32 makepkg --config ~/.makepkg.i686.conf<br />
<br />
== Troubleshooting ==<br />
<br />
=== Makepkg sometimes fails to sign a package without asking for signature passphrase ===<br />
<br />
{{Style|Vague instructions}}<br />
<br />
With [https://www.gnupg.org/faq/whats-new-in-2.1.html gnupg 2.1], gpg-agent no longer has to be started manually and will be started automatically on the first invokation of gpg. Thus if you do not manually start gpg-agent, makepkg will start it. The problem is that makepkg runs gpg inside a fakeroot, so gpg-agent is also started in that same environment. This leads to bad behavior. A possible solution is to manually start the gpg-agent, either on boot or by command (see [[GnuPG#gpg-agent]] for ways to do this), before you run makepkg, but this also can be unreliable: {{Bug|49946}}.<br />
<br />
In the meantime if you do not wish to experiment with your gpg-agent configuration, simply use makepkg ''without'' signing, and sign the packages afterwards with {{ic|gpg --detach-sign ''name''.pkg.tar.xz}}.<br />
<br />
=== CFLAGS/CXXFLAGS/CPPFLAGS in makepkg.conf do not work for QMAKE based packages ===<br />
Qmake automatically sets the variable {{ic|CFLAGS}} and {{ic|CXXFLAGS}} according to what it thinks should be the right configuration. In order to let qmake use the variables defined in the makepkg configuration file, you must edit the PKGBUILD and pass the variables [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cflags-release QMAKE_CFLAGS_RELEASE] and [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cxxflags-release QMAKE_CXXFLAGS_RELEASE] to qmake. For example:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
build() {<br />
cd "$srcdir/$_pkgname-$pkgver-src"<br />
qmake-qt4 "$srcdir/$_pkgname-$pkgver-src/$_pkgname.pro" \<br />
PREFIX=/usr \<br />
QMAKE_CFLAGS_RELEASE="${CFLAGS}"\<br />
QMAKE_CXXFLAGS_RELEASE="${CXXFLAGS}"<br />
<br />
make<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, for a system wide configuration, you can create your own {{ic|qmake.conf}} and set the [http://doc.qt.io/qt-5/qmake-environment-reference.html#qmakespec QMAKESPEC] environment variable.<br />
<br />
=== Specifying install directory for QMAKE based packages ===<br />
The makefile generated by qmake uses the environment variable INSTALL_ROOT to specify where the program should be installed. Thus this package function should work:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
package() {<br />
cd "$srcdir/${pkgname%-git}"<br />
make INSTALL_ROOT="$pkgdir" install<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Note, that qmake also has to be configured appropriately. For example put this in your .pro file:<br />
<br />
{{hc|YourProject.pro|<nowiki><br />
...<br />
<br />
target.path = /usr/local/bin<br />
INSTALLS += target<br />
<br />
...<br />
</nowiki>}}<br />
<br />
=== WARNING: Package contains reference to $srcdir ===<br />
<br />
Somehow, the literal strings {{ic|$srcdir}} or {{ic|$pkgdir}} ended up in one of the installed files in your package.<br />
<br />
To identify which files, run the following from the ''makepkg'' build directory:<br />
$ grep -R "$(pwd)/src" pkg/<br />
<br />
[http://www.mail-archive.com/arch-general@archlinux.org/msg15561.html Link] to discussion thread.<br />
<br />
== See also ==<br />
<br />
* [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8) Manual Page]<br />
* [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5) Manual Page]<br />
* [https://gist.github.com/Earnestly/bebad057f40a662b5cc3 A Brief Tour of the Makepkg Process]<br />
* [https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg source code]</div>Medicineman25https://wiki.archlinux.org/index.php?title=Pacman/Package_signing&diff=471334Pacman/Package signing2017-03-20T07:13:02Z<p>Medicineman25: typo from previous edit</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Package signing]]<br />
[[fr:pacman-key]]<br />
[[it:Pacman/Package signing]]<br />
[[ja:Pacman-key]]<br />
[[ru:Pacman/Package signing]]<br />
[[tr:pacman paket imzaları]]<br />
[[zh-hans:Pacman/Package signing]]<br />
{{Related articles start}}<br />
{{Related|GnuPG}}<br />
{{Related|DeveloperWiki:Package signing}}<br />
{{Related articles end}}<br />
To determine if packages are authentic, ''pacman'' uses [http://www.gnupg.org/ GnuPG keys] in a [http://www.gnupg.org/gph/en/manual.html#AEN385 web of trust] model. There are currently five [https://www.archlinux.org/master-keys/ Master Signing Keys]. At least three of these Master Signing Keys are used to sign each of the Developer's and Trusted User's own keys which then in turn are used to sign their packages. The user also has a unique PGP key which is generated when you set up ''pacman-key''. So the web of trust links the user's key to the five Master Keys.<br />
<br />
Examples of webs of trust:<br />
<br />
* '''Custom packages''': You made the package yourself and signed it with your own key.<br />
* '''Unofficial packages''': A developer made the package and signed it. You used your key to sign that developer's key.<br />
* '''Official packages''': A developer made the package and signed it. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.<br />
<br />
{{Note|The HKP protocol uses 11371/tcp for communication. In order to get the signed keys from the servers (using ''pacman-key''), this port is required for communication.}}<br />
<br />
== Setup ==<br />
<br />
=== Configuring pacman ===<br />
<br />
The {{ic|SigLevel}} option in {{ic|/etc/pacman.conf}} determines how much trust is required to install a package. For a detailed explanation of {{ic|SigLevel}} see the [https://www.archlinux.org/pacman/pacman.conf.5.html#_package_and_database_signature_checking pacman.conf man page] and the comments in the file itself. Signature checking may be set globally or per repository. If {{ic|SigLevel}} is set globally in the {{ic|[options]}} section to require all packages to be signed, then packages you build will also need to be signed using ''makepkg''.<br />
<br />
{{Note|Although all official packages are now signed, as of June 2012 signing of the databases is a work in progress. If {{ic|Required}} is set then {{ic|DatabaseOptional}} should also be set.}}<br />
<br />
A default configuration can be used to only install packages that are signed by trusted keys:<br />
<br />
{{hc|1=/etc/pacman.conf|<br />
output=SigLevel = Required DatabaseOptional<br />
}}<br />
<br />
This is because {{ic|TrustedOnly}} is a default compiled-in ''pacman'' parameter. So above leads to the same result as a global option of:<br />
<br />
SigLevel = Required DatabaseOptional TrustedOnly<br />
<br />
The above can be achieved too on a repository level further below in the configuration, e.g.:<br />
<br />
[core]<br />
SigLevel = PackageRequired<br />
Include = /etc/pacman.d/mirrorlist<br />
<br />
explicitly adds signature checking for the packages of the repository, but does not require the database to be signed. {{ic|Optional}} here would turn off a global {{ic|Required}} for this repository<br />
<br />
{{warning|The SigLevel {{ic|TrustAll}} option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use {{ic|TrustedOnly}} for all official repositories.}}<br />
<br />
=== Initializing the keyring ===<br />
<br />
To set up the ''pacman'' keyring use:<br />
<br />
# pacman-key --init<br />
<br />
For this initialization, [[Wikipedia:Entropy_(computing)|entropy]] is required. Moving your mouse around, pressing random characters at the keyboard or running some disk-based activity (for example in another console running {{ic|ls -R /}} or {{ic|find / -name foo}} or {{ic|1=dd if=/dev/sda8 of=/dev/tty7}}) should generate entropy. If your system does not already have sufficient entropy, this step may take hours; if you actively generate entropy, it will complete much more quickly.<br />
<br />
The randomness created is used to set up a keyring ({{ic|/etc/pacman.d/gnupg}}) and the GPG signing key of your system.<br />
<br />
{{Note|If you need to run {{ic|pacman-key --init}} on computer that does not generate much entropy (e.g. a headless server), key generation may take a very long time. To generate pseudo-entropy, install either [[haveged]] or [[rng-tools]] on the target machine and start the corresponding service before running {{ic|pacman-key --init}}.}}<br />
<br />
== Managing the keyring ==<br />
<br />
=== Verifying the five master keys ===<br />
<br />
The initial setup of keys is achieved using:<br />
# pacman-key --populate archlinux<br />
Take time to verify the [https://www.archlinux.org/master-keys/ Master Signing Keys] when prompted as these are used to co-sign (and therefore trust) all other packager's keys.<br />
<br />
PGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the '(short) key ID' (the last ''sixteen'' digits of the fingerprint would be the 'long key ID').<br />
<br />
=== Adding developer keys ===<br />
<br />
The official developer and TU keys are signed by the master keys, so you do not need to use ''pacman-key'' to sign them yourself. Whenever ''pacman'' encounters a key it does not recognize, it will prompt to download it from a {{ic|keyserver}} configured in {{ic|/etc/pacman.d/gnupg/gpg.conf}} (or by using the {{ic|--keyserver}} option on the command line). Wikipedia maintains a [[wikipedia:Key server (cryptographic)|list of keyservers]].<br />
<br />
Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.<br />
<br />
{{Note|The {{Pkg|archlinux-keyring}} package, which is a dependency of {{Pkg|pacman}}, contains the latest keys. However keys can also be updated manually using {{ic|pacman-key --refresh-keys}} (as root). While doing {{ic|--refresh-keys}}, your local key will also be looked up on the remote keyserver, and you will receive a message about it being not found. This is nothing to be concerned about.}}<br />
<br />
=== Adding unofficial keys ===<br />
<br />
{{Note| For packages requiring a build process, it is recommended you add those types of unofficial keys to a user-keyring, because makepkg does not employ the pacman keyring. See [https://wiki.archlinux.org/index.php/Makepkg#Usage]}}<br />
<br />
You may wish to use this method, for example, to add your own key to the ''pacman'' keyring, or when enabling a signed [[Unofficial user repositories|unofficial repository]].If <br />
<br />
First get the key ID ({{ic|''keyid''}}) from the owner of the key. Then you need to add the key to the keyring:<br />
<br />
* If the key is found on a keyserver, import it with: {{bc|# pacman-key -r ''keyid''}}<br />
<br />
* If otherwise a link to a keyfile is provided, download it and then run: {{bc|# pacman-key --add ''/path/to/downloaded/keyfile''}}<br />
<br />
Always be sure to verify the fingerprint, as you would with a master key, or any other key which you are going to sign.<br />
$ pacman-key -f ''keyid''<br />
<br />
Finally, you need to locally sign the imported key:<br />
# pacman-key --lsign-key ''keyid''<br />
<br />
You now trust this key to sign packages.<br />
<br />
=== Debugging with gpg ===<br />
<br />
For debugging purposes, you can access ''pacman'''s keyring directly with ''gpg'', e.g.:<br />
<br />
# gpg --homedir /etc/pacman.d/gnupg --list-keys<br />
<br />
== Troubleshooting ==<br />
<br />
{{Style|Instructions could be clearer}}<br />
<br />
{{Warning|''pacman-key'' depends on [[time]]. If your system clock is wrong, you'll get:<br />
error: PackageName: signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
}}<br />
<br />
=== Cannot import keys ===<br />
<br />
There are multiple possible sources of this problem:<br />
<br />
* An outdated {{Pkg|archlinux-keyring}} package.<br />
* Incorrect date.<br />
* Your ISP blocked the port used to import PGP keys.<br />
* Your ''pacman'' cache contains copy of unsigned packages from previous attempts.<br />
* {{ic|dirmngr}} is not correctly configured<br />
<br />
You might be stuck because of outdated {{Pkg|archlinux-keyring}} package when doing an upgrade synchronization. Try if [[Pacman#Upgrading_packages|upgrading the system]] can fix it first.<br />
<br />
If you are still having issues, make sure the following file exists {{ic|/root/.gnupg/dirmngr_ldapservers.conf}} and that you can successfully run {{ic|# dirmngr}}. Create an empty file if it doesn't and run {{ic|# dirmngr}} again.<br />
<br />
If it does not help and your date is correct, you could try to switch to the MIT keyserver, which provides an alternate port. To do this, edit {{ic|/etc/pacman.d/gnupg/gpg.conf}} and change the {{ic|keyserver}} line to:<br />
<br />
keyserver hkp://pgp.mit.edu:11371<br />
<br />
If this does not help either, change the keyserver to the kjsl keyserver, which provides this service through port 80 (the HTTP port), which should always remain unblocked:<br />
<br />
keyserver hkp://keyserver.kjsl.com:80<br />
<br />
If you have IPv6 disabled, ''gpg'' will fail when it found some IPv6 address. In this case try with an IPv4-only keyserver like:<br />
<br />
keyserver hkp://ipv4.pool.sks-keyservers.net:11371<br />
<br />
If you happen to forget to run {{ic|pacman-key --populate archlinux}} you might get some errors while importing keys.<br />
<br />
If none of this helps, your ''pacman'' cache, located at {{ic|/var/cache/pacman/pkg/}} might contain unsigned packages from previous attempts. Try cleaning the cache manually or run:<br />
<br />
# pacman -Sc<br />
<br />
which removes all cached packages that have not been installed.<br />
<br />
=== Disabling signature checking ===<br />
<br />
{{Warning|Use with caution. Disabling package signing will allow ''pacman'' to install untrusted packages automatically.}}<br />
<br />
If you are not concerned about package signing, you can disable PGP signature checking completely. Edit {{ic|/etc/pacman.conf}} and uncomment the following line under {{ic|[options]}}:<br />
<br />
SigLevel = Never<br />
<br />
You need to comment out any repository-specific SigLevel settings too because they override the global settings. This will result in no signature checking, which was the behavior before pacman 4. If you decide to do this, you do not need to set up a keyring with ''pacman-key''. You can change this option later if you decide to enable package verification.<br />
<br />
=== Resetting all the keys ===<br />
<br />
If you want to remove or reset all the keys installed in your system, you can remove {{ic|/etc/pacman.d/gnupg}} folder as root and rerun {{ic|pacman-key --init}} and following that add the keys as preferred.<br />
<br />
=== Removing stale packages ===<br />
<br />
If the same packages keep failing and you are sure you did all the ''pacman-key'' stuff right, try removing them like so {{ic|rm /var/cache/pacman/pkg/''badpackage''*}} so that they are freshly downloaded.<br />
<br />
This might actually be the solution if you get a message like {{ic|error: linux: signature from "Some Person <Some.Person@example.com>" is invalid}} or similar when upgrading (i.e. you might not be the victim of a MITM attack after all, your downloaded file was simply corrupt).<br />
<br />
=== Updating keys via proxy ===<br />
<br />
In order to use a proxy when updating keys the {{ic|honor-http-proxy}} option must be set in both {{ic|/etc/gnupg/dirmngr.conf}} and {{ic|/etc/pacman.d/gnupg/dirmngr.conf}}. See [[GnuPG#Use a keyserver]] for more information.<br />
<br />
{{Note|If ''pacman-key'' is used without the {{ic|honor-http-proxy}} option and fails, a reboot may solve the issue.}}<br />
<br />
== See also ==<br />
<br />
* [[DeveloperWiki:Package Signing Proposal for Pacman]]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-1-makepkg-and-repo-add/ Pacman Package Signing – 1: Makepkg and Repo-add]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-2-pacman-key/ Pacman Package Signing – 2: Pacman-key]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-3-pacman/ Pacman Package Signing – 3: Pacman]<br />
* [http://allanmcrae.com/2011/12/pacman-package-signing-4-arch-linux/ Pacman Package Signing – 4: Arch Linux]</div>Medicineman25https://wiki.archlinux.org/index.php?title=Pacman/Package_signing&diff=471333Pacman/Package signing2017-03-20T07:12:09Z<p>Medicineman25: ty</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Package signing]]<br />
[[fr:pacman-key]]<br />
[[it:Pacman/Package signing]]<br />
[[ja:Pacman-key]]<br />
[[ru:Pacman/Package signing]]<br />
[[tr:pacman paket imzaları]]<br />
[[zh-hans:Pacman/Package signing]]<br />
{{Related articles start}}<br />
{{Related|GnuPG}}<br />
{{Related|DeveloperWiki:Package signing}}<br />
{{Related articles end}}<br />
To determine if packages are authentic, ''pacman'' uses [http://www.gnupg.org/ GnuPG keys] in a [http://www.gnupg.org/gph/en/manual.html#AEN385 web of trust] model. There are currently five [https://www.archlinux.org/master-keys/ Master Signing Keys]. At least three of these Master Signing Keys are used to sign each of the Developer's and Trusted User's own keys which then in turn are used to sign their packages. The user also has a unique PGP key which is generated when you set up ''pacman-key''. So the web of trust links the user's key to the five Master Keys.<br />
<br />
Examples of webs of trust:<br />
<br />
* '''Custom packages''': You made the package yourself and signed it with your own key.<br />
* '''Unofficial packages''': A developer made the package and signed it. You used your key to sign that developer's key.<br />
* '''Official packages''': A developer made the package and signed it. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.<br />
<br />
{{Note|The HKP protocol uses 11371/tcp for communication. In order to get the signed keys from the servers (using ''pacman-key''), this port is required for communication.}}<br />
<br />
== Setup ==<br />
<br />
=== Configuring pacman ===<br />
<br />
The {{ic|SigLevel}} option in {{ic|/etc/pacman.conf}} determines how much trust is required to install a package. For a detailed explanation of {{ic|SigLevel}} see the [https://www.archlinux.org/pacman/pacman.conf.5.html#_package_and_database_signature_checking pacman.conf man page] and the comments in the file itself. Signature checking may be set globally or per repository. If {{ic|SigLevel}} is set globally in the {{ic|[options]}} section to require all packages to be signed, then packages you build will also need to be signed using ''makepkg''.<br />
<br />
{{Note|Although all official packages are now signed, as of June 2012 signing of the databases is a work in progress. If {{ic|Required}} is set then {{ic|DatabaseOptional}} should also be set.}}<br />
<br />
A default configuration can be used to only install packages that are signed by trusted keys:<br />
<br />
{{hc|1=/etc/pacman.conf|<br />
output=SigLevel = Required DatabaseOptional<br />
}}<br />
<br />
This is because {{ic|TrustedOnly}} is a default compiled-in ''pacman'' parameter. So above leads to the same result as a global option of:<br />
<br />
SigLevel = Required DatabaseOptional TrustedOnly<br />
<br />
The above can be achieved too on a repository level further below in the configuration, e.g.:<br />
<br />
[core]<br />
SigLevel = PackageRequired<br />
Include = /etc/pacman.d/mirrorlist<br />
<br />
explicitly adds signature checking for the packages of the repository, but does not require the database to be signed. {{ic|Optional}} here would turn off a global {{ic|Required}} for this repository<br />
<br />
{{warning|The SigLevel {{ic|TrustAll}} option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use {{ic|TrustedOnly}} for all official repositories.}}<br />
<br />
=== Initializing the keyring ===<br />
<br />
To set up the ''pacman'' keyring use:<br />
<br />
# pacman-key --init<br />
<br />
For this initialization, [[Wikipedia:Entropy_(computing)|entropy]] is required. Moving your mouse around, pressing random characters at the keyboard or running some disk-based activity (for example in another console running {{ic|ls -R /}} or {{ic|find / -name foo}} or {{ic|1=dd if=/dev/sda8 of=/dev/tty7}}) should generate entropy. If your system does not already have sufficient entropy, this step may take hours; if you actively generate entropy, it will complete much more quickly.<br />
<br />
The randomness created is used to set up a keyring ({{ic|/etc/pacman.d/gnupg}}) and the GPG signing key of your system.<br />
<br />
{{Note|If you need to run {{ic|pacman-key --init}} on computer that does not generate much entropy (e.g. a headless server), key generation may take a very long time. To generate pseudo-entropy, install either [[haveged]] or [[rng-tools]] on the target machine and start the corresponding service before running {{ic|pacman-key --init}}.}}<br />
<br />
== Managing the keyring ==<br />
<br />
=== Verifying the five master keys ===<br />
<br />
The initial setup of keys is achieved using:<br />
# pacman-key --populate archlinux<br />
Take time to verify the [https://www.archlinux.org/master-keys/ Master Signing Keys] when prompted as these are used to co-sign (and therefore trust) all other packager's keys.<br />
<br />
PGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the '(short) key ID' (the last ''sixteen'' digits of the fingerprint would be the 'long key ID').<br />
<br />
=== Adding developer keys ===<br />
<br />
The official developer and TU keys are signed by the master keys, so you do not need to use ''pacman-key'' to sign them yourself. Whenever ''pacman'' encounters a key it does not recognize, it will prompt to download it from a {{ic|keyserver}} configured in {{ic|/etc/pacman.d/gnupg/gpg.conf}} (or by using the {{ic|--keyserver}} option on the command line). Wikipedia maintains a [[wikipedia:Key server (cryptographic)|list of keyservers]].<br />
<br />
Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.<br />
<br />
{{Note|The {{Pkg|archlinux-keyring}} package, which is a dependency of {{Pkg|pacman}}, contains the latest keys. However keys can also be updated manually using {{ic|pacman-key --refresh-keys}} (as root). While doing {{ic|--refresh-keys}}, your local key will also be looked up on the remote keyserver, and you will receive a message about it being not found. This is nothing to be concerned about.}}<br />
<br />
=== Adding unofficial keys ===<br />
<br />
{{Note| It is recommended that for packages requiring a build process, that you add those unofficial keys to a user-keyring, because makepkg does not employ the pacman keyring. See [https://wiki.archlinux.org/index.php/Makepkg#Usage]}}<br />
<br />
You may wish to use this method, for example, to add your own key to the ''pacman'' keyring, or when enabling a signed [[Unofficial user repositories|unofficial repository]].If <br />
<br />
First get the key ID ({{ic|''keyid''}}) from the owner of the key. Then you need to add the key to the keyring:<br />
<br />
* If the key is found on a keyserver, import it with: {{bc|# pacman-key -r ''keyid''}}<br />
<br />
* If otherwise a link to a keyfile is provided, download it and then run: {{bc|# pacman-key --add ''/path/to/downloaded/keyfile''}}<br />
<br />
Always be sure to verify the fingerprint, as you would with a master key, or any other key which you are going to sign.<br />
$ pacman-key -f ''keyid''<br />
<br />
Finally, you need to locally sign the imported key:<br />
# pacman-key --lsign-key ''keyid''<br />
<br />
You now trust this key to sign packages.<br />
<br />
=== Debugging with gpg ===<br />
<br />
For debugging purposes, you can access ''pacman'''s keyring directly with ''gpg'', e.g.:<br />
<br />
# gpg --homedir /etc/pacman.d/gnupg --list-keys<br />
<br />
== Troubleshooting ==<br />
<br />
{{Style|Instructions could be clearer}}<br />
<br />
{{Warning|''pacman-key'' depends on [[time]]. If your system clock is wrong, you'll get:<br />
error: PackageName: signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
}}<br />
<br />
=== Cannot import keys ===<br />
<br />
There are multiple possible sources of this problem:<br />
<br />
* An outdated {{Pkg|archlinux-keyring}} package.<br />
* Incorrect date.<br />
* Your ISP blocked the port used to import PGP keys.<br />
* Your ''pacman'' cache contains copy of unsigned packages from previous attempts.<br />
* {{ic|dirmngr}} is not correctly configured<br />
<br />
You might be stuck because of outdated {{Pkg|archlinux-keyring}} package when doing an upgrade synchronization. Try if [[Pacman#Upgrading_packages|upgrading the system]] can fix it first.<br />
<br />
If you are still having issues, make sure the following file exists {{ic|/root/.gnupg/dirmngr_ldapservers.conf}} and that you can successfully run {{ic|# dirmngr}}. Create an empty file if it doesn't and run {{ic|# dirmngr}} again.<br />
<br />
If it does not help and your date is correct, you could try to switch to the MIT keyserver, which provides an alternate port. To do this, edit {{ic|/etc/pacman.d/gnupg/gpg.conf}} and change the {{ic|keyserver}} line to:<br />
<br />
keyserver hkp://pgp.mit.edu:11371<br />
<br />
If this does not help either, change the keyserver to the kjsl keyserver, which provides this service through port 80 (the HTTP port), which should always remain unblocked:<br />
<br />
keyserver hkp://keyserver.kjsl.com:80<br />
<br />
If you have IPv6 disabled, ''gpg'' will fail when it found some IPv6 address. In this case try with an IPv4-only keyserver like:<br />
<br />
keyserver hkp://ipv4.pool.sks-keyservers.net:11371<br />
<br />
If you happen to forget to run {{ic|pacman-key --populate archlinux}} you might get some errors while importing keys.<br />
<br />
If none of this helps, your ''pacman'' cache, located at {{ic|/var/cache/pacman/pkg/}} might contain unsigned packages from previous attempts. Try cleaning the cache manually or run:<br />
<br />
# pacman -Sc<br />
<br />
which removes all cached packages that have not been installed.<br />
<br />
=== Disabling signature checking ===<br />
<br />
{{Warning|Use with caution. Disabling package signing will allow ''pacman'' to install untrusted packages automatically.}}<br />
<br />
If you are not concerned about package signing, you can disable PGP signature checking completely. Edit {{ic|/etc/pacman.conf}} and uncomment the following line under {{ic|[options]}}:<br />
<br />
SigLevel = Never<br />
<br />
You need to comment out any repository-specific SigLevel settings too because they override the global settings. This will result in no signature checking, which was the behavior before pacman 4. If you decide to do this, you do not need to set up a keyring with ''pacman-key''. You can change this option later if you decide to enable package verification.<br />
<br />
=== Resetting all the keys ===<br />
<br />
If you want to remove or reset all the keys installed in your system, you can remove {{ic|/etc/pacman.d/gnupg}} folder as root and rerun {{ic|pacman-key --init}} and following that add the keys as preferred.<br />
<br />
=== Removing stale packages ===<br />
<br />
If the same packages keep failing and you are sure you did all the ''pacman-key'' stuff right, try removing them like so {{ic|rm /var/cache/pacman/pkg/''badpackage''*}} so that they are freshly downloaded.<br />
<br />
This might actually be the solution if you get a message like {{ic|error: linux: signature from "Some Person <Some.Person@example.com>" is invalid}} or similar when upgrading (i.e. you might not be the victim of a MITM attack after all, your downloaded file was simply corrupt).<br />
<br />
=== Updating keys via proxy ===<br />
<br />
In order to use a proxy when updating keys the {{ic|honor-http-proxy}} option must be set in both {{ic|/etc/gnupg/dirmngr.conf}} and {{ic|/etc/pacman.d/gnupg/dirmngr.conf}}. See [[GnuPG#Use a keyserver]] for more information.<br />
<br />
{{Note|If ''pacman-key'' is used without the {{ic|honor-http-proxy}} option and fails, a reboot may solve the issue.}}<br />
<br />
== See also ==<br />
<br />
* [[DeveloperWiki:Package Signing Proposal for Pacman]]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-1-makepkg-and-repo-add/ Pacman Package Signing – 1: Makepkg and Repo-add]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-2-pacman-key/ Pacman Package Signing – 2: Pacman-key]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-3-pacman/ Pacman Package Signing – 3: Pacman]<br />
* [http://allanmcrae.com/2011/12/pacman-package-signing-4-arch-linux/ Pacman Package Signing – 4: Arch Linux]</div>Medicineman25https://wiki.archlinux.org/index.php?title=Pacman/Package_signing&diff=471332Pacman/Package signing2017-03-20T07:11:54Z<p>Medicineman25: Emphasizing recommendation for adding unofficial package keys, for build packages, to user keyring. Link to Makepkg#Usage provided</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package management]]<br />
[[es:Pacman/Package signing]]<br />
[[fr:pacman-key]]<br />
[[it:Pacman/Package signing]]<br />
[[ja:Pacman-key]]<br />
[[ru:Pacman/Package signing]]<br />
[[tr:pacman paket imzaları]]<br />
[[zh-hans:Pacman/Package signing]]<br />
{{Related articles start}}<br />
{{Related|GnuPG}}<br />
{{Related|DeveloperWiki:Package signing}}<br />
{{Related articles end}}<br />
To determine if packages are authentic, ''pacman'' uses [http://www.gnupg.org/ GnuPG keys] in a [http://www.gnupg.org/gph/en/manual.html#AEN385 web of trust] model. There are currently five [https://www.archlinux.org/master-keys/ Master Signing Keys]. At least three of these Master Signing Keys are used to sign each of the Developer's and Trusted User's own keys which then in turn are used to sign their packages. The user also has a unique PGP key which is generated when you set up ''pacman-key''. So the web of trust links the user's key to the five Master Keys.<br />
<br />
Examples of webs of trust:<br />
<br />
* '''Custom packages''': You made the package yourself and signed it with your own key.<br />
* '''Unofficial packages''': A developer made the package and signed it. You used your key to sign that developer's key.<br />
* '''Official packages''': A developer made the package and signed it. The developer's key was signed by the Arch Linux master keys. You used your key to sign the master keys, and you trust them to vouch for developers.<br />
<br />
{{Note|The HKP protocol uses 11371/tcp for communication. In order to get the signed keys from the servers (using ''pacman-key''), this port is required for communication.}}<br />
<br />
== Setup ==<br />
<br />
=== Configuring pacman ===<br />
<br />
The {{ic|SigLevel}} option in {{ic|/etc/pacman.conf}} determines how much trust is required to install a package. For a detailed explanation of {{ic|SigLevel}} see the [https://www.archlinux.org/pacman/pacman.conf.5.html#_package_and_database_signature_checking pacman.conf man page] and the comments in the file itself. Signature checking may be set globally or per repository. If {{ic|SigLevel}} is set globally in the {{ic|[options]}} section to require all packages to be signed, then packages you build will also need to be signed using ''makepkg''.<br />
<br />
{{Note|Although all official packages are now signed, as of June 2012 signing of the databases is a work in progress. If {{ic|Required}} is set then {{ic|DatabaseOptional}} should also be set.}}<br />
<br />
A default configuration can be used to only install packages that are signed by trusted keys:<br />
<br />
{{hc|1=/etc/pacman.conf|<br />
output=SigLevel = Required DatabaseOptional<br />
}}<br />
<br />
This is because {{ic|TrustedOnly}} is a default compiled-in ''pacman'' parameter. So above leads to the same result as a global option of:<br />
<br />
SigLevel = Required DatabaseOptional TrustedOnly<br />
<br />
The above can be achieved too on a repository level further below in the configuration, e.g.:<br />
<br />
[core]<br />
SigLevel = PackageRequired<br />
Include = /etc/pacman.d/mirrorlist<br />
<br />
explicitly adds signature checking for the packages of the repository, but does not require the database to be signed. {{ic|Optional}} here would turn off a global {{ic|Required}} for this repository<br />
<br />
{{warning|The SigLevel {{ic|TrustAll}} option exists for debugging purposes and makes it very easy to trust keys that have not been verified. You should use {{ic|TrustedOnly}} for all official repositories.}}<br />
<br />
=== Initializing the keyring ===<br />
<br />
To set up the ''pacman'' keyring use:<br />
<br />
# pacman-key --init<br />
<br />
For this initialization, [[Wikipedia:Entropy_(computing)|entropy]] is required. Moving your mouse around, pressing random characters at the keyboard or running some disk-based activity (for example in another console running {{ic|ls -R /}} or {{ic|find / -name foo}} or {{ic|1=dd if=/dev/sda8 of=/dev/tty7}}) should generate entropy. If your system does not already have sufficient entropy, this step may take hours; if you actively generate entropy, it will complete much more quickly.<br />
<br />
The randomness created is used to set up a keyring ({{ic|/etc/pacman.d/gnupg}}) and the GPG signing key of your system.<br />
<br />
{{Note|If you need to run {{ic|pacman-key --init}} on computer that does not generate much entropy (e.g. a headless server), key generation may take a very long time. To generate pseudo-entropy, install either [[haveged]] or [[rng-tools]] on the target machine and start the corresponding service before running {{ic|pacman-key --init}}.}}<br />
<br />
== Managing the keyring ==<br />
<br />
=== Verifying the five master keys ===<br />
<br />
The initial setup of keys is achieved using:<br />
# pacman-key --populate archlinux<br />
Take time to verify the [https://www.archlinux.org/master-keys/ Master Signing Keys] when prompted as these are used to co-sign (and therefore trust) all other packager's keys.<br />
<br />
PGP keys are too large (2048 bits or more) for humans to work with, so they are usually hashed to create a 40-hex-digit fingerprint which can be used to check by hand that two keys are the same. The last eight digits of the fingerprint serve as a name for the key known as the '(short) key ID' (the last ''sixteen'' digits of the fingerprint would be the 'long key ID').<br />
<br />
=== Adding developer keys ===<br />
<br />
The official developer and TU keys are signed by the master keys, so you do not need to use ''pacman-key'' to sign them yourself. Whenever ''pacman'' encounters a key it does not recognize, it will prompt to download it from a {{ic|keyserver}} configured in {{ic|/etc/pacman.d/gnupg/gpg.conf}} (or by using the {{ic|--keyserver}} option on the command line). Wikipedia maintains a [[wikipedia:Key server (cryptographic)|list of keyservers]].<br />
<br />
Once you have downloaded a developer key, you will not have to download it again, and it can be used to verify any other packages signed by that developer.<br />
<br />
{{Note|The {{Pkg|archlinux-keyring}} package, which is a dependency of {{Pkg|pacman}}, contains the latest keys. However keys can also be updated manually using {{ic|pacman-key --refresh-keys}} (as root). While doing {{ic|--refresh-keys}}, your local key will also be looked up on the remote keyserver, and you will receive a message about it being not found. This is nothing to be concerned about.}}<br />
<br />
=== Adding unofficial keys ===<br />
<br />
{{Note: It is recommended that for packages requiring a build process, that you add those unofficial keys to a user-keyring, because makepkg does not employ the pacman keyring. See [https://wiki.archlinux.org/index.php/Makepkg#Usage]}}<br />
<br />
You may wish to use this method, for example, to add your own key to the ''pacman'' keyring, or when enabling a signed [[Unofficial user repositories|unofficial repository]].If <br />
<br />
First get the key ID ({{ic|''keyid''}}) from the owner of the key. Then you need to add the key to the keyring:<br />
<br />
* If the key is found on a keyserver, import it with: {{bc|# pacman-key -r ''keyid''}}<br />
<br />
* If otherwise a link to a keyfile is provided, download it and then run: {{bc|# pacman-key --add ''/path/to/downloaded/keyfile''}}<br />
<br />
Always be sure to verify the fingerprint, as you would with a master key, or any other key which you are going to sign.<br />
$ pacman-key -f ''keyid''<br />
<br />
Finally, you need to locally sign the imported key:<br />
# pacman-key --lsign-key ''keyid''<br />
<br />
You now trust this key to sign packages.<br />
<br />
=== Debugging with gpg ===<br />
<br />
For debugging purposes, you can access ''pacman'''s keyring directly with ''gpg'', e.g.:<br />
<br />
# gpg --homedir /etc/pacman.d/gnupg --list-keys<br />
<br />
== Troubleshooting ==<br />
<br />
{{Style|Instructions could be clearer}}<br />
<br />
{{Warning|''pacman-key'' depends on [[time]]. If your system clock is wrong, you'll get:<br />
error: PackageName: signature from "User <email@archlinux.org>" is invalid<br />
error: failed to commit transaction (invalid or corrupted package (PGP signature))<br />
Errors occured, no packages were upgraded.<br />
}}<br />
<br />
=== Cannot import keys ===<br />
<br />
There are multiple possible sources of this problem:<br />
<br />
* An outdated {{Pkg|archlinux-keyring}} package.<br />
* Incorrect date.<br />
* Your ISP blocked the port used to import PGP keys.<br />
* Your ''pacman'' cache contains copy of unsigned packages from previous attempts.<br />
* {{ic|dirmngr}} is not correctly configured<br />
<br />
You might be stuck because of outdated {{Pkg|archlinux-keyring}} package when doing an upgrade synchronization. Try if [[Pacman#Upgrading_packages|upgrading the system]] can fix it first.<br />
<br />
If you are still having issues, make sure the following file exists {{ic|/root/.gnupg/dirmngr_ldapservers.conf}} and that you can successfully run {{ic|# dirmngr}}. Create an empty file if it doesn't and run {{ic|# dirmngr}} again.<br />
<br />
If it does not help and your date is correct, you could try to switch to the MIT keyserver, which provides an alternate port. To do this, edit {{ic|/etc/pacman.d/gnupg/gpg.conf}} and change the {{ic|keyserver}} line to:<br />
<br />
keyserver hkp://pgp.mit.edu:11371<br />
<br />
If this does not help either, change the keyserver to the kjsl keyserver, which provides this service through port 80 (the HTTP port), which should always remain unblocked:<br />
<br />
keyserver hkp://keyserver.kjsl.com:80<br />
<br />
If you have IPv6 disabled, ''gpg'' will fail when it found some IPv6 address. In this case try with an IPv4-only keyserver like:<br />
<br />
keyserver hkp://ipv4.pool.sks-keyservers.net:11371<br />
<br />
If you happen to forget to run {{ic|pacman-key --populate archlinux}} you might get some errors while importing keys.<br />
<br />
If none of this helps, your ''pacman'' cache, located at {{ic|/var/cache/pacman/pkg/}} might contain unsigned packages from previous attempts. Try cleaning the cache manually or run:<br />
<br />
# pacman -Sc<br />
<br />
which removes all cached packages that have not been installed.<br />
<br />
=== Disabling signature checking ===<br />
<br />
{{Warning|Use with caution. Disabling package signing will allow ''pacman'' to install untrusted packages automatically.}}<br />
<br />
If you are not concerned about package signing, you can disable PGP signature checking completely. Edit {{ic|/etc/pacman.conf}} and uncomment the following line under {{ic|[options]}}:<br />
<br />
SigLevel = Never<br />
<br />
You need to comment out any repository-specific SigLevel settings too because they override the global settings. This will result in no signature checking, which was the behavior before pacman 4. If you decide to do this, you do not need to set up a keyring with ''pacman-key''. You can change this option later if you decide to enable package verification.<br />
<br />
=== Resetting all the keys ===<br />
<br />
If you want to remove or reset all the keys installed in your system, you can remove {{ic|/etc/pacman.d/gnupg}} folder as root and rerun {{ic|pacman-key --init}} and following that add the keys as preferred.<br />
<br />
=== Removing stale packages ===<br />
<br />
If the same packages keep failing and you are sure you did all the ''pacman-key'' stuff right, try removing them like so {{ic|rm /var/cache/pacman/pkg/''badpackage''*}} so that they are freshly downloaded.<br />
<br />
This might actually be the solution if you get a message like {{ic|error: linux: signature from "Some Person <Some.Person@example.com>" is invalid}} or similar when upgrading (i.e. you might not be the victim of a MITM attack after all, your downloaded file was simply corrupt).<br />
<br />
=== Updating keys via proxy ===<br />
<br />
In order to use a proxy when updating keys the {{ic|honor-http-proxy}} option must be set in both {{ic|/etc/gnupg/dirmngr.conf}} and {{ic|/etc/pacman.d/gnupg/dirmngr.conf}}. See [[GnuPG#Use a keyserver]] for more information.<br />
<br />
{{Note|If ''pacman-key'' is used without the {{ic|honor-http-proxy}} option and fails, a reboot may solve the issue.}}<br />
<br />
== See also ==<br />
<br />
* [[DeveloperWiki:Package Signing Proposal for Pacman]]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-1-makepkg-and-repo-add/ Pacman Package Signing – 1: Makepkg and Repo-add]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-2-pacman-key/ Pacman Package Signing – 2: Pacman-key]<br />
* [http://allanmcrae.com/2011/08/pacman-package-signing-3-pacman/ Pacman Package Signing – 3: Pacman]<br />
* [http://allanmcrae.com/2011/12/pacman-package-signing-4-arch-linux/ Pacman Package Signing – 4: Arch Linux]</div>Medicineman25https://wiki.archlinux.org/index.php?title=GnuPG&diff=471331GnuPG2017-03-20T07:08:50Z<p>Medicineman25: typo from previous edit</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans: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 [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. 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 ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''user-id''<br />
<br />
=== Import keys for a specific package ===<br />
<br />
If you wish to import a KEYID for a specific package, simply locate the "validgpgkeys" section of a PKGBUILD file and place the key value within the following command:<br />
<br />
$ gpg --rev-keys <KEYID><br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<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}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{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 />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<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 {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}} and {{ic|gpg-agent-ssh.socket}}.}}<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<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. Either follow [[#Start gpg-agent with systemd user]], 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''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
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|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], 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 />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<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 />
max-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 pcscd (PCSC 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|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{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 />
{{Tip|[[pass]] automates this process.}}<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 use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses 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 />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== 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 />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is 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}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
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 />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt 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://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [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>Medicineman25https://wiki.archlinux.org/index.php?title=GnuPG&diff=471330GnuPG2017-03-20T07:08:17Z<p>Medicineman25: re-ordered section: moved "Import keys for a specific package" up so as to apply existing warning section to this method</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans: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 [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. 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 ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''user-id''<br />
<br />
<br />
=== Import keys for a specific package ===<br />
<br />
If you wish to import a KEYID for a specific package, simply locate the "validgpgkeys" section of a PKGBUILD file and place the key value within the following command:<br />
<br />
$ gpg --rev-keys <KEYID><br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<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}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{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 />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<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 {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}} and {{ic|gpg-agent-ssh.socket}}.}}<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<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. Either follow [[#Start gpg-agent with systemd user]], 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''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
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|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], 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 />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<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 />
max-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 pcscd (PCSC 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|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{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 />
{{Tip|[[pass]] automates this process.}}<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 use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses 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 />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== 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 />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is 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}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
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 />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt 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://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [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>Medicineman25https://wiki.archlinux.org/index.php?title=GnuPG&diff=471329GnuPG2017-03-20T07:02:17Z<p>Medicineman25: typo from previous edit</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans: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 [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. 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 ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''user-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<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}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Import keys for a specific package ===<br />
<br />
If you wish to import a KEYID for a specific package, simply locate the "validgpgkeys" section of a PKGBUILD file and place the key value within the following command:<br />
<br />
$ gpg --rev-keys <KEYID><br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{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 />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<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 {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}} and {{ic|gpg-agent-ssh.socket}}.}}<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<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. Either follow [[#Start gpg-agent with systemd user]], 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''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
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|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], 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 />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<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 />
max-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 pcscd (PCSC 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|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{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 />
{{Tip|[[pass]] automates this process.}}<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 use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses 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 />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== 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 />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is 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}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
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 />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt 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://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [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>Medicineman25https://wiki.archlinux.org/index.php?title=GnuPG&diff=471328GnuPG2017-03-20T07:01:36Z<p>Medicineman25: Added section: "Import Keys for a specific package" breifly, but explicitly, detailing location of KEYID and relevant gpg command syntax</p>
<hr />
<div>[[Category:Encryption]]<br />
[[es:GnuPG]]<br />
[[ja:GnuPG]]<br />
[[ru:GnuPG]]<br />
[[zh-hans: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 [http://openpgp.org/about/ OpenPGP] standard as defined by [https://tools.ietf.org/html/rfc4880 RFC4880] (also known as PGP). GnuPG allows you to encrypt and sign your data and communication. It features a versatile key management system as well as access modules for all kinds of public key directories. GnuPG, also known as GPG, is a command line tool with features for easy integration with other applications. A wealth of frontend applications and libraries are available. Version 2 of GnuPG also provides support for S/MIME and Secure Shell (ssh).<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|gnupg}} package.<br />
<br />
This will also install {{Pkg|pinentry}}, a collection of simple PIN or passphrase entry dialogs which GnuPG uses for passphrase entry. 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 ''user-id''<br />
<br />
To find out details of a key on the keyserver, without importing it, do:<br />
<br />
$ gpg --search-keys ''user-id''<br />
<br />
To import a key from a key server:<br />
<br />
$ gpg --recv-keys ''user-id''<br />
<br />
{{Warning|<br />
* You should verify the authenticity of the retrieved public key by comparing its fingerprint with one that the owner published on an independent source(s) (i.e., contacting the person directly). See [[Wikipedia:Public key fingerprint]] for more information.<br />
* Using a short ID may encounter collisions. All keys will be imported that have the short ID. To avoid this, use the full fingerprint or long key ID when receiving a key.[https://lkml.org/lkml/2016/8/15/445]}}<br />
<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}}. See this [https://gnupg.org/blog/20151224-gnupg-in-november-and-december.html GnuPG blog post] for more information.<br />
* You can connect to a keyserver using a proxy by setting the {{ic|http_proxy}} environment variable and setting {{ic|honor-http-proxy}} in {{ic|dirmngr.conf}}. Alternatively, set {{ic|http-proxy ''host[:port]''}} in {{ic|dirmngr.conf}}, overriding the {{ic|http_proxy}} environment variable.}}<br />
<br />
=== Import keys for a specific package ===<br />
<br />
If you wish to import a KEYID for a specific package, simply locate the "validgpgkeys" section of a PKGBUILD file and place it within the following command:<br />
<br />
$ gpg --rev-keys <KEYID><br />
<br />
=== Encrypt and decrypt ===<br />
<br />
==== Asymmetric ====<br />
You need to [[#Import a public key]] of a user before encrypting (options {{ic|--encrypt}} or {{ic|-e}}) a file or message to that recipient (options {{ic|--recipient}} or {{ic|-r}}). Additionally you need to [[#Create key pair]] if you have not already done so.<br />
<br />
To encrypt a file with the name ''doc'', use:<br />
<br />
$ gpg --recipient ''user-id'' --encrypt ''doc''<br />
<br />
To decrypt (option {{ic|--decrypt}} or {{ic|-d}}) a file with the name ''doc''.gpg encrypted with your public key, use:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
''gpg'' will prompt you for your passphrase and then decrypt and write the data from ''doc''.gpg to ''doc''. If you omit the {{ic|-o}} ({{ic|--output}}) option, ''gpg'' will write the decrypted data to stdout.<br />
<br />
{{Tip|<br />
* Add {{ic|--armor}} to encrypt a file using ASCII armor (suitable for copying and pasting a message in text format)<br />
* Use {{ic|-R ''user-id''}} or {{ic|--hidden-recipient ''user-id''}} instead of {{ic|-r}} to not put the recipient key IDs in the encrypted message. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis.<br />
* Add {{ic|--no-emit-version}} to avoid printing the version number, or add the corresponding setting to your configuration file.<br />
* You can use gnupg to encrypt your sensitive documents by using your own user-id as recipient or by using the {{ic|--default-recipient-self}} flag instead; however, you can only do this one file at a time, although you can always tarball various files and then encrypt the tarball. See also [[Disk encryption#Available methods]] if you want to encrypt directories or a whole file-system.}}<br />
<br />
==== Symmetric ====<br />
Symmetric encryption does not require the generation of a key pair and can be used to simply encrypt data with a passphrase. Simply use {{ic|--symmetric}} or {{ic|-c}} to perform symmetic encryption:<br />
<br />
$ gpg -c ''doc''<br />
<br />
The following example:<br />
<br />
* Encrypts {{ic|''doc''}} with a symmetric cipher using a passphrase<br />
* Uses the AES-256 cipher algorithm to encrypt the passphrase<br />
* Uses the SHA-512 digest algorithm to mangle the passphrase<br />
* Mangles the passphrase for 65536 iterations<br />
<br />
$ gpg -c --s2k-cipher-algo AES256 --s2k-digest-algo SHA512 --s2k-count 65536 ''doc''<br />
<br />
To decrypt a symmetrically encrypted {{ic|''doc''.gpg}} using a passphrase and output decrypted contents into the same directory as {{ic|''doc''}} do:<br />
<br />
$ gpg --output ''doc'' --decrypt ''doc''.gpg<br />
<br />
== Key maintenance ==<br />
<br />
=== Backup your private key ===<br />
<br />
To backup your private key do the following:<br />
<br />
$ gpg --export-secret-keys --armor ''<user-id>'' > ''privkey.asc''<br />
<br />
Note that ''gpg'' release 2.1 changed default behaviour so that the above command enforces a passphrase protection, even if you deliberately chose not to use one on key creation. This is because otherwise anyone who gains access to the above exported file would be able to encrypt and sign documents as if they were you ''without'' needing to know your passphrase. <br />
<br />
{{Warning|The passphrase is usually the weakest link in protecting your secret key. Place the private key in a safe place on a different system/device, such as a locked container or encrypted drive. It is the only safety you have to regain control to your keyring in case of, for example, a drive failure, theft or worse.}}<br />
<br />
To import the backup of your private key:<br />
$ gpg --import ''privkey.asc''<br />
<br />
=== Edit your key ===<br />
<br />
Running the {{ic|gpg --edit-key ''<user-id>''}} command will present a menu which enables you to do most of your key management related tasks.<br />
<br />
Some useful commands in the edit key sub menu:<br />
> passwd # change the passphrase<br />
> clean # compact any user ID that is no longer usable (e.g revoked or expired)<br />
> revkey # revoke a key<br />
> addkey # add a subkey to this key<br />
> expire # change the key expiration time<br />
<br />
Type {{ic|help}} in the edit key sub menu for more commands.<br />
<br />
{{Tip|If you have multiple email accounts you can add each one of them as an identity, using {{ic|adduid}} command. You can then set your favourite one as {{ic|primary}}.}}<br />
<br />
=== Exporting subkey ===<br />
<br />
If you plan to use the same key across multiple devices, you may want to strip out your master key and only keep the bare minimum encryption subkey on less secure systems.<br />
<br />
First, find out which subkey you want to export.<br />
<br />
$ gpg -K<br />
<br />
Select only that subkey to export.<br />
<br />
$ gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.gpg<br />
<br />
{{Warning|If you forget to add the !, all of your subkeys will be exported.}}<br />
<br />
At this point you could stop, but it is most likely a good idea to change the passphrase as well. Import the key into a temporary folder. <br />
<br />
$ gpg --homedir /tmp/gpg --import /tmp/subkey.gpg<br />
$ gpg --homedir /tmp/gpg --edit-key ''<user-id>''<br />
> passwd<br />
> save<br />
$ gpg --homedir /tmp/gpg -a --export-secret-subkeys [subkey id]! > /tmp/subkey.altpass.gpg<br />
<br />
{{Note|You will get a warning that the master key was not available and the password was not changed, but that can safely be ignored as the subkey password was.}}<br />
<br />
At this point, you can now use {{ic|/tmp/subkey.altpass.gpg}} on your other devices.<br />
<br />
=== Rotating subkeys ===<br />
<br />
{{Warning|'''Never''' delete your expired or revoked subkeys unless you have a good reason. Doing so will cause you to lose the ability to decrypt files encrypted with the old subkey. Please '''only''' delete expired or revoked keys from other users to clean your keyring.}}<br />
<br />
If you have set your subkeys to expire after a set time, you can create new ones. Do this a few weeks in advance to allow others to update their keyring.<br />
<br />
{{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 />
=== Create a signature ===<br />
<br />
==== Sign a file ====<br />
<br />
To sign a file use the {{ic|--sign}} or {{ic|-s}} flag:<br />
<br />
$ gpg --output ''doc''.sig --sign ''doc''<br />
<br />
{{ic|''doc''.sig}} contains both the compressed content of the original file {{ic|''doc''}} and the signature in a binary format, but the file is not encrypted. However, you can combine signing with [[#Encrypt and decrypt|encrypting]].<br />
<br />
==== Clearsign a file or message ====<br />
<br />
To sign a file without compressing it into binary format use:<br />
<br />
$ gpg --output ''doc''.sig --clearsign ''doc''<br />
<br />
Here both the content of the original file {{ic|''doc''}} and the signature are stored in human-readable form in {{ic|''doc''.sig}}.<br />
<br />
==== Make a detached signature ====<br />
<br />
To create a separate signature file to be distributed separately from the document or file itself, use the {{ic|--detach-sig}} flag:<br />
<br />
$ gpg --output ''doc''.sig --detach-sig ''doc''<br />
<br />
Here the signature is stored in {{ic|''doc''.sig}}, but the contents of {{ic|''doc''}} are not stored in it. This method is often used in distributing software projects to allow users to verify that the program has not been modified by a third party.<br />
<br />
=== Verify a signature ===<br />
<br />
To verify a signature use the {{ic|--verify}} flag:<br />
<br />
$ gpg --verify ''doc''.sig<br />
<br />
where {{ic|''doc''.sig}} is the signed file containing the signature you wish to verify.<br />
<br />
If you are verifying a detached signature, both the signed data file and the signature file must be present when verifying. For example, to verify Arch Linux's latest iso you would do:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig<br />
<br />
where {{ic|archlinux-''version''.iso}} must be located in the same directory.<br />
<br />
You can also specify the signed data file with a second argument:<br />
<br />
$ gpg --verify archlinux-''version''.iso.sig ''/path/to/''archlinux-''version''.iso<br />
<br />
If a file as been encrypted in addition to being signed, simply [[#Encrypt and decrypt|decrypt]] the file and its signature will also be verified.<br />
<br />
== gpg-agent ==<br />
<br />
''gpg-agent'' is mostly used as daemon to request and cache the password for the keychain. This is useful if GnuPG is used from an external program like a mail client.<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 {{AUR|kwalletcli}} package.}}<br />
<br />
After making this change, reload the gpg-agent.<br />
<br />
=== Start gpg-agent with systemd user ===<br />
<br />
{{Expansion|Add {{ic|gpg-agent-extra.socket}}, {{ic|gpg-agent-browser.socket}} and {{ic|gpg-agent-ssh.socket}}.}}<br />
<br />
It is possible to use the [[Systemd/User]] facilities to start the agent.<br />
<br />
The {{ic|gpg-agent.socket}} unit will start the service on-demand and manage the lifetime. The {{ic|dirmngr.socket}} should usually be enabled too, which is a daemon spawned to handle keyserver requests.<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. Either follow [[#Start gpg-agent with systemd user]], 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''. To make sure each process can find your ''gpg-agent'' instance regardless of e.g. the type of shell it is child of use [[Environment_variables#Using_pam_env|pam_env]].<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
}}<br />
<br />
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|1=<nowiki></nowiki><br />
* If you use non-default GnuPG [[#Directory location]], 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 />
* The test involving the {{ic|gnupg_SSH_AUTH_SOCK_by}} variable is for the case where the agent is started as {{ic|gpg-agent --daemon /bin/sh}}, in which case the shell inherits the {{ic|SSH_AUTH_SOCK}} variable from the parent, ''gpg-agent'' [http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=blob;f=agent/gpg-agent.c;hb=7bca3be65e510eda40572327b87922834ebe07eb#l1307].<br />
}}<br />
<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 />
max-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 pcscd (PCSC 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|pcscd.socket}} has to be listening.}}<br />
<br />
pcscd is a daemon which handles access to smartcard (SCard API). If GnuPG's scdaemon fails to connect the smartcard directly (e.g. by using its integrated CCID support), it will fallback and try to find a smartcard using the PCSC Lite driver.<br />
<br />
==== Always use pcscd ====<br />
<br />
If you are using any smartcard with an opensc driver (e.g.: ID cards from some countries) you should pay some attention to GnuPG configuration. Out of the box you might receive a message like this when using {{Ic|gpg --card-status}}<br />
<br />
gpg: selecting openpgp failed: ec=6.108<br />
<br />
By default, scdaemon will try to connect directly to the device. This connection will fail if the reader is being used by another process. For example: the pcscd daemon used by OpenSC. To cope with this situation we should use the same underlying driver as opensc so they can work well together. In order to point scdaemon to use pcscd you should remove {{Ic|reader-port}} from {{ic|~/.gnupg/scdaemon.conf}}, specify the location to {{ic|libpcsclite.so}} library and disable ccid so we make sure that we use pcscd:<br />
<br />
{{hc|~/.gnupg/scdaemon.conf|<nowiki><br />
pcsc-driver /usr/lib/libpcsclite.so<br />
card-timeout 5<br />
disable-ccid<br />
</nowiki>}}<br />
<br />
Please check {{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 />
{{Tip|[[pass]] automates this process.}}<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 use|Trust on first use]] by adding {{ic|1=--trust-model=tofu}} when adding a key or adding this option to your GnuPG configuration file. More details are in [https://lists.gnupg.org/pipermail/gnupg-devel/2015-October/030341.html this email to the GnuPG list].<br />
<br />
=== Hide all recipient id's ===<br />
<br />
By default the recipient's key ID is in the encrypted message. This can be removed at encryption time for a recipient by using {{ic|hidden-recipient ''<user-id>''}}. To remove it for all recipients add {{ic|throw-keyids}} to your configuration file. This helps to hide the receivers of the message and is a limited countermeasure against traffic analysis. (Using a little social engineering anyone who is able to decrypt the message can check whether one of the other recipients is the one he suspects.) On the receiving side, it may slow down the decryption process because all available secret keys must be tried (''e.g.'' with {{ic|--try-secret-key ''<user-id>''}}).<br />
<br />
=== Using caff for keysigning parties ===<br />
<br />
To allow users to validate keys on the keyservers and in their keyrings (i.e. make sure they are from whom they claim to be), PGP/GPG uses 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 />
=== Always show long ID's and fingerprints ===<br />
<br />
To always show long key ID's add {{ic|keyid-format 0xlong}} to your configuration file. To always show full fingerprints of keys, add {{ic|with-fingerprint}} to your configuration file.<br />
<br />
== 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 />
{{Tip|If you run gpg with {{ic|script}} it will use a new tty with the correct ownership:<br />
<br />
# script -q -c "gpg --gen-key" /dev/null<br />
}}<br />
<br />
=== Agent complains end of file ===<br />
<br />
The default pinentry program is 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}}{{Broken package link|replaced by {{Pkg|kgpg}}}} being able to access the {{ic|~/.gnupg/}} options. One issue might be a result of a deprecated ''options'' file, see the [https://bugs.kde.org/show_bug.cgi?id=290221 bug] report.<br />
<br />
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 />
=== GNOME on Wayland overrides SSH agent socket ===<br />
<br />
For Wayland sessions, {{Ic|gnome-session}} sets {{Ic|SSH_AUTH_SOCK}} to the standard gnome-keyring socket, {{Ic|$XDG_RUNTIME_DIR/keyring/ssh}}. This overrides any value set in {{Ic|~/.pam_environmment}} or systemd unit files.<br />
<br />
To disable this behavior, set the {{Ic|GSM_SKIP_AGENT_WORKAROUND}} variable:<br />
<br />
{{hc|~/.pam_environment|2=<br />
SSH_AGENT_PID DEFAULT=<br />
SSH_AUTH_SOCK DEFAULT="${XDG_RUNTIME_DIR}/gnupg/S.gpg-agent.ssh"<br />
GSM_SKIP_SSH_AGENT_WORKAROUND DEFAULT="true"<br />
}}<br />
<br />
=== mutt 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://tools.ietf.org/html/rfc4880 RFC4880 "OpenPGP Message Format"]<br />
* [https://fedoraproject.org/wiki/Creating_GPG_Keys Creating GPG Keys (Fedora)]<br />
* [https://wiki.debian.org/Subkeys OpenPGP subkeys in Debian]<br />
* [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>Medicineman25https://wiki.archlinux.org/index.php?title=Makepkg&diff=471327Makepkg2017-03-20T06:51:38Z<p>Medicineman25: typo from previous edit</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package development]]<br />
[[Category:About Arch]]<br />
[[ar:Makepkg]]<br />
[[el:Makepkg]]<br />
[[es:Makepkg]]<br />
[[fa:Makepkg]]<br />
[[fr:makepkg]]<br />
[[it:Makepkg]]<br />
[[ja:Makepkg]]<br />
[[nl:Makepkg]]<br />
[[pt:Makepkg]]<br />
[[ru:Makepkg]]<br />
[[sr:Makepkg]]<br />
[[tr:Makepkg]]<br />
[[zh-hans:Makepkg]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Arch User Repository}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
[https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg] is a script to automate the building of packages. The requirements for using the script are a build-capable Unix platform and a [[PKGBUILD]].<br />
<br />
''makepkg'' is provided by the {{Pkg|pacman}} package.<br />
<br />
== Configuration ==<br />
<br />
See {{ic|man makepkg.conf}} for details on configuration options for makepkg.<br />
<br />
The system configuration is available in {{ic|/etc/makepkg.conf}}, but user-specific changes can be made in {{ic|$XDG_CONFIG_HOME/pacman/makepkg.conf}} or {{ic|~/.makepkg.conf}}. It is recommended to review the configuration prior to building packages.<br />
<br />
=== Packager information ===<br />
<br />
Each package is tagged with metadata identifying amongst others also the ''packager''. By default, user-compiled packages are marked with {{ic|Unknown Packager}}. If multiple users will be compiling packages on a system, or you are otherwise distributing your packages to other users, it is convenient to provide real contact. This can be done by setting the {{ic|PACKAGER}} variable in {{ic|makepkg.conf}}.<br />
<br />
To check this on an installed package:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : John Doe <john@doe.com><br />
[...]<br />
</nowiki>}}<br />
<br />
To automatically produce signed packages, also set the {{ic|GPGKEY}} variable in {{ic|makepkg.conf}}.<br />
<br />
=== Package output ===<br />
<br />
By default, ''makepkg'' creates the package tarballs in the working directory and downloads source data directly to the {{ic|src/}} directory. Custom paths can be configured, for example to keep all built packages in {{ic|~/build/packages/}} and all sources in {{ic|~/build/sources/}}.<br />
<br />
Configure the following {{ic|makepkg.conf}} variables if needed:<br />
<br />
* {{ic|PKGDEST}} &mdash; directory for storing resulting packages<br />
* {{ic|SRCDEST}} &mdash; directory for storing [[PKGBUILD#source|source]] data (symbolic links will be placed to {{ic|src/}} if it points elsewhere)<br />
* {{ic|SRCPKGDEST}} &mdash; directory for storing resulting source packages (built with {{ic|makepkg -S}})<br />
<br />
=== Signature checking ===<br />
<br />
If a signature file in the form of {{ic|.sig}} or {{ic|.asc}} is part of the [[PKGBUILD]] source array, ''makepkg'' automatically attempts to [[GnuPG#Verify a signature|verify]] it. In case the user's keyring does not contain the needed public key for signature verification, ''makepkg'' will abort the installation with a message that the PGP key could not be verified. <br />
<br />
If a needed public key is missing, or if you want to add public keys by other developers, you can [[GnuPG#Import_a_public_key|import]] it manually, or you can find it [[GnuPG#Use_a_keyserver|on a keyserver]] and import it from there. <br />
<br />
{{Note| The [[PKGBUILD]] will most likely, contain a [[PKGBUILD#validpgpkeys|validpgpkeys]] entry with the required key IDs.}}<br />
<br />
{{Note|The signature checking implemented in ''makepkg'' does not use pacman's keyring, instead relying on the user's keyring. [http://allanmcrae.com/2015/01/two-pgp-keyrings-for-package-management-in-arch-linux/]}}<br />
<br />
== Usage ==<br />
Before continuing, [[install]] the {{Grp|base-devel}} group. Packages belonging to this group are '''not''' required to be listed as build-time dependencies (''makedepends'') in [[PKGBUILD]] files. In addition, the {{Grp|base}} group is assumed to be installed on '''all''' Arch systems.<br />
<br />
{{Note|<br />
* Make sure [[sudo]] is configured properly for commands passed to [[pacman]].<br />
* Running ''makepkg'' itself as root is [https://lists.archlinux.org/pipermail/pacman-dev/2014-March/018911.html disallowed].[https://projects.archlinux.org/pacman.git/tree/NEWS] Besides how a {{ic|PKGBUILD}} may contain arbitrary commands, building as root is generally considered unsafe.[https://bbs.archlinux.org/viewtopic.php?id&#61;67561] Users who have no access to a regular user account should run makepkg as the [http://allanmcrae.com/2015/01/replacing-makepkg-asroot/ nobody user].<br />
}}<br />
<br />
To build a package, one must first create a [[PKGBUILD]], or build script, as described in [[Creating packages]]. Existing scripts are available from the [[Arch Build System|ABS tree]] or the [[AUR]]. Once in possession of a {{ic|PKGBUILD}}, change to the directory where it is saved and issue the following command to build the package described by said {{ic|PKGBUILD}}:<br />
<br />
$ makepkg<br />
<br />
If required dependencies are missing, ''makepkg'' will issue a warning before failing. To build the package and install needed dependencies, add the flag {{ic|-s}}/{{ic|--syncdeps}}:<br />
<br />
$ makepkg -s<br />
<br />
Adding the {{ic|-r}}/{{ic|--rmdeps}} flag causes ''makepkg'' to remove the make dependencies later, which are no longer needed. If constantly building packages, consider using [[Pacman/Tips and tricks#Removing unused packages (orphans)]] once in a while instead.<br />
<br />
{{Note|<br />
* These dependencies must be available in the configured repositories; see [[pacman#Repositories and mirrors]] for details. Alternatively, one can manually install dependencies prior to building ({{ic|pacman -S --asdeps ''dep1'' ''dep2''}}).<br />
* Only global values are used when installing dependencies, i.e any override done in a split package's packaging function will not be used. [https://patchwork.archlinux.org/patch/2271/]}}<br />
<br />
Once all dependencies are satisfied and the package builds successfully, a package file ({{ic|''pkgname''-''pkgver''.pkg.tar.xz}}) will be created in the working directory. To install, use {{ic|-i}}/{{ic|--install}} (same as {{ic|pacman -U ''pkgname''-''pkgver''.pkg.tar.xz}}):<br />
<br />
$ makepkg -i<br />
<br />
To clean up leftover files and folders, such as files extracted to the {{ic|$srcdir}}, add the option {{ic|-c}}/{{ic|--clean}}. This is useful for multiple builds of the same package or updating the package version, while using the same build folder. It prevents obsolete and remnant files from carrying over to the new builds:<br />
<br />
$ makepkg -c<br />
<br />
For more, see [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Creating optimized packages ===<br />
<br />
A performance improvement of the packaged software can be achieved by enabling compiler optimizations for the host machine. The downside is that packages compiled for a specific processor architecture will not run correctly on other machines. On x86_64 machines, there are rarely significant enough real world performance gains that would warrant investing the time to rebuild official packages.<br />
<br />
However, it is very easy to reduce performance by using "nonstandard" compiler flags. Many compiler optimizations are only useful in certain situations and should not be indiscriminately applied to every package. Unless you can verify/benchmark that something is faster, there is a very good chance it is not! The Gentoo [http://www.gentoo.org/doc/en/gcc-optimization.xml Compilation Optimization Guide] and [http://wiki.gentoo.org/wiki/Safe_CFLAGS Safe CFLAGS] wiki article provide more in-depth information about compiler optimization.<br />
<br />
The options passed to a C/C++ compiler (e.g. {{Pkg|gcc}} or {{Pkg|clang}}) are controlled by the {{ic|CFLAGS}}, {{ic|CXXFLAGS}}, and {{ic|CPPFLAGS}} environment variables. Similarly, the {{Pkg|make}} build system uses {{ic|MAKEFLAGS}}. For use in the Arch build system, ''makepkg'' exposes these environment variables as configuration options in {{ic|makepkg.conf}}. The default values are configured to produce generic packages that can be installed on a wide range of machines.<br />
<br />
{{Note|Keep in mind that not all build systems use the variables configured in {{ic|makepkg.conf}}. For example, ''cmake'' disregards the preprocessor options environment variable, {{ic|CPPFLAGS}}. Consequently, many [[PKGBUILD]]s contain workarounds with options specific to the build system used by the packaged software.}}<br />
<br />
GCC can automatically detect and enable safe architecture-specific optimizations. To use this feature, first remove any {{ic|-march}} and {{ic|-mtune}} flags, then add {{ic|1=-march=native}}. For example,<br />
<br />
CFLAGS="-march=native -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
<br />
To see what flags this enables on your machine, run:<br />
<br />
$ gcc -march=native -v -Q --help=target<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you specify different value than {{ic|1=-march=native}}, then {{ic|1=-Q --help=target}} '''will not''' work as expected.[https://bbs.archlinux.org/viewtopic.php?pid=1616694#p1616694] You need to go through a compilation phase to find out which options are really enabled. See [https://wiki.gentoo.org/wiki/Safe_CFLAGS#Find_CPU-specific_options Find CPU-specific options] on Gentoo wiki for instructions.<br />
* To find out the optimal options for a '''32 bit''' x86 architecture, you can use the script [https://github.com/pixelb/scripts/blob/master/scripts/gcccpuopt gcccpuopt].<br />
}}<br />
<br />
==== MAKEFLAGS ====<br />
<br />
The {{ic|MAKEFLAGS}} option can be used to specify additional options for make. Users with multi-core/multi-processor systems can specify the number of jobs to run simultaneously. This can be accomplished with the use of ''nproc'' to determine the number of available processors, e.g. {{ic|1=MAKEFLAGS="-j$(nproc)"}}. Some [[PKGBUILD]]s specifically override this with {{ic|-j1}}, because of race conditions in certain versions or simply because it is not supported in the first place. Packages that fail to build because of this should be [[Reporting bug guidelines|reported]] on the bug tracker (or in the case of [[AUR]] packages, to the package maintainer) after making sure that the error is indeed being caused by your {{ic|MAKEFLAGS}}.<br />
<br />
See {{ic|man make}} for a complete list of available options.<br />
<br />
=== Improving compile times ===<br />
<br />
==== tmpfs ====<br />
<br />
As compiling requires many I/O operations and handling of small files, moving the working directory to a [[tmpfs]] may bring improvements in build times. <br />
<br />
The {{ic|BUILDDIR}} variable can be temporarily exported to ''makepkg'' to set the build directory to an existing tmpfs. For example:<br />
<br />
$ BUILDDIR=/tmp/makepkg makepkg<br />
<br />
{{Warning|Avoid compiling larger packages in tmpfs to prevent running out of memory.}}<br />
<br />
Persistent configuration can be done in {{ic|makepkg.conf}} by uncommenting the {{ic|BUILDDIR}} option, which is found at the end of the {{ic|BUILD ENVIRONMENT}} section in the default {{ic|/etc/makepkg.conf}} file. Setting its value to e.g. {{ic|1=BUILDDIR=/tmp/makepkg}} will make use of the Arch's default {{ic|/tmp}} [[tmpfs]].<br />
<br />
{{Note|<br />
* The [[tmpfs]] folder must be mounted without the {{ic|noexec}} option, else it will prevent build scripts or utilities from being executed.<br />
* Keep in mind that any package compiled in [[tmpfs]] will not persist across reboot. Consider setting the [[#Package output|PKGDEST]] option appropriately to move the built package automatically to another (persistent) directory.<br />
}}<br />
<br />
==== ccache ====<br />
<br />
The use of [[ccache]] can improve build times by caching the results of compilations.<br />
<br />
=== Generate new checksums ===<br />
Since [http://allanmcrae.com/2013/04/pacman-4-1-released/ pacman 4.1], {{ic|makepkg -g >> PKGBUILD}} is no longer required because pacman-contrib was [https://projects.archlinux.org/pacman.git/tree/NEWS merged into upstream pacman], including the {{ic|updpkgsums}} script that will generate new checksums and/or replace them in the PKGBUILD. In the same directory as the PKGBUILD file, run the following command:<br />
$ updpkgsums<br />
<br />
=== Create uncompressed packages ===<br />
If you do not mind having larger package files, you can speed up both packaging and installation by having makepkg produce uncompressed packages. Set {{ic|1=PKGEXT='.pkg.tar'}} in {{ic|/etc/makepkg.conf}}.<br />
<br />
=== Utilizing multiple cores on compression ===<br />
{{pkg|xz}} supports [[Wikipedia:Symmetric multiprocessing|symmetric multiprocessing (SMP)]] via the {{ic|--threads}} flag to speed up compression. For example, to let makepkg use as many CPU cores as possible to compress packages, edit {{ic|COMPRESSXZ}} array in {{ic|/etc/makepkg.conf}}:<br />
<br />
COMPRESSXZ=(xz -c -z - '''--threads=0''')<br />
<br />
=== Build 32-bit packages on a 64-bit system ===<br />
{{Warning|Errors have been reported when using this method to build the {{Pkg|linux}} package. The [[Install bundled 32-bit system in 64-bit system|chroot method]] is preferred and has been verified to work for building the kernel packages.}}<br />
<br />
First, enable the [[multilib]] repository and [[install]] {{Grp|multilib-devel}}. Reply yes when asked about removing the conflicting {{ic|gcc}} and {{ic|gcc-libs}} packages; gcc-multilib is capable of building both 64-bit and 32-bit software.<br />
<br />
Then create a 32-bit configuration file<br />
<br />
{{hc|~/.makepkg.i686.conf|<nowiki><br />
CARCH="i686"<br />
CHOST="i686-unknown-linux-gnu"<br />
CFLAGS="-m32 -march=i686 -mtune=generic -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
LDFLAGS="-m32 -Wl,-O1,--sort-common,--as-needed,-z,relro"</nowiki>}}<br />
<br />
and invoke makepkg as such<br />
$ linux32 makepkg --config ~/.makepkg.i686.conf<br />
<br />
== Troubleshooting ==<br />
<br />
=== Makepkg sometimes fails to sign a package without asking for signature passphrase ===<br />
<br />
{{Style|Vague instructions}}<br />
<br />
With [https://www.gnupg.org/faq/whats-new-in-2.1.html gnupg 2.1], gpg-agent no longer has to be started manually and will be started automatically on the first invokation of gpg. Thus if you do not manually start gpg-agent, makepkg will start it. The problem is that makepkg runs gpg inside a fakeroot, so gpg-agent is also started in that same environment. This leads to bad behavior. A possible solution is to manually start the gpg-agent, either on boot or by command (see [[GnuPG#gpg-agent]] for ways to do this), before you run makepkg, but this also can be unreliable: {{Bug|49946}}.<br />
<br />
In the meantime if you do not wish to experiment with your gpg-agent configuration, simply use makepkg ''without'' signing, and sign the packages afterwards with {{ic|gpg --detach-sign ''name''.pkg.tar.xz}}.<br />
<br />
=== CFLAGS/CXXFLAGS/CPPFLAGS in makepkg.conf do not work for QMAKE based packages ===<br />
Qmake automatically sets the variable {{ic|CFLAGS}} and {{ic|CXXFLAGS}} according to what it thinks should be the right configuration. In order to let qmake use the variables defined in the makepkg configuration file, you must edit the PKGBUILD and pass the variables [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cflags-release QMAKE_CFLAGS_RELEASE] and [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cxxflags-release QMAKE_CXXFLAGS_RELEASE] to qmake. For example:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
build() {<br />
cd "$srcdir/$_pkgname-$pkgver-src"<br />
qmake-qt4 "$srcdir/$_pkgname-$pkgver-src/$_pkgname.pro" \<br />
PREFIX=/usr \<br />
QMAKE_CFLAGS_RELEASE="${CFLAGS}"\<br />
QMAKE_CXXFLAGS_RELEASE="${CXXFLAGS}"<br />
<br />
make<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, for a system wide configuration, you can create your own {{ic|qmake.conf}} and set the [http://doc.qt.io/qt-5/qmake-environment-reference.html#qmakespec QMAKESPEC] environment variable.<br />
<br />
=== Specifying install directory for QMAKE based packages ===<br />
The makefile generated by qmake uses the environment variable INSTALL_ROOT to specify where the program should be installed. Thus this package function should work:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
package() {<br />
cd "$srcdir/${pkgname%-git}"<br />
make INSTALL_ROOT="$pkgdir" install<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Note, that qmake also has to be configured appropriately. For example put this in your .pro file:<br />
<br />
{{hc|YourProject.pro|<nowiki><br />
...<br />
<br />
target.path = /usr/local/bin<br />
INSTALLS += target<br />
<br />
...<br />
</nowiki>}}<br />
<br />
=== WARNING: Package contains reference to $srcdir ===<br />
<br />
Somehow, the literal strings {{ic|$srcdir}} or {{ic|$pkgdir}} ended up in one of the installed files in your package.<br />
<br />
To identify which files, run the following from the ''makepkg'' build directory:<br />
$ grep -R "$(pwd)/src" pkg/<br />
<br />
[http://www.mail-archive.com/arch-general@archlinux.org/msg15561.html Link] to discussion thread.<br />
<br />
== See also ==<br />
<br />
* [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8) Manual Page]<br />
* [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5) Manual Page]<br />
* [https://gist.github.com/Earnestly/bebad057f40a662b5cc3 A Brief Tour of the Makepkg Process]<br />
* [https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg source code]</div>Medicineman25https://wiki.archlinux.org/index.php?title=Makepkg&diff=471326Makepkg2017-03-20T06:49:57Z<p>Medicineman25: placed emphasis on the location of the KEYID i.e. within a PKGBUILD. I was lacking in this specific piece of information and I feel it would be useful to briefly draw attention.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Package development]]<br />
[[Category:About Arch]]<br />
[[ar:Makepkg]]<br />
[[el:Makepkg]]<br />
[[es:Makepkg]]<br />
[[fa:Makepkg]]<br />
[[fr:makepkg]]<br />
[[it:Makepkg]]<br />
[[ja:Makepkg]]<br />
[[nl:Makepkg]]<br />
[[pt:Makepkg]]<br />
[[ru:Makepkg]]<br />
[[sr:Makepkg]]<br />
[[tr:Makepkg]]<br />
[[zh-hans:Makepkg]]<br />
{{Related articles start}}<br />
{{Related|Creating packages}}<br />
{{Related|PKGBUILD}}<br />
{{Related|.SRCINFO}}<br />
{{Related|Arch User Repository}}<br />
{{Related|pacman}}<br />
{{Related|Official repositories}}<br />
{{Related|Arch Build System}}<br />
{{Related articles end}}<br />
<br />
[https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg] is a script to automate the building of packages. The requirements for using the script are a build-capable Unix platform and a [[PKGBUILD]].<br />
<br />
''makepkg'' is provided by the {{Pkg|pacman}} package.<br />
<br />
== Configuration ==<br />
<br />
See {{ic|man makepkg.conf}} for details on configuration options for makepkg.<br />
<br />
The system configuration is available in {{ic|/etc/makepkg.conf}}, but user-specific changes can be made in {{ic|$XDG_CONFIG_HOME/pacman/makepkg.conf}} or {{ic|~/.makepkg.conf}}. It is recommended to review the configuration prior to building packages.<br />
<br />
=== Packager information ===<br />
<br />
Each package is tagged with metadata identifying amongst others also the ''packager''. By default, user-compiled packages are marked with {{ic|Unknown Packager}}. If multiple users will be compiling packages on a system, or you are otherwise distributing your packages to other users, it is convenient to provide real contact. This can be done by setting the {{ic|PACKAGER}} variable in {{ic|makepkg.conf}}.<br />
<br />
To check this on an installed package:<br />
<br />
{{hc|$ pacman -Qi ''package''|<nowiki><br />
[...]<br />
Packager : John Doe <john@doe.com><br />
[...]<br />
</nowiki>}}<br />
<br />
To automatically produce signed packages, also set the {{ic|GPGKEY}} variable in {{ic|makepkg.conf}}.<br />
<br />
=== Package output ===<br />
<br />
By default, ''makepkg'' creates the package tarballs in the working directory and downloads source data directly to the {{ic|src/}} directory. Custom paths can be configured, for example to keep all built packages in {{ic|~/build/packages/}} and all sources in {{ic|~/build/sources/}}.<br />
<br />
Configure the following {{ic|makepkg.conf}} variables if needed:<br />
<br />
* {{ic|PKGDEST}} &mdash; directory for storing resulting packages<br />
* {{ic|SRCDEST}} &mdash; directory for storing [[PKGBUILD#source|source]] data (symbolic links will be placed to {{ic|src/}} if it points elsewhere)<br />
* {{ic|SRCPKGDEST}} &mdash; directory for storing resulting source packages (built with {{ic|makepkg -S}})<br />
<br />
=== Signature checking ===<br />
<br />
If a signature file in the form of {{ic|.sig}} or {{ic|.asc}} is part of the [[PKGBUILD]] source array, ''makepkg'' automatically attempts to [[GnuPG#Verify a signature|verify]] it. In case the user's keyring does not contain the needed public key for signature verification, ''makepkg'' will abort the installation with a message that the PGP key could not be verified. <br />
<br />
If a needed public key is missing, or if you want to add public keys by other developers, you can [[GnuPG#Import_a_public_key|import]] it manually, or you can find it [[GnuPG#Use_a_keyserver|on a keyserver]] and import it from there. <br />
<br />
{{Note: The [[PKGBUILD]] will most likely, contain a [[PKGBUILD#validpgpkeys|validpgpkeys]] entry with the required key IDs.}}<br />
<br />
{{Note|The signature checking implemented in ''makepkg'' does not use pacman's keyring, instead relying on the user's keyring. [http://allanmcrae.com/2015/01/two-pgp-keyrings-for-package-management-in-arch-linux/]}}<br />
<br />
== Usage ==<br />
Before continuing, [[install]] the {{Grp|base-devel}} group. Packages belonging to this group are '''not''' required to be listed as build-time dependencies (''makedepends'') in [[PKGBUILD]] files. In addition, the {{Grp|base}} group is assumed to be installed on '''all''' Arch systems.<br />
<br />
{{Note|<br />
* Make sure [[sudo]] is configured properly for commands passed to [[pacman]].<br />
* Running ''makepkg'' itself as root is [https://lists.archlinux.org/pipermail/pacman-dev/2014-March/018911.html disallowed].[https://projects.archlinux.org/pacman.git/tree/NEWS] Besides how a {{ic|PKGBUILD}} may contain arbitrary commands, building as root is generally considered unsafe.[https://bbs.archlinux.org/viewtopic.php?id&#61;67561] Users who have no access to a regular user account should run makepkg as the [http://allanmcrae.com/2015/01/replacing-makepkg-asroot/ nobody user].<br />
}}<br />
<br />
To build a package, one must first create a [[PKGBUILD]], or build script, as described in [[Creating packages]]. Existing scripts are available from the [[Arch Build System|ABS tree]] or the [[AUR]]. Once in possession of a {{ic|PKGBUILD}}, change to the directory where it is saved and issue the following command to build the package described by said {{ic|PKGBUILD}}:<br />
<br />
$ makepkg<br />
<br />
If required dependencies are missing, ''makepkg'' will issue a warning before failing. To build the package and install needed dependencies, add the flag {{ic|-s}}/{{ic|--syncdeps}}:<br />
<br />
$ makepkg -s<br />
<br />
Adding the {{ic|-r}}/{{ic|--rmdeps}} flag causes ''makepkg'' to remove the make dependencies later, which are no longer needed. If constantly building packages, consider using [[Pacman/Tips and tricks#Removing unused packages (orphans)]] once in a while instead.<br />
<br />
{{Note|<br />
* These dependencies must be available in the configured repositories; see [[pacman#Repositories and mirrors]] for details. Alternatively, one can manually install dependencies prior to building ({{ic|pacman -S --asdeps ''dep1'' ''dep2''}}).<br />
* Only global values are used when installing dependencies, i.e any override done in a split package's packaging function will not be used. [https://patchwork.archlinux.org/patch/2271/]}}<br />
<br />
Once all dependencies are satisfied and the package builds successfully, a package file ({{ic|''pkgname''-''pkgver''.pkg.tar.xz}}) will be created in the working directory. To install, use {{ic|-i}}/{{ic|--install}} (same as {{ic|pacman -U ''pkgname''-''pkgver''.pkg.tar.xz}}):<br />
<br />
$ makepkg -i<br />
<br />
To clean up leftover files and folders, such as files extracted to the {{ic|$srcdir}}, add the option {{ic|-c}}/{{ic|--clean}}. This is useful for multiple builds of the same package or updating the package version, while using the same build folder. It prevents obsolete and remnant files from carrying over to the new builds:<br />
<br />
$ makepkg -c<br />
<br />
For more, see [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8)].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Creating optimized packages ===<br />
<br />
A performance improvement of the packaged software can be achieved by enabling compiler optimizations for the host machine. The downside is that packages compiled for a specific processor architecture will not run correctly on other machines. On x86_64 machines, there are rarely significant enough real world performance gains that would warrant investing the time to rebuild official packages.<br />
<br />
However, it is very easy to reduce performance by using "nonstandard" compiler flags. Many compiler optimizations are only useful in certain situations and should not be indiscriminately applied to every package. Unless you can verify/benchmark that something is faster, there is a very good chance it is not! The Gentoo [http://www.gentoo.org/doc/en/gcc-optimization.xml Compilation Optimization Guide] and [http://wiki.gentoo.org/wiki/Safe_CFLAGS Safe CFLAGS] wiki article provide more in-depth information about compiler optimization.<br />
<br />
The options passed to a C/C++ compiler (e.g. {{Pkg|gcc}} or {{Pkg|clang}}) are controlled by the {{ic|CFLAGS}}, {{ic|CXXFLAGS}}, and {{ic|CPPFLAGS}} environment variables. Similarly, the {{Pkg|make}} build system uses {{ic|MAKEFLAGS}}. For use in the Arch build system, ''makepkg'' exposes these environment variables as configuration options in {{ic|makepkg.conf}}. The default values are configured to produce generic packages that can be installed on a wide range of machines.<br />
<br />
{{Note|Keep in mind that not all build systems use the variables configured in {{ic|makepkg.conf}}. For example, ''cmake'' disregards the preprocessor options environment variable, {{ic|CPPFLAGS}}. Consequently, many [[PKGBUILD]]s contain workarounds with options specific to the build system used by the packaged software.}}<br />
<br />
GCC can automatically detect and enable safe architecture-specific optimizations. To use this feature, first remove any {{ic|-march}} and {{ic|-mtune}} flags, then add {{ic|1=-march=native}}. For example,<br />
<br />
CFLAGS="-march=native -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
<br />
To see what flags this enables on your machine, run:<br />
<br />
$ gcc -march=native -v -Q --help=target<br />
<br />
{{Note|1=<nowiki></nowiki><br />
* If you specify different value than {{ic|1=-march=native}}, then {{ic|1=-Q --help=target}} '''will not''' work as expected.[https://bbs.archlinux.org/viewtopic.php?pid=1616694#p1616694] You need to go through a compilation phase to find out which options are really enabled. See [https://wiki.gentoo.org/wiki/Safe_CFLAGS#Find_CPU-specific_options Find CPU-specific options] on Gentoo wiki for instructions.<br />
* To find out the optimal options for a '''32 bit''' x86 architecture, you can use the script [https://github.com/pixelb/scripts/blob/master/scripts/gcccpuopt gcccpuopt].<br />
}}<br />
<br />
==== MAKEFLAGS ====<br />
<br />
The {{ic|MAKEFLAGS}} option can be used to specify additional options for make. Users with multi-core/multi-processor systems can specify the number of jobs to run simultaneously. This can be accomplished with the use of ''nproc'' to determine the number of available processors, e.g. {{ic|1=MAKEFLAGS="-j$(nproc)"}}. Some [[PKGBUILD]]s specifically override this with {{ic|-j1}}, because of race conditions in certain versions or simply because it is not supported in the first place. Packages that fail to build because of this should be [[Reporting bug guidelines|reported]] on the bug tracker (or in the case of [[AUR]] packages, to the package maintainer) after making sure that the error is indeed being caused by your {{ic|MAKEFLAGS}}.<br />
<br />
See {{ic|man make}} for a complete list of available options.<br />
<br />
=== Improving compile times ===<br />
<br />
==== tmpfs ====<br />
<br />
As compiling requires many I/O operations and handling of small files, moving the working directory to a [[tmpfs]] may bring improvements in build times. <br />
<br />
The {{ic|BUILDDIR}} variable can be temporarily exported to ''makepkg'' to set the build directory to an existing tmpfs. For example:<br />
<br />
$ BUILDDIR=/tmp/makepkg makepkg<br />
<br />
{{Warning|Avoid compiling larger packages in tmpfs to prevent running out of memory.}}<br />
<br />
Persistent configuration can be done in {{ic|makepkg.conf}} by uncommenting the {{ic|BUILDDIR}} option, which is found at the end of the {{ic|BUILD ENVIRONMENT}} section in the default {{ic|/etc/makepkg.conf}} file. Setting its value to e.g. {{ic|1=BUILDDIR=/tmp/makepkg}} will make use of the Arch's default {{ic|/tmp}} [[tmpfs]].<br />
<br />
{{Note|<br />
* The [[tmpfs]] folder must be mounted without the {{ic|noexec}} option, else it will prevent build scripts or utilities from being executed.<br />
* Keep in mind that any package compiled in [[tmpfs]] will not persist across reboot. Consider setting the [[#Package output|PKGDEST]] option appropriately to move the built package automatically to another (persistent) directory.<br />
}}<br />
<br />
==== ccache ====<br />
<br />
The use of [[ccache]] can improve build times by caching the results of compilations.<br />
<br />
=== Generate new checksums ===<br />
Since [http://allanmcrae.com/2013/04/pacman-4-1-released/ pacman 4.1], {{ic|makepkg -g >> PKGBUILD}} is no longer required because pacman-contrib was [https://projects.archlinux.org/pacman.git/tree/NEWS merged into upstream pacman], including the {{ic|updpkgsums}} script that will generate new checksums and/or replace them in the PKGBUILD. In the same directory as the PKGBUILD file, run the following command:<br />
$ updpkgsums<br />
<br />
=== Create uncompressed packages ===<br />
If you do not mind having larger package files, you can speed up both packaging and installation by having makepkg produce uncompressed packages. Set {{ic|1=PKGEXT='.pkg.tar'}} in {{ic|/etc/makepkg.conf}}.<br />
<br />
=== Utilizing multiple cores on compression ===<br />
{{pkg|xz}} supports [[Wikipedia:Symmetric multiprocessing|symmetric multiprocessing (SMP)]] via the {{ic|--threads}} flag to speed up compression. For example, to let makepkg use as many CPU cores as possible to compress packages, edit {{ic|COMPRESSXZ}} array in {{ic|/etc/makepkg.conf}}:<br />
<br />
COMPRESSXZ=(xz -c -z - '''--threads=0''')<br />
<br />
=== Build 32-bit packages on a 64-bit system ===<br />
{{Warning|Errors have been reported when using this method to build the {{Pkg|linux}} package. The [[Install bundled 32-bit system in 64-bit system|chroot method]] is preferred and has been verified to work for building the kernel packages.}}<br />
<br />
First, enable the [[multilib]] repository and [[install]] {{Grp|multilib-devel}}. Reply yes when asked about removing the conflicting {{ic|gcc}} and {{ic|gcc-libs}} packages; gcc-multilib is capable of building both 64-bit and 32-bit software.<br />
<br />
Then create a 32-bit configuration file<br />
<br />
{{hc|~/.makepkg.i686.conf|<nowiki><br />
CARCH="i686"<br />
CHOST="i686-unknown-linux-gnu"<br />
CFLAGS="-m32 -march=i686 -mtune=generic -O2 -pipe -fstack-protector-strong"<br />
CXXFLAGS="${CFLAGS}"<br />
LDFLAGS="-m32 -Wl,-O1,--sort-common,--as-needed,-z,relro"</nowiki>}}<br />
<br />
and invoke makepkg as such<br />
$ linux32 makepkg --config ~/.makepkg.i686.conf<br />
<br />
== Troubleshooting ==<br />
<br />
=== Makepkg sometimes fails to sign a package without asking for signature passphrase ===<br />
<br />
{{Style|Vague instructions}}<br />
<br />
With [https://www.gnupg.org/faq/whats-new-in-2.1.html gnupg 2.1], gpg-agent no longer has to be started manually and will be started automatically on the first invokation of gpg. Thus if you do not manually start gpg-agent, makepkg will start it. The problem is that makepkg runs gpg inside a fakeroot, so gpg-agent is also started in that same environment. This leads to bad behavior. A possible solution is to manually start the gpg-agent, either on boot or by command (see [[GnuPG#gpg-agent]] for ways to do this), before you run makepkg, but this also can be unreliable: {{Bug|49946}}.<br />
<br />
In the meantime if you do not wish to experiment with your gpg-agent configuration, simply use makepkg ''without'' signing, and sign the packages afterwards with {{ic|gpg --detach-sign ''name''.pkg.tar.xz}}.<br />
<br />
=== CFLAGS/CXXFLAGS/CPPFLAGS in makepkg.conf do not work for QMAKE based packages ===<br />
Qmake automatically sets the variable {{ic|CFLAGS}} and {{ic|CXXFLAGS}} according to what it thinks should be the right configuration. In order to let qmake use the variables defined in the makepkg configuration file, you must edit the PKGBUILD and pass the variables [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cflags-release QMAKE_CFLAGS_RELEASE] and [http://doc.qt.io/qt-5/qmake-variable-reference.html#qmake-cxxflags-release QMAKE_CXXFLAGS_RELEASE] to qmake. For example:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
build() {<br />
cd "$srcdir/$_pkgname-$pkgver-src"<br />
qmake-qt4 "$srcdir/$_pkgname-$pkgver-src/$_pkgname.pro" \<br />
PREFIX=/usr \<br />
QMAKE_CFLAGS_RELEASE="${CFLAGS}"\<br />
QMAKE_CXXFLAGS_RELEASE="${CXXFLAGS}"<br />
<br />
make<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Alternatively, for a system wide configuration, you can create your own {{ic|qmake.conf}} and set the [http://doc.qt.io/qt-5/qmake-environment-reference.html#qmakespec QMAKESPEC] environment variable.<br />
<br />
=== Specifying install directory for QMAKE based packages ===<br />
The makefile generated by qmake uses the environment variable INSTALL_ROOT to specify where the program should be installed. Thus this package function should work:<br />
<br />
{{hc|PKGBUILD|<nowiki><br />
...<br />
<br />
package() {<br />
cd "$srcdir/${pkgname%-git}"<br />
make INSTALL_ROOT="$pkgdir" install<br />
}<br />
<br />
...<br />
</nowiki>}}<br />
<br />
Note, that qmake also has to be configured appropriately. For example put this in your .pro file:<br />
<br />
{{hc|YourProject.pro|<nowiki><br />
...<br />
<br />
target.path = /usr/local/bin<br />
INSTALLS += target<br />
<br />
...<br />
</nowiki>}}<br />
<br />
=== WARNING: Package contains reference to $srcdir ===<br />
<br />
Somehow, the literal strings {{ic|$srcdir}} or {{ic|$pkgdir}} ended up in one of the installed files in your package.<br />
<br />
To identify which files, run the following from the ''makepkg'' build directory:<br />
$ grep -R "$(pwd)/src" pkg/<br />
<br />
[http://www.mail-archive.com/arch-general@archlinux.org/msg15561.html Link] to discussion thread.<br />
<br />
== See also ==<br />
<br />
* [https://www.archlinux.org/pacman/makepkg.8.html makepkg(8) Manual Page]<br />
* [https://www.archlinux.org/pacman/makepkg.conf.5.html makepkg.conf(5) Manual Page]<br />
* [https://gist.github.com/Earnestly/bebad057f40a662b5cc3 A Brief Tour of the Makepkg Process]<br />
* [https://projects.archlinux.org/pacman.git/tree/scripts/makepkg.sh.in makepkg source code]</div>Medicineman25