https://wiki.archlinux.org/api.php?action=feedcontributions&user=EasyToRemember&feedformat=atomArchWiki - User contributions [en]2024-03-28T21:14:18ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=GNOME&diff=705766GNOME2021-12-13T18:38:50Z<p>EasyToRemember: /* Autostart */ gnome-tweaks does not show autostarted apps from /etc/xdg/autostart</p>
<hr />
<div>[[Category:GNOME]]<br />
[[de:GNOME]]<br />
[[es:GNOME]]<br />
[[fr:GNOME]]<br />
[[it:GNOME]]<br />
[[ja:GNOME]]<br />
[[pt:GNOME]]<br />
[[ru:GNOME]]<br />
[[zh-hans:GNOME]]<br />
[[zh-hant:GNOME]]<br />
{{Related articles start}}<br />
{{Related|Desktop environment}}<br />
{{Related|GTK}}<br />
{{Related|GDM}}<br />
{{Related|GNOME/Tips and tricks}}<br />
{{Related|GNOME/Troubleshooting}}<br />
{{Related|GNOME/Files}}<br />
{{Related|GNOME/Gedit}}<br />
{{Related|GNOME/Web}}<br />
{{Related|GNOME/Evolution}}<br />
{{Related|GNOME/Flashback}}<br />
{{Related|GNOME/Keyring}}<br />
{{Related|GNOME/Document viewer}}<br />
{{Related|Official repositories#gnome-unstable}}<br />
{{Related articles end}}<br />
<br />
[[Wikipedia:GNOME|GNOME]] (/(ɡ)noʊm/) is a [[desktop environment]] that aims to be simple and easy to use. It is designed by [[Wikipedia:The GNOME Project|The GNOME Project]] and is composed entirely of free and open-source software. The default display is [[Wayland]] instead of [[Xorg]] and the available sessions are<br />
<br />
* '''GNOME''', the default, runs GNOME Shell on [[Wayland]]. Traditional X applications are run through Xwayland.<br />
* '''GNOME Classic''' provides a "[https://help.gnome.org/users/gnome-help/stable/gnome-classic.html traditional desktop experience]" (with an interface similar to GNOME 2) by using [https://web.archive.org/web/20190503163814/http://www.worldofgnome.org/welcome-to-gnome-3-8-flintstones-mode/ certain extensions and values]. Thus, it is a customized form of GNOME Shell rather than a truly distinct mode.<br />
* '''GNOME on Xorg''' runs GNOME Shell using [[Xorg]].<br />
<br />
== Installation ==<br />
<br />
Two groups are available:<br />
<br />
* {{Grp|gnome}} contains the base GNOME desktop and a subset of well-integrated [https://wiki.gnome.org/Apps applications];<br />
* {{Grp|gnome-extra}} contains further GNOME applications, including an email client, an IRC client, [[#Advanced settings|GNOME Tweaks]], and a set of games. Note that this group builds on the {{Grp|gnome}} group.<br />
<br />
The base desktop consists of [[Wikipedia:GNOME_Shell|GNOME Shell]], a plugin for the [[Wikipedia:Mutter_(software)|Mutter]] window manager. It can be installed separately with {{Pkg|gnome-shell}}.<br />
<br />
{{Note|''mutter'' acts as a composite manager for the desktop, employing hardware graphics acceleration to provide effects aimed at reducing screen clutter. The GNOME session manager automatically detects if your video driver is capable of running GNOME Shell and if not, falls back to software rendering using ''llvmpipe''.}}<br />
<br />
Unstable releases can also be used, see [[Official repositories#gnome-unstable]].<br />
<br />
== Starting ==<br />
<br />
GNOME can be started either graphically with a [[display manager]] or manually from the console (some features may be missing). The display manager included in {{Grp|gnome}} is [[GDM]].<br />
<br />
{{Note|Support for screen locking (and more) in GNOME is provided by GDM. If GNOME is not started with GDM, another screen locker may be used. See [[List of applications/Security#Screen lockers]].}}<br />
<br />
=== Graphically ===<br />
<br />
If you installed the {{Grp|gnome}} group and want GNOME to start automatically on next boot, [[enable]] {{ic|gdm.service}}. You can then select the desired session: ''GNOME'', ''GNOME Classic'' (only displayed if {{Pkg|gnome-shell-extensions}} is installed), or ''GNOME on Xorg'' from the display manager's session menu.<br />
<br />
If you prefer to start GNOME right away, thereby avoiding a reboot, [[start]] the aforementioned {{ic|gdm.service}} from a graphically unoccupied tty instead.<br />
<br />
=== Manually ===<br />
<br />
==== Xorg sessions ====<br />
<br />
* For the GNOME on Xorg session, add to the {{ic|~/.xinitrc}} file (see [https://gitlab.gnome.org/GNOME/gtk/issues/1390#note_344758] for details): {{bc|<nowiki><br />
export XDG_SESSION_TYPE=x11<br />
export GDK_BACKEND=x11<br />
exec gnome-session<br />
</nowiki>}}<br />
* For the GNOME Classic session, add to the {{ic|~/.xinitrc}} file: {{bc|<nowiki><br />
export XDG_CURRENT_DESKTOP=GNOME-Classic:GNOME<br />
export GNOME_SHELL_SESSION_MODE=classic<br />
exec gnome-session<br />
</nowiki>}}<br />
<br />
After editing the {{ic|~/.xinitrc}} file, GNOME can be launched with the {{ic|startx}} command (see [[xinitrc]] for additional details, such as preserving the logind session). After setting up the {{ic|~/.xinitrc}} file it can also be arranged to [[Start X at login]], e.g. on tty1 by adding to {{ic|.bash_profile}}:<br />
<br />
{{bc|<nowiki><br />
if [[ -z $DISPLAY && $(tty) == /dev/tty1 ]]; then<br />
XDG_SESSION_TYPE=x11 GDK_BACKEND=x11 exec startx<br />
fi<br />
</nowiki>}}<br />
<br />
==== Wayland sessions ====<br />
<br />
{{Accuracy|Executing {{ic|gnome-session}} via dbus may cause issues or not work at all. Some issues include the inability to start Chrome/Chromium and the lack of a sound device. Running {{ic|gnome-session}} directly may work better.|section=Manually start a Wayland session}}<br />
<br />
{{Note|An X server is still necessary to run applications that have not yet been ported to [[Wayland]], see [[Wayland#XWayland]] for details. Applications using certain graphics libraries, such as Qt, can be forced to use Wayland by setting environment variables. See [[Wayland#GUI libraries]] for more information.}}<br />
<br />
Manually starting a Wayland session is possible with {{ic|1=XDG_SESSION_TYPE=wayland dbus-run-session gnome-session}}. Alternatively, call {{ic|gnome-shell}} directly with its wayland flag from any available tty:<br />
<br />
$ gnome-shell --wayland<br />
<br />
Note that manual invocation of Gnome does '''not''' require {{ic|gdm}} (consequently also the accompanying {{ic|gdm.service}}) at all and is thus also accessible for users with a (possibly very) minimal installation of Gnome composing of a selected few packages included in the more inclusive {{ic|gnome}} group in accordance to personal preference.<br />
<br />
To start on login to tty1, add the previous line of code to your {{ic|.bash_profile}}. Firefox and QT applications do not respect {{ic|XDG_SESSION_TYPE}}, so add variables for them as well:<br />
<br />
{{bc|<nowiki><br />
if [[ -z $DISPLAY && $(tty) == /dev/tty1 && $XDG_SESSION_TYPE == tty ]]; then<br />
MOZ_ENABLE_WAYLAND=1 QT_QPA_PLATFORM=wayland XDG_SESSION_TYPE=wayland exec dbus-run-session gnome-session<br />
fi<br />
</nowiki>}}<br />
<br />
=== GNOME applications in Wayland ===<br />
<br />
When the ''GNOME'' session is used, GNOME applications will be run using Wayland. For debugging cases, https://docs.gtk.org/gtk3/running.html and https://docs.gtk.org/gtk4/running.html list options and environment variables.<br />
<br />
== Navigation ==<br />
<br />
To learn how to use the GNOME shell effectively read the [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]; it highlights GNOME shell features and keyboard shortcuts. Features include task switching, keyboard use, window control, the panel, overview mode, and more. A few of the shortcuts are:<br />
<br />
* {{ic|Super+m}}: show notification list<br />
* {{ic|Super+a}}: show application grid<br />
* {{ic|Alt+Tab}}: cycle active applications<br />
* {{ic|Alt+`}} (the key above {{ic|Tab}} on US keyboard layouts): cycle windows of the application in the foreground<br />
* {{ic|Alt+F2}}, then enter {{ic|r}} or {{ic|restart}}: restart the shell in case of graphical shell problems (only in X/legacy mode, not in Wayland mode).<br />
<br />
See [https://help.gnome.org/users/gnome-help/stable/keyboard-nav.html Keyboard navigation] for more shortcuts.<br />
<br />
{{Tip|To make {{ic|Alt+Tab}} switch applications only in current workspace, you can set {{ic|current-workspace-only}} to {{ic|true}}:<br />
<br />
$ gsettings set org.gnome.shell.app-switcher current-workspace-only true<br />
}}<br />
<br />
== Legacy names ==<br />
<br />
{{Note|Some GNOME programs have undergone name changes where the application's name in documentation and about dialogs has been changed but the executable name has not. A few such applications are listed in the table below.}}<br />
<br />
{{Tip|Searching for the legacy name of an application in the Shell search bar will successfully return the application in question. For instance, searching for ''nautilus'' will return ''Files''.}}<br />
<br />
{| class="wikitable"<br />
! Current<br />
! Legacy<br />
|-<br />
| [[GNOME/Files|Files]]<br />
| Nautilus<br />
|-<br />
| [[GNOME/Web|Web]]<br />
| Epiphany<br />
|-<br />
| Videos<br />
| Totem<br />
|-<br />
| Main Menu<br />
| Alacarte<br />
|-<br />
| [[GNOME/Document viewer|Document Viewer]]<br />
| Evince<br />
|-<br />
| Disk Usage Analyzer<br />
| Baobab<br />
|-<br />
| Image Viewer<br />
| EoG (Eye of GNOME)<br />
|-<br />
| [[GNOME/Keyring|Passwords and Keys]]<br />
| Seahorse<br />
|-<br />
| GNOME Translation Editor<br />
| Gtranslator<br />
|}<br />
<br />
== Configuration ==<br />
<br />
GNOME Settings (''gnome-control-center'') and GNOME applications use the [[wikipedia:Dconf|dconf]] configuration system to store their settings.<br />
<br />
You can directly access the dconf database using the {{man|1|gsettings}} command line tool. This also allows you to configure settings not exposed by the user interfaces. Command line tool {{man|1|dconf}} can directly modify the underlying database, bypassing validation.<br />
<br />
Up until GNOME 3.24, settings were applied by the GNOME settings daemon (located at {{ic|/usr/lib/gnome-settings-daemon/gnome-settings-daemon}}), which could be run outside of a GNOME session.<br />
<br />
GNOME 3.24, however, replaced the GNOME settings daemon with several separate settings plugins {{ic|/usr/lib/gnome-settings-daemon/gsd-*}} which were later moved to {{ic|/usr/lib/gsd-*}}. These plugins are now controlled via desktop files under {{ic|/etc/xdg/autostart/}} (matching {{ic|org.gnome.SettingsDaemon.*.desktop}}). To run these plugins outside of a GNOME session, you will now need to copy/edit the appropriate [[desktop entries]] to {{ic|~/.config/autostart}}.<br />
<br />
The configuration is usually performed user-specific; this section does not cover how to create configuration templates for multiple users.<br />
<br />
=== System settings ===<br />
<br />
==== Color ====<br />
<br />
The daemon {{ic|colord}} reads the display's EDID and extracts the appropriate color profile. Most color profiles are accurate and no setup is required; however for those that are not accurate, or for older displays, color profiles can be put in {{ic|~/.local/share/icc/}} and directed to.<br />
<br />
==== Night Light ====<br />
<br />
GNOME comes with a built-in blue light filter similar to [[Redshift]]. You can enable and customise the time you want to enable Night Light from the display settings menu. Furthermore, you can tweak the kelvin temperature with the following {{Pkg|dconf}} setting, where 5000 is an example value:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.color night-light-temperature 5000<br />
<br />
{{Tip|To change the daytime temperature in a Wayland session, install the [https://extensions.gnome.org/extension/1276/night-light-slider/ Night Light Slider extension].}}<br />
<br />
==== Date & time ====<br />
<br />
If the system has a configured [[Network Time Protocol daemon]], it will be effective for GNOME as well. The synchronization can be set to manual control from the menu, if required.<br />
<br />
GNOME supports automatic time zone selection (can be enabled in ''Date & Time'' section of the system settings, given that location services are enabled (see ''Privacy'' section of the settings).<br />
<br />
To show the date in the top bar, execute:<br />
<br />
$ gsettings set org.gnome.desktop.interface clock-show-date true<br />
<br />
Additionally, to show week numbers in the calendar opened on the top bar, execute:<br />
<br />
$ gsettings set org.gnome.desktop.calendar show-weekdate true<br />
<br />
==== Default applications ====<br />
<br />
Upon installing GNOME for the first time, you may find that the wrong applications are handling certain protocols. For example, ''totem'' opens videos instead of a previously used [[VLC]]. Some of the associations can be set from system settings via ''Default Applications''.<br />
<br />
For other protocols and methods see [[Default applications]] for configuration.<br />
<br />
==== Mouse and touchpad ====<br />
<br />
Most touchpad settings can be set from system settings via ''Mouse & Touchpad''.<br />
<br />
Depending on your device, other configuration settings may be available, but not exposed via the default GUI. For example, a different touchpad {{ic|click-method}}<br />
<br />
{{hc|$ gsettings range org.gnome.desktop.peripherals.touchpad click-method|<br />
enum<br />
'default'<br />
'none'<br />
'areas'<br />
'fingers'<br />
}}<br />
<br />
to be set manually:<br />
<br />
$ gsettings set org.gnome.desktop.peripherals.touchpad click-method 'fingers'<br />
<br />
or via {{Pkg|gnome-tweaks}}.<br />
<br />
{{Note|1=The [[synaptics]] driver is not supported by GNOME. Instead, you should use [[libinput]]. See [https://bugzilla.gnome.org/show_bug.cgi?id=764257#c12 this bug report].}}<br />
<br />
==== Network ====<br />
<br />
[[NetworkManager]] is the native tool of the GNOME project to control network settings from the shell, and is part of {{Grp|gnome}} group. If not installed already, [[install]] the {{Pkg|networkmanager}} package and [[enable]] the {{ic|NetworkManager.service}} systemd unit.<br />
<br />
While any other [[network manager]] can be used as well, NetworkManager provides the full integration via the shell network settings and a status indicator applet {{Pkg|network-manager-applet}} (not required for GNOME).<br />
<br />
{{Note|1=Hidden wireless networks set up with {{Pkg|networkmanager}}'s ''nmtui'' do not connect automatically. You need to create a new profile using GNOME control center in order to restore auto-connect capabilities for that network.}}<br />
<br />
==== Online accounts ====<br />
<br />
Some online accounts, such as [[ownCloud]], require {{Pkg|gvfs-goa}} to be installed for full functionality in GNOME applications such as [[GNOME Files]] and GNOME Documents [https://wiki.gnome.org/ThreePointSeven/Features/Owncloud].<br />
<br />
See [https://help.gnome.org/users/gnome-help/stable/accounts.html Online accounts] for more information.<br />
<br />
==== Search ====<br />
<br />
The GNOME shell has a search that can be quickly accessed by pressing the {{ic|Super}} key and starting to type. The {{Pkg|tracker}} package is installed by default as a part of {{Grp|gnome}} group and provides an indexing application and metadata database. It can be configured with the ''Search and Indexing'' menu item; monitor status with ''tracker-control''. It is started automatically by ''gnome-session'' when the user logs in. Indexing can be started manually with {{ic|tracker-control -s}}. Search settings can also be configured in Settings.<br />
<br />
The Tracker database can be queried using the ''tracker-sparql'' command. See {{man|1|tracker-sparql}} for more information.<br />
<br />
=== Advanced settings ===<br />
<br />
As noted above, many configuration options such as changing the [[GTK]] theme or the [[window manager]] theme are not exposed in GNOME Settings (''gnome-control-center''). Those users that want to configure these settings may wish to use the GNOME Tweaks ({{Pkg|gnome-tweaks}}), a convenient graphical tool which exposes many of these settings.<br />
<br />
GNOME settings (which are stored in the DConf database) can also be configured using the {{man|1|dconf-editor}} (a graphical DConf configuration tool) or the [https://developer.gnome.org/gio/stable/GSettings.html gsettings] command line tool. The GNOME Tweaks does not do anything else in the background of the GUI; note though that you will not find all settings described in the following sections in it.<br />
<br />
==== Appearance ====<br />
<br />
===== Themes =====<br />
<br />
GNOME uses Adwaita by default. To apply Adwaita dark only to GTK 2 applications use the following symlink:<br />
<br />
$ ln -s /usr/share/themes/Adwaita-dark ~/.themes/Adwaita<br />
<br />
To select new themes (move them to the appropriate directory and) use GNOME Tweaks or the GSettings commands below:<br />
<br />
For the GTK theme:<br />
<br />
$ gsettings set org.gnome.desktop.interface gtk-theme ''theme-name''<br />
<br />
For the icon theme:<br />
<br />
$ gsettings set org.gnome.desktop.interface icon-theme ''theme-name''<br />
<br />
{{Note|The window manager theme follows the GTK theme. Using {{ic|org.gnome.desktop.wm.preferences theme}} is deprecated and ignored.}}<br />
<br />
See [[GTK#Themes]] and [[Icons#Manually]].<br />
<br />
===== Titlebar height =====<br />
<br />
{{Note|Applying this configuration shrinks the titlebar of applications that do not use GNOME-style CSD. Native GNOME applications with CSD are not affected.}}<br />
<br />
{{hc|~/.config/gtk-3.0/gtk.css|<br />
headerbar.default-decoration {<br />
padding-top: 5px;<br />
padding-bottom: 5px;<br />
min-height: 0px;<br />
font-size: 0.8em;<br />
}<br />
<br />
headerbar.default-decoration button.titlebutton {<br />
padding: 0px;<br />
min-height: 0px;<br />
}<br />
}}<br />
<br />
See [https://askbot.fedoraproject.org/en/question/10035/shrink-title-bar/?answer=86149#post-id-86149] for more information.<br />
<br />
===== Titlebar button order =====<br />
<br />
To set the order for the GNOME window manager (Mutter, Metacity):<br />
<br />
$ gsettings set org.gnome.desktop.wm.preferences button-layout ':minimize,maximize,close'<br />
<br />
{{Tip|The colon indicates which side of the titlebar the window buttons will appear.}}<br />
<br />
===== Hide titlebar when maximized =====<br />
<br />
* [[Install]] {{AUR|gnome-shell-extension-gtktitlebar-git}}. Removes titlebars of maximized, non-GTK windows.<br />
* [[Install]] {{AUR|gnome-shell-extension-no-title-bar-git}} or {{AUR|gnome-shell-extension-no-title-bar}}. Maximized windows get the title bar merged into the activity bar.<br />
{{Note|The above extension does not work for gnome-shell version 3.32 or higher [https://github.com/franglais125/no-title-bar/issues/114].}}<br />
* [[Install]] {{AUR|mutter-hide-legacy-decorations}}. It changes a default setting in the window manager, so as to automatically hide the titlebar on legacy (non-headerbar) apps when they are maximized or tiled to the side.<br />
* [[Install]] {{AUR|gnome-shell-extension-pixel-saver-git}} or {{AUR|gnome-shell-extension-pixel-saver}}. Maximized windows get the title bar merged into the activity bar, saving precious pixels.<br />
<br />
===== GNOME Shell themes =====<br />
<br />
The theme of GNOME Shell itself is configurable. To use a Shell theme, firstly ensure that you have the {{Pkg|gnome-shell-extensions}} package installed. Then enable the ''User Themes'' extension, either through the GNOME Extensions application or through the [https://extensions.gnome.org GNOME Shell Extensions] webpage. Shell themes can then be loaded and selected using GNOME Extensions.<br />
<br />
There are a number of GNOME Shell themes available [https://aur.archlinux.org/packages.php?O=0&K=gnome-shell-theme&do_Search=Go&PP=50&SB=v&SO=d in the AUR]. Shell themes can also be downloaded from [https://gnome-look.org/ gnome-look.org].<br />
<br />
===== AppIndicators/Top bar icons =====<br />
<br />
To enable AppIndicators, which is useful for controlling/monitoring certain applications running in the background, Install {{Pkg|gnome-shell-extension-appindicator}} or {{AUR|gnome-shell-extension-appindicator-git}}, [[#Navigation|restart the GNOME Shell]], then enable the AppIndicator extension in the GNOME Extensions application or by running {{ic|$ gnome-extensions enable $(gnome-extensions list {{!}} grep -m 1 appindicatorsupport)}}.<br />
<br />
==== Apps grid folders ====<br />
<br />
{{Tip|The [https://github.com/prurigro/gnome-catgen gnome-catgen] ({{AUR|gnome-catgen-git}}) script allows you to manage folders through the creation of files in {{ic|~/.local/share/applications-categories}} named after each category and containing a list of the desktop files belonging to apps you would like to have inside. Optionally, you can have it cycle through each app without a folder and input the desired category until you {{ic|Ctrl+c}} or run out of apps.}}<br />
<br />
In the '''dconf-editor''' navigate to {{ic|org.gnome.desktop.app-folders}} and set the value of {{ic|folder-children}} to an array of comma separated folder names:<br />
<br />
['Utilities', 'Sundry']<br />
<br />
Add applications using {{ic|gsettings}}:<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ apps "['alacarte.desktop', 'dconf-editor.desktop']"<br />
<br />
This adds the applications {{ic|alacarte.desktop}} and {{ic|dconf-editor.desktop}} to the Sundry folder. This will also create the folder {{ic|org.gnome.desktop.app-folders.folders.Sundry}}.<br />
<br />
To name the folder (if it has no name that appears at the top of the applications):<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ name "Sundry"<br />
<br />
Applications can also be sorted by their category (specified in their ''.desktop'' file):<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ categories "['Office']"<br />
<br />
If certain applications matching a category are not wanted in a certain folder, exclusions can be set:<br />
<br />
$ gsettings set org.gnome.desktop.app-folders.folder:/org/gnome/desktop/app-folders/folders/Sundry/ excluded-apps "['libreoffice-draw.desktop']"<br />
<br />
For more information, see [https://gitlab.gnome.org/GNOME/gsettings-desktop-schemas/blob/master/schemas/org.gnome.desktop.app-folders.gschema.xml.in] and [[Gentoo:Gnome Applications Folders]].<br />
<br />
==== Autostart ====<br />
<br />
GNOME implements [[XDG Autostart]].<br />
<br />
The {{Pkg|gnome-tweaks}} allows managing autostart-entries.<br />
<br />
{{Tip|If the plus sign button in the Tweaks's Startup Applications section is unresponsive, try start the Tweaks from the terminal using the following command: {{ic|gnome-tweaks}}. See the following [https://bbs.archlinux.org/viewtopic.php?pid&#61;1413631#p1413631 forum thread].}}<br />
<br />
{{Note|The deprecated ''gnome-session-properties'' dialog can be added by [[install]]ing the {{AUR|gnome-session-properties}} package. Compared to gnome-tweaks, it also allows to disable the system-wide autostarted apps.}}<br />
<br />
==== Desktop ====<br />
<br />
===== Icons on the desktop =====<br />
<br />
Up until GNOME 3.28, icons on the desktop were provided by [[GNOME/Files|Files]] which would draw a transparent window over the desktop containing the icons. As of GNOME 3.28 this functionality has been removed and desktop icons are no longer available in GNOME. Possible workarounds include using [[Nemo]] (a fork of Files which still has desktop icons functionality) or installing {{AUR|gnome-shell-extension-desktop-icons}}, which replicates the desktop icon functionality available in GNOME 3.26 and prior, but with some minor differences. For more information, please see the following [https://bbs.archlinux.org/viewtopic.php?id=235633 Arch forum thread].<br />
<br />
===== Lock screen and background =====<br />
<br />
When setting the Desktop or Lock screen background, it is important to note that the Pictures tab will only display pictures located in {{ic|/home/''username''/Pictures}} folder. If you wish to use a picture not located in this folder, use the commands indicated below.<br />
<br />
For the desktop background:<br />
<br />
$ gsettings set org.gnome.desktop.background picture-uri 'file:///path/to/my/picture.jpg'<br />
<br />
For the lock screen background:<br />
<br />
$ gsettings set org.gnome.desktop.screensaver picture-uri 'file:///path/to/my/picture.jpg'<br />
<br />
===== Disable top left hot corner =====<br />
<br />
Starting from GNOME 3.34 you can disable it with this:<br />
<br />
$ gsettings set org.gnome.desktop.interface enable-hot-corners false<br />
<br />
or via {{Pkg|gnome-tweaks}}, in ''Top Bar > Activities Overview Hot Corner''<br />
<br />
===== Startup in Overview Mode =====<br />
<br />
Starting from GNOME 40, the desktop will start directly into Overview Mode instead of an empty desktop (like in previous versions). To mimic legacy behaviour, one may install the extension [https://extensions.gnome.org/extension/4099/no-overview/ No overview at start-up].<br />
<br />
See the discussion at [https://discourse.gnome.org/t/gnome-40-login-is-to-the-activities-overview-mode-how-do-you-disable-this/5783].<br />
<br />
==== Extensions ====<br />
<br />
The catalogue of extensions is available at https://extensions.gnome.org. They can be installed and activated in a browser by setting the switch in the top left of the screen to '''ON''' and clicking '''Install''' on the popup window (if the extension in question is not installed). Installed extensions may be seen at https://extensions.gnome.org/local/, where available updates can be checked. Installed extensions can also be enabled or disabled through a GUI with ''gnome-extensions-app'' or from the command line with {{man|1|gnome-extensions}}.<br />
<br />
{{Note|Installing extensions from https://extensions.gnome.org using a browser requires the installation of {{AUR|chrome-gnome-shell}} and the appropriate browser extension.}}<br />
<br />
GNOME Shell can be customized with extensions per user or system-wide. Installing extensions with [[pacman]] makes them available for all users of the system and automates the update process.<br />
<br />
The {{Pkg|gnome-shell-extensions}} package provides a set of extensions maintained as part of the GNOME project (many of the included extensions are used by the GNOME Classic session). Users who want a taskbar but do not wish to use the GNOME Classic session may want to enable the ''Window list'' extension (provided by the aforementioned package).<br />
<br />
To list currently enabled extensions:<br />
<br />
$ gsettings get org.gnome.shell enabled-extensions<br />
<br />
The above command may list extensions that have been removed. To only list extensions that are enabled ''and'' installed, use ''gnome-extensions'' instead:<br />
<br />
$ gnome-extensions list --enabled<br />
<br />
For more information about GNOME shell extensions, see https://extensions.gnome.org/about/.<br />
<br />
==== Fonts ====<br />
<br />
{{Tip|If you set the ''Scaling factor'' to a value above 1.00, the Accessibility menu will be automatically enabled.}}<br />
<br />
Fonts can be set for Window titles, Interface (applications), Documents and Monospace. See the Fonts tab in the Tweaks for the relevant options.<br />
<br />
For hinting, RGBA will likely be desired as this fits most monitors types, and if fonts appear too blocked reduce hinting to ''Slight'' or ''None''.<br />
<br />
==== WEBP, thumbnails ====<br />
<br />
[[Install]] {{Pkg|webp-pixbuf-loader}} to make GNOME's image viewer ({{Pkg|eog}}) work with WEBP images, and add a thumbnailer which creates thumbnails for WEBP images to display them in [[GNOME Files]].<br />
<br />
==== Input methods ====<br />
<br />
GNOME has integrated support for [[input method]]s through [[IBus]]. Only {{Pkg|ibus}} and the wanted input method engine (e.g. {{Pkg|ibus-libpinyin}} for Intelligent Pinyin) needed to be installed. After installation, the input method engine can be added as a keyboard layout under ''Keyboard > Input Sources'' in GNOME Settings (''gnome-control-center'').<br />
<br />
==== Keyboard Layout quirks ====<br />
<br />
If you are using an alternative keyboard layout like Neo2 which uses multiple layers/modifiers, you might need to go to ''Keyboard > Type Special Characters'' in GNOME Settings (''gnome-control-center'') and change the ''Alternate Characters Key'' away from ''Right Alt'' so that it can be used as a native modifier of the keyboard layout. Setting it to e.g. ''Left Alt'' prevents ''Alt+Tab'', so be careful what you change it to.<br />
Without this change, your left ''Mod3'' key might work, but the right one (''AltGr'') does not. (As of 2021-05-18)<br />
<br />
==== Power ====<br />
<br />
When you are using a laptop you might want to alter the following settings controlling behavior when idle, screen lock power button presses and lid close:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-timeout ''3600''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type ''hibernate''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-timeout ''1800''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-battery-type ''hibernate''<br />
$ gsettings set org.gnome.settings-daemon.plugins.power power-button-action ''suspend''<br />
$ gsettings set org.gnome.desktop.lockdown disable-lock-screen ''true''<br />
<br />
To keep the monitor active when the lid is closed:<br />
<br />
$ gsettings set org.gnome.settings-daemon.plugins.xrandr default-monitors-setup do-nothing<br />
<br />
GNOME 3.24 deprecated the following settings:<br />
<br />
org.gnome.settings-daemon.plugins.power button-hibernate<br />
org.gnome.settings-daemon.plugins.power button-power<br />
org.gnome.settings-daemon.plugins.power button-sleep<br />
org.gnome.settings-daemon.plugins.power button-suspend<br />
org.gnome.settings-daemon.plugins.power critical-battery-action<br />
<br />
===== Do not suspend when laptop lid is closed =====<br />
<br />
The settings panel of GNOME does not provide an option for the user to change the action triggered when the laptop lid is closed. However {{Pkg|gnome-tweaks}} can override the setting applied by {{Pkg|systemd}}. On the tab ''General'' turn off the switch ''Suspend when laptop lid is closed''. The system will then not ''Suspend to RAM (S3)'' on lid close.<br />
<br />
To change the lid switch action system-wide, ensure that the setting described above is '''not turned off''' and edit the systemd settings in {{ic|/etc/systemd/logind.conf}}. To turn off suspend on lid close, set {{ic|1=HandleLidSwitch=ignore}}, as described in [[Power management#ACPI events]].<br />
<br />
===== Change critical battery level action =====<br />
<br />
The settings panel does not provide an option for changing the critical battery level action. These settings have been removed from dconf as well. They are now managed by upower. Edit the upower settings in {{ic|/etc/UPower/UPower.conf}}. Find these settings and adjust to your needs.<br />
<br />
{{hc|head=/etc/UPower/UPower.conf|output=<br />
PercentageLow=10<br />
PercentageCritical=3<br />
PercentageAction=2<br />
CriticalPowerAction=HybridSleep<br />
}}<br />
<br />
===== Power modes =====<br />
<br />
See [[CPU frequency scaling#power-profiles-daemon]].<br />
<br />
The relevant package should already be installed as a dependency of {{Pkg|gnome-control-center}}. Explicitly [[starting/enabling]] the {{ic|power-profiles-daemon}} service is also unnecessary since ''gnome-shell'' and GNOME Settings both request its activation upon launching.<br />
<br />
When the service is active, power profiles can be managed through the ''Power'' section of GNOME Settings and in the system menu.<br />
<br />
=== Use a different window manager ===<br />
<br />
GNOME Shell does not support using a different [[window manager]], however [[GNOME Flashback]] provides sessions for Metacity and [[Compiz]]. Furthermore, it is possible to define your own [[GNOME/Tips and tricks#Custom GNOME sessions|custom GNOME sessions]] which use alternative components.<br />
<br />
== See also ==<br />
<br />
* [https://www.gnome.org/ Official Website]<br />
* [https://blogs.gnome.org/tbernard/2021/06/15/community-power-2/ Contributing to GNOME, feature requests, bugs, code]<br />
* [[Wikipedia:GNOME|Wikipedia article]]<br />
* [https://extensions.gnome.org/ GNOME-Shell Extensions]<br />
* [https://wiki.gnome.org/Projects/GnomeShell/CheatSheet GNOME Shell Cheat Sheet]<br />
* Customization (themes, icons...):<br />
** [https://wiki.gnome.org/Personalization Personalize GNOME]<br />
** [https://www.gnome-look.org/ GNOME Look]<br />
* GNOME applications:<br />
** [https://wiki.gnome.org/Apps GNOME Apps Index]<br />
** [[Wikipedia:GNOME Core Applications]]<br />
* GNOME Source/Mirrors:<br />
** [https://gitlab.gnome.org/ GNOME GitLab]<br />
** [https://github.com/GNOME GNOME Github Mirror]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=SpamAssassin&diff=639959SpamAssassin2020-10-28T14:07:30Z<p>EasyToRemember: /* Updating rules */ /etc/mail/spamassassin/sa-update-keys should be owned by spamd user.</p>
<hr />
<div>[[Category:Mail server]]<br />
{{Related articles start}}<br />
{{Related|Postfix#SpamAssassin}}<br />
{{Related articles end}}<br />
[https://spamassassin.apache.org/ SpamAssassin] is a mail filter to identify spam.<br />
<br />
== Installation ==<br />
<br />
Install the {{Pkg|spamassassin}} package. Next [[start]] and enable {{ic|spamassassin.service}}.<br />
<br />
== Usage ==<br />
<br />
Go over {{ic|/etc/mail/spamassassin/local.cf}} and configure it to your needs.<br />
<br />
=== Updating rules ===<br />
<br />
Update the SpamAssassin matching patterns and compile them:<br />
# sudo -u spamd sa-update && sudo -u spamd sa-compile<br />
<br />
You will want to run this periodically, the best way to do so is by setting up a [[Systemd/Timers]].<br />
<br />
Create the following service, which will run these commands:<br />
{{hc|1=/etc/systemd/system/spamassassin-update.service|2=<br />
[Unit]<br />
Description=spamassassin housekeeping stuff<br />
After=network.target<br />
<br />
[Service]<br />
#User=spamd<br />
#Group=spamd<br />
Type=oneshot<br />
<br />
# remove --allowplugins, if you do not want plugin updates from SA.<br />
ExecStart=sudo -u spamd /usr/bin/vendor_perl/sa-update --allowplugins<br />
SuccessExitStatus=1<br />
ExecStart=sudo -u spamd /usr/bin/vendor_perl/sa-compile<br />
ExecStart=/usr/bin/systemctl -q --no-block try-restart spamassassin.service<br />
<br />
# uncomment the following ExecStart line to train SA's bayes filter<br />
# and specify the path to the mailbox that contains spam email(s)<br />
#ExecStart=/usr/bin/vendor_perl/sa-learn --spam <path_to_your_spam_mailbox><br />
}}<br />
<br />
Then create the timer, which will execute the previous service daily:<br />
{{hc|1=/etc/systemd/system/spamassassin-update.timer|2=<br />
[Unit]<br />
Description=spamassassin house keeping<br />
<br />
[Timer]<br />
OnCalendar=daily<br />
Persistent=true<br />
<br />
[Install]<br />
WantedBy=timers.target<br />
}}<br />
<br />
Now you can [[start]] and [[enable]] {{ic|spamassassin-update.timer}}.<br />
<br />
== Plugins ==<br />
<br />
=== ClamAV ===<br />
<br />
Install and setup clamd as described in [[ClamAV]].<br />
<br />
Follow one of the above instructions to call SpamAssassin from within your mail system.<br />
<br />
[[Install]] the {{pkg|perl-cpanplus-dist-arch}} package. Then install the ClamAV perl library as follows:<br />
<br />
# /usr/bin/vendor_perl/cpanp -i File::Scan::ClamAV<br />
Add the 2 files from http://wiki.apache.org/spamassassin/ClamAVPlugin into {{ic|/etc/mail/spamassassin/}}.<br />
Edit {{ic|/etc/mail/spamassassin/clamav.pm}} and update {{ic|$CLAM_SOCK}} to point to your Clamd socket location (default is {{ic|/run/clamav/clamd.ctl}}).<br />
<br />
Finally, [[restart]] {{ic|spamassassin.service}}.<br />
<br />
=== Razor ===<br />
<br />
{{Note|The last version was released 2008.[https://sourceforge.net/projects/razor/files/razor-agents/]}}<br />
<br />
[http://razor.sourceforge.net/ Vipul's Razor] is a distributed, collaborative, spam detection and filtering network.<br />
<br />
Make sure you have installed SpamAssassin first, then:<br />
<br />
[[Install]] the {{Pkg|razor}} package.<br />
<br />
Register with Razor.<br />
<br />
# mkdir /etc/mail/spamassassin/razor<br />
# chown spamd:spamd /etc/mail/spamassassin/razor<br />
# sudo -u spamd -s<br />
$ cd /etc/mail/spamassassin/razor<br />
$ razor-admin -home=/etc/mail/spamassassin/razor -register<br />
$ razor-admin -home=/etc/mail/spamassassin/razor -create<br />
$ razor-admin -home=/etc/mail/spamassassin/razor -discover<br />
<br />
To tell SpamAssassin about Razor, add the following line to {{ic|/etc/mail/spamassassin/local.cf}}:<br />
<br />
razor_config /etc/mail/spamassassin/razor/razor-agent.conf<br />
<br />
To tell Razor about itself, add the following line to {{ic|/etc/mail/spamassassin/razor/razor-agent.conf}}:<br />
<br />
razorhome = /etc/mail/spamassassin/razor/<br />
<br />
Finally, [[restart]] {{ic|spamassassin.service}}.</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Fail2ban&diff=639957Fail2ban2020-10-28T13:53:57Z<p>EasyToRemember: /* Service hardening */ Removed NoNewPrivileges=yes because it effectively disables postfix. https://lists.freedesktop.org/archives/systemd-devel/2014-June/020305.html</p>
<hr />
<div>[[Category:Firewalls]]<br />
[[Category:Secure Shell]]<br />
[[es:Fail2ban]]<br />
[[ja:Fail2ban]]<br />
[[ru:Fail2ban]]<br />
{{Related articles start}}<br />
{{Related|sshguard}}<br />
{{Related|Security}}<br />
{{Related articles end}}<br />
[https://www.fail2ban.org/wiki/index.php/Main_Page Fail2ban] scans log files (e.g. {{ic|/var/log/httpd/error_log}}) and bans IPs that show the malicious signs like too many password failures, seeking for exploits, etc. Generally Fail2ban is then used to update [[firewall]] rules to reject the IP addresses for a specified amount of time, although any other arbitrary action (e.g. sending an email) could also be configured. <br />
<br />
{{Warning|Using an IP banning software will stop trivial attacks but it relies on an additional daemon and successful logging. Additionally, if the attacker knows your IP address, they can send packets with a spoofed source header and get your IP address banned. Make sure to specify your IP in {{ic|ignoreip}}.}}<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|fail2ban}}.<br />
<br />
== Usage ==<br />
<br />
[[#Configuration|Configure]] Fail2ban and [[enable]]/[[start]] {{ic|fail2ban.service}}.<br />
<br />
=== fail2ban-client ===<br />
<br />
The fail2ban-client allows monitoring jails (reload, restart, status, etc.), to view all available commands:<br />
<br />
$ fail2ban-client<br />
<br />
To view all enabled jails:<br />
<br />
# fail2ban-client status<br />
<br />
To check the status of a jail, e.g. for ''sshd'':<br />
<br />
{{hc|# fail2ban-client status sshd|<nowiki><br />
Status for the jail: sshd<br />
|- Filter<br />
| |- Currently failed: 1<br />
| |- Total failed: 9<br />
| `- Journal matches: _SYSTEMD_UNIT=sshd.service + _COMM=sshd<br />
`- Actions<br />
|- Currently banned: 1<br />
|- Total banned: 1<br />
`- Banned IP list: 0.0.0.0<br />
</nowiki>}}<br />
<br />
== Configuration ==<br />
<br />
Due to the possibility of the {{ic|/etc/fail2ban/jail.conf}} file being overwritten or improved during a distribution update, it is recommended to [[create]] a {{ic|/etc/fail2ban/jail.local}} file. For example to change the default ban time to 1 day:<br />
<br />
{{hc|/etc/fail2ban/jail.local|<nowiki><br />
[DEFAULT]<br />
bantime = 1d<br />
</nowiki>}}<br />
<br />
Or create separate ''name.local'' files under the {{ic|/etc/fail2ban/jail.d}} directory, e.g. {{ic|/etc/fail2ban/jail.d/sshd.local}}.<br />
<br />
[[Restart]] {{ic|fail2ban.service}} to apply the configuration changes.<br />
<br />
=== Enabling jails ===<br />
By default all jails are disabled. [[Append]] {{ic|1=enabled = true}} to the jail you want to use, e.g. to enable the [[OpenSSH]] jail:<br />
<br />
{{hc|/etc/fail2ban/jail.local|2=<br />
[sshd]<br />
enabled = true<br />
}}<br />
<br />
See [[#Custom SSH jail]].<br />
<br />
=== Receive an alert e-mail ===<br />
<br />
If you want to receive an e-mail when someone has been banned, you have to configure an SMTP client (e.g. [[msmtp]]) and change default action, as given below.<br />
<br />
{{hc|/etc/fail2ban/jail.local|<nowiki><br />
[DEFAULT]<br />
destemail = yourname@example.com<br />
sender = yourname@example.com<br />
<br />
# to ban & send an e-mail with whois report to the destemail.<br />
action = %(action_mw)s<br />
<br />
# same as action_mw but also send relevant log lines<br />
#action = %(action_mwl)s<br />
</nowiki>}}<br />
<br />
=== Firewall and services ===<br />
<br />
By default, Fail2ban uses [[Iptables]]. However, configuration of most [[firewalls]] and services is straightforward. For example, to use [[Nftables]]:<br />
<br />
{{hc|/etc/fail2ban/jail.local|<nowiki><br />
[DEFAULT]<br />
banaction = nftables<br />
</nowiki>}}<br />
<br />
See {{ic|/etc/fail2ban/action.d/}} for other examples, e.g. [https://github.com/fail2ban/fail2ban/blob/master/config/action.d/ufw.conf ufw.conf].<br />
<br />
== Tips and tricks ==<br />
<br />
=== Custom SSH jail ===<br />
<br />
{{Warning|If the attacker knows your IP address, they can send packets with a spoofed source header and get your IP address locked out of the server. [[SSH keys]] provide an elegant solution to the problem of brute forcing without these problems.}}<br />
<br />
Edit {{ic|/etc/fail2ban/jail.d/sshd.local}}, add this section and update the list of trusted IP addresses in {{ic|ignoreip}}:<br />
<br />
{{hc|/etc/fail2ban/jail.d/sshd.local|2=<br />
[sshd]<br />
enabled = true<br />
filter = sshd<br />
banaction = iptables<br />
backend = systemd<br />
maxretry = 5<br />
findtime = 1d<br />
bantime = 2w<br />
ignoreip = 127.0.0.1/8<br />
}}<br />
<br />
{{Note|<br />
* It may be necessary to set {{ic|LogLevel VERBOSE}} in {{ic|/etc/ssh/sshd_config}} to allow full fail2ban monitoring as otherwise password failures may not be logged correctly.<br />
* Fail2ban has IPv6 support since version 0.10. Adapt your [[firewall]] accordingly, e.g. [[start]]/[[enable]] {{ic|ip6tables.service}}.<br />
* When using journal namespaces (by adding {{ic|1=LogNamespace=''something''}} to a unit file), you can make fail2ban read those logs by setting {{ic|backend}} like this: {{ic|1=backend = systemd[journalfiles="/var/log/journal/*.''something''/system.journal"]}}.<br />
}}<br />
<br />
{{Tip|<br />
* If using [[iptables]] front-ends like [[ufw]], one can use {{ic|1=banaction = ufw}} instead of using iptables.<br />
* When using [[Shorewall]], one can use {{ic|1=banaction = shorewall}} and also set {{ic|BLACKLIST}} to {{ic|ALL}} in {{ic|/etc/shorewall/shorewall.conf}}, otherwise the rule added to ban an IP address will affect only new connections.<br />
}}<br />
<br />
=== Service hardening ===<br />
<br />
Currently, Fail2ban must be run as ''root''. Therefore, you may wish to consider hardening the process with [[systemd]].<br />
<br />
[[Create]] a [[Systemd#Drop-in files|drop-in]] configuration file for {{ic|fail2ban.service}}:<br />
<br />
{{hc|/etc/systemd/system/fail2ban.service.d/override.conf|2=<br />
[Service]<br />
PrivateDevices=yes<br />
PrivateTmp=yes<br />
ProtectHome=read-only<br />
ProtectSystem=strict<br />
ReadWritePaths=-/var/run/fail2ban<br />
ReadWritePaths=-/var/lib/fail2ban<br />
ReadWritePaths=-/var/log/fail2ban<br />
ReadWritePaths=-/var/spool/postfix/maildrop<br />
ReadWritePaths=-/run/xtables.lock<br />
CapabilityBoundingSet=CAP_AUDIT_READ CAP_DAC_READ_SEARCH CAP_NET_ADMIN CAP_NET_RAW<br />
}}<br />
<br />
The {{ic|CapabilityBoundingSet}} parameters {{ic|CAP_DAC_READ_SEARCH}} will allow Fail2ban full read access to every directory and file. {{ic|CAP_NET_ADMIN}} and {{ic|CAP_NET_RAW}} allow Fail2ban to operate on any firewall that has [[command-line shell]] interface. See {{man|7|capabilities}} for more info.<br />
<br />
By using {{ic|1=ProtectSystem=strict}} the [[filesystem]] hierarchy will only be read-only, {{ic|ReadWritePaths}} allows Fail2ban to have write access on required paths.<br />
<br />
Create {{ic|/etc/fail2ban/fail2ban.local}} with the correct {{ic|logtarget}} path:<br />
{{hc|/etc/fail2ban/fail2ban.local|<nowiki><br />
[Definition]<br />
logtarget = /var/log/fail2ban/fail2ban.log<br />
</nowiki>}}<br />
<br />
Create the {{ic|/var/log/fail2ban/}} directory as root.<br />
<br />
Finally, [[Systemd#Using_units|reload systemd daemon]] to apply the changes of the unit and [[restart]] {{ic|fail2ban.service}}.<br />
<br />
== See also ==<br />
<br />
* [https://www.the-art-of-web.com/system/fail2ban-action-whitelist/ Using a Fail2Ban Jail to Whitelist a User]<br />
* [https://www.the-art-of-web.com/system/fail2ban-filters/ Optimising your Fail2Ban filters]<br />
* [https://www.the-art-of-web.com/system/fail2ban-sendmail/ Fail2Ban and sendmail]<br />
* [https://www.the-art-of-web.com/system/fail2ban/ Fail2Ban and iptables]<br />
* [https://www.the-art-of-web.com/system/fail2ban-howto/ Fail2Ban 0.8.3 Howto]<br />
* [https://www.the-art-of-web.com/system/fail2ban-log/ Monitoring the fail2ban log]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590706LDAP authentication2019-12-01T16:18:41Z<p>EasyToRemember: /* PAM Configuration */ Added info on Gnome Keyring</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[#Online Authentication|online-only]] or [[#Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=example,dc=org<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
<br />
# OpenLDAP supports posixGroup, uncomment the following two lines<br />
# to get group membership support (and comment the other conflicting parameters)<br />
#ldap_schema = rfc2307<br />
#ldap_group_member = memberUid<br />
<br />
# Other LDAP servers may support this instead<br />
ldap_schema = rfc2307bis<br />
ldap_group_member = uniqueMember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
{{Note|If you happen to use [[GNOME/Keyring]]: adding 'sufficient' in the beginning of the PAM stack results in Gnome Keyring not being unlocked. For a solution, look at [https://wiki.gnome.org/Projects/GnomeKeyring/Pam#Advanced_configuration Advanced PAM Configuration].}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
Also add sudo service to the list of enabled services and the search base in {{ic|/etc/sssd/sssd.conf}}:<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
...<br />
services = nss, pam, '''sudo'''<br />
...<br />
<br />
[domain/LDAP]<br />
...<br />
ldap_sudo_search_base = ou=sudoers,dc=example,dc=org<br />
...<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590697LDAP authentication2019-12-01T12:14:34Z<p>EasyToRemember: /* Enable sudo */ Rename dc of ldap.conf for sudo search base to dc=example,dc=org defaults.</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[#Online Authentication|online-only]] or [[#Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=example,dc=org<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
<br />
# OpenLDAP supports posixGroup, uncomment the following two lines<br />
# to get group membership support (and comment the other conflicting parameters)<br />
#ldap_schema = rfc2307<br />
#ldap_group_member = memberUid<br />
<br />
# Other LDAP servers may support this instead<br />
ldap_schema = rfc2307bis<br />
ldap_group_member = uniqueMember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
Also add sudo service to the list of enabled services and the search base in {{ic|/etc/sssd/sssd.conf}}:<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
...<br />
services = nss, pam, '''sudo'''<br />
...<br />
<br />
[domain/LDAP]<br />
...<br />
ldap_sudo_search_base = ou=sudoers,dc=example,dc=org<br />
...<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590695LDAP authentication2019-12-01T12:11:29Z<p>EasyToRemember: /* Enable sudo */ Extra info on ldap_sudo_search_base</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[#Online Authentication|online-only]] or [[#Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=AFOLA<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
<br />
# OpenLDAP supports posixGroup, uncomment the following two lines<br />
# to get group membership support (and comment the other conflicting parameters)<br />
#ldap_schema = rfc2307<br />
#ldap_group_member = memberUid<br />
<br />
# Other LDAP servers may support this instead<br />
ldap_schema = rfc2307bis<br />
ldap_group_member = uniqueMember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
Also add sudo service to the list of enabled services and the search base in {{ic|/etc/sssd/sssd.conf}}:<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
...<br />
services = nss, pam, '''sudo'''<br />
...<br />
<br />
[domain/LDAP]<br />
...<br />
ldap_sudo_search_base = ou=sudoers,dc=example,dc=org<br />
...<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590682LDAP authentication2019-12-01T10:41:11Z<p>EasyToRemember: /* SSSD Configuration */ Group membership support</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[#Online Authentication|online-only]] or [[#Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=AFOLA<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
<br />
# OpenLDAP supports posixGroup, uncomment the following two lines<br />
# to get group membership support (and comment the other conflicting parameters)<br />
#ldap_schema = rfc2307<br />
#ldap_group_member = memberUid<br />
<br />
# Other LDAP servers may support this instead<br />
ldap_schema = rfc2307bis<br />
ldap_group_member = uniqueMember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
Also add sudo service to the list of enabled services {{ic|/etc/sssd/sssd.conf}}:<br />
{{hc|/etc/pam.d/sudo|2=<br />
[sssd]<br />
...<br />
services = nss, pam, '''sudo'''<br />
...<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590681LDAP authentication2019-12-01T10:37:07Z<p>EasyToRemember: /* Enable sudo */ sudo service must be explicitely enabled</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[#Online Authentication|online-only]] or [[#Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=AFOLA<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
ldap_group_member = uniquemember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
Also add sudo service to the list of enabled services {{ic|/etc/sssd/sssd.conf}}:<br />
{{hc|/etc/pam.d/sudo|2=<br />
[sssd]<br />
...<br />
services = nss, pam, '''sudo'''<br />
...<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590604LDAP authentication2019-11-30T16:51:26Z<p>EasyToRemember: /* Client Setup */ Correction of link</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[#Online Authentication|online-only]] or [[#Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=AFOLA<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
ldap_group_member = uniquemember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=LDAP_authentication&diff=590596LDAP authentication2019-11-30T16:00:42Z<p>EasyToRemember: Restructure to show online-only and online/offline authentication to be alternatives in Client setup</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Authentication]]<br />
[[ja:LDAP 認証]]<br />
{{Related articles start}}<br />
{{Related|OpenLDAP}}<br />
{{Related|LDAP Hosts}}<br />
{{Related articles end}}<br />
<br />
== Introduction and Concepts ==<br />
<br />
This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).<br />
<br />
The guide is divided into two parts. The first part deals with how to setup an [[OpenLDAP]] server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticate against an already existing LDAP server, you can skip to the [[#Client_Setup|second part]].<br />
<br />
=== NSS and PAM ===<br />
NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database.<br />
<br />
[[PAM]] (which stands for Pluggable Authentication Modules) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.<br />
<br />
So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the {{ic|passwd}}, {{ic|shadow}} and other configuration databases and then configure PAM to use these sources to authenticate its users.<br />
<br />
== LDAP Server Setup ==<br />
<br />
=== Installation ===<br />
<br />
You can read about installation and basic configuration in the [[OpenLDAP]] article. After you have completed that, return here.<br />
<br />
=== Include required schemas ===<br />
<br />
To be able to use the {{ic|posixAccount}} object class used for storing users in LDAP, make sure to include the following schemas in {{ic|/etc/openldap/slapd.conf}}.<br />
{{hc|slapd.conf|2=<br />
include /etc/openldap/schema/cosine.schema<br />
include /etc/openldap/schema/inetorgperson.schema<br />
include /etc/openldap/schema/nis.schema<br />
}}<br />
<br />
=== Set up access controls ===<br />
<br />
To make sure that no-one can read the (encrypted) passwords from the LDAP server, but still allowing users to edit some of their own select attributes (such as own password and photo), add the following to {{ic|/etc/openldap/slapd.conf}} and restart {{ic|slapd.service}} afterwards:<br />
{{note|Alter the domain components "example" and "org" to your needs}}<br />
<br />
{{hc|slapd.conf|2=<br />
access to attrs=userPassword,givenName,sn,photo<br />
by self write<br />
by anonymous auth<br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * none<br />
<br />
access to *<br />
by self read <br />
by dn.base="cn=Manager,dc=example,dc=org" write<br />
by * read<br />
<br />
}}<br />
<br />
=== Populate LDAP Tree with Base Data ===<br />
<br />
Create a temporary file called {{ic|base.ldif}} with the following text.<br />
<br />
{{hc|base.ldif|<nowiki><br />
# example.org<br />
dn: dc=example,dc=org<br />
dc: example<br />
o: Example Organization<br />
objectClass: dcObject<br />
objectClass: organization<br />
<br />
# Manager, example.org<br />
dn: cn=Manager,dc=example,dc=org<br />
cn: Manager<br />
description: LDAP administrator<br />
objectClass: organizationalRole<br />
objectClass: top<br />
roleOccupant: dc=example,dc=org<br />
<br />
# People, example.org<br />
dn: ou=People,dc=example,dc=org<br />
ou: People<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
<br />
# Groups, example.org<br />
dn: ou=Group,dc=example,dc=org<br />
ou: Group<br />
objectClass: top<br />
objectClass: organizationalUnit<br />
</nowiki>}}<br />
<br />
Add it to your OpenLDAP tree:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif<br />
<br />
Test to make sure the data was imported:<br />
<br />
$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'<br />
<br />
=== Adding users ===<br />
To manually add a user, create an {{ic|.ldif}} file like this:<br />
{{hc|user_joe.ldif|<nowiki><br />
dn: uid=johndoe,ou=People,dc=example,dc=org<br />
objectClass: top<br />
objectClass: person<br />
objectClass: organizationalPerson<br />
objectClass: inetOrgPerson<br />
objectClass: posixAccount<br />
objectClass: shadowAccount<br />
uid: johndoe<br />
cn: John Doe<br />
sn: Doe<br />
givenName: John<br />
title: Guinea Pig<br />
telephoneNumber: +0 000 000 0000<br />
mobile: +0 000 000 0000<br />
postalAddress: AddressLine1$AddressLine2$AddressLine3<br />
userPassword: {CRYPT}xxxxxxxxxx<br />
labeledURI: https://archlinux.org/<br />
loginShell: /bin/bash<br />
uidNumber: 9999<br />
gidNumber: 9999<br />
homeDirectory: /home/johndoe/<br />
description: This is an example user<br />
</nowiki>}}<br />
<br />
The {{ic|xxxxxxxxxx}} in the {{ic|userPassword}} entry should be replaced with the value in {{ic|/etc/shadow}} or use the {{ic|slappasswd}} command. Now add the user:<br />
<br />
$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f user_joe.ldif<br />
<br />
{{Note|You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's [http://www.padl.com/OSS/MigrationTools.html Migration Tools].}}<br />
<br />
== Client Setup ==<br />
<br />
Install the OpenLDAP client as described in [[OpenLDAP]]. Make sure you can query the server with {{ic|ldapsearch}}.<br />
<br />
Depending on your target, choose either [[Online Authentication|online-only]] or [[Online and Offline Authentication with SSSD|online and offline]] authentication.<br />
<br />
=== Online Authentication ===<br />
<br />
==== NSS Configuration ====<br />
<br />
NSS is a system facility which manages different sources as configuration databases. For example, {{ic|/etc/passwd}} is a {{ic|file}} type source for the {{ic|passwd}} database, which stores the user accounts.<br />
<br />
[[Install]] the {{pkg|nss-pam-ldapd}} package.<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the {{ic|ldap}} directive to the {{ic|passwd}}, {{ic|group}} and {{ic|shadow}} databases, so be sure your file looks like this:<br />
<br />
passwd: files ldap<br />
group: files ldap<br />
shadow: files ldap<br />
<br />
Edit {{ic|/etc/nslcd.conf}} and change the {{ic|base}} and {{ic|uri}} lines to fit your ldap server setup.<br />
<br />
Edit the {{ic|binddn}} and the {{ic|bindpw}} if you set a password for the for your server. Make sure you change the permission of your {{ic|/etc/nslcd.conf}} to 0600 for {{ic|nslcd}} to start properly.<br />
<br />
Start {{ic|nslcd.service}} using systemd.<br />
<br />
You now should see your LDAP users when running {{ic|getent passwd}} on the client.<br />
<br />
==== PAM Configuration ====<br />
<br />
The basic rule of thumb for PAM configuration is to include {{ic|pam_ldap.so}} wherever {{ic|pam_unix.so}} is included. Arch moving to {{pkg|pambase}} has helped decrease the amount of edits required. For more details about configuring pam, the [https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Managing_Smart_Cards/PAM_Configuration_Files.html RedHat Documentation] is quite good. You might also want the upstream documentation for [http://arthurdejong.org/nss-pam-ldapd nss-pam-ldapd].<br />
<br />
{{Tip|If you want to prevent UID clashes with local users on your system, you might want to include {{ic|minimum_uid&#61;10000}} or similar on the end of the {{ic|pam_ldap.so}} lines. You will have to make sure the LDAP server returns uidNumber fields that match the restriction.}}<br />
<br />
{{Note|Each facility (auth, session, password, account) forms a separate chain and the order matters. Sufficient lines will sometimes "short circuit" and skip the rest of the section, so the rule of thumb for ''auth'', ''password'', and ''account'' is ''sufficient'' lines before ''required'', but after required lines for the ''session'' section; ''optional'' can almost always go at the end. When adding your {{ic|pam_ldap.so}} lines, do not change the relative order of the other lines without good reason! Simply insert LDAP within the chain.}}<br />
<br />
First edit {{ic|/etc/pam.d/system-auth}}. This file is included in most of the other files in {{ic|pam.d}}, so changes here propagate nicely. Updates to {{pkg|pambase}} may change this file.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section, except in the ''session'' section, where we make it optional.<br />
{{hc|/etc/pam.d/system-auth|<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_ldap.so'''<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_ldap.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
Then edit both {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} identically. The {{ic|su-l}} file is used when the user runs {{ic|su --login}}.<br />
<br />
Make {{ic|pam_ldap.so}} sufficient at the top of each section but below {{ic|pam_rootok}}, and add {{ic|use_first_pass}} to {{ic|pam_unix}} in the ''auth'' section.<br />
{{hc|/etc/pam.d/su|<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
'''auth sufficient pam_ldap.so'''<br />
# Uncomment the following line to implicitly trust users in the "wheel" group.<br />
#auth sufficient pam_wheel.so trust use_uid<br />
# Uncomment the following line to require a user to be in the "wheel" group.<br />
#auth required pam_wheel.so use_uid<br />
auth required pam_unix.so '''use_first_pass'''<br />
'''account sufficient pam_ldap.so'''<br />
account required pam_unix.so<br />
'''session sufficient pam_ldap.so'''<br />
session required pam_unix.so<br />
}}<br />
<br />
To enable users to edit their password, edit {{ic|/etc/pam.d/passwd}}:<br />
<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_ldap.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
===== Create home folders at login =====<br />
<br />
If you want home folders to be created at login (eg: if you are not using NFS to store home folders), edit {{ic|/etc/pam.d/system-login}} and add {{ic|pam_mkhomedir.so}} to the ''session'' section above any "sufficient" items. This will cause home folder creation when logging in at a tty, from ssh, xdm, kdm, gdm, etc. You might choose to edit additional files in the same way, such as {{ic|/etc/pam.d/su}} and {{ic|/etc/pam.d/su-l}} to enable it for {{ic|su}} and {{ic|su --login}}. If you do not want to do this for ssh logins, edit {{ic|system-local-login}} instead of {{ic|system-login}}, etc.<br />
<br />
{{hc|/etc/pam.d/system-login|<br />
...top of file not shown...<br />
session optional pam_loginuid.so<br />
session include system-auth<br />
session optional pam_motd.so motd&#61;/etc/motd<br />
session optional pam_mail.so dir&#61;/var/spool/mail standard quiet<br />
-session optional pam_systemd.so<br />
session required pam_env.so<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
}}<br />
<br />
{{hc|/etc/pam.d/su-l|<br />
...top of file not shown...<br />
'''session required pam_mkhomedir.so skel&#61;/etc/skel umask&#61;0022'''<br />
session sufficient pam_ldap.so<br />
session required pam_unix.so<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
To enable sudo from an LDAP user, edit {{ic|/etc/pam.d/sudo}}. You will also need to modify sudoers accordingly.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_ldap.so'''<br />
auth required pam_unix.so '''try_first_pass'''<br />
auth required pam_nologin.so<br />
}}<br />
<br />
You will also need to add in {{ic|/etc/openldap/ldap.conf}} the following.<br />
{{hc|/etc/openldap/ldap.conf|2=<br />
sudoers_base ou=sudoers,dc=AFOLA<br />
}}<br />
<br />
=== Online and Offline Authentication with SSSD ===<br />
<br />
SSSD is a system daemon. Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will D-BUS based interfaces for extended user information. It provides also a better database to store local users as well as extended user data.<br />
<br />
[[Install]] the {{pkg|sssd}} package.<br />
<br />
==== SSSD Configuration ====<br />
<br />
If it does not exist create {{ic|/etc/sssd/sssd.conf}}.<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam<br />
domains = LDAP<br />
<br />
[domain/LDAP]<br />
cache_credentials = true<br />
enumerate = true<br />
<br />
id_provider = ldap<br />
auth_provider = ldap<br />
<br />
ldap_uri = ldap://server1.example.org, ldap://server2.example.org<br />
ldap_search_base = dc=example,dc=org<br />
ldap_id_use_start_tls = true<br />
ldap_tls_reqcert = demand<br />
ldap_tls_cacert = /etc/openldap/certs/cacerts.pem<br />
chpass_provider = ldap<br />
ldap_chpass_uri = ldap://server1.example.org<br />
entry_cache_timeout = 600<br />
ldap_network_timeout = 2<br />
ldap_group_member = uniquemember<br />
}}<br />
<br />
The above is an example only. See {{man|5|sssd.conf}} for the full details.<br />
<br />
Finally set the file permissions {{ic|chmod 600 /etc/sssd/sssd.conf}} otherwise sssd will fail to start.<br />
<br />
==== NSCD Configuration ====<br />
<br />
Disable caching for passwd, group and netgroup entries in {{ic|/etc/nscd.conf}} as it will interfere with sssd caching.<br />
<br />
Keep caching enabled for hosts entries otherwise some services may fail to start.<br />
{{hc|/etc/nscd.conf|<br />
# Begin /etc/nscd.conf<br />
''[...]''<br />
enable-cache passwd '''no'''<br />
''[...]''<br />
enable-cache group '''no'''<br />
''[...]''<br />
enable-cache hosts yes<br />
''[...]''<br />
enable-cache netgroup '''no'''<br />
''[...]''<br />
# End /etc/nscd.conf<br />
}}<br />
<br />
==== NSS Configuration ====<br />
<br />
Edit {{ic|/etc/nsswitch.conf}} as follows.<br />
{{hc|/etc/nsswitch.conf|<br />
# Begin /etc/nsswitch.conf<br />
<br />
passwd: files '''sss'''<br />
group: files '''sss'''<br />
shadow: files '''sss'''<br />
'''sudoers: files sss'''<br />
<br />
publickey: files<br />
<br />
hosts: files dns myhostname<br />
networks: files<br />
<br />
protocols: files<br />
services: files<br />
ethers: files<br />
rpc: files<br />
<br />
netgroup: files<br />
<br />
# End /etc/nsswitch.conf<br />
}}<br />
<br />
==== PAM Configuration ====<br />
<br />
The first step is to edit {{ic|/etc/pam.d/system-auth}} as follows.<br />
{{hc|/etc/pam.d/system-auth|2=<br />
#%PAM-1.0<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so try_first_pass nullok<br />
auth optional pam_permit.so<br />
auth required pam_env.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
account optional pam_permit.so<br />
account required pam_time.so<br />
<br />
'''password sufficient pam_sss.so use_authtok'''<br />
password required pam_unix.so try_first_pass nullok sha512 shadow<br />
password optional pam_permit.so<br />
<br />
'''session required pam_mkhomedir.so skel=/etc/skel/ umask=0077'''<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
session optional pam_permit.so<br />
}}<br />
<br />
These PAM changes will apply to fresh login. To also allow the {{ic|su}} command to authenticate through SSSD, edit {{ic|/etc/pam.d/su}}:<br />
<br />
{{hc|/etc/pam.d/su|2=<br />
#%PAM-1.0<br />
auth sufficient pam_rootok.so<br />
<br />
'''auth sufficient pam_sss.so forward_pass'''<br />
auth required pam_unix.so<br />
<br />
'''account [default=bad success=ok user_unknown=ignore authinfo_unavail=ignore] pam_sss.so'''<br />
account required pam_unix.so<br />
<br />
session required pam_unix.so<br />
'''session optional pam_sss.so'''<br />
}}<br />
<br />
===== Enable sudo =====<br />
<br />
Edit {{ic|/etc/pam.d/sudo}} as follows.<br />
{{hc|/etc/pam.d/sudo|<br />
#%PAM-1.0<br />
'''auth sufficient pam_sss.so'''<br />
auth required pam_unix.so try_first_pass<br />
auth required pam_nologin.so<br />
}}<br />
<br />
===== Password Management =====<br />
<br />
In order to enable users to change their passwords using {{ic|passwd}} edit {{ic|/etc/pam.d/passwd}} as follows.<br />
{{hc|/etc/pam.d/passwd|2=<br />
#%PAM-1.0<br />
'''password sufficient pam_sss.so'''<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so sha512 shadow use_authtok<br />
password required pam_unix.so sha512 shadow nullok<br />
}}<br />
<br />
[[Start/enable]] the {{ic|sssd.service}} systemd unit.<br />
<br />
You should now be able to see details of your ldap users with {{ic|getent passwd <username>}} or {{ic|id <username>}}.<br />
<br />
Once you have logged in with a user the credentials will be cached and you will be able to login using the cached credentials when the ldap server is offline or unavailable.<br />
<br />
== Resources ==<br />
* [http://arthurdejong.org/nss-pam-ldapd/setup The official page of the nss-pam-ldapd packet]<br />
* [[debian:LDAP/NSS|Debian Wiki - LDAP/NSS]]<br />
* [[debian:LDAP/PAM|Debian Wiki - LDAP/PAM]]<br />
* [https://www.fatofthelan.com/technical/using-ldap-for-single-authentication/ Using LDAP for single authentication]<br />
* [http://www.cs.dixie.edu/ldap/ Heterogeneous Network Authentication Introduction]<br />
* [http://readlist.com/lists/suse.com/suse-linux-e/36/182642.html Discussion on suse's mailing lists about nss-pam-ldapd]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/Deployment_Guide/chap-SSSD_User_Guide-Introduction.html Fedora's SSSD User Guide]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=FreeIPA&diff=589296FreeIPA2019-11-18T18:14:41Z<p>EasyToRemember: /* See also */ Link update - to a more recent Fedora</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Security]]<br />
[[Category:Red Hat]]<br />
[[ja:FreeIPA]]<br />
{{Style|Is this article only about the client? If so it should say so.}}<br />
{{Expansion|How do you install the client? There is {{AUR|freeipa-client}}.}}<br />
[https://www.freeipa.org/ FreeIPA] is an open-source Identity, Policy and Audit (IPA) suite, sponsored by RedHat, which provides services similar to Microsoft's Active Directory<br />
<br />
== Configure as IPA client ==<br />
<br />
Make sure your clocks are synchronized. Kerberos will not work otherwise. [[Network_Time_Protocol_daemon|NTP]] is recommended.<br />
<br />
Instead of using {{ic|1=ipa-client-install}} script for automated client configuration and enrollment, the following sections describe a manual procedure.<br />
<br />
=== Configure SSSD and Kerberos ===<br />
<br />
Follow the LDAP auth instructions to [[LDAP_authentication#Online_and_Offline_Authentication_with_SSSD|setup SSSD]]. Use a SSSD configuration similar to the following, substituting the requisite fields:<br />
<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam, sudo, ssh<br />
domains = EXAMPLE.COM<br />
#debug_level = 9<br />
<br />
[domain/EXAMPLE.COM]<br />
#debug_level = 9<br />
cache_credentials = true<br />
krb5_store_password_if_offline = true<br />
id_provider = ipa<br />
auth_provider = ipa<br />
access_provider = ipa<br />
chpass_provider = ipa<br />
#ipa_domain=ipa.example.com # Optional if you set SRV records in DNS<br />
#ipa_server=controller.example.com # Optional if you set SRV records in DNS<br />
ipa_hostname=fqdn.for.machine}}<br />
<br />
Configure pam in similar way to [[LDAP_authentication#PAM_Configuration|LDAP]], replacing {{ic|pam_ldap.so}} with {{ic|pam_sss.so}}.<br />
<br />
Create an {{ic|/etc/krb5.conf}} file for your domain:<br />
<br />
{{hc|/etc/krb5.conf|2=<br />
[libdefaults]<br />
default_realm = EXAMPLE.COM<br />
dns_lookup_realm = false<br />
dns_lookup_kdc = false<br />
rdns = false<br />
ticket_lifetime = 24h<br />
forwardable = yes<br />
#allow_weak_crypto = yes # Only if absolutely necessary. Currently FreeIPA supports strong crypto.<br />
<br />
[realms]<br />
EXAMPLE.COM = {<br />
admin_server = controller.example.com<br />
kdc = controller.example.com:749<br />
default_admin = example.com<br />
}<br />
<br />
[domain_realm]<br />
example.com = EXAMPLE.COM<br />
.example.com = EXAMPLE.COM<br />
<br />
[logging]<br />
default = FILE:/var/log/krb5libs.log<br />
kdc = FILE:/var/log/krb5kdc.log<br />
admin_server = FILE:/var/log/kadmin.log<br />
}}<br />
<br />
=== Enroll the client ===<br />
<br />
On FreeIPA server, add the client to the IPA server ([https://docs.fedoraproject.org/en-US/Fedora/15/html/FreeIPA_Guide/linux-manual.html From Fedora documentation]):<br />
# Login and request and admin session {{ic|kinit admin}}<br />
# Create a host entry {{ic|1=ipa host-add --force --ip-address=192.168.166.31 client1.example.com}}<br />(if the host does not have a static IP, use {{ic|1=ipa host-add client1.example.com}})<br />
# Set the client to be managed by IPA {{ic|1=ipa host-add-managedby --hosts=controller.example.com client1.example.com}}<br />
# Generate keytab for the client {{ic|ipa-getkeytab -s controller.example.com -p host/client1.example.com -k /tmp/client1.keytab}}<br />
<br />
Install the keytab on the client:<br />
$ scp user@controller.example.com:/tmp/client1.keytab krb5.keytab<br />
# mv krb5.ketab /etc/krb5.keytab<br />
<br />
=== SSH integration ===<br />
<br />
==== authorized_keys ====<br />
<br />
You can configure SSHD to fetch users SSH public key from the LDAP directory by uncommenting those lines in {{ic|1=/etc/ssh/sshd_config}}:<br />
<br />
AuthorizedKeysCommand /usr/bin/sss_ssh_authorizedkeys<br />
AuthorizedKeysCommandUser nobody<br />
<br />
Then restart sshd.<br />
<br />
You can add your ssh key to your FreeIPA user account through the web interface or use the {{ic|1=-sshpubkey='ssh-rsa AAAA...'}} argument to the {{ic|1=ipa user-mod}} or {{ic|1=ipa user-create}} commands.<br />
<br />
Test it:<br />
<br />
sudo -u nobody sss_ssh_authorizedkeys <username><br />
<br />
You should see your ssh public key on standard output and no error message on standard error.<br />
<br />
==== known_hosts ====<br />
<br />
You can configure SSH to fetch hosts public key information from their directory entries in FreeIPA by adding those lines in {{ic|1=/etc/ssh/ssh_config}}:<br />
<br />
GlobalKnownHostsFile /var/lib/sss/pubconf/known_hosts<br />
ProxyCommand /usr/bin/sss_ssh_knownhostsproxy -p %p %h<br />
<br />
=== See also ===<br />
<br />
* [[Wikipedia:FreeIPA]]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/18/html/FreeIPA_Guide/linux-manual.html Manually Configuring a Linux Client] from the FreeIPA user guide<br />
* [https://www.freeipa.org/images/1/10/Freeipa30_SSSD_OpenSSH_integration.pdf Freeipa30_SSSD_OpenSSH_integration.pdf]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=FreeIPA&diff=588713FreeIPA2019-11-12T19:40:51Z<p>EasyToRemember: /* Configure as IPA client */ Split to sections, clarifications</p>
<hr />
<div>[[Category:Networking]]<br />
[[Category:Security]]<br />
[[Category:Red Hat]]<br />
[[ja:FreeIPA]]<br />
{{Style|Is this article only about the client? If so it should say so.}}<br />
{{Expansion|How do you install the client? There is {{AUR|freeipa-client}}.}}<br />
[https://www.freeipa.org/ FreeIPA] is an open-source Identity, Policy and Audit (IPA) suite, sponsored by RedHat, which provides services similar to Microsoft's Active Directory<br />
<br />
== Configure as IPA client ==<br />
<br />
Make sure your clocks are synchronized. Kerberos will not work otherwise. [[Network_Time_Protocol_daemon|NTP]] is recommended.<br />
<br />
Instead of using {{ic|1=ipa-client-install}} script for automated client configuration and enrollment, the following sections describe a manual procedure.<br />
<br />
=== Configure SSSD and Kerberos ===<br />
<br />
Follow the LDAP auth instructions to [[LDAP_authentication#Online_and_Offline_Authentication_with_SSSD|setup SSSD]]. Use a SSSD configuration similar to the following, substituting the requisite fields:<br />
<br />
{{hc|/etc/sssd/sssd.conf|2=<br />
[sssd]<br />
config_file_version = 2<br />
services = nss, pam, sudo, ssh<br />
domains = EXAMPLE.COM<br />
#debug_level = 9<br />
<br />
[domain/EXAMPLE.COM]<br />
#debug_level = 9<br />
cache_credentials = true<br />
krb5_store_password_if_offline = true<br />
id_provider = ipa<br />
auth_provider = ipa<br />
access_provider = ipa<br />
chpass_provider = ipa<br />
#ipa_domain=ipa.example.com # Optional if you set SRV records in DNS<br />
#ipa_server=controller.example.com # Optional if you set SRV records in DNS<br />
ipa_hostname=fqdn.for.machine}}<br />
<br />
Configure pam in similar way to [[LDAP_authentication#PAM_Configuration|LDAP]], replacing {{ic|pam_ldap.so}} with {{ic|pam_sss.so}}.<br />
<br />
Create an {{ic|/etc/krb5.conf}} file for your domain:<br />
<br />
{{hc|/etc/krb5.conf|2=<br />
[libdefaults]<br />
default_realm = EXAMPLE.COM<br />
dns_lookup_realm = false<br />
dns_lookup_kdc = false<br />
rdns = false<br />
ticket_lifetime = 24h<br />
forwardable = yes<br />
#allow_weak_crypto = yes # Only if absolutely necessary. Currently FreeIPA supports strong crypto.<br />
<br />
[realms]<br />
EXAMPLE.COM = {<br />
admin_server = controller.example.com<br />
kdc = controller.example.com:749<br />
default_admin = example.com<br />
}<br />
<br />
[domain_realm]<br />
example.com = EXAMPLE.COM<br />
.example.com = EXAMPLE.COM<br />
<br />
[logging]<br />
default = FILE:/var/log/krb5libs.log<br />
kdc = FILE:/var/log/krb5kdc.log<br />
admin_server = FILE:/var/log/kadmin.log<br />
}}<br />
<br />
=== Enroll the client ===<br />
<br />
On FreeIPA server, add the client to the IPA server ([https://docs.fedoraproject.org/en-US/Fedora/15/html/FreeIPA_Guide/linux-manual.html From Fedora documentation]):<br />
# Login and request and admin session {{ic|kinit admin}}<br />
# Create a host entry {{ic|1=ipa host-add --force --ip-address=192.168.166.31 client1.example.com}}<br />(if the host does not have a static IP, use {{ic|1=ipa host-add client1.example.com}})<br />
# Set the client to be managed by IPA {{ic|1=ipa host-add-managedby --hosts=controller.example.com client1.example.com}}<br />
# Generate keytab for the client {{ic|ipa-getkeytab -s controller.example.com -p host/client1.example.com -k /tmp/client1.keytab}}<br />
<br />
Install the keytab on the client:<br />
$ scp user@controller.example.com:/tmp/client1.keytab krb5.keytab<br />
# mv krb5.ketab /etc/krb5.keytab<br />
<br />
=== SSH integration ===<br />
<br />
==== authorized_keys ====<br />
<br />
You can configure SSHD to fetch users SSH public key from the LDAP directory by uncommenting those lines in {{ic|1=/etc/ssh/sshd_config}}:<br />
<br />
AuthorizedKeysCommand /usr/bin/sss_ssh_authorizedkeys<br />
AuthorizedKeysCommandUser nobody<br />
<br />
Then restart sshd.<br />
<br />
You can add your ssh key to your FreeIPA user account through the web interface or use the {{ic|1=-sshpubkey='ssh-rsa AAAA...'}} argument to the {{ic|1=ipa user-mod}} or {{ic|1=ipa user-create}} commands.<br />
<br />
Test it:<br />
<br />
sudo -u nobody sss_ssh_authorizedkeys <username><br />
<br />
You should see your ssh public key on standard output and no error message on standard error.<br />
<br />
==== known_hosts ====<br />
<br />
You can configure SSH to fetch hosts public key information from their directory entries in FreeIPA by adding those lines in {{ic|1=/etc/ssh/ssh_config}}:<br />
<br />
GlobalKnownHostsFile /var/lib/sss/pubconf/known_hosts<br />
ProxyCommand /usr/bin/sss_ssh_knownhostsproxy -p %p %h<br />
<br />
=== See also ===<br />
<br />
* [[Wikipedia:FreeIPA]]<br />
* [https://docs.fedoraproject.org/en-US/Fedora/15/html/FreeIPA_Guide/linux-manual.html Manually Configuring a Linux Client] from the FreeIPA user guide<br />
* [https://www.freeipa.org/images/1/10/Freeipa30_SSSD_OpenSSH_integration.pdf Freeipa30_SSSD_OpenSSH_integration.pdf]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Talk:FreeIPA&diff=588712Talk:FreeIPA2019-11-12T19:23:30Z<p>EasyToRemember: Split to sections</p>
<hr />
<div>== FreeIPA server ==<br />
How would one set up an Arch Linux FreeIPA server? This page seems to only deal with setting up a client. [[User:MountainX|MountainX]] ([[User talk:MountainX|talk]]) 07:13, 30 January 2018 (UTC)<br />
<br />
:: FreeIPA server packages are not maintained for Arch Linux. Better idea might be a VM/Docker/standalone installation of upstream FreeIPA server (CentOS, Fedora, RedHat). [[User:EasyToRemember|EasyToRemember]] ([[User talk:EasyToRemember|talk]]) 19:16, 12 November 2019 (UTC)<br />
<br />
== default_admin vs default_domain ==<br />
Hi,<br />
<br />
I have my doubts about this part of the krb5.conf :<br />
<br />
<br />
[realms]<br />
DOMAIN.COM = {<br />
admin_server = controller.domain.com<br />
kdc = controller.domain.com:749<br />
default_'''admin''' = domain.com<br />
}<br />
<br />
On my ubuntu 14.04 server which is in my ipa domain, the line is :<br />
default_domain = myDomain<br />
<br />
which seems more consistant than "admin"<br />
<br />
I'm no guru in those things, but i'll check for it later<br />
<br />
[[User:Natille|Natille]] ([[User talk:Natille|talk]]) 10:54, 14 January 2016 (UTC)</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Talk:FreeIPA&diff=588711Talk:FreeIPA2019-11-12T19:18:19Z<p>EasyToRemember: Formatting</p>
<hr />
<div>How would one set up an Arch Linux FreeIPA server? This page seems to only deal with setting up a client. [[User:MountainX|MountainX]] ([[User talk:MountainX|talk]]) 07:13, 30 January 2018 (UTC)<br />
<br />
:: FreeIPA server packages are not maintained for Arch Linux. Better idea might be a VM/Docker/standalone installation of upstream FreeIPA server (CentOS, Fedora, RedHat). [[User:EasyToRemember|EasyToRemember]] ([[User talk:EasyToRemember|talk]]) 19:16, 12 November 2019 (UTC)<br />
<br />
<br />
Hi,<br />
<br />
I have my doubts about this part of the krb5.conf :<br />
<br />
<br />
[realms]<br />
DOMAIN.COM = {<br />
admin_server = controller.domain.com<br />
kdc = controller.domain.com:749<br />
default_'''admin''' = domain.com<br />
}<br />
<br />
On my ubuntu 14.04 server which is in my ipa domain, the line is :<br />
default_domain = myDomain<br />
<br />
which seems more consistant than "admin"<br />
<br />
I'm no guru in those things, but i'll check for it later<br />
<br />
[[User:Natille|Natille]] ([[User talk:Natille|talk]]) 10:54, 14 January 2016 (UTC)</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Talk:FreeIPA&diff=588710Talk:FreeIPA2019-11-12T19:16:50Z<p>EasyToRemember: Added discussion point to lack of FreeIPA server on Arch</p>
<hr />
<div>How would one set up an Arch Linux FreeIPA server? This page seems to only deal with setting up a client. <br />
:: FreeIPA server packages are not maintained for Arch Linux. Better idea might be a VM/Docker/standalone installation of upstream FreeIPA server (CentOS, Fedora, RedHat). [[User:EasyToRemember|EasyToRemember]] ([[User talk:EasyToRemember|talk]]) 19:16, 12 November 2019 (UTC)<br />
<br />
[[User:MountainX|MountainX]] ([[User talk:MountainX|talk]]) 07:13, 30 January 2018 (UTC)<br />
<br />
Hi,<br />
<br />
I have my doubts about this part of the krb5.conf :<br />
<br />
<br />
[realms]<br />
DOMAIN.COM = {<br />
admin_server = controller.domain.com<br />
kdc = controller.domain.com:749<br />
default_'''admin''' = domain.com<br />
}<br />
<br />
On my ubuntu 14.04 server which is in my ipa domain, the line is :<br />
default_domain = myDomain<br />
<br />
which seems more consistant than "admin"<br />
<br />
I'm no guru in those things, but i'll check for it later<br />
<br />
[[User:Natille|Natille]] ([[User talk:Natille|talk]]) 10:54, 14 January 2016 (UTC)</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=EncFS&diff=583744EncFS2019-09-23T19:28:35Z<p>EasyToRemember: /* Backup encrypted directory */ Typo correction</p>
<hr />
<div>[[Category:Disk encryption]]<br />
[[Category:FUSE]]<br />
[[ja:EncFS]]<br />
[[ru:EncFS]]<br />
{{Related articles start}}<br />
{{Related|Disk encryption}}<br />
{{Related articles end}}<br />
[[Wikipedia:EncFS|EncFS]] is a userspace stackable cryptographic file-system similar to [[eCryptfs]], and aims to secure data with the minimum hassle. It uses [[wikipedia:Filesystem_in_Userspace|FUSE]] to mount an encrypted directory onto another directory specified by the user. It does not use a loopback system like some other comparable systems such as [[TrueCrypt]] and [[dm-crypt]].<br />
<br />
EncFS is definitely the simplest software if you want to try disk encryption on Linux.<br />
<br />
This has a number of advantages and disadvantages compared to these systems. Firstly, it does not require any root privileges to implement; any user can create a repository of encrypted files. Secondly, one does not need to create a single file and create a file-system within that; it works on existing file-system without modifications.<br />
<br />
This does create a few disadvantages, though; because the encrypted files are not stored in their own file, someone who obtains access to the system can still see the underlying directory structure, the number of files, their sizes and when they were modified. They cannot see the contents, however.<br />
<br />
This particular method of securing data is obviously not perfect, but there are situations in which it is useful.<br />
<br />
For more details on how EncFS compares to other disk encryption solution, see [[Disk encryption#Comparison table]].<br />
<br />
== Comparison to eCryptFS ==<br />
<br />
[[System_Encryption_with_eCryptfs|eCryptFS]] is implemented in kernelspace and therefore a little bit harder to configure. You have to remember various encryption options (used cyphers, key type, etc...). With EncFS this is not the case, because it stores the encryption metadata information in a per-directory configuration file ({{ic|.encfs6.xml}}). So you do not have to remember anything (except the passphrase). <br />
<br />
The performance of both depends on the type of disk activity. While eCryptFS can perform faster in some cases because there is less overhead by context switching (between kernel and userspace), EncFS has advantages in other cases because the encryption metadata is centralized and not stored in the individual files' headers. For more information [https://github.com/vgough/encfs/blob/master/PERFORMANCE.md benchmark examples] are provided by the EncFS project.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|encfs}} package.<br />
<br />
{{Warning|A security [https://defuse.ca/audits/encfs.htm review] (February 2014) of ''encfs'' discovered a number of security issues in the stable release 1.7.4 (June 2014). Please consider the report and the references in it for updated information before using the release.}}<br />
<br />
== Usage ==<br />
<br />
To create a secured repository, type:<br />
$ encfs ~/.''encrypted'' ~/''origin''<br />
Note that absolute paths must be used. This will be followed by a prompt about whether you want to go with the default options, expert configuration or a paranoid preset. The first is a fairly secure default setup. The second allows specifying algorithms and other options. After entering a key for the encryption, the encoded file-system will be created and mounted. The encoded files are stored, in this example, at {{ic|~/.''encrypted''}}, and their unencrypted versions in {{ic|~/''origin''}}.<br />
<br />
{{Tip|Using EncFS on exFAT formatted partitions might end up with slow performance as exFAT is also fuse-mounted by default. Use another way to mount the exFAT partition, or change the partition format if possible.}} <br />
<br />
To unmount the file-system, type:<br />
$ fusermount -u ~/''name''<br />
<br />
To remount the file-system, issue the first command, and enter the key used to encode it. Once this has been entered, the file-system will be mounted again.<br />
<br />
=== Changing the password ===<br />
<br />
To change the password of a directory encrypted by EncFS, the following command can be used:<br />
<br />
$ encfsctl passwd ~/.''name''<br />
<br />
In this example, {{ic|~/.''name''}} is the path to the directory which contains the encoded files. The tool will ask for your current password and afterwards, you will be able to set a new one.<br />
<br />
== User friendly mounting ==<br />
<br />
=== Gnome Encfs Manager ===<br />
<br />
The [http://libertyzero.com/GEncfsM/ Gnome Encfs Manager] is an easy to use manager and mounter for encfs stashes featuring per-stash configuration, Gnome Keyring support, a tray menu inspired by Cryptkeeper but using the AppIndicator API and lots of unique features. <br />
<br />
Both {{AUR|gnome-encfs-manager-bin}} and a slightly more up to date {{AUR|gnome-encfs-manager-bzr}} are available.<br />
<br />
=== Mount using gnome-encfs ===<br />
<br />
gnome-encfs integrates EncFS folders into the GNOME desktop by storing their passwords in the keyring and optionally mounting them at login using GNOME's autostart mechanism. See https://bitbucket.org/obensonne/gnome-encfs/.<br />
This method has the advantage that mounting and can automated and the password does not have to be the same as your user password.<br />
<br />
=== Mount using CryptKeeper trayicon ===<br />
<br />
Quite simple app, just [[install]] {{AUR|cryptkeeper}} and add it to your X session.<br />
<br />
=== Mount using encfsui ===<br />
<br />
A bash script [http://github.com/bulletmark/encfsui encfsui] provides a simple {{Pkg|zenity}} gui around the EncFS command line utility to mount and unmount an encrypted directory. It includes a desktop launcher. Install it from {{AUR|encfsui}}.<br />
<br />
=== Mount via fstab ===<br />
<br />
Adding an entry in {{ic|/etc/fstab}} will allow you to mount the encfs volume with a simple {{ic|mount /target/path}} and you will be prompted for your password.<br />
<br />
{{hc|/etc/fstab|<br />
encfs#/path/to/encfs/data /mnt/decrypted fuse noauto,user 0 0<br />
}}<br />
<br />
The {{ic|noauto}} option prevents an attempt to mount the volume at boot, which could delay the boot process while it waits for a password to be entered. {{ic|user}} can be omitted if only the {{ic|root}} user should be able to mount the volume.<br />
<br />
=== Mount at login using pam_encfs ===<br />
<br />
Install {{AUR|pam_encfs}}. See also:<br />
* http://pam-encfs.googlecode.com/svn/trunk/README<br />
* http://pam-encfs.googlecode.com/svn/trunk/pam_encfs.conf<br />
* https://wiki.edubuntu.org/EncryptedHomeFolder<br />
* http://code.google.com/p/pam-encfs/<br />
<br />
==== Single password ====<br />
<br />
{{Warning|Note that if you will use same password (eg.: using try_first_pass or use_first_pass) for login and encfs (so encfs will mount during your login) then you should use [[SHA password hashes]] (Preferably SHA512 with some huge number of rounds) and (which is most important) '''secure password''', because hash of your password is probably stored in unencrypted form in {{ic|/etc/shadow}} and it can be cracked in order to get your encfs password (because it is same as your regular unix login password).}}<br />
<br />
==== /etc/pam.d/ ====<br />
<br />
Note that when you are using ''try_first_pass'' parameter to ''pam_unix.so'' then you will have to set EncFS to use same password as you are using to login (or vice-versa) and you will be entering just single password. Without this parameter you will need to enter two passwords.<br />
<br />
===== setup pam_encfs for all login methods =====<br />
<br />
Put encfs line to /etc/pam.d/system-login as follows:<br />
<br />
{{bc|<br />
...<br />
auth sufficient pam_encfs.so<br />
...<br />
}}<br />
<br />
===== login =====<br />
<br />
This section tells how to make encfs automount when you are logging in by virtual terminal.<br />
{{Note|If you only want to use it through GDM, you may pass this and go right to the [[#gdm|GDM section]] below.}}<br />
<br />
Edit the file {{ic|/etc/pam.d/login}}:<br />
<br />
{{bc|<nowiki><br />
#%PAM-1.0<br />
<br />
auth required pam_securetty.so<br />
auth requisite pam_nologin.so<br />
auth sufficient pam_encfs.so<br />
auth required pam_unix.so nullok try_first_pass<br />
#auth required pam_unix.so nullok<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 required pam_unix.so<br />
#password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3<br />
#password required pam_unix.so md5 shadow use_authtok<br />
session required pam_unix.so<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 />
#Automatic unmount (optional):<br />
#session required pam_encfs.so<br />
</nowiki>}}<br />
{{Warning|Note that automatic unmount will process even when there is another session. eg.: logout on VC can unmount encfs mounted by GDM session that is still active.}}<br />
<br />
===== gdm =====<br />
<br />
This section explains how to make encfs automount when you are logging in by GDM.<br />
{{Note|For debug purposes you may try automount on virtual console login first. [[#login|This article has a section about automount on virtual console login]].}}<br />
<br />
Edit the file {{ic|/etc/pam.d/gdm-password}}.<br />
<br />
Insert (do not overwrite) the following into the bottom of gdm-password:<br />
<br />
{{bc|<nowiki><br />
#%PAM-1.0<br />
auth requisite pam_nologin.so<br />
auth required pam_env.so<br />
auth sufficient pam_encfs.so<br />
auth required pam_unix.so try_first_pass<br />
auth optional pam_gnome_keyring.so<br />
account required pam_unix.so<br />
session required pam_limits.so<br />
session required pam_unix.so<br />
session optional pam_gnome_keyring.so auto_start<br />
password required pam_unix.so<br />
session required pam_encfs.so<br />
</nowiki>}}<br />
<br />
Save and exit.<br />
<br />
===== Configuration =====<br />
<br />
Edit {{ic|/etc/security/pam_encfs.conf}} :<br />
<br />
Recommended: comment out the line<br />
<br />
encfs_default --idle=1<br />
<br />
This flag will unmount your encrypted folder after 1 minute of inactivity. If you are automounting this on login, you probably would like to keep this mounted for as long as you are logged in.<br />
<br />
At the bottom, comment any existing demo entries and add:<br />
{{bc|<br />
#USERNAME SOURCE TARGET PATH ENCFS Options FUSE Options<br />
foo /home/foo/EncryptedFolder /home/foo/DecryptedFolder -v allow_other<br />
}}<br />
<br />
{{Note|It is not possible to mount multiple EncFS folders at login using {{ic|pam_encfs}}. If multiple entries are specified in {{ic|/etc/security/pam_encfs.conf}}, only the first one will be mounted, and the rest will be ignored. To mount multiple EncFS folders at login it is necessary to use [[pam_mount]]. See [[#Mount at login using pam_mount]] for details.}}<br />
<br />
Also, if you see the following line, remove {{ic|allow_root}} from the options. Otherwise, it will be in conflict with {{ic|allow_other}} defined above.<br />
{{bc|<br />
fuse_default allow_root,nonempty<br />
}}<br />
<br />
<br />
Next, edit {{ic|/etc/fuse.conf}}:<br />
Uncomment:<br />
user_allow_other<br />
<br />
To test your config, open a new virtual terminal (e.g. {{ic|Ctrl+Alt+F4}}) and login. You should see pam successfuly mount your EncFS folder.<br />
<br />
=== Mount at login using pam_mount ===<br />
<br />
Install and configure [[pam_mount]] as explained on its wiki page. EncFS mounts can be specified in pam_mount's configuration file as follows:<br />
<br />
{{hc|/etc/security/pam_mount.conf.xml|2=<volume fstype="fuse" path="encfs#''/path/to/encfs/encrypted/data''" mountpoint="''/path/to/decrypted/data/mountpoint''" options="nonempty" />}}<br />
<br />
The EncFS mounts need to have the same password than your user account. The {{ic|nonempty}} option makes it possible to mount the encrypted file system even when the mount point is non-empty. You may remove this option if this is not the desired behaviour.<br />
<br />
It is possible to mount multiple EncFS folders at login specifying multiple consecutive {{ic|<volume>}} entries in the configuration file.<br />
<br />
=== Mount when USB drive with EncFS folders is inserted using fsniper ===<br />
<br />
Simple method to automount (asking for password) encfs when USB drive with EncFS one or more folders in root is inserted. We will use {{AUR|fsniper}} (filesystem watching daemon using inotify) and {{Pkg|git}} (for askpass binary).<br />
<br />
See more at https://github.com/Harvie/Programs/tree/master/bash/encfs/automount (latest version of files used in the [[#How to|How to]]).<br />
<br />
==== How to ====<br />
<br />
'''1.''' You need USB automount working for this - like Thunar or Gnome Files does.<br \><br />
'''2.''' Make encrypted folder on your drive, eg.: {{ic|encfs /media/USB/somename /media/USB/somename.plain}} (and then unmount everything).<br \><br />
'''3.''' Create a {{ic|~/.config/fsniper/config}} file:<br />
{{bc|<nowiki><br />
watch {<br />
/etc/ {<br />
mtab {<br />
# %% is replaced with the filename of the new file<br />
handler = encfs-automount.sh %%;<br />
}<br />
}<br />
}<br />
</nowiki>}}<br />
'''4.''' install helper script:<br />
{{bc|<nowiki><br />
#!/bin/sh<br />
# ~/.config/fsniper/scripts/encfs-automount.sh<br />
# Quick & dirty script for automounting EncFS USB drives<br />
# TODO:<br />
# - Unmounting!!!<br />
#<br />
ASKPASS="/usr/lib/git-core/git-gui--askpass"<br />
<br />
lock=/tmp/fsniper_encfs.lock<br />
lpid=$(cat "$lock" 2>/dev/null) &&<br />
ps "$lpid" | grep "$lpid" >/dev/null && {<br />
echo "Another instance of fsniper_encfs is running"<br />
exit;<br />
}<br />
echo $BASHPID > "$lock";<br />
sleep 2;<br />
<br />
echo<br />
echo ==== EncFS automount script for fsniper ====<br />
<br />
list_mounts() {<br />
cat /proc/mounts | cut -d ' ' -f 2<br />
}<br />
<br />
list_mounts | while read mount; do<br />
config="$mount"'/*/.encfs*';<br />
echo Looking for "$config"<br />
config="$(echo $config)"<br />
[ -r "$config" ] && {<br />
cyphertext="$(dirname "$config")";<br />
plaintext="$cyphertext".plain<br />
echo Found config: "$config";<br />
echo Trying to mount: "$cyphertext to $plaintext";<br />
list_mounts | grep "$plaintext" >/dev/null && {<br />
echo Already mounted: "$plaintext"<br />
} || {<br />
echo Will mount "$cyphertext to $plaintext"<br />
"$ASKPASS" "EncFS $cyphertext to $plaintext" | encfs --stdinpass "$cyphertext" "$plaintext"<br />
}<br />
}<br />
done<br />
echo<br />
<br />
rm "$lock" 2>/dev/null<br />
</nowiki>}}<br />
'''5.''' Make sure that /usr/lib/git-core/git-gui--askpass is working for you (that is why you need git package - but you can adjust the helper script).<br \><br />
'''6.''' Try {{ic|fsniper --log-to-stdout}} in terminal (askpass should appear when USB drive is inserted).<br \><br />
'''7.''' Add {{ic|fsniper --daemon}} to your session.<br \><br />
'''8.''' Do not forget to unmount encfs before removing drive.<br />
<br />
=== Mount using KDE KWallet ===<br />
This can be done in KDE with the [http://pastebin.com/RR1hguwE kdeencfs] script. You will also have to [[install]] the {{Pkg|kdialog}}, {{AUR|kdebase-runtime}}, {{Pkg|qt5-tools}} and {{Pkg|kwallet-pam}} packages from the [[official repositories]]. kwallet-pam has to started with the session which it is by default. ''(If not: Add /usr/lib/pam_kwallet_init to sessionstart.)'' It can be used by calling ''kdeencfs encrypted-folder decrypted-folder''.<br />
<br />
== Encrypted backup ==<br />
<br />
{{Warning|If you follow below examples to separate the encryption options file from the data, you - of course - need to ensure you have a separate backup of the options file in plaintext as well. If your disk crashes and you have not backed it up in plaintext, the backup alone will help nothing because the file contains cryptographic metadata! The good point is that the file is static, you do not need to back it up repetitively over time unless you change the password.}}<br />
<br />
=== Backup encrypted directory ===<br />
<br />
An encrypted directory may be backed up and restored to another location like it is. This is possible, because the configuration file for the encryption options/metadata is actually stored in the directory itself in plaintext in the hidden {{ic|.encfs6.xml}} file. This poses no direct problem, because the password is not in it. <br />
<br />
However, if you - for example - store the backup on a remote location (e.g. in the cloud) or a portable device, you might feel uncomfortable about it. In this case it also is no problem to manually move the file out of the directory before creating the backup. You can even move it permanently and still mount and access the files, if you pass its location to ''encfs'' via the {{ic|ENCFS6_CONFIG}} environment variable. For the [[#Usage]] example above: <br />
$ mv ~/.name/.encfs6.xml ~/.<br />
$ ENCFS6_CONFIG=~/.encfs6.xml encfs ~/.name ~/name<br />
<br />
=== Backup plaintext directory ===<br />
<br />
The following example assumes you want to create an encrypted backup of an existing plaintext directory {{ic|~/mythesis}} which contains the file {{ic|thesis.txt}}. <br />
<br />
First, we create the encrypted backup of the existing plaintext directory: <br />
<br />
$ encfs --reverse ~/mythesis /tmp/thesisbackup <br />
<br />
Note the directory order is reversed to normal usage in this case. Using the {{ic|--reverse}} option has two effects: Firstly, the configuration file is now stored in the plaintext directory and {{ic|/tmp/thesisbackup}} only contains it in encrypted form. Secondly, the files in {{ic|/tmp/thesisbackup}} are not persistent. They will vanish once it is unmounted (no, this is not due to usage of the {{ic|/tmp}} mountpoint). <br />
<br />
For the second reason, now is the time to copy the encrypted files to the desired backup location, ''before'' unmounting the temporary ''encfs'' directory again: <br />
$ cp -R /tmp/thesisbackup/* /mnt/usbstick/<br />
$ fusermount -u /tmp/thesisbackup <br />
and done. <br />
<br />
To restore (or view) the backup, we need access to the encryption options in plaintext, which has to be passed to ''encfs'' with the environment variable {{ic|ENCFS6_CONFIG}} (we use a different directory in order not to mess up the existing {{ic|~/mythesis}}): <br />
<br />
$ ENCFS6_CONFIG=~/mythesis/.encfs6.xml encfs ~/mnt/usbstick/thesisbackup ~/restoremythesis <br />
<br />
If you now list the restore location, it will contain two files: <br />
<br />
$ ls -la ~/restoremythesis<br />
... <br />
-rw-r--r-- 1 student student 1078 3. Jan 12:33 .encfs6.xml<br />
-rw-r--r-- 1 student student 42 3. Jan 12:33 thesis.txt<br />
...<br />
<br />
== See also ==<br />
<br />
* [https://vgough.github.io/encfs/ EncFS] - project homepage <br />
* [https://defuse.ca/audits/encfs.htm Security audit] of EncFS by Taylor Hornby (January 14, 2014).<br />
* [https://www.ict.griffith.edu.au/anthony/info/crypto/encfs.hints EncFS micro-how-to] by Anthony Thyssen.</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Mkinitcpio&diff=581329Mkinitcpio2019-09-01T19:45:49Z<p>EasyToRemember: /* Runtime hooks */ systemd based init does not run custom runtime hooks.</p>
<hr />
<div>{{DISPLAYTITLE:mkinitcpio}}<br />
[[Category:Boot process]]<br />
[[Category:Kernel]]<br />
[[Category:Arch projects]]<br />
[[Category:Commands]]<br />
[[da:Mkinitcpio]]<br />
[[de:Mkinitcpio]]<br />
[[es:Mkinitcpio]]<br />
[[fr:mkinitcpio]]<br />
[[id:Mkinitcpio]]<br />
[[it:Mkinitcpio]]<br />
[[ja:Mkinitcpio]]<br />
[[ru:Mkinitcpio]]<br />
[[zh-hans:Mkinitcpio]]<br />
{{Related articles start}}<br />
{{Related|systemd}}<br />
{{Related|Kernel modules}}<br />
{{Related|Minimal initramfs}}<br />
{{Related|Boot debugging}}<br />
{{Related|dracut}}<br />
{{Related articles end}}<br />
[https://projects.archlinux.org/mkinitcpio.git/ mkinitcpio] is a Bash script used to create an [[Wikipedia:Initial ramdisk|initial ramdisk]] environment. From the {{man|8|mkinitcpio}} man page:<br />
<br />
:The initial ramdisk is in essence a very small environment (early userspace) which loads various kernel modules and sets up necessary things before handing over control to {{ic|init}}. This makes it possible to have, for example, encrypted root file systems and root file systems on a software RAID array. mkinitcpio allows for easy extension with custom hooks, has autodetection at runtime, and many other features.<br />
<br />
Traditionally, the kernel was responsible for all hardware detection and initialization tasks early in the [[boot process]] before mounting the root file system and passing control to {{ic|init}}. However, as technology advances, these tasks have become increasingly complex. <br />
<br />
Nowadays, the root file system may be on a wide range of hardware, from SCSI to SATA to USB drives, controlled by a variety of drive controllers from different manufacturers. Additionally, the root file system may be encrypted or compressed; within a software RAID array or a logical volume group. The simple way to handle that complexity is to pass management into userspace: an initial ramdisk. See also: [https://web.archive.org/web/20150430223035/http://archlinux.me/brain0/2010/02/13/early-userspace-in-arch-linux/ /dev/brain0 &raquo; Blog Archive &raquo; Early Userspace in Arch Linux].<br />
<br />
mkinitcpio has been developed by the Arch Linux developers and from community contributions. See the [https://projects.archlinux.org/mkinitcpio.git/ public Git repository].<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|mkinitcpio}} package, which is a dependency of the {{Pkg|linux}} package, so most users will already have it installed.<br />
<br />
Advanced users may wish to install the latest development version of mkinitcpio from Git with the {{AUR|mkinitcpio-git}} package.<br />
<br />
{{Note|It is '''highly''' recommended that you follow the [https://mailman.archlinux.org/mailman/listinfo/arch-projects arch-projects mailing list] if you use mkinitcpio from Git!}}<br />
<br />
== Image creation and activation ==<br />
<br />
By default, the mkinitcpio script generates two images after kernel installation or upgrades: a ''default'' image, and a ''fallback'' image that skips the ''autodetect'' hook thus including a full range of mostly-unneeded modules. This is accomplished via the PRESETS directive of the ''.preset'' files which most kernel packages install in {{ic|/etc/mkinitcpio.d/}} (e.g. {{ic|/etc/mkinitcpio.d/linux.preset}} for {{Pkg|linux}} contain {{ic|1=PRESETS=('default' 'fallback')}}). A preset is a predefined definition of how to create an initramfs image instead of specifying the configuration file and output file every time. The {{ic|-p}}/{{ic|--preset}} switch specifies a ''preset'' to utilize. For example, the following will (re-)generate the preset provided by the {{Pkg|linux}} package:<br />
<br />
# mkinitcpio -p linux<br />
<br />
An additional configuration file is located at {{ic|/etc/mkinitcpio.conf}} and is used to specify options global to all presets. The {{ic|-P}}/{{ic|--allpresets}} switch specifies that all presets should be utilized when regenerating the initramfs after a {{ic|mkinitcpio.conf}} change.<br />
<br />
Users may create any number of initramfs images with a variety of different configurations. The desired image must be specified in the respective [[boot loader]] configuration file. <br />
<br />
{{Warning|''.preset'' files are used to automatically regenerate the initramfs after a kernel update; be careful when editing them.}}<br />
<br />
=== Generate customized manual initcpio ===<br />
<br />
Users can generate an image using an alternative configuration file. For example, the following will generate an initramfs image according to the directions in {{ic|/etc/mkinitcpio-custom.conf}} and save it at {{ic|/boot/linux-custom.img}}.<br />
<br />
# mkinitcpio -c /etc/mkinitcpio-custom.conf -g /boot/linux-custom.img<br />
<br />
If generating an image for a kernel other than the one currently running, add the kernel version to the command line. You can see available kernel versions in {{ic|/usr/lib/modules/}}.<br />
<br />
# mkinitcpio -g /boot/linux-custom2.img -k 3.3.0-ARCH<br />
<br />
== Configuration ==<br />
<br />
The primary configuration file for '''mkinitcpio''' is {{ic|/etc/mkinitcpio.conf}}. Additionally, preset definitions are provided by kernel packages in the {{ic|/etc/mkinitcpio.d}} directory (e.g. {{ic|/etc/mkinitcpio.d/linux.preset}}).<br />
<br />
{{Warning|'''lvm2''', '''mdadm''', and '''encrypt''' are '''NOT''' enabled by default. Please read this section carefully for instructions if these hooks are required.}}<br />
<br />
{{Note|<br />
* Users with multiple hardware disk controllers that use the same node names but different kernel modules (e.g. two SCSI/SATA or two IDE controllers) should use [[persistent block device naming]] to ensure that the right devices are mounted. Otherwise, the root device location may change between boots, resulting in kernel panics.<br />
* '''PS/2 keyboard users''': In order to get keyboard input during early init, if you do not have it already, add the '''keyboard''' hook to the {{ic|HOOKS}}. On some motherboards (mostly ancient ones, but also a few new ones), the i8042 controller cannot be automatically detected. It is rare, but some people will surely be without keyboard. You can detect this situation in advance. If you have a PS/2 port and get {{ic|i8042: PNP: No PS/2 controller found. Probing ports directly}} message, add '''atkbd''' to the {{ic|MODULES}}.<br />
}}<br />
<br />
Users can modify six variables within the configuration file:<br />
<br />
; {{ic|MODULES}}: Kernel modules to be loaded before any boot hooks are run. <br />
; {{ic|BINARIES}}: Additional binaries to be included in the initramfs image.<br />
; {{ic|FILES}}: Additional files to be included in the initramfs image.<br />
; {{ic|HOOKS}}: Hooks are scripts that execute in the initial ramdisk.<br />
; {{ic|COMPRESSION}}: Used to compress the initramfs image.<br />
; {{ic|COMPRESSION_OPTIONS}}: Extra arguments to pass to the {{ic|COMPRESSION}} program. Usage of this setting is strongly discouraged. mkinitcpio will handle special requirements for compressors (e.g. passing {{ic|1=--check=crc32}} to xz), and misusage can easily lead to an unbootable system.<br />
<br />
=== MODULES ===<br />
<br />
The {{ic|MODULES}} array is used to specify modules to load before anything else is done.<br />
<br />
Modules suffixed with a {{ic|?}} will not throw errors if they are not found. This might be useful for custom kernels that compile in modules which are listed explicitly in a hook or configuration file.<br />
<br />
{{Note|<br />
* If using '''reiser4''', it ''must'' be added to the modules list.<br />
* If you will be needing any file system during the boot process that is not live when you run mkinitcpio — for example, if your LUKS encryption key file is on an '''ext2''' file system but no '''ext2''' file systems are mounted when you run mkinitcpio — that file system module must also be added to the MODULES list. See [[Dm-crypt/System configuration#cryptkey]] for more details.<br />
}}<br />
<br />
=== BINARIES and FILES ===<br />
<br />
These options allow users to add files to the image. Both {{ic|BINARIES}} and {{ic|FILES}} are added before hooks are run, and may be used to override files used or provided by a hook. {{ic|BINARIES}} are auto-located within a standard {{ic|PATH}} and are dependency-parsed, meaning any required libraries will also be added. {{ic|FILES}} are added ''as-is''. For example:<br />
<br />
FILES=(/etc/modprobe.d/modprobe.conf)<br />
<br />
BINARIES=(kexec)<br />
<br />
Note that for both {{ic|BINARIES}} and {{ic|FILES}}, multiple entries can be added delimited with spaces.<br />
<br />
=== HOOKS ===<br />
<br />
The {{ic|HOOKS}} array is the most important setting in the file. Hooks are small scripts which describe what will be added to the image. For some hooks, they will also contain a runtime component which provides additional behavior, such as starting a daemon, or assembling a stacked block device. Hooks are referred to by their name, and executed in the order they exist in the {{ic|HOOKS}} array of the configuration file.<br />
<br />
The default {{ic|HOOKS}} setting should be sufficient for most simple, single disk setups. For root devices which are stacked or multi-block devices such as [[LVM]], [[Software_RAID_and_LVM|mdadm]], or [[dm-crypt]], see the respective wiki pages for further necessary configuration.<br />
<br />
==== Build hooks ====<br />
<br />
Build hooks are found in {{ic|/usr/lib/initcpio/install/}}, custom build hooks can be placed in {{ic|/etc/initcpio/install/}}. These files are sourced by the bash shell during runtime of mkinitcpio and should contain two functions: {{ic|build}} and {{ic|help}}. The {{ic|build}} function describes the modules, files, and binaries which will be added to the image. An API, documented by {{man|8|mkinitcpio}}, serves to facilitate the addition of these items. The {{ic|help}} function outputs a description of what the hook accomplishes.<br />
<br />
For a list of all available hooks:<br />
<br />
$ mkinitcpio -L<br />
<br />
Use mkinitcpio's {{ic|-H}}/{{ic|--hookhelp}} option to output help for a specific hook, for example:<br />
<br />
$ mkinitcpio -H udev<br />
<br />
==== Runtime hooks ====<br />
<br />
Runtime hooks are found in {{ic|/usr/lib/initcpio/hooks/}}, custom runtime hooks can be placed in {{ic|/etc/initcpio/hooks/}}. For any runtime hook, there should always be a build hook of the same name, which calls {{ic|add_runscript}} to add the runtime hook to the image. These files are sourced by the busybox ash shell during early userspace. With the exception of cleanup hooks, they will always be run in the order listed in the {{ic|HOOKS}} setting. Runtime hooks may contain several functions:<br />
<br />
{{ic|run_earlyhook}}: Functions of this name will be run once the API file systems have been mounted and the kernel command line has been parsed. This is generally where additional daemons, such as udev, which are needed for the early boot process are started from.<br />
<br />
{{ic|run_hook}}: Functions of this name are run shortly after the early hooks. This is the most common hook point, and operations such as assembly of stacked block devices should take place here.<br />
<br />
{{ic|run_latehook}}: Functions of this name are run after the root device has been mounted. This should be used, sparingly, for further setup of the root device, or for mounting other file systems, such as {{ic|/usr}}.<br />
<br />
{{ic|run_cleanuphook}}: Functions of this name are run as late as possible, and in the reverse order of how they are listed in the {{ic|HOOKS}} setting in the config file. These hooks should be used for any last minute cleanup, such as shutting down any daemons started by an early hook.<br />
<br />
{{Note|<br />
* Custom runtime hooks are usefull only for busybox init. '''systemd''' hook triggers a systemd based init, which will not run any custom runtime hook.<br />
}}<br />
<br />
==== Common hooks ====<br />
<br />
A table of common hooks and how they affect image creation and runtime follows. Note that this table is not complete, as packages can provide custom hooks.<br />
<br />
{{Expansion|Add info about {{ic|hostdata}}, {{ic|memdisk}}, {{ic|sleep}} and {{ic|strip}}, find out if {{ic|dmraid}}, etc. work/are needed for systemd based initramfs.|section=Improvements for the Common hooks table and section about systemd hook}}<br />
<br />
{| class="wikitable"<br />
! busybox init !! systemd init !! [[#Build hooks|Build hook]] !! [[#Runtime hooks|Runtime hook]] (busybox init only)<br />
|-<br />
|colspan="2" {{C|'''base'''}} || Sets up all initial directories and installs base utilities and libraries. Always keep this hook as the first hook unless you know what you are doing, as it provides critical busybox init when not using '''systemd''' hook.<br />
Provides a busybox recovery shell when using '''systemd''' hook.<br />
| {{-}}<br />
|-<br />
| {{C|'''udev'''}} ||rowspan="3" {{C|'''systemd'''}} || Adds udevd, udevadm, and a small subset of udev rules to your image. || Starts the udev daemon and processes uevents from the kernel; creating device nodes. As it simplifies the boot process by not requiring the user to explicitly specify necessary modules, using it is recommended.<br />
|-<br />
| {{C|'''usr'''}} || Adds support for {{ic|/usr}} on a separate partition. See [[#/usr as a separate partition]] for details. || Mounts the {{ic|/usr}} partition after the real root has been mounted.<br />
|-<br />
|-<br />
| {{C|'''resume'''}} || {{-}} || Tries to resume from the "suspend to disk" state. See [[Hibernation]] for further configuration.<br />
|-<br />
| {{C|'''btrfs'''}} || {{Grey|--}} || Sets the required modules to enable [[Btrfs]] for using multiple devices with Btrfs. You need to have {{Pkg|btrfs-progs}} installed to use this. This hook is not required for using Btrfs on a single device. || Runs {{ic|btrfs device scan}} to assemble a multi-device Btrfs root file system when '''udev''' hook or '''systemd''' hook is not present. The {{Pkg|btrfs-progs}} package is required for this hook.<br />
|-<br />
|colspan="2" {{C|'''autodetect'''}} || Shrinks your initramfs to a smaller size by creating a whitelist of modules from a scan of sysfs. Be sure to verify included modules are correct and none are missing. This hook must be run before other subsystem hooks in order to take advantage of auto-detection. Any hooks placed before 'autodetect' will be installed in full. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''modconf'''}} || Includes modprobe configuration files from {{ic|/etc/modprobe.d/}} and {{ic|/usr/lib/modprobe.d/}}. || {{-}}<br />
|-<br />
|colspan="2" {{C|'''block'''}} || Adds all block device modules, formerly separately provided by the ''fw'', ''mmc'', ''pata'', ''sata'', ''scsi'', ''usb'', and ''virtio'' hooks. || {{-}}<br />
|-<br />
| {{C|'''net'''}} || {{R|''not implemented''}} || Adds the necessary modules for a network device. You must have {{Pkg|mkinitcpio-nfs-utils}} installed to use this, see [[#Using net]] for details. || Provides handling for an NFS-based root file system.<br />
|-<br />
| {{C|'''dmraid'''}} || {{C|''?''}} || Provides support for fakeRAID root devices. You must have {{Pkg|dmraid}} installed to use this. Note that it is preferred to use {{ic|mdadm}} with the '''mdadm_udev''' hook with fakeRAID if your controller supports it. See [[#Using RAID]] for details. || Locates and assembles fakeRAID block devices using {{ic|dmraid}}.<br />
|-<br />
| {{C|'''mdadm'''}} || {{Grey|--}} || Provides support for assembling RAID arrays from {{ic|/etc/mdadm.conf}}, or autodetection during boot. You must have {{Pkg|mdadm}} installed to use this. The '''mdadm_udev''' hook is preferred over this hook. See [[#Using RAID]] for details. || Locates and assembles software RAID block devices using {{ic|mdassemble}}.<br />
|-<br />
|colspan="2" {{C|'''mdadm_udev'''}} || Provides support for assembling RAID arrays via udev. You must have {{Pkg|mdadm}} installed to use this. If you use this hook with a FakeRAID array, it is recommended to include {{ic|mdmon}} in the binaries section. See [[#Using RAID]] for details. || Locates and assembles software RAID block devices using {{ic|udev}} and {{ic|mdadm}} incremental assembly. This is the preferred method of mdadm assembly (rather than using the above ''mdadm'' hook). <br />
|-<br />
|colspan="2" {{C|'''keyboard'''}} || Adds the necessary modules for keyboard devices. Use this if you have an USB or serial keyboard and need it in early userspace (either for entering encryption passphrases or for use in an interactive shell). As a side effect, modules for some non-keyboard input devices might be added too, but this should not be relied on. Supersedes old ''usbinput'' hook.<br />
<br />
{{Tip|For systems that are booted with different hardware configurations (e.g. laptops with external keyboard vs. internal keyboard or [[Wikipedia:Headless computer|headless systems]]), it is helpful to place this hook before '''autodetect''' in order to always include all keyboard drivers. Otherwise the external keyboard only works in early userspace if it was connected when creating the image.}}<br />
<br />
| {{-}}<br />
|-<br />
| {{C|'''keymap'''}} ||rowspan="2" {{C|'''sd-vconsole'''}} || Adds the specified [[Linux console/Keyboard configuration#Persistent configuration|keymap(s)]] from {{ic|/etc/vconsole.conf}} to the initramfs. If you use [[dm-crypt/Encrypting an entire system|system encryption]], especially full-disk encryption, make sure you add it before the {{ic|1=encrypt}} hook. || Loads the specified keymap(s) from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''consolefont'''}} || Adds the specified [[Linux console#Persistent configuration|console font]] from {{ic|/etc/vconsole.conf}} to the initramfs. || Loads the specified console font from {{ic|/etc/vconsole.conf}} during early userspace.<br />
|-<br />
| {{C|'''encrypt'''}} || {{C|'''sd-encrypt'''}} || Adds the {{ic|dm_crypt}} kernel module and the {{ic|cryptsetup}} tool to the image. You must have {{Pkg|cryptsetup}} installed to use this. || Detects and unlocks an encrypted root partition. See [[#Runtime customization]] for further configuration.<br />
For '''sd-encrypt''' see [[dm-crypt/System configuration#Using sd-encrypt hook]].<br />
|-<br />
| {{C|'''lvm2'''}} || {{C|'''sd-lvm2'''}} || Adds the device mapper kernel module and the {{ic|lvm}} tool to the image. You must have {{Pkg|lvm2}} installed to use this. || Enables all LVM2 volume groups. This is necessary if you have your root file system on [[LVM]].<br />
|-<br />
|colspan="2" {{C|'''fsck'''}} || Adds the fsck binary and file system-specific helpers. If added after the '''autodetect''' hook, only the helper specific to your root file system will be added. Usage of this hook is '''strongly''' recommended, and it is required with a separate {{ic|/usr}} partition. || Runs fsck against your root device (and {{ic|/usr}} if separate) prior to mounting. The use of this hook requires the rw parameter to be set on the kernel commandline ([https://bbs.archlinux.org/viewtopic.php?pid=1307895#p1307895 discussion]).<br />
|-<br />
|colspan="2" {{C|'''filesystems'''}} || This includes necessary file system modules into your image. This hook is '''required''' unless you specify your file system modules in MODULES. || {{-}}<br />
|-<br />
|}<br />
<br />
=== COMPRESSION ===<br />
<br />
The kernel supports several formats for compression of the initramfs—{{pkg|gzip}}, {{pkg|bzip2}}, lzma, {{pkg|xz}} (also known as lzma2), {{pkg|lzo}}, and {{pkg|lz4}}. For most use cases, gzip, lzop, and lz4 provide the best balance of compressed image size and decompression speed. The provided {{ic|mkinitcpio.conf}} has the various {{ic|COMPRESSION}} options commented out. Uncomment one to choose which compression format you desire.<br />
<br />
Specifying no {{ic|COMPRESSION}} will result in a gzip-compressed initramfs file. To create an uncompressed image, specify {{ic|1=COMPRESSION=cat}} in the config or use {{ic|-z cat}} on the command line.<br />
<br />
Make sure you have the correct file compression utility installed for the method you wish to use.<br />
<br />
=== COMPRESSION_OPTIONS ===<br />
<br />
These are additional flags passed to the program specified by {{ic|COMPRESSION}}, such as:<br />
<br />
COMPRESSION_OPTIONS=(-9)<br />
<br />
{{Note|In general these should never be needed as mkinitcpio will make sure that any supported compression method has the necessary flags to produce a working image. Furthermore, misusage of this option can lead to an '''unbootable system''' if the kernel is unable to unpack the resultant archive.}}<br />
<br />
== Runtime customization ==<br />
<br />
{{Expansion|Which options work with the {{ic|systemd}} hook and which are {{ic|base}}-only?}}<br />
<br />
Runtime configuration options can be passed to {{ic|init}} and certain hooks via the kernel command line. Kernel command-line parameters are often supplied by the bootloader. The options discussed below can be appended to the kernel command line to alter default behavior. See [[Kernel parameters]] and [[Arch boot process]] for more information.<br />
<br />
=== init from base hook ===<br />
<br />
; {{ic|root}}: This is the most important parameter specified on the kernel command line, as it determines what device will be mounted as your proper root device. mkinitcpio is flexible enough to allow a wide variety of formats, for example:<br />
<br />
root=/dev/sda1 # /dev node<br />
root=LABEL=CorsairF80 # label<br />
root=UUID=ea1c4959-406c-45d0-a144-912f4e86b207 # UUID<br />
root=PARTUUID=14420948-2cea-4de7-b042-40f67c618660 # GPT partition UUID<br />
<br />
{{Note|The following boot parameters alter the default behavior of {{ic|init}} in the initramfs environment. See {{ic|/usr/lib/initcpio/init}} for details. They will not work when {{ic|systemd}} hook is being used since the {{ic|init}} from {{ic|base}} hook is replaced.}}<br />
<br />
; {{ic|break}}: If {{ic|break}} or {{ic|1=break=premount}} is specified, {{ic|init}} pauses the boot process (after loading hooks, but before mounting the root file system) and launches an interactive shell which can be used for troubleshooting purposes. This shell can be launched after the root has been mounted by specifying {{ic|1=break=postmount}}. Normal boot continues after exiting from the shell.<br />
<br />
; {{ic|disablehooks}}: Disable hooks at runtime by adding {{ic|1=disablehooks=hook1[,hook2,...]}}. For example: {{bc|1=disablehooks=resume}}<br />
<br />
; {{ic|earlymodules}}: Alter the order in which modules are loaded by specifying modules to load early via {{ic|1=earlymodules=mod1[,mod2,...]}}. (This may be used, for example, to ensure the correct ordering of multiple network interfaces.)<br />
<br />
See [[Boot debugging]] and {{man|8|mkinitcpio}} for other parameters.<br />
<br />
=== Using RAID ===<br />
<br />
{{Note|{{ic|mdadm}} is deprecated. If using it you will see {{ic|1===> WARNING: Hook 'mdadm' is deprecated. Replace it with 'mdadm_udev' in your config}} when doing an upgrade.}}<br />
<br />
First, add the {{ic|mdadm_udev}} or {{ic|mdadm}} hook to the {{ic|HOOKS}} array and any required RAID modules (e.g. raid456, ext4) to the {{ic|MODULES}} array in {{ic|/etc/mkinitcpio.conf}}.<br />
<br />
Using the {{ic|mdadm}} hook, you no longer need to configure your RAID array in the [[kernel parameters]]. The {{ic|mdadm}} hook will either use your {{ic|/etc/mdadm.conf}} file or automatically detect the array(s) during the init phase of boot.<br />
<br />
Assembly via udev is also possible using the {{ic|mdadm_udev}} hook. Upstream prefers this method of assembly. {{ic|/etc/mdadm.conf}} will still be read for purposes of naming the assembled devices if it exists.<br />
<br />
=== Using net ===<br />
<br />
{{Warning|NFSv4 is not yet supported {{Bug|28287}}.}}<br />
<br />
'''Required Packages'''<br />
<br />
{{ic|net}} requires the {{Pkg|mkinitcpio-nfs-utils}} package.<br />
<br />
'''Kernel Parameters''' <br />
<br />
Comprehensive and up-to-date information can be found in the official [https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt kernel documentation].<br />
<br />
'''ip='''<br />
<br />
This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It can take up to nine arguments separated by colons: {{ic|1=ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>:<dns0-ip>:<dns1-ip>}}.<br />
<br />
If this parameter is missing from the kernel command line, all fields are assumed to be empty, and the defaults mentioned in the [https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt kernel documentation] apply. In general this means that the kernel tries to configure everything using autoconfiguration.<br />
<br />
The {{ic|<autoconf>}} parameter can appear alone as the value to the 'ip' parameter (without all the ':' characters before). If the value is {{ic|1=ip=off}} or {{ic|1=ip=none}}, no autoconfiguration will take place, otherwise autoconfiguration will take place. The most common way to use this is {{ic|1=ip=dhcp}}.<br />
<br />
For parameters explanation, see the [https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt kernel doc].<br />
<br />
Examples:<br />
<br />
ip=127.0.0.1:::::lo:none --> Enable the loopback interface.<br />
ip=192.168.1.1:::::eth2:none --> Enable static eth2 interface.<br />
ip=:::::eth0:dhcp --> Enable dhcp protocol for eth0 configuration.<br />
<br />
{{Note|Make sure to use kernel device names (e.g. {{ic|eth0}}) for the {{ic|<device>}} parameter, the persistent names (e.g. {{ic|enp2s0}}) will not work. See [[Network configuration#Network interfaces]] for details.}}<br />
<br />
'''BOOTIF='''<br />
<br />
If you have multiple network cards, this parameter can include the MAC address of the interface you are booting from. This is often useful as interface numbering may change, or in conjunction with pxelinux IPAPPEND 2 or IPAPPEND 3 option.<br />
If not given, eth0 will be used.<br />
<br />
Example:<br />
<br />
BOOTIF=01-A1-B2-C3-D4-E5-F6 # Note the prepended "01-" and capital letters.<br />
<br />
'''nfsroot='''<br />
<br />
If the {{ic|nfsroot}} parameter is NOT given on the command line, the default {{ic|/tftpboot/%s}} will be used.<br />
<br />
nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>]<br />
<br />
Run {{ic|mkinitcpio -H net}} for parameter explanation.<br />
<br />
=== Using LVM ===<br />
<br />
If your root device is on [[LVM]], see [[LVM#Configure mkinitcpio]].<br />
<br />
=== Using encrypted root ===<br />
<br />
If using an [[Dm-crypt/Encrypting_an_entire_system|encrypted root]] see [[Dm-crypt/System configuration#mkinitcpio]] for detailed information on which hooks to include.<br />
<br />
=== /usr as a separate partition ===<br />
<br />
If you keep {{ic|/usr}} as a separate partition, you must adhere to the following requirements:<br />
<br />
* Add the {{ic|fsck}} hook, mark {{ic|/usr}} with a {{ic|passno}} of {{ic|0}} in {{ic|/etc/fstab}}. While recommended for everyone, it is mandatory if you want your {{ic|/usr}} partition to be fsck'ed at boot-up. Without this hook, {{ic|/usr}} will never be fsck'd.<br />
* If not using the systemd hook, add the {{ic|usr}} hook. This will mount the {{ic|/usr}} partition after root is mounted.<br />
<br />
== Troubleshooting ==<br />
<br />
=== Extracting the image ===<br />
<br />
If you are curious about what is inside the initramfs image, you can extract it and poke at the files inside of it. <br />
<br />
The initramfs image is an SVR4 CPIO archive, generated via the {{ic|find}} and {{ic|bsdcpio}} commands, optionally compressed with a compression scheme understood by the kernel. For more information on the compression schemes, see [[#COMPRESSION]].<br />
<br />
mkinitcpio includes a utility called {{ic|lsinitcpio}} which will list and/or extract the contents of initramfs images.<br />
<br />
You can list the files in the image with:<br />
<br />
$ lsinitcpio /boot/initramfs-linux.img<br />
<br />
And to extract them all in the current directory:<br />
<br />
$ lsinitcpio -x /boot/initramfs-linux.img<br />
<br />
You can also get a more human-friendly listing of the important parts in the image:<br />
<br />
$ lsinitcpio -a /boot/initramfs-linux.img<br />
<br />
=== Recompressing a modified extracted image ===<br />
<br />
After extracting an image as explained above, after modifying it, you can find the command necessary to recompress it. Edit {{ic|/usr/bin/mkinitcpio}} and change the line as shown below (line 531 in mkinitcpio v20-1.)<br />
<br />
#MKINITCPIO_PROCESS_PRESET=1 "$0" "${preset_cmd[@]}"<br />
MKINITCPIO_PROCESS_PRESET=1 /usr/bin/bash -x "$0" "${preset_cmd[@]}"<br />
<br />
Then running {{ic|mkinitcpio}} with its usual options (typically {{ic|mkinitcpio -p linux}}), toward the last 20 lines or so you will see something like:<br />
<br />
+ find -mindepth 1 -printf '%P\0'<br />
+ LANG=C<br />
+ bsdcpio -0 -o -H newc --quiet<br />
+ gzip<br />
<br />
Which corresponds to the command you need to run, which may be:<br />
<br />
# find -mindepth 1 -printf '%P\0' | LANG=C bsdcpio -0 -o -H newc --quiet | gzip > /boot/initramfs-linux.img<br />
<br />
{{Warning|It is a good idea to rename the automatically generated {{ic|/boot/initramfs-linux.img}} before you overwrite it, so you can easily undo your changes. Be prepared for making a mistake that prevents your system from booting. If this happens, you will need to boot through the fallback, or a boot CD, to restore your original, run mkinitcpio to overwrite your changes, or fix them yourself and recompress the image.}}<br />
<br />
=== "/dev must be mounted" when it already is ===<br />
<br />
The test used by mkinitcpio to determine if {{ic|/dev}} is mounted is to see if {{ic|/dev/fd/}} is there. If everything else looks fine, it can be "created" manually by:<br />
<br />
# ln -s /proc/self/fd /dev/<br />
<br />
(Obviously, {{ic|/proc}} must be mounted as well. mkinitcpio requires that anyway, and that is the next thing it will check.)<br />
<br />
=== Possibly missing firmware for module XXXX ===<br />
<br />
When initramfs are being rebuild after a kernel update, you might get these or similar warnings:<br />
<br />
==> WARNING: Possibly missing firmware for module: aic94xx<br />
==> WARNING: Possibly missing firmware for module: wd719x <br />
<br />
These appear to any Arch Linux users, especially those who have not installed these firmware modules. If you do not use hardware which uses these firmwares you can safely ignore this message.<br />
<br />
=== Standard rescue procedures ===<br />
<br />
With an improper initial ram-disk a system often is unbootable. So follow a system rescue procedure like below:<br />
<br />
==== Boot succeeds on one machine and fails on another ====<br />
<br />
''mkinitcpio'''s {{ic|autodetect}} hook filters unneeded [[kernel modules]] in the primary initramfs scanning {{ic|/sys}} and the modules loaded at the time it is run. If you transfer your {{ic|/boot}} directory to another machine and the boot sequence fails during early userspace, it may be because the new hardware is not detected due to missing kernel modules. Note that USB 2.0 and 3.0 need different kernel modules. <br />
<br />
To fix, first try choosing the [[#Image creation and activation|fallback]] image from your [[bootloader]], as it is not filtered by {{ic|autodetect}}. Once booted, run ''mkinitcpio'' on the new machine to rebuild the primary image with the correct modules. If the fallback image fails, try booting into an Arch Linux live CD/USB, chroot into the installation, and run ''mkinitcpio'' on the new machine. As a last resort, try [[#MODULES|manually]] adding modules to the initramfs.<br />
<br />
== See also ==<br />
<br />
* Linux Kernel documentation on [https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/filesystems/ramfs-rootfs-initramfs.txt?id=HEAD initramfs], search for "What is rootfs?"<br />
* Linux Kernel documentation on [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/initrd.rst?id=HEAD initrd]<br />
* Wikipedia article on [[wikipedia:initrd|initrd]]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Archiso&diff=581042Archiso2019-08-26T17:40:13Z<p>EasyToRemember: /* Build the ISO */ Warning regarding deletion of work directory</p>
<hr />
<div>[[Category:Live Arch systems]]<br />
[[Category:Installation process]]<br />
[[Category:Arch projects]]<br />
[[ar:Archiso]]<br />
[[el:Archiso]]<br />
[[es:Archiso]]<br />
[[fr:Archiso]]<br />
[[it:Archiso]]<br />
[[ja:Archiso]]<br />
[[nl:Archiso]]<br />
[[pt:Archiso]]<br />
[[ru:Archiso]]<br />
[[sk:Archiso]]<br />
[[zh-hans:Archiso]]<br />
{{Related articles start}}<br />
{{Related|Remastering the Install ISO}}<br />
{{Related|Archiso as pxe server}}<br />
{{Related|Archboot}}<br />
{{Related|Offline installation}}<br />
{{Related articles end}}<br />
'''Archiso''' is a small set of bash scripts capable of building fully functional Arch Linux live CD/DVD/USB images. It is the same tool used to generate the official images, but since it is a very generic tool, it can be used to generate anything from rescue systems, install disks, to special interest live CD/DVD/USB systems, and who knows what else. Simply put, if it involves Arch on a shiny coaster, it can do it. The heart and soul of Archiso is ''mkarchiso''. All of its options are documented in its usage output, so its direct usage will not be covered here. Instead, this wiki article will act as a guide for rolling your own live media in no time!<br />
<br />
If you require a technical run-down of requirements and build steps only, have a look at the [https://git.archlinux.org/archiso.git/tree/docs official project documentation] too.<br />
<br />
== Setup ==<br />
<br />
{{Note|It is recommended to act as root in all the following steps. If not, it is very likely to have problems with false permissions later.}}<br />
Before you begin, [[install]] the {{Pkg|archiso}} or {{AUR|archiso-git}} package.<br />
<br />
Archiso comes with two "profiles": ''releng'' and ''baseline''.<br />
<br />
* If you wish to create a fully customized live version of Arch Linux, pre-installed with all your favorite programs and configurations, use ''releng''. This profile is also used for building an official Arch Linux ISO.<br />
* If you just want to create the most basic live medium, with no pre-installed packages and a minimalistic configuration, use ''baseline''.<br />
<br />
Now, copy the profile of your choice to a directory (''archlive'' in the example below) where you can make adjustments and build it. Execute the following, replacing {{ic|'''profile'''}} with either {{ic|releng}} or {{ic|baseline}}.<br />
<br />
# cp -r /usr/share/archiso/configs/'''profile'''/ ''archlive''<br />
<br />
* If you are using the {{ic|releng}} profile to make a fully customized image, then you can proceed onto [[#Configure the live medium]].<br />
* If you are using the {{ic|baseline}} profile to create a bare image or using {{ic|releng}} to replicate an official ISO, then you will not be needing to do any customization and can proceed onto [[#Build the ISO]].<br />
<br />
== Configure the live medium ==<br />
<br />
This section details configuring the image you will be creating, allowing you to define the packages and configurations you want your live image to contain.<br />
<br />
Inside the {{ic|''archlive''}} directory created in [[#Setup]] there are a number of files and directories; we are only concerned with a few of these, mainly: <br />
* {{ic|packages.x86_64}} - this is where you list, line by line, the packages you want to have installed, and<br />
* the {{ic|airootfs}} directory - this directory acts as an overlay and it is where you make all the customizations.<br />
<br />
Generally, every administrative task that you would normally do after a fresh install except for package installation can be scripted into {{ic|''archlive''/airootfs/root/customize_airootfs.sh}}. It has to be written from the perspective of the new environment, so {{ic|/}} in the script means the root of the live-iso which is to be created.<br />
<br />
=== Installing packages ===<br />
<br />
Edit the lists of packages in {{ic|packages.x86_64}} to indicate which packages are to be installed on the live medium.<br />
<br />
{{Note|If you want to use a [[window manager]] in the Live CD then you must add the necessary and correct [[video drivers]], or the WM may freeze on loading.}}<br />
<br />
==== Custom local repository ====<br />
<br />
For the purpose of preparing custom packages or packages from [[AUR]]/[[ABS]], you could also [[custom local repository|create a custom local repository]].<br />
You can then add your repository by putting the following into {{ic|~/archlive/pacman.conf}}, above the other repository entries (for top priority):<br />
<br />
{{hc|~/archlive/pacman.conf|...<br />
# custom repository<br />
[customrepo]<br />
SigLevel <nowiki>=</nowiki> Optional TrustAll<br />
Server <nowiki>=</nowiki> file:///home/'''user'''/customrepo/$arch<br />
...}}<br />
<br />
==== Preventing installation of packages belonging to base group ====<br />
<br />
By default, {{ic|/usr/bin/mkarchiso}}, a script which is used by {{ic|~/archlive/build.sh}}, calls one of the {{Pkg|arch-install-scripts}} named {{ic|pacstrap}} without the {{ic|-i}} flag, which causes [[Pacman]] to not wait for user input during the installation process.<br />
<br />
When blacklisting base group packages by adding them to the {{ic|IgnorePkg}} line in {{ic|~/archlive/pacman.conf}}, [[Pacman]] asks if they still should be installed, which means they will when user input is bypassed. To get rid of these packages there are several options:<br />
<br />
* '''Dirty''': Add the {{ic|-i}} flag to each line calling {{ic|pacstrap}} in {{ic|/usr/bin/mkarchiso}}.<br />
<br />
* '''Clean''': Create a copy of {{ic|/usr/bin/mkarchiso}} in which you add the flag and adapt {{ic|~/archlive/build.sh}} so that it calls the modified version of the mkarchiso script.<br />
<br />
* '''Advanced''': Create a function for {{ic|~/archlive/build.sh}} which explicitly removes the packages after the base installation. This would leave you the comfort of not having to type enter so much during the installation process.<br />
<br />
==== Installing packages from multilib ====<br />
<br />
To install packages from the [[multilib]] repository simply uncomment the repository in {{ic|~/archlive/pacman.conf}}:<br />
<br />
{{hc|pacman.conf|2=<br />
[multilib]<br />
SigLevel = PackageRequired<br />
Include = /etc/pacman.d/mirrorlist<br />
}}<br />
<br />
=== Adding files to image ===<br />
<br />
{{Note|You must be root to do this, do not change the ownership of any of the files you copy over, '''everything''' within the airootfs directory must be root owned. Proper ownerships will be sorted out shortly.}}<br />
<br />
The airootfs directory acts as an overlay, think of it as root directory '/' on your current system, so any files you place within this directory will be copied over on boot-up.<br />
<br />
So if you have a set of iptables scripts on your current system you want to be used on you live image, copy them over as such:<br />
# cp -r /etc/iptables ~/archlive/airootfs/etc<br />
<br />
Placing files in the users home directory is a little different. Do not place them within {{ic|airootfs/home}}, but instead create a skel directory within {{ic|airootfs/}} and place them there. We will then add the relevant commands to the {{ic|customize_airootfs.sh}} which we are going to use to copy them over on boot and sort out the permissions.<br />
<br />
First, create the skel directory:<br />
# mkdir ~/archlive/airootfs/etc/skel<br />
<br />
Now copy the 'home' files to the skel directory, e.g for {{ic|.bashrc}}:<br />
# cp ~/.bashrc ~/archlive/airootfs/etc/skel/<br />
<br />
When {{ic|~/archlive/airootfs/root/customize_airootfs.sh}} is executed and a new user is created, the files from the skel directory will automatically be copied over to the new home folder, permissions set right.<br />
<br />
Similarly, some care is required for special configuration files that reside somewhere down the hierarchy. As an example the {{ic|/etc/X11/xinit/xinitrc}} configuration file resides on a path that might be overwritten by installing a package. To place the configuration file one should put the custom {{ic|xinitrc}} in {{ic|~/archlive/airootfs/etc/skel/}} and then modify {{ic|customize_airootfs.sh}} to move it appropriately.<br />
<br />
=== Boot Loader ===<br />
<br />
The default file should work fine, so you should not need to touch it.<br />
<br />
Due to the modular nature of isolinux, you are able to use lots of addons since all *.c32 files are copied and available to you. Take a look at the [http://syslinux.zytor.com/wiki/index.php/SYSLINUX official syslinux site] and the [https://projects.archlinux.org/archiso.git/tree/configs/syslinux-iso/boot-files archiso git repo]. Using said addons, it is possible to make visually attractive and complex menus. See [http://syslinux.zytor.com/wiki/index.php/Comboot/menu.c32 here].<br />
<br />
==== UEFI Secure Boot ====<br />
<br />
If you want to make your Archiso bootable on a UEFI Secure Boot enabled environment, you must use a signed bootloader. You can follow the instructions on [[Secure Boot#Booting an install media]].<br />
<br />
=== Login manager ===<br />
<br />
Starting X at boot is done by enabling your login manager's [[systemd]] service. If you know which .service file needs a softlink: Great. If not, you can easily find out in case you are using the same program on the system you build your iso on. Just use:<br />
<br />
$ ls -l /etc/systemd/system/display-manager.service<br />
<br />
Now create the same softlink in {{ic|~/archlive/airootfs/etc/systemd/system}}. For LXDM:<br />
<br />
# ln -s /usr/lib/systemd/system/lxdm.service ~/archlive/airootfs/etc/systemd/system/display-manager.service<br />
<br />
This will enable LXDM at system start on your live system.<br />
<br />
Alternatively you can just enable the service in {{ic|airootfs/root/customize_airootfs.sh}} along with other services that are enabled there.<br />
<br />
If you want the graphical environment to actually start automatically during boot make sure to edit {{ic|airootfs/root/customize_airootfs.sh}} and replace <br />
<br />
systemctl set-default multi-user.target<br />
with<br />
systemctl set-default graphical.target<br />
<br />
=== Changing Automatic Login ===<br />
<br />
The configuration for getty's automatic login is located under {{ic|airootfs/etc/systemd/system/getty@tty1.service.d/autologin.conf}}.<br />
<br />
You can modify this file to change the auto login user:<br />
<br />
[Service]<br />
ExecStart=<br />
ExecStart=-/sbin/agetty --autologin '''isouser''' --noclear %I 38400 linux<br />
<br />
Or remove it altogether to disable auto login.<br />
<br />
== Build the ISO ==<br />
<br />
Now you are ready to turn your files into the .iso which you can then burn to CD or USB.<br />
<br />
Inside {{ic|~/archlive}}, execute:<br />
<br />
# ./build.sh -v<br />
<br />
The script will now download and install the packages you specified to {{ic|work/*/airootfs}}, create the kernel and init images, apply your customizations and finally build the iso into {{ic|out/}}.<br />
<br />
=== Rebuild the ISO ===<br />
<br />
Rebuilding the iso after modifications is not officially supported. However, it is easily possible by applying two steps. First you have to remove lock files in the work directory:<br />
<br />
# rm -v work/build.make_*<br />
<br />
If you have edited {{ic|airootfs/root/customize_airootfs.sh}} to create an unprivileged user, the rebuild will fail when creating it because the user will already exist ({{Bug|41865}}). To avoid this issue, you need to check if the user exists before running {{ic|useradd}}, e.g. by running {{ic|id}}:<br />
<br />
! id arch && useradd -m -p "" -g users -G "adm,audio,floppy,log,network,rfkill,scanner,storage,optical,power,wheel" -s /usr/bin/zsh arch<br />
<br />
Also remove persistent data such as created users or symlinks such as {{ic|/etc/sudoers}}.<br />
<br />
{{Expansion|Report more data that needs to be removed or reset.}}<br />
<br />
Rebuilds can be sped up slightly by editing the pacstrap script (located at /bin/pacstrap) and changing the following at line 361:<br />
<br />
Before:<br />
<br />
if ! pacman -r "$newroot" -Sy "${pacman_args[@]}"; then<br />
<br />
After:<br />
<br />
if ! pacman -r "$newroot" -Sy --needed "${pacman_args[@]}"; then<br />
<br />
This increases the speed of the initial bootstrap, since it does not have to download and install any of the base packages that are already installed.<br />
<br />
=== Removal of work directory ===<br />
<br />
The temporary files are copied into work directory. If it happens that the build.sh script is interrupted, make sure there are no mount binds before deleting it - otherwise, you may lose data (e.g. an external device mounted at {{ic|/run/media/$user/$label}} gets bound within {{ic|work/x86_64/airootfs/run/media/$user/$label}} during the build process).<br />
<br />
== Using the ISO ==<br />
<br />
See the [[Installation guide]] article for various options.<br />
<br />
== See also ==<br />
=== Documentation and tutorials ===<br />
* [https://projects.archlinux.org/archiso.git Archiso project page]<br />
* [https://projects.archlinux.org/archiso.git/tree/docs Official documentation]<br />
<br />
=== Example customization template ===<br />
* [http://easy.open.and.free.fr/didjix/ A live DJ distribution powered by ArchLinux and built with Archiso]<br />
<br />
=== Creating a offline installation ISO ===<br />
* [[Archiso offline]]<br />
<br />
=== Find a previous version of an ISO image ===<br />
* [[Arch Linux Archive]]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=580945Dm-crypt/Encrypting an entire system2019-08-25T16:16:05Z<p>EasyToRemember: /* Encrypted boot partition (GRUB) */ Correcting info about /boot - which is a directory within root file system on LUKS1, not a separate partition.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[Category:Installation process]]<br />
[[de:Systemverschlüsselung mit dm-crypt]]<br />
[[es:Dm-crypt/Encrypting an entire system]]<br />
[[ja:Dm-crypt/システム全体の暗号化]]<br />
[[pl:Dm-crypt/Encrypting an entire system]]<br />
<br />
The following are examples of common scenarios of full system encryption with ''dm-crypt''. They explain all the adaptations that need to be done to the normal [[Installation guide|installation procedure]]. All the necessary tools are on the [https://www.archlinux.org/download/ installation image].<br />
<br />
== Overview ==<br />
<br />
Securing a root filesystem is where ''dm-crypt'' excels, feature and performance-wise. Unlike selectively encrypting non-root filesystems, an encrypted root filesystem can conceal information such as which programs are installed, the usernames of all user accounts, and common data-leakage vectors such as [[mlocate]] and {{ic|/var/log/}}. Furthermore, an encrypted root filesystem makes tampering with the system far more difficult, as everything except the [[boot loader]] and (usually) the kernel is encrypted.<br />
<br />
All scenarios illustrated in the following share these advantages, other pros and cons differentiating them are summarized below:<br />
<br />
{| class="wikitable"<br />
! Scenarios<br />
! Advantages<br />
! Disadvantages<br />
|----------------------------------------------------------<br />
| [[#LUKS on a partition]]<br />
shows a basic and straight-forward set-up for a fully LUKS encrypted root.<br />
|<br />
* Simple partitioning and setup<br />
|<br />
* Inflexible; disk-space to be encrypted has to be pre-allocated<br />
|----------------------------------------------------------<br />
| [[#LVM on LUKS]]<br />
achieves partitioning flexibility by using LVM inside a single LUKS encrypted partition.<br />
|<br />
* Simple partitioning with knowledge of LVM<br />
* Only one key required to unlock all volumes (e.g. easy resume-from-disk setup)<br />
* Volume layout not transparent when locked<br />
* Easiest method to allow [[dm-crypt/Swap encryption#With suspend-to-disk support|suspension to disk]]<br />
|<br />
* LVM adds an additional mapping layer and hook<br />
* Less useful, if a singular volume should receive a separate key<br />
|----------------------------------------------------------<br />
| [[#LUKS on LVM]]<br />
uses dm-crypt only after the LVM is setup.<br />
|<br />
* LVM can be used to have encrypted volumes span multiple disks<br />
* Easy mix of un-/encrypted volume groups<br />
|<br />
* Complex; changing volumes requires changing encryption mappers too<br />
* Volumes require individual keys<br />
* LVM layout is transparent when locked<br />
|----------------------------------------------------------<br />
| [[#LUKS on software RAID]]<br />
uses dm-crypt only after RAID is setup.<br />
|<br />
* Analogous to LUKS on LVM<br />
|<br />
* Analogous to LUKS on LVM<br />
|----------------------------------------------------------<br />
| [[#Plain dm-crypt]]<br />
uses dm-crypt plain mode, i.e. without a LUKS header and its options for multiple keys. <br>This scenario also employs USB devices for {{ic|/boot}} and key storage, which may be applied to the other scenarios.<br />
|<br />
* Data resilience for cases where a LUKS header may be damaged<br />
* Allows [[Wikipedia:Disk encryption#Full disk encryption|Full Disk Encryption]]<br />
* Helps addressing [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)|problems]] with SSDs<br />
|<br />
* High care to all encryption parameters is required<br />
* Single encryption key and no option to change it<br />
|----------------------------------------------------------<br />
| [[#Encrypted boot partition (GRUB)]]<br />
shows how to encrypt the boot partition using the GRUB bootloader. <br> This scenario also employs an EFI system partition, which may be applied to the other scenarios.<br />
|<br />
* Same advantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* Less data is left unencrypted, i.e. the boot loader and the EFI system partition, if present<br />
|<br />
* Same disadvantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* More complicated configuration<br />
* Not supported by other boot loaders<br />
|----------------------------------------------------------<br />
| [[#Btrfs subvolumes with swap]]<br />
shows how to encrypt a [[Btrfs]] system, including the {{ic|/boot}} directory, also adding a partition for swap, on UEFI hardware.<br />
|<br />
* Similar advantages as [[#Encrypted boot partition (GRUB)]]<br />
* Availability of Btrfs' features<br />
|<br />
* Similar disadvantages as [[#Encrypted boot partition (GRUB)]]<br />
|}<br />
<br />
While all above scenarios provide much greater protection from outside threats than encrypted secondary filesystems, they also share a common disadvantage: any user in possession of the encryption key is able to decrypt the entire drive, and therefore can access other users' data. If that is of concern, it is possible to use a combination of blockdevice and stacked filesystem encryption and reap the advantages of both. See [[Disk encryption]] to plan ahead.<br />
<br />
See [[dm-crypt/Drive preparation#Partitioning]] for a general overview of the partitioning strategies used in the scenarios.<br />
<br />
Another area to consider is whether to set up an encrypted swap partition and what kind. See [[dm-crypt/Swap encryption]] for alternatives.<br />
<br />
If you anticipate to protect the system's data not only against physical theft, but also have a requirement of precautions against logical tampering, see [[dm-crypt/Specialties#Securing the unencrypted boot partition]] for further possibilities after following one of the scenarios.<br />
<br />
For [[solid state drive]]s you might want to consider enabling TRIM support, but be warned, there are potential security implications. See [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]] for more information.<br />
<br />
{{Warning|<br />
* In any scenario, never use file system repair software such as [[fsck]] directly on an encrypted volume, or it will destroy any means to recover the key used to decrypt your files. Such tools must be used on the decrypted (opened) device instead.<br />
* For the LUKS2 format:<br />
** [[GRUB]] does not support LUKS2.[https://savannah.gnu.org/bugs/?55093] Use LUKS1 on partitions that GRUB needs to access.<br />
** The LUKS2 format has a high RAM usage per design, defaulting to 1GB per encrypted mapper. Machines with low RAM and/or multiple LUKS2 partitions unlocked in parallel may error on boot. See the {{ic|--pbkdf-memory}} option to control memory usage.[https://gitlab.com/cryptsetup/cryptsetup/issues/372]<br />
}}<br />
<br />
== LUKS on a partition ==<br />
<br />
This example covers a full system encryption with ''dm-crypt'' + LUKS in a simple partition layout:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------+------------------------+-----------------------+<br />
| Boot partition | LUKS2 encrypted system | Optional free space |<br />
| | partition | for additional |<br />
| | | partitions or swap |<br />
| /boot | / | to be setup later |<br />
| | | |<br />
| | /dev/mapper/cryptroot | |<br />
| |------------------------| |<br />
| /dev/sda1 | /dev/sda2 | |<br />
+-----------------------+------------------------+-----------------------+<br />
</nowiki>}}<br />
<br />
The first steps can be performed directly after booting the Arch Linux install image.<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
Then create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}) and {{ic|/boot}} ({{ic|/dev/sda1}}). See [[Partitioning]].<br />
<br />
=== Preparing non-boot partitions ===<br />
<br />
The following commands create and mount the encrypted root partition. They correspond to the procedure described in detail in [[dm-crypt/Encrypting a non-root file system#Partition]] (which, despite the title, ''can'' be applied to root partitions, as long as [[#Configuring mkinitcpio|mkinitcpio]] and the [[#Configuring the boot loader|boot loader]] are correctly configured).<br />
If you want to use particular non-default encryption options (e.g. cipher, key length), see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|encryption options]] before executing the first command:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sda2<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
Check the mapping works as intended:<br />
<br />
# umount /mnt<br />
# cryptsetup close cryptroot<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
If you created separate partitions (e.g. {{ic|/home}}), these steps have to be adapted and repeated for all of them, ''except'' for {{ic|/boot}}. See [[dm-crypt/Encrypting a non-root file system#Automated unlocking and mounting]] on how to handle additional partitions at boot.<br />
<br />
Note that each blockdevice requires its own passphrase. This may be inconvenient, because it results in a separate passphrase to be input during boot. An alternative is to use a keyfile stored in the system partition to unlock the separate partition via {{ic|crypttab}}. See [[dm-crypt/Device encryption#Using LUKS to format partitions with a keyfile]] for instructions.<br />
<br />
=== Preparing the boot partition ===<br />
<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a encrypted root. For an ordinary boot partition on BIOS systems, for example, execute:<br />
<br />
# mkfs.ext4 /dev/sda1<br />
<br />
or for an [[EFI system partition]] on UEFI systems:<br />
<br />
# mkfs.fat -F32 /dev/sda1<br />
<br />
Afterwards create the directory for the mounpoint and mount the partition:<br />
<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Mounting the devices ===<br />
<br />
At [[Installation guide#Mount the file systems]] you will have to mount the mapped devices, not the actual partitions. Of course {{ic|/boot}}, which is not encrypted, will still have to be mounted directly.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|keymap}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]. If the default US keymap is fine for you, you can omit the {{ic|keymap}} hook.<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' filesystems fsck)<br />
<br />
Depending on which other hooks are used, the order may be relevant. See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptroot root=/dev/mapper/cryptroot<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptroot root=/dev/mapper/cryptroot<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda2}}. See [[Persistent block device naming]] for details.<br />
<br />
== LVM on LUKS ==<br />
<br />
The straight-forward method is to set up [[LVM]] on top of the encrypted partition instead of the other way round. Technically the LVM is setup inside one big encrypted blockdevice. Hence, the LVM is not transparent until the blockdevice is unlocked and the underlying volume structure is scanned and mounted during boot.<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------------------------------------------------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot partition |<br />
| | | | | |<br />
| [SWAP] | / | /home | | /boot |<br />
| | | | | |<br />
| /dev/MyVolGroup/swap | /dev/MyVolGroup/root | /dev/MyVolGroup/home | | |<br />
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _| | (may be on |<br />
| | | other device) |<br />
| LUKS2 encrypted partition | | |<br />
| /dev/sda1 | | /dev/sdb1 |<br />
+-----------------------------------------------------------------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Note|While using the {{ic|encrypt}} hook this method does not allow you to span the logical volumes over multiple disks; either use the [[sd-encrypt]] or see [[dm-crypt/Specialties#Modifying the encrypt hook for multiple partitions]].}}<br />
<br />
{{Tip|Two variants of this setup:<br />
* Instructions at [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] use this setup with a detached LUKS header on a USB device to achieve a two factor authentication with it.<br />
* Instructions at [[dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB]] use this setup with a detached LUKS header, encrypted {{ic|/boot}} partition, and encrypted keyfile all on a USB device.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
{{Tip|When using the [[GRUB]] boot loader for BIOS booting from a [[GPT]] disk, create a [[BIOS boot partition]].}}<br />
<br />
Create a partition to be mounted at {{ic|/boot}} with a size of 200 MiB or more.<br />
<br />
{{Tip|UEFI systems can use the [[EFI system partition]] for {{ic|/boot}}.}}<br />
<br />
Create a partition which will later contain the encrypted container.<br />
<br />
Create the LUKS encrypted container at the "system" partition. Enter the chosen password twice.<br />
<br />
# cryptsetup luksFormat /dev/sda1<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda1 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
Create a physical volume on top of the opened LUKS container:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
<br />
Create the volume group named {{ic|MyVolGroup}} (or whatever you want), adding the previously created physical volume to it:<br />
<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
<br />
Create all your logical volumes on the volume group:<br />
<br />
# lvcreate -L 8G MyVolGroup -n swap<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
Format your filesystems on each logical volume:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mkswap /dev/MyVolGroup/swap<br />
<br />
Mount your filesystems:<br />
<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The bootloader loads the kernel, [[initramfs]], and its own configuration files from the {{ic|/boot}} directory. Any filesystem on a disk that can be read by the bootloader is eligible.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
<br />
{{Tip|When opting to keep {{ic|/boot}} on an [[EFI system partition]] the recommended formatting is<br />
<br />
# mkfs.fat -F32 /dev/sdb1<br />
<br />
}}<br />
<br />
Create the directory {{ic|/mnt/boot}}:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Mount the partition to {{ic|/mnt/boot}}:<br />
<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameter needs to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptlvm root=/dev/MyVolGroup/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptlvm root=/dev/MyVolGroup/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda1}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
== LUKS on LVM ==<br />
<br />
To use encryption on top of [[LVM]], the LVM volumes are set up first and then used as the base for the encrypted partitions. This way, a mixture of encrypted and non-encrypted volumes/partitions is possible as well.<br />
{{tip|Unlike [[#LVM on LUKS]], this method allows normally spanning the logical volumes over multiple disks. }}<br />
<br />
The following short example creates a LUKS on LVM setup and mixes in the use of a key-file for the /home partition and temporary crypt volumes for {{ic|/tmp}} and {{ic|/swap}}. The latter is considered desirable from a security perspective, because no potentially sensitive temporary data survives the reboot, when the encryption is re-initialised. If you are experienced with LVM, you will be able to ignore/replace LVM and other specifics according to your plan.<br />
<br />
If you want to span a logical volume over multiple disks that have already been set up, or expand the logical volume for {{ic|/home}} (or any other volume), a procedure to do so is described in [[dm-crypt/Specialties#Expanding LVM on multiple disks]]. It is important to note that the LUKS encrypted container has to be resized as well.<br />
<br />
{{Expansion|The intro of this scenario needs some adjustment now that a comparison has been added to [[#Overview]]. A suggested structure is to make it similar to the [[#LUKS on a partition]] intro.}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Partitioning scheme:<br />
<br />
{{Text art|<nowiki><br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
| Boot partition | dm-crypt plain encrypted volume | LUKS2 encrypted volume | LUKS2 encrypted volume |<br />
| | | | |<br />
| /boot | [SWAP] | / | /home |<br />
| | | | |<br />
| | /dev/mapper/swap | /dev/mapper/root | /dev/mapper/home |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | /dev/MyVolGroup/cryptswap | /dev/MyVolGroup/cryptroot | /dev/MyVolGroup/crypthome |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | |<br />
| /dev/sda1 | /dev/sda2 |<br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
Randomise {{ic|/dev/sda2}} according to [[dm-crypt/Drive preparation#dm-crypt wipe on an empty disk or partition]].<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
# pvcreate /dev/sda2<br />
# vgcreate MyVolGroup /dev/sda2<br />
# lvcreate -L 32G -n cryptroot MyVolGroup<br />
# lvcreate -L 500M -n cryptswap MyVolGroup<br />
# lvcreate -L 500M -n crypttmp MyVolGroup<br />
# lvcreate -l 100%FREE -n crypthome MyVolGroup<br />
<br />
# cryptsetup luksFormat /dev/MyVolGroup/cryptroot<br />
# cryptsetup open /dev/MyVolGroup/cryptroot root<br />
# mkfs.ext4 /dev/mapper/root<br />
# mount /dev/mapper/root /mnt<br />
<br />
More information about the encryption options can be found in [[dm-crypt/Device encryption#Encryption options for LUKS mode]].<br />
Note that {{ic|/home}} will be encrypted in [[#Encrypting logical volume /home]].<br />
<br />
{{Tip|If you ever have to access the encrypted root from the Arch-ISO, the above {{ic|open}} action will allow you to after the [[LVM#Logical Volumes do not show up|LVM shows up]].}}<br />
<br />
=== Preparing the boot partition ===<br />
<br />
# dd if=/dev/zero of=/dev/sda1 bs=1M status=progress<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|lvm2}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''lvm2''' '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':root root=/dev/mapper/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=root root=/dev/mapper/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/MyVolGroup/cryptroot}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
=== Configuring fstab and crypttab ===<br />
<br />
Both [[crypttab]] and [[fstab]] entries are required to both unlock the device and mount the filesystems, respectively. The following lines will re-encrypt the temporary filesystems on each reboot:<br />
<br />
{{hc|/etc/crypttab|2=<br />
swap /dev/MyVolGroup/cryptswap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
tmp /dev/MyVolGroup/crypttmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/root / ext4 defaults 0 1<br />
/dev/sda1 /boot ext4 defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
}}<br />
<br />
=== Encrypting logical volume /home ===<br />
<br />
Since this scenario uses LVM as the primary and dm-crypt as secondary mapper, each encrypted logical volume requires its own encryption. Yet, unlike the temporary filesystems configured with volatile encryption above, the logical volume for {{ic|/home}} should of course be persistent. The following assumes you have rebooted into the installed system, otherwise you have to adjust paths.<br />
To save on entering a second passphrase at boot, a [[dm-crypt/Device encryption#Keyfiles|keyfile]] is created:<br />
<br />
# mkdir -m 700 /etc/luks-keys<br />
# dd if=/dev/random of=/etc/luks-keys/home bs=1 count=256 status=progress<br />
<br />
The logical volume is encrypted with it:<br />
<br />
# cryptsetup luksFormat -v /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
# cryptsetup -d /etc/luks-keys/home open /dev/MyVolGroup/crypthome home<br />
# mkfs.ext4 /dev/mapper/home<br />
# mount /dev/mapper/home /home<br />
<br />
The encrypted mount is configured in both [[crypttab]] and [[fstab]]:<br />
<br />
{{hc|/etc/crypttab|<br />
home /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home /home ext4 defaults 0 2<br />
}}<br />
<br />
== LUKS on software RAID ==<br />
<br />
This example is based on a real-world setup for a workstation class laptop equipped with two SSDs of equal size, and an additional HDD for bulk storage. The end result is LUKS1 based full disk encryption (including {{ic|/boot}}) for all drives, with the SSDs in a [[RAID|RAID0]] array, and keyfiles used to unlock all encryption after [[GRUB]] is given a correct passphrase at boot.<br />
<br />
This setup utilizes a very simplistic partitioning scheme, with all the available RAID storage being mounted at {{ic|/}} (no separate {{ic|/boot}} partition), and the decrypted HDD being mounted at {{ic|/data}}.<br />
<br />
Please note that regular [[System backup|backups]] are very important in this setup. If either of the SSDs fail, the data contained in the RAID array will be practically impossible to recover. You may wish to select a different [[RAID#Standard RAID levels|RAID level]] if fault tolerance is important to you. <br />
<br />
The encryption is not deniable in this setup.<br />
<br />
For the sake of the instructions below, the following block devices are used:<br />
<br />
/dev/sda = first SSD<br />
/dev/sdb = second SSD<br />
/dev/sdc = HDD<br />
<br />
{{Text art|<nowiki><br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
| BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | LUKS2 encrypted volume |<br />
| | | | | | | | | |<br />
| | /efi | / | | | /efi | / | | /data |<br />
| | | | | | | | | |<br />
| | | /dev/mapper/cryptroot | | | | /dev/mapper/cryptroot | | |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ | |<br />
| | RAID1 array (part 1 of 2) | RAID0 array (part 1 of 2) | | | RAID1 array (part 2 of 2) | RAID0 array (part 2 of 2) | | |<br />
| | | | | | | | | |<br />
| | /dev/md/ESP | /dev/md/root | | | /dev/md/ESP | /dev/md/root | | /dev/mapper/cryptroot |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ +---------------------------+<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 | | /dev/sdb1 | /dev/sdb2 | /dev/sdb3 | | /dev/sdc1 |<br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
</nowiki>}}<br />
<br />
Be sure to substitute them with the appropriate device designations for your setup, as they may be different.<br />
<br />
=== Preparing the disks ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] with GPT, create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
In the remaining space on the drive create a partition ({{ic|/dev/sda3}} in this example) for "Linux RAID". Choose partition type ID {{ic|fd}} for MBR or partition type GUID {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} for GPT.<br />
<br />
Once partitions have been created on {{ic|/dev/sda}}, the following commands can be used to clone them to {{ic|/dev/sdb}}.<br />
<br />
# sfdisk -d /dev/sda > sda.dump<br />
# sfdisk /dev/sdb < sda.dump<br />
<br />
The HDD is prepared with a single Linux partition covering the whole drive at {{ic|/dev/sdc1}}.<br />
<br />
=== Building the RAID array ===<br />
<br />
Create the RAID array for the SSDs.<br />
<br />
{{Note|<br />
* All parts of an EFI system partition RAID array must be individually usable, that means that ESP can only placed in a RAID1 array.<br />
* The RAID superblock must be placed at the end of the EFI system partition using {{ic|1=--metadata=1.0}}, otherwise the firmware will not be able to access the partition.<br />
}}<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.0 --raid-devices=2 /dev/md/ESP /dev/sda2 /dev/sdb2<br />
<br />
This example utilizes RAID0 for root, you may wish to substitute a different level based on your preferences or requirements.<br />
<br />
# mdadm --create --verbose --level=0 --metadata=1.2 --raid-devices=2 /dev/md/root /dev/sda3 /dev/sdb3<br />
<br />
=== Preparing the block devices ===<br />
<br />
As explained in [[dm-crypt/Drive preparation]], the devices are wiped with random data utilizing {{ic|/dev/zero}} and a crypt device with a random key. Alternatively, you could use {{ic|dd}} with {{ic|/dev/random}} or {{ic|/dev/urandom}}, though it will be much slower.<br />
<br />
# cryptsetup open --type plain /dev/md/root container --key-file /dev/random<br />
# dd if=/dev/zero of=/dev/mapper/container bs=1M status=progress<br />
# cryptsetup close container<br />
<br />
And repeat above for the HDD ({{ic|/dev/sdc1}} in this example).<br />
<br />
Set up encryption for {{ic|/dev/md/root}}:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup -y -v luksFormat --type luks1 /dev/md/root<br />
# cryptsetup open /dev/md/root cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
And repeat for the HDD:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sdc1<br />
# cryptsetup open /dev/sdc1 cryptdata<br />
# mkfs.ext4 /dev/mapper/cryptdata<br />
# mkdir /mnt/data<br />
# mount /dev/mapper/cryptdata /mnt/data<br />
<br />
For UEFI systems, set up the EFI system partition:<br />
<br />
# mkfs.fat -F32 /dev/md/ESP<br />
# mount /dev/md/ESP /mnt/efi<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure [[GRUB]] for the LUKS1 encrypted system by editing {{ic|/etc/default/grub}} with the following:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/md/root:cryptroot"<br />
GRUB_ENABLE_CRYPTODISK=y<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details.<br />
<br />
Complete the GRUB install to both SSDs (in reality, installing only to {{ic|/dev/sda}} will work).<br />
<br />
# grub-install --target=i386-pc /dev/sda<br />
# grub-install --target=i386-pc /dev/sdb<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Creating the keyfiles ===<br />
<br />
The next steps save you from entering your passphrase twice when you boot the system (once so GRUB can unlock the LUKS1 device, and second time once the initramfs assumes control of the system). This is done by creating a [[dm-crypt/Device encryption#Keyfiles|keyfile]] for the encryption and adding it to the initramfs image to allow the encrypt hook to unlock the root device. See [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] for details.<br />
<br />
* Create the [[dm-crypt/Device encryption#Keyfiles|keyfile]] and add the key to {{ic|/dev/md/root}}.<br />
* Create another keyfile for the HDD ({{ic|/dev/sdc1}}) so it can also be unlocked at boot. For convenience, leave the passphrase created above in place as this can make recovery easier if you ever need it. Edit {{ic|/etc/crypttab}} to decrypt the HDD at boot. See [[Dm-crypt/System configuration#Unlocking with a keyfile]].<br />
<br />
=== Configuring the system ===<br />
<br />
Edit [[fstab]] to mount the cryptroot and cryptdata block devices and the ESP:<br />
<br />
/dev/mapper/cryptroot / ext4 rw,noatime 0 1<br />
/dev/mapper/cryptdata /data ext4 defaults 0 2<br />
/dev/md/ESP /efi vfat rw,relatime,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,tz=UTC,errors=remount-ro 0 2<br />
<br />
Save the RAID configuration:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
Edit [[mkinitcpio.conf]] to include your keyfile and add the proper hooks:<br />
<br />
FILES=(/crypto_keyfile.bin)<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''mdadm_udev''' '''encrypt''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details.<br />
<br />
== Plain dm-crypt ==<br />
<br />
Contrary to LUKS, dm-crypt ''plain'' mode does not require a header on the encrypted device: this scenario exploits this feature to set up a system on an unpartitioned, encrypted disk that will be indistinguishable from a disk filled with random data, which could allow [[Wikipedia:Deniable encryption|deniable encryption]]. See also [[wikipedia:Disk encryption#Full disk encryption]].<br />
<br />
Note that if full-disk encryption is not required, the methods using LUKS described in the sections above are better options for both system encryption and encrypted partitions. LUKS features like key management with multiple passphrases/key-files or re-encrypting a device in-place are unavailable with ''plain'' mode.<br />
<br />
''Plain'' dm-crypt encryption can be more resilient to damage than LUKS, because it does not rely on an encryption master-key which can be a single-point of failure if damaged. However, using ''plain'' mode also requires more manual configuration of encryption options to achieve the same cryptographic strength. See also [[Disk encryption#Cryptographic metadata]]. Using ''plain'' mode could also be considered if concerned with the problems explained in [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]].<br />
<br />
{{Tip|If headerless encryption is your goal but you are unsure about the lack of key-derivation with ''plain'' mode, then two alternatives are:<br />
* [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|dm-crypt LUKS mode with a detached header]] by using the ''cryptsetup'' {{ic|--header}} option. It cannot be used with the standard ''encrypt'' hook, but the hook may be modified.<br />
* [[tcplay]] which offers headerless encryption but with the PBKDF2 function.<br />
}}<br />
<br />
The scenario uses two USB sticks:<br />
<br />
* one for the boot device, which also allows storing the options required to open/unlock the plain encrypted device in the boot loader configuration, since typing them on each boot would be error prone;<br />
* another for the encryption key file, assuming it stored as raw bits so that to the eyes of an unaware attacker who might get the usbkey the encryption key will appear as random data instead of being visible as a normal file. See also [[Wikipedia:Security through obscurity]], follow [[dm-crypt/Device encryption#Keyfiles]] to prepare the keyfile.<br />
<br />
The disk layout is:<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+ +----------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot device | | Encryption key |<br />
| | | | | | | file storage |<br />
| / | [SWAP] | /home | | /boot | | (unpartitioned |<br />
| | | | | | | in example) |<br />
| /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home | | /dev/sdb1 | | /dev/sdc |<br />
|----------------------+----------------------+----------------------| |----------------| |----------------|<br />
| disk drive /dev/sda encrypted using plain mode and LVM | | USB stick 1 | | USB stick 2 |<br />
+--------------------------------------------------------------------+ +----------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* It is also possible to use a single USB key physical device:<br />
** By putting the key on another partition (/dev/sdb2) of the USB storage device (/dev/sdb).<br />
** By copying the keyfile to the initramfs directly. An example keyfile {{ic|/etc/keyfile}} gets copied to the initramfs image by setting {{ic|1=FILES=(/etc/keyfile)}} in {{ic|/etc/mkinitcpio.conf}}. The way to instruct the {{ic|encrypt}} hook to read the keyfile in the initramfs image is using {{ic|rootfs:}} prefix before the filename, e.g. {{ic|1=cryptkey=rootfs:/etc/keyfile}}.<br />
* Another option is using a passphrase with good [[Disk encryption#Choosing a strong passphrase|entropy]].<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
It is vital that the mapped device is filled with random data. In particular this applies to the scenario use case we apply here.<br />
<br />
See [[dm-crypt/Drive preparation]] and [[dm-crypt/Drive preparation#dm-crypt specific methods]]<br />
<br />
=== Preparing the non-boot partitions ===<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for plain mode]] for details.<br />
<br />
Using the device {{ic|/dev/sda}}, with the aes-xts cipher with a 512 bit key size and using a keyfile we have the following options for this scenario:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sdc --key-size=512 open --type plain /dev/sda cryptlvm<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, and key file details.<br />
<br />
We can now check a mapping entry has been made for {{ic|/dev/mapper/cryptlvm}}:<br />
<br />
# fdisk -l<br />
<br />
{{Tip|A simpler alternative to using LVM, advocated in the cryptsetup FAQ for cases where LVM is not necessary, is to just create a filesystem on the entirety of the mapped dm-crypt device.}} <br />
<br />
Next, we setup [[LVM]] logical volumes on the mapped device. See [[LVM#Installing Arch Linux on LVM]] for further details:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -L 10G MyVolGroup -n swap<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
We format and mount them and activate swap. See [[File systems#Create a file system]] for further details:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# mkswap /dev/MyVolGroup/swap<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The {{ic|/boot}} partition can be installed on the standard vfat partition of a USB stick, if required. But if manual partitioning is needed, then a small 200 MiB partition is all that is required. Create the partition using a [[Partitioning#Partitioning tools|partitioning tool]] of your choice.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}, if it is not already formatted as vfat:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
# mkdir /mnt/boot<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to boot the encrypted root partition, the following [[kernel parameters]] need to be set by the boot loader (note that 64 is the number of bytes in 512 bits):<br />
<br />
cryptdevice=/dev/disk/by-id/''disk-ID-of-sda'':cryptlvm cryptkey=/dev/disk/by-id/''disk-ID-of-sdc'':0:64 crypto=:aes-xts-plain64:512:0:<br />
<br />
The {{ic|''disk-ID-of-'''disk'''''}} refers to the id of the referenced disk. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details and other parameters that you may need.<br />
<br />
{{Tip|If using GRUB, you can install it on the same USB as the {{ic|/boot}} partition with:<br />
<br />
# grub-install --recheck /dev/sdb<br />
<br />
}}<br />
<br />
=== Post-installation ===<br />
<br />
You may wish to remove the USB sticks after booting. Since the {{ic|/boot}} partition is not usually needed, the {{ic|noauto}} option can be added to the relevant line in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
# /dev/sdb1<br />
/dev/sdb1 /boot ext4 '''noauto''',rw,noatime 0 2<br />
}}<br />
<br />
However, when an update to anything used in the initramfs, or a kernel, or the bootloader is required; the {{ic|/boot}} partition must be present and mounted. As the entry in {{ic|fstab}} already exists, it can be mounted simply with:<br />
<br />
# mount /boot<br />
<br />
== Encrypted boot partition (GRUB) ==<br />
<br />
This setup utilizes the same partition layout and configuration for the system's root partition as the previous [[#LVM on LUKS]] section, with the difference that a special feature of the [[GRUB]] bootloader is used to additionally encrypt the boot directory {{ic|/boot}}. See also [[GRUB#Encrypted /boot]].<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+---------------------+----------------------+----------------------+----------------------+----------------------+<br />
| BIOS boot partition | EFI system partition | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | | | | |<br />
| | /efi | / | [SWAP] | /home |<br />
| | | | | |<br />
| | | /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home |<br />
| /dev/sda1 | /dev/sda2 |----------------------+----------------------+----------------------+<br />
| unencrypted | unencrypted | /dev/sda3 encrypted using LVM on LUKS1 |<br />
+---------------------+----------------------+--------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* All scenarios are intended as examples. It is, of course, possible to apply both of the two above distinct installation steps with the other scenarios as well. See also the variants linked in [[#LVM on LUKS]].<br />
* You can use {{ic|cryptboot}} script from {{AUR|cryptboot}} package for simplified encrypted boot management (mounting, unmounting, upgrading packages) and as a defense against [https://www.schneier.com/blog/archives/2009/10/evil_maid_attac.html Evil Maid] attacks with [[Secure Boot#Using your own keys|UEFI Secure Boot]]. For more information and limitations see [https://github.com/xmikos/cryptboot cryptboot project] page.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
Create a partition of type {{ic|8309}}, which will later contain the encrypted container for the LVM.<br />
<br />
Create the LUKS encrypted container:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup luksFormat --type luks1 /dev/sda3<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Your partition layout should look similar to this:<br />
<br />
{{hc|# gdisk -l /dev/sda|<br />
...<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 4095 1024.0 KiB EF02 BIOS boot partition<br />
2 4096 1130495 550.0 MiB EF00 EFI System<br />
3 1130496 68239360 32.0 GiB 8309 Linux LUKS<br />
}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda3 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
The LVM logical volumes of this example follow the exact layout as the [[#LVM on LUKS]] scenario. Therefore, please follow [[#Preparing the logical volumes]] above and adjust as required.<br />
<br />
If you plan to boot in UEFI mode, create a mountpoint for the [[EFI system partition]] at {{ic|/efi}} for compatibility with {{ic|grub-install}} and mount it:<br />
<br />
# mkdir /mnt/efi<br />
# mount /dev/sda2 /mnt/efi<br />
<br />
At this point, you should have the following partitions and logical volumes inside of {{ic|/mnt}}:<br />
<br />
{{hc|$ lsblk|<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 200G 0 disk<br />
├─sda1 8:1 0 1M 0 part<br />
├─sda2 8:2 0 550M 0 part /mnt/efi<br />
└─sda3 8:3 0 100G 0 part<br />
└─cryptlvm 254:0 0 100G 0 crypt<br />
├─MyVolGroup-swap 254:1 0 8G 0 lvm [SWAP]<br />
├─MyVolGroup-root 254:2 0 32G 0 lvm /mnt<br />
└─MyVolGroup-home 254:3 0 60G 0 lvm /mnt/home<br />
}}<br />
<br />
The following steps assume that you have a functional arch installation on MyVolGroup-root (restore from backup, etc.) and have [[chroot]]ed to it. E.g.:<br />
<br />
# arch-chroot /mnt<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure GRUB to allow booting from {{ic|/boot}} on a LUKS1 encrypted partition:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_ENABLE_CRYPTODISK=y<br />
}}<br />
<br />
Set the kernel parameters, so that the initramfs can unlock the encrypted root partition. Using the {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... cryptdevice=UUID=''device-UUID'':cryptlvm ..."<br />
}}<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... rd.luks.name=''device-UUID''=cryptlvm ..."<br />
}}<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details. The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda3}} (the partition which holds the lvm containing the root filesystem). See [[Persistent block device naming]].<br />
<br />
[[GRUB#Installation_2|install GRUB]] to the mounted ESP for UEFI booting:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB --recheck<br />
<br />
[[GRUB#Installation|install GRUB]] to the disk for BIOS booting:<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
<br />
Generate GRUB's [[GRUB#Generate the main configuration file|configuration]] file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If all commands finished without errors, GRUB should prompt for the passphrase to unlock the {{ic|/dev/sda3}} partition after the next reboot.<br />
<br />
=== Avoiding having to enter the passphrase twice ===<br />
<br />
{{Merge|Dm-crypt/Device encryption#With a keyfile embedded in the initramfs|Too much duplicated content, too much detail here for this overview page.|section=Security Issue with Grub Keyfile}}<br />
<br />
While GRUB asks for a passphrase to unlock the LUKS1 encrypted partition after above instructions, the partition unlock is not passed on to the initramfs. Hence, you have to enter the passphrase twice at boot: once for GRUB and once for the initramfs.<br />
<br />
This section deals with extra configuration to let the system boot by only entering the passphrase once, in GRUB. This is accomplished by [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs|with a keyfile embedded in the initramfs]].<br />
<br />
First create a keyfile and add it as LUKS key:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/root/cryptlvm.keyfile iflag=fullblock<br />
# chmod 000 /root/cryptlvm.keyfile<br />
# chmod 600 /boot/initramfs-linux*<br />
# cryptsetup -v luksAddKey /dev/sda3 /root/cryptlvm.keyfile<br />
<br />
Add the keyfile to the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/root/cryptlvm.keyfile)<br />
}}<br />
<br />
Set the following kernel parameters to unlock the LUKS partition with the keyfile. Using the {{ic|encrypt}} hook:<br />
<br />
GRUB_CMDLINE_LINUX="... cryptkey=rootfs:/root/cryptlvm.keyfile"<br />
<br />
Or, using the [[sd-encrypt]] hook:<br />
<br />
GRUB_CMDLINE_LINUX="... rd.luks.key=''device-UUID''=/root/cryptlvm.keyfile"<br />
<br />
If for some reason the keyfile fails to unlock the boot partition, systemd will fallback to ask for a passphrase to unlock and, in case that is correct, continue booting.<br />
<br />
{{Tip|If you want to encrypt the {{ic|/boot}} partition to protect against offline tampering threats, the [[dm-crypt/Specialties#mkinitcpio-chkcryptoboot|mkinitcpio-chkcryptoboot]] hook has been contributed to help.}}<br />
<br />
== Btrfs subvolumes with swap ==<br />
<br />
The following example creates a full system encryption with LUKS1 using [[Btrfs]] subvolumes to [[Btrfs#Mounting subvolumes|simulate partitions]].<br />
<br />
If using UEFI, an [[EFI system partition]] (ESP) is required. {{ic|/boot}} itself may reside on {{ic|/}} and be encrypted; however, the ESP itself cannot be encrypted. In this example layout, the ESP is {{ic|/dev/sda1}} and is mounted at {{ic|/efi}}. {{ic|/boot}} itself is located on the system partition, {{ic|/dev/sda2}}.<br />
<br />
Since {{ic|/boot}} resides on the LUKS1 encrypted {{ic|/}}, [[GRUB]] must be used as the bootloader because only GRUB can load modules necessary to decrypt {{ic|/boot}} (e.g., crypto.mod, cryptodisk.mod and luks.mod).<br />
<br />
Additionally an optional plain-encrypted [[swap]] partition is shown.<br />
<br />
{{Warning|Do not use a [[swap file]] instead of a separate partition on Linux kernels before v5.0, because this may result in data loss. See [[Btrfs#Swap file]].}}<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+<br />
| EFI system partition | System partition | Swap partition |<br />
| unencrypted | LUKS1-encrypted | plain-encrypted |<br />
| | | |<br />
| /efi | / | [SWAP] |<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 |<br />
|----------------------+----------------------+----------------------+<br />
</nowiki>}}<br />
<br />
=== Preparing the disk ===<br />
<br />
{{Note|It is not possible to use btrfs partitioning as described in [[Btrfs#Partitionless Btrfs disk]] when using LUKS. Traditional partitioning must be used, even if it is just to create one partition.}}<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]]. If you are using [[UEFI]] create an [[EFI system partition]] with an appropriate size. It will later be mounted at {{ic|/efi}}. If you are going to create an encrypted swap partition, create the partition for it, but do '''not''' mark it as swap, since plain ''dm-crypt'' will be used with the partition.<br />
<br />
Create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}). See the [[Partitioning]] article.<br />
<br />
=== Preparing the system partition ===<br />
<br />
==== Create LUKS container ====<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
Follow [[dm-crypt/Device encryption#Encrypting devices with LUKS mode]] to setup {{ic|/dev/sda2}} for LUKS. See the [[dm-crypt/Device encryption#Encryption options for LUKS mode]] before doing so for a list of encryption options.<br />
<br />
==== Unlock LUKS container ====<br />
<br />
Now follow [[dm-crypt/Device encryption#Unlocking/Mapping LUKS partitions with the device mapper]] to unlock the LUKS container and map it.<br />
<br />
==== Format mapped device ====<br />
<br />
Proceed to format the mapped device as described in [[Btrfs#File system on a single device]], where {{ic|''/dev/partition''}} is the name of the mapped device (i.e., {{ic|cryptroot}}) and '''not''' {{ic|/dev/sda2}}.<br />
<br />
==== Mount mapped device ====<br />
<br />
Finally, [[mount]] the now-formatted mapped device (i.e., {{ic|/dev/mapper/cryptroot}}) to {{ic|/mnt}}.<br />
<br />
{{Tip|You may want to use the {{ic|1=compress=lzo}} mount option. See [[Btrfs#Compression]] for more information.}}<br />
<br />
=== Creating btrfs subvolumes ===<br />
<br />
{{Merge|Btrfs|The subvolume layout is not specific to an encrypted system.}}<br />
<br />
==== Layout ====<br />
<br />
[[Btrfs#Subvolumes|Subvolumes]] will be used to simulate partitions, but other (nested) subvolumes will also be created. Here is a partial representation of what the following example will generate:<br />
<br />
{{Text art|<nowiki><br />
subvolid=5 (/dev/sda2)<br />
|<br />
├── @ (mounted as /)<br />
| |<br />
| ├── /bin (directory)<br />
| |<br />
| ├── /home (mounted @home subvolume)<br />
| |<br />
| ├── /usr (directory)<br />
| |<br />
| ├── /.snapshots (mounted @snapshots subvolume)<br />
| |<br />
| ├── /var/cache/pacman/pkg (nested subvolume)<br />
| |<br />
| ├── ... (other directories and nested subvolumes)<br />
|<br />
├── @snapshots (mounted as /.snapshots)<br />
|<br />
├── @home (mounted as /home)<br />
|<br />
└── @... (additional subvolumes you wish to use as mount points)<br />
</nowiki>}}<br />
<br />
This section follows the [[Snapper#Suggested filesystem layout]], which is most useful when used with [[Snapper]]. You should also consult [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs Wiki SysadminGuide#Layout].<br />
<br />
==== Create top-level subvolumes ====<br />
<br />
Here we are using the convention of prefixing {{ic|@}} to subvolume names that will be used as mount points, and {{ic|@}} will be the subvolume that is mounted as {{ic|/}}.<br />
<br />
Following the [[Btrfs#Creating a subvolume]] article, create subvolumes at {{ic|/mnt/@}}, {{ic|/mnt/@snapshots}}, and {{ic|/mnt/@home}}.<br />
<br />
Create any additional subvolumes you wish to use as mount points now.<br />
<br />
==== Mount top-level subvolumes ====<br />
<br />
Unmount the system partition at {{ic|/mnt}}.<br />
<br />
Now mount the newly created {{ic|@}} subvolume which will serve as {{ic|/}} to {{ic|/mnt}} using the {{ic|1=subvol=}} mount option. Assuming the mapped device is named {{ic|cryptroot}}, the command would look like:<br />
<br />
# mount -o compress=lzo,subvol=@ /dev/mapper/cryptroot /mnt<br />
<br />
See [[Btrfs#Mounting subvolumes]] for more details.<br />
<br />
Also mount the other subvolumes to their respective mount points: {{ic|@home}} to {{ic|/mnt/home}} and {{ic|@snapshots}} to {{ic|/mnt/.snapshots}}.<br />
<br />
==== Create nested subvolumes ====<br />
<br />
Create any subvolumes you do '''not''' want to have snapshots of when taking a snapshot of {{ic|/}}. For example, you probably do not want to take snapshots of {{ic|/var/cache/pacman/pkg}}. These subvolumes will be nested under the {{ic|@}} subvolume, but just as easily could have been created earlier at the same level as {{ic|@}} according to your preference.<br />
<br />
Since the {{ic|@}} subvolume is mounted at {{ic|/mnt}} you will need to [[create a subvolume]] at {{ic|/mnt/var/cache/pacman/pkg}} for this example. You may have to create any parent directories first.<br />
<br />
Other directories you may wish to do this with are {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.<br />
<br />
==== Mount ESP ====<br />
<br />
If you prepared an EFI system partition earlier, create its mount point and mount it now.<br />
<br />
{{Note|Btrfs snapshots will exclude {{ic|/efi}}, since it is not a btrfs file system.}}<br />
<br />
At the [[Installation guide#Install the base packages|pacstrap]] installation step, the {{Pkg|btrfs-progs}} must be installed in addition to the base group.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
==== Create keyfile ====<br />
<br />
In order for GRUB to open the LUKS partition without having the user enter his passphrase twice, we will use a keyfile embedded in the initramfs. Follow [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] making sure to add the key to {{ic|/dev/sda2}} at the ''luksAddKey'' step.<br />
<br />
==== Edit mkinitcpio.conf ====<br />
<br />
After creating, adding, and embedding the key as described above, add the {{ic|encrypt}} hook to [[mkinitcpio.conf]] as well as any other hooks you require. See [[dm-crypt/System configuration#mkinitcpio]] for detailed information.<br />
<br />
{{Tip|You may want to add {{ic|1=BINARIES=(/usr/bin/btrfs)}} to your {{ic|mkinitcpio.conf}}. See the [[Btrfs#Corruption recovery]] article.}}<br />
<br />
=== Configuring the boot loader ===<br />
<br />
Install [[GRUB]] to {{ic|/dev/sda}}. Then, edit {{ic|/etc/default/grub}} as instructed in the [[GRUB#Additional arguments]] and [[GRUB#Encrypted /boot]], following both the instructions for an encrypted root and boot partition. Finally, generate the GRUB configuration file.<br />
<br />
=== Configuring swap ===<br />
<br />
If you created a partition to be used for encrypted swap, now is the time to configure it. Follow the instructions at [[dm-crypt/Swap encryption]].</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=580944Dm-crypt/Encrypting an entire system2019-08-25T15:58:18Z<p>EasyToRemember: /* Preparing the logical volumes */ Adding info about 'chroot' so that the subsequent steps make sense.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[Category:Installation process]]<br />
[[de:Systemverschlüsselung mit dm-crypt]]<br />
[[es:Dm-crypt/Encrypting an entire system]]<br />
[[ja:Dm-crypt/システム全体の暗号化]]<br />
[[pl:Dm-crypt/Encrypting an entire system]]<br />
<br />
The following are examples of common scenarios of full system encryption with ''dm-crypt''. They explain all the adaptations that need to be done to the normal [[Installation guide|installation procedure]]. All the necessary tools are on the [https://www.archlinux.org/download/ installation image].<br />
<br />
== Overview ==<br />
<br />
Securing a root filesystem is where ''dm-crypt'' excels, feature and performance-wise. Unlike selectively encrypting non-root filesystems, an encrypted root filesystem can conceal information such as which programs are installed, the usernames of all user accounts, and common data-leakage vectors such as [[mlocate]] and {{ic|/var/log/}}. Furthermore, an encrypted root filesystem makes tampering with the system far more difficult, as everything except the [[boot loader]] and (usually) the kernel is encrypted.<br />
<br />
All scenarios illustrated in the following share these advantages, other pros and cons differentiating them are summarized below:<br />
<br />
{| class="wikitable"<br />
! Scenarios<br />
! Advantages<br />
! Disadvantages<br />
|----------------------------------------------------------<br />
| [[#LUKS on a partition]]<br />
shows a basic and straight-forward set-up for a fully LUKS encrypted root.<br />
|<br />
* Simple partitioning and setup<br />
|<br />
* Inflexible; disk-space to be encrypted has to be pre-allocated<br />
|----------------------------------------------------------<br />
| [[#LVM on LUKS]]<br />
achieves partitioning flexibility by using LVM inside a single LUKS encrypted partition.<br />
|<br />
* Simple partitioning with knowledge of LVM<br />
* Only one key required to unlock all volumes (e.g. easy resume-from-disk setup)<br />
* Volume layout not transparent when locked<br />
* Easiest method to allow [[dm-crypt/Swap encryption#With suspend-to-disk support|suspension to disk]]<br />
|<br />
* LVM adds an additional mapping layer and hook<br />
* Less useful, if a singular volume should receive a separate key<br />
|----------------------------------------------------------<br />
| [[#LUKS on LVM]]<br />
uses dm-crypt only after the LVM is setup.<br />
|<br />
* LVM can be used to have encrypted volumes span multiple disks<br />
* Easy mix of un-/encrypted volume groups<br />
|<br />
* Complex; changing volumes requires changing encryption mappers too<br />
* Volumes require individual keys<br />
* LVM layout is transparent when locked<br />
|----------------------------------------------------------<br />
| [[#LUKS on software RAID]]<br />
uses dm-crypt only after RAID is setup.<br />
|<br />
* Analogous to LUKS on LVM<br />
|<br />
* Analogous to LUKS on LVM<br />
|----------------------------------------------------------<br />
| [[#Plain dm-crypt]]<br />
uses dm-crypt plain mode, i.e. without a LUKS header and its options for multiple keys. <br>This scenario also employs USB devices for {{ic|/boot}} and key storage, which may be applied to the other scenarios.<br />
|<br />
* Data resilience for cases where a LUKS header may be damaged<br />
* Allows [[Wikipedia:Disk encryption#Full disk encryption|Full Disk Encryption]]<br />
* Helps addressing [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)|problems]] with SSDs<br />
|<br />
* High care to all encryption parameters is required<br />
* Single encryption key and no option to change it<br />
|----------------------------------------------------------<br />
| [[#Encrypted boot partition (GRUB)]]<br />
shows how to encrypt the boot partition using the GRUB bootloader. <br> This scenario also employs an EFI system partition, which may be applied to the other scenarios.<br />
|<br />
* Same advantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* Less data is left unencrypted, i.e. the boot loader and the EFI system partition, if present<br />
|<br />
* Same disadvantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* More complicated configuration<br />
* Not supported by other boot loaders<br />
|----------------------------------------------------------<br />
| [[#Btrfs subvolumes with swap]]<br />
shows how to encrypt a [[Btrfs]] system, including the {{ic|/boot}} directory, also adding a partition for swap, on UEFI hardware.<br />
|<br />
* Similar advantages as [[#Encrypted boot partition (GRUB)]]<br />
* Availability of Btrfs' features<br />
|<br />
* Similar disadvantages as [[#Encrypted boot partition (GRUB)]]<br />
|}<br />
<br />
While all above scenarios provide much greater protection from outside threats than encrypted secondary filesystems, they also share a common disadvantage: any user in possession of the encryption key is able to decrypt the entire drive, and therefore can access other users' data. If that is of concern, it is possible to use a combination of blockdevice and stacked filesystem encryption and reap the advantages of both. See [[Disk encryption]] to plan ahead.<br />
<br />
See [[dm-crypt/Drive preparation#Partitioning]] for a general overview of the partitioning strategies used in the scenarios.<br />
<br />
Another area to consider is whether to set up an encrypted swap partition and what kind. See [[dm-crypt/Swap encryption]] for alternatives.<br />
<br />
If you anticipate to protect the system's data not only against physical theft, but also have a requirement of precautions against logical tampering, see [[dm-crypt/Specialties#Securing the unencrypted boot partition]] for further possibilities after following one of the scenarios.<br />
<br />
For [[solid state drive]]s you might want to consider enabling TRIM support, but be warned, there are potential security implications. See [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]] for more information.<br />
<br />
{{Warning|<br />
* In any scenario, never use file system repair software such as [[fsck]] directly on an encrypted volume, or it will destroy any means to recover the key used to decrypt your files. Such tools must be used on the decrypted (opened) device instead.<br />
* For the LUKS2 format:<br />
** [[GRUB]] does not support LUKS2.[https://savannah.gnu.org/bugs/?55093] Use LUKS1 on partitions that GRUB needs to access.<br />
** The LUKS2 format has a high RAM usage per design, defaulting to 1GB per encrypted mapper. Machines with low RAM and/or multiple LUKS2 partitions unlocked in parallel may error on boot. See the {{ic|--pbkdf-memory}} option to control memory usage.[https://gitlab.com/cryptsetup/cryptsetup/issues/372]<br />
}}<br />
<br />
== LUKS on a partition ==<br />
<br />
This example covers a full system encryption with ''dm-crypt'' + LUKS in a simple partition layout:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------+------------------------+-----------------------+<br />
| Boot partition | LUKS2 encrypted system | Optional free space |<br />
| | partition | for additional |<br />
| | | partitions or swap |<br />
| /boot | / | to be setup later |<br />
| | | |<br />
| | /dev/mapper/cryptroot | |<br />
| |------------------------| |<br />
| /dev/sda1 | /dev/sda2 | |<br />
+-----------------------+------------------------+-----------------------+<br />
</nowiki>}}<br />
<br />
The first steps can be performed directly after booting the Arch Linux install image.<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
Then create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}) and {{ic|/boot}} ({{ic|/dev/sda1}}). See [[Partitioning]].<br />
<br />
=== Preparing non-boot partitions ===<br />
<br />
The following commands create and mount the encrypted root partition. They correspond to the procedure described in detail in [[dm-crypt/Encrypting a non-root file system#Partition]] (which, despite the title, ''can'' be applied to root partitions, as long as [[#Configuring mkinitcpio|mkinitcpio]] and the [[#Configuring the boot loader|boot loader]] are correctly configured).<br />
If you want to use particular non-default encryption options (e.g. cipher, key length), see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|encryption options]] before executing the first command:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sda2<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
Check the mapping works as intended:<br />
<br />
# umount /mnt<br />
# cryptsetup close cryptroot<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
If you created separate partitions (e.g. {{ic|/home}}), these steps have to be adapted and repeated for all of them, ''except'' for {{ic|/boot}}. See [[dm-crypt/Encrypting a non-root file system#Automated unlocking and mounting]] on how to handle additional partitions at boot.<br />
<br />
Note that each blockdevice requires its own passphrase. This may be inconvenient, because it results in a separate passphrase to be input during boot. An alternative is to use a keyfile stored in the system partition to unlock the separate partition via {{ic|crypttab}}. See [[dm-crypt/Device encryption#Using LUKS to format partitions with a keyfile]] for instructions.<br />
<br />
=== Preparing the boot partition ===<br />
<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a encrypted root. For an ordinary boot partition on BIOS systems, for example, execute:<br />
<br />
# mkfs.ext4 /dev/sda1<br />
<br />
or for an [[EFI system partition]] on UEFI systems:<br />
<br />
# mkfs.fat -F32 /dev/sda1<br />
<br />
Afterwards create the directory for the mounpoint and mount the partition:<br />
<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Mounting the devices ===<br />
<br />
At [[Installation guide#Mount the file systems]] you will have to mount the mapped devices, not the actual partitions. Of course {{ic|/boot}}, which is not encrypted, will still have to be mounted directly.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|keymap}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]. If the default US keymap is fine for you, you can omit the {{ic|keymap}} hook.<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' filesystems fsck)<br />
<br />
Depending on which other hooks are used, the order may be relevant. See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptroot root=/dev/mapper/cryptroot<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptroot root=/dev/mapper/cryptroot<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda2}}. See [[Persistent block device naming]] for details.<br />
<br />
== LVM on LUKS ==<br />
<br />
The straight-forward method is to set up [[LVM]] on top of the encrypted partition instead of the other way round. Technically the LVM is setup inside one big encrypted blockdevice. Hence, the LVM is not transparent until the blockdevice is unlocked and the underlying volume structure is scanned and mounted during boot.<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------------------------------------------------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot partition |<br />
| | | | | |<br />
| [SWAP] | / | /home | | /boot |<br />
| | | | | |<br />
| /dev/MyVolGroup/swap | /dev/MyVolGroup/root | /dev/MyVolGroup/home | | |<br />
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _| | (may be on |<br />
| | | other device) |<br />
| LUKS2 encrypted partition | | |<br />
| /dev/sda1 | | /dev/sdb1 |<br />
+-----------------------------------------------------------------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Note|While using the {{ic|encrypt}} hook this method does not allow you to span the logical volumes over multiple disks; either use the [[sd-encrypt]] or see [[dm-crypt/Specialties#Modifying the encrypt hook for multiple partitions]].}}<br />
<br />
{{Tip|Two variants of this setup:<br />
* Instructions at [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] use this setup with a detached LUKS header on a USB device to achieve a two factor authentication with it.<br />
* Instructions at [[dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB]] use this setup with a detached LUKS header, encrypted {{ic|/boot}} partition, and encrypted keyfile all on a USB device.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
{{Tip|When using the [[GRUB]] boot loader for BIOS booting from a [[GPT]] disk, create a [[BIOS boot partition]].}}<br />
<br />
Create a partition to be mounted at {{ic|/boot}} with a size of 200 MiB or more.<br />
<br />
{{Tip|UEFI systems can use the [[EFI system partition]] for {{ic|/boot}}.}}<br />
<br />
Create a partition which will later contain the encrypted container.<br />
<br />
Create the LUKS encrypted container at the "system" partition. Enter the chosen password twice.<br />
<br />
# cryptsetup luksFormat /dev/sda1<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda1 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
Create a physical volume on top of the opened LUKS container:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
<br />
Create the volume group named {{ic|MyVolGroup}} (or whatever you want), adding the previously created physical volume to it:<br />
<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
<br />
Create all your logical volumes on the volume group:<br />
<br />
# lvcreate -L 8G MyVolGroup -n swap<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
Format your filesystems on each logical volume:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mkswap /dev/MyVolGroup/swap<br />
<br />
Mount your filesystems:<br />
<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The bootloader loads the kernel, [[initramfs]], and its own configuration files from the {{ic|/boot}} directory. Any filesystem on a disk that can be read by the bootloader is eligible.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
<br />
{{Tip|When opting to keep {{ic|/boot}} on an [[EFI system partition]] the recommended formatting is<br />
<br />
# mkfs.fat -F32 /dev/sdb1<br />
<br />
}}<br />
<br />
Create the directory {{ic|/mnt/boot}}:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Mount the partition to {{ic|/mnt/boot}}:<br />
<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameter needs to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptlvm root=/dev/MyVolGroup/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptlvm root=/dev/MyVolGroup/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda1}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
== LUKS on LVM ==<br />
<br />
To use encryption on top of [[LVM]], the LVM volumes are set up first and then used as the base for the encrypted partitions. This way, a mixture of encrypted and non-encrypted volumes/partitions is possible as well.<br />
{{tip|Unlike [[#LVM on LUKS]], this method allows normally spanning the logical volumes over multiple disks. }}<br />
<br />
The following short example creates a LUKS on LVM setup and mixes in the use of a key-file for the /home partition and temporary crypt volumes for {{ic|/tmp}} and {{ic|/swap}}. The latter is considered desirable from a security perspective, because no potentially sensitive temporary data survives the reboot, when the encryption is re-initialised. If you are experienced with LVM, you will be able to ignore/replace LVM and other specifics according to your plan.<br />
<br />
If you want to span a logical volume over multiple disks that have already been set up, or expand the logical volume for {{ic|/home}} (or any other volume), a procedure to do so is described in [[dm-crypt/Specialties#Expanding LVM on multiple disks]]. It is important to note that the LUKS encrypted container has to be resized as well.<br />
<br />
{{Expansion|The intro of this scenario needs some adjustment now that a comparison has been added to [[#Overview]]. A suggested structure is to make it similar to the [[#LUKS on a partition]] intro.}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Partitioning scheme:<br />
<br />
{{Text art|<nowiki><br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
| Boot partition | dm-crypt plain encrypted volume | LUKS2 encrypted volume | LUKS2 encrypted volume |<br />
| | | | |<br />
| /boot | [SWAP] | / | /home |<br />
| | | | |<br />
| | /dev/mapper/swap | /dev/mapper/root | /dev/mapper/home |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | /dev/MyVolGroup/cryptswap | /dev/MyVolGroup/cryptroot | /dev/MyVolGroup/crypthome |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | |<br />
| /dev/sda1 | /dev/sda2 |<br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
Randomise {{ic|/dev/sda2}} according to [[dm-crypt/Drive preparation#dm-crypt wipe on an empty disk or partition]].<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
# pvcreate /dev/sda2<br />
# vgcreate MyVolGroup /dev/sda2<br />
# lvcreate -L 32G -n cryptroot MyVolGroup<br />
# lvcreate -L 500M -n cryptswap MyVolGroup<br />
# lvcreate -L 500M -n crypttmp MyVolGroup<br />
# lvcreate -l 100%FREE -n crypthome MyVolGroup<br />
<br />
# cryptsetup luksFormat /dev/MyVolGroup/cryptroot<br />
# cryptsetup open /dev/MyVolGroup/cryptroot root<br />
# mkfs.ext4 /dev/mapper/root<br />
# mount /dev/mapper/root /mnt<br />
<br />
More information about the encryption options can be found in [[dm-crypt/Device encryption#Encryption options for LUKS mode]].<br />
Note that {{ic|/home}} will be encrypted in [[#Encrypting logical volume /home]].<br />
<br />
{{Tip|If you ever have to access the encrypted root from the Arch-ISO, the above {{ic|open}} action will allow you to after the [[LVM#Logical Volumes do not show up|LVM shows up]].}}<br />
<br />
=== Preparing the boot partition ===<br />
<br />
# dd if=/dev/zero of=/dev/sda1 bs=1M status=progress<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|lvm2}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''lvm2''' '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':root root=/dev/mapper/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=root root=/dev/mapper/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/MyVolGroup/cryptroot}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
=== Configuring fstab and crypttab ===<br />
<br />
Both [[crypttab]] and [[fstab]] entries are required to both unlock the device and mount the filesystems, respectively. The following lines will re-encrypt the temporary filesystems on each reboot:<br />
<br />
{{hc|/etc/crypttab|2=<br />
swap /dev/MyVolGroup/cryptswap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
tmp /dev/MyVolGroup/crypttmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/root / ext4 defaults 0 1<br />
/dev/sda1 /boot ext4 defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
}}<br />
<br />
=== Encrypting logical volume /home ===<br />
<br />
Since this scenario uses LVM as the primary and dm-crypt as secondary mapper, each encrypted logical volume requires its own encryption. Yet, unlike the temporary filesystems configured with volatile encryption above, the logical volume for {{ic|/home}} should of course be persistent. The following assumes you have rebooted into the installed system, otherwise you have to adjust paths.<br />
To save on entering a second passphrase at boot, a [[dm-crypt/Device encryption#Keyfiles|keyfile]] is created:<br />
<br />
# mkdir -m 700 /etc/luks-keys<br />
# dd if=/dev/random of=/etc/luks-keys/home bs=1 count=256 status=progress<br />
<br />
The logical volume is encrypted with it:<br />
<br />
# cryptsetup luksFormat -v /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
# cryptsetup -d /etc/luks-keys/home open /dev/MyVolGroup/crypthome home<br />
# mkfs.ext4 /dev/mapper/home<br />
# mount /dev/mapper/home /home<br />
<br />
The encrypted mount is configured in both [[crypttab]] and [[fstab]]:<br />
<br />
{{hc|/etc/crypttab|<br />
home /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home /home ext4 defaults 0 2<br />
}}<br />
<br />
== LUKS on software RAID ==<br />
<br />
This example is based on a real-world setup for a workstation class laptop equipped with two SSDs of equal size, and an additional HDD for bulk storage. The end result is LUKS1 based full disk encryption (including {{ic|/boot}}) for all drives, with the SSDs in a [[RAID|RAID0]] array, and keyfiles used to unlock all encryption after [[GRUB]] is given a correct passphrase at boot.<br />
<br />
This setup utilizes a very simplistic partitioning scheme, with all the available RAID storage being mounted at {{ic|/}} (no separate {{ic|/boot}} partition), and the decrypted HDD being mounted at {{ic|/data}}.<br />
<br />
Please note that regular [[System backup|backups]] are very important in this setup. If either of the SSDs fail, the data contained in the RAID array will be practically impossible to recover. You may wish to select a different [[RAID#Standard RAID levels|RAID level]] if fault tolerance is important to you. <br />
<br />
The encryption is not deniable in this setup.<br />
<br />
For the sake of the instructions below, the following block devices are used:<br />
<br />
/dev/sda = first SSD<br />
/dev/sdb = second SSD<br />
/dev/sdc = HDD<br />
<br />
{{Text art|<nowiki><br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
| BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | LUKS2 encrypted volume |<br />
| | | | | | | | | |<br />
| | /efi | / | | | /efi | / | | /data |<br />
| | | | | | | | | |<br />
| | | /dev/mapper/cryptroot | | | | /dev/mapper/cryptroot | | |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ | |<br />
| | RAID1 array (part 1 of 2) | RAID0 array (part 1 of 2) | | | RAID1 array (part 2 of 2) | RAID0 array (part 2 of 2) | | |<br />
| | | | | | | | | |<br />
| | /dev/md/ESP | /dev/md/root | | | /dev/md/ESP | /dev/md/root | | /dev/mapper/cryptroot |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ +---------------------------+<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 | | /dev/sdb1 | /dev/sdb2 | /dev/sdb3 | | /dev/sdc1 |<br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
</nowiki>}}<br />
<br />
Be sure to substitute them with the appropriate device designations for your setup, as they may be different.<br />
<br />
=== Preparing the disks ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] with GPT, create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
In the remaining space on the drive create a partition ({{ic|/dev/sda3}} in this example) for "Linux RAID". Choose partition type ID {{ic|fd}} for MBR or partition type GUID {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} for GPT.<br />
<br />
Once partitions have been created on {{ic|/dev/sda}}, the following commands can be used to clone them to {{ic|/dev/sdb}}.<br />
<br />
# sfdisk -d /dev/sda > sda.dump<br />
# sfdisk /dev/sdb < sda.dump<br />
<br />
The HDD is prepared with a single Linux partition covering the whole drive at {{ic|/dev/sdc1}}.<br />
<br />
=== Building the RAID array ===<br />
<br />
Create the RAID array for the SSDs.<br />
<br />
{{Note|<br />
* All parts of an EFI system partition RAID array must be individually usable, that means that ESP can only placed in a RAID1 array.<br />
* The RAID superblock must be placed at the end of the EFI system partition using {{ic|1=--metadata=1.0}}, otherwise the firmware will not be able to access the partition.<br />
}}<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.0 --raid-devices=2 /dev/md/ESP /dev/sda2 /dev/sdb2<br />
<br />
This example utilizes RAID0 for root, you may wish to substitute a different level based on your preferences or requirements.<br />
<br />
# mdadm --create --verbose --level=0 --metadata=1.2 --raid-devices=2 /dev/md/root /dev/sda3 /dev/sdb3<br />
<br />
=== Preparing the block devices ===<br />
<br />
As explained in [[dm-crypt/Drive preparation]], the devices are wiped with random data utilizing {{ic|/dev/zero}} and a crypt device with a random key. Alternatively, you could use {{ic|dd}} with {{ic|/dev/random}} or {{ic|/dev/urandom}}, though it will be much slower.<br />
<br />
# cryptsetup open --type plain /dev/md/root container --key-file /dev/random<br />
# dd if=/dev/zero of=/dev/mapper/container bs=1M status=progress<br />
# cryptsetup close container<br />
<br />
And repeat above for the HDD ({{ic|/dev/sdc1}} in this example).<br />
<br />
Set up encryption for {{ic|/dev/md/root}}:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup -y -v luksFormat --type luks1 /dev/md/root<br />
# cryptsetup open /dev/md/root cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
And repeat for the HDD:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sdc1<br />
# cryptsetup open /dev/sdc1 cryptdata<br />
# mkfs.ext4 /dev/mapper/cryptdata<br />
# mkdir /mnt/data<br />
# mount /dev/mapper/cryptdata /mnt/data<br />
<br />
For UEFI systems, set up the EFI system partition:<br />
<br />
# mkfs.fat -F32 /dev/md/ESP<br />
# mount /dev/md/ESP /mnt/efi<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure [[GRUB]] for the LUKS1 encrypted system by editing {{ic|/etc/default/grub}} with the following:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/md/root:cryptroot"<br />
GRUB_ENABLE_CRYPTODISK=y<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details.<br />
<br />
Complete the GRUB install to both SSDs (in reality, installing only to {{ic|/dev/sda}} will work).<br />
<br />
# grub-install --target=i386-pc /dev/sda<br />
# grub-install --target=i386-pc /dev/sdb<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Creating the keyfiles ===<br />
<br />
The next steps save you from entering your passphrase twice when you boot the system (once so GRUB can unlock the LUKS1 device, and second time once the initramfs assumes control of the system). This is done by creating a [[dm-crypt/Device encryption#Keyfiles|keyfile]] for the encryption and adding it to the initramfs image to allow the encrypt hook to unlock the root device. See [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] for details.<br />
<br />
* Create the [[dm-crypt/Device encryption#Keyfiles|keyfile]] and add the key to {{ic|/dev/md/root}}.<br />
* Create another keyfile for the HDD ({{ic|/dev/sdc1}}) so it can also be unlocked at boot. For convenience, leave the passphrase created above in place as this can make recovery easier if you ever need it. Edit {{ic|/etc/crypttab}} to decrypt the HDD at boot. See [[Dm-crypt/System configuration#Unlocking with a keyfile]].<br />
<br />
=== Configuring the system ===<br />
<br />
Edit [[fstab]] to mount the cryptroot and cryptdata block devices and the ESP:<br />
<br />
/dev/mapper/cryptroot / ext4 rw,noatime 0 1<br />
/dev/mapper/cryptdata /data ext4 defaults 0 2<br />
/dev/md/ESP /efi vfat rw,relatime,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,tz=UTC,errors=remount-ro 0 2<br />
<br />
Save the RAID configuration:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
Edit [[mkinitcpio.conf]] to include your keyfile and add the proper hooks:<br />
<br />
FILES=(/crypto_keyfile.bin)<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''mdadm_udev''' '''encrypt''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details.<br />
<br />
== Plain dm-crypt ==<br />
<br />
Contrary to LUKS, dm-crypt ''plain'' mode does not require a header on the encrypted device: this scenario exploits this feature to set up a system on an unpartitioned, encrypted disk that will be indistinguishable from a disk filled with random data, which could allow [[Wikipedia:Deniable encryption|deniable encryption]]. See also [[wikipedia:Disk encryption#Full disk encryption]].<br />
<br />
Note that if full-disk encryption is not required, the methods using LUKS described in the sections above are better options for both system encryption and encrypted partitions. LUKS features like key management with multiple passphrases/key-files or re-encrypting a device in-place are unavailable with ''plain'' mode.<br />
<br />
''Plain'' dm-crypt encryption can be more resilient to damage than LUKS, because it does not rely on an encryption master-key which can be a single-point of failure if damaged. However, using ''plain'' mode also requires more manual configuration of encryption options to achieve the same cryptographic strength. See also [[Disk encryption#Cryptographic metadata]]. Using ''plain'' mode could also be considered if concerned with the problems explained in [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]].<br />
<br />
{{Tip|If headerless encryption is your goal but you are unsure about the lack of key-derivation with ''plain'' mode, then two alternatives are:<br />
* [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|dm-crypt LUKS mode with a detached header]] by using the ''cryptsetup'' {{ic|--header}} option. It cannot be used with the standard ''encrypt'' hook, but the hook may be modified.<br />
* [[tcplay]] which offers headerless encryption but with the PBKDF2 function.<br />
}}<br />
<br />
The scenario uses two USB sticks:<br />
<br />
* one for the boot device, which also allows storing the options required to open/unlock the plain encrypted device in the boot loader configuration, since typing them on each boot would be error prone;<br />
* another for the encryption key file, assuming it stored as raw bits so that to the eyes of an unaware attacker who might get the usbkey the encryption key will appear as random data instead of being visible as a normal file. See also [[Wikipedia:Security through obscurity]], follow [[dm-crypt/Device encryption#Keyfiles]] to prepare the keyfile.<br />
<br />
The disk layout is:<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+ +----------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot device | | Encryption key |<br />
| | | | | | | file storage |<br />
| / | [SWAP] | /home | | /boot | | (unpartitioned |<br />
| | | | | | | in example) |<br />
| /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home | | /dev/sdb1 | | /dev/sdc |<br />
|----------------------+----------------------+----------------------| |----------------| |----------------|<br />
| disk drive /dev/sda encrypted using plain mode and LVM | | USB stick 1 | | USB stick 2 |<br />
+--------------------------------------------------------------------+ +----------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* It is also possible to use a single USB key physical device:<br />
** By putting the key on another partition (/dev/sdb2) of the USB storage device (/dev/sdb).<br />
** By copying the keyfile to the initramfs directly. An example keyfile {{ic|/etc/keyfile}} gets copied to the initramfs image by setting {{ic|1=FILES=(/etc/keyfile)}} in {{ic|/etc/mkinitcpio.conf}}. The way to instruct the {{ic|encrypt}} hook to read the keyfile in the initramfs image is using {{ic|rootfs:}} prefix before the filename, e.g. {{ic|1=cryptkey=rootfs:/etc/keyfile}}.<br />
* Another option is using a passphrase with good [[Disk encryption#Choosing a strong passphrase|entropy]].<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
It is vital that the mapped device is filled with random data. In particular this applies to the scenario use case we apply here.<br />
<br />
See [[dm-crypt/Drive preparation]] and [[dm-crypt/Drive preparation#dm-crypt specific methods]]<br />
<br />
=== Preparing the non-boot partitions ===<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for plain mode]] for details.<br />
<br />
Using the device {{ic|/dev/sda}}, with the aes-xts cipher with a 512 bit key size and using a keyfile we have the following options for this scenario:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sdc --key-size=512 open --type plain /dev/sda cryptlvm<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, and key file details.<br />
<br />
We can now check a mapping entry has been made for {{ic|/dev/mapper/cryptlvm}}:<br />
<br />
# fdisk -l<br />
<br />
{{Tip|A simpler alternative to using LVM, advocated in the cryptsetup FAQ for cases where LVM is not necessary, is to just create a filesystem on the entirety of the mapped dm-crypt device.}} <br />
<br />
Next, we setup [[LVM]] logical volumes on the mapped device. See [[LVM#Installing Arch Linux on LVM]] for further details:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -L 10G MyVolGroup -n swap<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
We format and mount them and activate swap. See [[File systems#Create a file system]] for further details:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# mkswap /dev/MyVolGroup/swap<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The {{ic|/boot}} partition can be installed on the standard vfat partition of a USB stick, if required. But if manual partitioning is needed, then a small 200 MiB partition is all that is required. Create the partition using a [[Partitioning#Partitioning tools|partitioning tool]] of your choice.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}, if it is not already formatted as vfat:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
# mkdir /mnt/boot<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to boot the encrypted root partition, the following [[kernel parameters]] need to be set by the boot loader (note that 64 is the number of bytes in 512 bits):<br />
<br />
cryptdevice=/dev/disk/by-id/''disk-ID-of-sda'':cryptlvm cryptkey=/dev/disk/by-id/''disk-ID-of-sdc'':0:64 crypto=:aes-xts-plain64:512:0:<br />
<br />
The {{ic|''disk-ID-of-'''disk'''''}} refers to the id of the referenced disk. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details and other parameters that you may need.<br />
<br />
{{Tip|If using GRUB, you can install it on the same USB as the {{ic|/boot}} partition with:<br />
<br />
# grub-install --recheck /dev/sdb<br />
<br />
}}<br />
<br />
=== Post-installation ===<br />
<br />
You may wish to remove the USB sticks after booting. Since the {{ic|/boot}} partition is not usually needed, the {{ic|noauto}} option can be added to the relevant line in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
# /dev/sdb1<br />
/dev/sdb1 /boot ext4 '''noauto''',rw,noatime 0 2<br />
}}<br />
<br />
However, when an update to anything used in the initramfs, or a kernel, or the bootloader is required; the {{ic|/boot}} partition must be present and mounted. As the entry in {{ic|fstab}} already exists, it can be mounted simply with:<br />
<br />
# mount /boot<br />
<br />
== Encrypted boot partition (GRUB) ==<br />
<br />
This setup utilizes the same partition layout and configuration for the system's root partition as the previous [[#LVM on LUKS]] section, with the difference that a special feature of the [[GRUB]] bootloader is used to additionally encrypt the boot partition {{ic|/boot}}. See also [[GRUB#Encrypted /boot]].<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+---------------------+----------------------+----------------------+----------------------+----------------------+<br />
| BIOS boot partition | EFI system partition | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | | | | |<br />
| | /efi | / | [SWAP] | /home |<br />
| | | | | |<br />
| | | /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home |<br />
| /dev/sda1 | /dev/sda2 |----------------------+----------------------+----------------------+<br />
| unencrypted | unencrypted | /dev/sda3 encrypted using LVM on LUKS1 |<br />
+---------------------+----------------------+--------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* All scenarios are intended as examples. It is, of course, possible to apply both of the two above distinct installation steps with the other scenarios as well. See also the variants linked in [[#LVM on LUKS]].<br />
* You can use {{ic|cryptboot}} script from {{AUR|cryptboot}} package for simplified encrypted boot management (mounting, unmounting, upgrading packages) and as a defense against [https://www.schneier.com/blog/archives/2009/10/evil_maid_attac.html Evil Maid] attacks with [[Secure Boot#Using your own keys|UEFI Secure Boot]]. For more information and limitations see [https://github.com/xmikos/cryptboot cryptboot project] page.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
Create a partition of type {{ic|8309}}, which will later contain the encrypted container for the LVM.<br />
<br />
Create the LUKS encrypted container:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup luksFormat --type luks1 /dev/sda3<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Your partition layout should look similar to this:<br />
<br />
{{hc|# gdisk -l /dev/sda|<br />
...<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 4095 1024.0 KiB EF02 BIOS boot partition<br />
2 4096 1130495 550.0 MiB EF00 EFI System<br />
3 1130496 68239360 32.0 GiB 8309 Linux LUKS<br />
}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda3 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
The LVM logical volumes of this example follow the exact layout as the [[#LVM on LUKS]] scenario. Therefore, please follow [[#Preparing the logical volumes]] above and adjust as required.<br />
<br />
If you plan to boot in UEFI mode, create a mountpoint for the [[EFI system partition]] at {{ic|/efi}} for compatibility with {{ic|grub-install}} and mount it:<br />
<br />
# mkdir /mnt/efi<br />
# mount /dev/sda2 /mnt/efi<br />
<br />
At this point, you should have the following partitions and logical volumes inside of {{ic|/mnt}}:<br />
<br />
{{hc|$ lsblk|<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 200G 0 disk<br />
├─sda1 8:1 0 1M 0 part<br />
├─sda2 8:2 0 550M 0 part /mnt/efi<br />
└─sda3 8:3 0 100G 0 part<br />
└─cryptlvm 254:0 0 100G 0 crypt<br />
├─MyVolGroup-swap 254:1 0 8G 0 lvm [SWAP]<br />
├─MyVolGroup-root 254:2 0 32G 0 lvm /mnt<br />
└─MyVolGroup-home 254:3 0 60G 0 lvm /mnt/home<br />
}}<br />
<br />
The following steps assume that you have a functional arch installation on MyVolGroup-root (restore from backup, etc.) and have [[chroot]]ed to it. E.g.:<br />
<br />
# arch-chroot /mnt<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure GRUB to allow booting from {{ic|/boot}} on a LUKS1 encrypted partition:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_ENABLE_CRYPTODISK=y<br />
}}<br />
<br />
Set the kernel parameters, so that the initramfs can unlock the encrypted root partition. Using the {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... cryptdevice=UUID=''device-UUID'':cryptlvm ..."<br />
}}<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... rd.luks.name=''device-UUID''=cryptlvm ..."<br />
}}<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details. The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda3}} (the partition which holds the lvm containing the root filesystem). See [[Persistent block device naming]].<br />
<br />
[[GRUB#Installation_2|install GRUB]] to the mounted ESP for UEFI booting:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB --recheck<br />
<br />
[[GRUB#Installation|install GRUB]] to the disk for BIOS booting:<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
<br />
Generate GRUB's [[GRUB#Generate the main configuration file|configuration]] file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If all commands finished without errors, GRUB should prompt for the passphrase to unlock the {{ic|/dev/sda3}} partition after the next reboot.<br />
<br />
=== Avoiding having to enter the passphrase twice ===<br />
<br />
{{Merge|Dm-crypt/Device encryption#With a keyfile embedded in the initramfs|Too much duplicated content, too much detail here for this overview page.|section=Security Issue with Grub Keyfile}}<br />
<br />
While GRUB asks for a passphrase to unlock the LUKS1 encrypted partition after above instructions, the partition unlock is not passed on to the initramfs. Hence, you have to enter the passphrase twice at boot: once for GRUB and once for the initramfs.<br />
<br />
This section deals with extra configuration to let the system boot by only entering the passphrase once, in GRUB. This is accomplished by [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs|with a keyfile embedded in the initramfs]].<br />
<br />
First create a keyfile and add it as LUKS key:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/root/cryptlvm.keyfile iflag=fullblock<br />
# chmod 000 /root/cryptlvm.keyfile<br />
# chmod 600 /boot/initramfs-linux*<br />
# cryptsetup -v luksAddKey /dev/sda3 /root/cryptlvm.keyfile<br />
<br />
Add the keyfile to the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/root/cryptlvm.keyfile)<br />
}}<br />
<br />
Set the following kernel parameters to unlock the LUKS partition with the keyfile. Using the {{ic|encrypt}} hook:<br />
<br />
GRUB_CMDLINE_LINUX="... cryptkey=rootfs:/root/cryptlvm.keyfile"<br />
<br />
Or, using the [[sd-encrypt]] hook:<br />
<br />
GRUB_CMDLINE_LINUX="... rd.luks.key=''device-UUID''=/root/cryptlvm.keyfile"<br />
<br />
If for some reason the keyfile fails to unlock the boot partition, systemd will fallback to ask for a passphrase to unlock and, in case that is correct, continue booting.<br />
<br />
{{Tip|If you want to encrypt the {{ic|/boot}} partition to protect against offline tampering threats, the [[dm-crypt/Specialties#mkinitcpio-chkcryptoboot|mkinitcpio-chkcryptoboot]] hook has been contributed to help.}}<br />
<br />
== Btrfs subvolumes with swap ==<br />
<br />
The following example creates a full system encryption with LUKS1 using [[Btrfs]] subvolumes to [[Btrfs#Mounting subvolumes|simulate partitions]].<br />
<br />
If using UEFI, an [[EFI system partition]] (ESP) is required. {{ic|/boot}} itself may reside on {{ic|/}} and be encrypted; however, the ESP itself cannot be encrypted. In this example layout, the ESP is {{ic|/dev/sda1}} and is mounted at {{ic|/efi}}. {{ic|/boot}} itself is located on the system partition, {{ic|/dev/sda2}}.<br />
<br />
Since {{ic|/boot}} resides on the LUKS1 encrypted {{ic|/}}, [[GRUB]] must be used as the bootloader because only GRUB can load modules necessary to decrypt {{ic|/boot}} (e.g., crypto.mod, cryptodisk.mod and luks.mod).<br />
<br />
Additionally an optional plain-encrypted [[swap]] partition is shown.<br />
<br />
{{Warning|Do not use a [[swap file]] instead of a separate partition on Linux kernels before v5.0, because this may result in data loss. See [[Btrfs#Swap file]].}}<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+<br />
| EFI system partition | System partition | Swap partition |<br />
| unencrypted | LUKS1-encrypted | plain-encrypted |<br />
| | | |<br />
| /efi | / | [SWAP] |<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 |<br />
|----------------------+----------------------+----------------------+<br />
</nowiki>}}<br />
<br />
=== Preparing the disk ===<br />
<br />
{{Note|It is not possible to use btrfs partitioning as described in [[Btrfs#Partitionless Btrfs disk]] when using LUKS. Traditional partitioning must be used, even if it is just to create one partition.}}<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]]. If you are using [[UEFI]] create an [[EFI system partition]] with an appropriate size. It will later be mounted at {{ic|/efi}}. If you are going to create an encrypted swap partition, create the partition for it, but do '''not''' mark it as swap, since plain ''dm-crypt'' will be used with the partition.<br />
<br />
Create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}). See the [[Partitioning]] article.<br />
<br />
=== Preparing the system partition ===<br />
<br />
==== Create LUKS container ====<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
Follow [[dm-crypt/Device encryption#Encrypting devices with LUKS mode]] to setup {{ic|/dev/sda2}} for LUKS. See the [[dm-crypt/Device encryption#Encryption options for LUKS mode]] before doing so for a list of encryption options.<br />
<br />
==== Unlock LUKS container ====<br />
<br />
Now follow [[dm-crypt/Device encryption#Unlocking/Mapping LUKS partitions with the device mapper]] to unlock the LUKS container and map it.<br />
<br />
==== Format mapped device ====<br />
<br />
Proceed to format the mapped device as described in [[Btrfs#File system on a single device]], where {{ic|''/dev/partition''}} is the name of the mapped device (i.e., {{ic|cryptroot}}) and '''not''' {{ic|/dev/sda2}}.<br />
<br />
==== Mount mapped device ====<br />
<br />
Finally, [[mount]] the now-formatted mapped device (i.e., {{ic|/dev/mapper/cryptroot}}) to {{ic|/mnt}}.<br />
<br />
{{Tip|You may want to use the {{ic|1=compress=lzo}} mount option. See [[Btrfs#Compression]] for more information.}}<br />
<br />
=== Creating btrfs subvolumes ===<br />
<br />
{{Merge|Btrfs|The subvolume layout is not specific to an encrypted system.}}<br />
<br />
==== Layout ====<br />
<br />
[[Btrfs#Subvolumes|Subvolumes]] will be used to simulate partitions, but other (nested) subvolumes will also be created. Here is a partial representation of what the following example will generate:<br />
<br />
{{Text art|<nowiki><br />
subvolid=5 (/dev/sda2)<br />
|<br />
├── @ (mounted as /)<br />
| |<br />
| ├── /bin (directory)<br />
| |<br />
| ├── /home (mounted @home subvolume)<br />
| |<br />
| ├── /usr (directory)<br />
| |<br />
| ├── /.snapshots (mounted @snapshots subvolume)<br />
| |<br />
| ├── /var/cache/pacman/pkg (nested subvolume)<br />
| |<br />
| ├── ... (other directories and nested subvolumes)<br />
|<br />
├── @snapshots (mounted as /.snapshots)<br />
|<br />
├── @home (mounted as /home)<br />
|<br />
└── @... (additional subvolumes you wish to use as mount points)<br />
</nowiki>}}<br />
<br />
This section follows the [[Snapper#Suggested filesystem layout]], which is most useful when used with [[Snapper]]. You should also consult [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs Wiki SysadminGuide#Layout].<br />
<br />
==== Create top-level subvolumes ====<br />
<br />
Here we are using the convention of prefixing {{ic|@}} to subvolume names that will be used as mount points, and {{ic|@}} will be the subvolume that is mounted as {{ic|/}}.<br />
<br />
Following the [[Btrfs#Creating a subvolume]] article, create subvolumes at {{ic|/mnt/@}}, {{ic|/mnt/@snapshots}}, and {{ic|/mnt/@home}}.<br />
<br />
Create any additional subvolumes you wish to use as mount points now.<br />
<br />
==== Mount top-level subvolumes ====<br />
<br />
Unmount the system partition at {{ic|/mnt}}.<br />
<br />
Now mount the newly created {{ic|@}} subvolume which will serve as {{ic|/}} to {{ic|/mnt}} using the {{ic|1=subvol=}} mount option. Assuming the mapped device is named {{ic|cryptroot}}, the command would look like:<br />
<br />
# mount -o compress=lzo,subvol=@ /dev/mapper/cryptroot /mnt<br />
<br />
See [[Btrfs#Mounting subvolumes]] for more details.<br />
<br />
Also mount the other subvolumes to their respective mount points: {{ic|@home}} to {{ic|/mnt/home}} and {{ic|@snapshots}} to {{ic|/mnt/.snapshots}}.<br />
<br />
==== Create nested subvolumes ====<br />
<br />
Create any subvolumes you do '''not''' want to have snapshots of when taking a snapshot of {{ic|/}}. For example, you probably do not want to take snapshots of {{ic|/var/cache/pacman/pkg}}. These subvolumes will be nested under the {{ic|@}} subvolume, but just as easily could have been created earlier at the same level as {{ic|@}} according to your preference.<br />
<br />
Since the {{ic|@}} subvolume is mounted at {{ic|/mnt}} you will need to [[create a subvolume]] at {{ic|/mnt/var/cache/pacman/pkg}} for this example. You may have to create any parent directories first.<br />
<br />
Other directories you may wish to do this with are {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.<br />
<br />
==== Mount ESP ====<br />
<br />
If you prepared an EFI system partition earlier, create its mount point and mount it now.<br />
<br />
{{Note|Btrfs snapshots will exclude {{ic|/efi}}, since it is not a btrfs file system.}}<br />
<br />
At the [[Installation guide#Install the base packages|pacstrap]] installation step, the {{Pkg|btrfs-progs}} must be installed in addition to the base group.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
==== Create keyfile ====<br />
<br />
In order for GRUB to open the LUKS partition without having the user enter his passphrase twice, we will use a keyfile embedded in the initramfs. Follow [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] making sure to add the key to {{ic|/dev/sda2}} at the ''luksAddKey'' step.<br />
<br />
==== Edit mkinitcpio.conf ====<br />
<br />
After creating, adding, and embedding the key as described above, add the {{ic|encrypt}} hook to [[mkinitcpio.conf]] as well as any other hooks you require. See [[dm-crypt/System configuration#mkinitcpio]] for detailed information.<br />
<br />
{{Tip|You may want to add {{ic|1=BINARIES=(/usr/bin/btrfs)}} to your {{ic|mkinitcpio.conf}}. See the [[Btrfs#Corruption recovery]] article.}}<br />
<br />
=== Configuring the boot loader ===<br />
<br />
Install [[GRUB]] to {{ic|/dev/sda}}. Then, edit {{ic|/etc/default/grub}} as instructed in the [[GRUB#Additional arguments]] and [[GRUB#Encrypted /boot]], following both the instructions for an encrypted root and boot partition. Finally, generate the GRUB configuration file.<br />
<br />
=== Configuring swap ===<br />
<br />
If you created a partition to be used for encrypted swap, now is the time to configure it. Follow the instructions at [[dm-crypt/Swap encryption]].</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=580941Dm-crypt/Encrypting an entire system2019-08-25T15:47:47Z<p>EasyToRemember: /* Configuring GRUB */ Typo correction</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[Category:Installation process]]<br />
[[de:Systemverschlüsselung mit dm-crypt]]<br />
[[es:Dm-crypt/Encrypting an entire system]]<br />
[[ja:Dm-crypt/システム全体の暗号化]]<br />
[[pl:Dm-crypt/Encrypting an entire system]]<br />
<br />
The following are examples of common scenarios of full system encryption with ''dm-crypt''. They explain all the adaptations that need to be done to the normal [[Installation guide|installation procedure]]. All the necessary tools are on the [https://www.archlinux.org/download/ installation image].<br />
<br />
== Overview ==<br />
<br />
Securing a root filesystem is where ''dm-crypt'' excels, feature and performance-wise. Unlike selectively encrypting non-root filesystems, an encrypted root filesystem can conceal information such as which programs are installed, the usernames of all user accounts, and common data-leakage vectors such as [[mlocate]] and {{ic|/var/log/}}. Furthermore, an encrypted root filesystem makes tampering with the system far more difficult, as everything except the [[boot loader]] and (usually) the kernel is encrypted.<br />
<br />
All scenarios illustrated in the following share these advantages, other pros and cons differentiating them are summarized below:<br />
<br />
{| class="wikitable"<br />
! Scenarios<br />
! Advantages<br />
! Disadvantages<br />
|----------------------------------------------------------<br />
| [[#LUKS on a partition]]<br />
shows a basic and straight-forward set-up for a fully LUKS encrypted root.<br />
|<br />
* Simple partitioning and setup<br />
|<br />
* Inflexible; disk-space to be encrypted has to be pre-allocated<br />
|----------------------------------------------------------<br />
| [[#LVM on LUKS]]<br />
achieves partitioning flexibility by using LVM inside a single LUKS encrypted partition.<br />
|<br />
* Simple partitioning with knowledge of LVM<br />
* Only one key required to unlock all volumes (e.g. easy resume-from-disk setup)<br />
* Volume layout not transparent when locked<br />
* Easiest method to allow [[dm-crypt/Swap encryption#With suspend-to-disk support|suspension to disk]]<br />
|<br />
* LVM adds an additional mapping layer and hook<br />
* Less useful, if a singular volume should receive a separate key<br />
|----------------------------------------------------------<br />
| [[#LUKS on LVM]]<br />
uses dm-crypt only after the LVM is setup.<br />
|<br />
* LVM can be used to have encrypted volumes span multiple disks<br />
* Easy mix of un-/encrypted volume groups<br />
|<br />
* Complex; changing volumes requires changing encryption mappers too<br />
* Volumes require individual keys<br />
* LVM layout is transparent when locked<br />
|----------------------------------------------------------<br />
| [[#LUKS on software RAID]]<br />
uses dm-crypt only after RAID is setup.<br />
|<br />
* Analogous to LUKS on LVM<br />
|<br />
* Analogous to LUKS on LVM<br />
|----------------------------------------------------------<br />
| [[#Plain dm-crypt]]<br />
uses dm-crypt plain mode, i.e. without a LUKS header and its options for multiple keys. <br>This scenario also employs USB devices for {{ic|/boot}} and key storage, which may be applied to the other scenarios.<br />
|<br />
* Data resilience for cases where a LUKS header may be damaged<br />
* Allows [[Wikipedia:Disk encryption#Full disk encryption|Full Disk Encryption]]<br />
* Helps addressing [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)|problems]] with SSDs<br />
|<br />
* High care to all encryption parameters is required<br />
* Single encryption key and no option to change it<br />
|----------------------------------------------------------<br />
| [[#Encrypted boot partition (GRUB)]]<br />
shows how to encrypt the boot partition using the GRUB bootloader. <br> This scenario also employs an EFI system partition, which may be applied to the other scenarios.<br />
|<br />
* Same advantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* Less data is left unencrypted, i.e. the boot loader and the EFI system partition, if present<br />
|<br />
* Same disadvantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* More complicated configuration<br />
* Not supported by other boot loaders<br />
|----------------------------------------------------------<br />
| [[#Btrfs subvolumes with swap]]<br />
shows how to encrypt a [[Btrfs]] system, including the {{ic|/boot}} directory, also adding a partition for swap, on UEFI hardware.<br />
|<br />
* Similar advantages as [[#Encrypted boot partition (GRUB)]]<br />
* Availability of Btrfs' features<br />
|<br />
* Similar disadvantages as [[#Encrypted boot partition (GRUB)]]<br />
|}<br />
<br />
While all above scenarios provide much greater protection from outside threats than encrypted secondary filesystems, they also share a common disadvantage: any user in possession of the encryption key is able to decrypt the entire drive, and therefore can access other users' data. If that is of concern, it is possible to use a combination of blockdevice and stacked filesystem encryption and reap the advantages of both. See [[Disk encryption]] to plan ahead.<br />
<br />
See [[dm-crypt/Drive preparation#Partitioning]] for a general overview of the partitioning strategies used in the scenarios.<br />
<br />
Another area to consider is whether to set up an encrypted swap partition and what kind. See [[dm-crypt/Swap encryption]] for alternatives.<br />
<br />
If you anticipate to protect the system's data not only against physical theft, but also have a requirement of precautions against logical tampering, see [[dm-crypt/Specialties#Securing the unencrypted boot partition]] for further possibilities after following one of the scenarios.<br />
<br />
For [[solid state drive]]s you might want to consider enabling TRIM support, but be warned, there are potential security implications. See [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]] for more information.<br />
<br />
{{Warning|<br />
* In any scenario, never use file system repair software such as [[fsck]] directly on an encrypted volume, or it will destroy any means to recover the key used to decrypt your files. Such tools must be used on the decrypted (opened) device instead.<br />
* For the LUKS2 format:<br />
** [[GRUB]] does not support LUKS2.[https://savannah.gnu.org/bugs/?55093] Use LUKS1 on partitions that GRUB needs to access.<br />
** The LUKS2 format has a high RAM usage per design, defaulting to 1GB per encrypted mapper. Machines with low RAM and/or multiple LUKS2 partitions unlocked in parallel may error on boot. See the {{ic|--pbkdf-memory}} option to control memory usage.[https://gitlab.com/cryptsetup/cryptsetup/issues/372]<br />
}}<br />
<br />
== LUKS on a partition ==<br />
<br />
This example covers a full system encryption with ''dm-crypt'' + LUKS in a simple partition layout:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------+------------------------+-----------------------+<br />
| Boot partition | LUKS2 encrypted system | Optional free space |<br />
| | partition | for additional |<br />
| | | partitions or swap |<br />
| /boot | / | to be setup later |<br />
| | | |<br />
| | /dev/mapper/cryptroot | |<br />
| |------------------------| |<br />
| /dev/sda1 | /dev/sda2 | |<br />
+-----------------------+------------------------+-----------------------+<br />
</nowiki>}}<br />
<br />
The first steps can be performed directly after booting the Arch Linux install image.<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
Then create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}) and {{ic|/boot}} ({{ic|/dev/sda1}}). See [[Partitioning]].<br />
<br />
=== Preparing non-boot partitions ===<br />
<br />
The following commands create and mount the encrypted root partition. They correspond to the procedure described in detail in [[dm-crypt/Encrypting a non-root file system#Partition]] (which, despite the title, ''can'' be applied to root partitions, as long as [[#Configuring mkinitcpio|mkinitcpio]] and the [[#Configuring the boot loader|boot loader]] are correctly configured).<br />
If you want to use particular non-default encryption options (e.g. cipher, key length), see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|encryption options]] before executing the first command:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sda2<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
Check the mapping works as intended:<br />
<br />
# umount /mnt<br />
# cryptsetup close cryptroot<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
If you created separate partitions (e.g. {{ic|/home}}), these steps have to be adapted and repeated for all of them, ''except'' for {{ic|/boot}}. See [[dm-crypt/Encrypting a non-root file system#Automated unlocking and mounting]] on how to handle additional partitions at boot.<br />
<br />
Note that each blockdevice requires its own passphrase. This may be inconvenient, because it results in a separate passphrase to be input during boot. An alternative is to use a keyfile stored in the system partition to unlock the separate partition via {{ic|crypttab}}. See [[dm-crypt/Device encryption#Using LUKS to format partitions with a keyfile]] for instructions.<br />
<br />
=== Preparing the boot partition ===<br />
<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a encrypted root. For an ordinary boot partition on BIOS systems, for example, execute:<br />
<br />
# mkfs.ext4 /dev/sda1<br />
<br />
or for an [[EFI system partition]] on UEFI systems:<br />
<br />
# mkfs.fat -F32 /dev/sda1<br />
<br />
Afterwards create the directory for the mounpoint and mount the partition:<br />
<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Mounting the devices ===<br />
<br />
At [[Installation guide#Mount the file systems]] you will have to mount the mapped devices, not the actual partitions. Of course {{ic|/boot}}, which is not encrypted, will still have to be mounted directly.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|keymap}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]. If the default US keymap is fine for you, you can omit the {{ic|keymap}} hook.<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' filesystems fsck)<br />
<br />
Depending on which other hooks are used, the order may be relevant. See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptroot root=/dev/mapper/cryptroot<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptroot root=/dev/mapper/cryptroot<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda2}}. See [[Persistent block device naming]] for details.<br />
<br />
== LVM on LUKS ==<br />
<br />
The straight-forward method is to set up [[LVM]] on top of the encrypted partition instead of the other way round. Technically the LVM is setup inside one big encrypted blockdevice. Hence, the LVM is not transparent until the blockdevice is unlocked and the underlying volume structure is scanned and mounted during boot.<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------------------------------------------------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot partition |<br />
| | | | | |<br />
| [SWAP] | / | /home | | /boot |<br />
| | | | | |<br />
| /dev/MyVolGroup/swap | /dev/MyVolGroup/root | /dev/MyVolGroup/home | | |<br />
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _| | (may be on |<br />
| | | other device) |<br />
| LUKS2 encrypted partition | | |<br />
| /dev/sda1 | | /dev/sdb1 |<br />
+-----------------------------------------------------------------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Note|While using the {{ic|encrypt}} hook this method does not allow you to span the logical volumes over multiple disks; either use the [[sd-encrypt]] or see [[dm-crypt/Specialties#Modifying the encrypt hook for multiple partitions]].}}<br />
<br />
{{Tip|Two variants of this setup:<br />
* Instructions at [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] use this setup with a detached LUKS header on a USB device to achieve a two factor authentication with it.<br />
* Instructions at [[dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB]] use this setup with a detached LUKS header, encrypted {{ic|/boot}} partition, and encrypted keyfile all on a USB device.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
{{Tip|When using the [[GRUB]] boot loader for BIOS booting from a [[GPT]] disk, create a [[BIOS boot partition]].}}<br />
<br />
Create a partition to be mounted at {{ic|/boot}} with a size of 200 MiB or more.<br />
<br />
{{Tip|UEFI systems can use the [[EFI system partition]] for {{ic|/boot}}.}}<br />
<br />
Create a partition which will later contain the encrypted container.<br />
<br />
Create the LUKS encrypted container at the "system" partition. Enter the chosen password twice.<br />
<br />
# cryptsetup luksFormat /dev/sda1<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda1 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
Create a physical volume on top of the opened LUKS container:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
<br />
Create the volume group named {{ic|MyVolGroup}} (or whatever you want), adding the previously created physical volume to it:<br />
<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
<br />
Create all your logical volumes on the volume group:<br />
<br />
# lvcreate -L 8G MyVolGroup -n swap<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
Format your filesystems on each logical volume:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mkswap /dev/MyVolGroup/swap<br />
<br />
Mount your filesystems:<br />
<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The bootloader loads the kernel, [[initramfs]], and its own configuration files from the {{ic|/boot}} directory. Any filesystem on a disk that can be read by the bootloader is eligible.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
<br />
{{Tip|When opting to keep {{ic|/boot}} on an [[EFI system partition]] the recommended formatting is<br />
<br />
# mkfs.fat -F32 /dev/sdb1<br />
<br />
}}<br />
<br />
Create the directory {{ic|/mnt/boot}}:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Mount the partition to {{ic|/mnt/boot}}:<br />
<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameter needs to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptlvm root=/dev/MyVolGroup/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptlvm root=/dev/MyVolGroup/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda1}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
== LUKS on LVM ==<br />
<br />
To use encryption on top of [[LVM]], the LVM volumes are set up first and then used as the base for the encrypted partitions. This way, a mixture of encrypted and non-encrypted volumes/partitions is possible as well.<br />
{{tip|Unlike [[#LVM on LUKS]], this method allows normally spanning the logical volumes over multiple disks. }}<br />
<br />
The following short example creates a LUKS on LVM setup and mixes in the use of a key-file for the /home partition and temporary crypt volumes for {{ic|/tmp}} and {{ic|/swap}}. The latter is considered desirable from a security perspective, because no potentially sensitive temporary data survives the reboot, when the encryption is re-initialised. If you are experienced with LVM, you will be able to ignore/replace LVM and other specifics according to your plan.<br />
<br />
If you want to span a logical volume over multiple disks that have already been set up, or expand the logical volume for {{ic|/home}} (or any other volume), a procedure to do so is described in [[dm-crypt/Specialties#Expanding LVM on multiple disks]]. It is important to note that the LUKS encrypted container has to be resized as well.<br />
<br />
{{Expansion|The intro of this scenario needs some adjustment now that a comparison has been added to [[#Overview]]. A suggested structure is to make it similar to the [[#LUKS on a partition]] intro.}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Partitioning scheme:<br />
<br />
{{Text art|<nowiki><br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
| Boot partition | dm-crypt plain encrypted volume | LUKS2 encrypted volume | LUKS2 encrypted volume |<br />
| | | | |<br />
| /boot | [SWAP] | / | /home |<br />
| | | | |<br />
| | /dev/mapper/swap | /dev/mapper/root | /dev/mapper/home |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | /dev/MyVolGroup/cryptswap | /dev/MyVolGroup/cryptroot | /dev/MyVolGroup/crypthome |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | |<br />
| /dev/sda1 | /dev/sda2 |<br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
Randomise {{ic|/dev/sda2}} according to [[dm-crypt/Drive preparation#dm-crypt wipe on an empty disk or partition]].<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
# pvcreate /dev/sda2<br />
# vgcreate MyVolGroup /dev/sda2<br />
# lvcreate -L 32G -n cryptroot MyVolGroup<br />
# lvcreate -L 500M -n cryptswap MyVolGroup<br />
# lvcreate -L 500M -n crypttmp MyVolGroup<br />
# lvcreate -l 100%FREE -n crypthome MyVolGroup<br />
<br />
# cryptsetup luksFormat /dev/MyVolGroup/cryptroot<br />
# cryptsetup open /dev/MyVolGroup/cryptroot root<br />
# mkfs.ext4 /dev/mapper/root<br />
# mount /dev/mapper/root /mnt<br />
<br />
More information about the encryption options can be found in [[dm-crypt/Device encryption#Encryption options for LUKS mode]].<br />
Note that {{ic|/home}} will be encrypted in [[#Encrypting logical volume /home]].<br />
<br />
{{Tip|If you ever have to access the encrypted root from the Arch-ISO, the above {{ic|open}} action will allow you to after the [[LVM#Logical Volumes do not show up|LVM shows up]].}}<br />
<br />
=== Preparing the boot partition ===<br />
<br />
# dd if=/dev/zero of=/dev/sda1 bs=1M status=progress<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|lvm2}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''lvm2''' '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':root root=/dev/mapper/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=root root=/dev/mapper/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/MyVolGroup/cryptroot}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
=== Configuring fstab and crypttab ===<br />
<br />
Both [[crypttab]] and [[fstab]] entries are required to both unlock the device and mount the filesystems, respectively. The following lines will re-encrypt the temporary filesystems on each reboot:<br />
<br />
{{hc|/etc/crypttab|2=<br />
swap /dev/MyVolGroup/cryptswap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
tmp /dev/MyVolGroup/crypttmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/root / ext4 defaults 0 1<br />
/dev/sda1 /boot ext4 defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
}}<br />
<br />
=== Encrypting logical volume /home ===<br />
<br />
Since this scenario uses LVM as the primary and dm-crypt as secondary mapper, each encrypted logical volume requires its own encryption. Yet, unlike the temporary filesystems configured with volatile encryption above, the logical volume for {{ic|/home}} should of course be persistent. The following assumes you have rebooted into the installed system, otherwise you have to adjust paths.<br />
To save on entering a second passphrase at boot, a [[dm-crypt/Device encryption#Keyfiles|keyfile]] is created:<br />
<br />
# mkdir -m 700 /etc/luks-keys<br />
# dd if=/dev/random of=/etc/luks-keys/home bs=1 count=256 status=progress<br />
<br />
The logical volume is encrypted with it:<br />
<br />
# cryptsetup luksFormat -v /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
# cryptsetup -d /etc/luks-keys/home open /dev/MyVolGroup/crypthome home<br />
# mkfs.ext4 /dev/mapper/home<br />
# mount /dev/mapper/home /home<br />
<br />
The encrypted mount is configured in both [[crypttab]] and [[fstab]]:<br />
<br />
{{hc|/etc/crypttab|<br />
home /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home /home ext4 defaults 0 2<br />
}}<br />
<br />
== LUKS on software RAID ==<br />
<br />
This example is based on a real-world setup for a workstation class laptop equipped with two SSDs of equal size, and an additional HDD for bulk storage. The end result is LUKS1 based full disk encryption (including {{ic|/boot}}) for all drives, with the SSDs in a [[RAID|RAID0]] array, and keyfiles used to unlock all encryption after [[GRUB]] is given a correct passphrase at boot.<br />
<br />
This setup utilizes a very simplistic partitioning scheme, with all the available RAID storage being mounted at {{ic|/}} (no separate {{ic|/boot}} partition), and the decrypted HDD being mounted at {{ic|/data}}.<br />
<br />
Please note that regular [[System backup|backups]] are very important in this setup. If either of the SSDs fail, the data contained in the RAID array will be practically impossible to recover. You may wish to select a different [[RAID#Standard RAID levels|RAID level]] if fault tolerance is important to you. <br />
<br />
The encryption is not deniable in this setup.<br />
<br />
For the sake of the instructions below, the following block devices are used:<br />
<br />
/dev/sda = first SSD<br />
/dev/sdb = second SSD<br />
/dev/sdc = HDD<br />
<br />
{{Text art|<nowiki><br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
| BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | LUKS2 encrypted volume |<br />
| | | | | | | | | |<br />
| | /efi | / | | | /efi | / | | /data |<br />
| | | | | | | | | |<br />
| | | /dev/mapper/cryptroot | | | | /dev/mapper/cryptroot | | |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ | |<br />
| | RAID1 array (part 1 of 2) | RAID0 array (part 1 of 2) | | | RAID1 array (part 2 of 2) | RAID0 array (part 2 of 2) | | |<br />
| | | | | | | | | |<br />
| | /dev/md/ESP | /dev/md/root | | | /dev/md/ESP | /dev/md/root | | /dev/mapper/cryptroot |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ +---------------------------+<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 | | /dev/sdb1 | /dev/sdb2 | /dev/sdb3 | | /dev/sdc1 |<br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
</nowiki>}}<br />
<br />
Be sure to substitute them with the appropriate device designations for your setup, as they may be different.<br />
<br />
=== Preparing the disks ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] with GPT, create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
In the remaining space on the drive create a partition ({{ic|/dev/sda3}} in this example) for "Linux RAID". Choose partition type ID {{ic|fd}} for MBR or partition type GUID {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} for GPT.<br />
<br />
Once partitions have been created on {{ic|/dev/sda}}, the following commands can be used to clone them to {{ic|/dev/sdb}}.<br />
<br />
# sfdisk -d /dev/sda > sda.dump<br />
# sfdisk /dev/sdb < sda.dump<br />
<br />
The HDD is prepared with a single Linux partition covering the whole drive at {{ic|/dev/sdc1}}.<br />
<br />
=== Building the RAID array ===<br />
<br />
Create the RAID array for the SSDs.<br />
<br />
{{Note|<br />
* All parts of an EFI system partition RAID array must be individually usable, that means that ESP can only placed in a RAID1 array.<br />
* The RAID superblock must be placed at the end of the EFI system partition using {{ic|1=--metadata=1.0}}, otherwise the firmware will not be able to access the partition.<br />
}}<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.0 --raid-devices=2 /dev/md/ESP /dev/sda2 /dev/sdb2<br />
<br />
This example utilizes RAID0 for root, you may wish to substitute a different level based on your preferences or requirements.<br />
<br />
# mdadm --create --verbose --level=0 --metadata=1.2 --raid-devices=2 /dev/md/root /dev/sda3 /dev/sdb3<br />
<br />
=== Preparing the block devices ===<br />
<br />
As explained in [[dm-crypt/Drive preparation]], the devices are wiped with random data utilizing {{ic|/dev/zero}} and a crypt device with a random key. Alternatively, you could use {{ic|dd}} with {{ic|/dev/random}} or {{ic|/dev/urandom}}, though it will be much slower.<br />
<br />
# cryptsetup open --type plain /dev/md/root container --key-file /dev/random<br />
# dd if=/dev/zero of=/dev/mapper/container bs=1M status=progress<br />
# cryptsetup close container<br />
<br />
And repeat above for the HDD ({{ic|/dev/sdc1}} in this example).<br />
<br />
Set up encryption for {{ic|/dev/md/root}}:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup -y -v luksFormat --type luks1 /dev/md/root<br />
# cryptsetup open /dev/md/root cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
And repeat for the HDD:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sdc1<br />
# cryptsetup open /dev/sdc1 cryptdata<br />
# mkfs.ext4 /dev/mapper/cryptdata<br />
# mkdir /mnt/data<br />
# mount /dev/mapper/cryptdata /mnt/data<br />
<br />
For UEFI systems, set up the EFI system partition:<br />
<br />
# mkfs.fat -F32 /dev/md/ESP<br />
# mount /dev/md/ESP /mnt/efi<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure [[GRUB]] for the LUKS1 encrypted system by editing {{ic|/etc/default/grub}} with the following:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/md/root:cryptroot"<br />
GRUB_ENABLE_CRYPTODISK=y<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details.<br />
<br />
Complete the GRUB install to both SSDs (in reality, installing only to {{ic|/dev/sda}} will work).<br />
<br />
# grub-install --target=i386-pc /dev/sda<br />
# grub-install --target=i386-pc /dev/sdb<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Creating the keyfiles ===<br />
<br />
The next steps save you from entering your passphrase twice when you boot the system (once so GRUB can unlock the LUKS1 device, and second time once the initramfs assumes control of the system). This is done by creating a [[dm-crypt/Device encryption#Keyfiles|keyfile]] for the encryption and adding it to the initramfs image to allow the encrypt hook to unlock the root device. See [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] for details.<br />
<br />
* Create the [[dm-crypt/Device encryption#Keyfiles|keyfile]] and add the key to {{ic|/dev/md/root}}.<br />
* Create another keyfile for the HDD ({{ic|/dev/sdc1}}) so it can also be unlocked at boot. For convenience, leave the passphrase created above in place as this can make recovery easier if you ever need it. Edit {{ic|/etc/crypttab}} to decrypt the HDD at boot. See [[Dm-crypt/System configuration#Unlocking with a keyfile]].<br />
<br />
=== Configuring the system ===<br />
<br />
Edit [[fstab]] to mount the cryptroot and cryptdata block devices and the ESP:<br />
<br />
/dev/mapper/cryptroot / ext4 rw,noatime 0 1<br />
/dev/mapper/cryptdata /data ext4 defaults 0 2<br />
/dev/md/ESP /efi vfat rw,relatime,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,tz=UTC,errors=remount-ro 0 2<br />
<br />
Save the RAID configuration:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
Edit [[mkinitcpio.conf]] to include your keyfile and add the proper hooks:<br />
<br />
FILES=(/crypto_keyfile.bin)<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''mdadm_udev''' '''encrypt''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details.<br />
<br />
== Plain dm-crypt ==<br />
<br />
Contrary to LUKS, dm-crypt ''plain'' mode does not require a header on the encrypted device: this scenario exploits this feature to set up a system on an unpartitioned, encrypted disk that will be indistinguishable from a disk filled with random data, which could allow [[Wikipedia:Deniable encryption|deniable encryption]]. See also [[wikipedia:Disk encryption#Full disk encryption]].<br />
<br />
Note that if full-disk encryption is not required, the methods using LUKS described in the sections above are better options for both system encryption and encrypted partitions. LUKS features like key management with multiple passphrases/key-files or re-encrypting a device in-place are unavailable with ''plain'' mode.<br />
<br />
''Plain'' dm-crypt encryption can be more resilient to damage than LUKS, because it does not rely on an encryption master-key which can be a single-point of failure if damaged. However, using ''plain'' mode also requires more manual configuration of encryption options to achieve the same cryptographic strength. See also [[Disk encryption#Cryptographic metadata]]. Using ''plain'' mode could also be considered if concerned with the problems explained in [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]].<br />
<br />
{{Tip|If headerless encryption is your goal but you are unsure about the lack of key-derivation with ''plain'' mode, then two alternatives are:<br />
* [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|dm-crypt LUKS mode with a detached header]] by using the ''cryptsetup'' {{ic|--header}} option. It cannot be used with the standard ''encrypt'' hook, but the hook may be modified.<br />
* [[tcplay]] which offers headerless encryption but with the PBKDF2 function.<br />
}}<br />
<br />
The scenario uses two USB sticks:<br />
<br />
* one for the boot device, which also allows storing the options required to open/unlock the plain encrypted device in the boot loader configuration, since typing them on each boot would be error prone;<br />
* another for the encryption key file, assuming it stored as raw bits so that to the eyes of an unaware attacker who might get the usbkey the encryption key will appear as random data instead of being visible as a normal file. See also [[Wikipedia:Security through obscurity]], follow [[dm-crypt/Device encryption#Keyfiles]] to prepare the keyfile.<br />
<br />
The disk layout is:<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+ +----------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot device | | Encryption key |<br />
| | | | | | | file storage |<br />
| / | [SWAP] | /home | | /boot | | (unpartitioned |<br />
| | | | | | | in example) |<br />
| /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home | | /dev/sdb1 | | /dev/sdc |<br />
|----------------------+----------------------+----------------------| |----------------| |----------------|<br />
| disk drive /dev/sda encrypted using plain mode and LVM | | USB stick 1 | | USB stick 2 |<br />
+--------------------------------------------------------------------+ +----------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* It is also possible to use a single USB key physical device:<br />
** By putting the key on another partition (/dev/sdb2) of the USB storage device (/dev/sdb).<br />
** By copying the keyfile to the initramfs directly. An example keyfile {{ic|/etc/keyfile}} gets copied to the initramfs image by setting {{ic|1=FILES=(/etc/keyfile)}} in {{ic|/etc/mkinitcpio.conf}}. The way to instruct the {{ic|encrypt}} hook to read the keyfile in the initramfs image is using {{ic|rootfs:}} prefix before the filename, e.g. {{ic|1=cryptkey=rootfs:/etc/keyfile}}.<br />
* Another option is using a passphrase with good [[Disk encryption#Choosing a strong passphrase|entropy]].<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
It is vital that the mapped device is filled with random data. In particular this applies to the scenario use case we apply here.<br />
<br />
See [[dm-crypt/Drive preparation]] and [[dm-crypt/Drive preparation#dm-crypt specific methods]]<br />
<br />
=== Preparing the non-boot partitions ===<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for plain mode]] for details.<br />
<br />
Using the device {{ic|/dev/sda}}, with the aes-xts cipher with a 512 bit key size and using a keyfile we have the following options for this scenario:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sdc --key-size=512 open --type plain /dev/sda cryptlvm<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, and key file details.<br />
<br />
We can now check a mapping entry has been made for {{ic|/dev/mapper/cryptlvm}}:<br />
<br />
# fdisk -l<br />
<br />
{{Tip|A simpler alternative to using LVM, advocated in the cryptsetup FAQ for cases where LVM is not necessary, is to just create a filesystem on the entirety of the mapped dm-crypt device.}} <br />
<br />
Next, we setup [[LVM]] logical volumes on the mapped device. See [[LVM#Installing Arch Linux on LVM]] for further details:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -L 10G MyVolGroup -n swap<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
We format and mount them and activate swap. See [[File systems#Create a file system]] for further details:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# mkswap /dev/MyVolGroup/swap<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The {{ic|/boot}} partition can be installed on the standard vfat partition of a USB stick, if required. But if manual partitioning is needed, then a small 200 MiB partition is all that is required. Create the partition using a [[Partitioning#Partitioning tools|partitioning tool]] of your choice.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}, if it is not already formatted as vfat:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
# mkdir /mnt/boot<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to boot the encrypted root partition, the following [[kernel parameters]] need to be set by the boot loader (note that 64 is the number of bytes in 512 bits):<br />
<br />
cryptdevice=/dev/disk/by-id/''disk-ID-of-sda'':cryptlvm cryptkey=/dev/disk/by-id/''disk-ID-of-sdc'':0:64 crypto=:aes-xts-plain64:512:0:<br />
<br />
The {{ic|''disk-ID-of-'''disk'''''}} refers to the id of the referenced disk. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details and other parameters that you may need.<br />
<br />
{{Tip|If using GRUB, you can install it on the same USB as the {{ic|/boot}} partition with:<br />
<br />
# grub-install --recheck /dev/sdb<br />
<br />
}}<br />
<br />
=== Post-installation ===<br />
<br />
You may wish to remove the USB sticks after booting. Since the {{ic|/boot}} partition is not usually needed, the {{ic|noauto}} option can be added to the relevant line in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
# /dev/sdb1<br />
/dev/sdb1 /boot ext4 '''noauto''',rw,noatime 0 2<br />
}}<br />
<br />
However, when an update to anything used in the initramfs, or a kernel, or the bootloader is required; the {{ic|/boot}} partition must be present and mounted. As the entry in {{ic|fstab}} already exists, it can be mounted simply with:<br />
<br />
# mount /boot<br />
<br />
== Encrypted boot partition (GRUB) ==<br />
<br />
This setup utilizes the same partition layout and configuration for the system's root partition as the previous [[#LVM on LUKS]] section, with the difference that a special feature of the [[GRUB]] bootloader is used to additionally encrypt the boot partition {{ic|/boot}}. See also [[GRUB#Encrypted /boot]].<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+---------------------+----------------------+----------------------+----------------------+----------------------+<br />
| BIOS boot partition | EFI system partition | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | | | | |<br />
| | /efi | / | [SWAP] | /home |<br />
| | | | | |<br />
| | | /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home |<br />
| /dev/sda1 | /dev/sda2 |----------------------+----------------------+----------------------+<br />
| unencrypted | unencrypted | /dev/sda3 encrypted using LVM on LUKS1 |<br />
+---------------------+----------------------+--------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* All scenarios are intended as examples. It is, of course, possible to apply both of the two above distinct installation steps with the other scenarios as well. See also the variants linked in [[#LVM on LUKS]].<br />
* You can use {{ic|cryptboot}} script from {{AUR|cryptboot}} package for simplified encrypted boot management (mounting, unmounting, upgrading packages) and as a defense against [https://www.schneier.com/blog/archives/2009/10/evil_maid_attac.html Evil Maid] attacks with [[Secure Boot#Using your own keys|UEFI Secure Boot]]. For more information and limitations see [https://github.com/xmikos/cryptboot cryptboot project] page.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
Create a partition of type {{ic|8309}}, which will later contain the encrypted container for the LVM.<br />
<br />
Create the LUKS encrypted container:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup luksFormat --type luks1 /dev/sda3<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Your partition layout should look similar to this:<br />
<br />
{{hc|# gdisk -l /dev/sda|<br />
...<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 4095 1024.0 KiB EF02 BIOS boot partition<br />
2 4096 1130495 550.0 MiB EF00 EFI System<br />
3 1130496 68239360 32.0 GiB 8309 Linux LUKS<br />
}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda3 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
The LVM logical volumes of this example follow the exact layout as the [[#LVM on LUKS]] scenario. Therefore, please follow [[#Preparing the logical volumes]] above and adjust as required.<br />
<br />
If you plan to boot in UEFI mode, create a mountpoint for the [[EFI system partition]] at {{ic|/efi}} for compatibility with {{ic|grub-install}} and mount it:<br />
<br />
# mkdir /mnt/efi<br />
# mount /dev/sda2 /mnt/efi<br />
<br />
At this point, you should have the following partitions and logical volumes inside of {{ic|/mnt}}:<br />
<br />
{{hc|$ lsblk|<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 200G 0 disk<br />
├─sda1 8:1 0 1M 0 part<br />
├─sda2 8:2 0 550M 0 part /mnt/efi<br />
└─sda3 8:3 0 100G 0 part<br />
└─cryptlvm 254:0 0 100G 0 crypt<br />
├─MyVolGroup-swap 254:1 0 8G 0 lvm [SWAP]<br />
├─MyVolGroup-root 254:2 0 32G 0 lvm /mnt<br />
└─MyVolGroup-home 254:3 0 60G 0 lvm /mnt/home<br />
}}<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure GRUB to allow booting from {{ic|/boot}} on a LUKS1 encrypted partition:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_ENABLE_CRYPTODISK=y<br />
}}<br />
<br />
Set the kernel parameters, so that the initramfs can unlock the encrypted root partition. Using the {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... cryptdevice=UUID=''device-UUID'':cryptlvm ..."<br />
}}<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... rd.luks.name=''device-UUID''=cryptlvm ..."<br />
}}<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details. The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda3}} (the partition which holds the lvm containing the root filesystem). See [[Persistent block device naming]].<br />
<br />
[[GRUB#Installation_2|install GRUB]] to the mounted ESP for UEFI booting:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB --recheck<br />
<br />
[[GRUB#Installation|install GRUB]] to the disk for BIOS booting:<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
<br />
Generate GRUB's [[GRUB#Generate the main configuration file|configuration]] file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If all commands finished without errors, GRUB should prompt for the passphrase to unlock the {{ic|/dev/sda3}} partition after the next reboot.<br />
<br />
=== Avoiding having to enter the passphrase twice ===<br />
<br />
{{Merge|Dm-crypt/Device encryption#With a keyfile embedded in the initramfs|Too much duplicated content, too much detail here for this overview page.|section=Security Issue with Grub Keyfile}}<br />
<br />
While GRUB asks for a passphrase to unlock the LUKS1 encrypted partition after above instructions, the partition unlock is not passed on to the initramfs. Hence, you have to enter the passphrase twice at boot: once for GRUB and once for the initramfs.<br />
<br />
This section deals with extra configuration to let the system boot by only entering the passphrase once, in GRUB. This is accomplished by [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs|with a keyfile embedded in the initramfs]].<br />
<br />
First create a keyfile and add it as LUKS key:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/root/cryptlvm.keyfile iflag=fullblock<br />
# chmod 000 /root/cryptlvm.keyfile<br />
# chmod 600 /boot/initramfs-linux*<br />
# cryptsetup -v luksAddKey /dev/sda3 /root/cryptlvm.keyfile<br />
<br />
Add the keyfile to the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/root/cryptlvm.keyfile)<br />
}}<br />
<br />
Set the following kernel parameters to unlock the LUKS partition with the keyfile. Using the {{ic|encrypt}} hook:<br />
<br />
GRUB_CMDLINE_LINUX="... cryptkey=rootfs:/root/cryptlvm.keyfile"<br />
<br />
Or, using the [[sd-encrypt]] hook:<br />
<br />
GRUB_CMDLINE_LINUX="... rd.luks.key=''device-UUID''=/root/cryptlvm.keyfile"<br />
<br />
If for some reason the keyfile fails to unlock the boot partition, systemd will fallback to ask for a passphrase to unlock and, in case that is correct, continue booting.<br />
<br />
{{Tip|If you want to encrypt the {{ic|/boot}} partition to protect against offline tampering threats, the [[dm-crypt/Specialties#mkinitcpio-chkcryptoboot|mkinitcpio-chkcryptoboot]] hook has been contributed to help.}}<br />
<br />
== Btrfs subvolumes with swap ==<br />
<br />
The following example creates a full system encryption with LUKS1 using [[Btrfs]] subvolumes to [[Btrfs#Mounting subvolumes|simulate partitions]].<br />
<br />
If using UEFI, an [[EFI system partition]] (ESP) is required. {{ic|/boot}} itself may reside on {{ic|/}} and be encrypted; however, the ESP itself cannot be encrypted. In this example layout, the ESP is {{ic|/dev/sda1}} and is mounted at {{ic|/efi}}. {{ic|/boot}} itself is located on the system partition, {{ic|/dev/sda2}}.<br />
<br />
Since {{ic|/boot}} resides on the LUKS1 encrypted {{ic|/}}, [[GRUB]] must be used as the bootloader because only GRUB can load modules necessary to decrypt {{ic|/boot}} (e.g., crypto.mod, cryptodisk.mod and luks.mod).<br />
<br />
Additionally an optional plain-encrypted [[swap]] partition is shown.<br />
<br />
{{Warning|Do not use a [[swap file]] instead of a separate partition on Linux kernels before v5.0, because this may result in data loss. See [[Btrfs#Swap file]].}}<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+<br />
| EFI system partition | System partition | Swap partition |<br />
| unencrypted | LUKS1-encrypted | plain-encrypted |<br />
| | | |<br />
| /efi | / | [SWAP] |<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 |<br />
|----------------------+----------------------+----------------------+<br />
</nowiki>}}<br />
<br />
=== Preparing the disk ===<br />
<br />
{{Note|It is not possible to use btrfs partitioning as described in [[Btrfs#Partitionless Btrfs disk]] when using LUKS. Traditional partitioning must be used, even if it is just to create one partition.}}<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]]. If you are using [[UEFI]] create an [[EFI system partition]] with an appropriate size. It will later be mounted at {{ic|/efi}}. If you are going to create an encrypted swap partition, create the partition for it, but do '''not''' mark it as swap, since plain ''dm-crypt'' will be used with the partition.<br />
<br />
Create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}). See the [[Partitioning]] article.<br />
<br />
=== Preparing the system partition ===<br />
<br />
==== Create LUKS container ====<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
Follow [[dm-crypt/Device encryption#Encrypting devices with LUKS mode]] to setup {{ic|/dev/sda2}} for LUKS. See the [[dm-crypt/Device encryption#Encryption options for LUKS mode]] before doing so for a list of encryption options.<br />
<br />
==== Unlock LUKS container ====<br />
<br />
Now follow [[dm-crypt/Device encryption#Unlocking/Mapping LUKS partitions with the device mapper]] to unlock the LUKS container and map it.<br />
<br />
==== Format mapped device ====<br />
<br />
Proceed to format the mapped device as described in [[Btrfs#File system on a single device]], where {{ic|''/dev/partition''}} is the name of the mapped device (i.e., {{ic|cryptroot}}) and '''not''' {{ic|/dev/sda2}}.<br />
<br />
==== Mount mapped device ====<br />
<br />
Finally, [[mount]] the now-formatted mapped device (i.e., {{ic|/dev/mapper/cryptroot}}) to {{ic|/mnt}}.<br />
<br />
{{Tip|You may want to use the {{ic|1=compress=lzo}} mount option. See [[Btrfs#Compression]] for more information.}}<br />
<br />
=== Creating btrfs subvolumes ===<br />
<br />
{{Merge|Btrfs|The subvolume layout is not specific to an encrypted system.}}<br />
<br />
==== Layout ====<br />
<br />
[[Btrfs#Subvolumes|Subvolumes]] will be used to simulate partitions, but other (nested) subvolumes will also be created. Here is a partial representation of what the following example will generate:<br />
<br />
{{Text art|<nowiki><br />
subvolid=5 (/dev/sda2)<br />
|<br />
├── @ (mounted as /)<br />
| |<br />
| ├── /bin (directory)<br />
| |<br />
| ├── /home (mounted @home subvolume)<br />
| |<br />
| ├── /usr (directory)<br />
| |<br />
| ├── /.snapshots (mounted @snapshots subvolume)<br />
| |<br />
| ├── /var/cache/pacman/pkg (nested subvolume)<br />
| |<br />
| ├── ... (other directories and nested subvolumes)<br />
|<br />
├── @snapshots (mounted as /.snapshots)<br />
|<br />
├── @home (mounted as /home)<br />
|<br />
└── @... (additional subvolumes you wish to use as mount points)<br />
</nowiki>}}<br />
<br />
This section follows the [[Snapper#Suggested filesystem layout]], which is most useful when used with [[Snapper]]. You should also consult [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs Wiki SysadminGuide#Layout].<br />
<br />
==== Create top-level subvolumes ====<br />
<br />
Here we are using the convention of prefixing {{ic|@}} to subvolume names that will be used as mount points, and {{ic|@}} will be the subvolume that is mounted as {{ic|/}}.<br />
<br />
Following the [[Btrfs#Creating a subvolume]] article, create subvolumes at {{ic|/mnt/@}}, {{ic|/mnt/@snapshots}}, and {{ic|/mnt/@home}}.<br />
<br />
Create any additional subvolumes you wish to use as mount points now.<br />
<br />
==== Mount top-level subvolumes ====<br />
<br />
Unmount the system partition at {{ic|/mnt}}.<br />
<br />
Now mount the newly created {{ic|@}} subvolume which will serve as {{ic|/}} to {{ic|/mnt}} using the {{ic|1=subvol=}} mount option. Assuming the mapped device is named {{ic|cryptroot}}, the command would look like:<br />
<br />
# mount -o compress=lzo,subvol=@ /dev/mapper/cryptroot /mnt<br />
<br />
See [[Btrfs#Mounting subvolumes]] for more details.<br />
<br />
Also mount the other subvolumes to their respective mount points: {{ic|@home}} to {{ic|/mnt/home}} and {{ic|@snapshots}} to {{ic|/mnt/.snapshots}}.<br />
<br />
==== Create nested subvolumes ====<br />
<br />
Create any subvolumes you do '''not''' want to have snapshots of when taking a snapshot of {{ic|/}}. For example, you probably do not want to take snapshots of {{ic|/var/cache/pacman/pkg}}. These subvolumes will be nested under the {{ic|@}} subvolume, but just as easily could have been created earlier at the same level as {{ic|@}} according to your preference.<br />
<br />
Since the {{ic|@}} subvolume is mounted at {{ic|/mnt}} you will need to [[create a subvolume]] at {{ic|/mnt/var/cache/pacman/pkg}} for this example. You may have to create any parent directories first.<br />
<br />
Other directories you may wish to do this with are {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.<br />
<br />
==== Mount ESP ====<br />
<br />
If you prepared an EFI system partition earlier, create its mount point and mount it now.<br />
<br />
{{Note|Btrfs snapshots will exclude {{ic|/efi}}, since it is not a btrfs file system.}}<br />
<br />
At the [[Installation guide#Install the base packages|pacstrap]] installation step, the {{Pkg|btrfs-progs}} must be installed in addition to the base group.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
==== Create keyfile ====<br />
<br />
In order for GRUB to open the LUKS partition without having the user enter his passphrase twice, we will use a keyfile embedded in the initramfs. Follow [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] making sure to add the key to {{ic|/dev/sda2}} at the ''luksAddKey'' step.<br />
<br />
==== Edit mkinitcpio.conf ====<br />
<br />
After creating, adding, and embedding the key as described above, add the {{ic|encrypt}} hook to [[mkinitcpio.conf]] as well as any other hooks you require. See [[dm-crypt/System configuration#mkinitcpio]] for detailed information.<br />
<br />
{{Tip|You may want to add {{ic|1=BINARIES=(/usr/bin/btrfs)}} to your {{ic|mkinitcpio.conf}}. See the [[Btrfs#Corruption recovery]] article.}}<br />
<br />
=== Configuring the boot loader ===<br />
<br />
Install [[GRUB]] to {{ic|/dev/sda}}. Then, edit {{ic|/etc/default/grub}} as instructed in the [[GRUB#Additional arguments]] and [[GRUB#Encrypted /boot]], following both the instructions for an encrypted root and boot partition. Finally, generate the GRUB configuration file.<br />
<br />
=== Configuring swap ===<br />
<br />
If you created a partition to be used for encrypted swap, now is the time to configure it. Follow the instructions at [[dm-crypt/Swap encryption]].</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=580937Dm-crypt/Encrypting an entire system2019-08-25T15:35:55Z<p>EasyToRemember: /* Preparing the logical volumes */ Updated actual mounts points in lsblk output</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[Category:Installation process]]<br />
[[de:Systemverschlüsselung mit dm-crypt]]<br />
[[es:Dm-crypt/Encrypting an entire system]]<br />
[[ja:Dm-crypt/システム全体の暗号化]]<br />
[[pl:Dm-crypt/Encrypting an entire system]]<br />
<br />
The following are examples of common scenarios of full system encryption with ''dm-crypt''. They explain all the adaptations that need to be done to the normal [[Installation guide|installation procedure]]. All the necessary tools are on the [https://www.archlinux.org/download/ installation image].<br />
<br />
== Overview ==<br />
<br />
Securing a root filesystem is where ''dm-crypt'' excels, feature and performance-wise. Unlike selectively encrypting non-root filesystems, an encrypted root filesystem can conceal information such as which programs are installed, the usernames of all user accounts, and common data-leakage vectors such as [[mlocate]] and {{ic|/var/log/}}. Furthermore, an encrypted root filesystem makes tampering with the system far more difficult, as everything except the [[boot loader]] and (usually) the kernel is encrypted.<br />
<br />
All scenarios illustrated in the following share these advantages, other pros and cons differentiating them are summarized below:<br />
<br />
{| class="wikitable"<br />
! Scenarios<br />
! Advantages<br />
! Disadvantages<br />
|----------------------------------------------------------<br />
| [[#LUKS on a partition]]<br />
shows a basic and straight-forward set-up for a fully LUKS encrypted root.<br />
|<br />
* Simple partitioning and setup<br />
|<br />
* Inflexible; disk-space to be encrypted has to be pre-allocated<br />
|----------------------------------------------------------<br />
| [[#LVM on LUKS]]<br />
achieves partitioning flexibility by using LVM inside a single LUKS encrypted partition.<br />
|<br />
* Simple partitioning with knowledge of LVM<br />
* Only one key required to unlock all volumes (e.g. easy resume-from-disk setup)<br />
* Volume layout not transparent when locked<br />
* Easiest method to allow [[dm-crypt/Swap encryption#With suspend-to-disk support|suspension to disk]]<br />
|<br />
* LVM adds an additional mapping layer and hook<br />
* Less useful, if a singular volume should receive a separate key<br />
|----------------------------------------------------------<br />
| [[#LUKS on LVM]]<br />
uses dm-crypt only after the LVM is setup.<br />
|<br />
* LVM can be used to have encrypted volumes span multiple disks<br />
* Easy mix of un-/encrypted volume groups<br />
|<br />
* Complex; changing volumes requires changing encryption mappers too<br />
* Volumes require individual keys<br />
* LVM layout is transparent when locked<br />
|----------------------------------------------------------<br />
| [[#LUKS on software RAID]]<br />
uses dm-crypt only after RAID is setup.<br />
|<br />
* Analogous to LUKS on LVM<br />
|<br />
* Analogous to LUKS on LVM<br />
|----------------------------------------------------------<br />
| [[#Plain dm-crypt]]<br />
uses dm-crypt plain mode, i.e. without a LUKS header and its options for multiple keys. <br>This scenario also employs USB devices for {{ic|/boot}} and key storage, which may be applied to the other scenarios.<br />
|<br />
* Data resilience for cases where a LUKS header may be damaged<br />
* Allows [[Wikipedia:Disk encryption#Full disk encryption|Full Disk Encryption]]<br />
* Helps addressing [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)|problems]] with SSDs<br />
|<br />
* High care to all encryption parameters is required<br />
* Single encryption key and no option to change it<br />
|----------------------------------------------------------<br />
| [[#Encrypted boot partition (GRUB)]]<br />
shows how to encrypt the boot partition using the GRUB bootloader. <br> This scenario also employs an EFI system partition, which may be applied to the other scenarios.<br />
|<br />
* Same advantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* Less data is left unencrypted, i.e. the boot loader and the EFI system partition, if present<br />
|<br />
* Same disadvantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* More complicated configuration<br />
* Not supported by other boot loaders<br />
|----------------------------------------------------------<br />
| [[#Btrfs subvolumes with swap]]<br />
shows how to encrypt a [[Btrfs]] system, including the {{ic|/boot}} directory, also adding a partition for swap, on UEFI hardware.<br />
|<br />
* Similar advantages as [[#Encrypted boot partition (GRUB)]]<br />
* Availability of Btrfs' features<br />
|<br />
* Similar disadvantages as [[#Encrypted boot partition (GRUB)]]<br />
|}<br />
<br />
While all above scenarios provide much greater protection from outside threats than encrypted secondary filesystems, they also share a common disadvantage: any user in possession of the encryption key is able to decrypt the entire drive, and therefore can access other users' data. If that is of concern, it is possible to use a combination of blockdevice and stacked filesystem encryption and reap the advantages of both. See [[Disk encryption]] to plan ahead.<br />
<br />
See [[dm-crypt/Drive preparation#Partitioning]] for a general overview of the partitioning strategies used in the scenarios.<br />
<br />
Another area to consider is whether to set up an encrypted swap partition and what kind. See [[dm-crypt/Swap encryption]] for alternatives.<br />
<br />
If you anticipate to protect the system's data not only against physical theft, but also have a requirement of precautions against logical tampering, see [[dm-crypt/Specialties#Securing the unencrypted boot partition]] for further possibilities after following one of the scenarios.<br />
<br />
For [[solid state drive]]s you might want to consider enabling TRIM support, but be warned, there are potential security implications. See [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]] for more information.<br />
<br />
{{Warning|<br />
* In any scenario, never use file system repair software such as [[fsck]] directly on an encrypted volume, or it will destroy any means to recover the key used to decrypt your files. Such tools must be used on the decrypted (opened) device instead.<br />
* For the LUKS2 format:<br />
** [[GRUB]] does not support LUKS2.[https://savannah.gnu.org/bugs/?55093] Use LUKS1 on partitions that GRUB needs to access.<br />
** The LUKS2 format has a high RAM usage per design, defaulting to 1GB per encrypted mapper. Machines with low RAM and/or multiple LUKS2 partitions unlocked in parallel may error on boot. See the {{ic|--pbkdf-memory}} option to control memory usage.[https://gitlab.com/cryptsetup/cryptsetup/issues/372]<br />
}}<br />
<br />
== LUKS on a partition ==<br />
<br />
This example covers a full system encryption with ''dm-crypt'' + LUKS in a simple partition layout:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------+------------------------+-----------------------+<br />
| Boot partition | LUKS2 encrypted system | Optional free space |<br />
| | partition | for additional |<br />
| | | partitions or swap |<br />
| /boot | / | to be setup later |<br />
| | | |<br />
| | /dev/mapper/cryptroot | |<br />
| |------------------------| |<br />
| /dev/sda1 | /dev/sda2 | |<br />
+-----------------------+------------------------+-----------------------+<br />
</nowiki>}}<br />
<br />
The first steps can be performed directly after booting the Arch Linux install image.<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
Then create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}) and {{ic|/boot}} ({{ic|/dev/sda1}}). See [[Partitioning]].<br />
<br />
=== Preparing non-boot partitions ===<br />
<br />
The following commands create and mount the encrypted root partition. They correspond to the procedure described in detail in [[dm-crypt/Encrypting a non-root file system#Partition]] (which, despite the title, ''can'' be applied to root partitions, as long as [[#Configuring mkinitcpio|mkinitcpio]] and the [[#Configuring the boot loader|boot loader]] are correctly configured).<br />
If you want to use particular non-default encryption options (e.g. cipher, key length), see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|encryption options]] before executing the first command:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sda2<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
Check the mapping works as intended:<br />
<br />
# umount /mnt<br />
# cryptsetup close cryptroot<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
If you created separate partitions (e.g. {{ic|/home}}), these steps have to be adapted and repeated for all of them, ''except'' for {{ic|/boot}}. See [[dm-crypt/Encrypting a non-root file system#Automated unlocking and mounting]] on how to handle additional partitions at boot.<br />
<br />
Note that each blockdevice requires its own passphrase. This may be inconvenient, because it results in a separate passphrase to be input during boot. An alternative is to use a keyfile stored in the system partition to unlock the separate partition via {{ic|crypttab}}. See [[dm-crypt/Device encryption#Using LUKS to format partitions with a keyfile]] for instructions.<br />
<br />
=== Preparing the boot partition ===<br />
<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a encrypted root. For an ordinary boot partition on BIOS systems, for example, execute:<br />
<br />
# mkfs.ext4 /dev/sda1<br />
<br />
or for an [[EFI system partition]] on UEFI systems:<br />
<br />
# mkfs.fat -F32 /dev/sda1<br />
<br />
Afterwards create the directory for the mounpoint and mount the partition:<br />
<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Mounting the devices ===<br />
<br />
At [[Installation guide#Mount the file systems]] you will have to mount the mapped devices, not the actual partitions. Of course {{ic|/boot}}, which is not encrypted, will still have to be mounted directly.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|keymap}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]. If the default US keymap is fine for you, you can omit the {{ic|keymap}} hook.<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' filesystems fsck)<br />
<br />
Depending on which other hooks are used, the order may be relevant. See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptroot root=/dev/mapper/cryptroot<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptroot root=/dev/mapper/cryptroot<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda2}}. See [[Persistent block device naming]] for details.<br />
<br />
== LVM on LUKS ==<br />
<br />
The straight-forward method is to set up [[LVM]] on top of the encrypted partition instead of the other way round. Technically the LVM is setup inside one big encrypted blockdevice. Hence, the LVM is not transparent until the blockdevice is unlocked and the underlying volume structure is scanned and mounted during boot.<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------------------------------------------------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot partition |<br />
| | | | | |<br />
| [SWAP] | / | /home | | /boot |<br />
| | | | | |<br />
| /dev/MyVolGroup/swap | /dev/MyVolGroup/root | /dev/MyVolGroup/home | | |<br />
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _| | (may be on |<br />
| | | other device) |<br />
| LUKS2 encrypted partition | | |<br />
| /dev/sda1 | | /dev/sdb1 |<br />
+-----------------------------------------------------------------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Note|While using the {{ic|encrypt}} hook this method does not allow you to span the logical volumes over multiple disks; either use the [[sd-encrypt]] or see [[dm-crypt/Specialties#Modifying the encrypt hook for multiple partitions]].}}<br />
<br />
{{Tip|Two variants of this setup:<br />
* Instructions at [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] use this setup with a detached LUKS header on a USB device to achieve a two factor authentication with it.<br />
* Instructions at [[dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB]] use this setup with a detached LUKS header, encrypted {{ic|/boot}} partition, and encrypted keyfile all on a USB device.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
{{Tip|When using the [[GRUB]] boot loader for BIOS booting from a [[GPT]] disk, create a [[BIOS boot partition]].}}<br />
<br />
Create a partition to be mounted at {{ic|/boot}} with a size of 200 MiB or more.<br />
<br />
{{Tip|UEFI systems can use the [[EFI system partition]] for {{ic|/boot}}.}}<br />
<br />
Create a partition which will later contain the encrypted container.<br />
<br />
Create the LUKS encrypted container at the "system" partition. Enter the chosen password twice.<br />
<br />
# cryptsetup luksFormat /dev/sda1<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda1 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
Create a physical volume on top of the opened LUKS container:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
<br />
Create the volume group named {{ic|MyVolGroup}} (or whatever you want), adding the previously created physical volume to it:<br />
<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
<br />
Create all your logical volumes on the volume group:<br />
<br />
# lvcreate -L 8G MyVolGroup -n swap<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
Format your filesystems on each logical volume:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mkswap /dev/MyVolGroup/swap<br />
<br />
Mount your filesystems:<br />
<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The bootloader loads the kernel, [[initramfs]], and its own configuration files from the {{ic|/boot}} directory. Any filesystem on a disk that can be read by the bootloader is eligible.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
<br />
{{Tip|When opting to keep {{ic|/boot}} on an [[EFI system partition]] the recommended formatting is<br />
<br />
# mkfs.fat -F32 /dev/sdb1<br />
<br />
}}<br />
<br />
Create the directory {{ic|/mnt/boot}}:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Mount the partition to {{ic|/mnt/boot}}:<br />
<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameter needs to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptlvm root=/dev/MyVolGroup/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptlvm root=/dev/MyVolGroup/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda1}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
== LUKS on LVM ==<br />
<br />
To use encryption on top of [[LVM]], the LVM volumes are set up first and then used as the base for the encrypted partitions. This way, a mixture of encrypted and non-encrypted volumes/partitions is possible as well.<br />
{{tip|Unlike [[#LVM on LUKS]], this method allows normally spanning the logical volumes over multiple disks. }}<br />
<br />
The following short example creates a LUKS on LVM setup and mixes in the use of a key-file for the /home partition and temporary crypt volumes for {{ic|/tmp}} and {{ic|/swap}}. The latter is considered desirable from a security perspective, because no potentially sensitive temporary data survives the reboot, when the encryption is re-initialised. If you are experienced with LVM, you will be able to ignore/replace LVM and other specifics according to your plan.<br />
<br />
If you want to span a logical volume over multiple disks that have already been set up, or expand the logical volume for {{ic|/home}} (or any other volume), a procedure to do so is described in [[dm-crypt/Specialties#Expanding LVM on multiple disks]]. It is important to note that the LUKS encrypted container has to be resized as well.<br />
<br />
{{Expansion|The intro of this scenario needs some adjustment now that a comparison has been added to [[#Overview]]. A suggested structure is to make it similar to the [[#LUKS on a partition]] intro.}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Partitioning scheme:<br />
<br />
{{Text art|<nowiki><br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
| Boot partition | dm-crypt plain encrypted volume | LUKS2 encrypted volume | LUKS2 encrypted volume |<br />
| | | | |<br />
| /boot | [SWAP] | / | /home |<br />
| | | | |<br />
| | /dev/mapper/swap | /dev/mapper/root | /dev/mapper/home |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | /dev/MyVolGroup/cryptswap | /dev/MyVolGroup/cryptroot | /dev/MyVolGroup/crypthome |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | |<br />
| /dev/sda1 | /dev/sda2 |<br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
Randomise {{ic|/dev/sda2}} according to [[dm-crypt/Drive preparation#dm-crypt wipe on an empty disk or partition]].<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
# pvcreate /dev/sda2<br />
# vgcreate MyVolGroup /dev/sda2<br />
# lvcreate -L 32G -n cryptroot MyVolGroup<br />
# lvcreate -L 500M -n cryptswap MyVolGroup<br />
# lvcreate -L 500M -n crypttmp MyVolGroup<br />
# lvcreate -l 100%FREE -n crypthome MyVolGroup<br />
<br />
# cryptsetup luksFormat /dev/MyVolGroup/cryptroot<br />
# cryptsetup open /dev/MyVolGroup/cryptroot root<br />
# mkfs.ext4 /dev/mapper/root<br />
# mount /dev/mapper/root /mnt<br />
<br />
More information about the encryption options can be found in [[dm-crypt/Device encryption#Encryption options for LUKS mode]].<br />
Note that {{ic|/home}} will be encrypted in [[#Encrypting logical volume /home]].<br />
<br />
{{Tip|If you ever have to access the encrypted root from the Arch-ISO, the above {{ic|open}} action will allow you to after the [[LVM#Logical Volumes do not show up|LVM shows up]].}}<br />
<br />
=== Preparing the boot partition ===<br />
<br />
# dd if=/dev/zero of=/dev/sda1 bs=1M status=progress<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|lvm2}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''lvm2''' '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':root root=/dev/mapper/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=root root=/dev/mapper/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/MyVolGroup/cryptroot}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
=== Configuring fstab and crypttab ===<br />
<br />
Both [[crypttab]] and [[fstab]] entries are required to both unlock the device and mount the filesystems, respectively. The following lines will re-encrypt the temporary filesystems on each reboot:<br />
<br />
{{hc|/etc/crypttab|2=<br />
swap /dev/MyVolGroup/cryptswap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
tmp /dev/MyVolGroup/crypttmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/root / ext4 defaults 0 1<br />
/dev/sda1 /boot ext4 defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
}}<br />
<br />
=== Encrypting logical volume /home ===<br />
<br />
Since this scenario uses LVM as the primary and dm-crypt as secondary mapper, each encrypted logical volume requires its own encryption. Yet, unlike the temporary filesystems configured with volatile encryption above, the logical volume for {{ic|/home}} should of course be persistent. The following assumes you have rebooted into the installed system, otherwise you have to adjust paths.<br />
To save on entering a second passphrase at boot, a [[dm-crypt/Device encryption#Keyfiles|keyfile]] is created:<br />
<br />
# mkdir -m 700 /etc/luks-keys<br />
# dd if=/dev/random of=/etc/luks-keys/home bs=1 count=256 status=progress<br />
<br />
The logical volume is encrypted with it:<br />
<br />
# cryptsetup luksFormat -v /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
# cryptsetup -d /etc/luks-keys/home open /dev/MyVolGroup/crypthome home<br />
# mkfs.ext4 /dev/mapper/home<br />
# mount /dev/mapper/home /home<br />
<br />
The encrypted mount is configured in both [[crypttab]] and [[fstab]]:<br />
<br />
{{hc|/etc/crypttab|<br />
home /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home /home ext4 defaults 0 2<br />
}}<br />
<br />
== LUKS on software RAID ==<br />
<br />
This example is based on a real-world setup for a workstation class laptop equipped with two SSDs of equal size, and an additional HDD for bulk storage. The end result is LUKS1 based full disk encryption (including {{ic|/boot}}) for all drives, with the SSDs in a [[RAID|RAID0]] array, and keyfiles used to unlock all encryption after [[GRUB]] is given a correct passphrase at boot.<br />
<br />
This setup utilizes a very simplistic partitioning scheme, with all the available RAID storage being mounted at {{ic|/}} (no separate {{ic|/boot}} partition), and the decrypted HDD being mounted at {{ic|/data}}.<br />
<br />
Please note that regular [[System backup|backups]] are very important in this setup. If either of the SSDs fail, the data contained in the RAID array will be practically impossible to recover. You may wish to select a different [[RAID#Standard RAID levels|RAID level]] if fault tolerance is important to you. <br />
<br />
The encryption is not deniable in this setup.<br />
<br />
For the sake of the instructions below, the following block devices are used:<br />
<br />
/dev/sda = first SSD<br />
/dev/sdb = second SSD<br />
/dev/sdc = HDD<br />
<br />
{{Text art|<nowiki><br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
| BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | LUKS2 encrypted volume |<br />
| | | | | | | | | |<br />
| | /efi | / | | | /efi | / | | /data |<br />
| | | | | | | | | |<br />
| | | /dev/mapper/cryptroot | | | | /dev/mapper/cryptroot | | |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ | |<br />
| | RAID1 array (part 1 of 2) | RAID0 array (part 1 of 2) | | | RAID1 array (part 2 of 2) | RAID0 array (part 2 of 2) | | |<br />
| | | | | | | | | |<br />
| | /dev/md/ESP | /dev/md/root | | | /dev/md/ESP | /dev/md/root | | /dev/mapper/cryptroot |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ +---------------------------+<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 | | /dev/sdb1 | /dev/sdb2 | /dev/sdb3 | | /dev/sdc1 |<br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
</nowiki>}}<br />
<br />
Be sure to substitute them with the appropriate device designations for your setup, as they may be different.<br />
<br />
=== Preparing the disks ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] with GPT, create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
In the remaining space on the drive create a partition ({{ic|/dev/sda3}} in this example) for "Linux RAID". Choose partition type ID {{ic|fd}} for MBR or partition type GUID {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} for GPT.<br />
<br />
Once partitions have been created on {{ic|/dev/sda}}, the following commands can be used to clone them to {{ic|/dev/sdb}}.<br />
<br />
# sfdisk -d /dev/sda > sda.dump<br />
# sfdisk /dev/sdb < sda.dump<br />
<br />
The HDD is prepared with a single Linux partition covering the whole drive at {{ic|/dev/sdc1}}.<br />
<br />
=== Building the RAID array ===<br />
<br />
Create the RAID array for the SSDs.<br />
<br />
{{Note|<br />
* All parts of an EFI system partition RAID array must be individually usable, that means that ESP can only placed in a RAID1 array.<br />
* The RAID superblock must be placed at the end of the EFI system partition using {{ic|1=--metadata=1.0}}, otherwise the firmware will not be able to access the partition.<br />
}}<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.0 --raid-devices=2 /dev/md/ESP /dev/sda2 /dev/sdb2<br />
<br />
This example utilizes RAID0 for root, you may wish to substitute a different level based on your preferences or requirements.<br />
<br />
# mdadm --create --verbose --level=0 --metadata=1.2 --raid-devices=2 /dev/md/root /dev/sda3 /dev/sdb3<br />
<br />
=== Preparing the block devices ===<br />
<br />
As explained in [[dm-crypt/Drive preparation]], the devices are wiped with random data utilizing {{ic|/dev/zero}} and a crypt device with a random key. Alternatively, you could use {{ic|dd}} with {{ic|/dev/random}} or {{ic|/dev/urandom}}, though it will be much slower.<br />
<br />
# cryptsetup open --type plain /dev/md/root container --key-file /dev/random<br />
# dd if=/dev/zero of=/dev/mapper/container bs=1M status=progress<br />
# cryptsetup close container<br />
<br />
And repeat above for the HDD ({{ic|/dev/sdc1}} in this example).<br />
<br />
Set up encryption for {{ic|/dev/md/root}}:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup -y -v luksFormat --type luks1 /dev/md/root<br />
# cryptsetup open /dev/md/root cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
And repeat for the HDD:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sdc1<br />
# cryptsetup open /dev/sdc1 cryptdata<br />
# mkfs.ext4 /dev/mapper/cryptdata<br />
# mkdir /mnt/data<br />
# mount /dev/mapper/cryptdata /mnt/data<br />
<br />
For UEFI systems, set up the EFI system partition:<br />
<br />
# mkfs.fat -F32 /dev/md/ESP<br />
# mount /dev/md/ESP /mnt/efi<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure [[GRUB]] for the LUKS1 encrypted system by editing {{ic|/etc/default/grub}} with the following:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/md/root:cryptroot"<br />
GRUB_ENABLE_CRYPTODISK=y<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details.<br />
<br />
Complete the GRUB install to both SSDs (in reality, installing only to {{ic|/dev/sda}} will work).<br />
<br />
# grub-install --target=i386-pc /dev/sda<br />
# grub-install --target=i386-pc /dev/sdb<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Creating the keyfiles ===<br />
<br />
The next steps save you from entering your passphrase twice when you boot the system (once so GRUB can unlock the LUKS1 device, and second time once the initramfs assumes control of the system). This is done by creating a [[dm-crypt/Device encryption#Keyfiles|keyfile]] for the encryption and adding it to the initramfs image to allow the encrypt hook to unlock the root device. See [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] for details.<br />
<br />
* Create the [[dm-crypt/Device encryption#Keyfiles|keyfile]] and add the key to {{ic|/dev/md/root}}.<br />
* Create another keyfile for the HDD ({{ic|/dev/sdc1}}) so it can also be unlocked at boot. For convenience, leave the passphrase created above in place as this can make recovery easier if you ever need it. Edit {{ic|/etc/crypttab}} to decrypt the HDD at boot. See [[Dm-crypt/System configuration#Unlocking with a keyfile]].<br />
<br />
=== Configuring the system ===<br />
<br />
Edit [[fstab]] to mount the cryptroot and cryptdata block devices and the ESP:<br />
<br />
/dev/mapper/cryptroot / ext4 rw,noatime 0 1<br />
/dev/mapper/cryptdata /data ext4 defaults 0 2<br />
/dev/md/ESP /efi vfat rw,relatime,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,tz=UTC,errors=remount-ro 0 2<br />
<br />
Save the RAID configuration:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
Edit [[mkinitcpio.conf]] to include your keyfile and add the proper hooks:<br />
<br />
FILES=(/crypto_keyfile.bin)<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''mdadm_udev''' '''encrypt''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details.<br />
<br />
== Plain dm-crypt ==<br />
<br />
Contrary to LUKS, dm-crypt ''plain'' mode does not require a header on the encrypted device: this scenario exploits this feature to set up a system on an unpartitioned, encrypted disk that will be indistinguishable from a disk filled with random data, which could allow [[Wikipedia:Deniable encryption|deniable encryption]]. See also [[wikipedia:Disk encryption#Full disk encryption]].<br />
<br />
Note that if full-disk encryption is not required, the methods using LUKS described in the sections above are better options for both system encryption and encrypted partitions. LUKS features like key management with multiple passphrases/key-files or re-encrypting a device in-place are unavailable with ''plain'' mode.<br />
<br />
''Plain'' dm-crypt encryption can be more resilient to damage than LUKS, because it does not rely on an encryption master-key which can be a single-point of failure if damaged. However, using ''plain'' mode also requires more manual configuration of encryption options to achieve the same cryptographic strength. See also [[Disk encryption#Cryptographic metadata]]. Using ''plain'' mode could also be considered if concerned with the problems explained in [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]].<br />
<br />
{{Tip|If headerless encryption is your goal but you are unsure about the lack of key-derivation with ''plain'' mode, then two alternatives are:<br />
* [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|dm-crypt LUKS mode with a detached header]] by using the ''cryptsetup'' {{ic|--header}} option. It cannot be used with the standard ''encrypt'' hook, but the hook may be modified.<br />
* [[tcplay]] which offers headerless encryption but with the PBKDF2 function.<br />
}}<br />
<br />
The scenario uses two USB sticks:<br />
<br />
* one for the boot device, which also allows storing the options required to open/unlock the plain encrypted device in the boot loader configuration, since typing them on each boot would be error prone;<br />
* another for the encryption key file, assuming it stored as raw bits so that to the eyes of an unaware attacker who might get the usbkey the encryption key will appear as random data instead of being visible as a normal file. See also [[Wikipedia:Security through obscurity]], follow [[dm-crypt/Device encryption#Keyfiles]] to prepare the keyfile.<br />
<br />
The disk layout is:<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+ +----------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot device | | Encryption key |<br />
| | | | | | | file storage |<br />
| / | [SWAP] | /home | | /boot | | (unpartitioned |<br />
| | | | | | | in example) |<br />
| /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home | | /dev/sdb1 | | /dev/sdc |<br />
|----------------------+----------------------+----------------------| |----------------| |----------------|<br />
| disk drive /dev/sda encrypted using plain mode and LVM | | USB stick 1 | | USB stick 2 |<br />
+--------------------------------------------------------------------+ +----------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* It is also possible to use a single USB key physical device:<br />
** By putting the key on another partition (/dev/sdb2) of the USB storage device (/dev/sdb).<br />
** By copying the keyfile to the initramfs directly. An example keyfile {{ic|/etc/keyfile}} gets copied to the initramfs image by setting {{ic|1=FILES=(/etc/keyfile)}} in {{ic|/etc/mkinitcpio.conf}}. The way to instruct the {{ic|encrypt}} hook to read the keyfile in the initramfs image is using {{ic|rootfs:}} prefix before the filename, e.g. {{ic|1=cryptkey=rootfs:/etc/keyfile}}.<br />
* Another option is using a passphrase with good [[Disk encryption#Choosing a strong passphrase|entropy]].<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
It is vital that the mapped device is filled with random data. In particular this applies to the scenario use case we apply here.<br />
<br />
See [[dm-crypt/Drive preparation]] and [[dm-crypt/Drive preparation#dm-crypt specific methods]]<br />
<br />
=== Preparing the non-boot partitions ===<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for plain mode]] for details.<br />
<br />
Using the device {{ic|/dev/sda}}, with the aes-xts cipher with a 512 bit key size and using a keyfile we have the following options for this scenario:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sdc --key-size=512 open --type plain /dev/sda cryptlvm<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, and key file details.<br />
<br />
We can now check a mapping entry has been made for {{ic|/dev/mapper/cryptlvm}}:<br />
<br />
# fdisk -l<br />
<br />
{{Tip|A simpler alternative to using LVM, advocated in the cryptsetup FAQ for cases where LVM is not necessary, is to just create a filesystem on the entirety of the mapped dm-crypt device.}} <br />
<br />
Next, we setup [[LVM]] logical volumes on the mapped device. See [[LVM#Installing Arch Linux on LVM]] for further details:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -L 10G MyVolGroup -n swap<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
We format and mount them and activate swap. See [[File systems#Create a file system]] for further details:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# mkswap /dev/MyVolGroup/swap<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The {{ic|/boot}} partition can be installed on the standard vfat partition of a USB stick, if required. But if manual partitioning is needed, then a small 200 MiB partition is all that is required. Create the partition using a [[Partitioning#Partitioning tools|partitioning tool]] of your choice.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}, if it is not already formatted as vfat:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
# mkdir /mnt/boot<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to boot the encrypted root partition, the following [[kernel parameters]] need to be set by the boot loader (note that 64 is the number of bytes in 512 bits):<br />
<br />
cryptdevice=/dev/disk/by-id/''disk-ID-of-sda'':cryptlvm cryptkey=/dev/disk/by-id/''disk-ID-of-sdc'':0:64 crypto=:aes-xts-plain64:512:0:<br />
<br />
The {{ic|''disk-ID-of-'''disk'''''}} refers to the id of the referenced disk. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details and other parameters that you may need.<br />
<br />
{{Tip|If using GRUB, you can install it on the same USB as the {{ic|/boot}} partition with:<br />
<br />
# grub-install --recheck /dev/sdb<br />
<br />
}}<br />
<br />
=== Post-installation ===<br />
<br />
You may wish to remove the USB sticks after booting. Since the {{ic|/boot}} partition is not usually needed, the {{ic|noauto}} option can be added to the relevant line in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
# /dev/sdb1<br />
/dev/sdb1 /boot ext4 '''noauto''',rw,noatime 0 2<br />
}}<br />
<br />
However, when an update to anything used in the initramfs, or a kernel, or the bootloader is required; the {{ic|/boot}} partition must be present and mounted. As the entry in {{ic|fstab}} already exists, it can be mounted simply with:<br />
<br />
# mount /boot<br />
<br />
== Encrypted boot partition (GRUB) ==<br />
<br />
This setup utilizes the same partition layout and configuration for the system's root partition as the previous [[#LVM on LUKS]] section, with the difference that a special feature of the [[GRUB]] bootloader is used to additionally encrypt the boot partition {{ic|/boot}}. See also [[GRUB#Encrypted /boot]].<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+---------------------+----------------------+----------------------+----------------------+----------------------+<br />
| BIOS boot partition | EFI system partition | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | | | | |<br />
| | /efi | / | [SWAP] | /home |<br />
| | | | | |<br />
| | | /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home |<br />
| /dev/sda1 | /dev/sda2 |----------------------+----------------------+----------------------+<br />
| unencrypted | unencrypted | /dev/sda3 encrypted using LVM on LUKS1 |<br />
+---------------------+----------------------+--------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* All scenarios are intended as examples. It is, of course, possible to apply both of the two above distinct installation steps with the other scenarios as well. See also the variants linked in [[#LVM on LUKS]].<br />
* You can use {{ic|cryptboot}} script from {{AUR|cryptboot}} package for simplified encrypted boot management (mounting, unmounting, upgrading packages) and as a defense against [https://www.schneier.com/blog/archives/2009/10/evil_maid_attac.html Evil Maid] attacks with [[Secure Boot#Using your own keys|UEFI Secure Boot]]. For more information and limitations see [https://github.com/xmikos/cryptboot cryptboot project] page.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
Create a partition of type {{ic|8309}}, which will later contain the encrypted container for the LVM.<br />
<br />
Create the LUKS encrypted container:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup luksFormat --type luks1 /dev/sda3<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Your partition layout should look similar to this:<br />
<br />
{{hc|# gdisk -l /dev/sda|<br />
...<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 4095 1024.0 KiB EF02 BIOS boot partition<br />
2 4096 1130495 550.0 MiB EF00 EFI System<br />
3 1130496 68239360 32.0 GiB 8309 Linux LUKS<br />
}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda3 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
The LVM logical volumes of this example follow the exact layout as the [[#LVM on LUKS]] scenario. Therefore, please follow [[#Preparing the logical volumes]] above and adjust as required.<br />
<br />
If you plan to boot in UEFI mode, create a mountpoint for the [[EFI system partition]] at {{ic|/efi}} for compatibility with {{ic|grub-install}} and mount it:<br />
<br />
# mkdir /mnt/efi<br />
# mount /dev/sda2 /mnt/efi<br />
<br />
At this point, you should have the following partitions and logical volumes inside of {{ic|/mnt}}:<br />
<br />
{{hc|$ lsblk|<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 200G 0 disk<br />
├─sda1 8:1 0 1M 0 part<br />
├─sda2 8:2 0 550M 0 part /mnt/efi<br />
└─sda3 8:3 0 100G 0 part<br />
└─cryptlvm 254:0 0 100G 0 crypt<br />
├─MyVolGroup-swap 254:1 0 8G 0 lvm [SWAP]<br />
├─MyVolGroup-root 254:2 0 32G 0 lvm /mnt<br />
└─MyVolGroup-home 254:3 0 60G 0 lvm /mnt/home<br />
}}<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure GRUB to allow booting from {{ic|/boot}} on a LUKS1 encrypted partition:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_ENABLE_CRYPTODISK=y<br />
}}<br />
<br />
Set the kernel parameters, so that the initramfs can unlock the encrypted root partition. Using the {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... cryptdevice=UUID=''device-UUID'':cryptlvm ..."<br />
}}<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... rd.luks.name=''device-UUID''=cryptlvm" ...<br />
}}<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details. The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda3}} (the partition which holds the lvm containing the root filesystem). See [[Persistent block device naming]].<br />
<br />
[[GRUB#Installation_2|install GRUB]] to the mounted ESP for UEFI booting:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB --recheck<br />
<br />
[[GRUB#Installation|install GRUB]] to the disk for BIOS booting:<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
<br />
Generate GRUB's [[GRUB#Generate the main configuration file|configuration]] file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If all commands finished without errors, GRUB should prompt for the passphrase to unlock the {{ic|/dev/sda3}} partition after the next reboot.<br />
<br />
=== Avoiding having to enter the passphrase twice ===<br />
<br />
{{Merge|Dm-crypt/Device encryption#With a keyfile embedded in the initramfs|Too much duplicated content, too much detail here for this overview page.|section=Security Issue with Grub Keyfile}}<br />
<br />
While GRUB asks for a passphrase to unlock the LUKS1 encrypted partition after above instructions, the partition unlock is not passed on to the initramfs. Hence, you have to enter the passphrase twice at boot: once for GRUB and once for the initramfs.<br />
<br />
This section deals with extra configuration to let the system boot by only entering the passphrase once, in GRUB. This is accomplished by [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs|with a keyfile embedded in the initramfs]].<br />
<br />
First create a keyfile and add it as LUKS key:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/root/cryptlvm.keyfile iflag=fullblock<br />
# chmod 000 /root/cryptlvm.keyfile<br />
# chmod 600 /boot/initramfs-linux*<br />
# cryptsetup -v luksAddKey /dev/sda3 /root/cryptlvm.keyfile<br />
<br />
Add the keyfile to the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/root/cryptlvm.keyfile)<br />
}}<br />
<br />
Set the following kernel parameters to unlock the LUKS partition with the keyfile. Using the {{ic|encrypt}} hook:<br />
<br />
GRUB_CMDLINE_LINUX="... cryptkey=rootfs:/root/cryptlvm.keyfile"<br />
<br />
Or, using the [[sd-encrypt]] hook:<br />
<br />
GRUB_CMDLINE_LINUX="... rd.luks.key=''device-UUID''=/root/cryptlvm.keyfile"<br />
<br />
If for some reason the keyfile fails to unlock the boot partition, systemd will fallback to ask for a passphrase to unlock and, in case that is correct, continue booting.<br />
<br />
{{Tip|If you want to encrypt the {{ic|/boot}} partition to protect against offline tampering threats, the [[dm-crypt/Specialties#mkinitcpio-chkcryptoboot|mkinitcpio-chkcryptoboot]] hook has been contributed to help.}}<br />
<br />
== Btrfs subvolumes with swap ==<br />
<br />
The following example creates a full system encryption with LUKS1 using [[Btrfs]] subvolumes to [[Btrfs#Mounting subvolumes|simulate partitions]].<br />
<br />
If using UEFI, an [[EFI system partition]] (ESP) is required. {{ic|/boot}} itself may reside on {{ic|/}} and be encrypted; however, the ESP itself cannot be encrypted. In this example layout, the ESP is {{ic|/dev/sda1}} and is mounted at {{ic|/efi}}. {{ic|/boot}} itself is located on the system partition, {{ic|/dev/sda2}}.<br />
<br />
Since {{ic|/boot}} resides on the LUKS1 encrypted {{ic|/}}, [[GRUB]] must be used as the bootloader because only GRUB can load modules necessary to decrypt {{ic|/boot}} (e.g., crypto.mod, cryptodisk.mod and luks.mod).<br />
<br />
Additionally an optional plain-encrypted [[swap]] partition is shown.<br />
<br />
{{Warning|Do not use a [[swap file]] instead of a separate partition on Linux kernels before v5.0, because this may result in data loss. See [[Btrfs#Swap file]].}}<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+<br />
| EFI system partition | System partition | Swap partition |<br />
| unencrypted | LUKS1-encrypted | plain-encrypted |<br />
| | | |<br />
| /efi | / | [SWAP] |<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 |<br />
|----------------------+----------------------+----------------------+<br />
</nowiki>}}<br />
<br />
=== Preparing the disk ===<br />
<br />
{{Note|It is not possible to use btrfs partitioning as described in [[Btrfs#Partitionless Btrfs disk]] when using LUKS. Traditional partitioning must be used, even if it is just to create one partition.}}<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]]. If you are using [[UEFI]] create an [[EFI system partition]] with an appropriate size. It will later be mounted at {{ic|/efi}}. If you are going to create an encrypted swap partition, create the partition for it, but do '''not''' mark it as swap, since plain ''dm-crypt'' will be used with the partition.<br />
<br />
Create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}). See the [[Partitioning]] article.<br />
<br />
=== Preparing the system partition ===<br />
<br />
==== Create LUKS container ====<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
Follow [[dm-crypt/Device encryption#Encrypting devices with LUKS mode]] to setup {{ic|/dev/sda2}} for LUKS. See the [[dm-crypt/Device encryption#Encryption options for LUKS mode]] before doing so for a list of encryption options.<br />
<br />
==== Unlock LUKS container ====<br />
<br />
Now follow [[dm-crypt/Device encryption#Unlocking/Mapping LUKS partitions with the device mapper]] to unlock the LUKS container and map it.<br />
<br />
==== Format mapped device ====<br />
<br />
Proceed to format the mapped device as described in [[Btrfs#File system on a single device]], where {{ic|''/dev/partition''}} is the name of the mapped device (i.e., {{ic|cryptroot}}) and '''not''' {{ic|/dev/sda2}}.<br />
<br />
==== Mount mapped device ====<br />
<br />
Finally, [[mount]] the now-formatted mapped device (i.e., {{ic|/dev/mapper/cryptroot}}) to {{ic|/mnt}}.<br />
<br />
{{Tip|You may want to use the {{ic|1=compress=lzo}} mount option. See [[Btrfs#Compression]] for more information.}}<br />
<br />
=== Creating btrfs subvolumes ===<br />
<br />
{{Merge|Btrfs|The subvolume layout is not specific to an encrypted system.}}<br />
<br />
==== Layout ====<br />
<br />
[[Btrfs#Subvolumes|Subvolumes]] will be used to simulate partitions, but other (nested) subvolumes will also be created. Here is a partial representation of what the following example will generate:<br />
<br />
{{Text art|<nowiki><br />
subvolid=5 (/dev/sda2)<br />
|<br />
├── @ (mounted as /)<br />
| |<br />
| ├── /bin (directory)<br />
| |<br />
| ├── /home (mounted @home subvolume)<br />
| |<br />
| ├── /usr (directory)<br />
| |<br />
| ├── /.snapshots (mounted @snapshots subvolume)<br />
| |<br />
| ├── /var/cache/pacman/pkg (nested subvolume)<br />
| |<br />
| ├── ... (other directories and nested subvolumes)<br />
|<br />
├── @snapshots (mounted as /.snapshots)<br />
|<br />
├── @home (mounted as /home)<br />
|<br />
└── @... (additional subvolumes you wish to use as mount points)<br />
</nowiki>}}<br />
<br />
This section follows the [[Snapper#Suggested filesystem layout]], which is most useful when used with [[Snapper]]. You should also consult [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs Wiki SysadminGuide#Layout].<br />
<br />
==== Create top-level subvolumes ====<br />
<br />
Here we are using the convention of prefixing {{ic|@}} to subvolume names that will be used as mount points, and {{ic|@}} will be the subvolume that is mounted as {{ic|/}}.<br />
<br />
Following the [[Btrfs#Creating a subvolume]] article, create subvolumes at {{ic|/mnt/@}}, {{ic|/mnt/@snapshots}}, and {{ic|/mnt/@home}}.<br />
<br />
Create any additional subvolumes you wish to use as mount points now.<br />
<br />
==== Mount top-level subvolumes ====<br />
<br />
Unmount the system partition at {{ic|/mnt}}.<br />
<br />
Now mount the newly created {{ic|@}} subvolume which will serve as {{ic|/}} to {{ic|/mnt}} using the {{ic|1=subvol=}} mount option. Assuming the mapped device is named {{ic|cryptroot}}, the command would look like:<br />
<br />
# mount -o compress=lzo,subvol=@ /dev/mapper/cryptroot /mnt<br />
<br />
See [[Btrfs#Mounting subvolumes]] for more details.<br />
<br />
Also mount the other subvolumes to their respective mount points: {{ic|@home}} to {{ic|/mnt/home}} and {{ic|@snapshots}} to {{ic|/mnt/.snapshots}}.<br />
<br />
==== Create nested subvolumes ====<br />
<br />
Create any subvolumes you do '''not''' want to have snapshots of when taking a snapshot of {{ic|/}}. For example, you probably do not want to take snapshots of {{ic|/var/cache/pacman/pkg}}. These subvolumes will be nested under the {{ic|@}} subvolume, but just as easily could have been created earlier at the same level as {{ic|@}} according to your preference.<br />
<br />
Since the {{ic|@}} subvolume is mounted at {{ic|/mnt}} you will need to [[create a subvolume]] at {{ic|/mnt/var/cache/pacman/pkg}} for this example. You may have to create any parent directories first.<br />
<br />
Other directories you may wish to do this with are {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.<br />
<br />
==== Mount ESP ====<br />
<br />
If you prepared an EFI system partition earlier, create its mount point and mount it now.<br />
<br />
{{Note|Btrfs snapshots will exclude {{ic|/efi}}, since it is not a btrfs file system.}}<br />
<br />
At the [[Installation guide#Install the base packages|pacstrap]] installation step, the {{Pkg|btrfs-progs}} must be installed in addition to the base group.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
==== Create keyfile ====<br />
<br />
In order for GRUB to open the LUKS partition without having the user enter his passphrase twice, we will use a keyfile embedded in the initramfs. Follow [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] making sure to add the key to {{ic|/dev/sda2}} at the ''luksAddKey'' step.<br />
<br />
==== Edit mkinitcpio.conf ====<br />
<br />
After creating, adding, and embedding the key as described above, add the {{ic|encrypt}} hook to [[mkinitcpio.conf]] as well as any other hooks you require. See [[dm-crypt/System configuration#mkinitcpio]] for detailed information.<br />
<br />
{{Tip|You may want to add {{ic|1=BINARIES=(/usr/bin/btrfs)}} to your {{ic|mkinitcpio.conf}}. See the [[Btrfs#Corruption recovery]] article.}}<br />
<br />
=== Configuring the boot loader ===<br />
<br />
Install [[GRUB]] to {{ic|/dev/sda}}. Then, edit {{ic|/etc/default/grub}} as instructed in the [[GRUB#Additional arguments]] and [[GRUB#Encrypted /boot]], following both the instructions for an encrypted root and boot partition. Finally, generate the GRUB configuration file.<br />
<br />
=== Configuring swap ===<br />
<br />
If you created a partition to be used for encrypted swap, now is the time to configure it. Follow the instructions at [[dm-crypt/Swap encryption]].</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=ICC_profiles&diff=511367ICC profiles2018-02-18T14:54:45Z<p>EasyToRemember: /* Applications that support ICC profiles */ typo correction</p>
<hr />
<div>[[Category:Image manipulation]]<br />
[[ja:ICC プロファイル]]<br />
As it pertains to general desktop use, an [[Wikipedia:ICC profile|ICC profile]] is a binary file which contains precise data regarding the color attributes of an input, or output device. Single, or multiple profiles can be applied across a system and its devices to produce consistent and repeatable results for graphic and document editing and publishing. ICC profiles are typically calibrated with a [[Wikipedia:Tristimulus colorimeter|(tristimulus) colorimeter]], or a spectrophotometer when absolute color accuracy is required.<br />
<br />
== Profile generation ==<br />
<br />
Color management is a workflow of hardware calibration, software profiling and embedding the profile into the picture or video. It's all based on using an [[Wikipedia:ICC profile|ICC profile]].<br />
<br />
=== Colorimeter or spectrometer ===<br />
<br />
It is highly recommended to use a colorimeter or spectrometer device for hardware-assisted display, printer and scanner calibration. For home use there are several affordable colorimeters available. Some are well- or even better-supported under Linux than on other operating systems. Frequently recommended devices are [http://www.xrite.com/colormunki-display X-Rite ColorMunki Display], [http://spyder.datacolor.com/portfolio-view/spyder5express/ DataColor Spyder5 Express] and the open source hardware [http://www.hughski.com/ ColorHug]. You can find more Linux-supported devices listed in the [http://www.argyllcms.com/doc/instruments.html AgyllCMS documentation].<br />
<br />
=== Argyll CMS ===<br />
<br />
The [http://www.argyllcms.com/ Argyll Color Management System] is a complete suite of command-line profile creation and loading tools listed under {{Pkg|argyllcms}}. <br />
<br />
Review the official [http://www.argyllcms.com/doc/ArgyllDoc.html Argyll CMS documentation] for details on how to profile selected devices.<br />
<br />
=== Monitor calibration and profiling with additional calibration hardware ===<br />
<br />
There is a GUI frontend for ArgyllCMS called [http://displaycal.net DisplayCal], available as {{Pkg|displaycal}}. In most common cases you will want to use its default settings. It is a common way to calibrate to a daylight color of 6500K and gamma 2,2. Read the DispalGui documentation for more. Many tutorials are available on the net.<br />
<br />
=== Scanner calibration ===<br />
<br />
Follow the scanner part of the [https://blog.simon-dreher.de/color-management.html scanner calibration] tutorial.<br />
<br />
=== Printer calibration ===<br />
<br />
See {{man|8|cups-calibrate}}.<br />
<br />
=== File transfer ===<br />
<br />
Profile generation on a Windows or macOS system is one of the easiest and most widely recommended methods to obtain a ICC monitor profile. Since ICC color profiles are written to an open specification, they are compatible across operating systems. Transferring profiles from one OS to another can be used as a workaround for the lack of support for certain spectrophotometers or colorimeters under Linux: one can simply produce a profile on a different OS and then use it in a Linux workflow. Note that the system on which the profile is generated must host the exact same video card and monitor for which the profile is to be used. Once generation of an ICC profile, or a series of profiles is complete on a Windows system, copy the file(s) from the default path:<br />
<br />
C:\WINDOWS\System32\spool\drivers\color<br />
<br />
macOS generally stores saved ICC profiles in one of two locations:<br />
<br />
/Library/ColorSync/Profiles<br />
/Users/USER_NAME/Library/ColorSync/Profile<br />
<br />
Once the appropriate {{Ic|.icc/.icm}} files have been copied, install the device profiles to your desired system. Common installation device profiles directories on Linux include:<br />
<br />
/usr/share/color/icc<br />
/usr/local/share/color/icc<br />
/home/USER_NAME/.color/icc<br />
<br />
{{Note|Ensure that the calibrated contrast, brightness and RGB settings of the monitor do not change between the time of calibration and the loading of the ICC profile. Use this method only if you are absolutely certain that neither Linux nor the other OS does anything behind your back (in video drivers or vendor utilities) that alters the signal actually sent to the display, or the way the display interprets the signal. Watch out for "Broadcast RGB" or similar settings. One concrete example where profiling in Windows and Linux yields [https://bugzilla.kernel.org/show_bug.cgi?id&#61;70721 significantly different results] is the Lenovo Ideapad Yoga 2 Pro laptop, because these OSes program the flat panel controller in very different ways.|}}<br />
<br />
=== Gnome Color Manager ===<br />
<br />
On Gnome, an ICC profile can easily be created by using {{pkg|gnome-color-manager}}. Under Gnome, this is accessible via the Control Center and is pretty straightforward to use. You'll need a colorimeter device to use this feature.<br />
<br />
==== Manually ====<br />
<br />
Ensure ''gnome-settings-daemon'' is started, and run:<br />
<br />
$ colormgr get-devices <br />
<br />
Look for the {{ic|Device ID}} line of your monitor. If this is e.g. {{ic|xrandr-Lenovo Group Limited}}, start calibration with the command:<br />
<br />
gcm-calibrate --device "''xrandr-Lenovo Group Limited''"<br />
<br />
=== LPROF ICC Profiler ===<br />
<br />
[http://lprof.sourceforge.net/ LPROF] is an ICC profiler with a graphical user interface listed under {{AUR|lprof}} in the [[AUR]]. <br />
<br />
{{Note|The following walkthrough has been modified from the ArchWiki article [[Using LPROF to profile monitors]].}}<br />
<br />
==== Monitor calibration ====<br />
<br />
===== Contrast/Brightness =====<br />
<br />
Adjust the lighting in the room to what you will be using when working. Even if your screen is coated with an anti-reflective coating, you should avoid light falling directly on it. Let your monitor warm up for at least an hour for the image to get stabilized. If your calibration device has an ambient diffuser, adjust your room brightness to reach the recommended target lux point.<br />
<br />
# Set the monitor contrast to maximum, or 100%. <br />
# Next, display a pure black over entire screen by creating a small, black PNG image (all pixels have RGB = 0, 0, 0) and opening it up in a picture viewer that is capable of displaying an image in fullscreen mode without any controls.<br />
# Reduce the vertical size of the monitor screen (not the PNG image displayed by a picture viewer but the whole of what's displayed on the screen) to 60% to 70% of the full height. What is revealed above and below the picture is called a ''non-scanned area'', and since that area is not receiving any voltage, it is the blackest of black your monitor is capable of displaying. <br />
# Locate the brightness control (usually a sun, circle with rays projecting from it's edges) and lower the value until the black ''image'' matches the non-scanned area.<br />
<br />
===== Color temperature =====<br />
<br />
As we said in the introduction, setting color temperature must occur at noon. If you only have fixed factory default color temperature, you do not really need to wait for the sunny day to come. Just set it to 6500K.<br />
<br />
Place your monitor so that you can see outside the window ''and'' your screen at the same time. For this step, you also need to create a white square image (RGB = 255, 255, 255), roughly 10 by 10 centimeters (4 by 3 inches). Using the same Gwenview technique as with brightness/contrast, display the white square on a pure black background.<br />
<br />
# First, prepare your eyes by staring at the outside world for a while. Let them adjust to the daylight viewing condition for a few minutes.<br />
# Glance at the monitor, and the white square for a few second (it has to be short, because eyes will readjust quickly).<br />
# If the square seems yellowish, you need higher color temperature, or if it has a blueish cast, the temperature needs to be lowered.<br />
# Keep glancing, looking out the window, and adjusting the white temperature, until the square looks pure white<br />
<br />
Take your time with the steps described above. It is essential to get it right.<br />
<br />
==== Monitor profiling without additional calibration hardware ====<br />
<br />
Start lprof. You will be presented by a fairly large window with multiple tabs on the right. <br />
<br />
# Click on the ''Monitor Profiler'' tab. Then click on the large ''Enter monitor values >>'' button.<br />
# White point should be set to ''6500K (daylight)''.<br />
# Primaries should be set to either ''SMPTE RP145-1994'', or ''EBU Tech.3213-E'' or ''P22'', or whatever appropriate values for your monitor. If you come across correct values for your monitor, enter those by selecting ''User Defined'' from the drop-down. If in doubt, you may use ''P22'' for all monitors with Trinitron CRTs (in this case, ''Trinitron'' is not related to Sony Trinitron mointors and TVs), and ''SMPTE RP145-1994'' for other CRTs.<br />
# Click the ''Set Gamma and Black Point'' button.<br />
# You will now see a full-screen view of two charts with some controls at the bottom.<br />
# Uncheck the ''Link channels'' check-box and adjust individual Red, Green, and Blue gamma by either moving the slider left or right, or by entering and changing values in the three boxes to the left. The goal is to make the chart on the left (the smaller square one) flat. When you are satisfied with how it looks, check the ''Link channels'' check-box and adjust the gamma again.<br />
# When you are done, click ''OK''. Click ''OK'' again.<br />
<br />
When you are finished entering monitor values, you might want to enter some information about the monitor. This is not mandatory, but it is always nice to know what profile is for what.<br />
<br />
# Click ''Profile identification'' button.<br />
# Fill in the data.<br />
# Click ''OK'' to finish.<br />
<br />
After you are all done, click on the '...' button next to ''Output Profile File'' box. Enter the name of your profile: ''somemonitor.icc''. Click ''Create Profile'' button, and you are done.<br />
<br />
=== ThinkPads ===<br />
<br />
See [http://www.thinkwiki.org/wiki/Colour_profile color profiles] for IBM/Lenovo [[Wikipedia:ThinkPad|ThinkPad]] notebook [http://www-307.ibm.com/pc/support/site.wss/migr-62923.html monitor profile] ([http://www-307.ibm.com/pc/support/site.wss/migr-44320.html generic]) support.<br />
<br />
== Loading ICC profiles ==<br />
<br />
ICC profiles are loaded either by the session daemon or by a dedicated ICC loader. Both Gnome and KDE have daemons capable of loading ICC profiles from {{pkg|colord}}. If you use colord in combination with either {{pkg|gnome-settings-daemon}} or {{Pkg|colord-kde}}, the profile will be loaded automatically. If you're not using neither Gnome nor KDE, you may install an independent daemon, [https://github.com/agalakhov/xiccd xiccd], which does the same but does not depend on your desktop environment. Do not start two ICC-capable daemons (e.g. gnome-settiongs-daemon and xiccd) at the same time.<br />
<br />
If you're not using any ICC-capable session daemon, make sure you use only one ICC loader - either xcalib, dispwin, dispcalGUI-apply-profiles or others, otherwise you easily end up with uncontrolled environment. (The most recently run loader set the calibration, and the earlier loaded calibration is overwritten.)<br />
<br />
Before using a particular ICC loader, you should understand that some tools set only the calibration curves (e.g. xcalib), other tools set only the display profile to X.org _ICC_PROFILE atom (e.g. xicc) and other tools do both tasks at once (e.g. dispwin, dispcalGUI-apply-profiles).<br />
<br />
=== xcalib ===<br />
<br />
* [http://xcalib.sourceforge.net/ xcalib] is a lightweight monitor calibration loader which can load an ICC monitor profile to be shared across desktop applications. {{AUR|xcalib}} is part of the Arch User Repository (AUR).<br />
<br />
==== Xinitrc example ====<br />
<br />
Load profile {{ic|P221W-sRGB.icc}} in {{Ic|/usr/share/color/icc}} on display host:0 when X server starts<br />
<pre>#!/bin/bash<br />
<br />
/usr/bin/xcalib -d :0 /usr/share/color/icc/P221W-sRGB.icc</pre><br />
<br />
==== JWM {{ic|<StartupCommand>}} example ====<br />
<br />
Load profile {{ic|P221W-Native.icc}} in {{Ic|/usr/local/share/color/icc}} on display host:0 when JWM starts<br />
{{ic|<StartupCommand>}}xcalib -d :0 /usr/local/share/color/icc/P221W-Native.icc{{ic|</StartupCommand>}}<br />
<br />
=== dispwin ===<br />
* [http://www.argyllcms.com/doc/dispwin.html dispwin] is a part of {{Pkg|argyllcms}}.<br />
<br />
==== Xinitrc example ====<br />
<br />
Load profile {{ic|906w-6500K.icc}} in {{Ic|/home/arch/.color/icc}} on display 0 when X server starts<br />
<pre>#!/bin/bash<br />
<br />
/usr/bin/dispwin -d0 /home/arch/.color/icc/906w-6500K.icc</pre><br />
<br />
==== JWM {{ic|<StartupCommand>}} example ====<br />
<br />
Load Argyll calibration file {{ic|906w-7000K.cal}} in {{Ic|/usr/local/share/color/icc}} on display 1 when JWM starts<br />
{{ic|<StartupCommand>}}dispwin -d1 /usr/local/share/color/icc/906w-7000K.cal{{ic|</StartupCommand>}}<br />
<br />
You can easily use one of these loaders to apply the color profile in early boot stage when starting a display manager, e.g. using [https://wiki.ubuntu.com/LightDM#Adding_System_Hooks LightDM startup script]. This allows to load a single icc profile file. This won't work with loading several profile files when using a multi monitopr setup.<br />
<br />
== Applications that support ICC profiles ==<br />
<br />
* [http://www.xsane.org/doc/sane-xsane-color-management-doc.html Xsane] can use ICC profiles for color-corrected scanning.<br />
* [[CUPS]] can use ICC profiles for color-corrected printing using [https://www.freedesktop.org/software/colord/faq.html#cups Colord], but the actual implementation and usability is [https://lists.cups.org/pipermail/cups/2016-December/056399.html unclear].<br />
* [[GIMP]] can use ICC profiles for display of the image being edited. The use of the installed ICC profile has to be explicitly enabled in the settings dialog, though.<br />
* [[mpv]] can take an ICC profile into account when playing a video. The command line argument is: <code>--icc-profile=/path/to/profile.icc</code> or <code>--icc-profile-auto</code>. Only <code>--vo=opengl</code> does color management; other VO drivers will silently ignore the ICC profile options.<br />
* [[Firefox]], by default, uses the system-wide ICC profile only when displaying images that are already tagged with an ICC profile. To assume that untagged images use sRGB and apply color correction also to them, set the {{ic|gfx.color_management.mode}} preference to 1.<br />
* Both [https://www.archlinux.org/packages/?name=eog Eye of Gnome] and [https://www.archlinux.org/packages/?name=eom Eye of MATE] automatically use the system-installed ICC profile.<br />
<br />
== See also ==<br />
<br />
* [[Using LPROF to profile monitors]] - Additional details on how to profile monitors<br />
* [[Wikipedia:Linux color management]]<br />
* [http://www.argyllcms.com/ Argyll Color Management System] - Official Site<br />
* [http://lprof.sourceforge.net/help/lprof-help.html LPROF Main Help Window] - Details on profiling printers and scanners<br />
* [http://displaycal.net/#concept DisplayCal: Basic concept of display calibration and profiling]<br />
* [https://encrypted.pcode.nl/blog/2013/11/24/display-color-profiling-on-linux/ Display color profiling on Linux (XFCE)]<br />
* [https://linuxtidbits.wordpress.com/2013/04/20/handling-display-calibration/ Monitor Hardware Calibration]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=ICC_profiles&diff=511366ICC profiles2018-02-18T14:54:02Z<p>EasyToRemember: /* Applications that support ICC profiles */ Added link to CUPS & ICC profiles</p>
<hr />
<div>[[Category:Image manipulation]]<br />
[[ja:ICC プロファイル]]<br />
As it pertains to general desktop use, an [[Wikipedia:ICC profile|ICC profile]] is a binary file which contains precise data regarding the color attributes of an input, or output device. Single, or multiple profiles can be applied across a system and its devices to produce consistent and repeatable results for graphic and document editing and publishing. ICC profiles are typically calibrated with a [[Wikipedia:Tristimulus colorimeter|(tristimulus) colorimeter]], or a spectrophotometer when absolute color accuracy is required.<br />
<br />
== Profile generation ==<br />
<br />
Color management is a workflow of hardware calibration, software profiling and embedding the profile into the picture or video. It's all based on using an [[Wikipedia:ICC profile|ICC profile]].<br />
<br />
=== Colorimeter or spectrometer ===<br />
<br />
It is highly recommended to use a colorimeter or spectrometer device for hardware-assisted display, printer and scanner calibration. For home use there are several affordable colorimeters available. Some are well- or even better-supported under Linux than on other operating systems. Frequently recommended devices are [http://www.xrite.com/colormunki-display X-Rite ColorMunki Display], [http://spyder.datacolor.com/portfolio-view/spyder5express/ DataColor Spyder5 Express] and the open source hardware [http://www.hughski.com/ ColorHug]. You can find more Linux-supported devices listed in the [http://www.argyllcms.com/doc/instruments.html AgyllCMS documentation].<br />
<br />
=== Argyll CMS ===<br />
<br />
The [http://www.argyllcms.com/ Argyll Color Management System] is a complete suite of command-line profile creation and loading tools listed under {{Pkg|argyllcms}}. <br />
<br />
Review the official [http://www.argyllcms.com/doc/ArgyllDoc.html Argyll CMS documentation] for details on how to profile selected devices.<br />
<br />
=== Monitor calibration and profiling with additional calibration hardware ===<br />
<br />
There is a GUI frontend for ArgyllCMS called [http://displaycal.net DisplayCal], available as {{Pkg|displaycal}}. In most common cases you will want to use its default settings. It is a common way to calibrate to a daylight color of 6500K and gamma 2,2. Read the DispalGui documentation for more. Many tutorials are available on the net.<br />
<br />
=== Scanner calibration ===<br />
<br />
Follow the scanner part of the [https://blog.simon-dreher.de/color-management.html scanner calibration] tutorial.<br />
<br />
=== Printer calibration ===<br />
<br />
See {{man|8|cups-calibrate}}.<br />
<br />
=== File transfer ===<br />
<br />
Profile generation on a Windows or macOS system is one of the easiest and most widely recommended methods to obtain a ICC monitor profile. Since ICC color profiles are written to an open specification, they are compatible across operating systems. Transferring profiles from one OS to another can be used as a workaround for the lack of support for certain spectrophotometers or colorimeters under Linux: one can simply produce a profile on a different OS and then use it in a Linux workflow. Note that the system on which the profile is generated must host the exact same video card and monitor for which the profile is to be used. Once generation of an ICC profile, or a series of profiles is complete on a Windows system, copy the file(s) from the default path:<br />
<br />
C:\WINDOWS\System32\spool\drivers\color<br />
<br />
macOS generally stores saved ICC profiles in one of two locations:<br />
<br />
/Library/ColorSync/Profiles<br />
/Users/USER_NAME/Library/ColorSync/Profile<br />
<br />
Once the appropriate {{Ic|.icc/.icm}} files have been copied, install the device profiles to your desired system. Common installation device profiles directories on Linux include:<br />
<br />
/usr/share/color/icc<br />
/usr/local/share/color/icc<br />
/home/USER_NAME/.color/icc<br />
<br />
{{Note|Ensure that the calibrated contrast, brightness and RGB settings of the monitor do not change between the time of calibration and the loading of the ICC profile. Use this method only if you are absolutely certain that neither Linux nor the other OS does anything behind your back (in video drivers or vendor utilities) that alters the signal actually sent to the display, or the way the display interprets the signal. Watch out for "Broadcast RGB" or similar settings. One concrete example where profiling in Windows and Linux yields [https://bugzilla.kernel.org/show_bug.cgi?id&#61;70721 significantly different results] is the Lenovo Ideapad Yoga 2 Pro laptop, because these OSes program the flat panel controller in very different ways.|}}<br />
<br />
=== Gnome Color Manager ===<br />
<br />
On Gnome, an ICC profile can easily be created by using {{pkg|gnome-color-manager}}. Under Gnome, this is accessible via the Control Center and is pretty straightforward to use. You'll need a colorimeter device to use this feature.<br />
<br />
==== Manually ====<br />
<br />
Ensure ''gnome-settings-daemon'' is started, and run:<br />
<br />
$ colormgr get-devices <br />
<br />
Look for the {{ic|Device ID}} line of your monitor. If this is e.g. {{ic|xrandr-Lenovo Group Limited}}, start calibration with the command:<br />
<br />
gcm-calibrate --device "''xrandr-Lenovo Group Limited''"<br />
<br />
=== LPROF ICC Profiler ===<br />
<br />
[http://lprof.sourceforge.net/ LPROF] is an ICC profiler with a graphical user interface listed under {{AUR|lprof}} in the [[AUR]]. <br />
<br />
{{Note|The following walkthrough has been modified from the ArchWiki article [[Using LPROF to profile monitors]].}}<br />
<br />
==== Monitor calibration ====<br />
<br />
===== Contrast/Brightness =====<br />
<br />
Adjust the lighting in the room to what you will be using when working. Even if your screen is coated with an anti-reflective coating, you should avoid light falling directly on it. Let your monitor warm up for at least an hour for the image to get stabilized. If your calibration device has an ambient diffuser, adjust your room brightness to reach the recommended target lux point.<br />
<br />
# Set the monitor contrast to maximum, or 100%. <br />
# Next, display a pure black over entire screen by creating a small, black PNG image (all pixels have RGB = 0, 0, 0) and opening it up in a picture viewer that is capable of displaying an image in fullscreen mode without any controls.<br />
# Reduce the vertical size of the monitor screen (not the PNG image displayed by a picture viewer but the whole of what's displayed on the screen) to 60% to 70% of the full height. What is revealed above and below the picture is called a ''non-scanned area'', and since that area is not receiving any voltage, it is the blackest of black your monitor is capable of displaying. <br />
# Locate the brightness control (usually a sun, circle with rays projecting from it's edges) and lower the value until the black ''image'' matches the non-scanned area.<br />
<br />
===== Color temperature =====<br />
<br />
As we said in the introduction, setting color temperature must occur at noon. If you only have fixed factory default color temperature, you do not really need to wait for the sunny day to come. Just set it to 6500K.<br />
<br />
Place your monitor so that you can see outside the window ''and'' your screen at the same time. For this step, you also need to create a white square image (RGB = 255, 255, 255), roughly 10 by 10 centimeters (4 by 3 inches). Using the same Gwenview technique as with brightness/contrast, display the white square on a pure black background.<br />
<br />
# First, prepare your eyes by staring at the outside world for a while. Let them adjust to the daylight viewing condition for a few minutes.<br />
# Glance at the monitor, and the white square for a few second (it has to be short, because eyes will readjust quickly).<br />
# If the square seems yellowish, you need higher color temperature, or if it has a blueish cast, the temperature needs to be lowered.<br />
# Keep glancing, looking out the window, and adjusting the white temperature, until the square looks pure white<br />
<br />
Take your time with the steps described above. It is essential to get it right.<br />
<br />
==== Monitor profiling without additional calibration hardware ====<br />
<br />
Start lprof. You will be presented by a fairly large window with multiple tabs on the right. <br />
<br />
# Click on the ''Monitor Profiler'' tab. Then click on the large ''Enter monitor values >>'' button.<br />
# White point should be set to ''6500K (daylight)''.<br />
# Primaries should be set to either ''SMPTE RP145-1994'', or ''EBU Tech.3213-E'' or ''P22'', or whatever appropriate values for your monitor. If you come across correct values for your monitor, enter those by selecting ''User Defined'' from the drop-down. If in doubt, you may use ''P22'' for all monitors with Trinitron CRTs (in this case, ''Trinitron'' is not related to Sony Trinitron mointors and TVs), and ''SMPTE RP145-1994'' for other CRTs.<br />
# Click the ''Set Gamma and Black Point'' button.<br />
# You will now see a full-screen view of two charts with some controls at the bottom.<br />
# Uncheck the ''Link channels'' check-box and adjust individual Red, Green, and Blue gamma by either moving the slider left or right, or by entering and changing values in the three boxes to the left. The goal is to make the chart on the left (the smaller square one) flat. When you are satisfied with how it looks, check the ''Link channels'' check-box and adjust the gamma again.<br />
# When you are done, click ''OK''. Click ''OK'' again.<br />
<br />
When you are finished entering monitor values, you might want to enter some information about the monitor. This is not mandatory, but it is always nice to know what profile is for what.<br />
<br />
# Click ''Profile identification'' button.<br />
# Fill in the data.<br />
# Click ''OK'' to finish.<br />
<br />
After you are all done, click on the '...' button next to ''Output Profile File'' box. Enter the name of your profile: ''somemonitor.icc''. Click ''Create Profile'' button, and you are done.<br />
<br />
=== ThinkPads ===<br />
<br />
See [http://www.thinkwiki.org/wiki/Colour_profile color profiles] for IBM/Lenovo [[Wikipedia:ThinkPad|ThinkPad]] notebook [http://www-307.ibm.com/pc/support/site.wss/migr-62923.html monitor profile] ([http://www-307.ibm.com/pc/support/site.wss/migr-44320.html generic]) support.<br />
<br />
== Loading ICC profiles ==<br />
<br />
ICC profiles are loaded either by the session daemon or by a dedicated ICC loader. Both Gnome and KDE have daemons capable of loading ICC profiles from {{pkg|colord}}. If you use colord in combination with either {{pkg|gnome-settings-daemon}} or {{Pkg|colord-kde}}, the profile will be loaded automatically. If you're not using neither Gnome nor KDE, you may install an independent daemon, [https://github.com/agalakhov/xiccd xiccd], which does the same but does not depend on your desktop environment. Do not start two ICC-capable daemons (e.g. gnome-settiongs-daemon and xiccd) at the same time.<br />
<br />
If you're not using any ICC-capable session daemon, make sure you use only one ICC loader - either xcalib, dispwin, dispcalGUI-apply-profiles or others, otherwise you easily end up with uncontrolled environment. (The most recently run loader set the calibration, and the earlier loaded calibration is overwritten.)<br />
<br />
Before using a particular ICC loader, you should understand that some tools set only the calibration curves (e.g. xcalib), other tools set only the display profile to X.org _ICC_PROFILE atom (e.g. xicc) and other tools do both tasks at once (e.g. dispwin, dispcalGUI-apply-profiles).<br />
<br />
=== xcalib ===<br />
<br />
* [http://xcalib.sourceforge.net/ xcalib] is a lightweight monitor calibration loader which can load an ICC monitor profile to be shared across desktop applications. {{AUR|xcalib}} is part of the Arch User Repository (AUR).<br />
<br />
==== Xinitrc example ====<br />
<br />
Load profile {{ic|P221W-sRGB.icc}} in {{Ic|/usr/share/color/icc}} on display host:0 when X server starts<br />
<pre>#!/bin/bash<br />
<br />
/usr/bin/xcalib -d :0 /usr/share/color/icc/P221W-sRGB.icc</pre><br />
<br />
==== JWM {{ic|<StartupCommand>}} example ====<br />
<br />
Load profile {{ic|P221W-Native.icc}} in {{Ic|/usr/local/share/color/icc}} on display host:0 when JWM starts<br />
{{ic|<StartupCommand>}}xcalib -d :0 /usr/local/share/color/icc/P221W-Native.icc{{ic|</StartupCommand>}}<br />
<br />
=== dispwin ===<br />
* [http://www.argyllcms.com/doc/dispwin.html dispwin] is a part of {{Pkg|argyllcms}}.<br />
<br />
==== Xinitrc example ====<br />
<br />
Load profile {{ic|906w-6500K.icc}} in {{Ic|/home/arch/.color/icc}} on display 0 when X server starts<br />
<pre>#!/bin/bash<br />
<br />
/usr/bin/dispwin -d0 /home/arch/.color/icc/906w-6500K.icc</pre><br />
<br />
==== JWM {{ic|<StartupCommand>}} example ====<br />
<br />
Load Argyll calibration file {{ic|906w-7000K.cal}} in {{Ic|/usr/local/share/color/icc}} on display 1 when JWM starts<br />
{{ic|<StartupCommand>}}dispwin -d1 /usr/local/share/color/icc/906w-7000K.cal{{ic|</StartupCommand>}}<br />
<br />
You can easily use one of these loaders to apply the color profile in early boot stage when starting a display manager, e.g. using [https://wiki.ubuntu.com/LightDM#Adding_System_Hooks LightDM startup script]. This allows to load a single icc profile file. This won't work with loading several profile files when using a multi monitopr setup.<br />
<br />
== Applications that support ICC profiles ==<br />
<br />
* [http://www.xsane.org/doc/sane-xsane-color-management-doc.html Xsane] can use ICC profiles for color-corrected scanning.<br />
* [[CUPS]] can use ICC profiles for color-corrected printing using [https://www.freedesktop.org/software/colord/faq.html#cups Colord], but the actual implementation and and usability is [https://lists.cups.org/pipermail/cups/2016-December/056399.html unclear].<br />
* [[GIMP]] can use ICC profiles for display of the image being edited. The use of the installed ICC profile has to be explicitly enabled in the settings dialog, though.<br />
* [[mpv]] can take an ICC profile into account when playing a video. The command line argument is: <code>--icc-profile=/path/to/profile.icc</code> or <code>--icc-profile-auto</code>. Only <code>--vo=opengl</code> does color management; other VO drivers will silently ignore the ICC profile options.<br />
* [[Firefox]], by default, uses the system-wide ICC profile only when displaying images that are already tagged with an ICC profile. To assume that untagged images use sRGB and apply color correction also to them, set the {{ic|gfx.color_management.mode}} preference to 1.<br />
* Both [https://www.archlinux.org/packages/?name=eog Eye of Gnome] and [https://www.archlinux.org/packages/?name=eom Eye of MATE] automatically use the system-installed ICC profile.<br />
<br />
== See also ==<br />
<br />
* [[Using LPROF to profile monitors]] - Additional details on how to profile monitors<br />
* [[Wikipedia:Linux color management]]<br />
* [http://www.argyllcms.com/ Argyll Color Management System] - Official Site<br />
* [http://lprof.sourceforge.net/help/lprof-help.html LPROF Main Help Window] - Details on profiling printers and scanners<br />
* [http://displaycal.net/#concept DisplayCal: Basic concept of display calibration and profiling]<br />
* [https://encrypted.pcode.nl/blog/2013/11/24/display-color-profiling-on-linux/ Display color profiling on Linux (XFCE)]<br />
* [https://linuxtidbits.wordpress.com/2013/04/20/handling-display-calibration/ Monitor Hardware Calibration]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Multiboot_USB_drive&diff=506662Multiboot USB drive2018-01-08T18:48:42Z<p>EasyToRemember: /* Hybrid UEFI GPT + BIOS GPT/MBR boot */ Minor sentence style correction</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Getting and installing Arch]]<br />
[[de:Multiboot USB Stick]]<br />
[[ja:マルチブート USB ドライブ]]<br />
{{Related articles start}}<br />
{{Related|GRUB}}<br />
{{Related|Syslinux}}<br />
{{Related|Archiso}}<br />
{{Related articles end}}<br />
{{Move|Multiboot disk images|See discussion|section=Scope and title}}<br />
A multiboot USB flash drive allows booting multiple ISO files from a single device. The ISO files can be copied to the device and booted directly without unpacking them first. There are multiple methods available, but they may not work for all ISO images.<br />
<br />
== Using GRUB and loopback devices ==<br />
<br />
{{Style|multiple [[Help:Style|style]] issues}}<br />
<br />
Advantages:<br />
* only a single partition required<br />
* all ISO files are found in one directory<br />
* adding and removing ISO files is simple<br />
<br />
Disadvantages:<br />
* not all ISO images are compatible<br />
* the original boot menu for the ISO file is not shown<br />
* it can be difficult to find a working boot entry<br />
<br />
=== Preparation ===<br />
<br />
{{Expansion|How much extra space is needed for the bootloader?}}<br />
<br />
Create at least one partition and a filesystem supported by [[GRUB]] on the USB drive. See [[Partitioning]] and [[File systems#Create a file system]]. Choose the size based on the total size of the ISO files that you want to store on the drive, and plan for extra space for the bootloader.<br />
<br />
=== Installing GRUB ===<br />
<br />
==== Simple installation ====<br />
<br />
Mount the filesystem located on the USB drive:<br />
<br />
# mount /dev/sdXY /mnt<br />
<br />
Create the directory /boot:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Install GRUB on the USB drive:<br />
<br />
# grub-install --target=i386-pc --recheck --boot-directory=/mnt/boot /dev/sdX<br />
<br />
In case you want to boot ISOs in UEFI mode, you have to install grub for the UEFI target:<br />
<br />
# grub-install --target x86_64-efi --efi-directory /mnt --boot-directory=/mnt/boot --removable<br />
<br />
For UEFI, the partition has to be the first one in an MBR partition table and formatted with FAT32.<br />
<br />
==== Hybrid UEFI GPT + BIOS GPT/MBR boot ====<br />
This configuration is useful for creating an universal USB key, bootable everywhere.<br />
First of all you must create a [[GPT]] partition table on your device. You need at least 3 partitions:<br />
# A BIOS boot partition (type EF02)<br />
# An EFI System partition (type EF00 with a [[EFI_System_Partition#Format_the_partition|FAT32 filesystem]])<br />
# Your data partition (use a filesystem supported by [[GRUB]])<br />
<br />
The BIOS boot partition must be sized 1 MB, while the EFI System partition can be at least as small as 50 MB. The data partition can take up the rest of the space of your drive.<br />
<br />
Next you must create a hybrid MBR partition table, as setting the boot flag on the protective MBR partition might not be enough.<br />
<br />
Hybrid MBR partition table creation example using gdisk:<br />
<br />
{{bc|<br />
# gdisk /dev/sdX<br />
<br />
Command (? for help): r<br />
Recovery/transformation command (? for help): h<br />
Type from one to three GPT partition numbers, separated by spaces, to be added to the hybrid MBR, in sequence: 1 2 3<br />
Place EFI GPT (0xEE) partition first in MBR (good for GRUB)? (Y/N): N<br />
<br />
Creating entry for GPT partition #1 (MBR partition #2)<br />
Enter an MBR hex code (default EF): <br />
Set the bootable flag? (Y/N): N<br />
<br />
Creating entry for GPT partition #2 (MBR partition #3)<br />
Enter an MBR hex code (default EF): <br />
Set the bootable flag? (Y/N): N<br />
<br />
Creating entry for GPT partition #3 (MBR partition #4)<br />
Enter an MBR hex code (default 83): <br />
Set the bootable flag? (Y/N): Y<br />
<br />
Recovery/transformation command (? for help): x<br />
Expert command (? for help): h<br />
Expert command (? for help): w<br />
<br />
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING<br />
PARTITIONS!!<br />
<br />
Do you want to proceed? (Y/N): Y<br />
}}<br />
<br />
You can now install GRUB to support both EFI + GPT and BIOS + GPT/MBR. The GRUB configuration (--boot-directory) can be kept in the same place.<br />
<br />
First, you need to mount the EFI System partition and the data partition of your USB drive. Then, you can install GRUB for EFI with:<br />
# grub-install --target=x86_64-efi --efi-directory=/EFI_MOUNTPOINT --boot-directory=/DATA_MOUNTPOINT/boot --removable --recheck<br />
<br />
And for BIOS with:<br />
# grub-install --target=i386-pc --boot-directory=/DATA_MOUNTPOINT/boot --recheck /dev/sdX<br />
<br />
As an additional fallback, you can also install GRUB on your MBR-bootable data partition:<br />
# grub-install --target=i386-pc --boot-directory=/DATA_MOUNTPOINT/boot --recheck /dev/sdX3<br />
<br />
{{Tip|Should you want to access the data partition in MS Windows (ie. NTFS, FAT) as a standard USB storage, you should consider placing it as the first Windows readable partition on the removable drive, otherwise it would not get a drive letter assigned. (That is, before the EFI FAT32 partition).}}<br />
<br />
=== Configuring GRUB ===<br />
<br />
==== Using a template ====<br />
There are some git projects which provide some pre-existing GRUB configuration files, and a nice generic {{ic|grub.cfg}} which can be used to load the other boot entries on demand, showing them only if the specified ISO files - or folders containing them - are present on the drive.<br />
<br />
Multiboot USB: https://github.com/aguslr/multibootusb<br />
<br />
GLIM (GRUB2 Live ISO Multiboot): https://github.com/thias/glim<br />
<br />
==== Manual configuration ====<br />
<br />
For the purpose of multiboot USB drive it is easier to edit {{ic|grub.cfg}} by hand instead of generating it. Alternatively, make the following changes in {{ic|/etc/grub.d/40_custom}} or {{ic|/mnt/boot/grub/custom.cfg}} and generate {{ic|/mnt/boot/grub/grub.cfg}} using [[GRUB#Generate the main configuration file|grub-mkconfig]].<br />
<br />
As it is recommend to use a [[Persistent block device naming|persistent name]] instead of {{ic|/dev/sd''xY''}} to identify the partition on the USB drive where the image files are located, define a variable for convenience to hold the value. If the ISO images are on the same partition as GRUB, use the following to read the UUID at boot time:<br />
<br />
{{hc|/mnt/boot/grub/grub.cfg|2=<br />
# path to the partition holding ISO images (using UUID)<br />
probe -u $root --set=rootuuid<br />
set imgdevpath="/dev/disk/by-uuid/$rootuuid"<br />
}}<br />
<br />
Or specify the UUID explicitly:<br />
<br />
{{hc|/mnt/boot/grub/grub.cfg|2=<br />
# path to the partition holding ISO images (using UUID)<br />
set imgdevpath="/dev/disk/by-uuid/''UUID_value''"<br />
}}<br />
<br />
Alternatively, use the device label instead of UUID:<br />
<br />
{{hc|/mnt/boot/grub/grub.cfg|2=<br />
# path to the partition holding ISO images (using labels)<br />
set imgdevpath="/dev/disk/by-label/''label_value''"<br />
}}<br />
<br />
The necessary UUID or label can be found using {{ic|lsblk -f}}. Do not use the same label as the Arch ISO for the USB device, otherwise the boot process will fail.<br />
<br />
To complete the configuration, a boot entry for each ISO image has to be added below this header, see the next section for examples.<br />
<br />
=== Boot entries ===<br />
<br />
It is assumed that the ISO images are stored in the {{ic|boot/iso/}} directory on the same filesystem where GRUB is installed. Otherwise it would be necessary to prefix the path to ISO file with device identification when using the {{ic|loopback}} command, for example {{ic|loopback loop '''(hd1,2)'''$isofile}}. As this identification of devices is not [[Persistent block device naming|persistent]], it is not used in the examples in this section.<br />
<br />
One can use persistent block device naming like so. Replace the UUID according to your ISO filesystem UUID.<br />
{{bc|1=<br />
# define globally (i.e outside any menuentry)<br />
insmod search_fs_uuid<br />
search --no-floppy --set='''isopart''' --fs-uuid ''123-456''<br />
# later use inside each menuentry instead<br />
loopback loop '''($isopart)'''$isofile<br />
}}<br />
<br />
{{Tip| For a list of kernel parameters, see [https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.rst kernel-parameters.rst] and [https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt kernel-parameters.txt] (still incomplete). For more examples of boot entries, see the [https://www.gnu.org/software/grub/manual/grub.html#Multi_002dboot-manual-config GRUB upstream documentation] or the documentation for the distribution you wish to boot.}}<br />
<br />
==== Arch Linux monthly release ====<br />
Also see [[archiso]].<br />
<br />
{{bc|1=<br />
menuentry '[loopback]archlinux-2017.10.01-x86_64.iso' {<br />
set isofile='/boot/iso/archlinux-2017.10.01-x86_64.iso'<br />
loopback loop $isofile<br />
linux (loop)/arch/boot/x86_64/vmlinuz archisodevice=/dev/loop0 img_dev=$imgdevpath img_loop=$isofile earlymodules=loop<br />
initrd (loop)/arch/boot/x86_64/archiso.img<br />
}<br />
}}<br />
<br />
{{note|As of archiso v23 (monthly release 2015.10.01), the parameter {{ic|1=archisodevice=/dev/loop0}} is no longer necessary when boot using GRUB and loopback devices.}}<br />
<br />
==== archboot ====<br />
Also see [[archboot]].<br />
<br />
{{bc|1=<br />
menuentry '[loopback]archlinux-2014.11-1-archboot' {<br />
set isofile='/boot/iso/archlinux-2014.11-1-archboot.iso'<br />
loopback loop $isofile<br />
linux (loop)/boot/vmlinuz_'''x86_64''' iso_loop_dev=$imgdevpath iso_loop_path=$isofile<br />
initrd (loop)/boot/initramfs_'''x86_64'''.img<br />
}<br />
}}<br />
<br />
== Using Syslinux and memdisk ==<br />
<br />
Using the [http://www.syslinux.org/wiki/index.php/MEMDISK memdisk] module, the ISO image is loaded into memory, and its bootloader is loaded. Make sure that the system that will boot this USB drive has sufficient amount of memory for the image file and running operating system.<br />
<br />
=== Preparation ===<br />
<br />
Make sure that the USB drive is properly [[Partitioning|partitioned]] and that there is a partition with [[file system]] supported by Syslinux, for example fat32 or ext4. Then install Syslinux to this partition, see [[Syslinux#Installation]]{{Broken section link}}.<br />
<br />
=== Install the memdisk module ===<br />
<br />
The memdisk module was not installed during Syslinux installation, it has to be installed manually. Mount the partition where Syslinux is installed to {{ic|/mnt/}} and copy the memdisk module to the same directory where Syslinux is installed:<br />
<br />
# cp /usr/lib/syslinux/bios/memdisk /mnt/boot/syslinux/<br />
<br />
=== Configuration ===<br />
<br />
After copying the ISO files on the USB drive, edit the [[Syslinux#Configuration|Syslinux configuration file]] and create menu entries for the ISO images. The basic entry looks like this:<br />
<br />
{{hc|boot/syslinux/syslinux.cfg|<br />
LABEL ''some_label''<br />
LINUX memdisk<br />
INITRD ''/path/to/image.iso''<br />
APPEND iso<br />
}}<br />
<br />
See [http://www.syslinux.org/wiki/index.php/MEMDISK memdisk on Syslinux wiki] for more configuration options.<br />
<br />
=== Caveat for 32-bit systems ===<br />
<br />
When booting a 32-bit system from an image larger than 128MiB, it is necessary to increase the maximum memory usage of vmalloc. This is done by adding {{ic|1=vmalloc=''value''M}} to the kernel parameters, where {{ic|''value''}} is larger than the size of the ISO image in MiB.[http://www.syslinux.org/wiki/index.php/MEMDISK#-_memdiskfind_in_combination_with_phram_and_mtdblock]<br />
<br />
For example when booting the 32-bit system from the [https://www.archlinux.org/download/ Arch installation ISO], press the {{ic|Tab}} key over the {{ic|Boot Arch Linux (i686)}} entry and add {{ic|1=vmalloc=768M}} at the end. Skipping this step will result in the following error during boot:<br />
<br />
modprobe: ERROR: could not insert 'phram': Input/output error<br />
<br />
== Using MultiBootUSB ==<br />
<br />
[http://multibootusb.org/ MultiBootUSB] is a cross platform software written in python which allows you to install multiple live linux on a USB disk non destructively and option to uninstall distros. Try out the world's first true cross platform multi boot live usb creator for free.<br />
<br />
The package {{AUR|multibootusb}} can be installed from the AUR. It includes both graphical and command line interfaces.<br />
<br />
== See also ==<br />
<br />
* GRUB:<br />
** https://help.ubuntu.com/community/Grub2/ISOBoot/Examples<br />
** https://help.ubuntu.com/community/Grub2/ISOBoot<br />
** [https://github.com/thias/glim GRUB Live ISO Multiboot] - GRUB configurations for booting ISO images<br />
* Syslinux:<br />
** [http://www.syslinux.org/wiki/index.php?title=Boot_an_Iso_image Boot an ISO image]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Multiboot_USB_drive&diff=506661Multiboot USB drive2018-01-08T18:46:30Z<p>EasyToRemember: /* Hybrid UEFI GPT + BIOS GPT/MBR boot */ Enable data partition in MS Windows</p>
<hr />
<div>[[Category:Boot process]]<br />
[[Category:Getting and installing Arch]]<br />
[[de:Multiboot USB Stick]]<br />
[[ja:マルチブート USB ドライブ]]<br />
{{Related articles start}}<br />
{{Related|GRUB}}<br />
{{Related|Syslinux}}<br />
{{Related|Archiso}}<br />
{{Related articles end}}<br />
{{Move|Multiboot disk images|See discussion|section=Scope and title}}<br />
A multiboot USB flash drive allows booting multiple ISO files from a single device. The ISO files can be copied to the device and booted directly without unpacking them first. There are multiple methods available, but they may not work for all ISO images.<br />
<br />
== Using GRUB and loopback devices ==<br />
<br />
{{Style|multiple [[Help:Style|style]] issues}}<br />
<br />
Advantages:<br />
* only a single partition required<br />
* all ISO files are found in one directory<br />
* adding and removing ISO files is simple<br />
<br />
Disadvantages:<br />
* not all ISO images are compatible<br />
* the original boot menu for the ISO file is not shown<br />
* it can be difficult to find a working boot entry<br />
<br />
=== Preparation ===<br />
<br />
{{Expansion|How much extra space is needed for the bootloader?}}<br />
<br />
Create at least one partition and a filesystem supported by [[GRUB]] on the USB drive. See [[Partitioning]] and [[File systems#Create a file system]]. Choose the size based on the total size of the ISO files that you want to store on the drive, and plan for extra space for the bootloader.<br />
<br />
=== Installing GRUB ===<br />
<br />
==== Simple installation ====<br />
<br />
Mount the filesystem located on the USB drive:<br />
<br />
# mount /dev/sdXY /mnt<br />
<br />
Create the directory /boot:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Install GRUB on the USB drive:<br />
<br />
# grub-install --target=i386-pc --recheck --boot-directory=/mnt/boot /dev/sdX<br />
<br />
In case you want to boot ISOs in UEFI mode, you have to install grub for the UEFI target:<br />
<br />
# grub-install --target x86_64-efi --efi-directory /mnt --boot-directory=/mnt/boot --removable<br />
<br />
For UEFI, the partition has to be the first one in an MBR partition table and formatted with FAT32.<br />
<br />
==== Hybrid UEFI GPT + BIOS GPT/MBR boot ====<br />
This configuration is useful for creating an universal USB key, bootable everywhere.<br />
First of all you must create a [[GPT]] partition table on your device. You need at least 3 partitions:<br />
# A BIOS boot partition (type EF02)<br />
# An EFI System partition (type EF00 with a [[EFI_System_Partition#Format_the_partition|FAT32 filesystem]])<br />
# Your data partition (use a filesystem supported by [[GRUB]])<br />
<br />
The BIOS boot partition must be sized 1 MB, while the EFI System partition can be at least as small as 50 MB. The data partition can take up the rest of the space of your drive.<br />
<br />
Next you must create a hybrid MBR partition table, as setting the boot flag on the protective MBR partition might not be enough.<br />
<br />
Hybrid MBR partition table creation example using gdisk:<br />
<br />
{{bc|<br />
# gdisk /dev/sdX<br />
<br />
Command (? for help): r<br />
Recovery/transformation command (? for help): h<br />
Type from one to three GPT partition numbers, separated by spaces, to be added to the hybrid MBR, in sequence: 1 2 3<br />
Place EFI GPT (0xEE) partition first in MBR (good for GRUB)? (Y/N): N<br />
<br />
Creating entry for GPT partition #1 (MBR partition #2)<br />
Enter an MBR hex code (default EF): <br />
Set the bootable flag? (Y/N): N<br />
<br />
Creating entry for GPT partition #2 (MBR partition #3)<br />
Enter an MBR hex code (default EF): <br />
Set the bootable flag? (Y/N): N<br />
<br />
Creating entry for GPT partition #3 (MBR partition #4)<br />
Enter an MBR hex code (default 83): <br />
Set the bootable flag? (Y/N): Y<br />
<br />
Recovery/transformation command (? for help): x<br />
Expert command (? for help): h<br />
Expert command (? for help): w<br />
<br />
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING<br />
PARTITIONS!!<br />
<br />
Do you want to proceed? (Y/N): Y<br />
}}<br />
<br />
You can now install GRUB to support both EFI + GPT and BIOS + GPT/MBR. The GRUB configuration (--boot-directory) can be kept in the same place.<br />
<br />
First, you need to mount the EFI System partition and the data partition of your USB drive. Then, you can install GRUB for EFI with:<br />
# grub-install --target=x86_64-efi --efi-directory=/EFI_MOUNTPOINT --boot-directory=/DATA_MOUNTPOINT/boot --removable --recheck<br />
<br />
And for BIOS with:<br />
# grub-install --target=i386-pc --boot-directory=/DATA_MOUNTPOINT/boot --recheck /dev/sdX<br />
<br />
As an additional fallback, you can also install GRUB on your MBR-bootable data partition:<br />
# grub-install --target=i386-pc --boot-directory=/DATA_MOUNTPOINT/boot --recheck /dev/sdX3<br />
<br />
{{Tip|Should you want to access the data partition on the flash drive in MS Windows (ie. NTFS, FAT) as a standard USB storage, you should consider placing it as the first Windows readable partition on the removable drive. That is, before the EFI partition (which is equivalent to FAT32).}}<br />
<br />
=== Configuring GRUB ===<br />
<br />
==== Using a template ====<br />
There are some git projects which provide some pre-existing GRUB configuration files, and a nice generic {{ic|grub.cfg}} which can be used to load the other boot entries on demand, showing them only if the specified ISO files - or folders containing them - are present on the drive.<br />
<br />
Multiboot USB: https://github.com/aguslr/multibootusb<br />
<br />
GLIM (GRUB2 Live ISO Multiboot): https://github.com/thias/glim<br />
<br />
==== Manual configuration ====<br />
<br />
For the purpose of multiboot USB drive it is easier to edit {{ic|grub.cfg}} by hand instead of generating it. Alternatively, make the following changes in {{ic|/etc/grub.d/40_custom}} or {{ic|/mnt/boot/grub/custom.cfg}} and generate {{ic|/mnt/boot/grub/grub.cfg}} using [[GRUB#Generate the main configuration file|grub-mkconfig]].<br />
<br />
As it is recommend to use a [[Persistent block device naming|persistent name]] instead of {{ic|/dev/sd''xY''}} to identify the partition on the USB drive where the image files are located, define a variable for convenience to hold the value. If the ISO images are on the same partition as GRUB, use the following to read the UUID at boot time:<br />
<br />
{{hc|/mnt/boot/grub/grub.cfg|2=<br />
# path to the partition holding ISO images (using UUID)<br />
probe -u $root --set=rootuuid<br />
set imgdevpath="/dev/disk/by-uuid/$rootuuid"<br />
}}<br />
<br />
Or specify the UUID explicitly:<br />
<br />
{{hc|/mnt/boot/grub/grub.cfg|2=<br />
# path to the partition holding ISO images (using UUID)<br />
set imgdevpath="/dev/disk/by-uuid/''UUID_value''"<br />
}}<br />
<br />
Alternatively, use the device label instead of UUID:<br />
<br />
{{hc|/mnt/boot/grub/grub.cfg|2=<br />
# path to the partition holding ISO images (using labels)<br />
set imgdevpath="/dev/disk/by-label/''label_value''"<br />
}}<br />
<br />
The necessary UUID or label can be found using {{ic|lsblk -f}}. Do not use the same label as the Arch ISO for the USB device, otherwise the boot process will fail.<br />
<br />
To complete the configuration, a boot entry for each ISO image has to be added below this header, see the next section for examples.<br />
<br />
=== Boot entries ===<br />
<br />
It is assumed that the ISO images are stored in the {{ic|boot/iso/}} directory on the same filesystem where GRUB is installed. Otherwise it would be necessary to prefix the path to ISO file with device identification when using the {{ic|loopback}} command, for example {{ic|loopback loop '''(hd1,2)'''$isofile}}. As this identification of devices is not [[Persistent block device naming|persistent]], it is not used in the examples in this section.<br />
<br />
One can use persistent block device naming like so. Replace the UUID according to your ISO filesystem UUID.<br />
{{bc|1=<br />
# define globally (i.e outside any menuentry)<br />
insmod search_fs_uuid<br />
search --no-floppy --set='''isopart''' --fs-uuid ''123-456''<br />
# later use inside each menuentry instead<br />
loopback loop '''($isopart)'''$isofile<br />
}}<br />
<br />
{{Tip| For a list of kernel parameters, see [https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.rst kernel-parameters.rst] and [https://www.kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt kernel-parameters.txt] (still incomplete). For more examples of boot entries, see the [https://www.gnu.org/software/grub/manual/grub.html#Multi_002dboot-manual-config GRUB upstream documentation] or the documentation for the distribution you wish to boot.}}<br />
<br />
==== Arch Linux monthly release ====<br />
Also see [[archiso]].<br />
<br />
{{bc|1=<br />
menuentry '[loopback]archlinux-2017.10.01-x86_64.iso' {<br />
set isofile='/boot/iso/archlinux-2017.10.01-x86_64.iso'<br />
loopback loop $isofile<br />
linux (loop)/arch/boot/x86_64/vmlinuz archisodevice=/dev/loop0 img_dev=$imgdevpath img_loop=$isofile earlymodules=loop<br />
initrd (loop)/arch/boot/x86_64/archiso.img<br />
}<br />
}}<br />
<br />
{{note|As of archiso v23 (monthly release 2015.10.01), the parameter {{ic|1=archisodevice=/dev/loop0}} is no longer necessary when boot using GRUB and loopback devices.}}<br />
<br />
==== archboot ====<br />
Also see [[archboot]].<br />
<br />
{{bc|1=<br />
menuentry '[loopback]archlinux-2014.11-1-archboot' {<br />
set isofile='/boot/iso/archlinux-2014.11-1-archboot.iso'<br />
loopback loop $isofile<br />
linux (loop)/boot/vmlinuz_'''x86_64''' iso_loop_dev=$imgdevpath iso_loop_path=$isofile<br />
initrd (loop)/boot/initramfs_'''x86_64'''.img<br />
}<br />
}}<br />
<br />
== Using Syslinux and memdisk ==<br />
<br />
Using the [http://www.syslinux.org/wiki/index.php/MEMDISK memdisk] module, the ISO image is loaded into memory, and its bootloader is loaded. Make sure that the system that will boot this USB drive has sufficient amount of memory for the image file and running operating system.<br />
<br />
=== Preparation ===<br />
<br />
Make sure that the USB drive is properly [[Partitioning|partitioned]] and that there is a partition with [[file system]] supported by Syslinux, for example fat32 or ext4. Then install Syslinux to this partition, see [[Syslinux#Installation]]{{Broken section link}}.<br />
<br />
=== Install the memdisk module ===<br />
<br />
The memdisk module was not installed during Syslinux installation, it has to be installed manually. Mount the partition where Syslinux is installed to {{ic|/mnt/}} and copy the memdisk module to the same directory where Syslinux is installed:<br />
<br />
# cp /usr/lib/syslinux/bios/memdisk /mnt/boot/syslinux/<br />
<br />
=== Configuration ===<br />
<br />
After copying the ISO files on the USB drive, edit the [[Syslinux#Configuration|Syslinux configuration file]] and create menu entries for the ISO images. The basic entry looks like this:<br />
<br />
{{hc|boot/syslinux/syslinux.cfg|<br />
LABEL ''some_label''<br />
LINUX memdisk<br />
INITRD ''/path/to/image.iso''<br />
APPEND iso<br />
}}<br />
<br />
See [http://www.syslinux.org/wiki/index.php/MEMDISK memdisk on Syslinux wiki] for more configuration options.<br />
<br />
=== Caveat for 32-bit systems ===<br />
<br />
When booting a 32-bit system from an image larger than 128MiB, it is necessary to increase the maximum memory usage of vmalloc. This is done by adding {{ic|1=vmalloc=''value''M}} to the kernel parameters, where {{ic|''value''}} is larger than the size of the ISO image in MiB.[http://www.syslinux.org/wiki/index.php/MEMDISK#-_memdiskfind_in_combination_with_phram_and_mtdblock]<br />
<br />
For example when booting the 32-bit system from the [https://www.archlinux.org/download/ Arch installation ISO], press the {{ic|Tab}} key over the {{ic|Boot Arch Linux (i686)}} entry and add {{ic|1=vmalloc=768M}} at the end. Skipping this step will result in the following error during boot:<br />
<br />
modprobe: ERROR: could not insert 'phram': Input/output error<br />
<br />
== Using MultiBootUSB ==<br />
<br />
[http://multibootusb.org/ MultiBootUSB] is a cross platform software written in python which allows you to install multiple live linux on a USB disk non destructively and option to uninstall distros. Try out the world's first true cross platform multi boot live usb creator for free.<br />
<br />
The package {{AUR|multibootusb}} can be installed from the AUR. It includes both graphical and command line interfaces.<br />
<br />
== See also ==<br />
<br />
* GRUB:<br />
** https://help.ubuntu.com/community/Grub2/ISOBoot/Examples<br />
** https://help.ubuntu.com/community/Grub2/ISOBoot<br />
** [https://github.com/thias/glim GRUB Live ISO Multiboot] - GRUB configurations for booting ISO images<br />
* Syslinux:<br />
** [http://www.syslinux.org/wiki/index.php?title=Boot_an_Iso_image Boot an ISO image]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Rsync&diff=505436Rsync2017-12-31T09:55:59Z<p>EasyToRemember: /* Snapshot backup */ Update of description to snapshots with cp -al</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data compression and archiving]]<br />
[[Category:System recovery]]<br />
[[es:Rsync]]<br />
[[ja:Rsync]]<br />
[[zh-hans:Rsync]]<br />
{{Related articles start}}<br />
{{Related|System backup}}<br />
{{Related|Synchronization and backup programs}}<br />
{{Related articles end}}<br />
[https://rsync.samba.org/ rsync] is an open source utility that provides fast incremental file transfer.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|rsync}} package.<br />
<br />
''rsync'' must be installed on both the source and the destination machine.<br />
<br />
=== Front-ends ===<br />
<br />
* {{App|Grsync|GTK+ front-end.|http://www.opbyte.it/grsync/|{{Pkg|grsync}}}}<br />
* {{App|gutback|rsync wrapper written in Shell.|https://github.com/gutenye/gutbackup|{{Aur|gutbackup}}}}<br />
* {{App|JotaSync|Java Swing GUI for rsync with integrated scheduler.|https://trixon.se/projects/jotasync/|{{Aur|jotasync}}}}<br />
* {{App|luckyBackup|Qt front-end written in C++.|http://luckybackup.sourceforge.net/index.html|{{Aur|luckybackup}}}}<br />
<br />
== As a cp alternative ==<br />
<br />
rsync can be used as an advanced alternative for the {{ic|cp}} command, especially for copying larger files:<br />
<br />
$ rsync -P source destination<br />
<br />
The {{ic|-P}} option is the same as {{Ic|--partial --progress}}, which keeps partially transferred files and shows a progress bar during transfer.<br />
<br />
You may want to use the {{ic|-r}}/{{ic|--recursive}} option to recurse into directories.<br />
<br />
Files can be copied locally as with cp, but the motivating purpose of rsync is to copy files remotely, i.e. between two different hosts. Remote locations can be specified with a host-colon syntax:<br />
<br />
$ rsync source host:destination<br />
<br />
or<br />
<br />
$ rsync host:source destination<br />
<br />
Network file transfers use the [[SSH]] protocol by default and {{ic|host}} can be a real hostname or a predefined profile/alias from {{ic|.ssh/config}}.<br />
<br />
{{Accuracy|By default, rsync does not compare contents of files. Rsync uses a "quick check" that (by default) checks if each file’s size and time of last modification match between the sender and receiver.}}<br />
<br />
Whether transferring files locally or remotely, rsync first creates an index of block checksums of each source file. This index is used to find any identical blocks of data which might exist in the destination. Such blocks are used in-place, rather than being copied from the source. This can greatly accelerate the synchronization of large files with small changes. For more information, see [https://rsync.samba.org/documentation.html official documentation], [https://rsync.samba.org/how-rsync-works.html how rsync works].<br />
<br />
=== Trailing slash caveat ===<br />
<br />
Arch by default uses GNU cp (part of [https://www.archlinux.org/packages/?name=coreutils GNU coreutils]). However, rsync follows the convention of BSD cp, which gives special treatment to source directories with a trailing slash "/". Although<br />
<br />
$ rsync -r source destination<br />
<br />
creates a directory "destination/source" with the contents of "source", the command<br />
<br />
$ rsync -r source/ destination<br />
<br />
copies all of the files in "source/" directly into "destination", with no intervening subdirectory - just as if you had invoked it as<br />
<br />
$ rsync -r source/. destination<br />
<br />
This behavior is different from that of GNU cp, which treats "source" and "source/" identically (but not "source/."). Also, some shells automatically append the trailing slash when tab-completing directory names. Because of these factors, there can be a tendency among new or occasional rsync users to forget about rsync's different behavior, and inadvertently create a mess or even overwrite important files by leaving the trailing slash on the command line.<br />
<br />
Thus it can be prudent to use a wrapper script to automatically remove trailing slashes before invoking rsync:<br />
<br />
#!/bin/zsh<br />
new_args=();<br />
for i in "$@"; do<br />
case $i in /) i=/;; */) i=${i%/};; esac<br />
new_args+=$i;<br />
done<br />
exec rsync "${(@)new_args}"<br />
<br />
This script can be put somewhere in the path, and aliased to rsync in the shell init file.<br />
<br />
== As a backup utility ==<br />
<br />
The rsync protocol can easily be used for backups, only transferring files that have changed since the last backup. This section describes a very simple scheduled backup script using rsync, typically used for copying to removable media.<br />
<br />
=== Automated backup ===<br />
<br />
For the sake of this example, the script is created in the {{ic|/etc/cron.daily}} directory, and will be run on a daily basis if a cron [[daemon]] is installed and properly configured. Configuring and using [[cron]] is outside the scope of this article.<br />
<br />
First, create a script containing the appropriate command options:<br />
<br />
{{hc|/etc/cron.daily/backup|<br />
#!/bin/bash<br />
rsync -a --delete --quiet /folder/to/backup /location/of/backup}}<br />
<br />
; {{ic|-a}} : indicates that files should be archived, meaning that most of their characteristics are preserved (but '''not''' ACLs, hard links or extended attributes such as capabilities)<br />
; {{ic|--delete}} : means files deleted on the source are to be deleted on the backup as well<br />
<br />
Here, {{ic|/folder/to/backup}} should be changed to what needs to be backed-up ({{ic|/home}}, for example) and {{ic|/location/to/backup}} is where the backup should be saved ({{ic|/media/disk}}, for instance).<br />
<br />
Finally, the script must be executable:<br />
<br />
# chmod +x /etc/cron.daily/backup<br />
<br />
=== Automated backup with SSH ===<br />
<br />
If backing-up to a remote host using [[SSH]], use this script instead:<br />
<br />
{{hc|/etc/cron.daily/backup|<br />
#!/bin/bash<br />
rsync -a --delete --quiet -e ssh /folder/to/backup remoteuser@remotehost:/location/of/backup<br />
}}<br />
<br />
; {{ic|-e ssh}} : tells rsync to use SSH<br />
; {{ic|remoteuser}} : is the user on the host {{ic|remotehost}}<br />
; {{ic|-a}} : groups all these options {{ic|-rlptgoD}} (recursive, links, perms, times, group, owner, devices)<br />
<br />
=== Automated backup with NetworkManager ===<br />
<br />
This script starts a backup when network connection is established.<br />
<br />
First, create a script containing the appropriate command options:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/backup|2=<br />
#!/bin/bash<br />
<br />
if [ x"$2" = "xup" ] ; then<br />
rsync --force --ignore-errors -a --delete --bwlimit=2000 --files-from=files.rsync /folder/to/backup /location/to/backup<br />
fi<br />
}}<br />
<br />
; {{ic|-a}} : group all this options {{ic|-rlptgoD}} recursive, links, perms, times, group, owner, devices<br />
; {{ic|--files-from}} : read the relative path of ''/folder/to/backup'' from this file<br />
; {{ic|--bwlimit}} : limit I/O bandwidth; KBytes per second<br />
<br />
Also, the script must have write permission for owner (root, of course) only (see [[NetworkManager#Network services with NetworkManager dispatcher]] for details).<br />
<br />
=== Automated backup with systemd and inotify ===<br />
<br />
{{Note|<br />
* Due to the limitations of inotify and systemd (see [http://www.quora.com/Linux-Kernel/Inotify-monitoring-of-directories-is-not-recursive-Is-there-any-specific-reason-for-this-design-in-Linux-kernel this question and answer]), recursive filesystem monitoring is not possible. Although you can watch a directory and its contents, it will not recurse into subdirectories and watch the contents of them; you must explicitly specify every directory to watch, even if that directory is a child of an already watched directory.<br />
* This setup is based on a [[systemd/User]] instance.<br />
}}<br />
<br />
Instead of running time interval backups with time based schedules, such as those implemented in [[cron]], it is possible to run a backup every time one of the files you are backing up changes. {{ic|systemd.path}} units use {{ic|inotify}} to monitor the filesystem, and can be used in conjunction with {{ic|systemd.service}} files to start any process (in this case your [[rsync]] backup) based on a filesystem event.<br />
<br />
First, create the {{ic|systemd.path}} file that will monitor the files you are backing up:<br />
<br />
{{hc|~/.config/systemd/user/backup.path|<nowiki><br />
[Unit]<br />
Description=Checks if paths that are currently being backed up have changed<br />
<br />
[Path]<br />
PathChanged=%h/documents<br />
PathChanged=%h/music<br />
<br />
[Install]<br />
WantedBy=default.target<br />
</nowiki>}}<br />
<br />
Then create a {{ic|systemd.service}} file that will be activated when it detects a change. By default a service file of the same name as the path unit (in this case {{ic|backup.path}}) will be activated, except with the {{ic|.service}} extension instead of {{ic|.path}} (in this case {{ic|backup.service}}).<br />
<br />
{{Note|If you need to run multiple rsync commands, use {{ic|1=Type=oneshot}}. This allows you to specify multiple {{ic|1=ExecStart=}} parameters, one for each [[rsync]] command, that will be executed. Alternatively, you can simply write a script to perform all of your backups, just like [[cron]] scripts.}}<br />
<br />
{{hc|~/.config/systemd/user/backup.service|<nowiki><br />
[Unit]<br />
Description=Backs up files<br />
<br />
[Service]<br />
ExecStart=/usr/bin/rsync %h/./documents %h/./music -CERrltm --delete ubuntu:<br />
</nowiki>}}<br />
<br />
Now all you have to do is [[start]]/enable {{ic|backup.path}} like a normal systemd service and it will start monitoring file changes and automatically starting {{ic|backup.service}}.<br />
<br />
=== Differential backup on a week ===<br />
<br />
This is a useful option of rsync, resulting in a full backup (on each run) and keeping a differential backup copy of changed files only in a separate directory for each day of a week.<br />
<br />
First, create a script containing the appropriate command options:<br />
<br />
{{hc|/etc/cron.daily/backup|2=<br />
#!/bin/bash<br />
<br />
DAY=$(date +%A)<br />
<br />
if [ -e /location/to/backup/incr/$DAY ] ; then<br />
rm -fr /location/to/backup/incr/$DAY<br />
fi<br />
<br />
rsync -a --delete --quiet --inplace --backup --backup-dir=/location/to/backup/incr/$DAY /folder/to/backup/ /location/to/backup/full/<br />
}}<br />
<br />
; {{ic|--inplace}} : implies {{ic|--partial}} update destination files in-place<br />
<br />
=== Snapshot backup ===<br />
<br />
The same idea can be used to maintain a tree of snapshots of your files. In other words, a directory with date-ordered copies of the files. The copies are made using hardlinks, which means that only files that did change will occupy space. Generally speaking, this is the idea behind Apple's TimeMachine.<br />
<br />
This basic script is easy to implement and creates quick incremental snapshots using the {{ic|--link-dest}} option to hardlink unchanged files: <br />
<br />
{{hc|/usr/local/bin/snapbackup.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Basic snapshot-style rsync backup script <br />
<br />
# Config<br />
OPT="-aPh"<br />
LINK="--link-dest=/snapshots/username/last/" <br />
SRC="/home/username/files/"<br />
SNAP="/snapshots/username/"<br />
LAST="/snapshots/username/last"<br />
date=`date "+%Y-%b-%d:_%T"`<br />
<br />
# Run rsync to create snapshot<br />
rsync $OPT $LINK $SRC ${SNAP}$date<br />
<br />
# Remove symlink to previous snapshot<br />
rm -f $LAST<br />
<br />
# Create new symlink to latest snapshot for the next backup to hardlink<br />
ln -s ${SNAP}$date $LAST<br />
</nowiki>}}<br />
<br />
There must be a symlink to a full backup already in existence as a target for {{ic|--link-dest}}. If the most recent snapshot is deleted, the symlink will need to be recreated to point to the most recent snapshot. If {{ic|--link-dest}} does not find a working symlink, rsync will proceed to copy all source files instead of only the changes. <br />
<br />
A more sophisticated version keeps an up-to-date full backup {{ic|$SNAP/latest}} and in case a certain number of files has changed since the last full backup, it creates a snapshot {{ic|$SNAP/$DATETAG}} of the current full-backup utilizing {{ic|cp -al}} to hardlink unchanged files:<br />
<br />
{{hc|/usr/local/bin/rsnapshot.sh|<nowiki><br />
#!/bin/bash<br />
<br />
## my own rsync-based snapshot-style backup procedure<br />
## (cc) marcio rps AT gmail.com<br />
<br />
# config vars<br />
<br />
SRC="/home/username/files/" #dont forget trailing slash!<br />
SNAP="/snapshots/username"<br />
OPTS="-rltgoi --delay-updates --delete --chmod=a-w"<br />
MINCHANGES=20<br />
<br />
# run this process with real low priority<br />
<br />
ionice -c 3 -p $$<br />
renice +12 -p $$<br />
<br />
# sync<br />
<br />
rsync $OPTS $SRC $SNAP/latest >> $SNAP/rsync.log<br />
<br />
# check if enough has changed and if so<br />
# make a hardlinked copy named as the date<br />
<br />
COUNT=$( wc -l $SNAP/rsync.log|cut -d" " -f1 )<br />
if [ $COUNT -gt $MINCHANGES ] ; then<br />
DATETAG=$(date +%Y-%m-%d)<br />
if [ ! -e $SNAP/$DATETAG ] ; then<br />
cp -al $SNAP/latest $SNAP/$DATETAG<br />
chmod u+w $SNAP/$DATETAG<br />
mv $SNAP/rsync.log $SNAP/$DATETAG<br />
chmod u-w $SNAP/$DATETAG<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
To make things really, really simple this script can be run from a [[systemd/Timers]] unit.<br />
<br />
=== Full system backup ===<br />
<br />
This section is about using ''rsync'' to transfer a copy of the entire {{ic|/}} tree, excluding a few selected folders. This approach is considered to be better than [[disk cloning]] with {{ic|dd}} since it allows for a different size, partition table and filesystem to be used, and better than copying with {{ic|cp -a}} as well, because it allows greater control over file permissions, attributes, [[Access Control Lists]] and [[extended attributes]].<br />
<br />
''rsync'' will work even while the system is running, but files changed during the transfer may or may not be transferred, which can cause undefined behavior of some programs using the transferred files.<br />
<br />
This approach works well for migrating an existing installation to a new hard drive or [[SSD]].<br />
<br />
Run the following command as root to make sure that rsync can access all system files and preserve the ownership:<br />
<br />
# rsync -aAXv --exclude={"/dev/*","/proc/*","/sys/*","/tmp/*","/run/*","/mnt/*","/media/*","/lost+found"} / ''/path/to/backup/folder''<br />
<br />
By using the {{ic|-aAX}} set of options, the files are transferred in archive mode which ensures that symbolic links, devices, permissions, ownerships, modification times, [[ACL]]s, and extended attributes are preserved, assuming that the target [[file system]] supports the feature.<br />
<br />
The {{ic|--exclude}} option causes files that match the given patterns to be excluded. The contents of {{ic|/dev}}, {{ic|/proc}}, {{ic|/sys}}, {{ic|/tmp}}, and {{ic|/run}} are excluded in the above command, because they are populated at boot, although the folders themselves are ''not'' created. {{ic|/lost+found}} is filesystem-specific. The command above depends on brace expansion available in both the [https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html bash] and [http://zsh.sourceforge.net/Doc/Release/Expansion.html#Brace-Expansion zsh] shells. When using a different [[shell]], {{ic|--exclude}} patterns should be repeated manually. Quoting the exclude patterns will avoid expansion by the [[shell]], which is necessary, for example, when backing up over [[SSH]]. Ending the excluded paths with {{ic|*}} ensures that the directories themselves are created if they do not already exist.<br />
<br />
{{Note|<br />
* If you plan on backing up your system somewhere other than {{ic|/mnt}} or {{ic|/media}}, do not forget to add it to the list of exclude patterns to avoid an infinite loop.<br />
* If there are any bind mounts in the system, they should be excluded as well so that the bind mounted contents is copied only once.<br />
* If you use a [[swap file]], make sure to exclude it as well.<br />
* Consider if you want to backup the {{ic|/home/}} folder. If it contains your data it might be considerably larger than the system. Otherwise consider excluding unimportant subdirectories such as {{ic|/home/*/.thumbnails/*}}, {{ic|/home/*/.cache/mozilla/*}}, {{ic|/home/*/.cache/chromium/*}}, and {{ic|/home/*/.local/share/Trash/*}}, depending on software installed on the system. If [[GVFS]] is installed, {{ic|/home/*/.gvfs}} must be excluded to prevent rsync errors.<br />
}}<br />
<br />
You may want to include additional [[rsync]] options, such as the following. See {{man|1|rsync}} for the full list.<br />
<br />
* If you use many hard links, consider adding the {{ic|-H}} option, which is turned off by default due to its memory expense; however, it should be no problem on most modern machines. Many hard links reside under the {{ic|/usr/}} directory.<br />
* You may want to add rsync's {{ic|--delete}} option if you are running this multiple times to the same backup folder. In this case make sure that the source path does not end with {{ic|/*}}, or this option will only have effect on the files inside the subdirectories of the source directory, but it will have no effect on the files residing directly inside the source directory.<br />
* If you use any sparse files, such as virtual disks, [[Docker]] images and similar, you should add the {{ic|-S}} option.<br />
* The {{ic|--numeric-ids}} option will disable mapping of user and group names; instead, numeric group and user IDs will be transfered. This is useful when backing up over [[SSH]] or when using a live system to backup different system disk.<br />
* Choosing {{ic|1=--info=progress2}} option instead of {{ic|-v}} will show the overall progress info and transfer speed instead of the list of files being transferred.<br />
<br />
=== Restore a backup ===<br />
<br />
If you wish to restore a backup, use the same rsync command that was executed but with the source and destination reversed.<br />
<br />
== File system cloning ==<br />
<br />
rsync provides a way to do a copy of all data in a file system while preserving as much information as possible, including the file system metadata. It is a procedure of data cloning on a file system level where source and destination file systems don't need to be of the same type. It can be used for backing up, file system migration or data recovery.<br />
<br />
rsync's ''archive'' mode comes close to being fit for the job, but it doesn't back up the special file system metadata such as access control lists, extended attributes or sparse file properties. For successful cloning at the file system level, some additional options need to be provided:<br />
<br />
rsync -qaHAXS SOURCE_DIR DESTINATION_DIR<br />
<br />
And their meaning is (from the manpage):<br />
<br />
-H, --hard-links preserve hard links<br />
-A, --acls preserve ACLs (implies -p)<br />
-X, --xattrs preserve extended attributes<br />
-S, --sparse handle sparse files efficiently<br />
<br />
Produced copy can be simply reread and checked (for example after a data recovery attempt) at the file system level with {{ic|diff}}'s recursive option:<br />
<br />
diff -r SOURCE_DIR DESTINATION_DIR<br />
<br />
It is possible to do a successful file system migration by using rsync as described in this article and updating the [[fstab]] and [[bootloader]] as described in [[Migrate installation to new hardware]]. This essentially provides a way to convert any root file system to another one.<br />
<br />
== rsync daemon ==<br />
<br />
''rsync'' can be run as daemon on a server listening on port {{ic|873}}.<br />
<br />
Edit the template {{ic|/etc/rsyncd.conf}}, configure a share and [[start]] the {{ic|rsyncd.service}}.<br />
<br />
{{Note|As of {{Pkg|rsync}}-3.1.2-5 the systemd unit {{ic|rsyncd.service}} included in the package adds security feature {{ic|1=ProtectSystem=full}} ({{ic|1=ProtectHome=on}} has been undone in {{Pkg|rsync}}-3.1.2-8) under the {{ic|[Service]}} section. This makes the {{ic|/boot/}}, {{ic|/etc/}} and {{ic|/usr/}} directories read-only. If you need rsyncd write system directories you can [[edit]] the unit and set {{ic|1=ProtectSystem=off}} in the {{ic|[Service]}} section of the overriding snippet.}}<br />
<br />
Usage from client, e.g. list server content:<br />
<br />
$ rsync rsync://''server/share''<br />
<br />
transfer file from client to server: <br />
<br />
$ rsync ''local-file'' rsync://''server/share/''<br />
<br />
Consider iptables to open port {{ic|873}} and user authentication.<br />
<br />
{{Note|All transferred data including user authentication are not encrypted.}}<br />
<br />
== See also ==<br />
<br />
* More usage examples can be searched in the [https://bbs.archlinux.org/viewforum.php?id=27 Community Contributions] and [https://bbs.archlinux.org/viewforum.php?id=33 General Programming] forums<br />
* [http://www.pointsoftware.ch/en/howto-local-and-remote-snapshot-backup-using-rsync-with-hard-links/ Howto – local and remote snapshot backup using rsync with hard links] Includes file deduplication with hard-links, MD5 integrity signature, 'chattr' protection, filter rules, disk quota, retention policy with exponential distribution (backups rotation while saving more recent backups than older)<br />
* [https://stackoverflow.com/questions/5527068/how-do-you-use-an-identity-file-with-rsync Using SSH keys/identity files with rsync]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=Rsync&diff=505424Rsync2017-12-31T09:08:29Z<p>EasyToRemember: /* Differential backup on a week */ Updated description</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Data compression and archiving]]<br />
[[Category:System recovery]]<br />
[[es:Rsync]]<br />
[[ja:Rsync]]<br />
[[zh-hans:Rsync]]<br />
{{Related articles start}}<br />
{{Related|System backup}}<br />
{{Related|Synchronization and backup programs}}<br />
{{Related articles end}}<br />
[https://rsync.samba.org/ rsync] is an open source utility that provides fast incremental file transfer.<br />
<br />
== Installation ==<br />
<br />
[[Install]] the {{Pkg|rsync}} package.<br />
<br />
''rsync'' must be installed on both the source and the destination machine.<br />
<br />
=== Front-ends ===<br />
<br />
* {{App|Grsync|GTK+ front-end.|http://www.opbyte.it/grsync/|{{Pkg|grsync}}}}<br />
* {{App|gutback|rsync wrapper written in Shell.|https://github.com/gutenye/gutbackup|{{Aur|gutbackup}}}}<br />
* {{App|JotaSync|Java Swing GUI for rsync with integrated scheduler.|https://trixon.se/projects/jotasync/|{{Aur|jotasync}}}}<br />
* {{App|luckyBackup|Qt front-end written in C++.|http://luckybackup.sourceforge.net/index.html|{{Aur|luckybackup}}}}<br />
<br />
== As a cp alternative ==<br />
<br />
rsync can be used as an advanced alternative for the {{ic|cp}} command, especially for copying larger files:<br />
<br />
$ rsync -P source destination<br />
<br />
The {{ic|-P}} option is the same as {{Ic|--partial --progress}}, which keeps partially transferred files and shows a progress bar during transfer.<br />
<br />
You may want to use the {{ic|-r}}/{{ic|--recursive}} option to recurse into directories.<br />
<br />
Files can be copied locally as with cp, but the motivating purpose of rsync is to copy files remotely, i.e. between two different hosts. Remote locations can be specified with a host-colon syntax:<br />
<br />
$ rsync source host:destination<br />
<br />
or<br />
<br />
$ rsync host:source destination<br />
<br />
Network file transfers use the [[SSH]] protocol by default and {{ic|host}} can be a real hostname or a predefined profile/alias from {{ic|.ssh/config}}.<br />
<br />
{{Accuracy|By default, rsync does not compare contents of files. Rsync uses a "quick check" that (by default) checks if each file’s size and time of last modification match between the sender and receiver.}}<br />
<br />
Whether transferring files locally or remotely, rsync first creates an index of block checksums of each source file. This index is used to find any identical blocks of data which might exist in the destination. Such blocks are used in-place, rather than being copied from the source. This can greatly accelerate the synchronization of large files with small changes. For more information, see [https://rsync.samba.org/documentation.html official documentation], [https://rsync.samba.org/how-rsync-works.html how rsync works].<br />
<br />
=== Trailing slash caveat ===<br />
<br />
Arch by default uses GNU cp (part of [https://www.archlinux.org/packages/?name=coreutils GNU coreutils]). However, rsync follows the convention of BSD cp, which gives special treatment to source directories with a trailing slash "/". Although<br />
<br />
$ rsync -r source destination<br />
<br />
creates a directory "destination/source" with the contents of "source", the command<br />
<br />
$ rsync -r source/ destination<br />
<br />
copies all of the files in "source/" directly into "destination", with no intervening subdirectory - just as if you had invoked it as<br />
<br />
$ rsync -r source/. destination<br />
<br />
This behavior is different from that of GNU cp, which treats "source" and "source/" identically (but not "source/."). Also, some shells automatically append the trailing slash when tab-completing directory names. Because of these factors, there can be a tendency among new or occasional rsync users to forget about rsync's different behavior, and inadvertently create a mess or even overwrite important files by leaving the trailing slash on the command line.<br />
<br />
Thus it can be prudent to use a wrapper script to automatically remove trailing slashes before invoking rsync:<br />
<br />
#!/bin/zsh<br />
new_args=();<br />
for i in "$@"; do<br />
case $i in /) i=/;; */) i=${i%/};; esac<br />
new_args+=$i;<br />
done<br />
exec rsync "${(@)new_args}"<br />
<br />
This script can be put somewhere in the path, and aliased to rsync in the shell init file.<br />
<br />
== As a backup utility ==<br />
<br />
The rsync protocol can easily be used for backups, only transferring files that have changed since the last backup. This section describes a very simple scheduled backup script using rsync, typically used for copying to removable media.<br />
<br />
=== Automated backup ===<br />
<br />
For the sake of this example, the script is created in the {{ic|/etc/cron.daily}} directory, and will be run on a daily basis if a cron [[daemon]] is installed and properly configured. Configuring and using [[cron]] is outside the scope of this article.<br />
<br />
First, create a script containing the appropriate command options:<br />
<br />
{{hc|/etc/cron.daily/backup|<br />
#!/bin/bash<br />
rsync -a --delete --quiet /folder/to/backup /location/of/backup}}<br />
<br />
; {{ic|-a}} : indicates that files should be archived, meaning that most of their characteristics are preserved (but '''not''' ACLs, hard links or extended attributes such as capabilities)<br />
; {{ic|--delete}} : means files deleted on the source are to be deleted on the backup as well<br />
<br />
Here, {{ic|/folder/to/backup}} should be changed to what needs to be backed-up ({{ic|/home}}, for example) and {{ic|/location/to/backup}} is where the backup should be saved ({{ic|/media/disk}}, for instance).<br />
<br />
Finally, the script must be executable:<br />
<br />
# chmod +x /etc/cron.daily/backup<br />
<br />
=== Automated backup with SSH ===<br />
<br />
If backing-up to a remote host using [[SSH]], use this script instead:<br />
<br />
{{hc|/etc/cron.daily/backup|<br />
#!/bin/bash<br />
rsync -a --delete --quiet -e ssh /folder/to/backup remoteuser@remotehost:/location/of/backup<br />
}}<br />
<br />
; {{ic|-e ssh}} : tells rsync to use SSH<br />
; {{ic|remoteuser}} : is the user on the host {{ic|remotehost}}<br />
; {{ic|-a}} : groups all these options {{ic|-rlptgoD}} (recursive, links, perms, times, group, owner, devices)<br />
<br />
=== Automated backup with NetworkManager ===<br />
<br />
This script starts a backup when network connection is established.<br />
<br />
First, create a script containing the appropriate command options:<br />
<br />
{{hc|/etc/NetworkManager/dispatcher.d/backup|2=<br />
#!/bin/bash<br />
<br />
if [ x"$2" = "xup" ] ; then<br />
rsync --force --ignore-errors -a --delete --bwlimit=2000 --files-from=files.rsync /folder/to/backup /location/to/backup<br />
fi<br />
}}<br />
<br />
; {{ic|-a}} : group all this options {{ic|-rlptgoD}} recursive, links, perms, times, group, owner, devices<br />
; {{ic|--files-from}} : read the relative path of ''/folder/to/backup'' from this file<br />
; {{ic|--bwlimit}} : limit I/O bandwidth; KBytes per second<br />
<br />
Also, the script must have write permission for owner (root, of course) only (see [[NetworkManager#Network services with NetworkManager dispatcher]] for details).<br />
<br />
=== Automated backup with systemd and inotify ===<br />
<br />
{{Note|<br />
* Due to the limitations of inotify and systemd (see [http://www.quora.com/Linux-Kernel/Inotify-monitoring-of-directories-is-not-recursive-Is-there-any-specific-reason-for-this-design-in-Linux-kernel this question and answer]), recursive filesystem monitoring is not possible. Although you can watch a directory and its contents, it will not recurse into subdirectories and watch the contents of them; you must explicitly specify every directory to watch, even if that directory is a child of an already watched directory.<br />
* This setup is based on a [[systemd/User]] instance.<br />
}}<br />
<br />
Instead of running time interval backups with time based schedules, such as those implemented in [[cron]], it is possible to run a backup every time one of the files you are backing up changes. {{ic|systemd.path}} units use {{ic|inotify}} to monitor the filesystem, and can be used in conjunction with {{ic|systemd.service}} files to start any process (in this case your [[rsync]] backup) based on a filesystem event.<br />
<br />
First, create the {{ic|systemd.path}} file that will monitor the files you are backing up:<br />
<br />
{{hc|~/.config/systemd/user/backup.path|<nowiki><br />
[Unit]<br />
Description=Checks if paths that are currently being backed up have changed<br />
<br />
[Path]<br />
PathChanged=%h/documents<br />
PathChanged=%h/music<br />
<br />
[Install]<br />
WantedBy=default.target<br />
</nowiki>}}<br />
<br />
Then create a {{ic|systemd.service}} file that will be activated when it detects a change. By default a service file of the same name as the path unit (in this case {{ic|backup.path}}) will be activated, except with the {{ic|.service}} extension instead of {{ic|.path}} (in this case {{ic|backup.service}}).<br />
<br />
{{Note|If you need to run multiple rsync commands, use {{ic|1=Type=oneshot}}. This allows you to specify multiple {{ic|1=ExecStart=}} parameters, one for each [[rsync]] command, that will be executed. Alternatively, you can simply write a script to perform all of your backups, just like [[cron]] scripts.}}<br />
<br />
{{hc|~/.config/systemd/user/backup.service|<nowiki><br />
[Unit]<br />
Description=Backs up files<br />
<br />
[Service]<br />
ExecStart=/usr/bin/rsync %h/./documents %h/./music -CERrltm --delete ubuntu:<br />
</nowiki>}}<br />
<br />
Now all you have to do is [[start]]/enable {{ic|backup.path}} like a normal systemd service and it will start monitoring file changes and automatically starting {{ic|backup.service}}.<br />
<br />
=== Differential backup on a week ===<br />
<br />
This is a useful option of rsync, resulting in a full backup (on each run) and keeping a differential backup copy of changed files only in a separate directory for each day of a week.<br />
<br />
First, create a script containing the appropriate command options:<br />
<br />
{{hc|/etc/cron.daily/backup|2=<br />
#!/bin/bash<br />
<br />
DAY=$(date +%A)<br />
<br />
if [ -e /location/to/backup/incr/$DAY ] ; then<br />
rm -fr /location/to/backup/incr/$DAY<br />
fi<br />
<br />
rsync -a --delete --quiet --inplace --backup --backup-dir=/location/to/backup/incr/$DAY /folder/to/backup/ /location/to/backup/full/<br />
}}<br />
<br />
; {{ic|--inplace}} : implies {{ic|--partial}} update destination files in-place<br />
<br />
=== Snapshot backup ===<br />
<br />
The same idea can be used to maintain a tree of snapshots of your files. In other words, a directory with date-ordered copies of the files. The copies are made using hardlinks, which means that only files that did change will occupy space. Generally speaking, this is the idea behind Apple's TimeMachine.<br />
<br />
This basic script is easy to implement and creates quick incremental snapshots using the {{ic|--link-dest}} option to hardlink unchanged files: <br />
<br />
{{hc|/usr/local/bin/snapbackup.sh|<nowiki><br />
#!/bin/bash<br />
<br />
# Basic snapshot-style rsync backup script <br />
<br />
# Config<br />
OPT="-aPh"<br />
LINK="--link-dest=/snapshots/username/last/" <br />
SRC="/home/username/files/"<br />
SNAP="/snapshots/username/"<br />
LAST="/snapshots/username/last"<br />
date=`date "+%Y-%b-%d:_%T"`<br />
<br />
# Run rsync to create snapshot<br />
rsync $OPT $LINK $SRC ${SNAP}$date<br />
<br />
# Remove symlink to previous snapshot<br />
rm -f $LAST<br />
<br />
# Create new symlink to latest snapshot for the next backup to hardlink<br />
ln -s ${SNAP}$date $LAST<br />
</nowiki>}}<br />
<br />
There must be a symlink to a full backup already in existence as a target for {{ic|--link-dest}}. If the most recent snapshot is deleted, the symlink will need to be recreated to point to the most recent snapshot. If {{ic|--link-dest}} does not find a working symlink, rsync will proceed to copy all source files instead of only the changes. <br />
<br />
A more sophisticated version checks to see if a certain number of changes have been made before making the backup and utilizes {{ic|cp -al}} to hardlink unchanged files:<br />
<br />
{{hc|/usr/local/bin/rsnapshot.sh|<nowiki><br />
#!/bin/bash<br />
<br />
## my own rsync-based snapshot-style backup procedure<br />
## (cc) marcio rps AT gmail.com<br />
<br />
# config vars<br />
<br />
SRC="/home/username/files/" #dont forget trailing slash!<br />
SNAP="/snapshots/username"<br />
OPTS="-rltgoi --delay-updates --delete --chmod=a-w"<br />
MINCHANGES=20<br />
<br />
# run this process with real low priority<br />
<br />
ionice -c 3 -p $$<br />
renice +12 -p $$<br />
<br />
# sync<br />
<br />
rsync $OPTS $SRC $SNAP/latest >> $SNAP/rsync.log<br />
<br />
# check if enough has changed and if so<br />
# make a hardlinked copy named as the date<br />
<br />
COUNT=$( wc -l $SNAP/rsync.log|cut -d" " -f1 )<br />
if [ $COUNT -gt $MINCHANGES ] ; then<br />
DATETAG=$(date +%Y-%m-%d)<br />
if [ ! -e $SNAP/$DATETAG ] ; then<br />
cp -al $SNAP/latest $SNAP/$DATETAG<br />
chmod u+w $SNAP/$DATETAG<br />
mv $SNAP/rsync.log $SNAP/$DATETAG<br />
chmod u-w $SNAP/$DATETAG<br />
fi<br />
fi<br />
</nowiki>}}<br />
<br />
To make things really, really simple this script can be run from a [[systemd/Timers]] unit.<br />
<br />
=== Full system backup ===<br />
<br />
This section is about using ''rsync'' to transfer a copy of the entire {{ic|/}} tree, excluding a few selected folders. This approach is considered to be better than [[disk cloning]] with {{ic|dd}} since it allows for a different size, partition table and filesystem to be used, and better than copying with {{ic|cp -a}} as well, because it allows greater control over file permissions, attributes, [[Access Control Lists]] and [[extended attributes]].<br />
<br />
''rsync'' will work even while the system is running, but files changed during the transfer may or may not be transferred, which can cause undefined behavior of some programs using the transferred files.<br />
<br />
This approach works well for migrating an existing installation to a new hard drive or [[SSD]].<br />
<br />
Run the following command as root to make sure that rsync can access all system files and preserve the ownership:<br />
<br />
# rsync -aAXv --exclude={"/dev/*","/proc/*","/sys/*","/tmp/*","/run/*","/mnt/*","/media/*","/lost+found"} / ''/path/to/backup/folder''<br />
<br />
By using the {{ic|-aAX}} set of options, the files are transferred in archive mode which ensures that symbolic links, devices, permissions, ownerships, modification times, [[ACL]]s, and extended attributes are preserved, assuming that the target [[file system]] supports the feature.<br />
<br />
The {{ic|--exclude}} option causes files that match the given patterns to be excluded. The contents of {{ic|/dev}}, {{ic|/proc}}, {{ic|/sys}}, {{ic|/tmp}}, and {{ic|/run}} are excluded in the above command, because they are populated at boot, although the folders themselves are ''not'' created. {{ic|/lost+found}} is filesystem-specific. The command above depends on brace expansion available in both the [https://www.gnu.org/software/bash/manual/html_node/Brace-Expansion.html bash] and [http://zsh.sourceforge.net/Doc/Release/Expansion.html#Brace-Expansion zsh] shells. When using a different [[shell]], {{ic|--exclude}} patterns should be repeated manually. Quoting the exclude patterns will avoid expansion by the [[shell]], which is necessary, for example, when backing up over [[SSH]]. Ending the excluded paths with {{ic|*}} ensures that the directories themselves are created if they do not already exist.<br />
<br />
{{Note|<br />
* If you plan on backing up your system somewhere other than {{ic|/mnt}} or {{ic|/media}}, do not forget to add it to the list of exclude patterns to avoid an infinite loop.<br />
* If there are any bind mounts in the system, they should be excluded as well so that the bind mounted contents is copied only once.<br />
* If you use a [[swap file]], make sure to exclude it as well.<br />
* Consider if you want to backup the {{ic|/home/}} folder. If it contains your data it might be considerably larger than the system. Otherwise consider excluding unimportant subdirectories such as {{ic|/home/*/.thumbnails/*}}, {{ic|/home/*/.cache/mozilla/*}}, {{ic|/home/*/.cache/chromium/*}}, and {{ic|/home/*/.local/share/Trash/*}}, depending on software installed on the system. If [[GVFS]] is installed, {{ic|/home/*/.gvfs}} must be excluded to prevent rsync errors.<br />
}}<br />
<br />
You may want to include additional [[rsync]] options, such as the following. See {{man|1|rsync}} for the full list.<br />
<br />
* If you use many hard links, consider adding the {{ic|-H}} option, which is turned off by default due to its memory expense; however, it should be no problem on most modern machines. Many hard links reside under the {{ic|/usr/}} directory.<br />
* You may want to add rsync's {{ic|--delete}} option if you are running this multiple times to the same backup folder. In this case make sure that the source path does not end with {{ic|/*}}, or this option will only have effect on the files inside the subdirectories of the source directory, but it will have no effect on the files residing directly inside the source directory.<br />
* If you use any sparse files, such as virtual disks, [[Docker]] images and similar, you should add the {{ic|-S}} option.<br />
* The {{ic|--numeric-ids}} option will disable mapping of user and group names; instead, numeric group and user IDs will be transfered. This is useful when backing up over [[SSH]] or when using a live system to backup different system disk.<br />
* Choosing {{ic|1=--info=progress2}} option instead of {{ic|-v}} will show the overall progress info and transfer speed instead of the list of files being transferred.<br />
<br />
=== Restore a backup ===<br />
<br />
If you wish to restore a backup, use the same rsync command that was executed but with the source and destination reversed.<br />
<br />
== File system cloning ==<br />
<br />
rsync provides a way to do a copy of all data in a file system while preserving as much information as possible, including the file system metadata. It is a procedure of data cloning on a file system level where source and destination file systems don't need to be of the same type. It can be used for backing up, file system migration or data recovery.<br />
<br />
rsync's ''archive'' mode comes close to being fit for the job, but it doesn't back up the special file system metadata such as access control lists, extended attributes or sparse file properties. For successful cloning at the file system level, some additional options need to be provided:<br />
<br />
rsync -qaHAXS SOURCE_DIR DESTINATION_DIR<br />
<br />
And their meaning is (from the manpage):<br />
<br />
-H, --hard-links preserve hard links<br />
-A, --acls preserve ACLs (implies -p)<br />
-X, --xattrs preserve extended attributes<br />
-S, --sparse handle sparse files efficiently<br />
<br />
Produced copy can be simply reread and checked (for example after a data recovery attempt) at the file system level with {{ic|diff}}'s recursive option:<br />
<br />
diff -r SOURCE_DIR DESTINATION_DIR<br />
<br />
It is possible to do a successful file system migration by using rsync as described in this article and updating the [[fstab]] and [[bootloader]] as described in [[Migrate installation to new hardware]]. This essentially provides a way to convert any root file system to another one.<br />
<br />
== rsync daemon ==<br />
<br />
''rsync'' can be run as daemon on a server listening on port {{ic|873}}.<br />
<br />
Edit the template {{ic|/etc/rsyncd.conf}}, configure a share and [[start]] the {{ic|rsyncd.service}}.<br />
<br />
{{Note|As of {{Pkg|rsync}}-3.1.2-5 the systemd unit {{ic|rsyncd.service}} included in the package adds security feature {{ic|1=ProtectSystem=full}} ({{ic|1=ProtectHome=on}} has been undone in {{Pkg|rsync}}-3.1.2-8) under the {{ic|[Service]}} section. This makes the {{ic|/boot/}}, {{ic|/etc/}} and {{ic|/usr/}} directories read-only. If you need rsyncd write system directories you can [[edit]] the unit and set {{ic|1=ProtectSystem=off}} in the {{ic|[Service]}} section of the overriding snippet.}}<br />
<br />
Usage from client, e.g. list server content:<br />
<br />
$ rsync rsync://''server/share''<br />
<br />
transfer file from client to server: <br />
<br />
$ rsync ''local-file'' rsync://''server/share/''<br />
<br />
Consider iptables to open port {{ic|873}} and user authentication.<br />
<br />
{{Note|All transferred data including user authentication are not encrypted.}}<br />
<br />
== See also ==<br />
<br />
* More usage examples can be searched in the [https://bbs.archlinux.org/viewforum.php?id=27 Community Contributions] and [https://bbs.archlinux.org/viewforum.php?id=33 General Programming] forums<br />
* [http://www.pointsoftware.ch/en/howto-local-and-remote-snapshot-backup-using-rsync-with-hard-links/ Howto – local and remote snapshot backup using rsync with hard links] Includes file deduplication with hard-links, MD5 integrity signature, 'chattr' protection, filter rules, disk quota, retention policy with exponential distribution (backups rotation while saving more recent backups than older)<br />
* [https://stackoverflow.com/questions/5527068/how-do-you-use-an-identity-file-with-rsync Using SSH keys/identity files with rsync]</div>EasyToRememberhttps://wiki.archlinux.org/index.php?title=XFS&diff=503134XFS2017-12-18T21:24:44Z<p>EasyToRemember: Setting up quota for root file system.</p>
<hr />
<div>[[Category:File systems]]<br />
[[it:XFS]]<br />
[[ja:XFS]]<br />
[[ru:XFS]]<br />
{{Related articles start}}<br />
{{Related|File systems}}<br />
{{Related articles end}}<br />
<br />
XFS is a high-performance journaling file system created by Silicon Graphics, Inc. XFS is particularly proficient at parallel IO due to its allocation group based design. This enables extreme scalability of IO threads, filesystem bandwidth, file and filesystem size when spanning multiple storage devices.<br />
<br />
== Installation ==<br />
<br />
The tools to manage XFS partions are in the {{Pkg|xfsprogs}} package, which is included in the default base installation.<br />
<br />
== Data corruption ==<br />
<br />
If for whatever reason you experience data corruption, you will need to repair the filesystem manually.<br />
<br />
=== Repair XFS Filesystem ===<br />
<br />
First unmount the XFS filesystem.<br />
# umount /dev/sda3<br />
<br />
Once unmounted, run the {{man|8|xfs_repair}} tool.<br />
# xfs_repair -v /dev/sda3<br />
<br />
== Integrity ==<br />
<br />
xfsprogs 3.2.0 has introduced a new on-disk format (v5) that includes a metadata checksum scheme called [https://www.kernel.org/doc/Documentation/filesystems/xfs-self-describing-metadata.txt Self-Describing Metadata]. <br />
Based upon CRC32 it provides for example additional protection against metadata corruption during unexpected power losses. Checksum is enabled by default when using xfsprogs 3.2.3 or later. If you need read-write mountable xfs for older kernel, It can be easily disable using the {{ic|1=-m crc=0}} switch when calling {{man|8|mkfs.xfs}}.<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
The XFS v5 on-disk format is considered stable for production workloads starting Linux Kernel 3.15.<br />
<br />
{{Note|Unlike [[Btrfs]] and [[ZFS]], the CRC32 checksum only applies to the metadata and not actual data.}}<br />
<br />
== Performance ==<br />
<br />
For optimal speed, just create an XFS file system with:<br />
<br />
# mkfs.xfs /dev/''target_partition''<br />
<br />
Yep, so simple - since all of the [http://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E "boost knobs" are already "on" by default].<br />
<br />
{{Warning|Disabling barriers, disabling atime, and other performance enhancements make data corruption and failure much more likely.}}<br />
<br />
As per [http://xfs.org/index.php/XFS_FAQ#Q:_I_want_to_tune_my_XFS_filesystems_for_.3Csomething.3E XFS wiki], consider changing the default CFQ [[Improving performance#Tuning IO schedulers|I/O scheduler]] (for example to [[wikipedia:Deadline_scheduler|Deadline]], [[wikipedia:NOOP_scheduler|Noop]] or [[Linux-ck#How_to_enable_the_BFQ_I.2FO_Scheduler|BFQ]]) to enjoy all of the benefits of XFS, especially on [[SSD]]s.<br />
<br />
=== Stripe size and width ===<br />
<br />
If this filesystem will be on a striped RAID you can gain significant speed improvements by specifying the stripe size to the {{man|8|mkfs.xfs}} command.<br />
<br />
See [http://xfs.org/index.php/XFS_FAQ#Q:_How_to_calculate_the_correct_sunit.2Cswidth_values_for_optimal_performance How to calculate the correct sunit,swidth values for optimal performance]<br />
<br />
=== Disable barrier ===<br />
<br />
You can increase performance by disabling barrier usage for the filesystem by adding the ''nobarrier'' mount option to the {{ic|/etc/fstab}} file.<br />
<br />
=== Access time ===<br />
<br />
On some filesystems you can increase performance by adding the {{ic|noatime}} mount option to the {{ic|/etc/fstab}} file. For XFS filesystems the default atime behaviour is {{ic|relatime}}, which has almost no overhead compared to noatime but still maintains sane atime values. All Linux filesystems use this as the default now (since around 2.6.30), but XFS has used relatime-like behaviour since 2006, so no-one should really need to ever use noatime on XFS for performance reasons.<br />
<br />
Also, {{ic|noatime}} implies {{ic|nodiratime}}, so there is never a need to specify '''nodiratime''' when '''noatime''' is also specified.<br />
<br />
=== Defragmentation ===<br />
<br />
Although the extent-based nature of XFS and the delayed allocation strategy it uses significantly improves the file system's resistance to fragmentation problems, XFS provides a filesystem defragmentation utility (''xfs_fsr'', short for XFS filesystem reorganizer) that can defragment the files on a mounted and active XFS filesystem. It can be useful to view XFS fragmentation periodically.<br />
<br />
{{man|8|xfs_fsr}} improves the organization of mounted filesystems. The reorganization algorithm operates on one file at a time, compacting or otherwise improving the layout of the file extents (contiguous blocks of file data).<br />
<br />
==== Inspect fragmentation levels ====<br />
<br />
To see how much fragmentation your file system currently has:<br />
# xfs_db -c frag -r /dev/sda3<br />
<br />
==== Perform defragmentation ====<br />
<br />
To begin defragmentation, use the {{man|8|xfs_fsr}} command:<br />
# xfs_fsr /dev/sda3<br />
<br />
=== Free inode btree ===<br />
<br />
Starting Linux 3.16, XFS has added a btree that tracks free inodes. It is equivalent to the existing inode allocation btree with the exception that the free inode btree tracks inode chunks with at least one free inode. The purpose is to improve lookups for free inode clusters for inode allocation. It improves performance on aged filesystems i.e. months or years down the track when you have added and removed millions of files to/from the filesystem. Using this feature doesn't impact overall filesystem reliability level or recovery capabilities.<br />
<br />
This feature relies on the new v5 on-disk format that has been considered stable for production workloads starting Linux Kernel 3.15. It does not change existing on-disk structures, but adds a new one that must remain consistent with the inode allocation btree; for this reason older kernels will only be able to mount read-only filesystems with the free inode btree feature.<br />
<br />
The feature enabled by default when using xfsprogs 3.2.3 or later. If you need writable filesystem for older kernel, it can be disable with {{ic|1=finobt=0}} switch when formatting a XFS partition. You will need {{ic|1=crc=0}} together.<br />
# mkfs.xfs -m crc=0,finobt=0 /dev/''target_partition''<br />
or shortly ({{ic|finobt}} depends {{ic|crc}})<br />
# mkfs.xfs -m crc=0 /dev/''target_partition''<br />
<br />
== Root file system quota ==<br />
<br />
XFS quota mount options (''uquota'', ''gquota'', ''prjquota'', ...) fail during re-mount of the file system. To enable quota for root file system, the mount option must be passed to initramfs as a kernel parameter {{ic|rootflags}}. Subsequently, it should not be listed among mount options in {{ic|/etc/fstab}} for the root (/) filesystem.<br />
<br />
If [[GRUB]] is used as a boot loader, add e.g. ''prjquota'' to {{ic|/etc/default/grub}}:<br />
<br />
GRUB_CMDLINE_LINUX_DEFAULT="rootflags=prjquota"<br />
<br />
and regenerate the GRUB configuration file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
{{Note|There are some differences of XFS Quota compared to standard Linux [[Disk Quota]], this article http://inai.de/linux/adm_quota may be worth reading.}}<br />
<br />
== See also ==<br />
<br />
* [http://xfs.org/index.php/XFS_FAQ XFS FAQ]<br />
* [http://xfs.org/index.php/Improving_Metadata_Performance_By_Reducing_Journal_Overhead Improving Metadata Performance By Reducing Journal Overhead]<br />
* [[wikipedia:XFS|XFS Wikipedia Entry]]</div>EasyToRemember