https://wiki.archlinux.org/api.php?action=feedcontributions&user=Nahant&feedformat=atomArchWiki - User contributions [en]2024-03-28T23:41:46ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=AMDGPU&diff=567546AMDGPU2019-02-28T18:29:36Z<p>Nahant: Fixed typo</p>
<hr />
<div>[[Category:Graphics]]<br />
[[Category:X server]]<br />
[[de:AMDGPU]]<br />
[[ja:AMDGPU]]<br />
[[ru:AMDGPU]]<br />
{{Related articles start}}<br />
{{Related|AMD Catalyst}}<br />
{{Related|ATI}}<br />
{{Related|Xorg}}<br />
{{Related|Vulkan}}<br />
{{Related articles end}}<br />
<br />
'''amdgpu''' is the open source graphics driver for the latest AMD Radeon graphics cards.<br />
<br />
== Selecting the right driver ==<br />
<br />
Depending on the card you have, find the right driver in [[Xorg#AMD]]. This page has instructions for '''AMDGPU''' and '''AMDGPU PRO'''.<br />
<br />
At the moment there is support for [https://www.x.org/wiki/RadeonFeature/ Volcanic Islands (VI)] (and newer) and experimental support for [https://www.phoronix.com/scan.php?page=news_item&px=AMD-AMDGPU-Released Sea Islands (CI)] and [https://www.phoronix.com/scan.php?page=news_item&px=AMDGPU-SI-Experimental-Code Southern Islands (SI)] cards. AMD has no plans to support pre-GCN GPUs.<br />
<br />
Owners of unsupported GPUs may use the open source [[radeon]] or the [[AMD Catalyst]] driver instead.<br />
<br />
== Installation ==<br />
<br />
{{Note|If coming from the proprietary Catalyst driver, see [[AMD Catalyst#Uninstallation]] first.}}<br />
<br />
[[Install]] the {{Pkg|mesa}} package, which provides the DRI driver for 3D acceleration.<br />
<br />
* For 32-bit application support, also install the {{Pkg|lib32-mesa}} package from the [[multilib]] repostory.<br />
* For the DDX driver (which provides 2D acceleration in [[Xorg]]), install the {{Pkg|xf86-video-amdgpu}} package.<br />
* For [[Vulkan]] support, install the {{Pkg|vulkan-radeon}} package. Optionally install the {{Pkg|lib32-vulkan-radeon}} package for 32-bit application support.<br />
<br />
Support for [[#Video acceleration|accelerated video decoding]] is provided by {{Pkg|libva-mesa-driver}} and {{Pkg|lib32-libva-mesa-driver}} for VA-API and {{Pkg|mesa-vdpau}} and {{Pkg|lib32-mesa-vdpau}} packages for VDPAU.<br />
<br />
=== Enable Southern Islands (SI) and Sea Islands (CIK) support ===<br />
<br />
The {{Pkg|linux}} package enables AMDGPU support for cards of the Southern Islands (SI) and Sea Islands (CIK). When building or compiling a [[kernel]], {{ic|1=CONFIG_DRM_AMDGPU_SI=Y}} and/or {{ic|1=CONFIG_DRM_AMDGPU_CIK=Y}} should be be set in the config.<br />
<br />
Even when AMDGPU support for SI/CIK has been enabled by the kernel, the [[radeon]] driver may be used instead of the AMDGPU driver.<br />
<br />
To make sure the {{ic|amdgpu}} is loaded first use the following [[Mkinitcpio#MODULES]] array, e.g. {{ic|1=MODULES=(amdgpu radeon)}}.<br />
<br />
==== Set required module parameters ====<br />
<br />
To enable full support for SI/CIK when using the {{ic|amdgpu}}, set the following [[kernel parameters]] to prevent the {{ic|radeon}} module from being used [http://www.phoronix.com/scan.php?page=article&item=linux-413-gcn101&num=1]:<br />
<br />
{{hc|$ dmesg|2=<br />
[..] amdgpu 0000:01:00.0: CIK support provided by radeon.<br />
[..] amdgpu 0000:01:00.0: Use radeon.cik_support=0 amdgpu.cik_support=1 to override.<br />
}}<br />
<br />
The flags depend on the cards GCN version: <br />
<br />
* Southern Islands (SI): {{ic|1=radeon.si_support=0 amdgpu.si_support=1}}<br />
* Sea Islands (CIK): {{ic|1=radeon.cik_support=0 amdgpu.cik_support=1}}<br />
<br />
=== AMDGPU PRO ===<br />
<br />
{{Warning|Arch Linux is officially not supported.}}<br />
{{Out of date|AMDGPU-PRO 18.50 driver [https://www.amd.com/en/support/kb/release-notes/rn-rad-lin-18-50-unified released]. Required downgrade versions may differ.}}<br />
{{Note|<br />
*To use the proprietary OpenCL component without AMDGPU PRO, [[install]] {{AUR|opencl-amd}} instead.<br />
*A [[downgrade]] of the {{pkg|linux}} (4.9) and [[Xorg]] (1.18) packages is required to use AMDGPU PRO 17.10.<br />
}}<br />
<br />
AMD provides a proprietary, binary userland driver called ''AMDGPU PRO'', which works on top of the open-source AMDGPU kernel driver. The driver provides OpenGL, [[OpenCL]], [[Vulkan]], [[VA-API]] and [[VDPAU]] support (although this is also supported by the open-source driver). For some workloads it provides better performance than the open-source driver ([https://www.phoronix.com/scan.php?page=news_item&px=AMDGPU-PRO-16.40-Deus-MD example benchmark]), while for others the contrary is true ([https://openbenchmarking.org/prospect/1610315-TA-AMDGPUPRO08/998ba9b677230564e0fbca342a8e1b9a7e85b6ab example benchmark]).<br />
<br />
See the [https://support.amd.com/en-us/kb-articles/Pages/AMDGPU-PRO-Driver-for-Linux-Release-Notes.aspx release notes] and the [https://www.phoronix.com/forums/forum/linux-graphics-x-org-drivers/amd-linux/855699-amd-representative-says-their-vulkan-linux-driver-will-be-here-soon/page6 announcement at the Phoronix forum] for more information.<br />
<br />
A patched version of the official AMDGPU PRO driver is available as {{AUR|amdgpu-pro}}.<br />
<br />
== Loading ==<br />
<br />
The {{ic|amdgpu}} kernel module should load fine automatically on system boot.<br />
<br />
If it does not happen, then:<br />
<br />
* Make sure to [[#Enable Southern Islands (SI) and Sea Islands (CIK) support]] when needed.<br />
* Make sure you have the latest {{Pkg|linux-firmware}} package installed. This driver requires the latest firmware for each model to successfully boot.<br />
* Make sure you do '''not''' have {{ic|nomodeset}} or {{ic|1=vga=}} as a [[kernel parameter]], since {{ic|amdgpu}} requires [[KMS]].<br />
* Check that you have not disabled {{ic|amdgpu}} by using any [[Kernel_modules#Blacklisting|kernel module blacklisting]].<br />
<br />
=== Enable early KMS ===<br />
See [[Kernel mode setting#Early KMS start]].<br />
<br />
== Xorg configuration ==<br />
<br />
[[Xorg]] will automatically load the driver and it will use your monitor's EDID to set the native resolution. Configuration is only required for tuning the driver.<br />
<br />
If you want manual configuration, create {{ic|/etc/X11/xorg.conf.d/20-amdgpu.conf}}, and add the following:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/20-amdgpu.conf|2=<br />
Section "Device"<br />
Identifier "AMD"<br />
Driver "amdgpu"<br />
EndSection<br />
}}<br />
<br />
Using this section, you can enable features and tweak the driver settings, see {{man|4|amdgpu}} first before setting driver options.<br />
<br />
=== Tear Free Rendering ===<br />
''TearFree'' controls tearing prevention using the hardware page flipping mechanism. If this option is set, the default value of the property is 'on' or 'off' accordingly. If this option isn't set, the default value of the property is auto, which means that TearFree is on for rotated outputs, outputs with RandR transforms applied and for RandR 1.4 slave outputs, otherwise off:<br />
<br />
Option "TearFree" "true"<br />
<br />
=== DRI level ===<br />
<br />
''DRI'' sets the maximum level of DRI to enable. Valid values are ''2'' for DRI2 or ''3'' for DRI3. The default is ''3'' for DRI3 if the [[Xorg]] version is >= 1.18.3, otherwise DRI2 is used:<br />
<br />
Option "DRI" "3" <br />
<br />
== Features ==<br />
=== Video acceleration ===<br />
<br />
See [[Hardware video acceleration]].<br />
<br />
=== Overclocking ===<br />
<br />
Since Linux 4.17, it is possible to adjust clocks and voltages of the graphics card via {{Ic|1=/sys/class/drm/card0/device/pp_od_clk_voltage}}. It is however required to unlock access to it in sysfs by appending the boot parameter {{Ic|1=amdgpu.ppfeaturemask=0xffffffff}}.<br />
<br />
{{Note|In sysfs, paths like {{Ic|1=/sys/class/drm/...}} are just symlinks and may change between reboots. Persistent locations can be found in {{Ic|1=/sys/devices/}}, e.g. {{Ic|1=/sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0/}}. Adjust the commands accordingly for a reliable result.}}<br />
<br />
To set the GPU clock for the maximum pstate 7 on e.g. a Polaris GPU to 1209MHz and 900mV voltage, run:<br />
# echo "s 7 1209 900" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
The same procedure can be applied to the VRAM, e.g. maximum pstate 2 on Polaris 5xx series cards:<br />
# echo "m 2 1850 850" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
{{Warning|1=Double check the entered values, as mistakes might instantly cause fatal hardware damage!}}<br />
To apply, run<br />
# echo "c" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
To check if it worked out, read out clocks and voltage under 3D load:<br />
# watch -n 0.5 cat /sys/kernel/debug/dri/0/amdgpu_pm_info<br />
You can reset to the default values using this:<br />
# echo "r" > /sys/class/drm/card0/device/pp_od_clk_voltage<br />
<br />
It is also possible to forbid the driver so switch to certain pstates, e.g. to workaround problems with deep powersaving pstates like flickering artifacts or stutter. To force the highest VRAM pstate on a Polaris RX 5xx card, while still allowing the GPU itself to run with lower clocks, run:<br />
# echo "manual" > /sys/class/drm/card0/device/power_dpm_force_performance_level<br />
# echo "2" > /sys/class/drm/card0/device/pp_dpm_mclk<br />
Allow only the three highest GPU pstates:<br />
# echo "5 6 7" > /sys/class/drm/card0/device/pp_dpm_sclk<br />
<br />
To set the allowed maximum power consumption of the GPU to e.g. 50 Watts, run<br />
# echo 50000000 > /sys/class/drm/card0/device/hwmon/hwmon0/power1_cap<br />
Until Linux kernel 4.20, it will only be possible to decrease the value, not increase.<br />
<br />
{{Note|The above procedure was tested with a Polaris RX 560 card. There may be different behavior or bugs with different GPUs.}}<br />
<br />
=== Enable GPU display scaling ===<br />
<br />
{{Move|xrandr|Not specific to AMDGPU.|section=Moving "Enable GPU display scaling" to xrandr}}<br />
<br />
To avoid the usage of the scaler which is built in the display, and use the GPU own scaler instead, when not using the native resolution of the monitor, execute:<br />
$ xrandr --output "<output>" --set "scaling mode" "<scaling mode>"<br />
Possible values for {{ic|"scaling mode"}} are: {{ic|None, Full, Center, Full aspect}}<br />
<br />
* To show the available outputs and settings, execute:<br />
$ xrandr --prop<br />
<br />
* To set {{ic|1=scaling mode = Full aspect}} for just every available output, execute:<br />
$ for output in $(xrandr --prop | grep -E -o -i "^[A-Z\-]+-[0-9]+"); do xrandr --output "$output" --set "scaling mode" "Full aspect"; done<br />
<br />
== Troubleshooting ==<br />
<br />
=== Xorg or applications won't start ===<br />
<br />
* "(EE) AMDGPU(0): [DRI2] DRI2SwapBuffers: drawable has no back or front?" error after opening glxgears, can open Xorg server but OpenGL apps crash.<br />
* "(EE) AMDGPU(0): Given depth (32) is not supported by amdgpu driver" error, Xorg won't start.<br />
<br />
Setting the screen's depth under Xorg to 16 or 32 will cause problems/crash. To avoid that, you should use a standard screen depth of 24 by adding this to your "screen" section:<br />
<br />
{{hc|/etc/X11/xorg.conf.d/10-screen.conf|<br />
Section "Screen"<br />
Identifier "Screen"<br />
DefaultDepth 24<br />
SubSection "Display"<br />
Depth 24<br />
EndSubSection<br />
EndSection<br />
}}<br />
<br />
=== Screen artifacts and frequency problem ===<br />
<br />
[[ATI#Dynamic power management|Dynamic power management]] may cause screen artifacts to appear when displaying to monitors at higher frequencies (120+Hz) due to issues in the way GPU clock speeds are managed[https://bugs.freedesktop.org/show_bug.cgi?id=96868][https://bugs.freedesktop.org/show_bug.cgi?id=102646].<br />
<br />
A workaround [https://bugs.freedesktop.org/show_bug.cgi?id=96868#c13] is saving {{ic|high}} or {{ic|low}} in {{ic|/sys/class/drm/card0/device/power_dpm_force_performance_level}}.<br />
<br />
There is also a GUI solution [https://github.com/marazmista/radeon-profile] where you can manage the "power_dpm" with {{aur|radeon-profile-git}} and {{aur|radeon-profile-daemon-git}}.<br />
<br />
=== R9 390 series Poor Performance and/or Instability ===<br />
<br />
If you experience issues [https://bugs.freedesktop.org/show_bug.cgi?id=91880] with a AMD R9 390 series graphics card, set {{ic|1=radeon.cik_support=0 radeon.si_support=0 amdgpu.cik_support=1 amdgpu.si_support=1 amdgpu.dpm=1 amdgpu.dc=1}} as [[kernel parameters]] to force the use of amdgpu driver instead of radeon.<br />
<br />
If it still does not work, try disabling DPM, by setting the [[kernel parameters]] to: {{ic|1=radeon.cik_support=0 radeon.si_support=0 amdgpu.cik_support=1 amdgpu.si_support=1}}<br />
<br />
=== Freezes with "[drm] IP block:gmc_v8_0 is hung!" kernel error ===<br />
<br />
If you experience freezes and kernel crashes during a GPU intensive task with the kernel error " [drm] IP block:gmc_v8_0 is hung!" [https://bugs.freedesktop.org/show_bug.cgi?id=102322], a workaround is to set {{ic|1=amdgpu.vm_update_mode=3}} as [[kernel parameters]] to force the GPUVM page tables update to be done using the CPU. Downsides are listed here [https://bugs.freedesktop.org/show_bug.cgi?id=102322#c15].<br />
<br />
=== Cursor corruption ===<br />
<br />
If you experience issues with the mouse cursor sometimes not rendering properly, set {{ic|Option "SWCursor" "True"}} in the {{ic|"Device"}} section of the {{ic|/etc/X11/xorg.conf.d/20-amdgpu.conf}} configuration file.</div>Nahanthttps://wiki.archlinux.org/index.php?title=Arch_build_system&diff=536799Arch build system2018-08-22T16:50:39Z<p>Nahant: Fixed typo</p>
<hr />
<div>[[Category:About Arch]]<br />
[[Category:Package development]]<br />
[[Category:Package management]]<br />
[[cs:Arch Build System]]<br />
[[da:Arch Build System]]<br />
[[de:Arch Build System]]<br />
[[el:Arch Build System]]<br />
[[es:Arch Build System]]<br />
[[fr:ABS]]<br />
[[it:Arch Build System]]<br />
[[ja:Arch Build System]]<br />
[[ko:Arch Build System]]<br />
[[pl:Arch Build System]]<br />
[[pt:Arch Build System]]<br />
[[ro:ABS]]<br />
[[ru:Arch Build System]]<br />
[[zh-hans:Arch Build System]]<br />
[[zh-hant:Arch Build System]]<br />
{{Related articles start}}<br />
{{Related|Arch packaging standards}}<br />
{{Related|Arch User Repository}}<br />
{{Related|Creating packages}}<br />
{{Related|Kernel Compilation with ABS}}<br />
{{Related|makepkg}}<br />
{{Related|Official repositories}}<br />
{{Related|pacman}}<br />
{{Related|PKGBUILD}}<br />
{{Related|Patching in ABS}}<br />
{{Related articles end}}<br />
<br />
This article provides an overview of the Arch Build System (ABS) along with a walkthrough for beginners. It is not intended to be a complete reference guide.<br />
<br />
== What is the Arch Build System? ==<br />
<br />
The Arch Build System is a ''ports-like'' system for building and packaging software from source code. While [[pacman]] is the specialized Arch tool for binary package management (including packages built with the ABS), ABS is a collection of tools for compiling source into installable {{ic|.pkg.tar.xz}} packages.<br />
<br />
=== What is a ports-like system? ===<br />
<br />
''Ports'' is a system used by *BSD to automate the process of building software from source code. The system uses a ''port'' to download, unpack, patch, compile, and install the given software. A ''port'' is merely a small directory on the user's computer, named after the corresponding software to be installed, that contains a few files with the instructions for building and installing the software from source. This makes installing software as simple as typing {{ic|make}} or {{ic|make install clean}} within the port's directory.<br />
<br />
=== ABS is a similar concept ===<br />
<br />
ABS is made up of a directory tree that can be checked out using SVN. This tree represents, but does not contain, all official Arch software. Subdirectories do not contain the software package nor the source but rather a [[PKGBUILD]] file and sometimes other files. By issuing [[makepkg]] inside a directory containing a PKGBUILD, the software is first compiled and then packaged within the build directory. Then you can use [[pacman]] to install or upgrade your new package.<br />
<br />
=== ABS overview ===<br />
<br />
'ABS' may be used as an umbrella term since it includes and relies on several other components; therefore, though not technically accurate, 'ABS' can refer to the following tools as a complete toolkit:<br />
<br />
; SVN tree: The directory structure containing files needed to build all official packages but not the packages themselves nor the source files of the software. It is available in [https://www.archlinux.org/svn/ svn] and [https://projects.archlinux.org/svntogit/packages.git/ git] repositories.<br />
<br />
; [[PKGBUILD]]: A [[Bash]] script that contains the URL of the source code along with the compilation and packaging instructions.<br />
<br />
; [[makepkg]]: shell command tool which reads the PKGBUILDs, automatically downloads and compiles the sources and creates a {{ic|.pkg.tar*}} according to the {{ic|PKGEXT}} array in {{ic|makepkg.conf}}. You may also use makepkg to make your own custom packages from the [[AUR]] or third-party sources. See [[Creating packages]] for more information.<br />
<br />
; [[pacman]]: pacman is completely separate, but is necessarily invoked either by makepkg or manually, to install and remove the built packages and for fetching dependencies.<br />
<br />
; [[AUR]]: The Arch User Repository is separate from ABS but AUR (unsupported) PKGBUILDs are built using makepkg to compile and package up software. In contrast to the ABS tree on your local machine, the AUR exists as a website interface. It contains many thousands of user-contributed PKGBUILDs for software which is unavailable as an official Arch package. If you need to build a package outside the official Arch tree, chances are it is in the AUR.<br />
<br />
{{Warning|Official PKGBUILDs assume that packages are [[DeveloperWiki:Building_in_a_Clean_Chroot|built in a clean chroot]]. Building software on a ''dirty'' build system may fail or cause unexpected behaviour at runtime, because if the build system detects dependencies dynamically, the result depends on what packages are available on the build system.}}<br />
<br />
==== SVN tree ====<br />
<br />
The ''core'', ''extra'', and ''testing'' [[repositories]] are in the ''packages'' SVN repository for [[#Non-recursive checkout|checkout]]. The ''community'' and ''multilib'' repositories are in the ''community'' SVN repository. <br />
<br />
Each package has its own subdirectory. Within it there are {{ic|repos}} and {{ic|trunk}} directories. {{ic|repos}} is further broken down by repository name (e.g., ''core'') and architecture. PKGBUILD's and files found in {{ic|repos}} are used in official builds. Files found in {{ic|trunk}} are used by developers in preparation before being copied to {{ic|repos}}.<br />
<br />
For example, the tree for {{pkg|acl}} looks like this:<br />
<br />
acl<br />
acl/repos<br />
acl/repos/core-i686<br />
acl/repos/core-i686/PKGBUILD<br />
acl/repos/core-x86_64<br />
acl/repos/core-x86_64/PKGBUILD<br />
acl/trunk<br />
acl/trunk/PKGBUILD<br />
<br />
The source code for the package is not present in the ABS directory. Instead, the {{ic|PKGBUILD}} contains a URL that will download the source code when the package is built.<br />
<br />
== Why would I want to use ABS? ==<br />
<br />
The Arch Build System is used to:<br />
* Compile or recompile a package, for any reason<br />
* Make and install new packages from source of software for which no packages are yet available (see [[Creating packages]]) <br />
* Customize existing packages to fit your needs (enabling or disabling options, patching)<br />
* Rebuild your entire system using your compiler flags, "à la FreeBSD" (e.g. with {{AUR|pacbuilder-svn}} (not available anymore) or {{AUR|pacman-src-git}})<br />
* Cleanly build and install your own custom kernel (see [[Kernels#Compilation|Kernel compilation]])<br />
* Get kernel modules working with your custom kernel<br />
* Easily compile and install a newer, older, beta, or development version of an Arch package by editing the version number in the PKGBUILD<br />
<br />
ABS is not necessary to use Arch Linux, but it is useful for automating certain tasks of source compilation.<br />
<br />
== How to use ABS ==<br />
<br />
To retrieve the [[PKGBUILD]] required to build a certain package from source, you can either use [[Svn]] or a [[Git]]-based approach using the {{pkg|asp}} package which is a thin wrapper around the svntogit repositories. In the following, the svn-based method as well as the [[#Retrieve PKGBUILD source using Git|git-based method]] is described.<br />
<br />
=== Retrieve PKGBUILD source using Svn ===<br />
<br />
==== Prerequisites ====<br />
<br />
[[Install]] the {{Pkg|subversion}} package.<br />
<br />
==== Non-recursive checkout ====<br />
<br />
{{Warning|Do not download the whole repository; only follow the instructions below. The entire SVN repository is huge. Not only will it take an obscene amount of disk space, but it will also tax the archlinux.org server for you to download it. If you abuse this service, your address may be blocked. Never use the public SVN for any sort of scripting.}}<br />
<br />
To checkout the ''core'', ''extra'', and ''testing'' [[repositories]]:<br />
<br />
$ svn checkout --depth=empty <nowiki>svn://svn.archlinux.org/packages</nowiki><br />
<br />
To checkout the ''community'' and ''multilib'' repositories:<br />
<br />
$ svn checkout --depth=empty <nowiki>svn://svn.archlinux.org/community</nowiki><br />
<br />
In both cases, it simply creates an empty directory, but it does know that it is an svn checkout.<br />
<br />
==== Checkout a package ====<br />
<br />
In the directory containing the svn repository you checked out (i.e., ''packages'' or ''community''), do:<br />
<br />
$ svn update ''package-name''<br />
<br />
This will pull the package you requested into your checkout. From now on, any time you ''svn update'' at the top level, this will be updated as well.<br />
<br />
If you specify a package that does not exist, svn will not warn you. It will just print something like "At revision 115847", without creating any files. If that happens:<br />
* check your spelling of the package name<br />
* check that the package has not been moved to another repository (i.e. from community to the main repository)<br />
* check https://www.archlinux.org/packages to see if the package is built from another base package (for example, {{Pkg|python-tensorflow}} is built from the {{Pkg|tensorflow}} PKGBUILD)<br />
<br />
{{Tip|To checkout an older version of a package, see [[#Checkout an older version of a package]].}}<br />
<br />
You should periodically update all of your checked out packages if you wish to perform rebuilds on more recent revisions of the repositories. To do so, do:<br />
<br />
$ svn update<br />
<br />
=== Retrieve PKGBUILD source using Git ===<br />
<br />
As a precondition, [[install]] the {{Pkg|asp}} package.<br />
<br />
To clone the svntogit-repository for a specific package, use:<br />
$ asp checkout ''pkgname''<br />
<br />
This will clone the git repository for the given package into a directory named like the package.<br />
<br />
To update the cloned git repository, run {{ic|asp update}} followed by {{ic|git pull}} inside the git repository.<br />
<br />
Furthermore, you can use all other git commands to checkout an older version of the package or to track custom changes. For more information on git usage, see the [[git]] page.<br />
<br />
If you just want to copy a snapshot of the current [[PKGBUILD]] for a specific package, use:<br />
$ asp export ''pkgname''<br />
<br />
=== Build package ===<br />
<br />
See [[makepkg#Configuration]] on how to configure ''makepkg'' for building packages from the [[PKGBUILD]]'s you have checked out.<br />
<br />
Then, copy the directory containing the [[PKGBUILD]] you wish to modify to a new location. There, make the desired modifications and use ''makepkg'' there as described in [[makepkg#Usage]] to create and install the new package.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Preserve modified packages ===<br />
<br />
Updating the system with pacman will replace a modified package from ABS with the package of the same name from the official repositories. See the following instructions for how to avoid this.<br />
<br />
Insert a group array into the PKGBUILD, and add the package to a group called {{ic|modified}}.<br />
<br />
{{hc|PKGBUILD|2=<br />
groups=('modified')<br />
}}<br />
<br />
Add this group to the section {{ic|IgnoreGroup}} in {{ic|/etc/pacman.conf}}.<br />
<br />
{{hc|/etc/pacman.conf|2=<br />
IgnoreGroup = modified<br />
}}<br />
<br />
If new versions are available in the official repositories during a system update, pacman prints a note that it is skipping this update because it is in the IgnoreGroup section. At this point the modified package should be rebuilt from ABS to avoid partial upgrades.<br />
<br />
=== Checkout an older version of a package ===<br />
<br />
Within the svn repository you checked out as described in [[#Non-recursive checkout]] (i.e. "packages" or "community"), first examine the log:<br />
<br />
$ svn log ''package-name''<br />
<br />
Find out the revision you want by examining the history, then specify the revision you wish to checkout. For example, to checkout revision {{ic|r1729}} you would do:<br />
<br />
$ svn update -r1729 ''package-name''<br />
<br />
This will update an existing working copy of ''package-name'' to the chosen revision.<br />
<br />
You can also specify a date. If no revision on that day exists, svn will grab the most recent package before that time. The following example checks out the revision from 2009-03-03:<br />
<br />
$ svn update -r'{20090303}' ''package-name''<br />
<br />
It is possible to checkout packages at versions before they were moved to another repository as well; check the logs thoroughly for the date they were moved or the last revision number.<br />
<br />
== Other tools ==<br />
<br />
* [http://xyne.archlinux.ca/projects/pbget/ pbget] - retrieve PKGBUILDs for individual packages directly from the web interface. Includes AUR support.<br />
* [https://github.com/falconindy/asp asp] - a tool to manage the build source files used to create Arch Linux packages. Uses the git interface which offers more up to date sources.</div>Nahanthttps://wiki.archlinux.org/index.php?title=Kernel/Traditional_compilation&diff=532923Kernel/Traditional compilation2018-08-09T07:33:12Z<p>Nahant: Updated make dependencies to 4.17.13</p>
<hr />
<div>[[Category:Kernel]]<br />
[[fr:Compiler un nouveau noyau]]<br />
[[it:Kernels/Compilation/Traditional]]<br />
[[ja:カーネル/コンパイル/伝統的な方法]]<br />
[[ru:Kernels/Compilation/Traditional]]<br />
[[zh-hans:Kernels/Compilation/Traditional]]<br />
This article is an introduction to building custom kernels from '''kernel.org sources'''. This method of compiling kernels is the traditional method common to all distributions. It can be, depending on your background, more complicated than using the [[Kernels/Arch Build System]]. Consider the [[Arch Build System]] tools are developed and maintained to make repeatable compilation tasks efficient and safe.<br />
<br />
== Preparation ==<br />
<br />
It is not necessary (or recommended) to use the root account or root privileges (i.e. via [[Sudo]]) for kernel preparation.<br />
<br />
=== Install the core packages ===<br />
<br />
Install the {{Grp|base-devel}} package group, which contains necessary packages such as {{Pkg|make}} and {{Pkg|gcc}}. It is also recommended to install the following packages, as listed in the default Arch kernel [https://projects.archlinux.org/svntogit/packages.git/tree/trunk/PKGBUILD?h=packages/linux PKGBUILD]: {{Pkg|xmlto}}, {{Pkg|kmod}}, {{Pkg|inetutils}}, {{Pkg|bc}}, {{Pkg|libelf}}, {{Pkg|git}}<br />
<br />
=== Create a kernel compilation directory ===<br />
<br />
It is recommended to create a separate build directory for your kernel(s). In this example, the directory {{ic|kernelbuild}} will be created in the {{ic|home}} directory:<br />
<br />
$ mkdir ~/kernelbuild<br />
<br />
=== Download the kernel source ===<br />
<br />
{{Warning| [[systemd]] requires kernel version 3.12 at least (4.2 or greater for unified [[cgroups]] hierarchy support). See {{ic|/usr/share/doc/systemd/README}} for more information.}}<br />
<br />
Download the kernel source from https://www.kernel.org. This should be the [[wikipedia:Tar (computing)|tarball]] ({{ic|tar.xz}}) file for your chosen kernel. <br />
<br />
It can be downloaded by simply right-clicking the {{ic|tar.xz}} link in your browser and selecting {{ic|Save Link As...}}, or any other number of ways via alternative graphical or command-line tools that utilise HTTP, [[Ftp#FTP|FTP]], [[Rsync|RSYNC]], or [[Git]]. <br />
<br />
{{Note| It is a good idea to verify the PGP signature of any downloaded kernel tarball. This ensures that it is legitimate and helps to build the Web of Trust. See [https://kernel.org/signature.html#using-gnupg-to-verify-kernel-signatures kernel.org/signature].}}<br />
<br />
In the following command-line example, {{Pkg|wget}} has been installed and is used inside the {{ic|~/kernelbuild}} directory to obtain kernel 4.8.6:<br />
<br />
$ cd ~/kernelbuild<br />
$ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.8.6.tar.xz<br />
<br />
If {{ic|wget}} was not used inside the build directory, it will be necessary to move the tarball into it, e.g.<br />
<br />
$ mv /path/to/linux-4.8.6.tar.xz ~/kernelbuild/<br />
<br />
=== Unpack the kernel source ===<br />
<br />
Within the build directory, unpack the kernel tarball:<br />
<br />
$ tar -xvJf linux-4.8.6.tar.xz<br />
<br />
To finalise the preparation, ensure that the kernel tree is absolutely clean; do not rely on the source tree being clean after unpacking. To do so, first change into the new kernel source directory created, and then run the {{ic|make mrproper}} command:<br />
<br />
$ cd linux-4.8.6/<br />
$ make clean && make mrproper<br />
<br />
== Configuration ==<br />
<br />
This is the most crucial step in customizing the default kernel to reflect your computer's precise specifications. Kernel configuration is set in its {{ic|.config}} file, which includes the use of [[Kernel modules]]. <br />
<br />
{{Note| It is not necessary to use the root account or root privileges at this stage.}}<br />
<br />
By setting the options in {{ic|.config}} properly, your kernel and computer will function most efficiently. <br />
<br />
=== Kernel configuration ===<br />
<br />
You can choose from two options to set your kernel configuration:<br />
* A. Use the default Arch settings from an official kernel (recommended)<br />
* B. Generate a configuration file which matches the currently running kernel's configuration. (useful if you want to customize your kernel settings further)<br />
<br />
{{Note| Especially if you choose option **B**, you will be prompted to manually configure your kernel with tools described in {{ic|Advanced Configuration}}.}} <br />
<br />
==== A. Default Arch configuration ====<br />
<br />
This method will create a {{ic|.config}} file for the custom kernel using the default Arch kernel settings. Ensure that a stock Arch kernel is running and use the following command inside the custom kernel source directory:<br />
<br />
$ zcat /proc/config.gz > .config<br />
<br />
{{Warning|If you are compiling a kernel using your current {{ic|.config}} file, do not forget to rename your kernel version "CONFIG_LOCALVERSION" in the new .config or in the {{ic| General Setup --->}} option using one of the user interfaces listed under Advanced Configuration. If you skip this, there is the risk of overwriting one of your existing kernels by mistake.}}<br />
<br />
==== B. Generated configuration ====<br />
<br />
{{tip|Plug in all devices that you expect to use on the system if using this method.}}<br />
<br />
Since kernel 2.6.32, the {{ic|localmodconfig}} command will create a {{ic|.config}} file for the custom kernel by disabling any and all options not currently in use by the running kernel ''at the time''. In other words, it will only enable the options currently being used.<br />
<br />
While this minimalist approach will result in a highly streamlined and efficient configuration tailored specifically for your system, there are drawbacks, such as the potential inability of the kernel to support newer hardware, peripherals, or other features. <br />
<br />
{{Note|Again, ensure that all devices you expect to use have been connected to (and detected by) your system before running the following command}}<br />
<br />
$ make localmodconfig<br />
<br />
=== Advanced configuration ===<br />
<br />
{{Tip|Unless you want to see a lot of extra messages when booting and shutting down with the custom kernel, it is a good idea to deactivate the relevant debugging options.}}<br />
<br />
There are several tools available to fine-tune the kernel configuration, which provide an alternative to otherwise spending hours manually configuring each and every one of the options available during compilation. <br />
<br />
{{Note| Those tools listed below will provide you with three configuration options for each kernel feature: {{ic|y}} for enabled, {{ic|n}} for disabled, and {{ic|m}} for enabled as kernel module (loaded when necessary).}}<br />
<br />
Those tools are:<br />
* {{ic|make menuconfig}}: Command-line ncurses interface superseded by {{ic|nconfig}}<br />
* {{ic|make nconfig}}: Newer ncurses interface for the command-line<br />
* {{ic|make xconfig}}: User-friendly graphical interface that requires {{Pkg|packagekit-qt5}} to be installed as a dependency. This is the recommended method - especially for less experienced users - as it is easier to navigate, and information about each option is also displayed.<br />
* {{ic|make gconfig}}: Graphical configuration similar to xconfig but using gtk.<br />
<br />
The chosen method should be run inside the kernel source directory, and all will either create a new {{ic|.config}} file, or overwrite an existing one where present. All optional configurations will be automatically enabled, although any newer configuration options (i.e. with an older kernel {{ic|.config}}) may not be automatically selected.<br />
<br />
Once the changes have been made save the {{ic|.config}} file. It is a good idea to make a backup copy outside the source directory. You may need to do this multiple times before you get all the options right. <br />
<br />
If unsure, only change a few options between compilations. If you cannot boot your newly built kernel, see the list of necessary config items [https://www.archlinux.org/news/users-of-unofficial-kernels-must-enable-devtmpfs-support/ here]. <br />
<br />
Running {{ic|$ lspci -k #}} from liveCD lists names of kernel modules in use. Most importantly, you must maintain CGROUPS support. This is necessary for [[systemd]].<br />
<br />
== Compilation and installation ==<br />
{{Tip|If you want to have {{Pkg|gcc}} optimize for your processor's instruction sets, edit {{ic|arch/x86/Makefile}} (both for 32 and 64 bits, see [https://lkml.org/lkml/2007/7/20/447]) within the kernel source directory:<br />
* Look for {{ic|CONFIG_MK8,CONFIG_MPSC,CONFIG_MCORE2,CONFIG_MATOM,CONFIG_GENERIC_CPU}} that you have chosen in {{ic|Processor type and features > Processor Family}}<br />
* Change the call cc-options flag from {{ic|-march<nowiki>=</nowiki>native}} to the one that you have selected in Processor Family, e.g. {{ic|cflags-$(CONFIG_MK8) +<nowiki>=</nowiki> $(call cc-option,-march<nowiki>=</nowiki>native)}}. This is probably the best way to compile with {{ic|-march<nowiki>=</nowiki>native}} as it works.<br />
<br />
* Note: For 32bit Kernels, you need to edit {{ic|arch/x86/Makefile_32.cpu}} instead and set {{ic|-march<nowiki>=</nowiki>native}} for your processor.}}<br />
<br />
=== Compile the kernel ===<br />
<br />
Compilation time will vary from as little as fifteen minutes to over an hour, depending on your kernel configuration and processor capability. Once the {{ic|.config}} file has been set for the custom kernel, within the source directory run the following command to compile:<br />
<br />
$ make<br />
<br />
{{Tip|To compile faster, ''make'' can be run with the {{ic|-jX}} argument, where {{ic|X}} is an integer number of parallel jobs. The best results are often achieved using the number of CPU cores in the machine + 1; for example, with a 2-core processor run {{ic|make -j3}}. See [[Makepkg#Improving compile times]] for more information.}}<br />
<br />
=== Compile the modules ===<br />
{{warning|From this step onwards, commands must be either run as root or with root privileges. If not, they will fail.}}<br />
<br />
Once the kernel has been compiled, the modules for it must follow. As root or with root privileges, run the following command to do so:<br />
<br />
# make modules_install<br />
<br />
This will copy the compiled modules into {{ic|/lib/modules/<kernel version>-<config local version>}}. For example, for kernel version 4.8 installed above, they would be copied to {{ic|/lib/modules/4.8.6-ARCH}}. This keeps the modules for individual kernels used separated.<br />
<br />
{{Tip|If your system requires modules which are not distributed with the regular Linux kernel, you need to compile them for your custom kernel when it is finished. Such modules are typically those which you explicitly installed separately for your running system. See [[NVIDIA#Custom kernel]] for an example.}}<br />
<br />
=== Copy the kernel to /boot directory ===<br />
{{Note|Ensure that the {{ic|bzImage}} kernel file has been copied from the appropriate directory for your system architecture. See below.}}<br />
<br />
The kernel compilation process will generate a compressed {{ic|bzImage}} (big zImage) of that kernel, which must be copied to the {{ic|/boot}} directory and renamed in the process. Provided the name is prefixed with {{ic|vmlinuz-}}, you may name the kernel as you wish. In the examples below, the installed and compiled 4.8 kernel has been copied over and renamed to {{ic|vmlinuz-linux48}}:<br />
<br />
* 32-bit (i686) kernel:<br />
# cp -v arch/x86/boot/bzImage /boot/vmlinuz-linux48<br />
<br />
* 64-bit (x86_64) kernel:<br />
# cp -v arch/x86_64/boot/bzImage /boot/vmlinuz-linux48<br />
<br />
=== Make initial RAM disk ===<br />
{{Note|You are free to name the initramfs image file whatever you wish when generating it. However, it is recommended to use the {{ic|linux<major revision><minor revision>}} convention. For example, the name 'linux48' was given as '4' is the major revision and '8' is the minor revision of the 4.8 kernel. This convention will make it easier to maintain multiple kernels, regularly use mkinitcpio, and build third-party modules.}}<br />
<br />
{{Tip|If you are using the LILO bootloader and it cannot communicate with the kernel device-mapper driver, you have to run {{ic|modprobe dm-mod}} first.}}<br />
<br />
If you do not know what making an initial RAM disk is, see [[wikipedia:Initrd|Initramfs on Wikipedia]] and [[mkinitcpio]]. <br />
<br />
==== Automated preset method ====<br />
An existing [[Mkinitcpio#Image_creation_and_activation|mkinitcpio preset]] can be copied and modified so that the custom kernel initramfs images can be generated in the same way as for an official kernel. This is useful where intending to recompile the kernel (e.g. where updated). In the example below, the preset file for the stock Arch kernel will be copied and modified for kernel 4.8, installed above.<br />
<br />
First, copy the existing preset file, renaming it to match the name of the custom kernel specified as a suffix to {{ic|/boot/vmlinuz-}} when copying the {{ic|bzImage}} (in this case, {{ic|linux48}}):<br />
<br />
# cp /etc/mkinitcpio.d/linux.preset /etc/mkinitcpio.d/linux48.preset<br />
<br />
Second, edit the file and amend for the custom kernel. Note (again) that the {{ic|ALL_kver<nowiki>=</nowiki>}} parameter also matches the name of the custom kernel specified when copying the {{ic|bzImage}}:<br />
<br />
{{hc|/etc/mkinitcpio.d/linux48.preset|<br />
...<br />
ALL_kver<nowiki>=</nowiki>"/boot/vmlinuz-linux48"<br />
...<br />
default_image<nowiki>=</nowiki>"/boot/initramfs-linux48.img"<br />
...<br />
fallback_image<nowiki>=</nowiki>"/boot/initramfs-linux48-fallback.img"}}<br />
<br />
Finally, generate the initramfs images for the custom kernel in the same way as for an official kernel:<br />
<br />
# mkinitcpio -p linux48<br />
<br />
==== Manual method ====<br />
Rather than use a preset file, mkinitcpio can also be used to generate an initramfs file manually. The syntax of the command is:<br />
<br />
# mkinitcpio -k <kernelversion> -g /boot/initramfs-<file name>.img<br />
<br />
* {{ic|-k}} (--kernel <kernelversion>): Specifies the modules to use when generating the initramfs image. The {{ic|<kernelversion>}} name will be the same as the name of the custom kernel source directory (and the modules directory for it, located in {{ic|/usr/lib/modules/}}).<br />
* {{ic|-g}} (--generate <filename>): Specifies the name of the initramfs file to generate in the {{ic|/boot}} directory. Again, using the naming convention mentioned above is recommended.<br />
<br />
For example, the command for the 4.8 custom kernel installed above would be:<br />
<br />
# mkinitcpio -k linux-4.8.6 -g /boot/initramfs-linux48.img<br />
<br />
=== Copy System.map ===<br />
The {{ic|System.map}} file is not required for booting Linux. It is a type of "phone directory" list of functions in a particular build of a kernel. The {{ic|System.map}} contains a list of kernel symbols (i.e function names, variable names etc) and their corresponding addresses. This "symbol-name to address mapping" is used by:<br />
<br />
* Some processes like klogd, ksymoops etc<br />
* By OOPS handler when information has to be dumped to the screen during a kernel crash (i.e info like in which function it has crashed).<br />
<br />
{{Tip| UEFI partitions are formatted using FAT32, which does not support symlinks.}}<br />
<br />
If your {{ic|/boot}} is on a filesystem which supports symlinks (i.e., not FAT32), copy {{ic|System.map}} to {{ic|/boot}}, appending your kernel's name to the destination file. Then create a symlink from {{ic|/boot/System.map}} to point to {{ic|/boot/System.map-YourKernelName}}:<br />
# cp System.map /boot/System.map-YourKernelName<br />
# ln -sf /boot/System.map-YourKernelName /boot/System.map<br />
<br />
After completing all steps above, you should have the following 3 files and 1 soft symlink in your {{ic|/boot}} directory along with any other previously existing files:<br />
* Kernel: {{ic|vmlinuz-YourKernelName}}<br />
* Initramfs: {{ic|Initramfs-YourKernelName.img}}<br />
* System Map: {{ic|System.map-YourKernelName}}<br />
* System Map kernel symlink<br />
<br />
== Bootloader configuration ==<br />
<br />
Add an entry for your new kernel in your bootloader's configuration file - see [[GRUB]], [[LILO]], [[GRUB2]], [[Syslinux]], [[systemd-boot]] or [[REFInd]] for examples. <br />
<br />
{{Tip| Kernel sources include a script to automate the process for LILO: {{ic|$ arch/x86/boot/install.sh}}. Remember to type {{ic|lilo}} as root at the prompt to update it.}}</div>Nahanthttps://wiki.archlinux.org/index.php?title=Gaming&diff=461669Gaming2017-01-06T10:25:39Z<p>Nahant: Fixed typo</p>
<hr />
<div>[[Category:Gaming]]<br />
[[da:List of games]]<br />
[[es:List of games]]<br />
[[it:List of games]]<br />
[[ja:ゲーム]]<br />
[[lt:Games]]<br />
[[ru:Gaming]]<br />
[[zh-cn:List of games]]<br />
{{Related articles start}}<br />
{{Related|List of games}}<br />
{{Related|Xorg}}<br />
{{Related articles end}}<br />
<br />
This page only contains information about running games and related system configuration tips. For lists of popular games for GNU/Linux see [[List of games]].<br />
<br />
== Game environments ==<br />
<br />
Different environments exist to play games in Linux:<br />
<br />
* Native &ndash; Games written for Linux.<br />
* Browser &ndash; you need only browser and Internet connection to play these types of games.<br />
** HTML5 games use canvas and WebGL technologies and work in all modern browsers but can be slow on weak machines.<br />
** Plugin-based &ndash; you need to install plugin to play.<br />
*** [[Java]] Webstart &ndash; used to install cross-platform games very easily.<br />
*** [[Flash]] games are very common on the Web.<br />
* Specialized environments (software emulators) &ndash; &ndash; Required for running software designed for other architectures or systems, (Heed the copyright laws of your country!). Check the [[List of applications/Other#Emulators|list of emulators]] for more details.<br />
** [[Wine]] &ndash; allows running of some Windows games, as well as a large amount of Windows software. Performance in Wine varies, the additional CPU overhead will cause slowdown in some games while in some cases games may run faster. Consult [http://appdb.winehq.org/ Wine AppDB] for game-specific compatibility information.<br />
** [http://www.codeweavers.com/ Crossover Games] &ndash; members of the Codeweavers team are prime supporters of Wine. Using Crossover Games makes the installation & setting up of some games easier, more reliable & even possible, when compared to using other methods. Crossover is a paid commercial product, which also provides a [http://www.codeweavers.com/support/forums/ forum] where the developers are very much involved in the community. <br />
** [[DOSBox]] is a minimal virtual machine which runs a full DOS-compatible environment. It can be used to run classic DOS titles.<br />
** {{Pkg|scummvm}} is an all-in-one engine reimplementation of many classic point-and-click adventure games. A full list of compatible titles can be found on the [http://scummvm.org ScummVM website].<br />
** Similar to ScummVM, engine reimplementations exist for specific titles, such as Doom.<br />
* Virtual machines can be used to install compatible operating systems (such as Windows). [[VirtualBox]] has good 3D support. As an extension of this, if you have compatible hardware you can consider VGA passthrough to a Windows KVM guest.<br />
<br />
== Getting games ==<br />
<br />
=== Native ===<br />
<br />
A good number are available in the [[official repositories]] or in the [[AUR]]. [http://liflg.org/ Loki] provides installers for several games.<br />
<br />
=== Digital distribution ===<br />
<br />
* {{App|[[Wikipedia:Desura|Desura]]|Digital distribution platform featuring indie games. It can be considered good source of games (if you do not care about security and bugs too much).<br />
|http://www.desura.com/|{{AUR|desura}}}}<br />
<br />
* {{App|[[Steam]]|Famous digital distribution and communications platform developed by Valve. It has a large library with over 1000 Linux games. These include popular titles like Dota 2, Counter Strike: Global Offensive, Team Fortress 2, several AAA games, and lots of indie titles.<br />
|http://store.steampowered.com|{{Pkg|steam}}}}<br />
::*[http://developer.valvesoftware.com/wiki/Steam_under_Linux Steam under Linux.]<br />
::*[http://store.steampowered.com/browse/linux/ See linux-games catalog.]<br />
::*Not all Steam titles are native, some are packaged to run using Wine.<br />
<br />
* The [https://www.humblebundle.com/store Humble Store]<br />
<br />
* [https://itch.io/ itch.io]|{{AUR|itch}}<br />
<br />
* [http://www.gog.com/games/linux GOG.com]<br />
::*The {{AUR|lgogdownloader}} package can be used to download GOG titles from the command line.<br />
::*GOG.com only officially supports Ubuntu and Linux Mint. Bear this in mind if requesting support from them; you will not get a refund if you are having trouble running games on Arch.<br />
::*Many GOG.com titles come pre-packaged with DOSBox, ScummVM or Wine.<br />
<br />
=== Flash ===<br />
{{Note|The official Adobe Flash Player for Linux with NPAPI-based browsers is stuck at major version 11, whereas the current (as of August 25, 2015) major version is 18. An up-to-date Adobe Flash Player is, however, obtainable on Linux with PPAPI-based browsers. Please see [[wikipedia:Adobe Flash Player#Desktop platforms]] for more info. If you do not wish to install Chrome, however, there is an even more potent option to use the Windows version of Flash; see http://community.linuxmint.com/tutorial/view/2028 for details.}}<br />
<br />
Several huge Flash games portals exists, among them are:<br />
* https://armorgames.com/<br />
* https://www.kongregate.com/<br />
* https://www.newgrounds.com/<br />
<br />
=== Java ===<br />
<br />
* Lots of games smaller than 4kb (some are real masterpieces of game design) can be found at http://www.java4k.com.<br />
* https://www.pogo.com/ &ndash; biggest casual Java gaming portal<br />
* [http://www.javagametome.com/ The Java Game Tome] - huge database of primarily casual games<br />
<br />
=== Wine ===<br />
<br />
* Centralized source of information about running games (and other applications) in [[Wine]] is [http://appdb.winehq.org/ Wine AppDB].<br />
* See also [[:Category:Wine]].<br />
<br />
It is recommended (especially for beginners) to use {{Pkg|playonlinux}}, which pulls all necessary dependencies during installation, automatically downloads Windows tools at first start-up to configure and set-up native windows applications to launch properly. For more information, see [https://www.playonlinux.com/en/ Official Website].<br />
<br />
== Running games ==<br />
<br />
Certain games or game types may need special configuration to run or to run as expected.<br />
For the most part, games will work right out of the box in Arch Linux with possibly better performance than on other distributions due to compile time optimizations. However, some special setups may require a bit of configuration or scripting to make games run as smoothly as desired.<br />
<br />
=== Multi-screen setups ===<br />
<br />
Running a multi-screen setup may lead to problems with fullscreen games. In such a case, [[#Starting games in a separate X server|running a second X server]] is one possible solution. Another solution may be found in the [[NVIDIA#Gaming using TwinView|NVIDIA article]] (may also apply to non-NVIDIA users).<br />
<br />
=== Keyboard grabbing ===<br />
<br />
Many games grab the keyboard, noticeably preventing you from switching windows (also known as alt-tabbing).<br />
<br />
Some SDL games (e.g. Guacamelee) let you disable grabbing by pressing {{ic|Ctrl-g}}.<br />
<br />
You can also download {{AUR|sdl-nokeyboardgrab}}{{Broken package link|{{aur-mirror|sdl-nokeyboardgrab}}}} to gain the ability to use keyboard commands while in SDL games. If you wish to turn it up to 11, you can disable keyboard grabbing at X11 level using {{AUR|libx11-nokeyboardgrab}}, or with more fine-grained control with {{AUR|libx11-ldpreloadnograb}}{{Broken package link|{{aur-mirror|libx11-ldpreloadnograb}}}} using the {{ic|LD_PRELOAD}} environment variable to run applications with particular grab prevention. Wine/lib32 users should also look at the respective lib32 libraries.<br />
<br />
{{Note|SDL is known to sometimes not be able to grab the input system. In such a case, it may succeed in grabbing it after a few seconds of waiting.}}<br />
<br />
=== Starting games in a separate X server ===<br />
<br />
In some cases like those mentioned above, it may be necessary or desired to run a second X server. Running a second X server has multiple advantages such as better performance, the ability to "tab" out of your game by using {{ic|Ctrl+Alt+F7}}/{{ic|Ctrl+Alt+F8}}, no crashing your primary X session (which may have open work on) in case a game conflicts with the graphics driver. The new X server will be akin a remote access login for the ALSA, so your user need to be part of the {{ic|audio}} group to be able to hear any sound.<br />
<br />
To start a second X server (using [http://www.xonotic.org/ Xonotic] as an example) you can simply do: <br />
$ xinit /usr/bin/xonotic-glx -- :1 vt$XDG_VTNR<br />
This can further be spiced up by using a separate X configuration file:<br />
$ xinit /usr/bin/xonotic-glx -- :1 -xf86config xorg-game.conf vt$XDG_VTNR<br />
A good reason to provide an alternative ''xorg.conf'' here may be that your primary configuration makes use of NVIDIA's Twinview which would render your 3D games like Xonotic in the middle of your multiscreen setup, spanned across all screens. This is undesirable, thus starting a second X with an alternative config where the second screen is disabled is advised.<br />
<br />
A game starting script making use of Openbox for your home directory or {{ic|/usr/local/bin}} may look like this:<br />
{{hc|~/game.sh|<nowiki><br />
if [ $# -ge 1 ]; then<br />
game="$(which $1)"<br />
openbox="$(which openbox)"<br />
tmpgame="/tmp/tmpgame.sh"<br />
DISPLAY=:1.0<br />
echo -e "${openbox} &\n${game}" > ${tmpgame}<br />
echo "starting ${game}"<br />
xinit ${tmpgame} -- :1 -xf86config xorg-game.conf || exit 1<br />
else<br />
echo "not a valid argument"<br />
fi<br />
</nowiki>}}<br />
<br />
So after a {{ic|chmod +x}} you would be able to use this script like:<br />
$ ~/game.sh xonotic-glx<br />
<br />
=== Adjusting mouse detections ===<br />
<br />
For games that require exceptional amount of mouse skill, adjusting the [[mouse polling rate]] can help improve accuracy.<br />
<br />
=== Mouse focus in GNOME ===<br />
<br />
{{Merge|GNOME}}<br />
<br />
The 'sloppy' and 'mouse' window-focusing modes in [[GNOME]] are known to cause issues with a variety of games, causing a 'click-through' effect. Users can remedy this problem by switching the focus mode to 'click' (with a tool such as {{Pkg|gnome-tweak-tool}}), playing in a different desktop environment, or spawing their game in a separate X-session.<br />
<br />
=== Binaural Audio with OpenAL ===<br />
<br />
For games using [[Wikipedia:OpenAL|OpenAL]], if you use headphones you may get much better positional audio using OpenAL's [[Wikipedia:Head-related transfer function|HRTF]] filters. To enable, run the following command:<br />
<br />
echo "hrtf = true" >> ~/.alsoftrc<br />
<br />
Alternatively, install {{AUR|openal-hrtf}} from the AUR, and edit the options in /etc/openal/alsoftrc.conf<br />
<br />
For Source games, the ingame setting `dsp_slow_cpu` must be set to `1` to enable HRTF, otherwise the game will enable its own processing instead. You will also either need to set up Steam to use native runtime, or link its copy of openal.so to your own local copy. For completeness, also use the following options:<br />
<br />
dsp_slow_cpu 1 # Disable in-game spatialiazation<br />
snd_spatialize_roundrobin 1 # Disable spatialization 1.0*100% of sounds<br />
dsp_enhance_stereo 0 # Disable DSP sound effects. You may want to leave this on, if you find it does not interfere with your perception of the sound effects.<br />
snd_pitchquality 1 # Use high quality sounds<br />
<br />
=== Tuning Pulseaudio ===<br />
<br />
If you are using [[PulseAudio]], you may wish to tweak some default settings to make sure it is running optimally.<br />
<br />
==== Enabling realtime priority and negative nice level ====<br />
<br />
Pulseaudio is built to be run with realtime priority, being an audio daemon. However, because of security risks of it locking up the system, it is scheduled as a regular thread by default. To adjust this, first make sure you are in the {{ic|audio}} group. Then, uncomment and edit the following lines in {{ic|/etc/pulse/daemon.conf}}:<br />
high-priority = yes<br />
nice-level = -11<br />
<br />
realtime-scheduling = yes<br />
realtime-priority = 5<br />
and restart pulseaudio.<br />
<br />
==== Using higher quality remixing for better sound ====<br />
<br />
Pulseaudio on Arch uses speex-float-0 by default to remix channels, which is considered a 'medium-low' quality remixing. If your system can handle the extra load, you may benefit from setting it to one of the following instead:<br />
resample-method = speex-float-10<br />
<br />
==== Matching hardware buffers to Pulse's buffering ====<br />
<br />
Matching the buffers can reduce stuttering and increase performance marginally. See [http://forums.linuxmint.com/viewtopic.php?f=42&t=44862 here] for more details.<br />
<br />
=== Double check your CPU frequency scaling settings ===<br />
<br />
If your system is currently configured to properly insert its own cpu frequency scaling driver, the system sets the default governor to Ondemand. By default, this governor only adjusts the clock if the system is utilizing 95% of its CPU, and then only for a very short period of time. This saves power and reduces heat, but has a noticeable impact on performance. You can instead only have the system downclock when it is idle, by tuning the system governor. To do so, see [[Cpufrequtils#Improving on-demand performance]]{{Broken section link}}.<br />
<br />
== Improving framerates and responsiveness with scheduling policies ==<br />
Most every game can benefit if given the correct scheduling policies for the kernel to prioritize the task. However, without the help of a daemon, this rescheduling would have to be carried out manually or through the use of several daemons for each policy. These policies should ideally be set per-thread by the application itself, but not all developers implement these policies. There are several methods for getting them to work anyway:<br />
<br />
=== For Wine programs ===<br />
<br />
{{AUR|wine-rt}} is a patched version of Wine that implements scheduling policies on a per-thread basis, using the equivalent of what the Windows developers had intended the threads to be run at. The default patch is more oriented towards professional audio users, and tends to be too heavy-handed of an approach for gaming. You may instead wish to use [http://pastebin.com/D9GBzBBv this patch], which also includes nice levels and uses more than one policy decision. Be warned that it uses {{ic|SCHED_ISO}}, which is only properly implemented on [[Linux-ck]], and will simply renice {{ic|THREAD_PRIORITY_ABOVE_NORMAL}} threads if your system does not support it.<br />
<br />
{{Pkg|wine-staging}} versions 1.9.5 and before incorporate the CSMT patchset which provides better performance for 3D accelerated games. The patchset has been disabled as of 1.9.6 pending an upstream update to the patch and incorporation into the main Wine source tree, so you will need to compile version 1.9.5 of wine-staging yourself if you wish to take advantage of this.<br />
<br />
=== For everything else ===<br />
<br />
For programs which do not implement scheduling policies on their own, one tool known as '''schedtool''', and its associated daemon {{AUR|schedtoold}} can handle many of these tasks automatically.<br />
To edit what programs relieve what policies, simply edit {{ic|/etc/schedtoold.conf}} and add the program followed by the ''schedtool'' arguments desired.<br />
<br />
==== Policies ====<br />
<br />
First and foremost, setting the scheduling policy to {{ic|SCHED_ISO}} will not only allow the process to use a maximum of 80 percent of the CPU, but will attempt to reduce latency and stuttering wherever possible. <br />
{{ic|SCHED_ISO}} requires [[Linux-ck]] to operate, as it has only been implemented in that kernel. [[Linux-ck]] itself provides a hefty latency reduction, and should ideally be installed <br />
Most if not all games will benefit from this:<br />
bit.trip.runner -I<br />
For users not using [[Linux-ck]], {{ic|SCHED_FIFO}} provides an alternative, that can even work better. You should test to see if your applications run more smoothly with {{ic|SCHED_FIFO}}, in which case by all means use it instead. Be warned though, as {{ic|SCHED_FIFO}} runs the risk of starving the system! Use this in cases where -I is used below:<br />
bit.trip.runner -F -p 15<br />
<br />
==== Nice levels ====<br />
<br />
Secondly, the nice level sets which tasks are processed first, in ascending order. A nice level of -4 is reccommended for most multimedia tasks, including games:<br />
bit.trip.runner -n -4<br />
<br />
==== Core affinity ====<br />
<br />
There is some confusion in development as to whether the driver should be multithreading, or the program. In any case where they both attempt it, it causes drops in framerate and crashes. Examples of this include a number of modern games, and any Wine program which is running without [[Wikipedia:OpenGL Shading Language|GLSL]] disabled. To select a single core and allow only the driver to handle this process, simply use the {{ic|-a 0x''#''}} flag, where ''#'' is the core number, e.g.: <br />
bit.trip.runner -a 0x1<br />
uses first core.<br />
Some CPUs are hyperthreaded and have only 2 or 4 cores but show up as 4 or 8, and are best accounted for:<br />
bit.trip.runner -a 0x5<br />
which use virtual cores 0101, or 1 and 3.<br />
<br />
==== General case ====<br />
<br />
For most games which require high framerates and low latency, usage of all of these flags seems to work best. Affinity should be checked per-program, however, as most native games can understand the correct usage.<br />
For a general case:<br />
bit.trip.runner -I -n -4<br />
Amnesia.bin64 -I -n -4<br />
hl2.exe -I -n -4 -a 0x1 #Wine with GLSL enabled<br />
etc.<br />
<br />
==== Optimus, and other helping programs ====<br />
<br />
As a general rule, any other process which the game requires to operate should be reniced to a level above that of the game itself. Strangely, Wine has a problem known as ''reverse scheduling'', it can often have benefits when the more important processes are set to a higher nice level. Wineserver also seems unconditionally to benefit from {{ic|SCHED_FIFO}}, since rarely consumes the whole CPU and needs higher prioritization when possible.<br />
optirun -I -n -5<br />
wineserver -F -p 20 -n 19<br />
steam.exe -I -n -5<br />
<br />
== Using alternate kernels ==<br />
<br />
{{Note|Many users report inconsistant framerate and other performance hits when using [[Linux-ck]], even if the overall framerate is sometimes higher. You may wish to try using {{Pkg|linux-zen}} if you just want BFQ.}}<br />
<br />
The stock Arch kernel provides a very good baseline for general usage. However, if your system has less than 16 cores and is intended for use primarily as a workstation, you can sacrifice a small amount of throughput on batch workloads and gain a significant boost to interactivity by using [[Linux-ck]]. If you prefer not to compile your own kernel, you can instead add [[Repo-ck]] and use one of their kernels. Using a pre-optimized kernel will most definitely offset any loss of throughput that may have occurred as a result, so be sure to select the appropriate kernel for your architecture. <br />
<br />
=== Using BFQ ===<br />
<br />
BFQ is an io-scheduler that comes as a feature of {{Pkg|linux-zen}} and [[Linux-ck]], and is optimized to be much more simplistic, but provides better interactivity and throughput for non-server workloads. To enable, simply add the kernel parameter ''elevator=bfq'' to your [[bootloader]]. It is important to note that although most guides recommend using either ''noop'' or ''deadline'' for SSDs for their raw throughput, they are actually detrimental to interactivity when more than one thread is attempting to access the device. It is best to use ''bfq'' unless you desperately need the throughput advantage.<br />
<br />
== See also ==<br />
<br />
* [http://www.linuxgames.com/ LinuxGames] - News on linux games<br />
* [http://osgameclones.com/ OSGameClones] - List of open source game clones<br />
* [http://freegamer.blogspot.com/ Free Gamer] - Open source games blog<br />
* [http://forum.freegamedev.net/ FreeGameDev] - Free/open source game development community<br />
* [https://fedoraproject.org/wiki/SIGs/Games#Gaming_News_sites SIG/Games] - OS/Linux gaming news sites and lists at Fedora's wiki<br />
* [http://live.linux-gamers.net live.linux-gamers] - Arch-based live gaming distro<br />
* [http://www.gamingonlinux.com/ Gaming on Linux] - Active Linux gaming news and editorial source and community<br />
* [https://unixgames.org/ Unixgames] - Q&A service for Linux gamers.</div>Nahanthttps://wiki.archlinux.org/index.php?title=SDDM&diff=461668SDDM2017-01-06T10:21:22Z<p>Nahant: Fixed typo</p>
<hr />
<div>[[Category:KDE]]<br />
[[Category:Display managers]]<br />
[[ja:SDDM]]<br />
[[ru:SDDM]]<br />
[[zh-CN:SDDM]]<br />
{{Related articles start}}<br />
{{Related|Display manager}}<br />
{{Related|KDE}}<br />
{{Related articles end}}<br />
The [[Wikipedia:Simple Desktop Display Manager|Simple Desktop Display Manager]] (SDDM) is the preferred [[display manager]] for [[KDE]] Plasma desktop. From Wikipedia:<br />
<br />
:''Simple Desktop Display Manager (SDDM) is a display manager (a graphical login program) for X11. SDDM was written from scratch in C++11 and supports theming via QML. It is the successor of the KDE Display Manager and is used in conjunction with KDE Frameworks 5, KDE Plasma 5 and KDE Applications 5.''<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|sddm}} package.<br />
<br />
Then follow [[Display manager#Loading the display manager]] to start SDDM at boot.<br />
<br />
== Configuration ==<br />
<br />
The configuration file for SDDM can be found at {{ic|/etc/sddm.conf}}. See {{man|5|sddm.conf|url=}} for all options.<br />
<br />
On systems controlled by [[systemd]], everything should work out of the box, since SDDM defaults to using {{ic|systemd-logind}} for session management. The configuration file will therefore not be created at package installation time. SDDM offers a command for generating a sample configuration file with the default settings if you really want one:<br />
<br />
# sddm --example-config > /etc/sddm.conf<br />
<br />
=== Autologin ===<br />
<br />
SDDM supports automatic login through its configuration file, for example:<br />
<br />
{{hc|<br />
1=/etc/sddm.conf|<br />
2=[Autologin]<br />
User=john<br />
Session=plasma.desktop<br />
}}<br />
<br />
This configuration causes a KDE Plasma session to be started for user {{ic|john}} when the system is booted. Available session types can be found in {{ic|/usr/share/xsessions/}} directory.<br />
<br />
An option to autologin into KDE Plasma while simultaneously locking the session is not available [https://github.com/sddm/sddm/issues/306]<br />
<br />
You can add a script that activates the screensaver of KDE to the autostart as a workaround:<br />
<br />
#!/bin/bash<br />
/usr/bin/qdbus-qt4 org.kde.screensaver /ScreenSaver SetActive true &<br />
exit 0<br />
<br />
=== Unlock KDE Wallet automatically on login ===<br />
<br />
See [[KDE Wallet#Unlock KDE Wallet automatically on login]].<br />
<br />
=== Theme settings ===<br />
<br />
Theme settings can be changed in the {{ic|[Theme]}} section.<br />
<br />
Set to {{ic|breeze}} for the default Plasma theme.<br />
<br />
Some themes are available in the [[AUR]], for example {{AUR|archlinux-themes-sddm}}.<br />
<br />
==== Main theme ====<br />
<br />
Set the main theme through the {{ic|Current}} value, e.g. {{ic|1=Current=archlinux-simplyblack}}.<br />
<br />
==== Editing themes ====<br />
<br />
The default SDDM theme directory is {{ic|/usr/share/sddm/themes/}}. You can add your custom made themes to that directory under a separate subdirectory. Study the files installed to modify or create your own theme.<br />
<br />
==== Mouse cursor ====<br />
<br />
To set the mouse cursor theme, set {{ic|CursorTheme}} to your preferred cursor theme.<br />
<br />
Valid [[Plasma]] mouse cursor theme names are {{ic|breeze_cursors}}, {{ic|Breeze_Snow}} and {{ic|breeze-dark}}.<br />
<br />
==== Changing your avatar ====<br />
<br />
You can simply put a png image named {{ic|username.face.icon}} into the default directory {{ic|/usr/share/sddm/faces/}}. Alternatively you can change the default directory to match your desires:<br />
<br />
{{hc|/etc/sddm.conf|2=<br />
[Theme]<br />
FacesDir=/var/lib/AccountsService/icons/<br />
}}<br />
<br />
You can also put a png image named {{ic|.face.icon}} at the root of your home directory. However, you need to make sure that {{ic|sddm}} user can read that file.<br />
<br />
{{Note|If avatar images are symlinks, you need to set proper file permissions to the target files.}}<br />
<br />
=== Numlock ===<br />
<br />
If you want to enforce Numlock to be enabled, set {{ic|1=Numlock=on}} in the {{ic|[General]}} section.<br />
<br />
=== Rotate display ===<br />
<br />
See [[Xrandr#Configuration]].<br />
<br />
=== Configuration GUI ===<br />
<br />
* KDE Frameworks' System Settings contains an SDDM configuration module. Install {{Pkg|sddm-kcm}} package to use it.<br />
* There is a Qt-based {{AUR|sddm-config-editor-git}} in the AUR.<br />
<br />
=== DPI settings ===<br />
<br />
Sometimes it's useful to set up correct monitor's PPI settings on a "Display Manager" level. To do so you need to find "ServerArguments" parameter in sdd.conf and add -dpi %YOUR RESOLUTION at the end of the string. <br />
<br />
For example:<br />
<br />
{{hc|head=/etc/sddm.conf|output=ServerArguments=-nolisten tcp -dpi 94}}<br />
<br />
== Troubleshooting ==<br />
<br />
=== Hangs after login ===<br />
<br />
Try removing {{ic|~/.Xauthority}}.<br />
<br />
=== SDDM starts on tty1 instead of tty7 ===<br />
<br />
SDDM follows the [http://0pointer.de/blog/projects/serial-console.html systemd convention] of starting the first graphical session on tty1. If you prefer the old convention where tty1 through tty6 are reserved for text consoles, uncomment and edit the {{ic|MinimumVT}} variable, under the {{ic|[X11]}} section in {{ic|sddm.conf}}:<br />
<br />
{{hc|/etc/sddm.conf|2=<br />
[X11]<br />
...<br />
MinimumVT=7<br />
...<br />
}}<br />
<br />
=== One or more users do not show up on the greeter ===<br />
<br />
{{Warning|Users set with a lower or higher {{ic|UID}} range should generally not be exposed to a [[Display manager]].}}<br />
<br />
SDDM only displays users with a UID in the range of 1000 to 65000 by default, if the UIDs of the desired users are below this value then you will have to modify this range. Modify your {{ic|sddm.conf}} to (for a UID of 501, say):<br />
<br />
{{hc|/etc/sddm.conf|2=<br />
[Users]<br />
HideShells=/sbin/nologin,/bin/false<br />
# Hidden users, this is if any system users fall within your range, see /etc/passwd on your system.<br />
HideUsers=git,sddm,systemd-journal-remote,systemd-journal-upload<br />
<br />
# Maximum user id for displayed users<br />
MaximumUid=65000<br />
<br />
# Minimum user id for displayed users<br />
MinimumUid=500 #My UID is 501<br />
}}<br />
<br />
=== SDDM loads only US keyboard layout ===<br />
<br />
SDDM loads the keyboard layout specified in {{ic|/etc/X11/xorg.conf.d/00-keyboard.conf}}. You can generate this configuration file by {{ic|localectl set-x11-keymap}} command. See [[Keyboard configuration in Xorg]] for more information.<br />
<br />
=== No user Icon ===<br />
<br />
SDDM reads user icon from either {{ic|~/.face.icon}} or {{ic|''FacesDir''/username.face.icon}}<br />
<br />
You need to make sure that SDDM user have permissions to read those files.<br />
<br />
$ setfacl -m u:sddm:x /home/username<br />
$ setfacl -m u:sddm:r /home/username/.face.icon<br />
$ setfacl -m u:sddm:r /home/username/.face<br />
<br />
See [https://github.com/sgerbino/sddm#no-user-icon SDDM README: No User Icon].</div>Nahanthttps://wiki.archlinux.org/index.php?title=SSH_keys&diff=425352SSH keys2016-03-12T12:23:26Z<p>Nahant: Added information that PuTTY development snapshots support ECDSA.</p>
<hr />
<div>[[Category:Secure Shell]]<br />
[[es:SSH keys]]<br />
[[it:SSH keys]]<br />
[[ja:SSH 鍵]]<br />
[[ru:SSH keys]]<br />
[[sr:SSH keys]]<br />
[[tr:SSH Anahtarları]]<br />
[[zh-cn:SSH keys]]<br />
SSH keys serve as a means of identifying yourself to an SSH server using [[Wikipedia:Public-key cryptography|public-key cryptography]] and [[Wikipedia:Challenge-response authentication|challenge-response authentication]]. One immediate advantage this method has over traditional password authentication is that you can be authenticated by the server without ever having to send your password over the network. Anyone eavesdropping on your connection will not be able to intercept and crack your password because it is never actually transmitted. Additionally, using SSH keys for authentication virtually eliminates the risk posed by brute-force password attacks by drastically reducing the chances of the attacker correctly guessing the proper credentials.<br />
<br />
As well as offering additional security, SSH key authentication can be more convenient than the more traditional password authentication. When used with a program known as an SSH agent, SSH keys can allow you to connect to a server, or multiple servers, without having to remember or enter your password for each system.<br />
<br />
SSH keys are not without their drawbacks and may not be appropriate for all environments, but in many circumstances they can offer some strong advantages. A general understanding of how SSH keys work will help you decide how and when to use them to meet your needs. This article assumes you already have a basic understanding of the [[Secure Shell]] protocol and have [[Install|installed]] the {{Pkg|openssh}} package.<br />
<br />
==Background==<br />
SSH keys are always generated in pairs with one known as the private key and the other as the public key. The private key is known only to you and it should be safely guarded. By contrast, the public key can be shared freely with any SSH server to which you wish to connect.<br />
<br />
If a SSH server has your public key on file and sees you requesting a connection, it uses your public key to construct and send you a challenge. This challenge is an encrypted message and it must be met with the appropriate response before the server will grant you access. What makes this coded message particularly secure is that it can only be understood by the private key holder. While the public key can be used to encrypt the message, it cannot be used to decrypt that very same message. Only you, the holder of the private key, will be able to correctly understand the challenge and produce the proper response.<br />
<br />
This challenge-response phase happens behind the scenes and is invisible to the user. As long as you hold the private key, which is typically stored in the {{ic|~/.ssh/}} directory, your SSH client should be able to reply with the appropriate response to the server.<br />
<br />
A private key is a guarded secret and as such it is advisable to store it on disk in an encrypted form. When the encrypted private key is required, a passphrase must first be entered in order to decrypt it. While this might superficially appear as though you are providing a login password to the SSH server, the passphrase is only used to decrypt the private key on the local system. The passphrase is not be transmitted over the network.<br />
<br />
==Generating an SSH key pair==<br />
An SSH key pair can be generated by running the {{ic|ssh-keygen}} command, defaulting to 2048-bit RSA (and SHA256) which the man page says is "''generally considered sufficient''"[http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man1/ssh-keygen.1?query=ssh-keygen&sec=1] and should be compatible with virtually all clients and servers:<br />
<br />
{{hc<br />
|$ ssh-keygen<br />
|<nowiki>Generating public/private rsa key pair.<br />
Enter file in which to save the key (/home/<username>/.ssh/id_rsa): <br />
Enter passphrase (empty for no passphrase): <br />
Enter same passphrase again: <br />
Your identification has been saved in /home/<username>/.ssh/id_rsa.<br />
Your public key has been saved in /home/<username>/.ssh/id_rsa.pub.<br />
The key fingerprint is:<br />
SHA256:gGJtSsV8BM+7w018d39Ji57F8iO6c0N2GZq3/RY2NhI username@hostname<br />
The key's randomart image is:<br />
+---[RSA 2048]----+<br />
| ooo. |<br />
| oo+. |<br />
| + +.+ |<br />
| o + + E . |<br />
| . . S . . =.o|<br />
| . + . . B+@o|<br />
| + . oo*=O|<br />
| . ..+=o+|<br />
| o=ooo+|<br />
+----[SHA256]-----+</nowiki>}}<br />
<br />
The [http://www.cs.berkeley.edu/~dawnsong/papers/randomart.pdf randomart image] was [http://www.openssh.com/txt/release-5.1 introduced in OpenSSH 5.1] as an easier means of visually identifying the key fingerprint.<br />
<br />
You can also add an optional comment field to the public key with the {{ic|-C}} switch, to more easily identify it in places such as {{ic|~/.ssh/known_hosts}}, {{ic|~/.ssh/authorized_keys}} and {{ic|ssh-add -L}} output. For example:<br />
<br />
ssh-keygen -C "$(whoami)@$(hostname)-$(date -I)"<br />
<br />
will add a comment saying which user created the key on which machine and when.<br />
<br />
The {{ic|-o}} switch can also be used to save the private key in the new OpenSSH format, which has increased resistance to brute-force password cracking (but is not supported by versions of OpenSSH prior to 6.5). Use the {{ic|-a}} switch to specify the number of KDF rounds. Ed25519 keys always use the new private key format.<br />
<br />
===Choosing the type of encryption===<br />
<br />
OpenSSH supports several key exchange algorithms which can be divided in two groups depending on the mathematical properties they exploit:<br />
<br />
# [[Wikipedia:Digital_Signature_Algorithm|DSA]] and [[Wikipedia:RSA_(cryptosystem)|RSA]], which rely on the practical difficulty of factoring the product of two large prime numbers,<br />
# [[Wikipedia:Elliptic_Curve_Digital_Signature_Algorithm|ECDSA]] and [[Wikipedia:Curve25519|Ed25519]], which rely on the elliptic curve [[Wikipedia:Discrete_logarithm|discrete logarithm]] problem. ([https://www.certicom.com/index.php/52-the-elliptic-curve-discrete-logarithm-problem example])<br />
<br />
[https://blog.cloudflare.com/a-relatively-easy-to-understand-primer-on-elliptic-curve-cryptography/ Elliptic curve cryptography] (ECC) algorithms are a [[Wikipedia:Elliptic_curve_cryptography#History|more recent addition]] to public key cryptosystems. One of their main advantages is their ability to provide [[Wikipedia:Elliptic_curve_cryptography#Rationale|the same level of security with smaller keys]], which makes for less computationally intensive operations (''i.e.'' faster key creation and decryption) and reduced storage and transmission requirements.<br />
<br />
OpenSSH 7.0 [https://www.archlinux.org/news/openssh-70p1-deprecates-ssh-dss-keys/ deprecated and disabled support for DSA keys] due to discovered vulnerabilities, therefore the choice of [[Wikipedia:cryptosystem|cryptosystem]] lies within RSA or one of the two types of ECC.<br />
<br />
[[#RSA]] keys will give you the greatest portability, while [[#Ed25519]] will give you the best security but requires recent versions of client & server.[https://www.gentoo.org/support/news-items/2015-08-13-openssh-weak-keys.html] [[#ECDSA]] is likely more compatible than Ed25519 (though still less than RSA), but suspicions exist about its security (see below).<br />
<br />
{{Note|1=[[GNOME Keyring]] does not handle ECDSA[https://bugzilla.gnome.org/show_bug.cgi?id=641082] and Ed25519[https://bugzilla.gnome.org/show_bug.cgi?id=723274] keys. Users will have to turn to other [[#SSH agents|SSH agents]] or stick to RSA keys.}}<br />
<br />
{{Note|These keys are used only to authenticate you; choosing stronger keys will not increase CPU load when transferring data over SSH.}}<br />
<br />
==== RSA ====<br />
<br />
As said previously, ''ssh-keygen'' defaults to RSA therefore there is no need to specify it with the {{ic|-t}} option. It provides the best compatibility of all algorithms but requires the key size to be larger to provide sufficient security.<br />
<br />
Minimum key size is 1024 bits, default is 2048 (see {{ic|man ssh-keygen}}) and maximum is 16384:<br />
<br />
{{hc|$ ssh-keygen -b 32768|<br />
key bits exceeds maximum 16384}}<br />
<br />
If you wish to generate a stronger RSA key pair (''e.g.'' to guard against cutting-edge or unknown attacks and more sophisticated attackers), simply specify the {{ic|-b}} option with a higher bit value than the default:<br />
<br />
{{hc<br />
|$ ssh-keygen -b 4096<br />
|<nowiki>Generating public/private rsa key pair.<br />
Enter file in which to save the key (/home/<username>/.ssh/id_rsa):<br />
Enter passphrase (empty for no passphrase):<br />
Enter same passphrase again:<br />
Your identification has been saved in /home/<username>/.ssh/id_rsa.<br />
Your public key has been saved in /home/<username>/.ssh/id_rsa.pub.<br />
The key fingerprint is:<br />
SHA256:+Pqo84NC+vAQQ9lUV0z+/zPHsyCe8oZpy6hLkIa7qfk <username>@<hostname><br />
The key's randomart image is:<br />
+---[RSA 4096]----+<br />
| ... .+o |<br />
| + . .. |<br />
| o . . |<br />
|. . . . . |<br />
|o. + . S . |<br />
| o+ . . . |<br />
|o+ o . o. o . |<br />
|.=+ + .oo=..o o+o|<br />
|+=E..**+oo=+ o*|<br />
+----[SHA256]-----+</nowiki>}}<br />
<br />
Be aware though that there are diminishing returns in using longer keys.[https://security.stackexchange.com/a/25377][https://www.gnupg.org/faq/gnupg-faq.html#no_default_of_rsa4096] The GnuPG FAQ reads: "''If you need more security than RSA-2048 offers, the way to go would be to switch to elliptical curve cryptography — not to continue using RSA''".[https://www.gnupg.org/faq/gnupg-faq.html#please_use_ecc]<br />
<br />
On the other hand, the latest iteration of the [https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml NSA Fact Sheet Suite B Cryptography] suggests a minimum 3072-bit modulus for RSA while "''[preparing] for the upcoming quantum resistant algorithm transition''".[http://www.keylength.com/en/6/]<br />
<br />
==== ECDSA ====<br />
<br />
{{Note|The Windows SSH client PuTTY does not support ECDSA in its current releases. One needs a PuTTY development snapshot to connect to a server that uses only ECDSA keys.}}<br />
<br />
The Elliptic Curve Digital Signature Algorithm (ECDSA) was introduced as the preferred algorithm for authentication [http://www.openssh.com/txt/release-5.7 in OpenSSH 5.7]. Some vendors also disable the required implementations due to potential patent issues.<br />
<br />
There are two sorts of concerns with it:<br />
<br />
# ''Political concerns'', the trustworthiness of NIST-produced curves [https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters being questioned] after revelations that the NSA willingly inserts backdoors into softwares, hardware components and published standards were made; well-known cryptographers [https://www.schneier.com/blog/archives/2013/09/the_nsa_is_brea.html#c1675929 have] [http://safecurves.cr.yp.to/rigid.html expressed] [https://www.hyperelliptic.org/tanja/vortraege/20130531.pdf doubts] about how the NIST curves were designed, and voluntary tainting has already [https://www.schneier.com/blog/archives/2007/11/the_strange_sto.html been] [http://www.scientificamerican.com/article/nsa-nist-encryption-scandal/ proved] in the past.<br />
# ''Technical concerns'', about the [http://blog.cr.yp.to/20140323-ecdsa.html difficulty to properly implement the standard] and the [http://www.gossamer-threads.com/lists/openssh/dev/57162#57162 slowness and design flaws] which reduce security in insufficiently precautious implementations. <br />
<br />
Both of those concerns are best summarized in [https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt#n4 libssh curve25519 introduction]. Although the political concerns are still subject to debate, there is a [https://news.ycombinator.com/item?id=7597653 clear consensus] that [[#Ed25519]] is technically superior and should therefore be preferred.<br />
<br />
==== Ed25519 ====<br />
<br />
[http://ed25519.cr.yp.to/ Ed25519] was introduced in [http://www.openssh.com/txt/release-6.5 OpenSSH 6.5]: "''Ed25519 is an elliptic curve signature scheme that offers better security than ECDSA and DSA and good performance''". Its main strengths are its speed, its constant-time run time (and resistance against side-channel attacks), and its lack of nebulous hard-coded constants.[https://git.libssh.org/projects/libssh.git/tree/doc/curve25519-sha256@libssh.org.txt] See also [https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/ this blog post] by a Mozilla developer on how it works.<br />
<br />
It is already implemented in [[Wikipedia:Curve25519#Popularity|many applications and libraries]] and is the [https://www.libssh.org/2013/11/03/openssh-introduces-curve25519-sha256libssh-org-key-exchange/ default key exchange algorithm] (which is different from key ''signature'') in OpenSSH.<br />
<br />
Ed25519 key pairs can be generated with:<br />
<br />
ssh-keygen -t ed25519<br />
<br />
There is no need to set the key size, as all Ed25519 keys are 256 bits. Also, they rely on a [http://www.gossamer-threads.com/lists/openssh/dev/57162#57162 new key format] which "''uses a bcrypt-based key derivation function that makes brute-force attacks against stolen private keys far slower''".<br />
<br />
For those reasons, compatibility with older versions of OpenSSH or [[Ssh#Other_SSH_clients_and_servers|other SSH clients and servers]] may prove troublesome.<br />
<br />
===Choosing the key location and passphrase===<br />
Upon issuing the {{ic|ssh-keygen}} command, you will be prompted for the desired name and location of your private key. By default, keys are stored in the {{ic|~/.ssh/}} directory and named according to the type of encryption used. You are advised to accept the default name and location in order for later code examples in this article to work properly.<br />
<br />
When prompted for a passphrase, choose something that will be hard to guess if you have the security of your private key in mind. A longer, more random password will generally be stronger and harder to crack should it fall into the wrong hands.<br />
<br />
It is also possible to create your private key without a passphrase. While this can be convenient, you need to be aware of the associated risks. Without a passphrase, your private key will be stored on disk in an unencrypted form. Anyone who gains access to your private key file will then be able to assume your identity on any SSH server to which you connect using key-based authentication. Furthermore, without a passphrase, you must also trust the root user, as he can bypass file permissions and will be able to access your unencrypted private key file at any time.<br />
<br />
====Changing the private key's passphrase without changing the key====<br />
If the originally chosen SSH key passphrase is undesirable or must be changed, one can use the {{ic|ssh-keygen}} command to change the passphrase without changing the actual key.<br />
<br />
To change the passphrase for the private RSA key, run the following command:<br />
$ ssh-keygen -f ~/.ssh/id_rsa -p<br />
<br />
==== Managing multiple keys ====<br />
<br />
It is possible —although [http://security.stackexchange.com/questions/10963/whats-the-common-pragmatic-strategy-for-managing-key-pairs not considered best practice]— to use the same SSH key pair for multiple hosts.<br />
<br />
On the other hand, it is rather easy to maintain distinct keys for multiple hosts by using the {{ic|IdentityFile}} directive in your openSSH config file:<br />
<br />
{{hc|~/.ssh/config|<br />
Host SERVER1<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_rsa_SERVER1<br />
<br />
Host SERVER2<br />
IdentitiesOnly yes<br />
IdentityFile ~/.ssh/id_ed25519_SERVER2<br />
}}<br />
<br />
See {{ic|ssh_config(5)}} manual page for full description of these options.<br />
<br />
==Copying the public key to the remote server==<br />
Once you have generated a key pair, you will need to copy the public key to the remote server so that it will use SSH key authentication. The public key file shares the same name as the private key except that it is appended with a {{ic|.pub}} extension. Note that the private key is not shared and remains on the local machine.<br />
<br />
===Simple method===<br />
<br />
{{Note|1=This method might fail if the remote server uses a non-{{ic|sh}} shell such as {{ic|tcsh}} as default and uses OpenSSH older than 6.6.1p1. See [https://bugzilla.redhat.com/show_bug.cgi?id=1045191 this bug report].}}<br />
<br />
If your key file is {{ic|~/.ssh/id_rsa.pub}} you can simply enter the following command.<br />
$ ssh-copy-id remote-server.org<br />
<br />
If your username differs on remote machine, be sure to prepend the username followed by {{ic|@}} to the server name.<br />
$ ssh-copy-id username@remote-server.org<br />
<br />
If your public key filename is anything other than the default of {{ic|~/.ssh/id_rsa.pub}} you will get an error stating {{ic|/usr/bin/ssh-copy-id: ERROR: No identities found}}. In this case, you must explicitly provide the location of the public key.<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub username@remote-server.org<br />
<br />
If the ssh server is listening on a port other than default of 22, be sure to include it within the host argument.<br />
$ ssh-copy-id -i ~/.ssh/id_ed25519.pub -p 221 username@remote-server.org<br />
<br />
===Manual method===<br />
By default, for OpenSSH, the public key needs to be concatenated with {{ic|~/.ssh/authorized_keys}}. Begin by copying the public key to the remote server.<br />
<br />
$ scp ~/.ssh/id_ecdsa.pub username@remote-server.org:<br />
<br />
The above example copies the public key ({{ic|id_ecdsa.pub}}) to your home directory on the remote server via {{ic|scp}}. Do not forget to include the {{ic|:}} at the end of the server address. Also note that the name of your public key may differ from the example given.<br />
<br />
On the remote server, you will need to create the {{ic|~/.ssh}} directory if it does not yet exist and append your public key to the {{ic|authorized_keys}} file.<br />
<br />
$ ssh username@remote-server.org<br />
username@remote-server.org's password:<br />
$ mkdir ~/.ssh<br />
$ chmod 700 ~/.ssh<br />
$ cat ~/id_ecdsa.pub >> ~/.ssh/authorized_keys<br />
$ rm ~/id_ecdsa.pub<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
The last two commands remove the public key file from the server and set the permissions on the {{ic|authorized_keys}} file such that it is only readable and writable by you, the owner.<br />
<br />
==SSH agents==<br />
If your private key is encrypted with a passphrase, this passphrase must be entered every time you attempt to connect to an SSH server using public-key authentication. Each individual invocation of {{ic|ssh}} or {{ic|scp}} will need the passphrase in order to decrypt your private key before authentication can proceed.<br />
<br />
An SSH agent is a program which caches your decrypted private keys and provides them to SSH client programs on your behalf. In this arrangement, you must only provide your passphrase once, when adding your private key to the agent's cache. This facility can be of great convenience when making frequent SSH connections.<br />
<br />
An agent is typically configured to run automatically upon login and persist for the duration of your login session. A variety of agents, front-ends, and configurations exist to achieve this effect. This section provides an overview of a number of different solutions which can be adapted to meet your specific needs.<br />
<br />
===ssh-agent===<br />
{{ic|ssh-agent}} is the default agent included with OpenSSH. It can be used directly or serve as the back-end to a few of the front-end solutions mentioned later in this section. When {{ic|ssh-agent}} is run, it forks to background and prints necessary environment variables. E.g.<br />
<br />
{{hc|$ ssh-agent|2=<br />
SSH_AUTH_SOCK=/tmp/ssh-vEGjCM2147/agent.2147; export SSH_AUTH_SOCK;<br />
SSH_AGENT_PID=2148; export SSH_AGENT_PID;<br />
echo Agent pid 2148;<br />
}}<br />
<br />
To make use of these variables, run the command through the {{ic|eval}} command.<br />
<br />
{{hc|$ eval $(ssh-agent)|<br />
Agent pid 2157<br />
}}<br />
<br />
Once {{ic|ssh-agent}} is running, you will need to add your private key to its cache:<br />
<br />
{{hc|$ ssh-add ~/.ssh/id_ecdsa|<br />
Enter passphrase for /home/user/.ssh/id_ecdsa:<br />
Identity added: /home/user/.ssh/id_ecdsa (/home/user/.ssh/id_ecdsa)<br />
}}<br />
<br />
If your private key is encrypted, {{ic|ssh-add}} will prompt you to enter your passphrase. Once your private key has been successfully added to the agent you will be able to make SSH connections without having to enter your passphrase.<br />
<br />
In order to have all this happen automatically, and make sure that only one {{ic|ssh-agent}} process runs at a time, add the following to your {{ic|~/.bashrc}}:<br />
<br />
<nowiki>if ! pgrep -u $USER ssh-agent > /dev/null; then<br />
ssh-agent > ~/.ssh-agent-thing<br />
fi<br />
if [[ "$SSH_AGENT_PID" == "" ]]; then<br />
eval $(<~/.ssh-agent-thing)<br />
fi<br />
ssh-add -l >/dev/null || alias ssh='ssh-add -l >/dev/null || ssh-add && unalias ssh; ssh'</nowiki><br />
<br />
This will run a {{ic|ssh-agent}} process if there is not one already, and save the output thereof. If there is one running already, we retrieve the cached {{ic|ssh-agent}} output and evaluate it which will set the necessary environment variables. Also, if needed, we create an alias around {{ic|ssh}} to add the key to the agent, then remove the alias. One downside to this approach is that the key will not be added by commands that use the private key other than {{ic|ssh}}, such as {{ic|git}}.<br />
<br />
There also exist a number of front-ends to {{ic|ssh-agent}} and alternative agents described later in this section which avoid this problem.<br />
<br />
====Start ssh-agent with systemd user====<br />
<br />
It is possible to use the [[systemd/User]] facilities to start the agent.<br />
<br />
{{hc|~/.config/systemd/user/ssh-agent.service|<nowiki><br />
[Unit]<br />
Description=SSH key agent<br />
<br />
[Service]<br />
Type=forking<br />
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket<br />
ExecStart=/usr/bin/ssh-agent -a $SSH_AUTH_SOCK<br />
<br />
[Install]<br />
WantedBy=</nowiki>''default''.target<br />
}}<br />
<br />
Add {{ic|1=export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"}} to your shell's startup file, for example {{ic|.bash_profile}} for [[Bash]]. Then enable or start the service.<br />
<br />
====ssh-agent as a wrapper program====<br />
An alternative way to start ssh-agent (with, say, each X session) is described in [http://upc.lbl.gov/docs/user/sshagent.shtml this ssh-agent tutorial by UC Berkeley Labs]. A basic use case is if you normally begin X with the {{ic|startx}} command, you can instead prefix it with {{ic|ssh-agent}} like so:<br />
<br />
$ ssh-agent startx<br />
<br />
And so you do not even need to think about it you can put an alias in your {{ic|.bash_aliases}} file or equivalent:<br />
<br />
alias startx='ssh-agent startx'<br />
<br />
Doing it this way avoids the problem of having extraneous {{ic|ssh-agent}} instances floating around between login sessions. Exactly one instance will live and die with the entire X session.<br />
<br />
{{note|You can also add {{ic|eval $(ssh-agent)}} to {{ic|~/.xinitrc}}.}}<br />
<br />
See [[#Calling x11-ssh-askpass with ssh-add|the below notes on using x11-ssh-askpass with ssh-add]] for an idea on how to immediately add your key to the agent.<br />
<br />
===GnuPG Agent===<br />
<br />
The [[GnuPG#gpg-agent|gpg-agent]] has OpenSSH agent emulation. See [[GnuPG#SSH agent]] for necessary configuration.<br />
<br />
=== Keychain ===<br />
<br />
[http://www.funtoo.org/Keychain Keychain] is a program designed to help you easily manage your SSH keys with minimal user interaction. It is implemented as a shell script which drives both ''ssh-agent'' and ''ssh-add''. A notable feature of Keychain is that it can maintain a single ''ssh-agent'' process across multiple login sessions. This means that you only need to enter your passphrase once each time your local machine is booted.<br />
<br />
==== Installation ====<br />
<br />
[[Install]] the {{Pkg|keychain}} package available from the [[official repositories]].<br />
<br />
==== Configuration ====<br />
<br />
{{Warning|As of 2015-09-26, the {{ic|-Q, --quick}} option has the unexpected side-effect of making ''keychain'' switch to a newly-spawned ''ssh-agent'' upon relogin (at least on systems using [[GNOME]]), forcing you to re-add all the previously registered keys.}}<br />
<br />
Add a line similar to the following to your [[shell]] congifuration file, ''e.g.'' if using [[Bash]]:<br />
<br />
{{hc|~/.bashrc|<br />
eval $(keychain --eval --quiet id_ed25519 id_rsa ~/.keys/my_custom_key)<br />
}}<br />
<br />
{{Note|{{ic|~/.bashrc}} is used instead of the upstream suggested {{ic|~/.bash_profile}} because on Arch it is sourced by both login and non-login shells, making it suitable for textual and graphical environments alike. See [[Bash#Invocation]] for more information on the difference between those.}}<br />
<br />
In the above example,<br />
* the {{ic|--eval}} switch outputs lines to be evaluated by the opening {{ic|eval}} command; this sets the necessary environments variables for SSH client to be able to find your agent.<br />
* {{ic|--quiet}} will limit output to warnings, errors, and user prompts.<br />
<br />
Multiple keys can be specified on the command line, as shown in the example. By default keychain will look for key pairs in the {{ic|~/.ssh/}} directory, but absolute path can be used for keys in non-standard location. You may also use the {{ic|--confhost}} option to inform keychain to look in {{ic|~/.ssh/config}} for {{ic|IdentityFile}} settings defined for particular hosts, and use these paths to locate keys.<br />
<br />
See {{ic|keychain --help}} or {{ic|man keychain}} for details on setting ''keychain'' for other shells.<br />
<br />
To test Keychain, simply open a new terminal emulator or log out and back in your session. It should prompt you for the passphrase of the specified private key(s) (if applicable), either using the program set in {{ic|$SSH_ASKPASS}} or on the terminal.<br />
<br />
Because Keychain reuses the same ''ssh-agent'' process on successive logins, you should not have to enter your passphrase the next time you log in or open a new terminal. You will only be prompted for your passphrase once each time the machine is rebooted.<br />
<br />
==== Tips ====<br />
<br />
* ''keychain'' expects public key files to exist in the same directory as their private counterparts, with a {{ic|.pub}} extension. If the private key is a symlink, the public key can be found alongside the symlink or in the same directory as the symlink target (this capability requires the {{ic|readlink}} command to be available on the system).<br />
<br />
*to disable the graphical prompt and always enter your passphrase on the terminal, use the {{ic|--nogui}} option. This allows to copy-paste long passphrases from a password manager for example.<br />
<br />
*if you do not want to be immediately prompted for unlocking the keys but rather wait until they are needed, use the {{ic|--noask}} option.<br />
<br />
{{Note|Keychain is able to manage [[GPG]] keys in the same fashion. By default it attempts to start ''ssh-agent'' only, but you can modify this behavior using the {{ic|--agents}} option, ''e.g.'' {{ic|--agents ssh,gpg}}. See {{ic|man keychain}}.}}<br />
<br />
===envoy===<br />
<br />
An alternative to keychain is [https://github.com/vodik/envoy envoy]. Envoy is available as {{Pkg|envoy}} , or the Git version as {{AUR|envoy-git}}.<br />
<br />
After installing it, set up the envoy socket by [[enabling]] {{ic|envoy@ssh-agent.socket}}.<br />
<br />
And add to your shell's rc file:<br />
<br />
envoy -t ssh-agent -a ''ssh_key''<br />
source <(envoy -p)<br />
<br />
If this syntax for sourcing causes errors (in mksh, for example), you can replace it with:<br />
<br />
envoy -t ssh-agent -a ''ssh_key''<br />
eval "$(envoy -p)"<br />
<br />
If the key is {{ic|~/.ssh/id_rsa}}, {{ic|~/.ssh/id_dsa}}, {{ic|~/.ssh/id_ecdsa}}, or {{ic|~/.ssh/identity}}, the {{ic|-a ''ssh_key''}} parameter is not needed.<br />
<br />
====envoy with key passphrases stored in kwallet====<br />
<br />
If you have long passphrases for your SSH keys, remembering them can be a pain. So let us tell kwallet to store them!<br />
Along with {{Pkg|envoy}}, install {{Pkg|ksshaskpass}} and {{Pkg|kwalletmanager}} from the [[official repositories]]. Next, enable the envoy socket in systemd (see above).<br />
<br />
{{Note|As of April 30, 2015, if after installation {{Pkg|ksshaskpass}} keeps asking for access to your wallet even after having submitted the password, you might have [https://bbs.archlinux.org/viewtopic.php?id=192862 this] problem. The proposed solution is to install {{Aur|ksshaskpass4}}, though this might break your login.}}<br />
<br />
First, you will add this script to {{ic|~/.kde4/Autostart/ssh-agent.sh}}:<br />
#!/bin/sh<br />
envoy -t ssh-agent -a ''ssh_key''<br />
Then, make sure the script is executable by running: {{ic|chmod +x ~/.kde4/Autostart/ssh-agent.sh}}<br />
<br />
And add this to {{ic|~/.kde4/env/ssh-agent.sh}}:<br />
#!/bin/sh<br />
eval $(envoy -p)<br />
<br />
When you log into KDE, it will execute the {{ic|ssh-agent.sh}} script. This will call ''ksshaskpass'', which will prompt you for your kwallet password when envoy calls ''ssh-agent''.<br />
<br />
===x11-ssh-askpass===<br />
The {{pkg|x11-ssh-askpass}} package provides a graphical dialog for entering your passhrase when running an X session. ''x11-ssh-askpass'' depends only on the {{Pkg|libx11}} and {{Pkg|libxt}} libraries, and the appearance of ''x11-ssh-askpass'' is customizable. While it can be invoked by the ''ssh-add'' program, which will then load your decrypted keys into [[#ssh-agent|ssh-agent]], the following instructions will, instead, configure ''x11-ssh-askpass'' to be invoked by the aforementioned [[#Keychain|Keychain]] script.<br />
<br />
Install {{Pkg|keychain}} and {{Pkg|x11-ssh-askpass}}, both available in the [[official repositories]].<br />
<br />
Edit your {{ic|~/.xinitrc}} file to include the following lines, replacing the name and location of your private key if necessary. Be sure to place these commands '''before''' the line which invokes your window manager.<br />
<br />
{{hc|~/.xinitrc|<br />
keychain ~/.ssh/id_ecdsa<br />
[ -f ~/.keychain/$HOSTNAME-sh ] && . ~/.keychain/$HOSTNAME-sh 2>/dev/null<br />
[ -f ~/.keychain/$HOSTNAME-sh-gpg ] && . ~/.keychain/$HOSTNAME-sh-gpg 2>/dev/null<br />
...<br />
exec openbox-session}}<br />
<br />
In the above example, the first line invokes ''keychain'' and passes the name and location of your private key. If this is not the first time ''keychain'' was invoked, the following two lines load the contents of {{ic|$HOSTNAME-sh}} and {{ic|$HOSTNAME-sh-gpg}}, if they exist. These files store the environment variables of the previous instance of ''keychain''.<br />
<br />
====Calling x11-ssh-askpass with ssh-add====<br />
The ''ssh-add'' manual page specifies that, in addition to needing the {{ic|DISPLAY}} variable defined, you also need {{ic|SSH_ASKPASS}} set to the name of your askpass program (in this case ''x11-ssh-askpass''). It bears keeping in mind that the default Arch Linux installation places the ''x11-ssh-askpass'' binary in {{ic|/usr/lib/ssh/}}, which will not be in most people's {{ic|PATH}}. This is a little annoying, not only when declaring the {{ic|SSH_ASKPASS}} variable, but also when theming. You have to specify the full path everywhere. Both inconveniences can be solved simultaneously by symlinking:<br />
<br />
$ ln -sv /usr/lib/ssh/x11-ssh-askpass ~/bin/ssh-askpass<br />
<br />
This is assuming that {{ic|~/bin}} is in your {{ic|PATH}}. So now in your {{ic|.xinitrc}}, before calling your window manager, one just needs to export the {{ic|SSH_ASKPASS}} environment variable:<br />
<br />
$ export SSH_ASKPASS=ssh-askpass<br />
<br />
and your [[X resources]] will contain something like:<br />
<br />
ssh-askpass*background: #000000<br />
<br />
Doing it this way works well with [[#ssh-agent as a wrapper program|the above method on using ''ssh-agent'' as a wrapper program]]. You start X with {{ic|ssh-agent startx}} and then add ''ssh-add'' to your window manager's list of start-up programs.<br />
<br />
====Theming====<br />
The appearance of the ''x11-ssh-askpass'' dialog can be customized by setting its associated [[X resources]]. The ''x11-ssh-askpass'' [http://www.jmknoble.net/software/x11-ssh-askpass/ home page]{{Dead link|2015|04|01}} presents some [http://www.jmknoble.net/software/x11-ssh-askpass/screenshots.html example themes]{{Dead link|2015|04|01}}. See the ''x11-ssh-askpass'' manual page for full details.<br />
<br />
====Alternative passphrase dialogs====<br />
There are other passphrase dialog programs which can be used instead of ''x11-ssh-askpass''. The following list provides some alternative solutions.<br />
<br />
* {{Pkg|ksshaskpass}} is available in the official repositories. It is dependent on {{Pkg|kdelibs}} and is suitable for the [[KDE]] Desktop Environment.<br />
<br />
* {{Pkg|openssh-askpass}} depends on the {{Pkg|qt4}} libraries and is available from the official repositories.<br />
<br />
===pam_ssh===<br />
The [http://pam-ssh.sourceforge.net/ pam_ssh] project exists to provide a [[Wikipedia:Pluggable authentication module|Pluggable Authentication Module]] (PAM) for SSH private keys. This module can provide single sign-on behavior for your SSH connections. On login, your SSH private key passphrase can be entered in place of, or in addition to, your traditional system password. Once you have been authenticated, the pam_ssh module spawns ssh-agent to store your decrypted private key for the duration of the session.<br />
<br />
To enable single sign-on behavior at the tty login prompt, install the unofficial {{AUR|pam_ssh}} package, available in the [[Arch User Repository]]. <br />
<br />
{{Note|pam_ssh 2.0 now requires that all private keys used in the authentication process be located under {{ic|~/.ssh/login-keys.d/}}.}}<br />
<br />
Create a symlink to your private key file and place it in {{ic|~/.ssh/login-keys.d/}}. Replace the {{ic|id_rsa}} in the example below with the name of your own private key file.<br />
<br />
$ mkdir ~/.ssh/login-keys.d/<br />
$ cd ~/.ssh/login-keys.d/<br />
$ ln -s ../id_rsa<br />
<br />
Edit the {{ic|/etc/pam.d/login}} configuration file to include the text highlighted in bold in the example below. The order in which these lines appear is significiant and can affect login behavior.<br />
<br />
{{Warning|Misconfiguring PAM can leave the system in a state where all users become locked out. Before making any changes, you should have an understanding of how PAM configuration works as well as a backup means of accessing the PAM configuration files, such as an Arch Live CD, in case you become locked out and need to revert any changes. An IBM developerWorks [http://www.ibm.com/developerworks/linux/library/l-pam/index.html article] is available which explains PAM configuration in further detail.}}<br />
<br />
{{hc|/etc/pam.d/login|2=<br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth include system-local-login<br />
'''auth optional pam_ssh.so try_first_pass'''<br />
account include system-local-login<br />
session include system-local-login<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
In the above example, login authentication initially proceeds as it normally would, with the user being prompted to enter his user password. The additional {{ic|auth}} authentication rule added to the end of the authentication stack then instructs the pam_ssh module to try to decrypt any private keys found in the {{ic|~/.ssh/login-keys.d}} directory. The {{ic|try_first_pass}} option is passed to the pam_ssh module, instructing it to first try to decrypt any SSH private keys using the previously entered user password. If the user's private key passphrase and user password are the same, this should succeed and the user will not be prompted to enter the same password twice. In the case where the user's private key passphrase user password differ, the pam_ssh module will prompt the user to enter the SSH passphrase after the user password has been entered. The {{ic|optional}} control value ensures that users without an SSH private key are still able to log in. In this way, the use of pam_ssh will be transparent to users without an SSH private key.<br />
<br />
If you use another means of logging in, such as an X11 display manager like [[SLiM]] or [[XDM]] and you would like it to provide similar functionality, you must edit its associated PAM configuration file in a similar fashion. Packages providing support for PAM typically place a default configuration file in the {{ic|/etc/pam.d/}} directory.<br />
<br />
Further details on how to use pam_ssh and a list of its options can be found in the pam_ssh man page.<br />
<br />
====Using a different password to unlock the SSH key====<br />
If you want to unlock the SSH keys or not depending on whether you use your key's passphrase or the (different!) login password, you can modify {{ic|/etc/pam.d/system-auth}} to<br />
<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth [success=1 new_authtok_reqd=1 ignore=ignore default=ignore] pam_unix.so try_first_pass nullok'''<br />
'''auth required pam_ssh.so use_first_pass'''<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
session optional pam_permit.so<br />
'''session optional pam_ssh.so'''<br />
}}<br />
<br />
For an explanation, see [http://unix.stackexchange.com/a/239486/863 here].<br />
<br />
====Known issues with pam_ssh====<br />
Work on the pam_ssh project is infrequent and the documentation provided is sparse. You should be aware of some of its limitations which are not mentioned in the package itself.<br />
<br />
* Versions of pam_ssh prior to version 2.0 do not support SSH keys employing the newer option of ECDSA (elliptic curve) cryptography. If you are using earlier versions of pam_ssh you must use either RSA or DSA keys.<br />
<br />
* The {{ic|ssh-agent}} process spawned by pam_ssh does not persist between user logins. If you like to keep a [[GNU Screen]] session active between logins you may notice when reattaching to your screen session that it can no longer communicate with ssh-agent. This is because the GNU Screen environment and those of its children will still reference the instance of ssh-agent which existed when GNU Screen was invoked but was subsequently killed in a previous logout. The [[#Keychain|Keychain]] front-end avoids this problem by keeping the ssh-agent process alive between logins.<br />
<br />
===GNOME Keyring===<br />
If you use the [[GNOME]] desktop, the [[GNOME Keyring]] tool can be used as an SSH agent. See the [[GNOME Keyring]] article for further details.<br />
<br />
===Store SSH keys with Kwallet===<br />
For instructions on how to use kwallet to store your SSH keys, see [[KDE Wallet#Using the KDE Wallet to store ssh keys]].<br />
<br />
===KeePass2 with KeeAgent plugin===<br />
<br />
[http://lechnology.com/software/keeagent/ KeeAgent] is a plugin for [[KeePass]] that allows SSH keys stored in a KeePass database to be used for SSH authentication by other programs.<br />
<br />
* Supports both PuTTY and OpenSSH private key formats.<br />
* Works with native SSH agent on Linux/Mac and with PuTTY on Windows.<br />
<br />
See [[KeePass#Plugin Installation]] or [[install]] the {{AUR|keepass-plugin-keeagent}} package. There is also the beta version, where new features appear first, {{AUR|keepass-plugin-keeagent-beta}}.<br />
<br />
==Troubleshooting==<br />
<br />
=== Key ignored by the server ===<br />
<br />
If it appears that the SSH server is ignoring your keys, ensure that you have the proper permissions set on all relevant files.<br /><br />
For the local machine:<br />
<br />
$ chmod 700 ~/<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/id_ecdsa<br />
<br />
For the remote machine:<br />
<br />
$ chmod 700 ~/<br />
$ chmod 700 ~/.ssh<br />
$ chmod 600 ~/.ssh/authorized_keys<br />
<br />
If that does not solve the problem you may try temporarily setting {{ic|StrictModes}} to {{ic|no}} in {{ic|sshd_config}}. If authentication with StrictModes off is successful, it is likely an issue with file permissions persists.<br />
{{Tip|Do not forget to set {{ic|StrictModes}} to {{ic|yes}} for added security.}}<br />
Make sure the remote machine supports the type of keys you are using. Try using RSA or DSA keys instead [[#Generating an SSH key pair]]<br />
Some servers do not support ECDSA keys. <br />
<br />
Failing this, run the sshd in debug mode and monitor the output while connecting:<br />
<br />
# /usr/bin/sshd -d<br />
<br />
==See also==<br />
* [http://www.ibm.com/developerworks/linux/library/l-keyc.html OpenSSH key management, Part 1]<br />
* [http://www.ibm.com/developerworks/linux/library/l-keyc2/ OpenSSH key management, Part 2]<br />
* [http://www.ibm.com/developerworks/library/l-keyc3/ OpenSSH key management, Part 3]<br />
* [http://kimmo.suominen.com/docs/ssh/ Getting started with SSH]<br />
* [http://www.openssh.com/txt/release-5.7 OpenSSH 5.7 Release Notes]<br />
* [https://stribika.github.io/2015/01/04/secure-secure-shell.html Secure Secure Shell]</div>Nahanthttps://wiki.archlinux.org/index.php?title=Dm-crypt/Specialties&diff=417273Dm-crypt/Specialties2016-01-26T21:36:51Z<p>Nahant: Fixed typo: Ed2559 -> Ed25519</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Encryption]]<br />
[[Category:File systems]]<br />
[[ja:Dm-crypt/特記事項]]<br />
Back to [[Dm-crypt]].<br />
<br />
==Securing the unencrypted boot partition==<br />
The {{ic|/boot}} partition and the [[Master Boot Record]] are the two areas of the disk that are not encrypted, even in an [[Dm-crypt/Encrypting_an_entire_system|encrypted root]] configuration. They cannot usually be encrypted because the [[boot loader]] and BIOS (respectively) are unable to unlock a dm-crypt container in order to continue the boot process. An exception is [[GRUB]], which gained a feature to unlock a LUKS encrypted {{ic|/boot}} - see [[GRUB#Boot partition]]. <br />
<br />
This section describes steps that can be taken to make the boot process more secure. <br />
<br />
{{Warning|Note that securing the {{ic|/boot}} partition and MBR can mitigate numerous attacks that occur during the boot process, but systems configured this way may still be vulnerable to BIOS/UEFI/firmware tampering, hardware keyloggers, cold boot attacks, and many other threats that are beyond the scope of this article. For an overview of system-trust issues and how these relate to full-disk encryption, refer to [http://www.youtube.com/watch?v&#61;pKeiKYA03eE].}}<br />
<br />
===Booting from a removable device===<br />
<br />
Using a separate device to boot a system is a fairly straightforward procedure, and offers a significant security improvement against some kinds of attacks. Two vulnerable parts of a system employing an [[Dm-crypt/Encrypting_an_entire_system|encrypted root filesystem]] are<br />
* the [[Master Boot Record]], and<br />
* the {{ic|/boot}} partition.<br />
These must be stored unencrypted in order for the system to boot. In order to protect these from tampering, it is advisable to store them on a removable medium, such as a USB drive, and boot from that drive instead of the hard disk. As long as you keep the drive with you at all times, you can be certain that those components have not been tampered with, making authentication far more secure when unlocking your system.<br />
<br />
It is assumed that you already have your system configured with a dedicated partition mounted at {{ic|/boot}}. If you do not, please follow the steps in [[dm-crypt/System configuration#Boot loader]], substituting your hard disk for a removable drive.<br />
{{Note|You must make sure your system supports booting from the chosen medium, be it a USB drive, an external hard drive, an SD card, or anything else.}}<br />
Prepare the removable drive ({{ic|/dev/sdx}}).<br />
# gdisk /dev/sdx #format if necessary. Alternatively, cgdisk, fdisk, cfdisk, gparted...<br />
# mkfs.ext2 /dev/sdx1<br />
# mount /dev/sdx1 /mnt<br />
Copy your existing {{ic|/boot}} contents to the new one.<br />
# cp -R -i -d /boot/* /mnt<br />
Mount the new partition. Do not forget to update your [[fstab]] file accordingly.<br />
# umount /boot<br />
# umount /mnt<br />
# mount /dev/sdx1 /boot<br />
# genfstab -p -U / > /etc/fstab<br />
Update [[GRUB]]. {{ic|grub-mkconfig}} should detect the new partition UUID automatically, but custom menu entries may need to be updated manually.<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
# grub-install /dev/sdx #install to the removable device, not the hard disk.<br />
Reboot and test the new configuration. Remember to set your device boot order accordingly in your [[BIOS]] or [[UEFI]]. If the system fails to boot, you should still be able to boot from the hard drive in order to correct the problem.<br />
<br />
===chkboot===<br />
{{warning|chkboot makes a {{ic|/boot}} partition '''tamper-evident''', not '''tamper-proof'''. By the time the chkboot script is run, you have already typed your password into a potentially compromised boot loader, kernel, or initrd. If your system fails the chkboot integrity test, no assumptions can be made about the security of your data.}}<br />
Referring to an article from the ct-magazine (Issue 3/12, page 146, 01.16.2012, [http://www.heise.de/ct/inhalt/2012/03/6/]) the following script checks files under {{ic|/boot}} for changes of SHA-1 hash, inode, and occupied blocks on the hard drive. It also checks the [[Master Boot Record]]. The script cannot prevent certain type of attacks, but a lot are made harder. No configuration of the script itself is stored in unencrypted {{ic|/boot}}. With a locked/powered-off encrypted system, this makes it harder for some attackers because it is not apparent that an automatic checksum comparison of the partition is done upon boot. However, an attacker who anticipates these precautions can manipulate the firmware to run his own code on top of your kernel and intercept file system access, e.g. to {{ic|boot}}, and present the untampered files. Generally, no security measures below the level of the firmware are able to guarantee trust and tamper evidence.<br />
<br />
The script with installation instructions is [ftp://ftp.heise.de/pub/ct/listings/1203-146.zip available] (Author: Juergen Schmidt, ju at heisec.de; License: GPLv2). There is also package {{AUR|chkboot}} to [[install]].<br />
<br />
After installation add a service file (the package includes one based on the following) and [[enable]] it: <br />
[Unit]<br />
Description=Check that boot is what we want<br />
Requires=basic.target<br />
After=basic.target<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/local/bin/chkboot.sh<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
There is a small caveat for systemd. At the time of writing, the original {{ic|chkboot.sh}} script provided contains an empty space at the beginning of {{ic|<u> </u>#!/bin/bash}} which has to be removed for the service to start successfully.<br />
<br />
As {{ic|/usr/local/bin/chkboot_user.sh}} needs to be executed right after login, you need to add it to the [[autostart]] (e.g. under KDE -> ''System Settings -> Startup and Shutdown -> Autostart''; GNOME 3: ''gnome-session-properties''). <br />
<br />
With Arch Linux, changes to {{ic|/boot}} are pretty frequent, for example by new kernels rolling-in. Therefore it may be helpful to use the scripts with every full system update. One way to do so: <br />
<br />
#!/bin/bash<br />
#<br />
# Note: Insert your <user> and execute it with sudo for pacman & chkboot to work automagically<br />
#<br />
echo "Pacman update [1] Quickcheck before updating" & <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user> <br />
/usr/local/bin/chkboot.sh<br />
sync # sync disks with any results <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user> <br />
echo "Pacman update [2] Syncing repos for pacman" <br />
pacman -Syu<br />
/usr/local/bin/chkboot.sh<br />
sync <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user><br />
echo "Pacman update [3] All done, let us roll on ..."<br />
<br />
=== mkinitcpio-chkcryptoboot === <br />
{{Warning|This hook does '''not''' encrypt [[GRUB]]'s core (MBR) code or EFI stub, nor does it protect against situations where an attacker is able to modify the behaviour of the bootloader to compromise the kernel and/or initramfs at run-time.}}<br />
{{aur|mkinitcpio-chkcryptoboot}} is a [[mkinitcpio]] hook that performs integrity checks during early-userspace and advises the user not to enter his root partition password if the system appears to have been compromised. Security is achieved through an [[Dm-crypt/Encrypting_an_entire_system#Encrypted_boot_partition_.28GRUB.29|encrypted boot partition]], which is unlocked using [[GRUB#Boot_partition|GRUB]]'s {{ic|cryptodisk.mod}} module, and a root filesystem partition, which is encrypted with a password different from the former. This way, the [[initramfs]] and [[kernel]] are secured against offline tampering, and the root partition can remain secure even if the {{ic|/boot}} partition password is entered on a compromised machine (provided that the chkcryptoboot hook detects the compromise, and is not itself compromised at run-time). <br />
<br />
This hook requires {{pkg|GRUB}} release >=2.00 to function, and a dedicated, LUKS encrypted {{ic|/boot}} partition with its own password in order to be secure.<br />
<br />
==== Installation ====<br />
[[Install]] {{aur|mkinitcpio-chkcryptoboot}} and edit {{ic|/etc/default/chkcryptoboot.conf}}. If you want the ability of detecting if your boot partition was bypassed, edit the {{ic|CMDLINE_NAME}} and {{ic|CMDLINE_VALUE}} variables, with values known only to you. You can follow the advice of using two hashes as is suggested right after the installation. Also, be sure to make the appropriate changes to the [[Kernel parameters|kernel command line]] in {{ic|/etc/default/grub}}. Edit the {{ic|1=HOOKS=}} line in {{ic|/etc/mkinitcpio.conf}}, and insert the {{ic|chkcryptoboot}} hook '''before''' {{ic|encrypt}}. When finished, [[Mkinitcpio#Image_creation_and_activation|rebuild]] the initramfs.<br />
<br />
==== Technical Overview ====<br />
{{aur|mkinitcpio-chkcryptoboot}} consists of an install hook and a run-time hook for mkinitcpio. The install hook runs every time the initramfs is rebuilt, and hashes the GRUB [[UEFI|EFI]] stub ({{ic|$esp/EFI/grub_uefi/grubx64.efi}}) (in the case of [[UEFI]] systems) or the first 446 bytes of the disk on which GRUB is installed (in the case of BIOS systems), and stores that hash inside the initramfs located inside the encrypted {{ic|/boot}} partition. When the system is booted, GRUB prompts for the {{ic|/boot}} password, then the run-time hook performs the same hashing operation and compares the resulting hashes before prompting for the root partition password. If they do not match, the hook will print an error like this:<br />
{{bc|CHKCRYPTOBOOT ALERT!<br />
CHANGES HAVE BEEN DETECTED IN YOUR BOOT LOADER EFISTUB!<br />
YOU ARE STRONGLY ADVISED NOT TO ENTER YOUR ROOT CONTAINER PASSWORD!<br />
Please type uppercase yes to continue:<br />
}}<br />
<br />
In addition to hashing the boot loader, the hook also checks the parameters of the running kernel against those configured in {{ic|/etc/default/chkcryptoboot.conf}}. This is checked both at run-time and after the boot process is done. This allows the hook to detect if GRUB's configuration was not bypassed at run-time and afterwards to detect if the entire {{ic|/boot}} partition was not bypassed.<br />
<br />
For BIOS systems the hook creates a hash of GRUB's first stage bootloader (installed to the first 446 bytes of the bootdevice) to compare at the later boot processes. The main second-stage GRUB bootloader {{ic|core.img}} is not checked.<br />
<br />
===Other methods ===<br />
<br />
Alternatively to above scripts, a hash check can be set up with [[AIDE]] which can be customized via a very flexible configuration file. <br />
<br />
While one of these methods should serve the purpose for most users, they do not address all security problems associated with the unencrypted {{ic|/boot}}. One approach which endeavours to provide a fully authenticated boot chain was published with POTTS as an academic thesis to implement the [http://www1.informatik.uni-erlangen.de/stark STARK] authentication framework. <br />
<br />
The POTTS proof-of-concept uses Arch Linux as a base distribution and implements a system boot chain with <br />
* POTTS - a boot menu for a one-time authentication message prompt <br />
* TrustedGrub - a [[GRUB Legacy]] implementation which authenticates the kernel and initramfs against TPM chip registers <br />
* TRESOR - a kernel patch which implements AES but keeps the master-key not in RAM but in CPU registers during runtime. <br />
As part of the thesis [http://13.tc/p/potts/manual.html installation] instructions based on Arch Linux (ISO as of 2013-01) have been published. If you want to try it, be aware these tools are not in standard repositories and the solution will be time consuming to maintain.<br />
<br />
==Using GPG or OpenSSL Encrypted Keyfiles==<br />
The following forum posts give instructions to use two factor authentication, gpg or openssl encrypted keyfiles, instead of a plaintext keyfile described earlier in this wiki article [https://bbs.archlinux.org/viewtopic.php?id=120243 System Encryption using LUKS with GPG encrypted keys]:<br />
* GnuPG: [https://bbs.archlinux.org/viewtopic.php?pid=943338#p943338 Post regarding GPG encrypted keys] This post has the generic instructions.<br />
* OpenSSL: [https://bbs.archlinux.org/viewtopic.php?pid=947805#p947805 Post regarding OpenSSL encrypted keys] This post only has the {{ic|ssldec}} hooks.<br />
* OpenSSL: [https://bbs.archlinux.org/viewtopic.php?id=155393 Post regarding OpenSSL salted bf-cbc encrypted keys] This post has the {{ic|bfkf}} initcpio hooks, install, and encrypted keyfile generator scripts.<br />
* LUKS: [https://bbs.archlinux.org/viewtopic.php?pid=1502651#p1502651 Post regarding LUKS encrypted keys] with a {{ic|lukskey}} initcpio hook.<br />
<br />
Note that:<br />
* You can follow the above instructions with only two primary partitions, one boot partition (required because of encryption) and one primary LVM partition. Within the LVM partition you can have as many partitions as you need, but most importantly it should contain at least root, swap, and home logical volume partitions. This has the added benefit of having only one keyfile for all your partitions, and having the ability to hibernate your computer (suspend to disk) where the swap partition is encrypted. If you decide to do so your hooks in {{ic|/etc/mkinitcpio.conf}} should look like this:{{bc|1=HOOKS=" ... usb usbinput (etwo or ssldec) encrypt (if using openssl) lvm2 resume ... "}} and you should add {{bc|1=resume=/dev/mapper/<VolumeGroupName>-<LVNameOfSwap>}} to your [[kernel parameters]].<br />
* If you need to temporarily store the unencrypted keyfile somewhere, do not store them on an unencrypted disk. Even better make sure to store them to RAM such as {{ic|/dev/shm}}.<br />
* If you want to use a GPG encrypted keyfile, you need to use a statically compiled GnuPG version 1.4 or you could edit the hooks and use this AUR package {{AUR|gnupg1}}<br />
* It is possible that an update to OpenSSL could break the custom {{ic|ssldec}} mentioned in the second forum post.<br />
<br />
==Remote unlocking of the root (or other) partition==<br />
{{Note|1=As of 07/23/2015 the "dropbear_initrd_encrypt" package was split into three other packages. See [https://bbs.archlinux.org/viewtopic.php?id=200114 this forum post]. As of 11/18/2015 the package was deleted from the [[AUR]]. The steps below reflect the usage of the new packages.}}<br />
If you want to be able to reboot a fully LUKS-encrypted system remotely, or start it with a [[Wake-on-LAN]] service, you will need a way to enter a passphrase for the root partition/volume at startup. This can be achieved by running a [[mkinitcpio]] hook that configures a network interface, such as {{AUR|mkinitcpio-netconf}} and/or {{AUR|mkinitcpio-ppp}} (for remote unlocking using a [[Wikipedia:Point-to-Point Protocol|PPP]] connection over the internet) along with an [[SSH]] server in initrd. You have the option of using either {{AUR|mkinitcpio-dropbear}} or {{AUR|mkinitcpio-tinyssh}}. Those hooks do not install any shell, so you also need to [[Install|install]] the {{AUR|mkinitcpio-utils}} package. The instructions below can be used in any combination of the packages above. When there are different paths, it will be noted.<br />
<br />
# If you do not have an SSH key pair yet, [[SSH keys#Generating_an_SSH_key_pair|generate one]] on the client system (the one which will be used to unlock the remote machine).<br />
# If your choose to use {{AUR|mkinitcpio-tinyssh}}, you have the option of using [[SSH_keys#Choosing_the_type_of_encryption|Ed25519 keys]].<br />
# Insert your SSH public key (i.e. the one you usually put onto hosts so that you can ssh in without a password, or the one you just created and which ends with ''.pub'') into the remote machine's {{ic|/etc/dropbear/root_key or /etc/tinyssh/root_key}} file using the method of your choice, e.g.:<br />
#*[[SSH keys#Copying_the_public_key_to_the_remote_server|copy the public key to the remote system]]<br />
#* then enter the following command (on the remote system): {{bc|# cat /home/<user>/.ssh/authorized_keys > /etc/<dropbear or tinyssh>/root_key}}{{Tip|This method can later be used to add other SSH public keys as needed; in that case verify the content of remote {{ic|~/.ssh/authorized_keys}} contains only keys you agree to be used to unlock the remote machine. When adding additional keys, also regenerate your initrd with mkinitcpio. See also [[Secure Shell#Protection]].}}<br />
# Add the {{ic|<netconf and/or ppp> <dropbear or tinyssh> encryptssh}} [[Mkinitcpio#HOOKS|hooks]] before {{ic|filesystems}} within the "HOOKS" array in {{ic|/etc/mkinitcpio.conf}} (the {{ic|encryptssh}} can be used to replace the {{ic|encrypt}} hook). Then [[Mkinitcpio#Image_creation_and_activation|rebuild the initramfs image]]. {{Note|The {{ic|net}} hook provided with {{Pkg|mkinitcpio-nfs-utils}} is '''not''' needed}} {{Note|It could be necessary to add [[Network_configuration#Device_Driver|the module for your network card]] to the [[Mkinitcpio#MODULES|MODULES]] array.}}<br />
# Configure the required {{ic|1=cryptdevice=}} [[Dm-crypt/System_configuration#Boot_loader|parameter]] and add the {{ic|1=ip=}} [[Kernel_parameters|kernel command parameter]] to your bootloader configuration with the appropriate arguments (see [[Mkinitcpio#Using_net]]). For example, if the DHCP server does not attribute a static IP to your remote system, making it difficult to access via SSH accross reboots, you can explicitly state the IP you want to be used:{{bc|<nowiki>ip=192.168.1.1:::::eth0:none</nowiki>}}{{Note|Make sure to use kernel device names for the interface name (under the form ''eth#'') and not ''udev'' ones, as those will not work.}}Then update the configuration of your [[Boot_loaders|bootloader]], e.g. for [[GRUB#Generating_main_configuration_file|GRUB]]:{{bc|# grub-mkconfig -o /boot/grub/grub.cfg}}<br />
# Finally, restart the remote system and try to [[Secure_Shell#Client usage|ssh to it]], '''explicitly stating the "root" username''' (even if the root account is disabled on the machine, this root user is used only in the initrd for the purpose of unlocking the remote system). If you are using the {{AUR|mkinitcpio-dropbear}} package and you also have the {{Pkg|openssh}} package installed, then you most probably will not get any warnings before logging in, because it convert and use the same host keys openssh uses. (Except Ed25519 keys, dropbear does not support them). In case you are using {{AUR|mkinitcpio-tinyssh}}, you '''will''' get a warning the first time you login, because tinyssh does not use the same host keys as openssh, and they will be created when you build the initramfs. They will not be recreated every time, just on the first build. In either case, you should be prompted for the passphrase to unlock the root device:<br />
{{hc|$ ssh '''root'''@192.168.1.1|Enter passphrase for /dev/sda2: <br />
Connection to 192.168.1.1 closed.}}<br />
Afterwards, the system will complete its boot process and you can ssh to it [[Secure_Shell#Client usage|as you normally would]] (with the remote user of your choice).<br />
<br />
{{Tip|1=If you would simply like a nice solution to mount other encrypted partitions (such as {{ic|/home}}) remotely, you may want to look at [https://bbs.archlinux.org/viewtopic.php?pid=880484 this forum thread].}}<br />
<br />
=== Remote unlock via wifi ===<br />
The net hook is normally used with an ethernet connection. In case you want to setup a computer with wireless only, and unlock it via wifi, you can create a custom hook to connect to a wifi network before the net hook is run.<br />
<br />
Below example shows a setup using a usb wifi adapter, connecting to a wifi network protected with WPA2-PSK. In case you use for example WEP or another boot loader, you might need to change some things.<br />
<br />
# Modify {{ic|/etc/mkinitcpio.conf}}:<br />
#* Add the needed kernel module for your specific wifi adatper.<br />
#* Include the {{ic|wpa_passphrase}} and {{ic|wpa_supplicant}} binaries.<br />
#* Add a hook {{ic|wifi}} (or a name of your choice, this is the custom hook that will be created) before the {{ic|net}} hook.{{bc|1=MODULES="''module''"<br>BINARIES="wpa_passphrase wpa_supplicant"<br>HOOKS="base udev autodetect ... '''wifi''' net ... dropbear encryptssh ..."}}<br />
# Create the {{ic|wifi}} hook in {{ic|/lib/initcpio/hooks/wifi}}:{{bc|run_hook ()<br>{<br>&#09;# sleep a couple of seconds so wlan0 is setup by kernel<br>&#09;sleep 5<br><br>&#09;# set wlan0 to up<br>&#09;ip link set wlan0 up<br><br>&#09;# assocciate with wifi network<br>&#09;# 1. save temp config file<br>&#09;wpa_passphrase "''network ESSID''" "''pass phrase''" > /tmp/wifi<br><br>&#09;# 2. assocciate<br>&#09;wpa_supplicant -B -D nl80211,wext -i wlan0 -c /tmp/wifi<br><br>&#09;# sleep a couple of seconds so that wpa_supplicant finishes connecting<br>&#09;sleep 5<br><br>&#09;# wlan0 should now be connected and ready to be assigned an ip by the net hook<br>}<br><br>run_cleanuphook ()<br>{<br>&#09;# kill wpa_supplicant running in the background<br>&#09;killall wpa_supplicant<br><br>&#09;# set wlan0 link down<br>&#09;ip link set wlan0 down<br><br>&#09;# wlan0 should now be fully disconnected from the wifi network<br>}|}}<br />
# Create the hook installation file in {{ic|/lib/initcpio/install/wifi}}:{{bc|build ()<br>{<br>&#09;add_runscript<br>}<br>help ()<br>{<br>cat<<HELPEOF<br>&#09;Enables wifi on boot, for dropbear ssh unlocking of disk.<br>HELPEOF<br>}|}}<br />
# Add {{ic|1=ip=:::::wlan0:dhcp}} to the [[kernel parameters]]. Remove {{ic|1=ip=:::::eth0:dhcp}} so it does not conflict.<br />
# Optionally create an additional boot entry with kernel parameter {{ic|1=ip=:::::eth0:dhcp}}.<br />
# [[Mkinitcpio#Image_creation_and_activation|Regenerate the intiramfs image]].<br />
# Update the configuration of your [[boot loader]], e.g. for [[GRUB#Generating_main_configuration_file|GRUB]]:{{bc|# grub-mkconfig -o /boot/grub/grub.cfg}}<br />
Remember to setup [[Wireless_network_configuration|wifi]], so you are able to login once the system is fully booted. In case you are unable to connect to the wifi network, try increasing the sleep times a bit.<br />
<br />
== Discard/TRIM support for solid state drives (SSD) ==<br />
<br />
[[Solid state drive]] users should be aware that by default, Linux's full-drive encryption mechanisms will ''not'' forward TRIM commands from the filesystem to the underlying drive. The device-mapper maintainers have made it clear that TRIM support will never be enabled by default on dm-crypt devices because of the potential security implications.[http://www.saout.de/pipermail/dm-crypt/2011-September/002019.html][http://www.saout.de/pipermail/dm-crypt/2012-April/002420.html] Minimal data leakage in the form of freed block information, perhaps sufficient to determine the filesystem in use, may occur on devices with TRIM enabled. An illustration and discussion of the issues arising from activating TRIM is available in the [http://asalor.blogspot.de/2011/08/trim-dm-crypt-problems.html blog] of a ''cryptsetup'' developer. If you are worried about such factors, keep also in mind that threats may add up: for example, if your device is still encrypted with the previous (cryptsetup <1.6.0) default cipher {{ic|--cipher aes-cbc-essiv}}, more information leakage may occur from trimmed sector observation than with the current [[Dm-crypt/Device_encryption#Encryption_options_for_LUKS_mode|default]]. <br />
<br />
The following cases can be distinguished:<br />
<br />
* The device is encrypted with default dm-crypt LUKS mode:<br />
** By default the LUKS header is stored at the beginning of the device and using TRIM is useful to protect header modifications. If for example a compromised LUKS password is revoked, without TRIM the old header will in general still be available for reading until overwritten by another operation; if the drive is stolen in the meanwhile, the attackers could in theory find a way to locate the old header and use it to decrypt the content with the compromised password. See [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects cryptsetup FAQ, section 5.19 What about SSDs, Flash and Hybrid Drives?] and [https://www.reddit.com/r/archlinux/comments/2f370s/full_disk_encryption_on_an_ssd/ck5p5c5 Full disk encryption on an ssd]. <br />
** TRIM can be left disabled if the security issues stated at the top of this section are considered a worse threat than the above bullet.<br />
: See also [[Securely wipe disk#Flash memory]].<br />
* The device is encrypted with dm-crypt plain mode, or the LUKS header is stored [[Dm-crypt/Specialties#Encrypted_system_using_a_remote_LUKS_header|separately]]:<br />
** If plausible deniability is required, TRIM should '''never''' be used because of the considerations at the top of this section, or the use of encryption will be given away.<br />
** If plausible deniability is not required, TRIM can be used for its performance gains, provided that the security dangers described at the top of this section are not of concern.<br />
<br />
{{Warning|Before enabling TRIM on your drive, make sure it is fully supported, or data loss can occur. See [[Solid State Drives#TRIM]].}}<br />
<br />
In {{Pkg|linux}} 3.1 and up, support for dm-crypt TRIM pass-through can be toggled upon device creation or mount with dmsetup. Support for this option also exists in {{Pkg|cryptsetup}} version 1.4.0 and up. To add support during boot, you will need to add {{ic|:allow-discards}} to the {{ic|cryptdevice}} option. The TRIM option may look like this:<br />
cryptdevice=/dev/sdaX:root:allow-discards<br />
<br />
For the main {{ic|cryptdevice}} configuration options before the {{ic|:allow-discards}} see [[Dm-crypt/System configuration]].<br />
<br />
Besides the kernel option, it is also required to periodically run {{ic|fstrim}} or mount the filesystem (e.g. {{ic|/dev/mapper/root}} in this example) with the {{ic|discard}} option in {{ic|/etc/fstab}}. For details, please refer to the [[SSD#TRIM|SSD]] page.<br />
<br />
For LUKS devices unlocked manually on the console or via {{ic|/etc/crypttab}} either {{ic|discard}} or {{ic|allow-discards}} may be used.<br />
<br />
== The encrypt hook and multiple disks == <br />
<br />
The {{ic|encrypt}} hook only allows for a '''single''' {{ic|cryptdevice<nowiki>=</nowiki>}} entry. In system setups with multiple drives this may be limiting, because ''dm-crypt'' has no feature to exceed the physical device. For example, take "LVM on LUKS": The entire LVM exists inside a LUKS mapper. This is perfectly fine for a single-drive system, since there is only one device to decrypt. But what happens when you want to increase the size of the LVM? You cannot, at least not without modifying the {{ic|encrypt}} hook. <br />
<br />
The following sections briefly show alternatives to overcome the limitation. The first deals with how to expand a [[Dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|LUKS on LVM]] setup to a new disk. The second with modifying the {{ic|encrypt}} hook to unlock multiple disks in LUKS setups without LVM. The third section then again uses LVM, but modifies the {{ic|encrypt}} hook to unlock the encrypted LVM with a remote LUKS header. <br />
<br />
=== Expanding LVM on multiple disks ===<br />
The management of multiple disks is a basic [[LVM]] feature and a major reason for its partitioning flexibility. It can also be used with ''dm-crypt'', but only if LVM is employed as the first mapper. In such a [[Dm-crypt/Encrypting_an_entire_system#LUKS_on_LVM|LUKS on LVM]] setup the encrypted devices are created inside the logical volumes (with a separate passphrase/key per volume). The following covers the steps to expand that setup to another disk. <br />
<br />
{{Warning|Backup! While resizing filesystems may be standard, keep in mind that operations '''may''' go wrong and the following might not apply to a particular setup. Generally, extending a filesystem to free disk space is less problematic than shrinking one. This in particular applies when stacked mappers are used, as it is the case in the following example.}}<br />
<br />
==== Adding a new drive ====<br />
First, it may be desired to prepare a new disk according to [[Dm-crypt/Drive preparation]]. <br />
Second, it is partitioned as a LVM, e.g. all space is allocated to {{ic|/dev/sdY1}} with partition type "8E00" (Linux LVM). <br />
Third, the new disk/partition is attached to the existing LVM volume group, e.g.:<br />
# pvcreate /dev/sdY1<br />
# vgextend MyStorage /dev/sdY1<br />
<br />
==== Extending the logical volume ====<br />
<br />
For the next step, the final allocation of the new diskspace, the logical volume to be extended has to be unmounted. It can be performed for the {{ic|cryptdevice}} root partition, but in this case the procedure has to be performed from an Arch Install ISO. <br />
<br />
In this example, it is assumed that the logical volume for {{ic|/home}} (lv-name {{ic|homevol}}) is going to be expanded with the fresh disk space: <br />
# umount /home<br />
# fsck /dev/mapper/home<br />
# cryptsetup luksClose /dev/mapper/home<br />
# lvextend -l +100%FREE MyStorage/homevol<br />
<br />
Now the logical volume is extended and the LUKS container comes next: <br />
# cryptsetup open --type luks /dev/mapper/MyStorage-homevol home<br />
# umount /home # as a safety, in case it was automatically remounted<br />
# cryptsetup --verbose resize home<br />
<br />
Finally, the filesystem itself is resized: <br />
# e2fsck -f /dev/mapper/home<br />
# resize2fs /dev/mapper/home<br />
<br />
Done! If it went to plan, {{ic|/home}} can be remounted <br />
# mount /dev/mapper/home /home<br />
<br />
and now includes the span to the new disk. Note that the {{ic|cryptsetup resize}} action does not affect encryption keys, they have not changed.<br />
<br />
=== Modifying the encrypt hook for multiple partitions ===<br />
==== Multiple root partitions ====<br />
It is possible to modify the encrypt hook to allow multiple hard drive decrypt root ({{ic|/}}) at boot. One way according to an Arch user (benke):<br />
<br />
# cp /usr/lib/initcpio/hooks/encrypt /usr/lib/initcpio/hooks/encrypt2<br />
# cp /usr/lib/initcpio/install/encrypt /usr/lib/initcpio/install/encrypt2<br />
# nano /usr/lib/initcpio/hooks/encrypt2<br />
<br />
Change {{ic|$cryptkey}} to {{ic|$cryptkey2}}, and {{ic|$cryptdevice}} to {{ic|$cryptdevice2}}.<br />
Add {{ic|1=cryptdevice2=}} (e.g. {{ic|1=cryptdevice2=/dev/sdb:hdd2}}) to your boot options (and {{ic|1=cryptkey2=}} if needed).<br />
<br />
Change the {{ic|/etc/fstab}} flag for root:<br />
<br />
/dev/sdb /mnt btrfs device=/dev/sda,device=/dev/sdb, ... 0 0<br />
<br />
==== Multiple non-root partitions ====<br />
Maybe you have a requirement for using the {{ic|encrypt}} hook on a non-root partition. Arch does not support this out of the box, however, you can easily change the cryptdev and cryptname values in {{ic|/lib/initcpio/hooks/encrypt}} (the first one to your {{ic|/dev/sd*}} partition, the second to the name you want to attribute). That should be enough.<br />
<br />
The big advantage is you can have everything automated, while setting up {{ic|/etc/crypttab}} with an external key file (i.e. the keyfile is not on any internal hard drive partition) can be a pain - you need to make sure the USB/FireWire/... device gets mounted before the encrypted partition, which means you have to change the order of {{ic|/etc/fstab}} (at least).<br />
<br />
Of course, if the {{pkg|cryptsetup}} package gets upgraded, you will have to change this script again. Unlike {{ic|/etc/crypttab}}, only one partition is supported, but with some further hacking one should be able to have multiple partitions unlocked.<br />
<br />
{{accuracy|Why not use the supported Grub2 right away? See also [[Mkinitcpio#Using_RAID]]}} <br />
If you want to do this on a software RAID partition, there is one more thing you need to do. Just setting the {{ic|/dev/mdX}} device in {{ic|/lib/initcpio/hooks/encrypt}} is not enough; the {{ic|encrypt}} hook will fail to find the key for some reason, and not prompt for a passphrase either. It looks like the RAID devices are not brought up until after the {{ic|encrypt}} hook is run. You can solve this by putting the RAID array in {{ic|/boot/grub/menu.lst}}, like <br />
kernel /boot/vmlinuz-linux md=1,/dev/hda5,/dev/hdb5<br />
<br />
If you set up your root partition as a RAID, you will notice the similarities with that setup ;-). [[GRUB]] can handle multiple array definitions just fine:<br />
kernel /boot/vmlinuz-linux root=/dev/md0 ro md=0,/dev/sda1,/dev/sdb1 md=1,/dev/sda5,/dev/sdb5,/dev/sdc5<br />
<br />
=== Encrypted system using a remote LUKS header ===<br />
This example follows the same setup as in [[Dm-crypt/Encrypting an entire system#Plain dm-crypt]], which should be read first before following this guide.<br />
<br />
By using a remote header the encrypted blockdevice itself only carries encrypted data, which gives [[Wikipedia:Deniable encryption|deniable encryption]] as long as the existence of a header is unknown to the attackers. It is similar to using [[Dm-crypt/Encrypting an entire system#Plain_dm-crypt|plain dm-crypt]], but with the LUKS advantages such as multiple passphrases for the masterkey and key derivation. Further, using a remote header offers a form of two factor authentication with an easier setup than [[Dm-crypt/Specialties#Using_GPG_or_OpenSSL_Encrypted_Keyfiles|using GPG or OpenSSL encrypted keyfiles]], while still having a built-in password prompt for multiple retries. See [[Disk encryption#Cryptographic metadata]] for more information.<br />
<br />
See [[Dm-crypt/Device encryption#Encryption options for LUKS mode]] for encryption options before performing the first step to setup the encrypted system partition and creating a header file to use with {{ic|cryptsetup}}:<br />
# truncate -s 2M header.img<br />
# cryptsetup luksFormat /dev/sdX --header header.img<br />
<br />
Open the container:<br />
# cryptsetup open --header header.img --type luks /dev/sdX enc<br />
<br />
Now follow the [[Dm-crypt/Encrypting_an_entire_system#Preparing_the_non-boot_partitions|LVM on LUKS setup]] to your requirements. The same applies for [[Dm-crypt/Encrypting an entire system#Preparing the boot partition 4|preparing the boot partition]] on the removable device (because if not, there is no point in having a separate header file for unlocking the encrypted disk).<br />
Next move the {{ic|header.img}} onto it:<br />
# mv header.img /mnt/boot<br />
<br />
Follow the installation procedure up to the mkinitcpio step (you should now be {{ic|arch-chroot}}ed inside the encrypted system). <br />
<br />
There are two options for initramfs to support a detached LUKS header.<br />
<br />
==== Using systemd hook ====<br />
<br />
{{Note|This method requires systemd '''219''' or later.}} <br />
<br />
First create {{ic|/etc/crypttab.initramfs}} and add the encrypted device to it. The syntax is defined in [http://www.freedesktop.org/software/systemd/man/crypttab.html crypttab(5)]<br />
{{hc|/etc/crypttab.initramfs|2=MyStorage PARTUUID=00000000-0000-0000-0000-000000000000 none header=/boot/header.img}}<br />
<br />
Modify {{ic|/etc/mkinitcpio.conf}} [[Mkinitcpio#Common_hooks|to use systemd]] and add the header to {{ic|FILES}}.<br />
<br />
{{hc|<br />
/etc/mkinitcpio.conf|2=FILES="'''/boot/header.img'''"<br />
<br />
HOOKS="... '''systemd''' ... block '''sd-encrypt''' sd-lvm2 filesystems ..."<br />
}}<br />
<br />
[[Mkinitcpio#Image_creation_and_activation|Recreate the initramfs]] and you are done.<br />
<br />
{{Note|<br />
* No cryptsetup parameters need to be passed to the kernel command line, since{{ic|/etc/crypttab.initramfs}} will be added as {{ic|/etc/crypttab}} in the initramfs. If you wish to specify them in the kernel command line see [http://www.freedesktop.org/software/systemd/man/systemd-cryptsetup-generator.html systemd-cryptsetup-generator(8)] for the supported options. <br />
* Be aware the {{ic|systemd}} hook adds further files to the initramfs (e.g. {{ic|/etc/passwd}} and {{ic|/etc/group}}), in case you consider them sensitive.}}<br />
<br />
==== Modifying encrypt hook ====<br />
<br />
This method shows how to modify the {{ic|encrypt}} hook in order to use a remote LUKS header. <br />
Now the {{ic|encrypt}} hook has to be modified to let {{ic|cryptsetup}} use the separate header (base source and idea for these changes [https://bbs.archlinux.org/viewtopic.php?pid=1076346#p1076346 published on the BBS]). Make a copy so it is not overwritten on a [[mkinitcpio]] update:<br />
<br />
# cp /lib/initcpio/hooks/encrypt{,2}<br />
# cp /usr/lib/initcpio/install/encrypt{,2}<br />
<br />
{{hc|<br />
/lib/initcpio/hooks/encrypt2 (around line 52)|output=warn_deprecated() {<br />
echo "The syntax 'root=${root}' where '${root}' is an encrypted volume is deprecated"<br />
echo "Use 'cryptdevice=${root}:root root=/dev/mapper/root' instead."<br />
}<br />
<br />
'''local headerFlag=false'''<br />
for cryptopt in ${cryptoptions//,/ }; do<br />
case ${cryptopt} in<br />
allow-discards)<br />
cryptargs="${cryptargs} --allow-discards"<br />
;; <br />
<b>header)<br />
cryptargs="${cryptargs} --header /boot/header.img"<br />
headerFlag=true<br />
;;</b><br />
*) <br />
echo "Encryption option '${cryptopt}' not known, ignoring." >&2 <br />
;; <br />
esac<br />
done<br />
<br />
if resolved=$(resolve_device "${cryptdev}" ${rootdelay}); then<br />
if '''$headerFlag &#124;&#124; '''cryptsetup isLuks ${resolved} >/dev/null 2>&1; then<br />
[ ${DEPRECATED_CRYPT} -eq 1 ] && warn_deprecated<br />
dopassphrase=1<br />
}}<br />
<br />
Now edit the [[mkinitcpio|mkinitcpio.conf]] to add the {{ic|encrypt2}} and {{ic|lvm2}} hooks, the {{ic|header.img}} to {{ic|FILES}} and the {{ic|loop}} to {{ic|MODULES}}, apart from other configuration the system requires:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=MODULES="'''loop'''"<br />
<br />
FILES="'''/boot/header.img'''"<br />
<br />
HOOKS="... '''encrypt2''' '''lvm2''' ... filesystems ..."}}<br />
<br />
This is required so the LUKS header is available on boot allowing the decryption of the system, exempting us from a more complicated setup to mount another separate USB device in order to access the header. After this set up [[Mkinitcpio#Image_creation_and_activation|the initramfs]] is created.<br />
<br />
Next the [[Dm-crypt/Encrypting an entire system#Configuring the boot loader 4|boot loader is configured]] to specify the {{ic|1=cryptdevice=}} also passing the new {{ic|header}} option for this setup: <br />
<br />
cryptdevice=/dev/sdX:enc:header<br />
<br />
To finish, following [[Dm-crypt/Encrypting an entire system#Post-installation]] is particularly useful with a {{ic|/boot}} partition on an USB storage medium.<br />
<br />
{{Tip|1=You will notice that since the system partition only has "random" data, it does not have a partition table and by that an {{ic|UUID}} or a {{ic|name}}. But you can still have a consistent mapping using the disk id under {{ic|/dev/disk/by-id/}}}}</div>Nahanthttps://wiki.archlinux.org/index.php?title=Advanced_Format&diff=323719Advanced Format2014-07-06T11:44:36Z<p>Nahant: Fixed typos.</p>
<hr />
<div>[[Category:Storage]]<br />
==Introduction==<br />
The 'advanced format' feature reduces overhead by using 4 kilobyte sectors instead of the traditional 512 byte sectors. The old format gave a format efficiency of 87%. Advanced Format results in a format efficiency of 96% which increases space by up to 11%. The 4k sector is slated to become the next standard for HDDs by 2014.<br />
<br />
===More Detailed Explanation===<br />
The main idea behind using 4096-byte sectors is to increase the bit density on each track by reducing the number of gaps which hold Sync/DAM and ECC (Error Correction Code) information between data sectors. For eight 512-byte sectors, the track also holds eight sector gaps.<br />
<br />
By having one single sector of size 4096-byte (8 x 512-byte), the track holds only 1 sector gap for each data sector thus reducing an overhead for a need to support multiple Sync/DAM and ECC blocks and at the same time increasing bit density.<br />
<br />
Linux partitioning tools by default start each partition on sector 63 which leads to a bad performance in HDDs that use this 4K sector size due to misalignment to 4K sector from the beginning of the track.<br />
<br />
===External Links===<br />
*[http://www.anandtech.com/Show/Index/2888?cPage=2&all=False&sort=0&page=1 Western Digital’s Advanced Format: The 4K Sector Transition Begins]<br />
*[http://www.wdc.com/wdproducts/library/WhitePapers/ENG/2579-771430.pdf White paper entitled "Advanced Format Technology."]<br />
*Failure to align one's HDD results in poor read/write performance. See [http://www.linuxconfig.org/linux-wd-ears-advanced-format this article] for specific examples.<br />
<br />
==Current HDD Models that Employ a 4k Sectors==<br />
As of June 2011, there are a limited number of HDDs that support "Advanced Format" or 4k sectors as shown below.<br />
<br />
All drives in this list have a physical sector size of 4096 bytes, but not all drives correctly report this to the OS. The actual value reported (via new fields in the ATA-8 spec) is shown in the table as the physical reported sector size. As this is the value partitioning tools use for alignment, it is important that it should be 4096 to avoid misalignment issues.<br />
<br />
The logical sector size is the sector size used for data transfer. This value multiplied by the number of LBA sectors on the disk gives the disk capacity. Thus a disk with 4096 byte logical sectors will have a lower maximum LBA for the same capacity compared to a drive with 512 byte sectors. Drives with 512 byte logical sectors offer better compatibility with legacy operating systems (roughly those released before 2009) however drives with 4096 byte logical sectors may offer marginally better performance (e.g. more read/write requests may fit into the NCQ buffer.)<br />
<br />
{|class="wikitable"<br />
!rowspan=2| Manufacturer !!rowspan=2| Model !!rowspan=2| Capacity !!colspan=2| Reported sector size (bytes)<br />
|-<br />
! Logical !! Physical<br />
|-<br />
|colspan=5| '''3.5"'''<br />
|-<br />
| Western Digital || WD3000F9YZ || 2.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD30EZRX || 3.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD20EZRX || 2.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD30EZRSDTL || 3.0 TB<br />
|-<br />
| Western Digital || WD25EZRSDTL || 2.5 TB<br />
|-<br />
| Samsung || HD204UI || 2.0 TB || 512 || 512<br />
|-<br />
| Seagate || ST1000DL002 || 1.0 TB || 512 || 4096<br />
|-<br />
| Seagate || ST1000DM003 || 1.0 TB || 512 || 4096<br />
|-<br />
| Seagate || ST2000DL003 || 2.0 TB || 512 || 512<br />
|-<br />
| Seagate || ST2000DM001 || 2.0 TB || 512 || 4096<br />
|-<br />
| Seagate || ST3000DM001 || 3.0 TB || 512 || 4096<br />
|-<br />
| Seagate || ST4000VN000 || 4.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD20EARS || 2.0 TB || 512 || [http://community.wd.com/t5/Desktop-Mobile-Drives/Physical-Sector-Size-different-between-WD20EARS-00MVWB0-and/td-p/218226 4096] or [http://community.wdc.com/t5/Desktop/4k-sector-drive-reporting-512-byte-sectors-to-OS-why/td-p/205060 512]<br />
|-<br />
| Western Digital || WD20EARX || 2.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD20EFRX || 2.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD30EFRX || 3.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD15EARS || 1.5 TB || 512 || [http://excess.org/article/2010/11/wd-hdd-lying-about-4k-sectors/ 4096]<br />
|-<br />
| Western Digital || WD10EARS || 1.0 TB<br />
|-<br />
| Western Digital || WD10EURS || 1.0 TB<br />
|-<br />
| Western Digital || WD8000AARS || 800.0 GB<br />
|-<br />
| Western Digital || WD6400AARS || 640.0 GB<br />
|-<br />
|colspan=5| '''2.5"'''<br />
|-<br />
| Samsung || ST1000LM024|| 1.0 TB || 512 || 4096<br />
|-<br />
| Seagate || ST9750420AS || 750 GB || 512 || 4096<br />
|-<br />
| Western Digital || WD10JPVT || 1.0 TB || 512 || 4096<br />
|-<br />
| Western Digital || WD10TPVT || 1.0 TB<br />
|-<br />
| Western Digital || WD7500BPVT || 750.0 GB<br />
|-<br />
| Western Digital || WD7500KPVT || 750.0 GB<br />
|-<br />
| Western Digital || WD6400BPVT || 640.0 GB<br />
|-<br />
| Western Digital || WD5000BPVT || 500.0 GB<br />
|-<br />
| Western Digital || WD3200BPVT || 320.0 GB<br />
|-<br />
| Western Digital || WD2500BPVT || 250.0 GB || 512 || 4096<br />
|-<br />
| Western Digital || WD1600BPVT || 160.0 GB<br />
|-<br />
| TOSHIBA || MQ01ABD100 || 1.0 TB || 512 || 4096<br />
|}<br />
<br />
{{Note| Readers are encouraged to add to this table.}}<br />
<br />
== How to determine if HDD employ a 4k sector ==<br />
<br />
Tools which will report the physical sector of a drive (provided the drive will report it correctly) includes<br />
* smartmontools (since 5.41 ; <tt>smartmontools -a</tt>, in information section)<br />
* hdparm (since 9.12 ; <tt>hdparm -I</tt>, in configuration section)<br />
<br />
Note that both works even for USB-attached discs (if the USB bridge supports SAT aka SCSI/ATA Translation, ANSI INCITS 431-2007).<br />
<br />
==Aligning Partitions==<br />
<br />
{{Note|This should no longer require manual intervention. Any tools using recent libblkid versions are capable of handling Advanced Format automatically.}}<br />
<br />
Versions with this support include:<br />
<br />
* fdisk, since util-linux >= 2.15. You should start with ‘-c -u’ to disable DOS compatibility and use sectors instead of cylinders.<br />
* parted, since parted >= 2.1.<br />
* mdadm, since util-linux >= 2.15<br />
* lvm2, since util-linux >= 2.15<br />
* mkfs.{ext,xfs,gfs2,ocfs2} all support libblkid directly.<br />
<br />
Refer to [https://www.tolaris.com/2011/07/21/libblkid-or-why-you-dont-need-to-worry-about-4k-disk-format/ this page] for further information.<br />
<br />
===Check your partitions alignment===<br />
{{Note|This only works with [[MBR]], not [[GPT]].}}<br />
# fdisk -lu /dev/sda<br />
...<br />
# Device Boot Start End Blocks Id System<br />
# /dev/sda1 2048 46876671 23437312 7 HPFS/NTFS<br />
<br />
2048 (default since fdisk 2.17.2) means that your HDD is aligned correctly.<br />
Any other value divisible by 8 is good as well.<br />
<br />
===GPT (Recommended)===<br />
When using [[GPT]] partition tables, one need only use gdisk to create partitions which are aligned by default. For an example, see [[SSD#Detailed_Usage_Example]].<br />
<br />
===MBR (Not Recommended)===<br />
One can employ fdisk to align partitions to sector 2048 which will ensure that the partitions are aligned to the 4k sector. Interestingly, in sector mode, the default starting point is not 63 or 64 but 2048 in the current version of fdisk (2.17.2) so it is automatically taking care of the 4k sector size!<br />
<br />
# fdisk -c -u /dev/sda<br />
<br />
==Special Consideration for WD Green HDDs==<br />
<br />
FYI - this section has nothing to do with Advanced Format technology, but this is an appropriate location to share it with users. The WD20EARS (and other sizes include 1.0 and 1.5 TB driver in the series) will attempt to park the read heads once every 8 seconds FOR THE LIFE OF THE HDD which is just horrible! To see if you are affected use the smartctl command (part of smartmontools). If the last column changes rapidly, this section applies to your drive. <br />
# smartctl /dev/sdb -a | grep Load_Cycle<br />
193 Load_Cycle_Count 0x0032 001 001 000 Old_age Always - 597115<br />
<br />
=== Disable via hdparm ===<br />
Use hdparm in {{ic|/etc/systemd/system/lcc_fix.service}} to disable this 'feature' and likely add life to your hdd:<br />
<br />
{{hc|/etc/systemd/system/lcc_fix.service |<nowiki><br />
[Unit]<br />
Description=WDIDLE3<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/bin/hdparm -J 300 --please-destroy-my-drive /dev/sdX<br />
TimeoutSec=0<br />
StandardInput=tty<br />
RemainAfterExit=yes<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
</nowiki>}}<br />
<br />
Start the service<br />
# systemctl start lcc_fix.service<br />
<br />
Enable the service to autorun at boot.<br />
# systemctl enable lcc_fix.service<br />
<br />
==== Is this safe? ====<br />
Why do we need to pass the "--please-destroy-my-drive" flag? Here is an email from hdparm author, Mark Lord:<br />
<br />
> I have a Western DIgital \"Green\" drive (wd20ears). I noticed you added a -J switch and that <br />
> it is said to adjust the idle3 timeout. What frightens me is the output you gave it:<br />
> <br />
> How safe or not is this to use?<br />
<br />
I use it on my own drives. It works for me.<br />
<br />
If you can run the WDIDLE3.EXE MS-Dos program,<br />
then use it instead -- it was written by WD,<br />
and only they know how things really work there.<br />
<br />
If you cannot use the WDIDLE3.EXE, then you<br />
could consider "hdparm -J". It works for me,<br />
but it may or may not void some kind of warranty.<br />
<br />
Cheers<br />
-- <br />
Mark Lord<br />
Real-Time Remedies Inc.<br />
mlord@pobox.com<br />
<br />
=== Disable via changing firmware value (persistent) ===<br />
<br />
{{Warning|The tool used in this process is experimental, use at your own risk!}}<br />
<br />
{{Note|This method is persistent, you only need to do this once for every drive.}}<br />
<br />
This method will use a utility called idle3ctl to alter the firmware value for the idle3 timer on WD hard drives (similar to wdidle3.exe from WD). The advantage compared to the official utility is you do not need to create a DOS bootdisk first to change the idle3 timer value. Additionally idle3ctl might also work over USB-to-S-ATA bridges (in some cases).<br />
Download [http://idle3-tools.sourceforge.net/ idle3ctl], extract and compile it.<br />
Within the folder that contains the newly compiled binary, execute<br />
<br />
$ sudo ./idle3ctl -g /dev/your_wd_hdd<br />
<br />
to get the raw idle3 timer value.<br />
You can disable the IntelliPark feature completely, with:<br />
<br />
$ sudo ./idle3ctl -d /dev/your_wd_hdd<br />
<br />
or set it to a different value (''0''-''255'') with (e.g. 10 seconds):<br />
<br />
$ sudo ./idle3ctl -s 100 /dev/your_wd_hd<br />
<br />
The range ''0''-''128'' is in 0.1s and ''129-255'' in 30s. For the changes to take effect, the drive needs to go through one powercycle, meaning powering it off and on again (on internal drives, a reboot is not sufficient).<br />
<br />
If your WD hard drive is not recognized, you can use the ''--force'' option. For more options see:<br />
<br />
$ ./idle3ctl -h</div>Nahanthttps://wiki.archlinux.org/index.php?title=SSMTP&diff=303515SSMTP2014-03-07T19:36:34Z<p>Nahant: authentification -> authentication</p>
<hr />
<div>[[Category:Mail Server]]<br />
SSMTP is a program to deliver an email from a local computer to a configured mailhost (mailhub). It is not a mail server (like feature-rich mail server [[sendmail]]) and does not receive mail, expand aliases or manage a queue. One of its primary uses is for forwarding automated email (like system alerts) off your machine and to an external email address.<br />
<br />
==Installation==<br />
Install the package {{Pkg|ssmtp}} from the [[official repositories]].<br />
<br />
==Forward to a Gmail Mail Server==<br />
To configure SSMTP, you will have to edit its configuration file ({{ic|/etc/ssmtp/ssmtp.conf}}) and enter your account settings:<br />
{{bc|<nowiki><br />
# The user that gets all the mails (UID < 1000, usually the admin)<br />
root=username@gmail.com<br />
<br />
# The mail server (where the mail is sent to), both port 465 or 587 should be acceptable<br />
# See also http://mail.google.com/support/bin/answer.py?answer=78799<br />
mailhub=smtp.gmail.com:587<br />
<br />
# The address where the mail appears to come from for user authentication.<br />
rewriteDomain=gmail.com<br />
<br />
# The full hostname<br />
hostname=localhost<br />
<br />
# Use SSL/TLS before starting negotiation <br />
UseTLS=Yes<br />
UseSTARTTLS=Yes<br />
<br />
# Username/Password<br />
AuthUser=username<br />
AuthPass=password<br />
<br />
# Email 'From header's can override the default domain?<br />
FromLineOverride=yes<br />
</nowiki>}}<br />
<br />
Change the file permissions of {{ic|/etc/ssmtp/ssmtp.conf}} because the password is printed in plain text (so that other users on your system cannot see your Gmail password). <br />
{{bc|chmod 640 /etc/ssmtp/ssmtp.conf}}<br />
<br />
Change the config file group to mail to avoid "/etc/ssmtp/ssmtp.conf not found" error.<br />
{{bc|chown root:mail /etc/ssmtp/ssmtp.conf}}<br />
<br />
Users who can send mail need to belong to "mail" group (must log out and log back in for changes to be used).<br />
{{bc|gpasswd -a mainuser mail}}<br />
<br />
Create aliases for local usernames<br />
{{hc|/etc/ssmtp/revaliases|root:username@gmail.com:smtp.gmail.com:587<br />
mainuser:username@gmail.com:smtp.gmail.com:587}}<br />
<br />
To test whether the Gmail server will properly forward your email:<br />
{{bc|<nowiki>echo test | mail -v -s "testing ssmtp setup" username@somedomain.com</nowiki>}}<br />
<br />
If you receive the error {{bc|send-mail: Cannot open mailhub:25}} be sure the user is a member of the "mail" group.<br />
<br />
Change the 'From' text by editing {{ic|/etc/passwd}} to receive mail from 'root at myhost' instead of just 'root'.<br />
{{bc|chfn -f 'root at myhost' root<br />
chfn -f 'mainuser at myhost' mainuser}}<br />
Which changes {{ic|/etc/passwd}} to:<br />
{{hc|grep myhostname /etc/passwd|root:x:0:0:root@myhostname,,,:/root:/bin/bash<br />
mainuser:x:1000:1000:mainuser@myhostname,,,:/home/mainuser:/bin/bash}}<br />
<br />
An alternate method for sending emails is to create a text file and send it with 'ssmtp' or 'mail'<br />
{{hc|test-mail.txt|To:username@somedomain.com<br />
From:youraccount@gmail.com<br />
Subject: Test<br />
<br />
This is a test mail.}}<br />
<br />
Send the {{ic|test-mail.txt}} file<br />
{{bc|mail username@somedomain.com < test-mail.txt}}<br />
<br />
===Attachments===<br />
This method does not work with attachments. If you need to be able to add attachments, install and configure [[Mutt]] and [[Msmtp]] and then go see the tip at [http://www.cyberciti.biz/tips/sending-mail-with-attachment.html nixcraft].<br />
<br />
==References==<br />
*[https://bbs.archlinux.org/viewtopic.php?pid=446831 SSMTP and Gmail on the Arch forums]<br />
*[http://tombuntu.com/index.php/2008/10/21/sending-email-from-your-system-with-ssmtp/ Sending Email From Your System with sSMTP]<br />
*[http://www.scottro.net/qnd/qnd-ssmtp.html The Qnd Guide to ssmtp]<br />
*[http://mail.google.com/support/bin/answer.py?answer=78799 GMail Support - Configuring other mail clients]</div>Nahanthttps://wiki.archlinux.org/index.php?title=Active_Directory_integration&diff=300681Active Directory integration2014-02-23T15:51:59Z<p>Nahant: Fixed typo "tunig" -> "tuning"</p>
<hr />
<div>[[Category:Networking]]<br />
{{Warning|Because Arch Linux is a rolling release distribution, it is possible that some of the information in this article could be outdated due to package or configuration changes made by the maintainers. Never blindly follow these or any other instructions. When the instructions say to edit or change a file, consider making a backup copy. Check the date of the last revision of this article.}}<br />
<br />
A key challenge for system administrators of any datacenter is trying to coexisting in Heterogeneous environments. By this we mean the mixing of different server operating system technologies (typically Microsoft Windows & Unix/Linux). User management and authentication is by far the most difficult of these to solve. The most common way of solving this problem is to use a Directory Server. There are a number of open-source and commercial solutions for the various flavors of *NIX; however, few solve the problem of interoperating with Windows. Active Directory (AD) is a directory service created by Microsoft for Windows domain networks. It is included in most Windows Server operating systems. Server computers on which Active Directory is running are called domain controllers. <br />
<br />
[[Wikipedia:Active Directory|Active Directory]] serves as a central location for network administration and security. It is responsible for authenticating and authorizing all users and computers within a network of Windows domain type, assigning and enforcing security policies for all computers in a network and installing or updating software on network computers. For example, when a user logs into a computer that is part of a Windows domain, it is Active Directory that verifies his or her password and specifies whether he or she is a system administrator or normal user.<br />
<br />
Active Directory uses [[Wikipedia:Ldap|Lightweight Directory Access Protocol (LDAP)]] versions 2 and 3, [[Wikipedia:Kerberos_(protocol)|Kerberos]] and DNS. These same standards are available as linux, but piecing them together is not an easy task. Following these steps will help you configure an ArchLinux host to authenticate against an AD domain.<br />
<br />
This guide explains how to integrate an Arch Linux host with an existing Windows Active Directory domain. <br />
Before continuing, you must have an existing Active Directory domain, and have a user with the appropriate rights within the domain to: query users and add computer accounts (Domain Join). <br />
<br />
This document is not an intended as a complete guide to Active Directory nor Samba. Refer to the resources section for additional information.<br />
<br />
== Terminology ==<br />
<br />
If you are not familiar with Active Directory, there are a few keywords that are helpful to know.<br />
<br />
* '''Domain''' : The name used to group computers and accounts. <br />
* '''SID''' : Each computer that joins the domain as a member must have a unique SID or System Identifier.<br />
* '''SMB''' : Server Message Block.<br />
* '''NETBIOS''': Network naming protocol used as an alternative to DNS. Mostly legacy, but still used in Windows Networking.<br />
* '''WINS''': Windows Information Naming Service. Used for resolving Netbios names to windows hosts.<br />
* '''Winbind''': Protocol for windows authentication.<br />
== Configuration ==<br />
=== Active Directory Configuration ===<br />
{{Warning|This section has not been validated. Proceed with caution}}<br />
<br />
==== Updating the GPO ====<br />
It may be necessary to disable ''Digital Sign Communication (Always)'' in the AD group policies. Dive into:<br />
<br />
{{ic|Local policies}} -> {{ic|Security policies}} -> {{ic|Microsoft Network Server}} -> {{ic|Digital sign communication (Always)}} -> activate {{ic|define this policy}} and use the {{ic|disable}} radio button.<br />
<br />
If you use Windows Server 2008 R2, you need to modify that in GPO for Default Domain Controller Policy -> Computer Setting -> Policies -> Windows Setting -> Security Setting -> Local Policies -> Security Option -> ''Microsoft network client: Digitally sign communications (always)''<br />
<br />
=== Linux Host Configuration ===<br />
<br />
The next few steps will begin the process of configuring the Host. You will need root or sudo access to complete these steps.<br />
<br />
=== Installation ===<br />
<br />
[[Pacman|Install]] the following packages:<br />
* {{Pkg|samba}}, see also [[Samba]]<br />
* {{Aur|pam-krb5}} from the [[AUR]]<br />
* {{Pkg|ntp}} or {{Pkg|openntpd}}, see also [[NTPd]] or [[OpenNTPD]]<br />
<br />
=== Updating DNS ===<br />
<br />
Active Directory is heavily dependent upon DNS. You will need to update {{ic|/etc/resolv.conf}} to use one or more of the Active Directory domain controllers:<br />
{{hc|/etc/resolv.conf|<br />
nameserver <IP1><br />
nameserver <IP2><br />
}}<br />
Replacing <IP1> and <IP2> with valid IP addresses for the AD servers. If your AD domains do not permit DNS forwarding or recursion, you may need to add additional resolvers. <br />
<br />
{{Note|If your machine dual boots Windows and Linux, you should use a different DNS hostname and netbios name for the linux configuration if both operating systems will be members of the same domain.}}<br />
<br />
=== Configuring NTP ===<br />
Read [[NTPd]] or [[OpenNTPD]] to configure a NTP service. Note that OpenNTPD is no longer maintained.<br />
<br />
On the configuration, use the IP addresses for the AD servers. Alternatively, you can use other known NTP servers provided the Active directory servers sync to the same stratum. However, AD servers typically run NTP as a service.<br />
<br />
Ensure the daemon is configured to '''sync automatically on startup'''.<br />
<br />
=== Kerberos ===<br />
<br />
Let's assume that your AD is named example.com. Let's further assume your AD is ruled by two domain controllers, the primary and secondary one, which are named PDC and BDC, pdc.example.com and bdc.example.com respectively. Their IP adresses will be 192.168.1.2 and 192.168.1.3 in this example. Take care to watch your syntax; upper-case is very important here.<br />
<br />
{{hc|/etc/krb5.conf|<nowiki><br />
[libdefaults]<br />
default_realm = EXAMPLE.COM<br />
clockskew = 300<br />
ticket_lifetime = 1d<br />
forwardable = true<br />
proxiable = true<br />
dns_lookup_realm = true<br />
dns_lookup_kdc = true<br />
<br />
[realms]<br />
EXAMPLE.COM = {<br />
kdc = PDC.EXAMPLE.COM<br />
admin_server = PDC.EXAMPLE.COM<br />
default_domain = EXAMPLE.COM<br />
}<br />
<br />
[domain_realm]<br />
.kerberos.server = EXAMPLE.COM<br />
.example.com = EXAMPLE.COM<br />
example.com = EXAMPLE.COM<br />
example = EXAMPLE.COM<br />
<br />
[appdefaults]<br />
pam = {<br />
ticket_lifetime = 1d<br />
renew_lifetime = 1d<br />
forwardable = true<br />
proxiable = false<br />
retain_after_close = false<br />
minimum_uid = 0<br />
debug = false<br />
}<br />
<br />
[logging]<br />
default = FILE:/var/log/krb5libs.log<br />
kdc = FILE:/var/log/kdc.log<br />
admin_server = FILE:/var/log/kadmind.log<br />
</nowiki>}}<br />
<br />
{{Note|Heimdal 1.3.1 deprecated DES encryption which is required for AD authentication before Windows Server 2008. You'll probably have to add {{bc|1=allow_weak_crypto = true}} to the {{Ic|[libdefaults]}} section.}}<br />
<br />
==== Creating a Kerberos Ticket ====<br />
Now you can query the AD domain controllers and request a kerberos ticket ('''uppercase is necessary'''):<br />
{{bc|kinit administrator@EXAMPLE.COM}}<br />
<br />
You can use any username that has rights as a Domain Administrator.<br />
<br />
==== Validating the Ticket ====<br />
Run '''klist''' to verify you did receive the token. You should see something similar to:<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: administrator@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
=== pam_winbind.conf ===<br />
<br />
If you get errors stating that /etc/security/pam_winbind.conf was not found, create the file and add the following:<br />
<br />
{{hc|/etc/security/pam_winbind.conf|<nowiki><br />
debug=no<br />
debug_state=no<br />
try_first_pass=yes<br />
krb5_auth=yes<br />
krb5_cache_type=FILE<br />
cached_login=yes<br />
silent=no<br />
mkhomedir=yes<br />
</nowiki>}}<br />
<br />
<br />
=== Samba ===<br />
Samba is a free software re-implementation of the SMB/CIFS networking protocol. It also includes tools for Linux machines to act as Windows networking servers and clients.<br />
<br />
{{Note|The configuration can vary greatly depending on how the Windows environment is deployed. Be prepared to troubleshoot and research}}<br />
<br />
In this section, we will focus on getting Authentication to work first by editing the 'Global' section first. Later, we will go back and add shares.<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
<br />
idmap config * : backend = rid<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
We shall now explain to Samba that it shall use the PDC´s database for authentication queries. Again, we use winbindd which is a part of the samba package. Winbind maps the UID and GID of the AD to our Linux-machine. Winbind uses a Unix-implementation of RPC-calls, Pluggable Authentication Modules (aka PAM) and Name Service Switch (NSS) to allow Windows AD and users accessing and to grant permissions on the Linux-machine. The best part of winbindd is, that you don´t have to define the mapping yourself, but only define a range of UID and GID. That´s what we defined in smb.conf.<br />
<br />
Update the samba configuration file to enable the winbind daemon<br />
<br />
{{hc|/etc/conf.d/samba|<nowiki><br />
##### /etc/conf.d/samba #####<br />
#SAMBA_DAEMONS=(smbd nmbd)<br />
SAMBA_DAEMONS=(smbd nmbd winbindd)<br />
</nowiki>}}<br />
<br />
Next, configure {{ic|samba}} to startup at boot. Read [[Daemons]] for more details.<br />
<br />
== Starting and testing services ==<br />
<br />
=== Starting Samba ===<br />
<br />
Hopefully, you have not rebooted yet! Fine. If you are in an X-session, quit it, so you can test login into another console, while you are still logged in.<br />
<br />
[[Daemons|Start]] Samba (including smbd, nmbd and winbindd):<br />
<br />
If you check the processes, you'll see that winbind did not actually start. A quick review of the logs shows that the SID for this host could be obtained from the domain:<br />
{{hc|# tail /var/log/samba/log.winbindd|<br />
[2012/02/05 21:51:30.085574, 0] winbindd/winbindd_cache.c:3147(initialize_winbindd_cache)<br />
initialize_winbindd_cache: clearing cache and re-creating with version number 2<br />
[2012/02/05 21:51:30.086137, 2] winbindd/winbindd_util.c:233(add_trusted_domain)<br />
Added domain BUILTIN S-1-5-32<br />
[2012/02/05 21:51:30.086223, 2] winbindd/winbindd_util.c:233(add_trusted_domain)<br />
Added domain MYARCHLINUX S-1-5-21-3777857242-3272519233-2385508432<br />
[2012/02/05 21:51:30.086254, 0] winbindd/winbindd_util.c:635(init_domain_list)<br />
Could not fetch our SID - did we join?<br />
[2012/02/05 21:51:30.086408, 0] winbindd/winbindd.c:1105(winbindd_register_handlers)<br />
unable to initialize domain list<br />
}}<br />
<br />
=== Join the Domain ===<br />
<br />
You need an AD Administrator account to do this. Let's assume this is named Administrator. The command is 'net ads join'<br />
{{hc|# net ads join -U Administrator|<br />
Administrator's password: xxx<br />
Using short domain name -- EXAMPLE<br />
Joined 'MYARCHLINUX' to realm 'EXAMPLE.COM'<br />
}}<br />
<br />
See screenshot of Active Directory Users and Computers<br />
[[http://en.wikipedia.org/wiki/File:Ads_myarchlinux_computer_account.png]]<br />
<br />
=== Restart Samba ===<br />
'''winbindd''' failed to start on the first try because we were not yet a domain. <br />
<br />
[[Daemons|Restart]] the Samba service and winbind should fire up as well.<br />
<br />
NSSwitch tells the Linux host how to retrieve information from various sources and in which order to do so. In this case, we are appending Active Directory as additional sources for Users, Groups, and Hosts.<br />
{{hc|/etc/nsswitch.conf|<br />
passwd: files winbind<br />
shadow: files winbind<br />
group: files winbind <br />
<br />
hosts: files dns wins<br />
}}<br />
<br />
=== Testing Winbind ===<br />
Let's check if winbind is able to query the AD. The following command should return a list of AD users:<br />
<br />
{{hc|# wbinfo -u|<br />
administrator<br />
guest<br />
krbtgt<br />
test.user<br />
}}<br />
* Note we created an Active Directory user called 'test.user' on the domain controller<br />
<br />
We can do the same for AD groups:<br />
<br />
{{hc|# wbinfo -g|<br />
domain computers<br />
domain controllers<br />
schema admins<br />
enterprise admins<br />
cert publishers<br />
domain admins<br />
domain users<br />
domain guests<br />
group policy creator owners<br />
ras and ias servers<br />
allowed rodc password replication group<br />
denied rodc password replication group<br />
read-only domain controllers<br />
enterprise read-only domain controllers<br />
dnsadmins<br />
dnsupdateproxy<br />
}}<br />
<br />
=== Testing nsswitch ===<br />
<br />
To ensure that our host is able to query the domain for users and groups, we test nsswitch settings by issuing the 'getent' command. The following output shows what a stock ArchLinux install looks like:<br />
<br />
{{hc|# getent passwd|<br />
root:x:0:0:root:/root:/bin/bash<br />
bin:x:1:1:bin:/bin:/bin/false<br />
daemon:x:2:2:daemon:/sbin:/bin/false<br />
mail:x:8:12:mail:/var/spool/mail:/bin/false<br />
ftp:x:14:11:ftp:/srv/ftp:/bin/false<br />
http:x:33:33:http:/srv/http:/bin/false<br />
nobody:x:99:99:nobody:/:/bin/false<br />
dbus:x:81:81:System message bus:/:/bin/false<br />
ntp:x:87:87:Network Time Protocol:/var/empty:/bin/false<br />
avahi:x:84:84:avahi:/:/bin/false<br />
administrator:*:10001:10006:Administrator:/home/EXAMPLE/administrator:/bin/bash<br />
guest:*:10002:10007:Guest:/home/EXAMPLE/guest:/bin/bash<br />
krbtgt:*:10003:10006:krbtgt:/home/EXAMPLE/krbtgt:/bin/bash<br />
test.user:*:10000:10006:Test User:/home/EXAMPLE/test.user:/bin/bash<br />
}}<br />
<br />
And for groups:<br />
{{hc|# getent group|<br />
root:x:0:root<br />
bin:x:1:root,bin,daemon<br />
daemon:x:2:root,bin,daemon<br />
sys:x:3:root,bin<br />
adm:x:4:root,daemon<br />
tty:x:5:<br />
disk:x:6:root<br />
lp:x:7:daemon<br />
mem:x:8:<br />
kmem:x:9:<br />
wheel:x:10:root<br />
ftp:x:11:<br />
mail:x:12:<br />
uucp:x:14:<br />
log:x:19:root<br />
utmp:x:20:<br />
locate:x:21:<br />
rfkill:x:24:<br />
smmsp:x:25:<br />
http:x:33:<br />
games:x:50:<br />
network:x:90:<br />
video:x:91:<br />
audio:x:92:<br />
optical:x:93:<br />
floppy:x:94:<br />
storage:x:95:<br />
scanner:x:96:<br />
power:x:98:<br />
nobody:x:99:<br />
users:x:100:<br />
dbus:x:81:<br />
ntp:x:87:<br />
avahi:x:84:<br />
domain computers:x:10008:<br />
domain controllers:x:10009:<br />
schema admins:x:10010:administrator<br />
enterprise admins:x:10011:administrator<br />
cert publishers:x:10012:<br />
domain admins:x:10013:test.user,administrator<br />
domain users:x:10006:<br />
domain guests:x:10007:<br />
group policy creator owners:x:10014:administrator<br />
ras and ias servers:x:10015:<br />
allowed rodc password replication group:x:10016:<br />
denied rodc password replication group:x:10017:krbtgt<br />
read-only domain controllers:x:10018:<br />
enterprise read-only domain controllers:x:10019:<br />
dnsadmins:x:10020:<br />
dnsupdateproxy:x:10021:<br />
}}<br />
<br />
=== Testing Samba commands ===<br />
<br />
Try out some net commands to see if Samba can communicate with AD:<br />
<br />
{{hc|# net ads info|<nowiki><br />
[2012/02/05 20:21:36.473559, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
LDAP server: 192.168.1.2<br />
LDAP server name: PDC.example.com<br />
Realm: EXAMPLE.COM<br />
Bind Path: dc=EXAMPLE,dc=COM<br />
LDAP port: 389<br />
Server time: Sun, 05 Feb 2012 20:21:33 CST<br />
KDC server: 192.168.1.2<br />
Server time offset: -3<br />
</nowiki>}}<br />
<br />
{{hc|# net ads lookup|<br />
[2012/02/05 20:22:39.298823, 0] param/loadparm.c:7599(lp_do_parameter)<br />
Ignoring unknown parameter "idmapd backend"<br />
Information for Domain Controller: 192.168.1.2<br />
<br />
Response Type: LOGON_SAM_LOGON_RESPONSE_EX<br />
GUID: 2a098512-4c9f-4fe4-ac22-8f9231fabbad<br />
Flags:<br />
Is a PDC: yes<br />
Is a GC of the forest: yes<br />
Is an LDAP server: yes<br />
Supports DS: yes<br />
Is running a KDC: yes<br />
Is running time services: yes<br />
Is the closest DC: yes<br />
Is writable: yes<br />
Has a hardware clock: yes<br />
Is a non-domain NC serviced by LDAP server: no<br />
Is NT6 DC that has some secrets: no<br />
Is NT6 DC that has all secrets: yes<br />
Forest: example.com<br />
Domain: example.com<br />
Domain Controller: PDC.example.com<br />
Pre-Win2k Domain: EXAMPLE<br />
Pre-Win2k Hostname: PDC<br />
Server Site Name : Office<br />
Client Site Name : Office<br />
NT Version: 5<br />
LMNT Token: ffff<br />
LM20 Token: ffff<br />
}}<br />
<br />
{{hc|<nowiki># net ads status -U administrator | less</nowiki>|<nowiki><br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: user<br />
objectClass: computer<br />
cn: myarchlinux<br />
distinguishedName: CN=myarchlinux,CN=Computers,DC=leafscale,DC=inc<br />
instanceType: 4<br />
whenCreated: 20120206043413.0Z<br />
whenChanged: 20120206043414.0Z<br />
uSNCreated: 16556<br />
uSNChanged: 16563<br />
name: myarchlinux<br />
objectGUID: 2c24029c-8422-42b2-83b3-a255b9cb41b3<br />
userAccountControl: 69632<br />
badPwdCount: 0<br />
codePage: 0<br />
countryCode: 0<br />
badPasswordTime: 0<br />
lastLogoff: 0<br />
lastLogon: 129729780312632000<br />
localPolicyFlags: 0<br />
pwdLastSet: 129729764538848000<br />
primaryGroupID: 515<br />
objectSid: S-1-5-21-719106045-3766251393-3909931865-1105<br />
...<snip>...<br />
</nowiki>}}<br />
<br />
== Configuring PAM ==<br />
<br />
Now we will change various rules in PAM to allow Active Directory users to use the system for things like login and sudo access. When changing the rules, note the order of these items and whether they are marked as '''required''' or '''sufficient''' is critical to things working as expected. You should not deviate from these rules unless you know how to write PAM rules.<br />
<br />
In case of logins, PAM should first ask for AD accounts, and for local accounts if no matching AD account was found. Therefore, we add entries to include {{ic|pam_winbindd.so}} into the authentication process. Furthermore, we include pam_mkhomedir.so. If an AD user logs in, {{ic|/home/example/user}} will be created automatically.<br />
<br />
{{hc|/etc/pam.d/login|<nowiki><br />
#%PAM-1.0<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth sufficient pam_unix.so nullok<br />
auth required pam_winbind.so use_first_pass use_authtok<br />
auth required pam_tally.so onerr=succeed file=/var/log/faillog<br />
# use this to lockout accounts for 10 minutes after 3 failed attempts<br />
#auth required pam_tally.so deny=2 unlock_time=600 onerr=succeed file=/var/log/faillog<br />
account required pam_access.so<br />
account required pam_time.so<br />
account sufficient pam_unix.so<br />
account sufficient pam_winbind.so use_first_pass use_authtok<br />
password sufficient pam_unix.so<br />
password sufficient pam_winbind.so use_first_pass use_authtok<br />
password required pam_cracklib.so retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
session required pam_mkhomedir.so skel=/etc/skel/ umask=0022<br />
session sufficient pam_unix.so<br />
session sufficient pam_winbind.so use_first_pass use_authtok<br />
session required pam_env.so<br />
session required pam_motd.so<br />
session required pam_limits.so<br />
session optional pam_mail.so dir=/var/spool/mail standard<br />
session optional pam_lastlog.so<br />
session optional pam_loginuid.so<br />
-session optional pam_ck_connector.so nox11<br />
-session optional pam_systemd.so<br />
</nowiki>}}<br />
<br />
=== Testing login ===<br />
Now, start a new console session (or ssh) and try to login using the AD credentials. The domain name is optional, as this was set in the Winbind configuration as 'default realm'. Please note that in the case of ssh, you will need to modify the {{ic|/etc/ssh/sshd_config}} file to allow kerberos authentication {{ic|(KerberosAuthentication yes)}}.<br />
<br />
{{bc|<br />
test.user<br />
EXAMPLE+test.user<br />
}}<br />
<br />
Both should work. You should notice that {{ic|/home/example/test.user}} will be automatically created. Again, if you are using ssh, you need to add the pam_mkhomedir.so line mentioned above to the /etc/pam.d/sshd file.<br />
'''Log into another session using an linux account. Check that you still be able to log in as root - but keep in mind to be logged in as root in at least one session!'''<br />
<br />
=== /etc/pam.d/gdm ===<br />
The only way I could get gdm to accept winbind logons was to install authconfig. This created a system-auth considerably different to the KDE example.<br />
<br />
=== /etc/pam.d/kde ===<br />
to login in graphical session using KDM, you need to update your related pam configuration file : {{ic|/etc/pam.d/system-auth}}.<br />
<br />
in fact, the {{ic|/etc/pam.d/kde}} include {{ic|/etc/pam.d/system-login}} which include {{ic|/etc/pam.d/system-auth}}.<br />
<br />
the logic in this file is to put {{ic|pam_winbind.so use_first_pass use_authtok}} after {{ic|pam_unix.so}}, and make sure that {{ic|pam_unix.so}} is {{ic|sufficient}}, and {{ic|pam_winbind.so}} is {{ic|required}}.<br />
<br />
{{hc|/etc/pam.d/system-auth|<nowiki><br />
#%PAM-1.0<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth sufficient pam_unix.so nullok<br />
auth required pam_winbind.so use_first_pass use_authtok<br />
auth required pam_tally.so onerr=succeed file=/var/log/faillog<br />
# use this to lockout accounts for 10 minutes after 3 failed attempts<br />
# #auth required pam_tally.so deny=2 unlock_time=600 onerr=succeed file=/var/log/faillog<br />
account required pam_access.so<br />
account required pam_time.so<br />
account sufficient pam_unix.so<br />
account sufficient pam_winbind.so use_first_pass use_authtok<br />
#<br />
<br />
password sufficient pam_unix.so<br />
password sufficient pam_winbind.so use_first_pass use_authtok<br />
<br />
<br />
session include system-login<br />
session optional pam_winbind.so<br />
<br />
</nowiki>}}<br />
<br />
=== Sudo ===<br />
Another thing to get working is 'sudo'. First add the 'test.user' to /etc/sudoers. You can tweak this later, for now lets test things are working:<br />
<br />
{{bc|/etc/sudoers|<nowiki><br />
##<br />
## User privilege specification<br />
##<br />
root ALL=(ALL) ALL<br />
test.user ALL=(ALL) ALL<br />
</nowiki>}}<br />
<br />
If you were to attempt a sudo now, it would fail. <br />
<br />
Adjust the sudo file to mark {{ic|pam_unix}} as sufficient and add the line for {{ic|winbind}} as shown:<br />
<br />
{{hc|/etc/pam.d/sudo|<nowiki><br />
#%PAM-1.0<br />
auth sufficient pam_unix.so<br />
auth required pam_winbind.so use_first_pass use_authtok<br />
auth required pam_nologin.so<br />
</nowiki>}}<br />
<br />
== Configuring Shares ==<br />
Earlier we skipped configuration of the shares. Now that things are working, go back to {{ic|/etc/smb.conf}}, and add the exports for the host that you want available on the windows network. <br />
<br />
{{hc|/etc/smb.conf|<nowiki><br />
[MyShare]<br />
comment = Example Share<br />
path = /srv/exports/myshare<br />
read only = no<br />
browseable = yes<br />
valid users = @NETWORK+"Domain Admins" NETWORK+test.user<br />
</nowiki>}}<br />
<br />
In the above example, the keyword '''NETWORK''' is to be used. Do not mistakenly substitute this with your domain name. For adding groups, prepend the '@' symbol to the group. Note that {{ic|Domain Admins}} is encapsulated in quotes so Samba correctly parses it when reading the configuration file.<br />
<br />
<br />
== Adding a machine keytab file and activating password-free kerberized ssh to the machine ==<br />
This explains how to generate a machine keytab file which you will need e.g. to enable password-free kerberized ssh to your machine from other machines in the domain. The scenario in mind is that you have a bunch of systems in your domain and you just added a server/workstation using the above description to your domain onto which a lot of users need to ssh in order to work - e.g. GPU workstation or an OpenMP compute node, etc. In this case you might not want to type your password every time you log in. On the other hand the key authentication used by many users in this case can not give you the necessary credentials to e.g. mount kerberized NFSv4 shares. So this will help you to enable password-free logins from your clients to the machine in question using kerberos ticket forwarding.<br />
<br />
=== Creating a machine key tab file ===<br />
run 'net ads keytab create -U administrator' as root to create a machine keytab file in /etc/krb5.keytab. It will promt you with a warning that we need to enable keytab authentication in our configuration file, so we will do that in the next step. In my case it had problems when a key tab file is already in place - the command just did not come back it hang ... In that case you should rename the existing /etc/krb5.keytab and run the command again - it should work now.<br />
<br />
{{bc|# net ads keytab create -U administrator}}<br />
<br />
verify the content of your keytab by running:<br />
<br />
{{hc|# klist -k /etc/krb5.keytab|<nowiki><br />
Keytab name: FILE:/etc/krb5.keytab<br />
KVNO Principal<br />
---- --------------------------------------------------------------------------<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/myarchlinux.example.com@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 host/MYARCHLINUX@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
4 MYARCHLINUX$@EXAMPLE.COM<br />
</nowiki>}}<br />
<br />
=== Enabling keytab authentication ===<br />
{{Out of date|The option "use kerberos keytab" no longer exists, and should be replaced by "kerberos method". See https://lists.samba.org/archive/samba/2012-January/165640.html}}<br />
Now you need to tell winbind to use the file by adding this line to the /etc/samba/smb.conf:<br />
<br />
use kerberos keytab = true<br />
<br />
It should look sth. like this:<br />
<br />
{{hc|/etc/samba/smb.conf|<nowiki><br />
[Global]<br />
netbios name = MYARCHLINUX<br />
workgroup = EXAMPLE<br />
realm = EXAMPLE.COM<br />
server string = %h ArchLinux Host<br />
security = ads<br />
encrypt passwords = yes<br />
password server = pdc.example.com<br />
use kerberos keytab = true<br />
<br />
idmap config * : backend = tdb<br />
idmap config * : range = 10000-20000<br />
<br />
winbind use default domain = Yes<br />
winbind enum users = Yes<br />
winbind enum groups = Yes<br />
winbind nested groups = Yes<br />
winbind separator = +<br />
winbind refresh tickets = yes<br />
<br />
template shell = /bin/bash<br />
template homedir = /home/%D/%U<br />
<br />
preferred master = no<br />
dns proxy = no<br />
wins server = pdc.example.com<br />
wins proxy = no<br />
<br />
inherit acls = Yes<br />
map acl inherit = Yes<br />
acl group control = yes<br />
<br />
load printers = no<br />
debug level = 3<br />
use sendfile = no<br />
</nowiki>}}<br />
<br />
Restart the winbind.service using 'systemctl restart winbind.service' with root privileges.<br />
<br />
{{bc|# systemctl restart winbind.service}}<br />
<br />
Check if everything works by getting a machine ticket for your system by running <br />
<br />
{{bc|# kinit MYARCHLINUX$ -kt /etc/krb5.keytab}}<br />
<br />
This should not give you any feedback but running 'klist' should show you sth like:<br />
<br />
{{hc|# klist|<br />
Ticket cache: FILE:/tmp/krb5cc_0<br />
Default principal: MYARCHLINUX$@EXAMPLE.COM<br />
<br />
Valid starting Expires Service principal <br />
02/04/12 21:27:47 02/05/12 07:27:42 krbtgt/EXAMPLE.COM@EXAMPLE.COM<br />
renew until 02/05/12 21:27:47<br />
}}<br />
<br />
Some common mistakes here are a) forgetting the trailing $ or b) ignoring case sensitivity - it needs to look exactly like the entry in the keytab (usually you cannot to much wrong with all capital)<br />
<br />
=== Preparing sshd on server ===<br />
<br />
All we need to do is add some options to our sshd_config and restart the sshd.service.<br />
<br />
Edit /etc/ssh/sshd_config to look like this in the appropriate places:<br />
<br />
{{hc|# /etc/ssh/sshd_config|<br />
<br />
...<br />
<br />
# Change to no to disable s/key passwords<br />
ChallengeResponseAuthentication no<br />
<br />
# Kerberos options<br />
KerberosAuthentication yes<br />
#KerberosOrLocalPasswd yes<br />
KerberosTicketCleanup yes<br />
KerberosGetAFSToken yes<br />
<br />
# GSSAPI options<br />
GSSAPIAuthentication yes<br />
GSSAPICleanupCredentials yes<br />
<br />
...<br />
<br />
}}<br />
<br />
Restart the sshd.service using:<br />
<br />
{{bc|# systemctl restart sshd.service}}<br />
<br />
=== Adding necessary options on client ===<br />
<br />
First we need to make sure that the tickets on our client are forwardable. This is usually standard but we better check anyways. You have to look for the forwardable option and set it to 'true'<br />
<br />
{{bc|<nowiki>forwardable = true</nowiki>}}<br />
<br />
Secondly we need to add the options <br />
<br />
GSSAPIAuthentication yes<br />
GSSAPIDelegateCredentials yes<br />
<br />
to our .ssh/config file to tell ssh to use this options - alternatively they can be invoked using the -o options directly in the ssh command (see 'man ssh' for help).<br />
<br />
=== Testing the setup ===<br />
On Client:<br />
<br />
make sure you have a valid ticket - if in doubt run 'kinit'<br />
<br />
then use ssh to connect to you machine<br />
<br />
{{bc|ssh myarchlinux.example.com }}<br />
<br />
you should get connected without needing to enter your password.<br />
<br />
if you have key authentication additionally activated then you should perform<br />
<br />
{{bc|ssh -v myarchlinux.example.com }}<br />
<br />
to see which authentication method it actually uses.<br />
<br />
For debugging you can enable DEBUG3 on the server and look into the journal using journalctl <br />
<br />
=== Nifty fine-tuning for complete password-free kerberos handling. ===<br />
<br />
In case your clients are not using domain accounts on their local machines (for whatever reason) it can be hard to actually teach them to kinit before ssh to the workstation. Therefore I came up with a nice workaround:<br />
<br />
== Generating user Keytabs which are accepted by AD ==<br />
<br />
On a system let the user run:<br />
<br />
{{bc|<nowiki><br />
ktutil<br />
addent -password -p username@EXAMPLE.COM -k 1 -e RC4-HMAC<br />
- enter password for username -<br />
wkt username.keytab<br />
q<br />
</nowiki>}}<br />
<br />
Now test the file by invoking:<br />
<br />
{{bc|kinit -kt username.keytab}}<br />
<br />
It should not promt you to give your password nor should it give any other feedback. If it worked you are basically done - just put the line above into your ~./bashrc - you can now get kerberos tickets without typing a password and with that you can connect to your workstation without typing a password while being completely kerberized and able to authenticate against NFSv4 and CIFS via tickets - pretty neat.<br />
<br />
=== Nice to know ===<br />
<br />
The file 'username.keytab' is not machinespecific and can therefore be copied around. E.g. we created the files on a linux machine and copied them to our Mac clients as the commands on Macs are different ...<br />
<br />
<br />
== See also ==<br />
<br />
* [http://en.wikipedia.org/wiki/Active_Directory Wikipedia: Active Directory]<br />
* [http://en.wikipedia.org/wiki/Samba_(software) Wikipedia: Samba]<br />
* [http://en.wikipedia.org/wiki/Kerberos_(protocol) Wikipedia: Kerberos]<br />
* [http://www.samba.org/samba/docs Samba: Documentation]<br />
* [http://wiki.samba.org/index.php/Samba_&_Active_Directory Samba Wiki: Samba & Active Directory]<br />
* [http://www.samba.org/samba/docs/man/manpages-3/smb.conf.5.html Samba Man Page: smb.conf]<br />
=== Commercial Solutions ===<br />
* Centrify<br />
* Likewise</div>Nahanthttps://wiki.archlinux.org/index.php?title=NetworkManager&diff=284280NetworkManager2013-11-23T10:21:57Z<p>Nahant: Added tip when using KDE NetworkManager applet in combination with OpenConnect VPN</p>
<hr />
<div>[[Category:Networking]]<br />
[[cs:NetworkManager]]<br />
[[de:Networkmanager]]<br />
[[es:NetworkManager]]<br />
[[fr:NetworkManager]]<br />
[[it:NetworkManager]]<br />
[[ja:NetworkManager]]<br />
[[pt:NetworkManager]]<br />
[[ru:NetworkManager]]<br />
[[tr:NetworkManager]]<br />
[[zh-CN:NetworkManager]]<br />
{{Related articles start}}<br />
{{Related|Network Configuration}}<br />
{{Related|Wireless Setup}}<br />
{{Related|Netctl}}<br />
{{Related|Wicd}}<br />
{{Related articles end}}<br />
<br />
[http://projects.gnome.org/NetworkManager/ NetworkManager] is a program for providing detection and configuration for systems to automatically connect to network. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the [[GNOME]] project.<br />
<br />
== Base install ==<br />
<br />
NetworkManager can be installed with the package {{Pkg|networkmanager}}, available in the [[official repositories]].<br />
<br />
=== VPN support ===<br />
<br />
Network Manager VPN support is based on a plug-in system. If you need VPN support via network manager you have to install one of the following packages from the [[official repositories]]:<br />
<br />
* {{Pkg|networkmanager-openconnect}}<br />
* {{Pkg|networkmanager-openvpn}}<br />
* {{Pkg|networkmanager-pptp}}<br />
* {{Pkg|networkmanager-vpnc}}<br />
<br />
== Graphical front-ends ==<br />
<br />
To configure and have easy access to NetworkManager most people will want to install an applet. This GUI front-end usually resides in the system tray (or notification area) and allows network selection and configuration of NetworkManager. Various applets exist for different types of desktops.<br />
<br />
=== GNOME ===<br />
<br />
GNOME's {{Pkg|network-manager-applet}} is lightweight enough and works across all environments.<br />
<br />
If you want to store authentication details (Wireless/DSL) and enable global connection settings, i.e "available to all users" install and configure [[GNOME Keyring]].<br />
<br />
=== KDE ===<br />
<br />
The Plasma-nm front-end is a Plasma widget available in the official repositories as package {{Pkg|kdeplasma-applets-plasma-nm}}. The older KNetworkManager front-end Plasma widget is also available as package {{aur|kdeplasma-applets-networkmanagement}} from the aur.<br />
<br />
If you have both the Plasma widget and {{ic|nm-applet}} installed and do not want to start {{ic|nm-applet}} when using KDE, add the following line to {{ic|/etc/xdg/autostart/nm-applet.desktop}}:<br />
NotShowIn=KDE<br />
<br />
See [http://userbase.kde.org/NetworkManagement Userbase page] for more info.<br />
<br />
=== XFCE ===<br />
{{Pkg|network-manager-applet}} will work fine in XFCE, but in order to see notifications, ''including error messages'', {{ic|nm-applet}} needs an implementation of the Freedesktop desktop notifications specification (see the [http://www.galago-project.org/specs/notification/0.9/index.html Galapago Project]) to display them. To enable notifications install {{Pkg|xfce4-notifyd}}, a package that provides an implementation for the specification.<br />
<br />
Without such a notification daemon, {{ic|nm-applet}} outputs the following errors to stdout/stderr:<br />
<br />
(nm-applet:24209): libnotify-WARNING **: Failed to connect to proxy<br />
** (nm-applet:24209): WARNING **: get_all_cb: couldn't retrieve<br />
system settings properties: (25) Launch helper exited with unknown<br />
return code 1.<br />
** (nm-applet:24209): WARNING **: fetch_connections_done: error<br />
fetching connections: (25) Launch helper exited with unknown return<br />
code 1.<br />
** (nm-applet:24209): WARNING **: Failed to register as an agent:<br />
(25) Launch helper exited with unknown return code 1<br />
<br />
{{ic|nm-applet}} will still work fine, though, but without notifications.<br />
<br />
If nm-applet is not prompting for a password when connecting to new wifi networks, and is just disconnecting immediately, you probably need to install {{Pkg|gnome-keyring}}.<br />
<br />
=== Openbox ===<br />
<br />
To function properly in Openbox, the GNOME applet requires the {{Pkg|xfce4-notifyd}} notification daemon for the same reason as in XFCE and the {{Pkg|gnome-icon-theme}} package to be able to display the applet in the systray.<br />
<br />
If you want to store authentication details (Wireless/DSL) install and configure [[gnome-keyring]].<br />
<br />
{{ic|nm-applet}} installs the autostart file at {{ic|/etc/xdg/autostart/nm-applet.desktop}}. If you have issues with it (e.g. {{ic|nm-applet}} is started twice or is not started at all), see [[Openbox#Autostart directory]] or [https://bbs.archlinux.org/viewtopic.php?pid=993738] for solution.<br />
<br />
=== Other desktops and window managers ===<br />
<br />
In all other scenarios it is recommended to use the GNOME applet. You will also need to be sure that the {{Pkg|gnome-icon-theme}} package is installed to be able to display the applet.<br />
<br />
To store connection secrets install and configure [[gnome-keyring]].<br />
<br />
In order to run {{ic|nm-applet}} without a systray, you can use {{Pkg|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:<br />
{{hc|nmgui|<nowiki><br />
#!/bin/sh<br />
nm-applet > /dev/null 2>/dev/null &<br />
stalonetray > /dev/null 2>/dev/null<br />
killall nm-applet<br />
</nowiki>}}<br />
<br />
When you close the stalonetray window, it closes {{ic|nm-applet}} too, so no extra memory is used once you are done with network settings.<br />
<br />
=== Command line ===<br />
<br />
The {{Pkg|networkmanager}} package contains [http://manpages.ubuntu.com/manpages/maverick/man1/nmcli.1.html nmcli] since version 0.8.1.<br />
<br />
== Configuration ==<br />
<br />
NetworkManager will require some additional steps to be able run properly.<br />
<br />
Verify that your {{ic|/etc/hosts}} is correct before continuing. If you previously tried to connect before doing this step, NetworkManager may have altered it. An example hostname line in {{ic|/etc/hosts}}:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 localhost<br />
::1 localhost<br />
}}<br />
<br />
In case you have nss-myhostname turned off, the line would look like:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 my-laptop localhost<br />
::1 my-laptop localhost<br />
}}<br />
<br />
{{Note|It may be a good idea to use {{ic|1=systemctl --type=service}} to ensure that no other service is running that may want to configure the network. Multiple networking services will conflict.}}<br />
<br />
=== Enable NetworkManager ===<br />
<br />
Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need {{ic|nmcli}} or an applet to configure and connect.<br />
<br />
You can enable NetworkManager at startup with the following command:<br />
<br />
{{bc|# systemctl enable NetworkManager}}<br />
<br />
You can start the NetworkManager daemon immediately with the following command:<br />
<br />
{{bc|# systemctl start NetworkManager}}<br />
<br />
==== Avoid warnings ====<br />
<br />
NetworkManager will print probably meaningless [https://bugs.archlinux.org/task/34971 warnings (Bug#34971)] to your system log, when [[Networkmanager#Network_services_with_NetworkManager_dispatcher|NetworkManager-dispatcher.service]] and [https://www.archlinux.org/packages/?name=modemmanager ModemManager.service] are not enabled. To keep the log clean and suppress this messages, enable both, even if they are not required by your environment:<br />
<br />
{{bc|# systemctl enable NetworkManager-dispatcher.service && systemctl enable ModemManager.service}}<br />
{{bc|# systemctl start NetworkManager-dispatcher.service && systemctl start ModemManager.service}}<br />
<br />
=== Enable NetworkManager Wait Online ===<br />
If you have services which fail if they are started before the network is up, you have to use {{ic|NetworkManager-wait-online.service}} in addition to the NetworkManager service. This is however hardly ever necessary since most network daemons start up fine, even if the network has not been configured yet.<br />
<br />
You can enable NetworkManager Wait Online at startup with the following command:<br />
<br />
{{bc|# systemctl enable NetworkManager-wait-online}}<br />
<br />
In some cases the service will still fail to start sucessfully on boot:<br />
<br />
NetworkManager-wait-online.service: main process exited, code=exited, status=1/FAILURE<br />
Failed to start Network Manager Wait Online<br />
Unit NetworkManger-wait-online.service entered failed state<br />
Starting Network.<br />
Reached target Network.<br />
<br />
This is due to the timeout setting in {{ic|/usr/lib/systemd/system/NetworkManager-wait-online.service}} being too short. Change the default timeout from 30 to a higher value.<br />
<br />
=== Set up PolicyKit permissions ===<br />
<br />
See [[General Troubleshooting#Session permissions]] for setting up a working session.<br />
<br />
With a working session, you have several options for granting the necessary privileges to NetworkManager:<br />
<br />
''Option 1.'' Run a [[PolicyKit]] authentication agent when you log in, such as {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}} (part of {{Pkg|polkit-gnome}}). You will be prompted for your password whenever you add or remove a network connection.<br />
<br />
''Option 2.'' Add yourself to the {{ic|wheel}} group. You will not have to enter your password, but your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.<br />
<br />
''Option 3.'' Add yourself to the {{ic|network}} group and create the following file:<br />
{{hc|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {<br />
return polkit.Result.YES;<br />
}<br />
});</nowiki>}}<br />
All users in the {{ic|network}} group will be able to add and remove networks without a password. This will not work under systemd if you do not have an active session with [[Systemd#Using_systemd-logind|systemd-logind]].<br />
<br />
=== Network services with NetworkManager dispatcher===<br />
<br />
There are quite a few network services that you will not want running until NetworkManager brings up an interface. Good examples are [[NTPd]] and network filesystem mounts of various types (e.g. '''netfs'''). NetworkManager has the ability to start these services when you connect to a network and stop them when you disconnect. To activate the feature you need to enable/start the NetworkManager-dispatcher [[daemon|service]].<br />
<br />
Once the feature is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory. These scripts will need to have executable, user permissions. For security, it is good practice to make them owned by '''root:root''' and writable only by the owner.<br />
<br />
The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. They receive two arguments: the name of the interface (e.g. ''eth0'') and the status (''up'' or ''down'' for interfaces and ''vpn-up'' or ''vpn-down'' for vpn connections). To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. {{ic|10_portmap}} or {{ic|30_netfs}} (which ensures that the portmapper is up before NFS mounts are attempted).<br />
<br />
{{Warning|<br />
* For security reason. You should disable write access for group and other. For example use 755 mask. In other case it can refuse to execute script, with error message "nm-dispatcher.action: Script could not be executed: writable by group or other, or set-UID." in {{ic|/var/log/messages.log}}.<br />
* If you connect to foreign or public networks, be aware of what services you are starting and what servers you expect to be available for them to connect to. You could make a security hole by starting the wrong services while connected to a public network.<br />
}}<br />
<br />
==== Avoiding the three seconds timeout ====<br />
<br />
If the above is working, then this section is not relevant. However, there is a general problem related to running dispatcher scripts which take longer than 3 seconds to be executed. NetworkManager uses an internal timeout of 3 seconds (see the [https://bugzilla.redhat.com/show_bug.cgi?id=982734 Bugtracker] for more information) and automatically kills scripts that take longer than 3 seconds to finish. In this case, the dispatcher service file, located in {{ic|/usr/lib/systemd/system/NetworkManager-dispatcher.service}}, has to be modified to remain active after exist. Create the service file {{ic|/etc/systemd/system/NetworkManager-dispatcher.service}} with the following content:<br />
<br />
.include /usr/lib/systemd/system/NetworkManager-dispatcher.service<br />
[Service]<br />
RemainAfterExit=yes<br />
<br />
Now enable the modified {{ic|NetworkManager-dispatcher}} script.<br />
<br />
==== Start OpenNTPD ====<br />
<br />
The following example starts the OpenNTPD daemon when an interface is brought up. Save the file as {{ic|/etc/NetworkManager/dispatcher.d/20_openntpd}} and make it executable.<br />
<br />
{{bc|1=<br />
#!/bin/sh<br />
interface=$1 status=$2<br />
case $status in<br />
up)<br />
systemctl start openntpd<br />
;;<br />
down)<br />
if ! nm-tool | awk '/State:/{print $2}' | grep -qs ^connected; then<br />
systemctl stop openntpd<br />
fi<br />
;;<br />
esac<br />
}}<br />
<br />
==== Mount remote folder with sshfs ====<br />
<br />
As the script is run in a very restrictive environment, you have to export {{ic|SSH_AUTH_SOCK}} in order to connect to your SSH agent. There are different ways to accomplish this, see [https://bbs.archlinux.org/viewtopic.php?pid=1042030#p1042030 this link] for more information. The example below works with [[gnome-keyring]], and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely gnome-keyring has not yet started and the export will fail (hence the sleep). The {{ic|UUID}} to match can be found with the command {{ic|nmcli con status}} or {{ic|nmcli con list}}. <br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
USER='username'<br />
REMOTE='user@host:/remote/path'<br />
LOCAL='/local/path'<br />
<br />
interface=$1 status=$2<br />
if [ "$CONNECTION_UUID" = "</nowiki>''uuid''<nowiki>" ]; then<br />
case $status in<br />
up)<br />
export SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')<br />
su "$USER" -c "sshfs $REMOTE $LOCAL"<br />
;;<br />
down)<br />
fusermount -u "$LOCAL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
==== Use dispatcher to connect to a VPN after a network-connection is established ====<br />
<br />
In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network. <br />
<br />
:1. Create the dispatcher script:<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="wifi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli con up id "$VPN_NAME"<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli con status id "$VPN_NAME" | grep -qs activated; then<br />
nmcli con down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
Remember to make it executable with {{ic|chmod +x}} and to make the VPN connection available to all users. <br />
<br />
Trying to connect using this setup will fail and NetworkManager will complain about 'no valid VPN secrets', because of [http://projects.gnome.org/NetworkManager/developers/migrating-to-09/secrets-flags.html the way VPN secrets are stored] which brings us to step 2:<br />
<br />
:2. Edit your VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring [https://bugzilla.redhat.com/show_bug.cgi?id=710552 that will be inaccessible for root]: open up {{ic|/etc/NetworkManager/system-connections/''name of your VPN connection''}} and change the {{ic|password-flags}} and {{ic|secret-flags}} form {{ic|1}} to {{ic|0}}.<br />
<br />
Alternatively put the password directly in the configuration file adding the section {{ic|vpn-secrets}}:<br />
[vpn]<br />
....<br />
password-flags=0<br />
<br />
[vpn-secrets]<br />
password=your_password<br />
<br />
{{Note|It may now be necessary to re-open the NetworkManager connection editor and re-enter the VPN passwords/secrets.}}<br />
<br />
=== Proxy settings ===<br />
<br />
NetworkManager does not directly handle proxy settings, but if you are using GNOME, you could use [http://marin.jb.free.fr/proxydriver/ proxydriver] wich handles proxy settings using NetworkManager's informations. You can find the package for {{AUR|proxydriver}} in the [[AUR]].<br />
<br />
In order for proxydriver to be able to change the proxy settings, you would need to execute this command, as part of the GNOME startup process (System -> Preferences -> Startup Applications):<br />
<br />
xhost +si:localuser:your_username<br />
<br />
See: [[Proxy settings]]<br />
<br />
== Testing ==<br />
<br />
NetworkManager applets are designed to load upon login so no further configuration should be necessary for most users. If you have already disabled your previous network settings and disconnected from your network, you can now test if NetworkManager will work. The first step is to [[Daemon|start]] the ''networkmanager'' daemon.<br />
<br />
Some applets will provide you with a {{ic|.desktop}} file so that the NetworkManager applet can be loaded through the application menu. If it does not, you are going to either have to discover the command to use or logout and login again to start the applet. Once the applet is started, it will likely begin polling network connections with for auto-configuration with a DHCP server.<br />
<br />
To start the GNOME applet in non-xdg-compliant window managers like [[Awesome]]:<br />
<br />
nm-applet --sm-disable &<br />
<br />
For static IPs you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.<br />
<br />
== Troubleshooting ==<br />
<br />
Some fixes to common problems.<br />
<br />
=== Using nm-applet, wifi networks don't prompt for password and just disconnect ===<br />
<br />
This happens when no keyring package is installed. An easy solution is to install {{Pkg|gnome-keyring}}.<br />
<br />
=== No traffic via PPTP tunnel ===<br />
<br />
PPTP connection logins successfully, you see ppp0 interface with correct VPN IP, but you cannot even ping remote IP. It is due to lack of MPPE (Microsoft Point-to-Point Encryption) support in stock Arch pppd. It is recommended to first try with the stock Arch {{Pkg|ppp}} as it may work as intended.<br />
<br />
To solve the problem it should be sufficient to install {{AUR|ppp-mppe}} from the [[AUR]].<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require ppp-mppe rather than the stock ppp package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See this [https://www.cloudcracker.com/blog/2012/07/29/cracking-ms-chap-v2/ blog post].<br />
<br />
=== Network management disabled ===<br />
<br />
Sometimes when NetworkManager shuts down but the pid (state) file does not get removed and you will get a 'Network management disabled' message. If this happens, you'll have to remove it manually:<br />
<br />
# rm /var/lib/NetworkManager/NetworkManager.state<br />
<br />
If this happens upon reboot, you can add an action to your {{ic|/etc/rc.local}} to have it removed upon bootup:<br />
<br />
{{bc|<nowiki>nmpid=/var/lib/NetworkManager/NetworkManager.state<br />
[ -f $nmpid ] && rm $nmpid</nowiki>}}<br />
<br />
=== Customizing resolv.conf ===<br />
<br />
See the main page: [[resolv.conf]]. Also make sure that NetworkManager uses {{Pkg|dhcpcd}} and not {{Pkg|dhclient}}. If you want to use {{Pkg|dhclient}}, you may try the {{AUR|networkmanager-dispatch-resolv}} package from the [[AUR]].<br />
<br />
=== DHCP problems ===<br />
<br />
{{Poor writing|solutions for {{Pkg|dhcpcd}} and {{Pkg|dhclient}} mixed together}}<br />
<br />
If you have problems with getting an IP via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:<br />
interface "eth0" {<br />
send dhcp-client-identifier 01:aa:bb:cc:dd:ee:ff;<br />
}<br />
Where {{ic|aa:bb:cc:dd:ee:ff}} is the MAC address of this NIC. The MAC address can be found using the {{ic|ip link show eth0}} command from the {{Pkg|iproute2}} package.<br />
<br />
For some (incompliant) routers, you will not be able to connect properly unless you comment the line<br />
require dhcp_server_identifier<br />
in {{ic|/etc/dhcpcd.conf}} (note that this file is distinct from {{ic|dhcpd.conf}}). This should not cause issues unless you have multiple DHCP servers on your network (not typical); see [http://technet.microsoft.com/en-us/library/cc977442.aspx this page] for more information.<br />
<br />
=== Hostname problems ===<br />
<br />
{{Accuracy|no description of the problem|Talk:NetworkManager#Hostname_problems_Entry}}<br />
<br />
You have at least two options. <br />
Network Manager appears to use dhclient by default. One option is to change Network Manager to use dhcpcd instead. There seem to be mixed results with this method.<br />
<br />
The other option is to update the dhclient config file to tell dhclient to send host name.<br />
<br />
First, verify what dhcp client network manager is using. In this case, it is dhclient.<br />
[dylan@zenbook etc]$ sudo journalctl -b | egrep "dhclient|dhcpcd" | tail -5<br />
Nov 17 21:03:20 zenbook dhclient[2949]: Nov 17 21:03:20 zenbook dhclient[2949]: Bound to *:546<br />
Nov 17 21:03:20 zenbook dhclient[2949]: Listening on Socket/wlan0<br />
Nov 17 21:03:20 zenbook dhclient[2949]: Sending on Socket/wlan0<br />
Nov 17 21:03:20 zenbook dhclient[2949]: XMT: Info-Request on wlan0, interval 1020ms.<br />
Nov 17 21:03:20 zenbook dhclient[2949]: RCV: Reply message on wlan0 from fe80::126f:3fff:fe0c:2dc.<br />
<br />
<br />
====Option 1: Configure dhclient to push the hostname to the dhcp server====<br />
Find the local copy of the dhclient config file<br />
[dylan@zenbook etc]$ pacman -Ql dhclient | grep ".conf"<br />
dhclient /usr/share/dhclient/dhclient.conf.example<br />
dhclient /usr/share/man/man5/dhclient.conf.5.gz<br />
<br />
Copy it to /etc, and rename to get rid of the ".example". Take a look at the file - there will only really be one line we want to keep and dhclient will use it's defaults (as it has been using if you didn't have this file) for the other options. This is the important line<br />
[dylan@zenbook ~]$ head -1 /etc/dhclient.conf <br />
send host-name = pick-first-value(gethostname(), "ISC-dhclient");<br />
<br />
Save the file. Force an ip address renewal through your favorite means, and you should now see your hostname on your dhcp server! :)<br />
<br />
<br />
====Option 2: Configure Network Manager to use dhcpcd====<br />
Add the following line to /etc/NetworkManager/NetworkManager.conf:<br />
dhcp=dhcpcd<br />
then restart.<br />
systemctl restart NetworkManager<br />
source https://bbs.archlinux.org/viewtopic.php?id=152376<br />
<br />
=== Missing default route ===<br />
<br />
On at least one KDE4 system, no default route was created when establishing wireless connections with NetworkManager. Changing the route settings of the wireless connection to remove the default selection "Use only for resources on this connection" solved the issue.<br />
<br />
=== 3G modem not detected ===<br />
<br />
See [[USB_3G_Modem#Network_Manager]].<br />
<br />
=== Switching off WLAN on laptops ===<br />
<br />
Sometimes NetworkManager will not work when you disable your Wi-Fi adapter with a switch on your laptop and try to enable it again afterwards. This is often a problem with {{ic|rfkill}}. Install {{Pkg|rfkill}} from the [[official repositories]] and use <br />
<br />
$ watch -n1 rfkill list all<br />
<br />
to check if the driver notifies {{ic|rfkill}} about the wireless adapter's status.<br />
If one identifier stays blocked after you switch on the adapter you could try to manually unblock it with (where X is the number of the identifier provided by the above output):<br />
<br />
# rfkill event unblock X<br />
<br />
=== Static IP settings revert to DHCP ===<br />
<br />
Due to an unresolved bug, when changing default connections to static IP, {{ic|nm-applet}} may not properly store the configuration change, and will revert to automatic DHCP.<br />
<br />
To work around this issue you have to edit the default connection (e.g. "Auto eth0") in {{ic|nm-applet}}, change the connection name (e.g. "my eth0"), uncheck the "Available to all users" checkbox, change your static IP settings as desired, and click '''Apply'''. This will save a new connection with the given name.<br />
<br />
Next, you will want to make the default connection not connect automatically. To do so, run {{ic|nm-connection-editor}} (''not'' as root). In the connection editor, edit the default connection (eg "Auto eth0") and uncheck "Connect automatically". Click '''Apply''' and close the connection editor.<br />
<br />
=== Cannot edit connections as normal user ===<br />
<br />
See [[#Set_up_PolicyKit_permissions]].<br />
<br />
=== Forget hidden wireless network ===<br />
<br />
Since hidden network are not displayed in the selection list of the Wireless view, they cannot be forgotten (removed) with the GUI. You can delete one with the following command:<br />
<br />
# rm /etc/NetworkManager/system-connections/[SSID]<br />
<br />
This works for any other connection.<br />
<br />
=== VPN not working in Gnome ===<br />
<br />
When setting up openconnect or vpnc connections in NetworkManager while using Gnome, you'll sometimes never see the dialog box pop up and the following error appears in /var/log/errors.log:<br />
<br />
localhost NetworkManager[399]: <error> [1361719690.10506] [nm-vpn-connection.c:1405] get_secrets_cb(): Failed to request VPN secrets #3: (6) No agents were available for this request.<br />
<br />
This is caused by the Gnome NM Applet expecting dialog scripts to be at /usr/lib/gnome-shell, when NetworkManager's packages put them in /usr/lib/networkmanager.<br />
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):<br />
<br />
# For OpenConnect<br />
ln -s /usr/lib/networkmanager/nm-openconnect-auth-dialog /usr/lib/gnome-shell/ <br />
<br />
# For VPNC (i.e. Cisco VPN)<br />
ln -s /usr/lib/networkmanager/nm-vpnc-auth-dialog /usr/lib/gnome-shell/<br />
<br />
This may need to be done for any other NM VPN plugins as well, but these are the two most common.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Sharing internet connection over Wi-Fi ===<br />
<br />
You can share your internet connection (e.g.: 3G or wired) with a few clicks using nm. You will need a supported Wi-Fi card (Cards based on Atheros AR9xx or at least AR5xx are probably best choice)<br />
<br />
==== Ad-hoc ====<br />
<br />
* [[pacman|Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection.<br />
* Custom dnsmasq.conf may interfere with nm (not sure about this, but i think so).<br />
* Click on nm-applet -> Create new wireless network.<br />
* Follow wizard (if using WEP be sure to use 5 or 13 character long password, different lengths will fail).<br />
* Settings will remain stored for the next time you need it.<br />
<br />
==== Real AP ====<br />
<br />
Support of infrastructure mode (which is needed by Android phones as they intentionally do not support ad-hoc) is supported by NetworkManager as of late 2012.<br />
<br />
See: http://fedoraproject.org/wiki/Features/RealHotspot<br />
<br />
=== Checking if networking is up inside a cron job or script ===<br />
<br />
Some cron jobs require networking to be up to succeed. You may wish to avoid running these jobs when the network is down. To accomplish this, add an '''if''' test for networking that queries NetworkManager's {{ic|nm-tool}} and checks the state of networking. The test shown here succeeds if any interface is up, and fails if they are all down. This is convenient for laptops that might be hardwired, might be on wireless, or might be off the network.<br />
{{bc|<nowiki><br />
if [ $(nm-tool|grep State|cut -f2 -d' ') == "connected" ]; then<br />
#Whatever you want to do if the network is online<br />
else<br />
#Whatever you want to do if the network is offline - note, this and the else above are optional<br />
fi<br />
</nowiki>}}<br />
<br />
This useful for a {{ic|cron.hourly}} script that runs {{ic|fpupdate}} for the F-Prot virus scanner signature update, as an example. Another way it might be useful, with a little modification, is to differentiate between networks using various parts of the output from {{ic|nm-tool}}; for example, since the active wireless network is denoted with an asterisk, you could grep for the network name and then grep for a literal asterisk.<br />
<br />
=== Automatically unlock keyring after login ===<br />
<br />
==== GNOME ====<br />
<br />
# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab<br />
# Select the connection you want to work with and click the Edit button<br />
# Check the boxes “Connect Automatically” and “Available to all users”<br />
Log out and log back in to complete.<br />
<br />
{{Note|The following method is dated and known not to work on at least one machine!}}<br />
* In {{ic|/etc/pam.d/gdm}} (or your corresponding daemon in {{ic|/etc/pam.d}}), add these lines at the end of the "auth" and "session" blocks if they do not exist already: <br />
auth optional pam_gnome_keyring.so<br />
session optional pam_gnome_keyring.so auto_start<br />
<br />
* In {{ic|/etc/pam.d/passwd}}, use this line for the 'password' block:<br />
password optional pam_gnome_keyring.so<br />
<br />
:Next time you log in, you should be asked if you want the password to be unlocked automatically on login.<br />
<br />
==== KDE ====<br />
{{Note|See http://live.gnome.org/GnomeKeyring/Pam for reference, and if you are using KDE with KDM, you can use {{AUR|pam-keyring-tool}} from the [[AUR]].}}<br />
<br />
Put a script like the following in {{ic|~/.kde4/Autostart}}:<br />
#!/bin/sh<br />
echo PASSWORD | /usr/bin/pam-keyring-tool --unlock --keyring=default -s<br />
Similar should work with Openbox, LXDE, etc.<br />
<br />
==== SLiM login manager ====<br />
See [[Slim#SLiM and Gnome Keyring]].<br />
<br />
=== KDE and OpenConnect VPN with password authentication ===<br />
<br />
{{Pkg|kdeplasma-applets-plasma-nm}} does not support to configure username and password for OpenConnect VPN connections in its GUI. You have to type both<br />
values everytime you connect.<br />
{{Pkg|kdeplasma-applets-plasma-nm}} 0.9.3.2-1 and above is however capable of retrieving OpenConnect username and password directly from KWallet.<br />
<br />
Open "KDE Wallet Manager" and look up your OpenConnect VPN connection under "Network Management|Maps". Click "Show values" and <br />
enter your credentials in key "VpnSecrets" in this form (replace THE_USERNAME and THE_PASSWORD with your actual values):<br />
<br />
form:main:username%SEP%THE_USERNAME%SEP%form:main:password%SEP%THE_PASSWORD<br />
<br />
Next time you connect, username and password should appear in the "VPN secrets" dialog box.<br />
<br />
=== Ignore specific devices ===<br />
<br />
Sometimes it may be desired that NetworkManager ignores specific devices and does not try to configure addresses and routes for them.You can quickly and easily ignore devices by MAC by using the following in {{ic|/etc/NetworkManager/NetworkManager.conf}} :<br />
[keyfile]<br />
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4<br />
After you have put this in, [[Daemon|restart]] NetworkManager, and you should be able to configure interfaces without NetworkManager altering what you have set.<br />
<br />
=== Connect faster ===<br />
<br />
{{Merge|Network_Configuration#Additional_settings|This section contains mostly generally applicable tips.}}<br />
<br />
==== Disabling IPv6 ====<br />
<br />
Slow connection or reconnection to the network may be due to superfluous IPv6 queries in NetworkManager. If there is no IPv6 support on the local network, connecting to a network may take longer than normal while NetworkManager tries to establish an IPv6 connection that eventually times out. The solution is to disable IPv6 within NetworkManager which will make network connection faster. This has to be done once for every network you connect to.<br />
<br />
* Right-click on the network status icon.<br />
* Click on "Edit Connections".<br />
* Go to the "Wired" or "Wireless" tab, as appropriate.<br />
* Select the name of the network.<br />
* Click on "Edit".<br />
* Go to the "IPv6 Settings" tab.<br />
* In the "Method" dropdown, choose "Ignore/Disabled".<br />
* Click on "Save".<br />
<br />
==== Speed up DHCP by disabling ARP probing in DHCPCD ====<br />
<br />
{{ic|dhcpcd}} contains an implementation of a recommendation of the DHCP standard ([http://www.ietf.org/rfc/rfc2131.txt RFC2131] section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to {{ic|/etc/dhcpcd.conf}}:<br />
<br />
noarp<br />
<br />
This is equivalent to passing {{ic|--noarp}} to {{ic|dhcpcd}}, and disables the described ARP probing, speeding up connections to networks with DHCP.<br />
<br />
==== Use OpenDNS servers ====<br />
<br />
Create {{ic|/etc/resolv.conf.opendns}} with the nameservers:<br />
<br />
nameserver 208.67.222.222<br />
nameserver 208.67.220.220<br />
<br />
or use Google DNS servers, because people have been getting ads via the OpenDNS servers lately <br />
<br />
nameserver 8.8.8.8<br />
nameserver 8.8.4.4<br />
<br />
And have the dispatcher replace the discovered DHCP servers with the OpenDNS ones:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/dns-servers-opendns|<nowiki><br />
#!/bin/bash<br />
# Use OpenDNS servers over DHCP discovered servers<br />
<br />
cp -f /etc/resolv.conf.opendns /etc/resolv.conf</nowiki>}}<br />
<br />
Make the script executable:<br />
<br />
# chmod +x /etc/NetworkManager/dispatcher.d/dns-servers-opendns<br />
<br />
=== Enable DNS Caching ===<br />
<br />
DNS requests can be sped up by caching previous requests locally for subsequent lookup. NetworkManager has a plugin to enable DNS caching using dnsmasq, but it is not enabled in the default configuration. It is, however, easy to enable using the following instructions.<br />
<br />
Start by [[pacman|installing]] {{Pkg|dnsmasq}}. Then, edit {{ic|/etc/NetworkManager/NetworkManager.conf}} and add the following line under the {{ic|[main]}} section:<br />
<br />
dns=dnsmasq<br />
<br />
Now restart NetworkManager or reboot. NetworkManager will automatically start dnsmasq and add 127.0.0.1 to {{ic|/etc/resolv.conf}}. The actual DNS servers can be found in {{ic|/var/run/NetworkManager/dnsmasq.conf}}. You can verify dnsmasq is being used by doing the same DNS lookup twice with dig and verifying the server and query times.</div>Nahanthttps://wiki.archlinux.org/index.php?title=NetworkManager&diff=281133NetworkManager2013-11-03T10:58:57Z<p>Nahant: Added remark about NetworkManager OpenConnect VPN package</p>
<hr />
<div>[[Category:Networking]]<br />
[[cs:NetworkManager]]<br />
[[de:Networkmanager]]<br />
[[es:NetworkManager]]<br />
[[fr:NetworkManager]]<br />
[[it:NetworkManager]]<br />
[[ja:NetworkManager]]<br />
[[pt:NetworkManager]]<br />
[[ru:NetworkManager]]<br />
[[tr:NetworkManager]]<br />
[[zh-CN:NetworkManager]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers installation and configuration of NetworkManager &ndash; a set of co-operative tools that make networking simple and straightforward.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Networking overview}}}}<br />
{{Article summary end}}<br />
<br />
[http://projects.gnome.org/NetworkManager/ NetworkManager] is a program for providing detection and configuration for systems to automatically connect to network. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the [[GNOME]] project.<br />
<br />
== Base install ==<br />
<br />
NetworkManager can be installed with the package {{Pkg|networkmanager}}, available in the [[official repositories]].<br />
<br />
=== VPN support ===<br />
<br />
Network Manager VPN support is based on a plug-in system. If you need VPN support via network manager you have to install one of the following packages from the [[official repositories]]:<br />
<br />
* {{Pkg|networkmanager-openconnect}}<br />
* {{Pkg|networkmanager-openvpn}}<br />
* {{Pkg|networkmanager-pptp}}<br />
* {{Pkg|networkmanager-vpnc}}<br />
<br />
== Graphical front-ends ==<br />
<br />
To configure and have easy access to NetworkManager most people will want to install an applet. This GUI front-end usually resides in the system tray (or notification area) and allows network selection and configuration of NetworkManager. Various applets exist for different types of desktops.<br />
<br />
=== GNOME ===<br />
<br />
GNOME's {{Pkg|network-manager-applet}} is lightweight enough and works across all environments.<br />
<br />
If you want to store authentication details (Wireless/DSL) and enable global connection settings, i.e "available to all users" install and configure [[GNOME Keyring]].<br />
<br />
=== KDE ===<br />
<br />
The Plasma-nm front-end is a Plasma widget available in the official repositories as package {{Pkg|kdeplasma-applets-plasma-nm}}. The older KNetworkManager front-end Plasma widget is also available as package {{aur|kdeplasma-applets-networkmanagement}} from the aur.<br />
<br />
If you have both the Plasma widget and {{ic|nm-applet}} installed and do not want to start {{ic|nm-applet}} when using KDE, add the following line to {{ic|/etc/xdg/autostart/nm-applet.desktop}}:<br />
NotShowIn=KDE<br />
<br />
See [http://userbase.kde.org/NetworkManagement Userbase page] for more info.<br />
<br />
=== XFCE ===<br />
{{Pkg|network-manager-applet}} will work fine in XFCE, but in order to see notifications, ''including error messages'', {{ic|nm-applet}} needs an implementation of the Freedesktop desktop notifications specification (see the [http://www.galago-project.org/specs/notification/0.9/index.html Galapago Project]) to display them. To enable notifications install {{Pkg|xfce4-notifyd}}, a package that provides an implementation for the specification.<br />
<br />
Without such a notification daemon, {{ic|nm-applet}} outputs the following errors to stdout/stderr:<br />
<br />
(nm-applet:24209): libnotify-WARNING **: Failed to connect to proxy<br />
** (nm-applet:24209): WARNING **: get_all_cb: couldn't retrieve<br />
system settings properties: (25) Launch helper exited with unknown<br />
return code 1.<br />
** (nm-applet:24209): WARNING **: fetch_connections_done: error<br />
fetching connections: (25) Launch helper exited with unknown return<br />
code 1.<br />
** (nm-applet:24209): WARNING **: Failed to register as an agent:<br />
(25) Launch helper exited with unknown return code 1<br />
<br />
{{ic|nm-applet}} will still work fine, though, but without notifications.<br />
<br />
If nm-applet is not prompting for a password when connecting to new wifi networks, and is just disconnecting immediately, you probably need to install {{Pkg|gnome-keyring}}.<br />
<br />
=== Openbox ===<br />
<br />
To function properly in Openbox, the GNOME applet requires the {{Pkg|xfce4-notifyd}} notification daemon for the same reason as in XFCE and the {{Pkg|gnome-icon-theme}} package to be able to display the applet in the systray.<br />
<br />
If you want to store authentication details (Wireless/DSL) install and configure [[gnome-keyring]].<br />
<br />
{{ic|nm-applet}} installs the autostart file at {{ic|/etc/xdg/autostart/nm-applet.desktop}}. If you have issues with it (e.g. {{ic|nm-applet}} is started twice or is not started at all), see [[Openbox#Autostart directory]] or [https://bbs.archlinux.org/viewtopic.php?pid=993738] for solution.<br />
<br />
=== Other desktops and window managers ===<br />
<br />
In all other scenarios it is recommended to use the GNOME applet. You will also need to be sure that the {{Pkg|gnome-icon-theme}} package is installed to be able to display the applet.<br />
<br />
To store connection secrets install and configure [[gnome-keyring]].<br />
<br />
In order to run {{ic|nm-applet}} without a systray, you can use {{Pkg|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:<br />
{{hc|nmgui|<nowiki><br />
#!/bin/sh<br />
nm-applet > /dev/null 2>/dev/null &<br />
stalonetray > /dev/null 2>/dev/null<br />
killall nm-applet<br />
</nowiki>}}<br />
<br />
When you close the stalonetray window, it closes {{ic|nm-applet}} too, so no extra memory is used once you are done with network settings.<br />
<br />
=== Command line ===<br />
<br />
The {{Pkg|networkmanager}} package contains [http://manpages.ubuntu.com/manpages/maverick/man1/nmcli.1.html nmcli] since version 0.8.1.<br />
<br />
== Configuration ==<br />
<br />
NetworkManager will require some additional steps to be able run properly.<br />
<br />
Verify that your {{ic|/etc/hosts}} is correct before continuing. If you previously tried to connect before doing this step, NetworkManager may have altered it. An example hostname line in {{ic|/etc/hosts}}:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 localhost<br />
::1 localhost<br />
}}<br />
<br />
In case you have nss-myhostname turned off, the line would look like:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 my-laptop localhost<br />
::1 my-laptop localhost<br />
}}<br />
<br />
{{Note|It may be a good idea to use {{ic|1=systemctl --type=service}} to ensure that no other service is running that may want to configure the network. Multiple networking services will conflict.}}<br />
<br />
=== Enable NetworkManager ===<br />
<br />
Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need {{ic|nmcli}} or an applet to configure and connect.<br />
<br />
You can enable NetworkManager at startup with the following command:<br />
<br />
{{bc|# systemctl enable NetworkManager}}<br />
<br />
You can start the NetworkManager daemon immediately with the following command:<br />
<br />
{{bc|# systemctl start NetworkManager}}<br />
<br />
==== Avoid warnings ====<br />
<br />
NetworkManager will print probably meaningless [https://bugs.archlinux.org/task/34971 warnings (Bug#34971)] to your system log, when [[Networkmanager#Network_services_with_NetworkManager_dispatcher|NetworkManager-dispatcher.service]] and [https://www.archlinux.org/packages/?name=modemmanager ModemManager.service] are not enabled. To keep the log clean and suppress this messages, enable both, even if they are not required by your environment:<br />
<br />
{{bc|# systemctl enable NetworkManager-dispatcher.service && systemctl enable ModemManager.service}}<br />
{{bc|# systemctl start NetworkManager-dispatcher.service && systemctl start ModemManager.service}}<br />
<br />
=== Enable NetworkManager Wait Online ===<br />
If you have services which fail if they are started before the network is up, you have to use {{ic|NetworkManager-wait-online.service}} in addition to the NetworkManager service. This is however hardly ever necessary since most network daemons start up fine, even if the network has not been configured yet.<br />
<br />
You can enable NetworkManager Wait Online at startup with the following command:<br />
<br />
{{bc|# systemctl enable NetworkManager-wait-online}}<br />
<br />
In some cases the service will still fail to start sucessfully on boot:<br />
<br />
NetworkManager-wait-online.service: main process exited, code=exited, status=1/FAILURE<br />
Failed to start Network Manager Wait Online<br />
Unit NetworkManger-wait-online.service entered failed state<br />
Starting Network.<br />
Reached target Network.<br />
<br />
This is due to the timeout setting in {{ic|/usr/lib/systemd/system/NetworkManager-wait-online.service}} being too short. Change the default timeout from 30 to a higher value.<br />
<br />
=== Set up PolicyKit permissions ===<br />
<br />
See [[General Troubleshooting#Session permissions]] for setting up a working session.<br />
<br />
With a working session, you have several options for granting the necessary privileges to NetworkManager:<br />
<br />
''Option 1.'' Run a [[PolicyKit]] authentication agent when you log in, such as {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}} (part of {{Pkg|polkit-gnome}}). You will be prompted for your password whenever you add or remove a network connection.<br />
<br />
''Option 2.'' Add yourself to the {{ic|wheel}} group. You will not have to enter your password, but your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.<br />
<br />
''Option 3.'' Add yourself to the {{ic|network}} group and create the following file:<br />
{{hc|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {<br />
return polkit.Result.YES;<br />
}<br />
});</nowiki>}}<br />
All users in the {{ic|network}} group will be able to add and remove networks without a password. This will not work under systemd if you do not have an active session with [[Systemd#Using_systemd-logind|systemd-logind]].<br />
<br />
=== Network services with NetworkManager dispatcher===<br />
<br />
There are quite a few network services that you will not want running until NetworkManager brings up an interface. Good examples are [[OpenNTPD]] and network filesystem mounts of various types (e.g. '''netfs'''). NetworkManager has the ability to start these services when you connect to a network and stop them when you disconnect. To activate the feature you need to enable/start the NetworkManager-dispatcher service:<br />
<br />
{{bc|# systemctl start NetworkManager-dispatcher}}<br />
{{bc|# systemctl enable NetworkManager-dispatcher}}<br />
<br />
Once the feature is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory. These scripts will need to have executable, user permissions. For security, it is good practice to make them owned by '''root:root''' and writable only by the owner.<br />
<br />
The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. They receive two arguments: the name of the interface (e.g. ''eth0'') and the status (''up'' or ''down'' for interfaces and ''vpn-up'' or ''vpn-down'' for vpn connections). To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. {{ic|10_portmap}} or {{ic|30_netfs}} (which ensures that the portmapper is up before NFS mounts are attempted).<br />
<br />
{{Warning|For security reason. You should disable write access for group and other. For example use 755 mask.<br />
In other case it can refuse to execute script, with error message "nm-dispatcher.action: Script could not be executed: writable by group or other, or set-UID." in {{ic|/var/log/messages.log}} }}<br />
{{Warning|if you connect to foreign or public networks, be aware of what services you are starting and what servers you expect to be available for them to connect to. You could make a security hole by starting the wrong services while connected to a public network.}}<br />
<br />
==== Start OpenNTPD ====<br />
<br />
The following example starts the OpenNTPD daemon when an interface is brought up. Save the file as {{ic|/etc/NetworkManager/dispatcher.d/20_openntpd}} and make it executable.<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
interface=$1 status=$2<br />
case $status in<br />
up)<br />
systemctl start openntpd<br />
;;<br />
down)<br />
if ! nm-tool | awk '/State:/{print $2}' | grep -qs connected; then<br />
systemctl stop openntpd<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
==== Mount remote folder with sshfs ====<br />
<br />
As the script is run in a very restrictive environment, you have to export {{ic|SSH_AUTH_SOCK}} in order to connect to your SSH agent. There are different ways to accomplish this, see [https://bbs.archlinux.org/viewtopic.php?pid=1042030#p1042030 this link] for more information. The example below works with [[gnome-keyring]], and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely gnome-keyring has not yet started and the export will fail (hence the sleep). The {{ic|UUID}} to match can be found with the command {{ic|nmcli con status}} or {{ic|nmcli con list}}. <br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
USER='username'<br />
REMOTE='user@host:/remote/path'<br />
LOCAL='/local/path'<br />
<br />
interface=$1 status=$2<br />
if [ "$CONNECTION_UUID" = "<uuid>" ]; then<br />
case $status in<br />
up)<br />
export SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')<br />
su "$USER" -c "sshfs $REMOTE $LOCAL"<br />
;;<br />
down)<br />
fusermount -u "$LOCAL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
==== Use dispatcher to connect to a VPN after a network-connection is established ====<br />
<br />
In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network. <br />
<br />
:1. Create the dispatcher script:<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="wifi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli con up id "$VPN_NAME"<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli con status id "$VPN_NAME" | grep -qs activated; then<br />
nmcli con down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
Remember to make it executable with {{ic|chmod +x}} and to make the VPN connection available to all users. <br />
<br />
Trying to connect using this setup will fail and NetworkManager will complain about 'no valid VPN secrets', because of [http://projects.gnome.org/NetworkManager/developers/migrating-to-09/secrets-flags.html the way VPN secrets are stored] which brings us to step 2:<br />
<br />
:2. Edit your VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring [https://bugzilla.redhat.com/show_bug.cgi?id=710552 that will be inaccessible for root]: open up {{ic|/etc/NetworkManager/system-connections/<name of your VPN connection>}} and change the {{ic|password-flags}} and {{ic|secret-flags}} form {{ic|1}} to {{ic|0}}.<br />
<br />
{{Note|It may now be necessary to re-open the NetworkManager connection editor and re-enter the VPN passwords/secrets.}}<br />
<br />
=== Proxy settings ===<br />
<br />
NetworkManager does not directly handle proxy settings, but if you are using GNOME, you could use [http://marin.jb.free.fr/proxydriver/ proxydriver] wich handles proxy settings using NetworkManager's informations. You can find the package for {{AUR|proxydriver}} in the [[AUR]].<br />
<br />
In order for proxydriver to be able to change the proxy settings, you would need to execute this command, as part of the GNOME startup process (System -> Preferences -> Startup Applications):<br />
<br />
xhost +si:localuser:your_username<br />
<br />
See: [[Proxy settings]]<br />
<br />
== Testing ==<br />
<br />
NetworkManager applets are designed to load upon login so no further configuration should be necessary for most users. If you have already disabled your previous network settings and disconnected from your network, you can now test if NetworkManager will work. The first step is to [[Daemon|start]] the ''networkmanager'' daemon.<br />
<br />
Some applets will provide you with a {{ic|.desktop}} file so that the NetworkManager applet can be loaded through the application menu. If it does not, you are going to either have to discover the command to use or logout and login again to start the applet. Once the applet is started, it will likely begin polling network connections with for auto-configuration with a DHCP server.<br />
<br />
To start the GNOME applet in non-xdg-compliant window managers like [[Awesome]]:<br />
<br />
nm-applet --sm-disable &<br />
<br />
For static IPs you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.<br />
<br />
== Troubleshooting ==<br />
<br />
Some fixes to common problems.<br />
<br />
=== Using nm-applet, wifi networks don't prompt for password and just disconnect ===<br />
<br />
This happens when no keyring package is installed. An easy solution is to install {{Pkg|gnome-keyring}}.<br />
<br />
=== No traffic via PPTP tunnel ===<br />
<br />
PPTP connection logins successfully, you see ppp0 interface with correct VPN IP, but you cannot even ping remote IP. It is due to lack of MPPE (Microsoft Point-to-Point Encryption) support in stock Arch pppd. It is recommended to first try with the stock Arch {{Pkg|ppp}} as it may work as intended.<br />
<br />
To solve the problem it should be sufficient to install {{AUR|ppp-mppe}} from the [[AUR]].<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require ppp-mppe rather than the stock ppp package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See this [https://www.cloudcracker.com/blog/2012/07/29/cracking-ms-chap-v2/ blog post].<br />
<br />
=== Network management disabled ===<br />
<br />
Sometimes when NetworkManager shuts down but the pid (state) file does not get removed and you will get a 'Network management disabled' message. If this happens, you'll have to remove it manually:<br />
<br />
# rm /var/lib/NetworkManager/NetworkManager.state<br />
<br />
If this happens upon reboot, you can add an action to your {{ic|/etc/rc.local}} to have it removed upon bootup:<br />
<br />
{{bc|<nowiki>nmpid=/var/lib/NetworkManager/NetworkManager.state<br />
[ -f $nmpid ] && rm $nmpid</nowiki>}}<br />
<br />
=== Customizing resolv.conf ===<br />
<br />
See the main page: [[resolv.conf]]. Also make sure that NetworkManager uses {{Pkg|dhcpcd}} and not {{Pkg|dhclient}}. If you want to use {{Pkg|dhclient}}, you may try the {{AUR|networkmanager-dispatch-resolv}} package from the [[AUR]].<br />
<br />
=== DHCP problems ===<br />
<br />
{{Poor writing|solutions for {{Pkg|dhcpcd}} and {{Pkg|dhclient}} mixed together}}<br />
<br />
If you have problems with getting an IP via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:<br />
interface "eth0" {<br />
send dhcp-client-identifier 01:aa:bb:cc:dd:ee:ff;<br />
}<br />
Where {{ic|aa:bb:cc:dd:ee:ff}} is the MAC address of this NIC. The MAC address can be found using the {{ic|ip link show eth0}} command from the {{Pkg|iproute2}} package.<br />
<br />
For some (incompliant) routers, you will not be able to connect properly unless you comment the line<br />
require dhcp_server_identifier<br />
in {{ic|/etc/dhcpcd.conf}} (note that this file is distinct from {{ic|dhcpd.conf}}). This should not cause issues unless you have multiple DHCP servers on your network (not typical); see [http://technet.microsoft.com/en-us/library/cc977442.aspx this page] for more information.<br />
<br />
=== Hostname problems ===<br />
<br />
{{Accuracy|no description of the problem|Talk:NetworkManager#Hostname_problems_Entry}}<br />
<br />
Add the following line to /etc/NetworkManager/NetworkManager.conf:<br />
dhcp=dhcpcd<br />
then restart.<br />
systemctl restart NetworkManager<br />
source https://bbs.archlinux.org/viewtopic.php?id=152376<br />
<br />
=== Missing default route ===<br />
<br />
On at least one KDE4 system, no default route was created when establishing wireless connections with NetworkManager. Changing the route settings of the wireless connection to remove the default selection "Use only for resources on this connection" solved the issue.<br />
<br />
=== 3G modem not detected ===<br />
<br />
See [[USB_3G_Modem#Network_Manager]].<br />
<br />
=== Switching off WLAN on laptops ===<br />
<br />
Sometimes NetworkManager will not work when you disable your Wi-Fi adapter with a switch on your laptop and try to enable it again afterwards. This is often a problem with {{ic|rfkill}}. Install {{Pkg|rfkill}} from the [[official repositories]] and use <br />
<br />
$ watch -n1 rfkill list all<br />
<br />
to check if the driver notifies {{ic|rfkill}} about the wireless adapter's status.<br />
If one identifier stays blocked after you switch on the adapter you could try to manually unblock it with (where X is the number of the identifier provided by the above output):<br />
<br />
# rfkill event unblock X<br />
<br />
=== Static IP settings revert to DHCP ===<br />
<br />
Due to an unresolved bug, when changing default connections to static IP, {{ic|nm-applet}} may not properly store the configuration change, and will revert to automatic DHCP.<br />
<br />
To work around this issue you have to edit the default connection (e.g. "Auto eth0") in {{ic|nm-applet}}, change the connection name (e.g. "my eth0"), uncheck the "Available to all users" checkbox, change your static IP settings as desired, and click '''Apply'''. This will save a new connection with the given name.<br />
<br />
Next, you will want to make the default connection not connect automatically. To do so, run {{ic|nm-connection-editor}} (''not'' as root). In the connection editor, edit the default connection (eg "Auto eth0") and uncheck "Connect automatically". Click '''Apply''' and close the connection editor.<br />
<br />
=== Cannot edit connections as normal user ===<br />
<br />
See [[#Set_up_PolicyKit_permissions]].<br />
<br />
=== Forget hidden wireless network ===<br />
<br />
Since hidden network are not displayed in the selection list of the Wireless view, they cannot be forgotten (removed) with the GUI. You can delete one with the following command:<br />
<br />
# rm /etc/NetworkManager/system-connections/[SSID]<br />
<br />
This works for any other connection.<br />
<br />
=== VPN not working in Gnome ===<br />
<br />
When setting up openconnect or vpnc connections in NetworkManager while using Gnome, you'll sometimes never see the dialog box pop up and the following error appears in /var/log/errors.log:<br />
<br />
localhost NetworkManager[399]: <error> [1361719690.10506] [nm-vpn-connection.c:1405] get_secrets_cb(): Failed to request VPN secrets #3: (6) No agents were available for this request.<br />
<br />
This is caused by the Gnome NM Applet expecting dialog scripts to be at /usr/lib/gnome-shell, when NetworkManager's packages put them in /usr/lib/networkmanager.<br />
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):<br />
<br />
# For OpenConnect<br />
ln -s /usr/lib/networkmanager/nm-openconnect-auth-dialog /usr/lib/gnome-shell/ <br />
<br />
# For VPNC (i.e. Cisco VPN)<br />
ln -s /usr/lib/networkmanager/nm-vpnc-auth-dialog /usr/lib/gnome-shell/<br />
<br />
This may need to be done for any other NM VPN plugins as well, but these are the two most common.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Sharing internet connection over Wi-Fi ===<br />
<br />
You can share your internet connection (e.g.: 3G or wired) with a few clicks using nm. You will need a supported Wi-Fi card (Cards based on Atheros AR9xx or at least AR5xx are probably best choice)<br />
<br />
==== Ad-hoc ====<br />
<br />
* [[pacman|Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection.<br />
* Custom dnsmasq.conf may interfere with nm (not sure about this, but i think so).<br />
* Click on nm-applet -> Create new wireless network.<br />
* Follow wizard (if using WEP be sure to use 5 or 13 character long password, different lengths will fail).<br />
* Settings will remain stored for the next time you need it.<br />
<br />
==== Real AP ====<br />
<br />
Support of infrastructure mode (which is needed by Android phones as they do not intentionally support ad-hoc) is not currently supported by NetworkManager, but is in active development...<br />
<br />
See: http://fedoraproject.org/wiki/Features/RealHotspot<br />
<br />
=== Checking if networking is up inside a cron job or script ===<br />
<br />
Some cron jobs require networking to be up to succeed. You may wish to avoid running these jobs when the network is down. To accomplish this, add an '''if''' test for networking that queries NetworkManager's {{ic|nm-tool}} and checks the state of networking. The test shown here succeeds if any interface is up, and fails if they are all down. This is convenient for laptops that might be hardwired, might be on wireless, or might be off the network. <br />
if [ `nm-tool|grep State|cut -f2 -d' '` == "connected" ]; then<br />
#Whatever you want to do if the network is online<br />
else<br />
#Whatever you want to do if the network is offline - note, this and the else above are optional<br />
fi<br />
<br />
This useful for a {{ic|cron.hourly}} script that runs {{ic|fpupdate}} for the F-Prot virus scanner signature update, as an example. Another way it might be useful, with a little modification, is to differentiate between networks using various parts of the output from {{ic|nm-tool}}; for example, since the active wireless network is denoted with an asterisk, you could grep for the network name and then grep for a literal asterisk.<br />
<br />
=== Automatically unlock keyring after login ===<br />
<br />
==== GNOME ====<br />
<br />
# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab<br />
# Select the connection you want to work with and click the Edit button<br />
# Check the boxes “Connect Automatically” and “Available to all users”<br />
Log out and log back in to complete.<br />
<br />
{{Note|The following method is dated and known not to work on at least one machine!}}<br />
* In {{ic|/etc/pam.d/gdm}} (or your corresponding daemon in {{ic|/etc/pam.d}}), add these lines at the end of the "auth" and "session" blocks if they do not exist already: <br />
auth optional pam_gnome_keyring.so<br />
session optional pam_gnome_keyring.so auto_start<br />
<br />
* In {{ic|/etc/pam.d/passwd}}, use this line for the 'password' block:<br />
password optional pam_gnome_keyring.so<br />
<br />
:Next time you log in, you should be asked if you want the password to be unlocked automatically on login.<br />
<br />
==== KDE ====<br />
{{Note|See http://live.gnome.org/GnomeKeyring/Pam for reference, and if you are using KDE with KDM, you can use {{AUR|pam-keyring-tool}} from the [[AUR]].}}<br />
<br />
Put a script like the following in {{ic|~/.kde4/Autostart}}:<br />
#!/bin/sh<br />
echo PASSWORD | /usr/bin/pam-keyring-tool --unlock --keyring=default -s<br />
Similar should work with Openbox, LXDE, etc.<br />
<br />
==== SLiM login manager ====<br />
See [[Slim#SLiM and Gnome Keyring]].<br />
<br />
=== Ignore specific devices ===<br />
<br />
Sometimes it may be desired that NetworkManager ignores specific devices and does not try to configure addresses and routes for them.You can quickly and easily ignore devices by MAC by using the following in {{ic|/etc/NetworkManager/NetworkManager.conf}} :<br />
[keyfile]<br />
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4<br />
After you have put this in, [[Daemon|restart]] NetworkManager, and you should be able to configure interfaces without NetworkManager altering what you have set.<br />
<br />
=== Connect faster ===<br />
<br />
{{Merge|Network_Configuration#Additional_settings|This section contains mostly generally applicable tips.}}<br />
<br />
==== Disabling IPv6 ====<br />
<br />
Slow connection or reconnection to the network may be due to superfluous IPv6 queries in NetworkManager. If there is no IPv6 support on the local network, connecting to a network may take longer than normal while NetworkManager tries to establish an IPv6 connection that eventually times out. The solution is to disable IPv6 within NetworkManager which will make network connection faster. This has to be done once for every network you connect to.<br />
<br />
* Right-click on the network status icon.<br />
* Click on "Edit Connections".<br />
* Go to the "Wired" or "Wireless" tab, as appropriate.<br />
* Select the name of the network.<br />
* Click on "Edit".<br />
* Go to the "IPv6 Settings" tab.<br />
* In the "Method" dropdown, choose "Ignore/Disabled".<br />
* Click on "Save".<br />
<br />
==== Speed up DHCP by disabling ARP probing in DHCPCD ====<br />
<br />
{{ic|dhcpcd}} contains an implementation of a recommendation of the DHCP standard ([http://www.ietf.org/rfc/rfc2131.txt RFC2131] section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to {{ic|/etc/dhcpcd.conf}}:<br />
<br />
noarp<br />
<br />
This is equivalent to passing {{ic|--noarp}} to {{ic|dhcpcd}}, and disables the described ARP probing, speeding up connections to networks with DHCP.<br />
<br />
==== Use OpenDNS servers ====<br />
<br />
Create {{ic|/etc/resolv.conf.opendns}} with the nameservers:<br />
<br />
nameserver 208.67.222.222<br />
nameserver 208.67.220.220<br />
<br />
or use Google DNS servers, because people have been getting ads via the OpenDNS servers lately <br />
<br />
nameserver 8.8.8.8<br />
nameserver 8.8.4.4<br />
<br />
And have the dispatcher replace the discovered DHCP servers with the OpenDNS ones:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/dns-servers-opendns|<nowiki><br />
#!/bin/bash<br />
# Use OpenDNS servers over DHCP discovered servers<br />
<br />
cp -f /etc/resolv.conf.opendns /etc/resolv.conf</nowiki>}}<br />
<br />
Make the script executable:<br />
<br />
# chmod +x /etc/NetworkManager/dispatcher.d/dns-servers-opendns</div>Nahanthttps://wiki.archlinux.org/index.php?title=NetworkManager&diff=281125NetworkManager2013-11-03T10:45:27Z<p>Nahant: Fixed commands to enable and start NetworkManager and ModemManager</p>
<hr />
<div>[[Category:Networking]]<br />
[[cs:NetworkManager]]<br />
[[de:Networkmanager]]<br />
[[es:NetworkManager]]<br />
[[fr:NetworkManager]]<br />
[[it:NetworkManager]]<br />
[[ja:NetworkManager]]<br />
[[pt:NetworkManager]]<br />
[[ru:NetworkManager]]<br />
[[tr:NetworkManager]]<br />
[[zh-CN:NetworkManager]]<br />
{{Article summary start}}<br />
{{Article summary text|Covers installation and configuration of NetworkManager &ndash; a set of co-operative tools that make networking simple and straightforward.}}<br />
{{Article summary heading|Overview}}<br />
{{Article summary text|{{Networking overview}}}}<br />
{{Article summary end}}<br />
<br />
[http://projects.gnome.org/NetworkManager/ NetworkManager] is a program for providing detection and configuration for systems to automatically connect to network. NetworkManager's functionality can be useful for both wireless and wired networks. For wireless networks, NetworkManager prefers known wireless networks and has the ability to switch to the most reliable network. NetworkManager-aware applications can switch from online and offline mode. NetworkManager also prefers wired connections over wireless ones, has support for modem connections and certain types of VPN. NetworkManager was originally developed by Red Hat and now is hosted by the [[GNOME]] project.<br />
<br />
== Base install ==<br />
<br />
NetworkManager can be installed with the package {{Pkg|networkmanager}}, available in the [[official repositories]].<br />
<br />
=== VPN support ===<br />
<br />
Network Manager VPN support is based on a plug-in system. If you need VPN support via network manager you have to install one of the following packages from the [[official repositories]]:<br />
<br />
* {{Pkg|networkmanager-openvpn}}<br />
* {{Pkg|networkmanager-pptp}}<br />
* {{Pkg|networkmanager-vpnc}}<br />
<br />
== Graphical front-ends ==<br />
<br />
To configure and have easy access to NetworkManager most people will want to install an applet. This GUI front-end usually resides in the system tray (or notification area) and allows network selection and configuration of NetworkManager. Various applets exist for different types of desktops.<br />
<br />
=== GNOME ===<br />
<br />
GNOME's {{Pkg|network-manager-applet}} is lightweight enough and works across all environments.<br />
<br />
If you want to store authentication details (Wireless/DSL) and enable global connection settings, i.e "available to all users" install and configure [[GNOME Keyring]].<br />
<br />
=== KDE ===<br />
<br />
The Plasma-nm front-end is a Plasma widget available in the official repositories as package {{Pkg|kdeplasma-applets-plasma-nm}}. The older KNetworkManager front-end Plasma widget is also available as package {{aur|kdeplasma-applets-networkmanagement}} from the aur.<br />
<br />
If you have both the Plasma widget and {{ic|nm-applet}} installed and do not want to start {{ic|nm-applet}} when using KDE, add the following line to {{ic|/etc/xdg/autostart/nm-applet.desktop}}:<br />
NotShowIn=KDE<br />
<br />
See [http://userbase.kde.org/NetworkManagement Userbase page] for more info.<br />
<br />
=== XFCE ===<br />
{{Pkg|network-manager-applet}} will work fine in XFCE, but in order to see notifications, ''including error messages'', {{ic|nm-applet}} needs an implementation of the Freedesktop desktop notifications specification (see the [http://www.galago-project.org/specs/notification/0.9/index.html Galapago Project]) to display them. To enable notifications install {{Pkg|xfce4-notifyd}}, a package that provides an implementation for the specification.<br />
<br />
Without such a notification daemon, {{ic|nm-applet}} outputs the following errors to stdout/stderr:<br />
<br />
(nm-applet:24209): libnotify-WARNING **: Failed to connect to proxy<br />
** (nm-applet:24209): WARNING **: get_all_cb: couldn't retrieve<br />
system settings properties: (25) Launch helper exited with unknown<br />
return code 1.<br />
** (nm-applet:24209): WARNING **: fetch_connections_done: error<br />
fetching connections: (25) Launch helper exited with unknown return<br />
code 1.<br />
** (nm-applet:24209): WARNING **: Failed to register as an agent:<br />
(25) Launch helper exited with unknown return code 1<br />
<br />
{{ic|nm-applet}} will still work fine, though, but without notifications.<br />
<br />
If nm-applet is not prompting for a password when connecting to new wifi networks, and is just disconnecting immediately, you probably need to install {{Pkg|gnome-keyring}}.<br />
<br />
=== Openbox ===<br />
<br />
To function properly in Openbox, the GNOME applet requires the {{Pkg|xfce4-notifyd}} notification daemon for the same reason as in XFCE and the {{Pkg|gnome-icon-theme}} package to be able to display the applet in the systray.<br />
<br />
If you want to store authentication details (Wireless/DSL) install and configure [[gnome-keyring]].<br />
<br />
{{ic|nm-applet}} installs the autostart file at {{ic|/etc/xdg/autostart/nm-applet.desktop}}. If you have issues with it (e.g. {{ic|nm-applet}} is started twice or is not started at all), see [[Openbox#Autostart directory]] or [https://bbs.archlinux.org/viewtopic.php?pid=993738] for solution.<br />
<br />
=== Other desktops and window managers ===<br />
<br />
In all other scenarios it is recommended to use the GNOME applet. You will also need to be sure that the {{Pkg|gnome-icon-theme}} package is installed to be able to display the applet.<br />
<br />
To store connection secrets install and configure [[gnome-keyring]].<br />
<br />
In order to run {{ic|nm-applet}} without a systray, you can use {{Pkg|trayer}} or {{Pkg|stalonetray}}. For example, you can add a script like this one in your path:<br />
{{hc|nmgui|<nowiki><br />
#!/bin/sh<br />
nm-applet > /dev/null 2>/dev/null &<br />
stalonetray > /dev/null 2>/dev/null<br />
killall nm-applet<br />
</nowiki>}}<br />
<br />
When you close the stalonetray window, it closes {{ic|nm-applet}} too, so no extra memory is used once you are done with network settings.<br />
<br />
=== Command line ===<br />
<br />
The {{Pkg|networkmanager}} package contains [http://manpages.ubuntu.com/manpages/maverick/man1/nmcli.1.html nmcli] since version 0.8.1.<br />
<br />
== Configuration ==<br />
<br />
NetworkManager will require some additional steps to be able run properly.<br />
<br />
Verify that your {{ic|/etc/hosts}} is correct before continuing. If you previously tried to connect before doing this step, NetworkManager may have altered it. An example hostname line in {{ic|/etc/hosts}}:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 localhost<br />
::1 localhost<br />
}}<br />
<br />
In case you have nss-myhostname turned off, the line would look like:<br />
<br />
{{hc|/etc/hosts|<br />
127.0.0.1 my-laptop localhost<br />
::1 my-laptop localhost<br />
}}<br />
<br />
{{Note|It may be a good idea to use {{ic|1=systemctl --type=service}} to ensure that no other service is running that may want to configure the network. Multiple networking services will conflict.}}<br />
<br />
=== Enable NetworkManager ===<br />
<br />
Once the NetworkManager daemon is started, it will automatically connect to any available "system connections" that have already been configured. Any "user connections" or unconfigured connections will need {{ic|nmcli}} or an applet to configure and connect.<br />
<br />
You can enable NetworkManager at startup with the following command:<br />
<br />
{{bc|# systemctl enable NetworkManager}}<br />
<br />
You can start the NetworkManager daemon immediately with the following command:<br />
<br />
{{bc|# systemctl start NetworkManager}}<br />
<br />
==== Avoid warnings ====<br />
<br />
NetworkManager will print probably meaningless [https://bugs.archlinux.org/task/34971 warnings (Bug#34971)] to your system log, when [[Networkmanager#Network_services_with_NetworkManager_dispatcher|NetworkManager-dispatcher.service]] and [https://www.archlinux.org/packages/?name=modemmanager ModemManager.service] are not enabled. To keep the log clean and suppress this messages, enable both, even if they are not required by your environment:<br />
<br />
{{bc|# systemctl enable NetworkManager-dispatcher.service && systemctl enable ModemManager.service}}<br />
{{bc|# systemctl start NetworkManager-dispatcher.service && systemctl start ModemManager.service}}<br />
<br />
=== Enable NetworkManager Wait Online ===<br />
If you have services which fail if they are started before the network is up, you have to use {{ic|NetworkManager-wait-online.service}} in addition to the NetworkManager service. This is however hardly ever necessary since most network daemons start up fine, even if the network has not been configured yet.<br />
<br />
You can enable NetworkManager Wait Online at startup with the following command:<br />
<br />
{{bc|# systemctl enable NetworkManager-wait-online}}<br />
<br />
In some cases the service will still fail to start sucessfully on boot:<br />
<br />
NetworkManager-wait-online.service: main process exited, code=exited, status=1/FAILURE<br />
Failed to start Network Manager Wait Online<br />
Unit NetworkManger-wait-online.service entered failed state<br />
Starting Network.<br />
Reached target Network.<br />
<br />
This is due to the timeout setting in {{ic|/usr/lib/systemd/system/NetworkManager-wait-online.service}} being too short. Change the default timeout from 30 to a higher value.<br />
<br />
=== Set up PolicyKit permissions ===<br />
<br />
See [[General Troubleshooting#Session permissions]] for setting up a working session.<br />
<br />
With a working session, you have several options for granting the necessary privileges to NetworkManager:<br />
<br />
''Option 1.'' Run a [[PolicyKit]] authentication agent when you log in, such as {{ic|/usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1}} (part of {{Pkg|polkit-gnome}}). You will be prompted for your password whenever you add or remove a network connection.<br />
<br />
''Option 2.'' Add yourself to the {{ic|wheel}} group. You will not have to enter your password, but your user account may be granted other permissions as well, such as the ability to use [[sudo]] without entering the root password.<br />
<br />
''Option 3.'' Add yourself to the {{ic|network}} group and create the following file:<br />
{{hc|/etc/polkit-1/rules.d/50-org.freedesktop.NetworkManager.rules|<nowiki><br />
polkit.addRule(function(action, subject) {<br />
if (action.id.indexOf("org.freedesktop.NetworkManager.") == 0 && subject.isInGroup("network")) {<br />
return polkit.Result.YES;<br />
}<br />
});</nowiki>}}<br />
All users in the {{ic|network}} group will be able to add and remove networks without a password. This will not work under systemd if you do not have an active session with [[Systemd#Using_systemd-logind|systemd-logind]].<br />
<br />
=== Network services with NetworkManager dispatcher===<br />
<br />
There are quite a few network services that you will not want running until NetworkManager brings up an interface. Good examples are [[OpenNTPD]] and network filesystem mounts of various types (e.g. '''netfs'''). NetworkManager has the ability to start these services when you connect to a network and stop them when you disconnect. To activate the feature you need to enable/start the NetworkManager-dispatcher service:<br />
<br />
{{bc|# systemctl start NetworkManager-dispatcher}}<br />
{{bc|# systemctl enable NetworkManager-dispatcher}}<br />
<br />
Once the feature is active, scripts can be added to the {{ic|/etc/NetworkManager/dispatcher.d}} directory. These scripts will need to have executable, user permissions. For security, it is good practice to make them owned by '''root:root''' and writable only by the owner.<br />
<br />
The scripts will be run in alphabetical order at connection time, and in reverse alphabetical order at disconnect time. They receive two arguments: the name of the interface (e.g. ''eth0'') and the status (''up'' or ''down'' for interfaces and ''vpn-up'' or ''vpn-down'' for vpn connections). To ensure what order they come up in, it is common to use numerical characters prior to the name of the script (e.g. {{ic|10_portmap}} or {{ic|30_netfs}} (which ensures that the portmapper is up before NFS mounts are attempted).<br />
<br />
{{Warning|For security reason. You should disable write access for group and other. For example use 755 mask.<br />
In other case it can refuse to execute script, with error message "nm-dispatcher.action: Script could not be executed: writable by group or other, or set-UID." in {{ic|/var/log/messages.log}} }}<br />
{{Warning|if you connect to foreign or public networks, be aware of what services you are starting and what servers you expect to be available for them to connect to. You could make a security hole by starting the wrong services while connected to a public network.}}<br />
<br />
==== Start OpenNTPD ====<br />
<br />
The following example starts the OpenNTPD daemon when an interface is brought up. Save the file as {{ic|/etc/NetworkManager/dispatcher.d/20_openntpd}} and make it executable.<br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
interface=$1 status=$2<br />
case $status in<br />
up)<br />
systemctl start openntpd<br />
;;<br />
down)<br />
if ! nm-tool | awk '/State:/{print $2}' | grep -qs connected; then<br />
systemctl stop openntpd<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
<br />
==== Mount remote folder with sshfs ====<br />
<br />
As the script is run in a very restrictive environment, you have to export {{ic|SSH_AUTH_SOCK}} in order to connect to your SSH agent. There are different ways to accomplish this, see [https://bbs.archlinux.org/viewtopic.php?pid=1042030#p1042030 this link] for more information. The example below works with [[gnome-keyring]], and will ask you for the password if not unlocked already. In case NetworkManager connects automatically on login, it is likely gnome-keyring has not yet started and the export will fail (hence the sleep). The {{ic|UUID}} to match can be found with the command {{ic|nmcli con status}} or {{ic|nmcli con list}}. <br />
<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
USER='username'<br />
REMOTE='user@host:/remote/path'<br />
LOCAL='/local/path'<br />
<br />
interface=$1 status=$2<br />
if [ "$CONNECTION_UUID" = "<uuid>" ]; then<br />
case $status in<br />
up)<br />
export SSH_AUTH_SOCK=$(find /tmp -maxdepth 1 -type s -user "$USER" -name 'ssh')<br />
su "$USER" -c "sshfs $REMOTE $LOCAL"<br />
;;<br />
down)<br />
fusermount -u "$LOCAL"<br />
;;<br />
esac<br />
fi<br />
</nowiki>}}<br />
<br />
==== Use dispatcher to connect to a VPN after a network-connection is established ====<br />
<br />
In this example we want to connect automatically to a previously defined VPN connection after connecting to a specific Wi-Fi network. First thing to do is to create the dispatcher script that defines what to do after we are connected to the network. <br />
<br />
:1. Create the dispatcher script:<br />
{{hc|/etc/NetworkManager/dispatcher.d/vpn-up|<nowiki><br />
#!/bin/sh<br />
VPN_NAME="name of VPN connection defined in NetworkManager"<br />
ESSID="wifi network ESSID (not connection name)"<br />
<br />
interface=$1 status=$2<br />
case $status in<br />
up|vpn-down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
nmcli con up id "$VPN_NAME"<br />
fi<br />
;;<br />
down)<br />
if iwgetid | grep -qs ":\"$ESSID\""; then<br />
if nmcli con status id "$VPN_NAME" | grep -qs activated; then<br />
nmcli con down id "$VPN_NAME"<br />
fi<br />
fi<br />
;;<br />
esac<br />
</nowiki>}}<br />
Remember to make it executable with {{ic|chmod +x}} and to make the VPN connection available to all users. <br />
<br />
Trying to connect using this setup will fail and NetworkManager will complain about 'no valid VPN secrets', because of [http://projects.gnome.org/NetworkManager/developers/migrating-to-09/secrets-flags.html the way VPN secrets are stored] which brings us to step 2:<br />
<br />
:2. Edit your VPN connection configuration file to make NetworkManager store the secrets by itself rather than inside a keyring [https://bugzilla.redhat.com/show_bug.cgi?id=710552 that will be inaccessible for root]: open up {{ic|/etc/NetworkManager/system-connections/<name of your VPN connection>}} and change the {{ic|password-flags}} and {{ic|secret-flags}} form {{ic|1}} to {{ic|0}}.<br />
<br />
{{Note|It may now be necessary to re-open the NetworkManager connection editor and re-enter the VPN passwords/secrets.}}<br />
<br />
=== Proxy settings ===<br />
<br />
NetworkManager does not directly handle proxy settings, but if you are using GNOME, you could use [http://marin.jb.free.fr/proxydriver/ proxydriver] wich handles proxy settings using NetworkManager's informations. You can find the package for {{AUR|proxydriver}} in the [[AUR]].<br />
<br />
In order for proxydriver to be able to change the proxy settings, you would need to execute this command, as part of the GNOME startup process (System -> Preferences -> Startup Applications):<br />
<br />
xhost +si:localuser:your_username<br />
<br />
See: [[Proxy settings]]<br />
<br />
== Testing ==<br />
<br />
NetworkManager applets are designed to load upon login so no further configuration should be necessary for most users. If you have already disabled your previous network settings and disconnected from your network, you can now test if NetworkManager will work. The first step is to [[Daemon|start]] the ''networkmanager'' daemon.<br />
<br />
Some applets will provide you with a {{ic|.desktop}} file so that the NetworkManager applet can be loaded through the application menu. If it does not, you are going to either have to discover the command to use or logout and login again to start the applet. Once the applet is started, it will likely begin polling network connections with for auto-configuration with a DHCP server.<br />
<br />
To start the GNOME applet in non-xdg-compliant window managers like [[Awesome]]:<br />
<br />
nm-applet --sm-disable &<br />
<br />
For static IPs you will have to configure NetworkManager to understand them. The process usually involves right-clicking the applet and selecting something like 'Edit Connections'.<br />
<br />
== Troubleshooting ==<br />
<br />
Some fixes to common problems.<br />
<br />
=== Using nm-applet, wifi networks don't prompt for password and just disconnect ===<br />
<br />
This happens when no keyring package is installed. An easy solution is to install {{Pkg|gnome-keyring}}.<br />
<br />
=== No traffic via PPTP tunnel ===<br />
<br />
PPTP connection logins successfully, you see ppp0 interface with correct VPN IP, but you cannot even ping remote IP. It is due to lack of MPPE (Microsoft Point-to-Point Encryption) support in stock Arch pppd. It is recommended to first try with the stock Arch {{Pkg|ppp}} as it may work as intended.<br />
<br />
To solve the problem it should be sufficient to install {{AUR|ppp-mppe}} from the [[AUR]].<br />
<br />
WPA2-Enterprise wireless networks demanding MSCHAPv2 type-2 authentication with PEAP sometimes require ppp-mppe rather than the stock ppp package. [[netctl]] seems to work out of the box without ppp-mppe, however. In either case, usage of MSCHAPv2 is discouraged as it is highly vulnerable, although using another method is usually not an option. See this [https://www.cloudcracker.com/blog/2012/07/29/cracking-ms-chap-v2/ blog post].<br />
<br />
=== Network management disabled ===<br />
<br />
Sometimes when NetworkManager shuts down but the pid (state) file does not get removed and you will get a 'Network management disabled' message. If this happens, you'll have to remove it manually:<br />
<br />
# rm /var/lib/NetworkManager/NetworkManager.state<br />
<br />
If this happens upon reboot, you can add an action to your {{ic|/etc/rc.local}} to have it removed upon bootup:<br />
<br />
{{bc|<nowiki>nmpid=/var/lib/NetworkManager/NetworkManager.state<br />
[ -f $nmpid ] && rm $nmpid</nowiki>}}<br />
<br />
=== Customizing resolv.conf ===<br />
<br />
See the main page: [[resolv.conf]]. Also make sure that NetworkManager uses {{Pkg|dhcpcd}} and not {{Pkg|dhclient}}. If you want to use {{Pkg|dhclient}}, you may try the {{AUR|networkmanager-dispatch-resolv}} package from the [[AUR]].<br />
<br />
=== DHCP problems ===<br />
<br />
{{Poor writing|solutions for {{Pkg|dhcpcd}} and {{Pkg|dhclient}} mixed together}}<br />
<br />
If you have problems with getting an IP via DHCP, try to add the following to your {{ic|/etc/dhclient.conf}}:<br />
interface "eth0" {<br />
send dhcp-client-identifier 01:aa:bb:cc:dd:ee:ff;<br />
}<br />
Where {{ic|aa:bb:cc:dd:ee:ff}} is the MAC address of this NIC. The MAC address can be found using the {{ic|ip link show eth0}} command from the {{Pkg|iproute2}} package.<br />
<br />
For some (incompliant) routers, you will not be able to connect properly unless you comment the line<br />
require dhcp_server_identifier<br />
in {{ic|/etc/dhcpcd.conf}} (note that this file is distinct from {{ic|dhcpd.conf}}). This should not cause issues unless you have multiple DHCP servers on your network (not typical); see [http://technet.microsoft.com/en-us/library/cc977442.aspx this page] for more information.<br />
<br />
=== Hostname problems ===<br />
<br />
{{Accuracy|no description of the problem|Talk:NetworkManager#Hostname_problems_Entry}}<br />
<br />
Add the following line to /etc/NetworkManager/NetworkManager.conf:<br />
dhcp=dhcpcd<br />
then restart.<br />
systemctl restart NetworkManager<br />
source https://bbs.archlinux.org/viewtopic.php?id=152376<br />
<br />
=== Missing default route ===<br />
<br />
On at least one KDE4 system, no default route was created when establishing wireless connections with NetworkManager. Changing the route settings of the wireless connection to remove the default selection "Use only for resources on this connection" solved the issue.<br />
<br />
=== 3G modem not detected ===<br />
<br />
See [[USB_3G_Modem#Network_Manager]].<br />
<br />
=== Switching off WLAN on laptops ===<br />
<br />
Sometimes NetworkManager will not work when you disable your Wi-Fi adapter with a switch on your laptop and try to enable it again afterwards. This is often a problem with {{ic|rfkill}}. Install {{Pkg|rfkill}} from the [[official repositories]] and use <br />
<br />
$ watch -n1 rfkill list all<br />
<br />
to check if the driver notifies {{ic|rfkill}} about the wireless adapter's status.<br />
If one identifier stays blocked after you switch on the adapter you could try to manually unblock it with (where X is the number of the identifier provided by the above output):<br />
<br />
# rfkill event unblock X<br />
<br />
=== Static IP settings revert to DHCP ===<br />
<br />
Due to an unresolved bug, when changing default connections to static IP, {{ic|nm-applet}} may not properly store the configuration change, and will revert to automatic DHCP.<br />
<br />
To work around this issue you have to edit the default connection (e.g. "Auto eth0") in {{ic|nm-applet}}, change the connection name (e.g. "my eth0"), uncheck the "Available to all users" checkbox, change your static IP settings as desired, and click '''Apply'''. This will save a new connection with the given name.<br />
<br />
Next, you will want to make the default connection not connect automatically. To do so, run {{ic|nm-connection-editor}} (''not'' as root). In the connection editor, edit the default connection (eg "Auto eth0") and uncheck "Connect automatically". Click '''Apply''' and close the connection editor.<br />
<br />
=== Cannot edit connections as normal user ===<br />
<br />
See [[#Set_up_PolicyKit_permissions]].<br />
<br />
=== Forget hidden wireless network ===<br />
<br />
Since hidden network are not displayed in the selection list of the Wireless view, they cannot be forgotten (removed) with the GUI. You can delete one with the following command:<br />
<br />
# rm /etc/NetworkManager/system-connections/[SSID]<br />
<br />
This works for any other connection.<br />
<br />
=== VPN not working in Gnome ===<br />
<br />
When setting up openconnect or vpnc connections in NetworkManager while using Gnome, you'll sometimes never see the dialog box pop up and the following error appears in /var/log/errors.log:<br />
<br />
localhost NetworkManager[399]: <error> [1361719690.10506] [nm-vpn-connection.c:1405] get_secrets_cb(): Failed to request VPN secrets #3: (6) No agents were available for this request.<br />
<br />
This is caused by the Gnome NM Applet expecting dialog scripts to be at /usr/lib/gnome-shell, when NetworkManager's packages put them in /usr/lib/networkmanager.<br />
As a "temporary" fix (this bug has been around for a while now), make the following symlink(s):<br />
<br />
# For OpenConnect<br />
ln -s /usr/lib/networkmanager/nm-openconnect-auth-dialog /usr/lib/gnome-shell/ <br />
<br />
# For VPNC (i.e. Cisco VPN)<br />
ln -s /usr/lib/networkmanager/nm-vpnc-auth-dialog /usr/lib/gnome-shell/<br />
<br />
This may need to be done for any other NM VPN plugins as well, but these are the two most common.<br />
<br />
== Tips and tricks ==<br />
<br />
=== Sharing internet connection over Wi-Fi ===<br />
<br />
You can share your internet connection (e.g.: 3G or wired) with a few clicks using nm. You will need a supported Wi-Fi card (Cards based on Atheros AR9xx or at least AR5xx are probably best choice)<br />
<br />
==== Ad-hoc ====<br />
<br />
* [[pacman|Install]] the {{Pkg|dnsmasq}} package to be able to actually share the connection.<br />
* Custom dnsmasq.conf may interfere with nm (not sure about this, but i think so).<br />
* Click on nm-applet -> Create new wireless network.<br />
* Follow wizard (if using WEP be sure to use 5 or 13 character long password, different lengths will fail).<br />
* Settings will remain stored for the next time you need it.<br />
<br />
==== Real AP ====<br />
<br />
Support of infrastructure mode (which is needed by Android phones as they do not intentionally support ad-hoc) is not currently supported by NetworkManager, but is in active development...<br />
<br />
See: http://fedoraproject.org/wiki/Features/RealHotspot<br />
<br />
=== Checking if networking is up inside a cron job or script ===<br />
<br />
Some cron jobs require networking to be up to succeed. You may wish to avoid running these jobs when the network is down. To accomplish this, add an '''if''' test for networking that queries NetworkManager's {{ic|nm-tool}} and checks the state of networking. The test shown here succeeds if any interface is up, and fails if they are all down. This is convenient for laptops that might be hardwired, might be on wireless, or might be off the network. <br />
if [ `nm-tool|grep State|cut -f2 -d' '` == "connected" ]; then<br />
#Whatever you want to do if the network is online<br />
else<br />
#Whatever you want to do if the network is offline - note, this and the else above are optional<br />
fi<br />
<br />
This useful for a {{ic|cron.hourly}} script that runs {{ic|fpupdate}} for the F-Prot virus scanner signature update, as an example. Another way it might be useful, with a little modification, is to differentiate between networks using various parts of the output from {{ic|nm-tool}}; for example, since the active wireless network is denoted with an asterisk, you could grep for the network name and then grep for a literal asterisk.<br />
<br />
=== Automatically unlock keyring after login ===<br />
<br />
==== GNOME ====<br />
<br />
# Right click on the {{ic|nm-applet}} icon in your panel and select Edit Connections and open the Wireless tab<br />
# Select the connection you want to work with and click the Edit button<br />
# Check the boxes “Connect Automatically” and “Available to all users”<br />
Log out and log back in to complete.<br />
<br />
{{Note|The following method is dated and known not to work on at least one machine!}}<br />
* In {{ic|/etc/pam.d/gdm}} (or your corresponding daemon in {{ic|/etc/pam.d}}), add these lines at the end of the "auth" and "session" blocks if they do not exist already: <br />
auth optional pam_gnome_keyring.so<br />
session optional pam_gnome_keyring.so auto_start<br />
<br />
* In {{ic|/etc/pam.d/passwd}}, use this line for the 'password' block:<br />
password optional pam_gnome_keyring.so<br />
<br />
:Next time you log in, you should be asked if you want the password to be unlocked automatically on login.<br />
<br />
==== KDE ====<br />
{{Note|See http://live.gnome.org/GnomeKeyring/Pam for reference, and if you are using KDE with KDM, you can use {{AUR|pam-keyring-tool}} from the [[AUR]].}}<br />
<br />
Put a script like the following in {{ic|~/.kde4/Autostart}}:<br />
#!/bin/sh<br />
echo PASSWORD | /usr/bin/pam-keyring-tool --unlock --keyring=default -s<br />
Similar should work with Openbox, LXDE, etc.<br />
<br />
==== SLiM login manager ====<br />
See [[Slim#SLiM and Gnome Keyring]].<br />
<br />
=== Ignore specific devices ===<br />
<br />
Sometimes it may be desired that NetworkManager ignores specific devices and does not try to configure addresses and routes for them.You can quickly and easily ignore devices by MAC by using the following in {{ic|/etc/NetworkManager/NetworkManager.conf}} :<br />
[keyfile]<br />
unmanaged-devices=mac:00:22:68:1c:59:b1;mac:00:1E:65:30:D1:C4<br />
After you have put this in, [[Daemon|restart]] NetworkManager, and you should be able to configure interfaces without NetworkManager altering what you have set.<br />
<br />
=== Connect faster ===<br />
<br />
{{Merge|Network_Configuration#Additional_settings|This section contains mostly generally applicable tips.}}<br />
<br />
==== Disabling IPv6 ====<br />
<br />
Slow connection or reconnection to the network may be due to superfluous IPv6 queries in NetworkManager. If there is no IPv6 support on the local network, connecting to a network may take longer than normal while NetworkManager tries to establish an IPv6 connection that eventually times out. The solution is to disable IPv6 within NetworkManager which will make network connection faster. This has to be done once for every network you connect to.<br />
<br />
* Right-click on the network status icon.<br />
* Click on "Edit Connections".<br />
* Go to the "Wired" or "Wireless" tab, as appropriate.<br />
* Select the name of the network.<br />
* Click on "Edit".<br />
* Go to the "IPv6 Settings" tab.<br />
* In the "Method" dropdown, choose "Ignore/Disabled".<br />
* Click on "Save".<br />
<br />
==== Speed up DHCP by disabling ARP probing in DHCPCD ====<br />
<br />
{{ic|dhcpcd}} contains an implementation of a recommendation of the DHCP standard ([http://www.ietf.org/rfc/rfc2131.txt RFC2131] section 2.2) to check via ARP if the assigned IP address is really not taken. This seems mostly useless in home networks, so you can save about 5 seconds on every connect by adding the following line to {{ic|/etc/dhcpcd.conf}}:<br />
<br />
noarp<br />
<br />
This is equivalent to passing {{ic|--noarp}} to {{ic|dhcpcd}}, and disables the described ARP probing, speeding up connections to networks with DHCP.<br />
<br />
==== Use OpenDNS servers ====<br />
<br />
Create {{ic|/etc/resolv.conf.opendns}} with the nameservers:<br />
<br />
nameserver 208.67.222.222<br />
nameserver 208.67.220.220<br />
<br />
or use Google DNS servers, because people have been getting ads via the OpenDNS servers lately <br />
<br />
nameserver 8.8.8.8<br />
nameserver 8.8.4.4<br />
<br />
And have the dispatcher replace the discovered DHCP servers with the OpenDNS ones:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/dns-servers-opendns|<nowiki><br />
#!/bin/bash<br />
# Use OpenDNS servers over DHCP discovered servers<br />
<br />
cp -f /etc/resolv.conf.opendns /etc/resolv.conf</nowiki>}}<br />
<br />
Make the script executable:<br />
<br />
# chmod +x /etc/NetworkManager/dispatcher.d/dns-servers-opendns</div>Nahant