https://wiki.archlinux.org/api.php?action=feedcontributions&user=Piratejon&feedformat=atomArchWiki - User contributions [en]2024-03-29T12:39:42ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=RAID&diff=518213RAID2018-04-21T21:01:13Z<p>Piratejon: link is no longer dead</p>
<hr />
<div>[[Category:Storage virtualization]]<br />
[[es:RAID]]<br />
[[it:RAID]]<br />
[[ja:RAID]]<br />
[[ru:RAID]]<br />
[[zh-hans:RAID]]<br />
{{Related articles start}}<br />
{{Related|Software RAID and LVM}}<br />
{{Related|LVM#RAID}}<br />
{{Related|Installing with Fake RAID}}<br />
{{Related|Convert a single drive system to RAID}}<br />
{{Related|ZFS}}<br />
{{Related|ZFS/Virtual disks}}<br />
{{Related|Swap#Striping}}<br />
{{Related|Btrfs#RAID}}<br />
{{Related articles end}}<br />
{{Style|Non-standard headers, other [[Help:Style]] issues}}<br />
<br />
Redundant Array of Independent Disks ([[Wikipedia:RAID|RAID]]) is a storage technology that combines multiple disk drive components (typically disk drives or partitions thereof) into a logical unit. Depending on the RAID implementation, this logical unit can be a file system or an additional transparent layer that can hold several partitions. Data is distributed across the drives in one of several ways called [[#RAID levels]], depending on the level of redundancy and performance required. The RAID level chosen can thus prevent data loss in the event of a hard disk failure, increase performance or be a combination of both.<br />
<br />
This article explains how to create/manage a software RAID array using mdadm.<br />
<br />
{{Warning|Be sure [[Backup programs|to back up]] all data before proceeding.}}<br />
<br />
== RAID levels ==<br />
<br />
Despite redundancy implied by most RAID levels, RAID does not guarantee that data is safe. A RAID will not protect data if there is a fire, the computer is stolen or multiple hard drives fail at once. Furthermore, installing a system with RAID is a complex process that may destroy data.<br />
<br />
=== Standard RAID levels ===<br />
<br />
There are many different [[Wikipedia:Standard RAID levels|levels of RAID]], please find hereafter the most commonly used ones.<br />
<br />
; [[Wikipedia:Standard RAID levels#RAID 0|RAID 0]]<br />
: Uses striping to combine disks. Even though it ''does not provide redundancy'', it is still considered RAID. It does, however, ''provide a big speed benefit''. If the speed increase is worth the possibility of data loss (for [[swap]] partition for example), choose this RAID level. On a server, RAID 1 and RAID 5 arrays are more appropriate. The size of a RAID 0 array block device is the size of the smallest component partition times the number of component partitions.<br />
<br />
; [[Wikipedia:Standard RAID levels#RAID 1|RAID 1]]<br />
: The most straightforward RAID level: straight mirroring. As with other RAID levels, it only makes sense if the partitions are on different physical disk drives. If one of those drives fails, the block device provided by the RAID array will continue to function as normal. The example will be using RAID 1 for everything except [[swap]] and temporary data. Please note that with a software implementation, the RAID 1 level is the only option for the boot partition, because bootloaders reading the boot partition do not understand RAID, but a RAID 1 component partition can be read as a normal partition. The size of a RAID 1 array block device is the size of the smallest component partition.<br />
<br />
; [[Wikipedia:Standard RAID levels#RAID 5|RAID 5]]<br />
: Requires 3 or more physical drives, and provides the redundancy of RAID 1 combined with the speed and size benefits of RAID 0. RAID 5 uses striping, like RAID 0, but also stores parity blocks ''distributed across each member disk''. In the event of a failed disk, these parity blocks are used to reconstruct the data on a replacement disk. RAID 5 can withstand the loss of one member disk.<br />
: {{Note|RAID 5 is a common choice due to its combination of speed and data redundancy. The caveat is that if one drive were to fail and another drive failed before that drive was replaced, all data will be lost. Furthermore, with modern disk sizes and expected unrecoverable read error (URE) rates on consumer disks, the rebuild of a 4TiB array is '''expected''' (i.e. higher than 50% chance) to have at least one URE. Because of this, RAID 5 is no longer advised by the storage industry.}}<br />
<br />
; [[Wikipedia:Standard RAID levels#RAID 6|RAID 6]]<br />
: Requires 4 or more physical drives, and provides the benefits of RAID 5 but with security against two drive failures. RAID 6 also uses striping, like RAID 5, but stores two distinct parity blocks ''distributed across each member disk''. In the event of a failed disk, these parity blocks are used to reconstruct the data on a replacement disk. RAID 6 can withstand the loss of two member disks. The robustness against unrecoverable read errors is somewhat better, because the array still has parity blocks when rebuilding from a single failed drive. However, given the overhead, RAID 6 is costly and in most settings RAID 10 in far2 layout (see below) provides better speed benefits and robustness, and is therefore preferred.<br />
<br />
=== Nested RAID levels ===<br />
<br />
; [[Wikipedia:Nested RAID levels#RAID 10 (RAID 1+0)|RAID 1+0]]<br />
: RAID1+0 is a nested RAID that combines two of the standard levels of RAID to gain performance and additional redundancy. It is commonly referred to as ''RAID10'', however, Linux MD RAID10 is slightly different from simple RAID layering, see below.<br />
<br />
; [[Wikipedia:Non-standard RAID levels#Linux MD RAID 10|RAID 10]]<br />
: RAID10 under Linux is built on the concepts of RAID1+0, however, it implements this as a single layer, with multiple possible layouts.<br />
: The ''near X'' layout on Y disks repeats each chunk X times on Y/2 stripes, but does not need X to divide Y evenly. The chunks are placed on almost the same location on each disk they are mirrored on, hence the name. It can work with any number of disks, starting at 2. Near 2 on 2 disks is equivalent to RAID1, near 2 on 4 disks to RAID1+0.<br />
: The ''far X'' layout on Y disks is designed to offer striped read performance on a mirrored array. It accomplishes this by dividing each disk in two sections, say front and back, and what is written to disk 1 front is mirrored in disk 2 back, and vice versa. This has the effect of being able to stripe sequential reads, which is where RAID0 and RAID5 get their performance from. The drawback is that sequential writing has a very slight performance penalty because of the distance the disk needs to seek to the other section of the disk to store the mirror. RAID10 in far 2 layout is, however, preferable to layered RAID1+0 '''and''' RAID5 whenever read speeds are of concern and availability / redundancy is crucial. However, it is still not a substitute for backups. See the wikipedia page for more information.<br />
<br />
=== RAID level comparison ===<br />
<br />
{| class="wikitable"<br />
! RAID level!!Data redundancy!!Physical drive utilization!!Read performance!!Write performance!!Min drives<br />
|-<br />
| '''0'''||{{No}}||100%||nX<br />
<br />
'''Best'''<br />
||nX<br />
<br />
'''Best'''<br />
||2<br />
|-<br />
| '''1'''||{{Yes}}||50%||Up to nX if multiple processes are reading, otherwise 1X<br />
||1X||2<br />
|-<br />
| '''5'''||{{Yes}}||67% - 94%||(n−1)X<br />
<br />
'''Superior'''<br />
||(n−1)X<br />
<br />
'''Superior'''<br />
||3<br />
|-<br />
| '''6'''||{{Yes}}||50% - 88%||(n−2)X||(n−2)X||4<br />
|-<br />
| '''10,far2'''||{{Yes}}||50%||nX<br />
'''Best;''' on par with RAID0 but redundant<br />
||(n/2)X||2<br />
|-<br />
| '''10,near2'''||{{Yes}}||50%||Up to nX if multiple processes are reading, otherwise 1X||(n/2)X||2<br />
|}<br />
<br />
<nowiki>*</nowiki> Where ''n'' is standing for the number of dedicated disks.<br />
<br />
== Implementation ==<br />
<br />
The RAID devices can be managed in different ways:<br />
<br />
; Software RAID<br />
: This is the easiest implementation as it does not rely on obscure proprietary firmware and software to be used. The array is managed by the operating system either by:<br />
:* by an abstraction layer (e.g. [[#Installation|mdadm]]); {{Note|This is the method we will use later in this guide.}}<br />
:* by a logical volume manager (e.g. [[LVM#RAID|LVM]]);<br />
:* by a component of a file system (e.g. [[ZFS]], [[Btrfs#RAID|Btrfs]]).<br />
<br />
; Hardware RAID<br />
: The array is directly managed by a dedicated hardware card installed in the PC to which the disks are directly connected. The RAID logic runs on an on-board processor independently of [[Wikipedia:Central processing unit|the host processor (CPU)]]. Although this solution is independent of any operating system, the latter requires a driver in order to function properly with the hardware RAID controller. The RAID array can either be configured via an option rom interface or, depending on the manufacturer, with a dedicated application when the OS has been installed. The configuration is transparent for the Linux kernel: it does not see the disks separately.<br />
<br />
; [[Fakeraid|FakeRAID]]<br />
: This type of RAID is properly called BIOS or Onboard RAID, but is falsely advertised as hardware RAID. The array is managed by pseudo-RAID controllers where the RAID logic is implemented in an option rom or in the firmware itself [http://www.win-raid.com/t19f13-Intel-EFI-RAID-quot-SataDriver-quot-BIOS-Modules.html with a EFI SataDriver] (in case of [[UEFI]]), but are not full hardware RAID controllers with ''all'' RAID features implemented. Therefore, this type of RAID is sometimes called FakeRAID. {{Pkg|dmraid}} from the [[official repositories]], will be used to deal with these controllers. Here are some examples of FakeRAID controllers: [[Wikipedia:Intel Rapid Storage Technology|Intel Rapid Storage]], JMicron JMB36x RAID ROM, AMD RAID, ASMedia 106x, and NVIDIA MediaShield.<br />
<br />
=== Which type of RAID do I have? ===<br />
<br />
Since software RAID is implemented by the user, the type of RAID is easily known to the user.<br />
<br />
However, discerning between FakeRAID and true hardware RAID can be more difficult. As stated, manufacturers often incorrectly distinguish these two types of RAID and false advertising is always possible. The best solution in this instance is to run the {{ic|lspci}} command and looking through the output to find the RAID controller. Then do a search to see what information can be located about the RAID controller. Hardware RAID controllers appear in this list, but FakeRAID implementations do not. Also, true hardware RAID controller are often rather expensive, so if someone customized the system, then it is very likely that choosing a hardware RAID setup made a very noticeable change in the computer's price.<br />
<br />
== Installation ==<br />
<br />
[[Install]] {{Pkg|mdadm}}. ''mdadm'' is used for administering pure software RAID using plain block devices: the underlying hardware does not provide any RAID logic, just a supply of disks. ''mdadm'' will work with any collection of block devices. Even if unusual. For example, one can thus make a RAID array from a collection of thumb drives.<br />
<br />
=== Prepare the devices ===<br />
<br />
{{Warning|These steps erase everything on a device, so type carefully!}}<br />
<br />
If the device is being reused or re-purposed from an existing array, erase any old RAID configuration information:<br />
<br />
# mdadm --misc --zero-superblock /dev/<drive><br />
<br />
or if a particular partition on a drive is to be deleted:<br />
<br />
# mdadm --misc --zero-superblock /dev/<partition><br />
<br />
{{Note|<br />
* Zapping a partition's superblock should not affect the other partitions on the disk.<br />
* Due to the nature of RAID functionality it is very difficult to [[securely wipe disk]]s fully on a running array. Consider whether it is useful to do so before creating it.<br />
}}<br />
<br />
=== Partition the devices ===<br />
<br />
It is highly recommended to partition the disks to be used in the array. Since most RAID users are selecting disk drives larger than 2 TiB, GPT is required and recommended. See [[Partitioning]] for the more information on partitioning and the available [[partitioning tools]].<br />
<br />
{{Note|It is also possible to create a RAID directly on the raw disks (without partitions), but not recommended because it can cause problems when swapping a failed disk.}}<br />
<br />
{{Tip|When replacing a failed disk of a RAID, the new disk has to be exactly the same size as the failed disk or bigger — otherwise the array recreation process will not work. Even hard drives of the same manufacturer and model can have small size differences. By leaving a little space at the end of the disk unallocated one can compensate for the size differences between drives, which makes choosing a replacement drive model easier. Therefore, it is good practice to leave about 100 MiB of unallocated space at the end of the disk.}}<br />
<br />
==== GUID Partition Table ====<br />
<br />
* After creating the partitions, their [[Wikipedia:GUID Partition Table#Partition type GUIDs|partition type GUIDs]] should be {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} (it can be assigned by selecting partition type {{ic|Linux RAID}} in ''fdisk'' or {{ic|FD00}} in ''gdisk'').<br />
* If a larger disk array is employed, consider assigning [[Persistent block device naming#by-label|fylesystem labels]] or [[Persistent block device naming#by-partlabel|partition labels]] to make it easier to identify an individual disk later.<br />
* Creating partitions that are of the same size on each of the devices is recommended.<br />
<br />
==== Master Boot Record ====<br />
<br />
For those creating partitions on HDDs with a MBR partition table, the [[Wikipedia:Partition type|partition types IDs]] available for use are:<br />
<br />
* {{ic|0xFD}} for raid autodetect arrays ({{ic|Linux raid autodetect}} in ''fdisk'')<br />
* {{ic|0xDA}} for non-fs data ({{ic|Non-FS data}} in ''fdisk'')<br />
<br />
See [https://raid.wiki.kernel.org/index.php/Partition_Types Linux Raid Wiki:Partition Types] for more information.<br />
<br />
=== Build the array ===<br />
<br />
Use {{ic|mdadm}} to build the array. See {{man|8|mdadm}} for supported options. Several examples are given below.<br />
<br />
{{Warning|Do not simply copy/paste the examples below; make sure you use substitute the correct options and drive letters.}}<br />
<br />
{{Note|<br />
* If this is a RAID1 array which is intended to boot from [[Syslinux]] a limitation in syslinux v4.07 requires the metadata value to be 1.0 rather than the default of 1.2.<br />
* When creating an array from [[Archiso|Arch installation medium]] use the option {{ic|1=--homehost=''myhostname''}} (or {{ic|1=--homehost=any}} to always have the same name regardless of the host) to set the [[hostname]], otherwise the hostname {{ic|archiso}} will be written in the array metadata.<br />
}}<br />
<br />
{{Tip|You can specify a custom raid device name using the option {{ic|1=--name=''myraidname''}} or by setting the raid device path to {{ic|/dev/md/''myraidname''}}. Udev will create symlinks to the raid arrays in {{ic|/dev/md/}} using that name. If {{ic|homehost}} matches the current [[hostname]] (or if homehost is set to {{ic|any}}) the link will be {{ic|/dev/md/''name''}}, if the hostname does not match the link be {{ic|/dev/md/''homehost'':''name''}}.}}<br />
<br />
The following example shows building a 2-device RAID1 array:<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.2 --raid-devices=2 /dev/md/myraid1array /dev/sdb1 /dev/sdc1<br />
<br />
The following example shows building a RAID5 array with 4 active devices and 1 spare device:<br />
<br />
# mdadm --create --verbose --level=5 --metadata=1.2 --chunk=256 --raid-devices=4 /dev/md/myraid5array /dev/sdb1 /dev/sdc1 /dev/sdd1 /dev/sde1 --spare-devices=1 /dev/sdf1<br />
<br />
{{Tip|{{ic|--chunk}} is used to change the chunk size from the default value. See [http://www.zdnet.com/article/chunks-the-hidden-key-to-raid-performance/ Chunks: the hidden key to RAID performance] for more on chunk size optimisation.}}<br />
<br />
The following example shows building a RAID10,far2 array with 2 devices:<br />
<br />
# mdadm --create --verbose --level=10 --metadata=1.2 --chunk=512 --raid-devices=2 --layout=f2 /dev/md/myraid10array /dev/sdb1 /dev/sdc1<br />
<br />
The array is created under the virtual device {{ic|/dev/mdX}}, assembled and ready to use (in degraded mode). One can directly start using it while mdadm resyncs the array in the background. It can take a long time to restore parity. Check the progress with:<br />
<br />
$ cat /proc/mdstat<br />
<br />
=== Update configuration file ===<br />
<br />
By default, most of {{ic|mdadm.conf}} is commented out, and it contains just the following:<br />
<br />
{{hc|/etc/mdadm.conf|<br />
...<br />
DEVICE partitions<br />
...<br />
}}<br />
<br />
This directive tells mdadm to examine the devices referenced by {{ic|/proc/partitions}} and assemble as many arrays as possible. This is fine if you really do want to start all available arrays and are confident that no unexpected superblocks will be found (such as after installing a new storage device). A more precise approach is to explicitly add the arrays to {{ic|/etc/mdadm.conf}}:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
This results in something like the following:<br />
<br />
{{hc|/etc/mdadm.conf|2=<br />
...<br />
DEVICE partitions<br />
...<br />
ARRAY /dev/md/myraid1array metadata=1.2 name=pine:myraid1array UUID=27664f0d:111e493d:4d810213:9f291abe<br />
}}<br />
<br />
This also causes mdadm to examine the devices referenced by {{ic|/proc/partitions}}. However, only devices that have superblocks with a UUID of {{ic|27664…}} are assembled in to active arrays.<br />
<br />
See {{man|5|mdadm.conf}} for more information.<br />
<br />
=== Assemble the array ===<br />
<br />
Once the configuration file has been updated the array can be assembled using mdadm:<br />
<br />
# mdadm --assemble --scan<br />
<br />
=== Format the RAID filesystem ===<br />
<br />
The array can now be formatted with a [[file system]] like any other partition, just keep in mind that:<br />
<br />
* Due to the large volume size not all filesystems are suited (see: [[Wikipedia:Comparison of file systems#Limits]]).<br />
* The filesystem should support growing and shrinking while online (see: [[Wikipedia:Comparison of file systems#Features]]).<br />
* One should calculate the correct stride and stripe-width for optimal performance.<br />
<br />
==== Calculating the stride and stripe width ====<br />
<br />
Two parameters are required to optimise the filesystem structure to fit optimally within the underlying RAID structure: the ''stride'' and ''stripe width''. These are derived from the RAID ''chunk size'', the filesystem ''block size'', and the ''number of "data disks"''.<br />
<br />
The chunk size is a property of the RAID array, decided at the time of its creation. {{ic|mdadm}}'s current default is 512 KiB. It can be found with {{ic|mdadm}}:<br />
<br />
# mdadm --detail /dev/mdX | grep 'Chunk Size'<br />
<br />
The block size is a property of the filesystem, decided at ''its'' creation. The default for many filesystems, including ext4, is 4 KiB. See {{ic|/etc/mke2fs.conf}} for details on ext4.<br />
<br />
The number of "data disks" is the minimum number of devices in the array required to completely rebuild it without data loss. For example, this is N for a raid0 array of N devices and N-1 for raid5.<br />
<br />
Once you have these three quantities, the stride and the stripe width can be calculated using the following formulas:<br />
<br />
stride = chunk size / block size<br />
stripe width = number of data disks * stride<br />
<br />
===== Example 1. RAID0 =====<br />
<br />
Example formatting to ext4 with the correct stripe width and stride:<br />
<br />
* Hypothetical RAID0 array is composed of 2 physical disks.<br />
* Chunk size is 64 KiB.<br />
* Block size is 4 KiB.<br />
<br />
stride = chunk size / block size. In this example, the math is 64/4 so the stride = 16.<br />
<br />
stripe width = # of physical '''data''' disks * stride. In this example, the math is 2*16 so the stripe width = 32.<br />
<br />
# mkfs.ext4 -v -L myarray -m 0.5 -b 4096 -E stride=16,stripe-width=32 /dev/md0<br />
<br />
===== Example 2. RAID5 =====<br />
<br />
Example formatting to ext4 with the correct stripe width and stride:<br />
<br />
* Hypothetical RAID5 array is composed of 4 physical disks; 3 data discs and 1 parity disc.<br />
* Chunk size is 512 KiB.<br />
* Block size is 4 KiB.<br />
<br />
stride = chunk size / block size. In this example, the math is 512/4 so the stride = 128.<br />
<br />
stripe width = # of physical '''data''' disks * stride. In this example, the math is 3*128 so the stripe width = 384.<br />
<br />
# mkfs.ext4 -v -L myarray -m 0.01 -b 4096 -E stride=128,stripe-width=384 /dev/md0<br />
<br />
For more on stride and stripe width, see: [http://wiki.centos.org/HowTos/Disk_Optimization RAID Math].<br />
<br />
===== Example 3. RAID10,far2 =====<br />
<br />
Example formatting to ext4 with the correct stripe width and stride:<br />
<br />
* Hypothetical RAID10 array is composed of 2 physical disks. Because of the properties of RAID10 in far2 layout, both count as data disks.<br />
* Chunk size is 512 KiB.<br />
<br />
{{hc|# mdadm --detail /dev/md0 {{!}} grep 'Chunk Size'|<br />
Chunk Size : 512K<br />
}}<br />
<br />
* Block size is 4 KiB.<br />
<br />
stride = chunk size / block size.<br />
In this example, the math is 512/4 so the stride = 128.<br />
<br />
stripe width = # of physical '''data''' disks * stride.<br />
In this example, the math is 2*128 so the stripe width = 256.<br />
<br />
# mkfs.ext4 -v -L myarray -m 0.01 -b 4096 -E stride=128,stripe-width=256 /dev/md0<br />
<br />
== Mounting from a Live CD ==<br />
<br />
Users wanting to mount the RAID partition from a Live CD, use:<br />
<br />
# mdadm --assemble /dev/<disk1> /dev/<disk2> /dev/<disk3> /dev/<disk4><br />
<br />
If your RAID 1 that is missing a disk array was wrongly auto-detected as RAID 1 (as per {{ic|mdadm --detail /dev/md<number>}}) and reported as inactive (as per {{ic|cat /proc/mdstat}}), stop the array first:<br />
<br />
# mdadm --stop /dev/md<number><br />
<br />
== Installing Arch Linux on RAID ==<br />
<br />
{{Note|The following section is applicable only if the root filesystem resides on the array. Users may skip this section if the array holds a data partition(s).}}<br />
<br />
You should create the RAID array between the [[Partitioning]] and [[File systems#Create a file system|formatting]] steps of the Installation Procedure. Instead of directly formatting a partition to be your root file system, it will be created on a RAID array.<br />
Follow the section [[#Installation]] to create the RAID array. Then continue with the installation procedure until the pacstrap step is completed.<br />
When using [[Unified Extensible Firmware Interface|UEFI boot]], also read [[EFI System Partition#ESP on RAID]].<br />
<br />
=== Update configuration file ===<br />
<br />
{{Note|This should be done outside of the chroot, hence the prefix {{ic|/mnt}} to the filepath.}}<br />
<br />
After the base system is installed the default configuration file, {{ic|mdadm.conf}}, must be updated like so:<br />
<br />
# mdadm --detail --scan >> /mnt/etc/mdadm.conf<br />
<br />
Always check the {{ic|mdadm.conf}} configuration file using a text editor after running this command to ensure that its contents look reasonable.<br />
<br />
{{Note|To prevent failure of {{ic|mdmonitor.service}} at boot (enabled by default), you will need to uncomment {{ic|MAILADDR}} and provide an e-mail address and/or application to handle notification of problems with your array at the bottom of {{ic|mdadm.conf}}. See [[#Mailing on events]].}}<br />
<br />
Continue with the installation procedure until you reach the step [[Installation guide#Initramfs]], then follow the next section.<br />
<br />
=== Configure mkinitcpio ===<br />
<br />
{{Note|This should be done whilst chrooted.}}<br />
<br />
Add {{ic|mdadm_udev}} to the [[mkinitcpio#HOOKS|HOOKS]] section of the {{ic|mkinitcpio.conf}} to add support for mdadm into the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
HOOKS=(base udev autodetect keyboard modconf block '''mdadm_udev''' filesystems fsck)<br />
...<br />
}}<br />
<br />
If you use the {{ic|mdadm_udev}} hook with a FakeRAID array, it is recommended to include ''mdmon'' in the [[mkinitcpio#BINARIES and FILES|BINARIES]] array:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
...<br />
BINARIES=('''mdmon''')<br />
...<br />
}}<br />
<br />
Then [[Regenerate the initramfs]].<br />
<br />
See also [[mkinitcpio#Using RAID]].<br />
<br />
=== Configure the boot loader ===<br />
<br />
Point the {{ic|root}} parameter to the mapped device. E.g.:<br />
<br />
root=/dev/md/''homehost'':''myraidarray''<br />
<br />
If booting from a software raid partition fails using the kernel device node method above, an alternative way is to use one of the methods from [[Persistent block device naming]], for example:<br />
<br />
root=LABEL=Root_Label<br />
<br />
See also [[GRUB#RAID]].<br />
<br />
== RAID Maintenance ==<br />
<br />
=== Scrubbing ===<br />
<br />
It is good practice to regularly run data [[wikipedia:Data_scrubbing|scrubbing]] to check for and fix errors. Depending on the size/configuration of the array, a scrub may take multiple hours to complete.<br />
<br />
To initiate a data scrub:<br />
<br />
# echo check > /sys/block/md0/md/sync_action<br />
<br />
The check operation scans the drives for bad sectors and automatically repairs them. If it finds good sectors that contain bad data (the data in a sector does not agree with what the data from another disk indicates that it should be, for example the parity block + the other data blocks would cause us to think that this data block is incorrect), then no action is taken, but the event is logged (see below). This "do nothing" allows admins to inspect the data in the sector and the data that would be produced by rebuilding the sectors from redundant information and pick the correct data to keep.<br />
<br />
As with many tasks/items relating to mdadm, the status of the scrub can be queried by reading {{ic|/proc/mdstat}}.<br />
<br />
Example:<br />
<br />
{{hc|$ cat /proc/mdstat|<nowiki><br />
Personalities : [raid6] [raid5] [raid4] [raid1]<br />
md0 : active raid1 sdb1[0] sdc1[1]<br />
3906778112 blocks super 1.2 [2/2] [UU]<br />
[>....................] check = 4.0% (158288320/3906778112) finish=386.5min speed=161604K/sec<br />
bitmap: 0/30 pages [0KB], 65536KB chunk<br />
</nowiki>}}<br />
<br />
To stop a currently running data scrub safely:<br />
<br />
# echo idle > /sys/block/md0/md/sync_action<br />
<br />
{{Note|If the system is rebooted after a partial scrub has been suspended, the scrub will start over.}}<br />
<br />
When the scrub is complete, admins may check how many blocks (if any) have been flagged as bad:<br />
<br />
# cat /sys/block/md0/md/mismatch_cnt<br />
<br />
==== General notes on scrubbing ====<br />
<br />
{{Note|Users may alternatively echo '''repair''' to {{ic|/sys/block/md0/md/sync_action}} but this is ill-advised since if a mismatch in the data is encountered, it would be automatically updated to be consistent. The danger is that we really do not know whether it is the parity or the data block that is correct (or which data block in case of RAID1). It is luck-of-the-draw whether or not the operation gets the right data instead of the bad data.}}<br />
<br />
It is a good idea to set up a cron job as root to schedule a periodic scrub. See {{AUR|raid-check}} which can assist with this. To perform a periodic scrub using systemd timers instead of cron, See {{AUR|raid-check-systemd}} which contains the same script along with associated systemd timer unit files.<br />
<br />
{{Note|For typical platter drives, scrubbing can take approximately '''six seconds per gigabyte''' (that is one hour forty-five minutes per terabyte) so plan the start of your cron job or timer appropriately.}}<br />
<br />
==== RAID1 and RAID10 notes on scrubbing ====<br />
<br />
Due to the fact that RAID1 and RAID10 writes in the kernel are unbuffered, an array can have non-0 mismatch counts even when the array is healthy. These non-0 counts will only exist in transient data areas where they do not pose a problem. However, we cannot tell the difference between a non-0 count that is just in transient data or a non-0 count that signifies a real problem. This fact is a source of false positives for RAID1 and RAID10 arrays. It is however still recommended to scrub regularly in order to catch and correct any bad sectors that might be present in the devices.<br />
<br />
=== Removing devices from an array ===<br />
<br />
One can remove a device from the array after marking it as faulty:<br />
<br />
# mdadm --fail /dev/md0 /dev/sdxx<br />
<br />
Now remove it from the array:<br />
<br />
# mdadm --remove /dev/md0 /dev/sdxx<br />
<br />
Remove device permanently (for example, to use it individually from now on):<br />
Issue the two commands described above then:<br />
<br />
# mdadm --zero-superblock /dev/sdxx<br />
<br />
{{Warning|<br />
* Do not issue this command on linear or RAID0 arrays or data loss will occur!<br />
* Reusing the removed disk without zeroing the superblock will cause loss of all data on the next boot. (After mdadm will try to use it as the part of the raid array).<br />
}}<br />
<br />
Stop using an array:<br />
<br />
# Umount target array<br />
# Stop the array with: {{ic|mdadm --stop /dev/md0}}<br />
# Repeat the three command described in the beginning of this section on each device.<br />
# Remove the corresponding line from {{ic|/etc/mdadm.conf}}.<br />
<br />
=== Adding a new device to an array ===<br />
<br />
Adding new devices with mdadm can be done on a running system with the devices mounted.<br />
Partition the new device using the same layout as one of those already in the arrays as discussed above.<br />
<br />
Assemble the RAID array if it is not already assembled:<br />
<br />
# mdadm --assemble /dev/md0 /dev/sda1 /dev/sdb1<br />
<br />
Add the new device the array:<br />
<br />
# mdadm --add /dev/md0 /dev/sdc1<br />
<br />
This should not take long for mdadm to do. Again, check the progress with:<br />
<br />
# cat /proc/mdstat<br />
<br />
Check that the device has been added with the command:<br />
<br />
# mdadm --misc --detail /dev/md0<br />
<br />
{{Note|For RAID0 arrays you may get the following error message:<br />
<br />
mdadm: add new device failed for /dev/sdc1 as 2: Invalid argument<br />
<br />
This is because the above commands will add the new disk as a "spare" but RAID0 does not have spares. If you want to add a device to a RAID0 array, you need to "grow" and "add" in the same command. This is demonstrated below:<br />
<br />
# mdadm --grow /dev/md0 --raid-devices<nowiki>=</nowiki>3 --add /dev/sdc1<br />
<br />
}}<br />
<br />
=== Increasing size of a RAID volume ===<br />
<br />
If larger disks are installed in a RAID array or partition size has been increased, it may be desirable to increase the size of the RAID volume to fill the larger available space. This process may be begun by first following the above sections pertaining to replacing disks. Once the RAID volume has been rebuilt onto the larger disks it must be "grown" to fill the space.<br />
<br />
# mdadm --grow /dev/md0 --size=max<br />
<br />
Next, partitions present on the RAID volume {{ic|/dev/md0}} may need to be resized. See [[Partitioning]] for details. Finally, the filesystem on the above mentioned partition will need to be resized. If partitioning was performed with {{ic|gparted}} this will be done automatically. If other tools were used, unmount and then resize the filesystem manually.<br />
<br />
# umount /storage<br />
# fsck.ext4 -f /dev/md0p1<br />
# resize2fs /dev/md0p1<br />
<br />
=== Change sync speed limits ===<br />
<br />
Syncing can take a while. If the machine is not needed for other tasks the speed limit can be increased.<br />
<br />
{{hc|# cat /proc/mdstat|<nowiki><br />
Personalities : [raid1]<br />
md0 : active raid1 sda3[2] sdb3[1]<br />
155042219 blocks super 1.2 [2/1] [_U]<br />
[>....................] recovery = 0.0% (77696/155042219) finish=265.8min speed=9712K/sec<br />
<br />
unused devices: <none><br />
</nowiki>}}<br />
<br />
Check the current speed limit.<br />
<br />
{{hc|# cat /proc/sys/dev/raid/speed_limit_min|<br />
1000<br />
}}<br />
<br />
{{hc|# cat /proc/sys/dev/raid/speed_limit_max|<br />
200000<br />
}}<br />
<br />
Increase the limits.<br />
<br />
# echo 400000 >/proc/sys/dev/raid/speed_limit_min<br />
# echo 400000 >/proc/sys/dev/raid/speed_limit_max<br />
<br />
Then check out the syncing speed and estimated finish time.<br />
<br />
{{hc|# cat /proc/mdstat|<nowiki><br />
Personalities : [raid1]<br />
md0 : active raid1 sda3[2] sdb3[1]<br />
155042219 blocks super 1.2 [2/1] [_U]<br />
[>....................] recovery = 1.3% (2136640/155042219) finish=158.2min speed=16102K/sec<br />
<br />
unused devices: <none><br />
</nowiki>}}<br />
<br />
See also [[sysctl#MDADM]].<br />
<br />
== Monitoring ==<br />
<br />
A simple one-liner that prints out the status of the RAID devices:<br />
<br />
{{hc|# awk '/^md/ {printf "%s: ", $1}; /blocks/ {print $NF}' </proc/mdstat<br />
|md1: [UU]<br />
md0: [UU]<br />
}}<br />
<br />
=== Watch mdstat ===<br />
<br />
# watch -t 'cat /proc/mdstat'<br />
<br />
Or preferably using {{pkg|tmux}}<br />
<br />
# tmux split-window -l 12 "watch -t 'cat /proc/mdstat'"<br />
<br />
=== Track IO with iotop ===<br />
<br />
The {{pkg|iotop}} package displays the input/output stats for processes. Use this command to view the IO for raid threads.<br />
<br />
# iotop -a -p $(sed 's, , -p ,g' <<<`pgrep "_raid|_resync|jbd2"`)<br />
<br />
=== Track IO with iostat ===<br />
<br />
The ''iostat'' utility from {{Pkg|sysstat}} package displays the input/output statistics for devices and partitions.<br />
<br />
# iostat -dmy 1 /dev/md0<br />
# iostat -dmy 1 # all<br />
<br />
=== Mailing on events ===<br />
<br />
A smtp mail server (sendmail) or at least an email forwarder (ssmtp/msmtp) is required to accomplish this. Perhaps the most simplistic solution is to use {{AUR|dma}} which is very tiny (installs to 0.08 MiB) and requires no setup.<br />
<br />
Edit {{ic|/etc/mdadm.conf}} defining the email address to which notifications will be received.<br />
<br />
{{Note|If using dma as mentioned above, users may simply mail directly to the username on the localhost rather than to an external email address.}}<br />
<br />
To test the configuration:<br />
<br />
# mdadm --monitor --scan --oneshot --test<br />
<br />
mdadm includes {{ic|mdmonitor.service}} to perform the monitoring task, so at this point, you have nothing left to do. If you do not set a mail address in {{ic|/etc/mdadm.conf}}, that service will fail. If you do not want to receive mail on mdadm events, the failure can be ignored; if you do not want notifications and are sensitive about failure messages, you can [[mask]] the unit.<br />
<br />
==== Alternative method ====<br />
<br />
To avoid the installation of a smtp mail server or an email forwarder you can use the [[S-nail]] tool (do not forget to setup) already on your system.<br />
<br />
Create a file named {{ic|/etc/mdadm_warning.sh}}:<br />
<br />
{{hc|/etc/mdadm_warning.sh|2=<br />
#!/bin/bash<br />
event=$1<br />
device=$2<br />
<br />
echo " " | /usr/bin/mailx -s "$event on $device" '''destination@email.com'''<br />
}}<br />
<br />
And give it execution permissions {{ic|chmod +x /etc/mdadm_warning.sh}}<br />
<br />
Then add this to the mdadm.conf<br />
<br />
PROGRAM /etc/mdadm_warning.sh<br />
<br />
To test and enable use the same as in the previous method.<br />
<br />
== Troubleshooting ==<br />
<br />
If you are getting error when you reboot about "invalid raid superblock magic" and you have additional hard drives other than the ones you installed to, check that your hard drive order is correct. During installation, your RAID devices may be hdd, hde and hdf, but during boot they may be hda, hdb and hdc. Adjust your kernel line accordingly. This is what happened to me anyway.<br />
<br />
=== Error: "kernel: ataX.00: revalidation failed" ===<br />
<br />
If you suddenly (after reboot, changed BIOS settings) experience Error messages like:<br />
<br />
Feb 9 08:15:46 hostserver kernel: ata8.00: revalidation failed (errno=-5)<br />
<br />
Is does not necessarily mean that a drive is broken. You often find panic links on the web which go for the worst. In a word, No Panic. Maybe you just changed APIC or ACPI settings within your BIOS or Kernel parameters somehow. Change them back and you should be fine. Ordinarily, turning ACPI and/orACPI off should help.<br />
<br />
=== Start arrays read-only ===<br />
<br />
When an md array is started, the superblock will be written, and resync may begin. To start read-only set the kernel module {{ic|md_mod}} parameter {{ic|start_ro}}. When this is set, new arrays get an 'auto-ro' mode, which disables all internal io (superblock updates, resync, recovery) and is automatically switched to 'rw' when the first write request arrives.<br />
<br />
{{Note|The array can be set to true 'ro' mode using {{ic|mdadm --readonly}} before the first write request, or resync can be started without a write using {{ic|mdadm --readwrite}}.}}<br />
<br />
To set the parameter at boot, add {{ic|1=md_mod.start_ro=1}} to your kernel line.<br />
<br />
Or set it at module load time from {{ic|/etc/modprobe.d/}} file or from directly from {{ic|/sys/}}:<br />
<br />
# echo 1 > /sys/module/md_mod/parameters/start_ro<br />
<br />
=== Recovering from a broken or missing drive in the raid ===<br />
<br />
You might get the above mentioned error also when one of the drives breaks for whatever reason. In that case you will have to force the raid to still turn on even with one disk short. Type this (change where needed):<br />
<br />
# mdadm --manage /dev/md0 --run<br />
<br />
Now you should be able to mount it again with something like this (if you had it in fstab):<br />
<br />
# mount /dev/md0<br />
<br />
Now the raid should be working again and available to use, however with one disk short! So, to add that one disc partition it the way like described above in [[#Prepare the devices]]. Once that is done you can add the new disk to the raid by doing:<br />
<br />
# mdadm --manage --add /dev/md0 /dev/sdd1<br />
<br />
If you type:<br />
<br />
# cat /proc/mdstat<br />
<br />
you probably see that the raid is now active and rebuilding.<br />
<br />
You also might want to update your configuration (see: [[#Update configuration file]]).<br />
<br />
== Benchmarking ==<br />
<br />
There are several tools for benchmarking a RAID. The most notable improvement is the speed increase when multiple threads are reading from the same RAID volume.<br />
<br />
{{AUR|tiobench}} specifically benchmarks these performance improvements by measuring fully-threaded I/O on the disk.<br />
<br />
{{Pkg|bonnie++}} tests database type access to one or more files, and creation, reading, and deleting of small files which can simulate the usage of programs such as Squid, INN, or Maildir format e-mail. The enclosed [http://www.coker.com.au/bonnie++/zcav/ ZCAV] program tests the performance of different zones of a hard drive without writing any data to the disk.<br />
<br />
{{ic|hdparm}} should '''NOT''' be used to benchmark a RAID, because it provides very inconsistent results.<br />
<br />
== See also ==<br />
<br />
{{Out of date|A lot of old and dead links.}}<br />
<br />
* [http://www.gentoo.org/doc/en/articles/software-raid-p1.xml Software RAID in the new Linux 2.4 kernel, Part 1]{{Dead link|2018|03|10}} and [http://www.gentoo.org/doc/en/articles/software-raid-p2.xml Part 2]{{Dead link|2018|03|10}} in the Gentoo Linux Docs<br />
* [http://raid.wiki.kernel.org/index.php/Linux_Raid Linux RAID wiki entry] on The Linux Kernel Archives<br />
* [https://raid.wiki.kernel.org/index.php/Write-intent_bitmap How Bitmaps Work]<br />
* [http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Linux/6/html/Storage_Administration_Guide/ch-raid.html Chapter 15: Redundant Array of Independent Disks (RAID)] of Red Hat Enterprise Linux 6 Documentation<br />
* [http://tldp.org/FAQ/Linux-RAID-FAQ/x37.html Linux-RAID FAQ] on the Linux Documentation Project<br />
* [http://support.dell.com/support/topics/global.aspx/support/entvideos/raid?c=us&l=en&s=gen Dell.com Raid Tutorial]{{Dead link|2018|03|10}} - Interactive Walkthrough of Raid<br />
* [http://www.miracleas.com/BAARF/ BAARF]{{Dead link|2018|03|10}} including ''[http://www.miracleas.com/BAARF/RAID5_versus_RAID10.txt Why should I not use RAID 5?]''{{Dead link|2018|03|10}} by Art S. Kagel<br />
* [http://www.linux-mag.com/id/7924/ Introduction to RAID], [http://www.linux-mag.com/id/7931/ Nested-RAID: RAID-5 and RAID-6 Based Configurations], [http://www.linux-mag.com/id/7928/ Intro to Nested-RAID: RAID-01 and RAID-10], and [http://www.linux-mag.com/id/7932/ Nested-RAID: The Triple Lindy] in Linux Magazine<br />
* [http://www.cyberciti.biz/tips/linux-raid-increase-resync-rebuild-speed.html HowTo: Speed Up Linux Software Raid Building And Re-syncing]<br />
* [http://fomori.org/blog/?p=94 RAID5-Server to hold all your data]<br />
* [[Wikipedia:Non-RAID drive architectures]]<br />
<br />
'''mdadm'''<br />
* [http://anonscm.debian.org/gitweb/?p=pkg-mdadm/mdadm.git;a=blob_plain;f=debian/FAQ;hb=HEAD Debian mdadm FAQ]<br />
* [http://www.kernel.org/pub/linux/utils/raid/mdadm/ mdadm source code]<br />
* [http://www.linux-mag.com/id/7939/ Software RAID on Linux with mdadm] in Linux Magazine<br />
* [[Wikipedia:mdadm|Wikipedia - mdadm]]<br />
<br />
'''Forum threads'''<br />
* [http://forums.overclockers.com.au/showthread.php?t=865333 Raid Performance Improvements with bitmaps]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=125445 GRUB and GRUB2]<br />
* [https://bbs.archlinux.org/viewtopic.php?id=123698 Can't install grub2 on software RAID]<br />
* [http://forums.gentoo.org/viewtopic-t-888624-start-0.html Use RAID metadata 1.2 in boot and root partition]<br />
<br />
'''RAID with encryption'''<br />
* [http://www.shimari.com/dm-crypt-on-raid/ Linux/Fedora: Encrypt /home and swap over RAID with dm-crypt] by Justin Wells</div>Piratejonhttps://wiki.archlinux.org/index.php?title=Syslog-ng&diff=425444Syslog-ng2016-03-13T00:12:08Z<p>Piratejon: /* PostgreSQL Destination */ correct paths for postgres and syslog config files (9.5.1-2 and 3.6.3-2)</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Daemons and system services]]<br />
[[ja:Syslog-ng]]<br />
{{Related articles start}}<br />
{{Related|rsyslog}}<br />
{{Related articles end}}<br />
<br />
{{Note|After upgrading to systemd, syslog-ng is unnecessary for users who can be satisfied by journalctl and can be uninstalled for those.}}<br />
<br />
== Overview ==<br />
<br />
syslog-ng takes incoming log messages from defined '[[#Sources|sources]]' and forwards them to the appropriate [[#Destinations|destinations]], based on powerful [[#Creating Filters for Messages|filter]] directives. In a typical simple set-up, syslog-ng will read messages from three sources:<br />
<br />
# the default {{ic|/dev/log}} device, where most logs are sent<br />
# syslog-ng "internal" log messages<br />
# {{ic|/proc/kmsg}} kernel messages<br />
<br />
Sources are defined using the "source" directive. These incoming messages are then filtered according to defined filters ("filter" keyword), i.e. according to originating program or log level, and sent to the appropriate "destination". Destinations include log files (e.g. {{ic|/var/log/messages.log}}), printing messages on a console and remote servers. The pivotal function is [[#Log Paths|log]]. This function defines which filters should be applied to a certain source, and where the resulting messages should be sent to.<br />
<br />
[[Enable]] syslog-ng with the {{ic|syslog-ng.service}} service file. As of ''systemd'' 216, messages are no longer forwarded to syslog by default. Syslog-ng did not become journald aware until months later with the release of syslog-ng 3.6. This meant that if you were running systemd 216 or greater and syslog-ng you needed to set the option {{ic|1=ForwardToSyslog=yes}} in {{ic|/etc/systemd/journald.conf}} to actually use ''syslog-ng'' with ''journald''. <br />
<br />
If you use a current {{Pkg|syslog-ng}}, it is not necessary to change the option because [[syslog-ng]] pulls the messages from the journal. If you have set {{ic|1=ForwardToSyslog=yes}} you should revert it to {{ic|1=ForwardToSyslog=no}} in order to avoid the overhead associated with the socket and to avoid [https://github.com/balabit/syslog-ng/issues/314 needless error messages in the log]. If on the other hand you do not want to store your logs twice and turn ''journald'''s {{ic|1=Storage=none}}, you '''will''' need {{ic|1=ForwardToSyslog=yes}}, as ''syslog-ng'' tries to follow the 'journald' journal file.<br />
<br />
== Sources ==<br />
syslog-ng receives log messages from a source. To define a source you should follow the following syntax:<br />
source <identifier> { source-driver(params); source-driver(params); ... };<br />
<br />
You can look at the identifiers and source-drivers in the [http://www.balabit.com/support/documentation/ official manuals]. <br />
This will follow the manual to explain the configuration file above. The unix-stream() source-driver opens the given AF_UNIX<br />
[[wikipedia:Berkeley_sockets|socket]] and starts listening on it for messages. <br />
The internal() source-driver gets messages generated by syslog-ng.<br />
<br />
Therefore, the following means: {{ic|src}} gets messages from the {{ic|/dev/log}} socket and syslog-ng.<br />
source src { unix-stream("/dev/log"); internal(); };<br />
<br />
The kernel sends log messages to {{ic|/proc/kmsg}} and the file() driver reads log messages from files. Therefore, the following means:<br />
kernsrc gets messages from file {{ic|/proc/kmsg}}<br />
source kernsrc { file("/proc/kmsg"); };<br />
<br />
In the default configuration file after emerging syslog-ng, the source is defined as:<br />
source src { unix-stream("/dev/log"); internal(); pipe("/proc/kmsg"); };<br />
<br />
Reading messages by {{ic|pipe("/proc/kmsg")}} gives a better performance but because it opens its argument in read-write mode can be a security<br />
hazard as the [http://www.balabit.com/sites/default/files/documents/syslog-ng-v3.0-guide-admin-en.html/index.html-single.html#configuring_sources_pipe syslog-ng admin guide] states in section 3.3.3:<br />
<br />
"Pipe is very similar to the file() driver, but there are a few differences, for example pipe() opens its argument in read-write mode, therefore it is not recommended to be used on special files like {{ic|/proc/kmsg}}." (You can follow this discussion in [http://forums.gentoo.org/viewtopic-t-558161.html this post].)<br />
<br />
To open a port to read data from a remote server a source must be defined with this syntax:<br />
source s_net { udp(); };<br />
<br />
for UDP or<br />
source s_net { tcp(); };<br />
<br />
to receive log messages via TCP. Both listen on port 514.<br />
<br />
=== syslog-ng and systemd journal===<br />
Starting with syslog-ng version 3.6.1 the default {{ic|system()}} source on Linux systems using systemd uses journald as its standard {{ic|system()}} source.<br />
<br />
If you wish to use both the journald and syslog-ng files, ensure the following settings are in effect. For systemd-journald, in the {{ic|/etc/systemd/journald.conf}} file, {{ic|1=Storage=}} either set to {{ic|auto}} or unset (which defaults to auto) and {{ic|1=ForwardToSyslog=}} set to {{ic|no}} or unset (defaults to no). For {{ic|/etc/syslog-ng/syslog-ng.conf}}, you need the following {{ic|source}} stanza:<br />
<br />
{{bc|<nowiki><br />
source src {<br />
system();<br />
internal();<br />
};</nowiki>}}<br />
<br />
If, on the other hand, you wish ''not'' to retain the journald logs, but only syslog-ng's text logs, set {{ic|<nowiki>Storage=volatile</nowiki>}} and {{ic|1=ForwardToSyslog=yes}} in {{ic|/etc/systemd/journald.conf}}. This will store journald in ram. As of syslog-ng 3.6.3, syslog-ng is using journald as the system(); source so if you set {{ic|1=Storage=none}}, the systemd journal will drop all messages and '''not''' forward them to syslog-ng.<br />
<br />
After the change [[restart]] the {{ic|systemd-journald.service}} and {{ic|syslog-ng.service}} daemons.<br />
<br />
== Destinations ==<br />
In syslog-ng, log messages are sent to files. The syntax is very similar to sources:<br />
destination <identifier> {destination-driver(params); destination-driver(params); ... };<br />
<br />
You will be normally logging to a file, but you could log to a different destination-driver: pipe, Unix socket, TCP-UDP ports,<br />
terminals or to specific programs. Therefore, this means sending authlog messages to {{ic|/var/log/auth.log}}:<br />
destination authlog { file("/var/log/auth.log"); };<br />
<br />
If the user is logged in, {{ic|usertty()}} sends messages to the terminal of the specified user. If you want to send console messages<br />
to root's terminal if it is logged in:<br />
destination console { usertty("root"); };<br />
<br />
Messages can be sent to a pipe with {{ic|pipe()}}. The following sends xconsole messages to the pipe {{ic|/dev/xconsole}}.<br />
This needs some more configuration, so you could look at the sub-section xconsole below.<br />
destination xconsole { pipe("/dev/xconsole"); };<br />
<br />
To send messages on the network, use {{ic|udp()}}. The following will send your log data out to another server.<br />
destination remote_server { udp("10.0.0.2" port(514)); };<br />
<br />
== Creating Filters for Messages ==<br />
The syntax for the filter statement is:<br />
filter <identifier> { expression; };<br />
<br />
Functions can be used in the expression, such as the function {{ic|facility()}} which selects messages based on the facility codes. <br />
The Linux kernel has a few facilities you can use for logging. Each facility has a log-level; where debug is the most verbose,<br />
and panic only shows serious errors. You can find the facilities, log levels and priority names in {{ic|/usr/include/sys/syslog.h}}.<br />
To filter those messages coming from authorization, like <br />
''<nowiki>May 11 23:42:31 mimosinnet su(pam_unix)[18569]: session opened for user root by (uid=1000)</nowiki>'', use the following:<br />
filter f_auth { facility(auth); };<br />
<br />
The facility expression can use the boolean operators {{ic|and}}, {{ic|or}}, and {{ic|not}}, so the following filter<br />
selects those messages not coming from authorization, network news or mail:<br />
filter f_debug { not facility(auth, authpriv, news, mail); };<br />
<br />
The function {{ic|level()}} selects messages based on its priority level, so if you want to select informational levels:<br />
filter f_info { level(info); };<br />
<br />
Functions and boolean operators can be combined in more complex expressions. The following line filters messages with a priority level from<br />
informational to warning not coming from auth, authpriv, mail and news facilities:<br />
filter f_messages { level(info..warn) and not facility(auth, authpriv, mail, news); };<br />
<br />
Messages can also be selected by matching a regular expression in the message with the function {{ic|match("regex" value("TEMPLATE"))}}. For example:<br />
filter f_failed { match("failed" value("MESSAGE")); };<br />
<br />
here is a list of templates : <br />
"AMPM", "BSDTAG", "DATE, C_DATE, R_DATE, S_DATE", "DAY, C_DAY, R_DAY, S_DAY", "FACILITY", "FACILITY_NUM", "FULLDATE, C_FULLDATE, R_FULLDATE, S_FULLDATE", "FULLHOST", "FULLHOST_FROM", "HOUR, C_HOUR, R_HOUR, S_HOUR", "HOUR12, C_HOUR12, R_HOUR12, S_HOUR12", "HOST", "HOST_FROM", "ISODATE, C_ISODATE, R_ISODATE, S_ISODATE", "LEVEL_NUM", "LOGHOST", "MIN, C_MIN, R_MIN, S_MIN", "MONTH, C_MONTH, R_MONTH, S_MONTH", "MONTH_ABBREV, C_MONTH_ABBREV, R_MONTH_ABBREV, S_MONTH_ABBREV", "MONTH_NAME, C_MONTH_NAME, R_MONTH_NAME, S_MONTH_NAME", "MONTH_WEEK, C_MONTH_WEEK, R_MONTH_WEEK, S_MONTH_WEEK", "MSEC, C_MSEC, R_MSEC, S_MSEC", "MSG or MESSAGE", "MSGHDR", "MSGID", "MSGONLY", "PID", "PRI", "PRIORITY or LEVEL", "PROGRAM", "SDATA, .SDATA.SDID.SDNAME", "SEC, C_SEC, R_SEC, S_SEC", "SOURCEIP", "SEQNUM", "STAMP, R_STAMP, S_STAMP", "SYSUPTIME", "TAG", "TAGS", "TZ, C_TZ, R_TZ, S_TZ", "TZOFFSET, C_TZOFFSET, R_TZOFFSET, S_TZOFFSET", "UNIXTIME, C_UNIXTIME, R_UNIXTIME, S_UNIXTIME", "USEC, C_USEC, R_USEC, S_USEC", "YEAR, C_YEAR, R_YEAR, S_YEAR", "WEEK, C_WEEK, R_WEEK, S_WEEK", "WEEK_ABBREV, C_WEEK_ABBREV, R_WEEK_ABBREV, S_WEEK_ABBREV", "WEEK_DAY, C_WEEK_DAY, R_WEEK_DAY, S_WEEK_DAY", "WEEKDAY, C_WEEKDAY, R_WEEKDAY, S_WEEKDAY", "WEEK_DAY_NAME, C_WEEK_DAY_NAME, R_WEEK_DAY_NAME, S_WEEK_DAY_NAME".<br />
<br />
To filter messages received from a particular remote host, the {{ic|host()}} function must be used:<br />
filter f_host { host( "192.168.1.1" ); };<br />
<br />
== Log Paths ==<br />
syslog-ng connects sources, filters and destinations with log statements. The syntax is:<br />
log {source(s1); source(s2); ...<br />
filter(f1); filter(f2); ...<br />
destination(d1); destination(d2); ...<br />
flags(flag1[, flag2...]); };<br />
<br />
The following for example sends messages from {{ic|src}} source to {{ic|mailinfo}} destination filtered by {{ic|f_info}} filter.<br />
log { source(src); filter(f_mail); filter(f_info); destination(mailinfo); };<br />
<br />
== Tips and Tricks ==<br />
After understanding the logic behind syslog-ng, many possible and complex configuration are possible. Here there are some examples.<br />
<br />
=== Have syslog-ng reload the configuration file ===<br />
<br />
You can make syslog-ng re-evaluate the configuration file. You can do so manually by sending a {{ic|SIGHUP}} to the process, or call the reload function with systemctl:<br />
# systemctl reload syslog-ng<br />
<br />
=== Failover Logging to Remote Host ===<br />
This setup shows how to send the default unencrypted syslog packets across both TCP and UDP protocols, using the standard port (514) and an alternate port. This is sending the same output to the same machine 4 different ways to try and make sure packets make it. Mostly useful if you are debugging a remote server that fails to reboot. The different ports and protocols are to make it past any firewall filters or other network problems. Also useful for port-forwarding and using tunnels. Something like this setup is ideal to tunnel across an ssh connection that the prone-to-failover host initiates through a reverse connection.<br />
<br />
{{bc|<nowiki>#sending to a remote syslog server on TCP and UDP ports (not encrypted)<br />
destination askapache_failover_loghost {<br />
tcp("208.86.158.195" port(25214));<br />
udp("208.86.158.195" port(25214));<br />
udp("mysyslog1.dyndns.org" port(514));<br />
};<br />
log { <br />
source(src); <br />
destination(askapache_failover_loghost);<br />
};</nowiki><br />
}}<br />
<br />
And then on the loghost receiving these logs:<br />
<br />
{{bc|<nowiki>#a USB redirected console for flexible viewing<br />
destination debugging_console {<br />
file("/dev/ttyU1");<br />
};<br />
<br />
# listens on IP addresses and ports, sets the incoming settings<br />
source prone_to_failover_host {<br />
tcp(ip(208.86.158.195),port(25214));<br />
udp(ip(208.86.158.195) port(25214));<br />
<br />
udp(default-facility(syslog) default-priority(emerg));<br />
tcp(default-facility(syslog) default-priority(emerg));<br />
}<br />
<br />
# log it<br />
log {<br />
source(prone_to_failover_host); <br />
destination(debugging_console);<br />
};</nowiki><br />
}}<br />
<br />
=== Move log to another file ===<br />
In order to move some log from {{ic|/var/log/messages}} to another file:<br />
<br />
{{bc|<nowiki>#sshd configuration<br />
destination ssh { file("/var/log/ssh.log"); };<br />
filter f_ssh { program("sshd"); };<br />
log { source(src); filter(f_ssh); destination(ssh); };</nowiki><br />
}}<br />
<br />
=== Configuring as a loghost ===<br />
Configuring your system to be a loghost is quite simple. Drop the following into your configuration, and create the needed directory.<br />
With this simple configuration, log filenames will be based on the [[Wikipedia:FQDN|FQDN]] of the remote host,<br />
and located in {{ic|/var/log/remote/}}. After creating the remote directory, reload your syslog-ng configuration.<br />
<br />
{{bc|<nowiki>source net { udp(); };<br />
destination remote { file("/var/log/remote/${FULLHOST}-log"); };<br />
log { source(net); destination(remote); };</nowiki><br />
}}<br />
<br />
=== Improve Performance ===<br />
syslog-ng's performance can be improved in different ways:<br />
<br />
==== Write every so often ====<br />
It seems that the old {{ic|sync(X)}} '''option''' is called {{ic|flush_lines(X)}} now, where the writing to the file is buffered for {{ic|X}} lines. Default is 0 (no buffering).<br />
<br />
==== Avoid redundant processing and disk space ====<br />
A single log message can be sent to different log files several times. For example, in the initial configuration file, we have the following definitions:<br />
<br />
{{bc|<nowiki>destination cron { file("/var/log/cron.log"); };<br />
destination messages { file("/var/log/messages"); };<br />
filter f_cron { facility(cron); };<br />
filter f_messages { level(info..warn) <br />
and not facility(auth, authpriv, mail, news); };<br />
log { source(src); filter(f_cron); destination(cron); };<br />
log { source(src); filter(f_messages); destination(messages); };</nowiki><br />
}}<br />
<br />
The same message from the {{ic|cron}} facility will end up in both the {{ic|cron.log}} and {{ic|messages}} files. To change this behavior we can use the {{ic|final}} flag, <br />
ending up further processing with the message. Therefore, in this example, if we want messages from the {{ic|cron}} facility not ending up in the<br />
messages file, we should change the cron's log sentence by:<br />
<br />
log { source(src); filter(f_cron); destination(cron); flags(final); };<br />
<br />
another way is to exclude the {{ic|cron}} facility from {{ic|f_messages}} filter:<br />
filter f_messages { level(info..warn) and not facility(cron, auth, authpriv, mail, news); };<br />
<br />
=== PostgreSQL Destination ===<br />
This section will use two roles: {{ic|syslog}} and {{ic|logwriter}}. {{ic|syslog}} will be the administrator of the database {{ic|syslog}} and {{ic|logwriter}} will only be able to add records to the {{ic|logs}} table.<br />
<br />
No longer needed to create table for logs. syslog-ng will create automatically.<br />
psql -U postgres<br />
<br />
postgres=# CREATE ROLE syslog WITH LOGIN;<br />
postgres=# \password syslog # Using the \password function is secure because<br />
postgres=# CREATE ROLE logwriter WITH LOGIN;<br />
postgres=# \password logwriter # the password is not saved in history.<br />
postgres=# CREATE DATABASE syslog OWNER syslog;<br />
postgres=# \q # You are done here for the moment<br />
<br />
Edit {{ic|pg_hba.conf}} to allow {{ic|syslog}} and {{ic|logwriter}} to establish a connection to PostgreSQL.<br />
<br />
{{hc|/var/lib/postgres/data/pg_hba.conf|<br />
# TYPE DATABASE USER CIDR-ADDRESS METHOD<br />
<br />
host syslog logwriter 192.168.0.1/24 md5<br />
host syslog syslog 192.168.0.10/32 md5<br />
}}<br />
<br />
Tell PostgreSQL to reload the configuration files:<br />
<br />
# systemctl reload postgresql<br />
<br />
Edit {{ic|/etc/syslog-ng/syslog-ng.conf}} so that it knows where and how to write to PostgreSQL. syslog-ng will utilize the {{ic|logwriter}} role.<br />
<br />
{{bc|<nowiki>...<br />
#<br />
# SQL logging support<br />
#<br />
<br />
destination d_pgsql {<br />
sql(type(pgsql)<br />
host("127.0.0.1") username("logwriter") password("password")<br />
database("syslog")<br />
table("logs_${HOST}_${R_YEAR}${R_MONTH}${R_DAY}") #or whatever you want, example ${HOST}" for hosts, ${LEVEL}" for levels.. etc<br />
columns("datetime timestamp with time zone", "host varchar(32)", "program varchar(16)", "pid varchar(16)", "message varchar(200)")<br />
values("$R_ISODATE", "$HOST", "$PROGRAM", "$PID", "$MSG")<br />
indexes("datetime", "host", "program", "pid", "message"));<br />
};<br />
<br />
log { source(src); destination(d_pgsql); };</nowiki><br />
}}<br />
<br />
Finally, restart syslog-ng.<br />
# systemctl restart syslog-ng<br />
<br />
And check to see if things are being logged.<br />
psql -U logwriter -d syslog<br />
syslog=> SELECT * FROM <your table name> ORDER BY datetime DESC LIMIT 10;<br />
<br />
=== ISO 8601 timestamps ===<br />
'''Before''' :<br />
#logger These timestamps are not optimal.<br />
#tail -n 1 /var/log/messages.log<br />
Feb 18 14:25:01 hostname logger: These timestamps are not optimal.<br />
#<br />
<br />
Add {{ic|ts_format(iso);}} to {{ic|/etc/syslog-ng/syslog-ng.conf}} in the options section. Example:<br />
options {<br />
stats_freq (0);<br />
flush_lines (0);<br />
time_reopen (10);<br />
log_fifo_size (1000);<br />
long_hostnames(off); <br />
use_dns (no);<br />
use_fqdn (no);<br />
create_dirs (no);<br />
keep_hostname (yes);<br />
perm(0640);<br />
group("log");<br />
ts_format(iso); #make ISO-8601 timestamps<br />
};<br />
<br />
Then:<br />
# systemctl reload syslog-ng<br />
<br />
'''After''' :<br />
#logger Now THAT is a timestamp!<br />
#tail -n 2 /var/log/messages.log<br />
Feb 18 14:25:01 hostname logger: These timestamps are not optimal.<br />
2010-02-18T20:23:58-05:00 electron logger: Now THAT is a timestamp!<br />
#<br />
<br />
=== RFC 3339 timestamps ===<br />
Same as above, except use {{ic|rfc3339}} instead of {{ic|iso}} for {{ic|ts_format}}<br />
<br />
=== Log Levels ===<br />
<br />
Log levels are defined separately for each logged facility in syslog-ng config. Available log levels are listed in /usr/include/sys/syslog.h :<br />
<br />
define LOG_EMERG 0 /* system is unusable */<br />
define LOG_ALERT 1 /* action must be taken immediately */<br />
define LOG_CRIT 2 /* critical conditions */<br />
define LOG_ERR 3 /* error conditions */<br />
define LOG_WARNING 4 /* warning conditions */<br />
define LOG_NOTICE 5 /* normal but significant condition */<br />
define LOG_INFO 6 /* informational */<br />
define LOG_DEBUG 7 /* debug-level messages */<br />
<br />
=== Macros and Variables ===<br />
Macros can be used in both templates, and in destination file names. [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/reference-macros.html Macros of syslog-ng OSE].<br />
<br />
The following code will write the log lines to {{ic|/var/log/test.log}} in the format of {{ic|<nowiki>macroname=value@</nowiki>}}. <br />
<br />
{{bc|<nowiki>template t_test { template("PROGRAM=$PROGRAM@PID=$PID@BSDTAG=$BSDTAG@TAG=$TAG@TAGS=$TAGS@FACILITY=$FACILITY@FACILITY_NUM=$FACILITY_NUM@LEVEL=$LEVEL@LEVEL_NUM=$LEVEL_NUM@PRI=$PRI@PRIORITY=$PRIORITY@FULLHOST=$FULLHOST@FULLHOST_FROM=$FULLHOST_FROM@HOST=$HOST@HOST_FROM=$HOST_FROM@LOGHOST=$LOGHOST@MSGHDR=$MSGHDR@MSGID=$MSGID@MSGONLY=$MSGONLY@MSG=$MSG@MESSAGE=$MESSAGE@SOURCE=$SOURCE@SOURCEIP=$SOURCEIP@SOURCE_IP=$SOURCE_IP@SEQNUM=$SEQNUM@UNIXTIME=$UNIXTIME@FULLDATE=$FULLDATE@ISODATE=$ISODATE@DATE=$DATE@STAMP=$STAMP@TZ=$TZ@TZOFFSET=$TZOFFSET@SEC=$SEC@MIN=$MIN@HOUR=$HOUR@HOUR12=$HOUR12@DAY=$DAY@WEEK=$WEEK@WEEK_DAY=$WEEK_DAY@WEEK_DAY_ABBREV=$WEEK_DAY_ABBREV@WEEK_DAY_NAME=$WEEK_DAY_NAME@MONTH=$MONTH@MONTH_ABBREV=$MONTH_ABBREV@MONTH_NAME=$MONTH_NAME@MONTH_WEEK=$MONTH_WEEK@YEAR=$YEAR@YEAR_DAY=$YEAR_DAY<br />
\n"); template_escape(no); };<br />
<br />
destination d_test { file("/var/log/test.log" template(t_test)); };<br />
<br />
log { source(s_local); destination(d_test); flags(final); };<br />
</nowiki>}}<br />
<br />
You can create your own value list as below once syslog-ng is restarted with:<br />
{{ic|<nowiki>tail /var/log/test.log|tr "@" "\n"</nowiki>}}<br />
<br />
{{bc|<nowiki><br />
PROGRAM=kernel<br />
PID=<br />
BSDTAG=4A<br />
TAG=04<br />
TAGS=.source.s_local<br />
FACILITY=kern<br />
FACILITY_NUM=0<br />
LEVEL=warning<br />
LEVEL_NUM=4<br />
PRI=4<br />
PRIORITY=warning<br />
FULLHOST=www.askapache.com<br />
FULLHOST_FROM=www.askapache.com<br />
HOST=www.askapache.com<br />
HOST_FROM=www.askapache.com<br />
LOGHOST=<br />
MSGHDR=kernel: <br />
MSGID=<br />
MSGONLY=Firewall: *INVALID* IN=eth0 OUT= MAC=00:00 SRC=x.x.x.x DST=198.101.159.98 LEN=40 TOS=0x00 PREC=0x00 TTL=113 ID=7730 DF PROTO=TCP SPT=52369 DPT=80 WINDOW=0 RES=0x00 ACK RST URGP=0 <br />
MSG=Firewall: *INVALID* IN=eth0 OUT= MAC=00:00 SRC=x.x.x.x DST=198.101.159.98 LEN=40 TOS=0x00 PREC=0x00 TTL=113 ID=7730 DF PROTO=TCP SPT=52369 DPT=80 WINDOW=0 RES=0x00 ACK RST URGP=0 <br />
MESSAGE=Firewall: *INVALID* IN=eth0 OUT= MAC=00:00 SRC=x.x.x.x DST=198.101.159.98 LEN=40 TOS=0x00 PREC=0x00 TTL=113 ID=7730 DF PROTO=TCP SPT=52369 DPT=80 WINDOW=0 RES=0x00 ACK RST URGP=0 <br />
SOURCE=s_local<br />
SOURCEIP=127.0.0.1<br />
SOURCE_IP=<br />
UNIXTIME=1369742458<br />
FULLDATE=2013 May 28 08:00:58<br />
ISODATE=2013-05-28T08:00:58-04:00<br />
DATE=May 28 08:00:58<br />
STAMP=2013-05-28T08:00:58-04:00<br />
TZ=-04:00<br />
TZOFFSET=-04:00<br />
SEC=58<br />
MIN=00<br />
HOUR=08<br />
HOUR12=<br />
DAY=28<br />
WEEK=21<br />
WEEK_DAY=3<br />
WEEK_DAY_ABBREV=Tue<br />
WEEK_DAY_NAME=Tuesday<br />
MONTH=05<br />
MONTH_ABBREV=May<br />
MONTH_NAME=May<br />
MONTH_WEEK=4<br />
YEAR=2013<br />
YEAR_DAY=148<br />
</nowiki>}}<br />
<br />
=== See Also ===<br />
* [[Netconsole]] A kernel module that sends all kernel log messages (i.e. dmesg) over the network to another computer, without involving user space (e.g. syslogd).<br />
<br />
== External Links ==<br />
* [http://www.balabit.com/network-security/syslog-ng/opensource-logging-system/overview syslog-ng OSE Project Page]<br />
* [http://www.balabit.com/support/documentation/ Portal to syslog-ng Documentation]<br />
** [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/index.html The syslog-ng 3.4 Administrator Guide]<br />
** [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/syslog-ng-parameter-index.html List of syslog-ng 3.4 Parameters]<br />
** [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/reference-macros.html List of syslog-ng 3.4 Macros]<br />
* [http://freshmeat.net/projects/syslog-ng/ syslog-ng Project Page on Freshmeat]<br />
* [https://wiki.gentoo.org/wiki/Syslog-ng Gentoo syslog-ng wiki]<br />
* [http://www.gentoo.org/doc/en/security/security-handbook.xml?part=1&chap=3 Gentoo Security Handbook on Logging]<br />
* [http://www.pcwdld.com/what-is-syslog-including-servers-and-ports What is Syslog? Logging with PostgreSQL HOWTO]<br />
* [[wikipedia:ISO_8601|ISO_8601]] Wikipedia page for ISO 8601<br />
* [http://tools.ietf.org/html/rfc3164 RFC 3164] - The BSD syslog Protocol<br />
* [http://tools.ietf.org/html/rfc3164 RFC 5424] - The Syslog Protocol<br />
** [http://tools.ietf.org/html/rfc5425 RFC 5425] - Transport Layer Security (TLS) Transport Mapping for Syslog<br />
** [http://tools.ietf.org/html/rfc5425 RFC 5426] - Transmission of Syslog Messages over UDP<br />
** [http://tools.ietf.org/html/rfc5425 RFC 5427] - Textual Conventions for Syslog Management<br />
** [http://tools.ietf.org/html/rfc5425 RFC 5428] - MIB for PacketCable and IPCablecom-Compliant Devices<br />
* [http://tools.ietf.org/html/rfc3339 RFC 3339] - Date and Time on the Internet: Timestamps</div>Piratejonhttps://wiki.archlinux.org/index.php?title=Dm-crypt&diff=233351Dm-crypt2012-11-03T07:17:19Z<p>Piratejon: /* Adding Additional Passphrases or Keyfiles to a LUKS Encrypted Partition */ clarify luksAddKey example when luksFormat was used with a keyfile rather than a passphrase</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Security]]<br />
[[Category:File systems]]<br />
[[ru:System Encryption with LUKS]]<br />
[[zh-CN:System Encryption with LUKS]]<br />
{{Article summary start}}<br />
{{Article summary text|This tutorial will show you how to set up system encryption with LUKS for dm-crypt.}}<br />
{{Article summary heading|Related}}<br />
{{Article summary wiki|Disk Encryption}}<br />
{{Article summary wiki|Removing System Encryption}}<br />
{{Article summary end}}<br />
<br />
This article focuses on how to set up full system encryption on Arch Linux, using dm-crypt with LUKS.<br />
<br />
'''dm-crypt''' is the standard device-mapper encryption functionality provided by the Linux kernel. It can be used directly by those who like to have full control over all aspects of partition and key management.<br />
<br />
'''LUKS''' is an additional convenience layer which stores all of the needed setup information for dm-crypt on the disk itself and abstracts partition and key management in an attempt to improve ease of use.<br />
<br />
For more details on how dm-crypt+LUKS compares to other disk encryption solution, see [[Disk Encryption#Comparison table]].<br />
<br />
== Caveats ==<br />
{{Out of date|As of the [http://www.archlinux.org/news/install-media-20120715-released/ 2012.07.15 installation media release], AIF (the Arch Installation Framework) is no longer included but instead [https://github.com/falconindy/arch-install-scripts Arch Install Scripts] are provided to aid in the installation process. A lot of content still has to get updated all over this page. Many external Links are old so that they may not include all noticeable changes in Arch Linux configs. Just keep that in mind while reading.}}<br />
<br />
== Initial Setup ==<br />
=== Overview and Preparation ===<br />
The Arch installation media comes with all the tools required for system encryption.<br />
The installation of an encrypted system is largely the same as installing an unencrypted system, so you can follow the [[Installation Guide]] or the [[Beginners' Guide]] after the encrypted partitions are set up. You will have to adjust the System Configuration to be able to boot from your Luks-Volumes tough.<br />
<br />
Routine creation of an encrypted system follows these general steps:<br />
<br />
::* Secure erasure of the hard disk drive(s)<br />
::* Partitioning and setup of encryption ([[LVM]] optional)<br />
::* Routine package selection and installation<br />
::* System Configuration<br />
<br />
{{Warning | Encrypting a partition will erase everything currently on that partition. Please make appropriate data backups prior to starting.}}<br />
<br />
=== Secure erasure of the hard disk drive ===<br />
{{Note|The following methods are specifically to dm-crypt/LUKS. For detailed instructions on how to erase and prepare a drive consult: [[Securely wipe disk]]}}<br />
<br />
It is recommended to wipe all data accesible on your drive or partition using random data. Random data should be completely indistinguishable from all data later written by dm-crypt for security reasons. Secure erasure of the hard disk drive involves overwriting the entire drive with random data.<br />
<br />
Both new and used disks should be securely overwritten. This helps ensure the privacy of data located within the encrypted partitions. The contents of disks purchased directly from a manufacturer is not guaranteed. If the drive was filled with zero bits then after writing encrypted data, it is relatively simple to identify where the encrypted data ends and the zeroed data begins. Since an encrypted partition should be indistinguishable from random data, the lack of random data on a zeroed drive makes the encrypted data an easier target of cryptanalysis.<br />
<br />
Repartitioning or reformatting a used hard drive removes the file system structure for identifying where the original data was located while leaving the actual data intact on the drive itself. It is relatively straightforward using [[File Recovery]] Software to access the remnant data. Therefore hard drives should be securely overwritten with random data prior to encryption to prevent data recovery.<br />
<br />
In deciding which method to use for secure erasure of a hard disk drive, remember that this will not need to be performed more than once for as long as the drive is used as an encrypted drive.<br />
<br />
==== Use LUKS container as pseudorandom number generator (alternate) ====<br />
<br />
The [http://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions#5._Security_Aspects cryptsetup FAQ] mentions a very simple procedure to use an existing dm-crypt-volume to wipe all free space accessible on the underlying block device with random data by acting as a simple pseudorandom number generator. It is also claimed to protect against disclosure of usage patterns.<br />
<br />
{{bc|1=<br />
# dd if=/dev/zero of=/dev/mapper/luks-container}}<br />
<br />
===== Wipe free space with encrypted file after Installation =====<br />
<br />
The same effect can be achieved if a file is created on each encrypted partition that fills the partition completely after the system is installed, booted and filesystems mounted. That is because encrypted data is indistinguishable from random.<br />
<br />
{{bc|1=<br />
# dd if=/dev/zero of=/file/in/luks-container<br />
# rm /file/in/luks-container}}<br />
<br />
Obviously the above process has to be repeated for every container created.<br />
<br />
==== Wipe LUKS keyslots ====<br />
#cryptsetup luksKillSlot <device> <key slot number><br />
<br />
This will only wipe a single keyslot.<br />
<br />
==== Wipe LUKS header ====<br />
The partitions formatted with dm-crypt/LUKS contain a header with the cipher and crypt-options used, which is referred to {{ic|dm-mod}} when opening the blockdevice. After the header the actual random data partition starts. Hence, when de-commissioning a drive (e.g. sale of PC, switch of drives, etc.) it ''may'' be just enough to wipe the header of the partition, rather than overwriting the whole drive - which can be a lengthy process. <br />
<br />
Wiping the LUKS header will delete the PBKDF2-encrypted (AES) master key, salts and so on.<br />
<br />
{{Note|It is crucial to write to the LUKS encrypted partition ({{ic|/dev/sda'''1'''}} in this example) and not directly to the disks device node. If you did set up encryption as a device-mapper layer on top of others, e.g. LVM on LUKS on RAID then write to RAID respectively.}}<br />
<br />
A header with one single default 256 bit size keyslot is 1024KB in size. It is advised to also overwrite the first 4KB written by dm-crypt, so 1028KB have to be wiped. That is {{ic|1052672}} Byte.<br />
<br />
For zero offset use:<br />
#head -c 1052672 /dev/zero > /dev/sda1; sync<br />
<br />
For 512 bit key length (e.g. for aes-xts-plain with 512 bit key) the header is 2MB.<br />
<br />
If in doubt, just be generous and overwrite the first 10MB or so.<br />
<br />
#dd if=/dev/zero of=/dev/sda1 bs=512 count=20480<br />
<br />
{{Note|With a backup-copy of the header data can get rescued but the filesystem was likely damaged as the first encrypted sectors were overwritten. See further sections on how to make a backup of the crucial header blocks.}}<br />
<br />
When wiping the header with random data and the header is followed by encrypted data written ontop random data everything left is random data.<br />
<br />
====Discard/TRIM support for solid state disks (SSD)====<br />
Solid state disk users should be aware that by default, Linux's full-disk encryption mechanisms will ''not'' forward TRIM commands from the filesystem to the underlying disk. The device-mapper maintainers have made it clear that TRIM support will never be enabled by default on dm-crypt devices because of the potential security implications.<br />
<br />
Most users will still want to use TRIM on their encrypted SSDs. Minimal data leakage in the form of freed block information, perhaps sufficient to determine the filesystem in use, may occur on devices with TRIM enabled. An illustration and discussion of the issues arising from activating TRIM is available in the [http://asalor.blogspot.de/2011/08/trim-dm-crypt-problems.html blog] of a {{ic|cryptsetup}} developer.<br />
<br />
As a semi-tangential caveat, it is worth noting that because TRIM provides information to the disk firmware about which blocks contain data, encryption schemes that rely on plausible deniability, like TrueCrypt's hidden volumes, should never be used on a device that utilizes TRIM. This is probably also valid for TC containers within a LUKS encrypted device that uses TRIM.<br />
<br />
TrueCrypt's developers also recommend against using any TC volume on a device that performs wear-leveling techniques to extend the life of the disk; most flash devices, including SSDs and USB flash drives, use mandatory wear-leveling at the firmware level. LUKS devices are probably not vulnerable to problems with wear-leveling if the entire device is blanked before the LUKS partition is initialized. See http://www.truecrypt.org/docs/?s=trim-operation and http://www.truecrypt.org/docs/?s=wear-leveling for more information.<br />
<br />
In {{Pkg|linux}} 3.1 and up, support for dm-crypt TRIM pass-through can be toggled upon device creation or mount with dmsetup. Support for this option also exists in {{Pkg|cryptsetup}} version 1.4.0 and up. To add support during boot, you will need to add {{ic|:allow-discards}} to the {{ic|cryptdevice}} option. The TRIM option may look like this:<br />
cryptdevice=/dev/mapper/root:root:allow-discards<br />
<br />
For the main {{ic|cryptdevice}} configuration options before the {{ic|:allow-discards}} please refer to the sections following.<br />
<br />
===Partitioning===<br />
<br />
After the drive has been securely overwritten, it is time to create partitions and begin setting up an encrypted system.<br />
<br />
There are multiple ways to create disk partitions:<br />
<br />
::*Standard partitions<br />
::*[[#LVM:_Logical_Volume_Manager|LVM]]<br />
::*[[RAID]]<br />
<br />
LUKS is compatible with systems that require LVM and/or RAID as well as with with standard primary, extended, and logical partitions.<br />
<br />
====Standard Partitions====<br />
<br />
These are the partitions that most people are familiar with. They come in three flavors: primary partitions, extended partitions, and logical partitions.<br />
<br />
;Primary Partitions: These are the normal partitions recognized by the system BIOS. There can be up to four of these stored in the MBR.<br />
<br />
;Extended Partitions: These are primary partitions that also define another partition within themselves. Extended partitions were created to work around the original limit of four primary partitions.<br />
<br />
;Logical Partitions: These are the partitions that are defined within extended partitions.<br />
<br />
====LVM: Logical Volume Manager====<br />
<br />
The LVM allows for creation of volume groups for systems that require complex combinations of multiple hard disk drives and partitions that are not possible with standard partitions. LVM is covered in detail in the [[LVM|Article on LVM]] which is recommended reading prior to continuing with the instructions on [[Dm-crypt_with_LUKS#Encrypting_a_LVM_setup|setting up LUKS with LVM]] located below.<br />
<br />
{{Tip|Btrfs has a built-in [[Btrfs#Subvolumes|Subvolume-Feature]] that fully replaces the need for LVM if no other filesystems are required. An encrypted swap is not possible this way and swap files are [https://btrfs.wiki.kernel.org/index.php/FAQ#Does_btrfs_support_swap_files.3F not supported] by btrfs up to now.}}<br />
<br />
{{Poor writing|Due to uncomprehensible disarrangement this small section on stacking of device-mapper layers was overcomplicated to read. Now different setups are seperated by subsection-headings, nevertheless language and content still need improvement and duplicates should get deleted.}}<br />
<br />
=====LVM on LUKS=====<br />
<br />
There is a growing preference towards logical volume management of LUKS encrypted physical media (LVM on LUKS). The deployment of LVM on LUKS is considered much more generalizable. In a LVM on LUKS scenario, the LUKS-partition has to be opened and mapped before LVM can access the underlaying setup volumes.<br />
<br />
One reason for this is that using LUKS as the lowest level of infrastructure most closely approximates the deployment of physical disks with built-in hardware encryption. In that case, logical volume management would be layered on top of the hardware encryption - usage of LUKS would be superfluous.<br />
<br />
=====LUKS on LVM=====<br />
<br />
It is possible there may exist usage scenarios where encrypting logical volumes rather than physical disks is required (LUKS on LVM).<br />
A usage scenario for LUKS on LVM exists where utmost flexibility for assigning available diskspace or a mix of unencrypted and encrypted volumes is desired. Upon boot the LVM is setup and assigned before the LUKS-encrypted volumes are opened. In order to manage changes of volumes in a LUKS on LVM setup, both module layers' setup have to be taken into account, i.e. shrinking or expanding an encrypted volume has to include the resizing of the encrypted LUKS blockdevice to ensure integrity of it and the filesystem. That said, in simpler scenarios the usage of LVM may be superfluous.<br />
<br />
====Creating Disk Partitions====<br />
<br />
Disk partitions are created using:<br />
<br />
# cfdisk<br />
<br />
This will display a graphical interface for creating disk partitions.<br />
<br />
There are two required partitions for any encrypted system:<br />
<br />
; root file system: {{ic|'''/'''}} Will be encrypted and store all system and user files ({{ic|/usr}}, {{ic|/bin}}, {{ic|/var}}, {{ic|/home}}, etc.)<br />
<br />
; initial boot partition: {{ic|'''/boot'''}} Will ''not'' be encrypted; the bootloader needs to access the {{ic|/boot}} directory where it will load the initramfs/encryption modules needed to load the rest of the system which ''is'' encrypted (see [[Mkinitcpio]] for details). For this reason, {{ic|/boot}} needs to reside on its own, unencrypted partition.<br />
<br />
{{Note| A swap partition is optional; it can be encrypted with dm-crypt/LUKS. See [[#Encrypting_the_Swap_partition|Encrypting the Swap Partition]] for details.}}<br />
<br />
=====Single Disk Systems=====<br />
<br />
Depending on the system demands, there may be additional partitions desired. These partitions can be individually created at this level by defining separate primary or extended/logical partitions. However, if LVM is to be used, the space unoccupied by {{ic|/boot}} and swap should be defined as single large partition which will be divided up later at the LVM level.<br />
<br />
=====Multiple Disk Systems=====<br />
<br />
In systems that will have multiple hard disk drives, the same options exist as a single disk system. After the creation of the {{ic|/boot}} and swap partitions, the remaining free space on physical disks can divided up into their respective partitions at this level, or large partitions can define all free space per physical disk with intent to partition them within the LVM.<br />
<br />
== Configuring LUKS ==<br />
This section covers how to manually utilize LUKS from the command line to encrypt a system. <br />
<br />
=== Mapping Physical Partitions to LUKS ===<br />
After writing the partition table to the MBR (optionally set up LVM thereafter) the next step is to create the LUKS and dm-crypt magic and make device mapper mount it to the filesystem of the installation system.<br />
<br />
When creating LUKS partitions they must be associated with a key. The key is used to unlock the header of the LUKS-encrypted partitions.<br />
<br />
A key is either a: <br />
<br />
*Passphrase<br />
*Keyfile <br />
<br />
It is possible to define up to 8 different keys per LUKS partition. This enables the user to create access keys for save backup storage. Also a different key-slot could be used to grant access to a partition to a user by issuing a second key and later revoking it again without the need to re-encrypt the partition.<br />
<br />
==== Using LUKS to Format Partitions with a Passphrase ====<br />
{{Note|Using a passphrase to decrypt LUKS partitions automatically from {{ic|/etc/crypttab}} is [http://www.mail-archive.com/arch-projects@archlinux.org/msg02115.html deprecated.]}}<br />
<br />
Cryptsetup is used to interface with LUKS for formatting, mounting and unmounting encrypted partitions.<br />
<br />
Usage:<br />
# cryptsetup [OPTION...] <action> <action-specific><br />
<br />
Example:<br />
# cryptsetup --cipher aes-xts-plain64 --key-size 512 --hash sha512 --iter-time 5000 --use-random --verify-passphrase luksFormat <device> <br />
<br />
Common options used with luksFormat:<br />
<br />
{| class="wikitable" style="margin:0 5em 0.5em 0.5em 0.5em;"<br />
! scope="col" style="text-align:left" | Available&nbsp;options<br />
! scope="col" style="text-align:left" | Cryptsetup defaults <br />
! scope="col" style="text-align:left" | Comment<br />
! scope="col" style="text-align:left" | Example<br />
! scope="col" style="text-align:left" | Comment<br />
|-<br />
! scope="row" style="text-align:right" | --cipher, -c<br />
| {{ic|aes-cbc-essiv:sha256}}<br />
| Use the AES-[[Disk_Encryption#Ciphers_and_modes_of_operation|cipher]] with [http://en.wikipedia.org/wiki/Disk_encryption_theory#Cipher-block_chaining_.28CBC.29 CBC/ESSIV].<br />
| {{ic|aes-xts-plain64}}<br />
| [http://en.wikipedia.org/wiki/Disk_encryption_theory#XEX-based_tweaked-codebook_mode_with_ciphertext_stealing_.28XTS.29 XTS]. For volumes >2TiB use {{ic|aes-xts-plain64}} (requires kernel >= 2.6.33).<br />
|-<br />
! scope="row" style="text-align:right" | --key-size, -s<br />
| {{ic|256}}<br />
| The cipher is used with 256 bit key-size.<br />
| {{ic|512}}<br />
| [http://en.wikipedia.org/wiki/XEX-TCB-CTS#Issues_with_XTS XTS splits the supplied key] into fraternal twins. For an effective AES-256 the XTS key-size must be {{ic|512}}.<br />
|-<br />
! scope="row" style="text-align:right" | --hash, -h<br />
| {{ic|sha1}}<br />
| Hash algorithm used for [[Disk_Encryption#Keys.2C_keyfiles_and_passphrases|PBKDF2]].<br />
| {{ic|sha512}}<br />
| <br />
|-<br />
! scope="row" style="text-align:right" | --iter-time, -i<br />
| {{ic|1000}}<br />
| Number of milliseconds to spend with PBKDF2 passphrase processing.<br />
| {{ic|5000}}<br />
| Using a hash stronger than sha1 results in less iterations if iter-time is not increased.<br />
|-<br />
! scope="row" style="text-align:right" | --use-random<br />
| {{ic|--use-'''u'''random}}<br />
| /dev/u[[Random|random]] is used as randomness source for the (long-term) volume master key.<br />
| {{ic|--use-random}}<br />
| Avoid generating an insecure master key if low on entropy. Will block if the entropy pool is used up.<br />
|-<br />
! scope="row" style="text-align:right" | --verify-passphrase, -y<br />
| Yes<br />
| Default only for luksFormat and luksAddKey.<br />
| -<br />
| No need to type for archlinux at the moment.<br />
|}<br />
<br />
When comparing the defaults with the example, it has to be taken into account that a number of the options stated affect system performance just for creating the initial crypt-blockdevice or opening it, but not the disk-io operations when the system is running. A full list of options {{ic|cryptsetup}} accepts can be found in the [http://www.dsm.fordham.edu/cgi-bin/man-cgi.pl?topic=cryptsetup manpage].<br />
<br />
In the following examples for creating LUKS partitions, we will use the AES cipher in XTS mode; at present this is most generally used preferred cipher.<br />
Other ciphers can be used with cryptsetup, and details about them can be found here: [[Wikipedia:Block_cipher]]<br />
<br />
'''Formatting LUKS Partitions'''<br />
<br />
First of all make sure the device mapper kernel module is loaded by executing the following: {{ic|# modprobe dm_mod}}<br />
<br />
In order to format a desired partition as an encrypted LUKS partition execute:<br />
{{hc|# cryptsetup -c <cipher> -y -s <key size> luksFormat /dev/<partition name>|<br />
Enter passphrase: <password><br />
Verify passphrase: <password>}}<br />
<br />
Check results:<br />
# cryptsetup luksDump /dev/<drive><br />
<br />
This should be repeated for all partitions except for {{ic|/boot}} and possibly swap.<br />
<br />
The example below will create an encrypted root partition using the AES cipher in XTS mode (generally referred to as ''XTS-AES'').<br />
{{bc|# cryptsetup -c aes-xts-plain -y -s 512 luksFormat /dev/sda2}}<br />
<br />
{{Note|If hibernation usage is planned, swap must be encrypted in this fashion; otherwise, if hibernation is not a planned feature for the system, encrypting the swap file will be performed in a alternative manner.}}<br />
<br />
{{Warning|Irrespective of the chosen partitioning method, the {{ic|/boot}} partition must remain separate and unencrypted in order to load the kernel and boot the system.}}<br />
<br />
'''Unlocking/Mapping LUKS Partitions with the Device Mapper'''<br />
<br />
Once the LUKS partitions have been created it is time to unlock them.<br />
<br />
The unlocking process will map the partitions to a new device name using the device mapper. This alerts the kernel that {{ic|/dev/<partition name>}} is actually an encrypted device and should be addressed through LUKS using the {{ic|/dev/mapper/<name>}} so as not to overwrite the encrypted data. To guard against accidental overwriting, read about the possibilities to [[LUKS#Backup_the_cryptheader|backup the cryptheader]] after finishing setup.<br />
<br />
In order to open an encrypted LUKS partition execute:<br />
{{hc|# cryptsetup luksOpen /dev/<partition name> <device-mapper name>|<br />
Enter any LUKS passphrase: <password><br />
key slot 0 unlocked.<br />
Command successful.}}<br />
<br />
Usually the device mapped name is descriptive of the function of the partition that is mapped, example:<br />
<br />
; cryptsetup luksOpen /dev/sda2 swap: Once opened, the swap partition device address would be {{ic|/dev/mapper/swap}} instead of {{ic|/dev/sda2}}.<br />
<br />
; cryptsetup luksOpen /dev/sda3 root: Once opened, the root partition device address would be {{ic|/dev/mapper/root}} instead of {{ic|/dev/sda3}}.<br />
<br />
; cryptsetup luksOpen /dev/sda3 lvmpool (alternate): For setting up [[#LVM:_Logical_Volume_Manager|LVM]] ontop the encryption layer the device file for the decrypted volume group would be anything like {{ic|/dev/mapper/lvmpool}} instead of {{ic|/dev/sda3}}. LVM will then give additional names to all logical volumes created, e.g. {{ic|/dev/mapper/lvmpool-root}} and {{ic|/dev/mapper/lvmpool-swap}}.<br />
<br />
In order to write encrypted data into the partition it must be accessed through the device mapped name.<br />
<br />
{{Note|Since {{ic|/boot}} is not encrypted, it does not need a device mapped name and will be addressed as {{ic|/dev/sda1}}.}}<br />
<br />
==== Using LUKS to Format Partitions with a Keyfile ====<br />
{{Note|This section describes using a plaintext keyfile, if you want to encrypt your keyfile giving you two factor authentication see [https://wiki.archlinux.org/index.php/System_Encryption_with_LUKS#Using_GPG_or_OpenSSL_Encrypted_Keyfiles Section 9] for details, but please still read this section.}}<br />
<br />
'''What is a Keyfile?'''<br />
<br />
A keyfile is any file in which the data contained within it is used as the passphrase to unlock an encrypted volume.<br />
Therefore if these files are lost or changed, decrypting the volume will no longer be possible.<br />
<br />
{{Tip|Define a passphrase in addition to the keyfile for backup access to encrypted volumes in the event the defined keyfile is lost or changed.}}<br />
<br />
'''Why use a Keyfile?'''<br />
<br />
There are many kinds of keyfile. Each type of keyfile used has benefits and disadvantages summarized below:<br />
<br />
:'''keyfile.passphrase:'''<br />
::this is my passphrase I would have typed during boot but I have placed it in a file instead<br />
<br />
This is a keyfile containing a simple passphrase. The benefit of this type of keyfile is that if the file is lost the data it contained is known and hopefully easily remembered by the owner of the encrypted volume. However the disadvantage is that this does not add any security over entering a passphrase during the initial system start.<br />
<br />
:'''keyfile.randomtext:'''<br />
::fjqweifj830149-57 819y4my1- 38t1934yt8-91m 34co3;t8y;9p3y-<br />
<br />
This is a keyfile containing a block of random characters. The benefit of this type of keyfile is that it is much more resistant to dictionary attacks than a simple passphrase. An additional strength of keyfiles can be utilized in this situation which is the length of data used. Since this is not a string meant to be memorized by a person for entry, it is trivial to create files containing thousands of random characters as the key. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase.<br />
<br />
:'''keyfile.binary:'''<br />
::where any binary file, images, text, video could be chosen as the keyfile<br />
<br />
This is a binary file that has been defined as a keyfile. When identifying files as candidates for a keyfile, it is recommended to choose files that are relatively static such as photos, music, video clips. The benefit of these files is that they serve a dual function which can make them harder to identify as keyfiles. Instead of having a text file with a large amount of random text, the keyfile would look like a regular image file or music clip to the casual observer. The disadvantage is that if this file is lost or changed, it will most likely not be possible to access the encrypted volume without a backup passphrase. Additionally, there is a theoretical loss of randomness when compared to a randomly generated text file. This is due to the fact that images, videos and music have some intrinsic relationship between neighboring bits of data that does not exist for a text file. However this is controversial and has never been exploited publicly.<br />
<br />
'''Creating a Keyfile with Random Characters'''<br />
<br />
Here {{ic|dd}} is used to generate a keyfile of 2048 bits of random characters.<br />
<br />
# dd if=/dev/urandom of=mykeyfile bs=512 count=4<br />
<br />
The usage of {{ic|dd}} is similar to initially wiping the volume with random data prior to encryption. <br />
<br />
{{Warning|Do not use [[badblocks]] here. It only generate a random pattern which just repeats its randomness over and over again.}}<br />
<br />
'''Creating a new LUKS encrypted partition with a Keyfile'''<br />
<br />
When creating a new LUKS encrypted partition, a keyfile may be associated with the partition on its creation using:<br />
<br />
# cryptsetup -c <desired cipher> -s <key size> luksFormat /dev/<volume to encrypt> '''/path/to/mykeyfile'''<br />
<br />
This is accomplished by appending the bold area to the standard cryptsetup command which defines where the keyfile is located.<br />
<br />
==== Adding Additional Passphrases or Keyfiles to a LUKS Encrypted Partition ====<br />
<br />
LUKS supports the association of up to 8 keys with any single encrypted volume.<br />
Keys can be either keyfiles or passphrases.<br />
<br />
Once an encrypted partition has been created, the initial key is associated at slot 0.<br />
Additional keys will occupy slots 1&ndash;7.<br />
<br />
The addition of new keys to an encrypted partition is accomplished using cryptsetup with the {{ic|luksAddKey}} extension.<br />
<br />
# cryptsetup luksAddKey /dev/<encrypted volume> '''/path/to/myadditionalkeyfile'''<br />
<br />
If you specified a keyfile rather than a passphrase when you used luksFormat and have not added a passphrase yet, you will need to specify the original keyfile with the -d option when using luksAddKey:<br />
<br />
# cryptsetup luksAddKey /dev/<encrypted volume> '''/path/to/myadditionalkeyfile''' -d /path/to/mykeyfile<br />
<br />
Where {{ic|/dev/<encrypted volume>}} is the volume that is to have the new key associated with it, and /path/to/mykeyfile is the keyfile used with luksFormat.<br />
<br />
If the bolded area is present, cryptsetup will look for the keyfile defined at that location to associate with the encrypted volume specified. Otherwise a new passphrase will be prompted for.<br />
<br />
=== Storing the Key File ===<br />
<br />
==== External Storage on a USB Drive ====<br />
<br />
=====Preparation for Persistent block device naming=====<br />
<br />
For reading the file from an external storage device it is very convenient to access it through udev's [[Persistent block device naming]] features and not by ordinary device nodes like {{ic|/dev/sdb1}} whose naming depends on the order in which devices are plugged in. So in order to assure that the {{ic|encrypt}} HOOK in the initcpio finds your keyfile, you must use a permanent device name. <br />
<br />
=====Persistent symlinks=====<br />
<br />
{{Merge|Persistent block device naming|Anything not specific to storing LUKS keyfiles should get merged there.}}<br />
<br />
A quick method (as opposed to setting up a [[udev]] rule) for doing so involves referencing the right partition by its UUID, id (based on hardware info and serial number) or filesystem label.<br />
<br />
Plug the device in and print every file name under /dev/disk:<br />
<br />
{{hc|#ls -lR /dev/disk/|<br />
/dev/disk/:<br />
total 0<br />
drwxr-xr-x 2 root root 180 Feb 12 10:11 by-id<br />
drwxr-xr-x 2 root root 60 Feb 12 10:11 by-label<br />
drwxr-xr-x 2 root root 100 Feb 12 10:11 by-path<br />
drwxr-xr-x 2 root root 180 Feb 12 10:11 by-uuid<br />
<br />
/dev/disk/by-id:<br />
total 0<br />
lrwxrwxrwx 1 root root 9 Feb 12 10:11 usb-Generic_STORAGE_DEVICE_000000014583-0:0 -> ../../sdb<br />
lrwxrwxrwx 1 root root 10 Feb 12 10:11 usb-Generic_STORAGE_DEVICE_000000014583-0:0-part1 -> ../../sdb1<br />
<br />
/dev/disk/by-label:<br />
total 0<br />
lrwxrwxrwx 1 root root 10 Feb 12 10:11 Keys -> ../../sdb1<br />
<br />
/dev/disk/by-path:<br />
total 0<br />
lrwxrwxrwx 1 root root 9 Feb 12 10:11 pci-0000:00:1d.7-usb-0:1:1.0-scsi-0:0:0:0 -> ../../sdb<br />
lrwxrwxrwx 1 root root 10 Feb 12 10:11 pci-0000:00:1d.7-usb-0:1:1.0-scsi-0:0:0:0-part1 -> ../../sdb1<br />
<br />
/dev/disk/by-uuid:<br />
total 0<br />
lrwxrwxrwx 1 root root 10 Feb 12 10:11 baa07781-2a10-43a7-b876-c1715aba9d54 -> ../../sdb1}}<br />
<br />
'''UUID'''<br />
<br />
Using the filesystem UUID for persistent block device naming is considered very reliable. Filesystem UUIDs are stored in the filesystem itself, meaning that the UUID will be the same if you plug it into any other computer, and that a dd backup of it will always have the same UUID since dd does a bitwise copy.<br />
<br />
The right device node for what is now {{ic|/dev/sdb1}} will always get symlinked by {{ic|/dev/disk/by-uuid/baa07781-2a10-43a7-b876-c1715aba9d54}}. Symlinks can be used in the bootloaders "cryptkey" kernel option or anywhere else.<br />
<br />
For legacy filesystems like FAT the UUID will be much shorter but collision is still unlikely to happen if not mounting many different FAT filesystems at once.<br />
<br />
'''Label'''<br />
<br />
In the following example a FAT partition is labeled as "Keys" and will always get symlinked by {{ic|/dev/disk/by-label/Keys}}:<br />
<br />
#mkdosfs -n >volume-name< /dev/sdb1<br />
<br />
{{hc|#blkid -o list|<br />
device fs_type label mount point UUID<br />
<nowiki>-------------------------------------------------------</nowiki><br />
/dev/sdb1 vfat Keys (not mounted) 221E-09C0}}<br />
<br />
{{Note|If you plan to store the keyfile between [[#Storing_the_key_between_MBR_and_1st_partition|MBR and the 1st partition]] you '''cannot use this method''', since it only allows access to the partitions ({{ic|sdb1}}, {{ic|sdb2}}, ...) but not to the USB device ({{ic|sdb}}) itself. Use something like {{ic|/dev/disk/by-id/*}} or alternatively create a udev rule as described in the following section.}}<br />
<br />
=====Persistent udev rule=====<br />
Optionally you may choose to set up your flash drive with a [[udev]] rule. There is some documentation in the Arch wiki about that already; if you want more in-depth, structural info, read [http://reactivated.net/writing_udev_rules.html this guide]. Here is quickly how it goes.<br />
<br />
Get the serial number from your USB flash drive:<br />
lsusb -v | grep -A 5 Vendor<br />
<br />
Create a udev rule for it by adding the following to a file in {{ic|/etc/udev/rules.d/}}, such as {{ic|8-usbstick.rules}}:<br />
KERNEL=="sd*", ATTRS{serial}=="$SERIAL", SYMLINK+="$SYMLINK%n"<br />
<br />
Replace {{ic|$SYMLINK}} and {{ic|$SERIAL}} with their respective values. {{ic|%n}} will expand to the partition (just like sda is subdivided into sda1, sda2, ...). You do not need to go with the 'serial' attribute. If you have a custom rule of your own, you can put it in as well (e.g. using the vendor name).<br />
<br />
Rescan your sysfs:<br />
udevadm trigger<br />
Now check the contents of {{ic|/dev}}:<br />
ls /dev<br />
It should show your device with your desired name.<br />
<br />
==== Generating the keyfile ====<br />
Optionally you can mount a tmpfs for storing the temporary keyfile.<br />
# mkdir ./mytmpfs<br />
# mount tmpfs ./mytmpfs -t tmpfs -o size=32m<br />
# cd ./mytmpfs<br />
The advantage is that it resides in RAM and not on a physical disk, so after unmounting your keyfile is securly gone.<br />
So copy your keyfile to some place you consider as secure before unmounting.<br />
If you are planning to store the keyfile as a plain file on your USB device, you can also simply execute the following command in the corresponding directory, e.g. {{ic|/media/sdb1}}<br />
<br />
The keyfile can be of arbitrary content and size. We will generate a random temporary keyfile of 2048 bytes:<br />
# dd if=/dev/urandom of=secretkey bs=512 count=4<br />
<br />
If you stored your temporary keyfile on a physical storage device, remember to not just (re)move the keyfile later on, but use something like<br />
cp secretkey /destination/path<br />
shred --remove --zero secretkey<br />
to securely overwrite it. For overaged filesystems like FAT or ext2 this will suffice while in the case of journaling filesystems, flash memory hardware and other cases it is highly recommended to [[Securely wipe disk|wipe the entire device]] or at least the keyfiles partition.<br />
<br />
Add a keyslot for the temporary keyfile to the LUKS header:<br />
{{hc|# cryptsetup luksAddKey /dev/sda2 secretkey|<br />
Enter any LUKS passphrase:<br />
key slot 0 unlocked.<br />
Command successful.}}<br />
<br />
==== Storing the keyfile ====<br />
To store the key file, you have two options. The first is less risky than the other, but perhaps a bit more secure (if you consider security by obscurity as more secure).<br />
In any case you have to do some further configuration, if not already done above.<br />
<br />
==== Configuration of initcpio ====<br />
You have to add two extra modules in your {{ic|/etc/mkinitcpio.conf}}, one for the drive's file system and one for the codepage. Further if you created a udev rule, you should tell {{ic|mkinitcpio}} about it:<br />
MODULES="ata_generic ata_piix nls_cp437 vfat"<br />
FILES="/etc/udev/rules.d/8-usbstick.rules"<br />
In this example it is assumed that you use a FAT formatted USB drive. Replace those module names if you use another file system on your USB stick (e.g. ext2) or another codepage. Users running the stock Arch kernel should stick to the codepage mentioned here.<br />
<br />
Additionally, insert the {{ic|usb}} hook somewhere before the {{ic|encrypt}} hook.<br />
HOOKS="... '''usb''' encrypt ... filesystems ..."<br />
<br />
If you have a non-US keyboard, it might prove useful to load your keyboard layout before you are prompted to enter the password to unlock the root partition at boot. For this, you will need the {{ic|keymap}} hook before {{ic|encrypt}}.<br />
<br />
Generate a new image (maybe you should backup a copy of your old {{ic|/boot/initramfs-linux.img}} first):<br />
# mkinitcpio -p linux<br />
<br />
==== Storing the key as a plain (visible) file ====<br />
Be sure to choose a plain name for your key &ndash; a bit of 'security through obscurity' is always nice ;-). Avoid using dotfiles (hidden files) &ndash; the {{ic|encrypt}} hook will fail to find the keyfile during the boot process.<br />
<br />
You have to add a kernel parameter in your {{ic|/boot/grub/menu.lst}} ([[GRUB]]). It should look something like this:<br />
kernel /vmlinuz-linux cryptdevice=/dev/sda3:root root=/dev/mapper/root ro cryptkey=/dev/usbstick:vfat:/secretkey<br />
This assumes {{ic|/dev/usbstick}} is the FAT partition of your choice. Replace it with {{ic|/dev/disk/by-...}} or whatever your device is.<br />
<br />
That is all, reboot and have fun!<br />
<br />
==== Storing the key between MBR and 1st partition ====<br />
We will write the key directly between the Master Boot Record (MBR) and the first partition.<br />
<br />
{{Warning|You should only follow this step if you know what you are doing -- '''it can cause data loss and damage your partitions or MBR on the stick!'''}}<br />
<br />
{{Out of date|Grub-legacy is not available anymore and for [[GRUB2]] a 1-2MB gap between MBR and the beginning of other written data (e.g. first partition or LUKS-key) is needed for embedding GRUB2's {{ic|core.img}}. Information regarding GPT and/or UEFI combinations are required. GRUB2 has changed parsing configuration.}}<br />
<br />
If you have a bootloader installed on your drive you have to adjust the values. E.g. [[GRUB]] needs the first 16 sectors (actually, it depends on the type of the file system, so do not rely on this too much), so you would have to replace {{ic|seek<nowiki>=</nowiki>4}} with {{ic|seek<nowiki>=</nowiki>16}}; otherwise you would overwrite parts of your GRUB installation. When in doubt, take a look at the first 64 sectors of your drive and decide on your own where to place your key. <br />
<br />
''Optional''<br />
If you do not know if you have enough free space before the first partition, you can do<br />
dd if=/dev/usbstick of=64sectors bs=512 count=64 # gives you copy of your first 64 sectors<br />
hexcurse 64sectors # determine free space<br />
xxd 64sectors | less # alternative hex viewer<br />
<br />
Write your key to the disk:<br />
dd if=secretkey of=/dev/usbstick bs=512 seek=4<br />
<br />
If everything went fine you can now overwrite and delete your temporary secretkey as noted above.<br />
You should not simply use {{ic|rm}} as the keyfile would only be unlinked from your filesystem and be left physically intact.<br />
<br />
Now you have to add a kernel parameter in your {{ic|/boot/grub/menu.lst}} file (GRUB); it should look something like this:<br />
kernel /vmlinuz-linux cryptdevice=/dev/sda3:root root=/dev/mapper/root ro cryptkey=/dev/usb:2048:2048<br />
Format for the {{ic|cryptkey}} option:<br />
cryptkey=BLOCKDEVICE:OFFSET:SIZE<br />
{{ic|OFFSET}} and {{ic|SIZE}} match in this example, but this is just coincidence - they can differ (and often will). An other possible example could be<br />
kernel /vmlinuz-linux cryptdevice=/dev/sda3:root root=/dev/mapper/root ro cryptkey=/dev/usb:8192:2048<br />
That is all, reboot and have fun! And look if your partitions still work after that ;-).<br />
<br />
=== Encrypting the Swap partition ===<br />
<br />
==== Without suspend-to-disk support ====<br />
<br />
In systems where suspend to disk is not a desired feature, it is possible to create a swap file that will have a random master key with each boot. This is accomplished by using dm-crypt directly without LUKS extensions.<br />
<br />
The {{ic|/etc/crypttab}} is well commented and you can basically just uncomment the swap line and change <device> to a persistent symlink.<br />
<br />
{{hc|/etc/crypttab|# <name> <device> <password> <options><br />
# swap /dev/hdx4 /dev/urandom <nowiki>swap,cipher=aes-cbc-essiv:sha256,size=256</nowiki>}}<br />
<br />
Where:<br />
; <name>: Represents the name ({{ic|/dev/mapper/<name>}}) to list in /etc/fstab.<br />
; <device>: Should be the symlink to the actual partition's device file.<br />
; <password>: {{ic|/dev/urandom}} sets the dm-crypt master key to be randomized on every volume recreation.<br />
; <options>: The {{ic|swap}} option runs mkswap after cryptographic's are setup.<br />
<br />
{{Warning|You should use persistent block device naming (in example ID's) for <device> because if there are multiple hard drives installed in the system, their naming order (sda, sdb,...) can occasionally be scrambled upon boot and thus the swap would be created over a valuable file system, destroying its content.}}<br />
<br />
Persistent block device naming is implemented with simple symlinks. Using UUID's or filesystem-labels is not possible as plain dm-crypt writes only encrypted data without a persistent header like LUKS. If you are not familar with one of the directories under {{ic|/dev/disk/}} read on in the section on [[#Preparation for Persistent block device naming]]<br />
<br />
{{hc|#ls -l <nowiki>/dev/disk/*/* |</nowiki> grep sda2|<br />
lrwxrwxrwx 1 root root 10 Oct 12 16:54 /dev/disk/by-id/ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part2 -> ../../sda2}}<br />
<br />
Example line for the {{ic|/dev/sda2}} symlink from above:<br />
<br />
{{hc|/etc/crypttab|# <name> <device> <password> <options><br />
swap /dev/disk/by-id/ata-WDC_WD2500BEVT-22ZCT0_WD-WXE908VF0470-part2 /dev/urandom <nowiki>swap,cipher=aes-cbc-essiv:sha256,size=256</nowiki>}}<br />
<br />
This will map {{ic|/dev/sda2}} to {{ic|/dev/mapper/swap}} as a swap partition that can be added in {{ic|/etc/fstab}} like a normal swap.<br />
<br />
If the partition chosen for swap was previously a LUKS partition, crypttab will not overwrite the partition to create a swap partition. This is a safety measure to prevent data loss from accidental mis-identification of the swap partition in crypttab. In order to use such a partition the [[#Wipe_LUKS_header|LUKS header must be overwritten]] once.<br />
<br />
==== With suspend-to-disk support ====<br />
<br />
To be able to resume after suspending the computer to disk (hibernate), it is required to keep the swap filesystem intact. Therefore, it is required to have a pre-existent LUKS swap partition, which can be stored on the disk or input manually at startup. Because the resume takes place before {{ic|/etc/crypttab}} can be used, it is required to create a hook in {{ic|/etc/mkinitcpio.conf}} to open the swap LUKS device before resuming.<br />
<br />
If you want to use a partition which is currently used by the system, you have to disable it first:<br />
# swapoff /dev/<device><br />
<br />
Also make sure you remove any line in {{ic|/etc/crypttab}} pointing to this device.<br />
<br />
A simple way to realize encrypted swap with suspend-to-disk support is by using [[LVM]] ontop the encryption layer, so one encrypted partition can contain infinite filesystems (root, swap, home, ...). Follow the instructions on [[#Encrypting a LVM setup]].<br />
<br />
The following setup has the disadvantage of having to insert an additional passphrase for the swap partition manually on every boot.<br />
<br />
{{Warning|Do not use this setup with a key file. Please read about the issue reported [[Talk:System Encryption with LUKS for dm-crypt#Suspend to disk instructions are insecure|here]]}}<br />
<br />
To format the encrypted container for the swap partition, follow steps similar to those described in [[#Configuring LUKS]] above and create keyslot for a user-memorizable passphrase.<br />
<br />
Open the partition in {{ic|/dev/mapper}}:<br />
# cryptsetup luksOpen /dev/<device> swapDevice<br />
<br />
Create a swap filesystem inside the mapped partition:<br />
# mkswap /dev/mapper/swapDevice<br />
<br />
Now you have to create a hook to open the swap at boot time.<br />
<br />
* Create a hook file containing the open command:<br />
<br />
{{hc|/lib/initcpio/hooks/openswap|<nowiki><br />
# vim: set ft=sh:<br />
run_hook ()<br />
{<br />
cryptsetup luksOpen /dev/<device> swapDevice<br />
}<br />
</nowiki>}}<br />
<br />
{{Note|If swap is on a Solid State Disk (SSD) and Discard/TRIM is desired the option {{ic|--allow-discards}} has to get added to the cryptsetup line in the openswap hook above. See [[#Discard.2FTRIM_support_for_solid_state_disks_.28SSD.29|Discard/TRIM support for solid state disks (SSD)]] or [[SSD]] for more information on discard. Additionally you have to add the mount option 'discard' to your fstab entry for the swap device.''}}<br />
<br />
* Then create and edit the hook setup file:<br />
{{hc|/lib/initcpio/install/openswap|<nowiki><br />
# vim: set ft=sh:<br />
build ()<br />
{<br />
MODULES=""<br />
BINARIES=""<br />
FILES=""<br />
SCRIPT="openswap"<br />
}<br />
help ()<br />
{<br />
cat<<HELPEOF<br />
This opens the swap encrypted partition /dev/<device> in /dev/mapper/swapDevice<br />
HELPEOF<br />
}<br />
</nowiki>}}<br />
<br />
* Add the hook {{ic|openswap}} in the {{ic|HOOKS}} array in {{ic|/etc/mkinitcpio.conf}}, before {{ic|filesystem}} but after {{ic|encrypt}}. Do not forget to add the {{ic|resume}} hook after {{ic|openswap}}.<br />
<nowiki>HOOKS="... encrypt openswap resume filesystems ..."</nowiki><br />
* Regenerate the boot image:<br />
<br />
# mkinitcpio -p linux<br />
<br />
* Add the mapped partition to {{ic|/etc/fstab}} by adding the following line:<br />
/dev/mapper/swapDevice swap swap defaults 0 0<br />
<br />
* Set up your system to resume from {{ic|/dev/mapper/swapDevice}}. For example, if you use [[GRUB]] with kernel hibernation support, add {{ic|resume<nowiki>=</nowiki>/dev/mapper/swapDevice}} to the kernel line in {{ic|/boot/grub/menu.lst}}. A line with encrypted root and swap partitions can look like this:<br />
<br />
kernel /vmlinuz-linux cryptdevice=/dev/sda2:rootDevice root=/dev/mapper/rootDevice resume=/dev/mapper/swapDevice ro<br />
<br />
At boot time, the {{ic|openswap}} hook will open the swap partition so the kernel resume may use it. If you use special hooks for resuming from hibernation, make sure they are placed '''after''' {{ic|openswap}} in the {{ic|HOOKS}} array. Please note that because of initrd opening swap, there is no entry for swapDevice in {{ic|/etc/crypttab}} needed in this case.<br />
<br />
==== Using a swap file for suspend-to-disk support ====<br />
* Choose a mapped partition (e.g. {{ic|/dev/mapper/rootDevice}}) whose mounted filesystem (e.g. {{ic|/}}) contains enough free space to hold the entire contents of your system's RAM. For example, if your system has 4 GiB RAM, then you need at least that much free space on the mounted filesystem of your chosen mapped partition for the swap file.<br />
<br />
* [[HOW_TO:_Create_swap_file#Swap_file_creation | Create the swap file]] (e.g. {{ic|/swapfile}}) inside the mounted filesystem of your chosen mapped partition. Be sure to activate it with {{ic|swapon}} and also add it to your {{ic|/etc/fstab}} file afterward.<br />
<br />
* Set up your system to resume from your chosen mapped partition. For example, if you use [[GRUB]] with kernel hibernation support, add {{ic|resume<nowiki>=</nowiki>}}''your chosen mapped partition'' and {{ic|resume_offset<nowiki>=</nowiki>}}''see calculation command below'' to the kernel line in {{ic|/boot/grub/menu.lst}}. A line with encrypted root partition can look like this:<br />
<br />
kernel /vmlinuz-linux cryptdevice=/dev/sda2:rootDevice root=/dev/mapper/rootDevice resume=/dev/mapper/rootDevice resume_offset=123456789 ro<br />
<br />
You can calculate the {{ic|resume_offset}} of your swap file like this:<br />
<br />
# filefrag -v /swapfile | awk '{if($1==0){print $3}}'<br />
<br />
* Add the {{ic|resume}} hook to your {{ic|etc/mkinitcpio.conf}} file and [[Mkinitcpio#Image_creation_and_activation|rebuild the image]] afterward:<br />
<br />
HOOKS="... encrypt '''resume''' ... filesystems ..."<br />
<br />
* If you use a USB keyboard to enter your decryption password, then the {{ic|usbinput}} module '''must''' appear in front of the {{ic|encrypt}} hook, as shown below. Otherwise, you will not be able to boot your computer because you couldn't enter your decryption password to decrypt your Linux root partition!<br />
<br />
HOOKS="... '''usbinput''' encrypt ..."<br />
<br />
== Installing the system ==<br />
<br />
{{Note | Most of the installation can be carried out normally. However, there are a few areas where it is important to make certain selections. These are marked below.}}<br />
<br />
=== Prepare hard drive for Arch Install Scripts ===<br />
<br />
This assumes you want to install an encrypted system with the Arch Install Scripts, have created partitions for {{ic|/}} (e.g. {{ic|/dev/sdaX}}) and {{ic|/boot}} ({{ic|/dev/sdaY}}) at least, following the [[Installation_Guide|Installation Guide]] and deciding against [[LUKS#LVM:_Logical_Volume_Manager|using LVM]]. Prior to creating the partitions you have done a [[LUKS#Secure_erasure_of_the_hard_disk_drive|preparation]] of the disk for encryption according to your necessities (the necessary tools are on the installation-ISO). <br />
<br />
First check, if the blockdevice mapper {{ic|dm_mod}} is loaded with <br />
# lsmod | grep mod <br />
If one wants to use the default LUKS-cipher algorithm, there is no need to specify one for the luksFormat. At the time of writing the default is set to an AES variant with 256 bit key-length. With that a dm-crypt/LUKS blockdevice for the crypted root can be created <br />
# cryptsetup -y -v luksFormat /dev/sdaX<br />
opened<br />
# cryptsetup luksOpen /dev/sdaX cryptroot<br />
formatted with your desired filesystem<br />
# mkfs -t ext4 /dev/mapper/cryptroot<br />
and mounted<br />
# mount -t ext4 /dev/mapper/cryptroot /mnt<br />
<br />
At this point, just before installing the base system, it might be useful to check the mapping works as intended:<br />
# umount /mnt<br />
# cryptsetup luksClose cryptroot<br />
and mount it again to check.<br />
<br />
If you created a separate {{ic|/home}} partition, the steps have to be adapted and repeated for that.<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a crypted root. For a standard [[EFI|MBR/non-EFI]] {{ic|/boot}} partition that may be achieved by formatting<br />
# mkfs -t ext2 /dev/sdaY<br />
creating a mount-point for installation<br />
# mkdir /mnt/boot<br />
and mounting it<br />
# mount -t ext2 /dev/sdaY /mnt/boot<br />
<br />
That is basically what is necessary at this point before installing the base system with the [[Installation_Guide#Mount_the_partitions|Arch Install Scripts]]. Take care to install the bootloader to {{ic|/mnt/boot}} with the {{ic|pacstrap}} script. Additional configuration steps must be followed before booting the installed system.<br />
<br />
=== Configure initramfs ===<br />
One important point is to add the hooks relevant for your particular install in the correct order to {{ic|/etc/mkinitcpio.conf}}. The one you ''have'' to add when encrypting the root filesystem is {{ic|encrypt}}. A recommended hook for LUKS encrypted blockdevices is {{ic|shutdown}} to ensure controlled unmounting during system shutdown. Others needed, e.g. {{ic|keymap}}, should be clear from other manual steps you follow during the installation and further details in the following. For detailed information about initramfs configuration and available Hooks refer to [[Mkinitcpio#HOOKS]].<br />
<br />
{{Note|The {{ic|encrypt}} hook is only needed if your '''root''' partition is a ''LUKS'' partition (or a LUKS partition that needs to be mounted ''before'' root). The {{ic|encrypt}} hook is not needed for any other encrypted partitions (swap, for example). System initialization scripts ({{ic|/etc/rc.sysinit}} and {{ic|/etc/crypttab}} among others) take care of those.}}<br />
<br />
It is important that the {{ic|encrypt}} hook comes ''before'' the {{ic|filesystems}} hook, so make sure that your {{ic|HOOKS}} array looks something like this:<br />
{{hc|etc/mkinitcpio.conf|HOOKS<nowiki>=</nowiki>"(base udev) ... '''encrypt''' ... filesystems ..."}}<br />
<br />
If you need support for foreign keymaps for your encryption password, you have to specify the hook {{ic|keymap}} as well before {{ic|encrypt}}.<br />
<br />
If you have a USB keyboard, you will need the {{ic|usbinput}} hook. Without it, no USB keyboard will work in early userspace.<br />
<br />
If the encrypted root container has keyslots for [[#Storing_the_Key_File|keyfiles loaded from external usb devices]] or root itself is on usb storage the {{ic|usb}} hook is needed before encrypt.<br />
HOOKS="... '''usb''' encrypt ... filesystems ..."<br />
<br />
After you are done don't forget:<br />
mkinitcpio -p linux<br />
<br />
{{Deletion|Specific filesystem modules do not need to be listed as the {{ic|filesystems}} hook takes care of them.}}<br />
If your root partition is a ''LUKS'' partition, add the used filesystem to the {{ic|MODULES}} section.<br />
MODULES="... ext3 ext4 xfs ..."<br />
<br />
=== Kernel parameter configuration of the bootloader ===<br />
==== GRUB2 ====<br />
<br />
The article on GRUB2 gives a brief introduction and features [[GRUB2#Root_Encryption|a small section on configuration for system encryption]].<br />
<br />
The recommended way for configuring GRUB is {{ic|/etc/default/grub}} where the kernel line has to be adjusted so GRUB can pass to the kernel how to map the (encrypted) root device.<br />
<br />
The syntax for '''cryptdevice''' is:<br />
cryptdevice=<device>:<dmname><br />
; <device>: The path to the raw encrypted device. Usage of [[Persistent block device naming]] is advisable.<br />
; <dmname>: The name given to the device after decryption, will be available as {{ic|/dev/mapper/<dmname>}}.<br />
<br />
So if the encrypted root device is in example {{ic|/dev/sda2}} and the decrypted one should be mapped to {{ic|/dev/mapper/cryptroot}} the kernel line must look like:<br />
{{hc|/etc/default/grub|<nowiki>GRUB_CMDLINE_LINUX="cryptdevice=/dev/sda2:cryptroot"</nowiki>}}<br />
<br />
Depending on the setup other parameters are required as well:<br />
GRUB_CMDLINE_LINUX="cryptdevice=<device>:<dmname> root=<device> resume=<device> cryptkey=<device>:<fstype>:<path>"<br />
<br />
; root=<device>: The device file of the actual (decrypted) root filesystem. If the filesystem is formatted directly on the decrypted device file this will be {{ic|/dev/mapper/<dmname>}}. If LVM is in between sth. like {{ic|/dev/mapper/<volgroup>-<pvol>}} or {{ic|/dev/<volgroup>/<pvol>}} does the trick.<br />
; resume=<device>: The device file of the decrypted (swap) filesystem used for suspend2disk.<br />
; cryptkey=<nowiki><device>:<fstype>:<path></nowiki>: Required for reading a [[#Storing_the_Key_File|keyfile]] from a filesystem.<br />
<br />
The syntax for the optional '''cryptkey''' parameter is:<br />
<br />
cryptkey=<device>:<fstype>:<path><br />
<br />
; <device>: The raw block device where the key exists.<br />
; <fstype>: The filesystem type of <device> (or auto).<br />
; <path>: The absolute path of the keyfile within the device.<br />
<br />
{{Accuracy|Even if LVM is used it is bad practice to specify a false root device to the kernel. The rest is now already covered up above and maybe the whole paragraph should be a candidate for deletion?}}<br />
The device name your harddrive should be mapped to depends on your setup and configuration. If you are directly decrypting your root partition, the parameter {{ic|1=root=/dev/mapper/cryptroot}} will indicate the expected name. In case of [[LVM]] this name can be any arbitrary name, as LVM will parse all available devices if specified as the next hook.<br />
<br />
==== Syslinux ====<br />
The Article on Syslinux describes in [[Syslinux#Basic_Config|the basic config-section]] how to use LUKS for system encryption (added 2012):<br />
<br />
APPEND root=/dev/mapper/<name> cryptdevice=/dev/sda2:<name> ro<br />
<br />
{{Expansion|Backlinking from [[Syslinux]] should be done and more instruction for different setups instead of only duplicating stub content among 2 articles is required.}}<br />
<br />
==== GRUB Legacy ====<br />
{{Out of date|GRUB Legacy and LILO are dropped.}}<br />
'''[[GRUB Legacy]]:''' You have to make some small changes to the entries generated by the installer by replacing {{ic|/dev/mapper/root}} with {{ic|/dev/sda3}}. The important point to remember here is to use the same {{ic|cryptdevice}} name you assigned when you initially unlocked your device. In this example, the device name is {{ic|cryptroot}}; customize yours accordingly:<br />
<br />
# (0) Arch Linux<br />
title Arch Linux<br />
root (hd0,0)<br />
kernel /vmlinuz-linux cryptdevice=/dev/sda3:cryptroot root=/dev/mapper/cryptroot ro<br />
initrd /initramfs-linux.img<br />
<br />
For kernels older than 2.6.37, the syntax is:<br />
# (0) Arch Linux<br />
title Arch Linux<br />
root (hd0,0)<br />
kernel /vmlinuz26 root=/dev/sda3 ro<br />
initrd /kernel26.img<br />
<br />
==== LILO ====<br />
'''LILO:''' Edit the Arch Linux section in {{ic|/etc/lilo.conf}} and include a line for the {{ic|append}} option, over the initrd, with the {{ic|root<nowiki>=</nowiki>/dev/sda3}} parameter. The {{ic|append}} section makes the same kernel line as in GRUB. Also, you can omit the {{ic|root}} option above the {{ic|image}} option. The section looks like this:<br />
# Arch Linux lilo section<br />
image = /vmlinuz-linux<br />
# root = /dev/sda3<br />
label = Arch<br />
initrd = /initramfs-linux.img<br />
append = "root=/dev/sda3"<br />
read-only<br />
<br />
{{Note|If you want to use a USB flash drive with a keyfile, you have to append the {{ic|cryptkey}} option. See the corresponding section below.}}<br />
<br />
=== Fstab ===<br />
Further, double-check the {{ic|gen[[fstab]]}} scripts result for your {{ic|/dev/mapper/cryptroot}} and other mounts.<br />
<br />
=== AIF Instructions ===<br />
{{Delete|}}<br />
{{Out of date|AIF (Arch Installation Framework; referenced below also as {{ic|/arch/setup}}) does not exist anymore, GRUB Legacy is not available anymore}}<br />
==== Prepare hard drive for AIF ====<br />
<br />
Now that {{ic|/dev/mapper/root}} and {{ic|/dev/mapper/home}} are in place, we can enter the regular Arch setup script to install the system into the encrypted volumes.<br />
# /arch/setup<br />
Skip the Partitioning and Auto-Prepare steps and go straight to manual configuration.<br />
Instead of choosing the hardware devices ({{ic|/dev/sdaX}}) directly, you have to select the mapper devices created above.<br />
Choose {{ic|/dev/mapper/root}} for your root and {{ic|/dev/mapper/home}} as {{ic|/home}} partition respectively and format them with any filesystem you like.<br />
The same is valid for a swap partition which is set up like the {{ic|/home}} partition. Make sure you mount {{ic|/dev/sda1}} as the {{ic|/boot}} partition, or else the installer will not properly set up the bootloader.<br />
<br />
==== Select and Install packages ====<br />
Select and install the packages as usual: the base package contains all required programs.<br />
<br />
==== Exit Install ====<br />
Now that the install is finished the only thing left to do is add entries to the {{ic|/etc/crypttab}} file so you do not have to enter the passphrase for all encrypted partitions. This works only for non-root partitions e.g. {{ic|/home}}, swap, etc.<br />
# vi /mnt/etc/crypttab<br />
<br />
Add one of the following for the {{ic|/home}} partition.<br />
{{Note|Using a passphrase to decrypt LUKS partitions automatically from {{ic|/etc/crypttab}} is deprecated: see http://www.mail-archive.com/arch-projects@archlinux.org/msg02115.html}}<br />
home /dev/sda5 /etc/mypassword1<br />
<br />
You can also use a keyfile instead of a passphrase. If not already done, create a keyfile and add the key to the corresponding LUKS partition as described [[#Adding_Additional_Passphrases_or_Keyfiles_to_a_LUKS_Encrypted_Partition|above]].<br />
Then add the following information to the {{ic|/etc/crypttab}} file for automounting:<br />
home /dev/sda5 /path/of/your/keyfile<br />
<br />
If you used a USB device to store your keyfile, you should have something like this:<br />
home /dev/sda5 /dev/sd*1/keyfile<br />
<br />
Or if the keyfile was stored in the MBR, it should be like this:<br />
home /dev/sda5 /dev/sd*:2048:2048<br />
<br />
{{Box BLUE|Note:|When reading the keyfile from the MBR it should be {{ic|/dev/sdb}} not {{ic|/dev/sdb1}} but if the key is in the filesystem it should still be {{ic|/dev/sdb1}}.}}<br />
<br />
After rebooting you should now be presented with the text<br />
A password is required to access the root filesystem:<br />
followed by a prompt for a LUKS password. Type it in and everything should boot.<br />
Once you have logged in, have a look at your mounted partitions by typing {{ic|mount}}. You should have {{ic|/dev/mapper/root}} mounted at {{ic|/}} and, if you set up a separate encrypted home partition, {{ic|/dev/mapper/home}} mounted at {{ic|/home}}. If you set up encrypted swap, {{ic|swapon -s}} should have {{ic|/dev/mapper/swap}} listed as your swap partition.<br />
<br />
{{Note|Eventually the text prompting for the password is mixed up with other boot messages. So the boot process may seem frozen at first glance, but it is not, simply enter your password and press {{keypress|Enter}}.}}<br />
<br />
== Remote unlocking of the root (or other) partition ==<br />
If you want to be able to reboot a fully LUKS-encrypted system remotely, or start it with a Wake-on-LAN service, you will need a way to enter a passphrase for the root partition/volume at startup. This can be achieved by running the {{ic|net}} hook along with an [[SSH]] server in initrd. Install the {{AUR|dropbear_initrd_encrypt}} package from the [[Arch User Repository|AUR]] and follow the post-installation instructions. Replace the {{ic|encrypt}} hook with {{ic|dropbear encryptssh}} in {{ic|/etc/mkinitcpio.conf}}. Put the {{ic|net}} hook early in the HOOKS array if your DHCP server takes a long time to lease IP addresses.<br />
<br />
If you would simply like a nice solution to mount other encrypted partitions (such as {{ic|/home}})remotely, you may want to look at [https://bbs.archlinux.org/viewtopic.php?pid=880484 this forum thread].<br />
<br />
{{Note|Acutally trim will not work with this script because it is not yet updated to the latest encrypt hook, so it is not able to parse {{ic|-–allow-discards}} from {{ic|/boot/grub/menu.lst}}. (Version: dropbear_initrd_encrypt 0.8-16). You won't notice any error when using online discard, but you see an error when you try to use {{ic|fstrim}}.For a temporary solution just add {{ic|-–allow-discards}} to every cryptsetup line of {{ic|/lib/initcpio/install/dropbear}}(1 line) and {{ic|/lib/initcpio/hooks/encryptssh}}(3 lines)}}<br />
<br />
== Backup the cryptheader ==<br />
If the header of your encrypted partition gets destroyed, you will not be able to decrypt your data. It is just as much as a dilemma as forgetting the passphrase or damaging a key-file used to unlock the partition. A damage may occur by your own fault while re-partitioning the disk later or by third-party programs misinterpreting the partition table.<br />
<br />
Therefore, having a backup of the headers and storing them on another disk might be a good idea.<br />
<br />
'''Attention:''' Many people recommend NOT backing up the cryptheader, but even so it's a single point of failure!<br />
In short, the problem is that LUKS is not aware of the duplicated cryptheader, which contains the master key which is used to encrypt all files on your partition. Of course this master key is encrypted with your passphrases or keyfiles.<br />
But if one of those gets compromised and you want to revoke it you have to do this on all copies of the cryptheader!<br />
I.e. if someone has got your cryptheader and one of your keys he can decrypt the master key and access all your data.<br />
Of course the same is true for all backups you create of your partions.<br />
So you decide if you are one of those paranoids brave enough to go without a backup for the sake of security or not.<br />
See also the [http://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions#6._Backup_and_Data_Recovery| LUKS FAQ] for further details on this.<br />
<br />
=== Backup ===<br />
==== Using cryptsetup ====<br />
Cryptsetups {{ic|luksHeaderBackup}} action stores a binary backup of the LUKS header and keyslot area:<br />
# cryptsetup luksHeaderBackup /dev/<device> --header-backup-file /mnt/backup/<file>.img<br />
where <device> is the partition containing the LUKS volume.<br />
<br />
{{Note|Using {{ic|-}} as header backup file writes to a file named {{ic|-}}.}}<br />
<br />
{{Tip|You can also back up the header into a tmpfs/ramfs and encrypt it in example with gpg before writing it to a physical device by executing the following commands.}}<br />
{{bc|# mkdir /root/<tmp><br />
# mount tmpfs /root/<tmp> -t tmpfs -o nouser,nosuid,<nowiki>size=32m</nowiki><br />
# cryptsetup luksHeaderBackup /dev/<device> --header-backup-file /root/<tmp>/<file>.img<br />
# gpg2 --recipient <User ID> --encrypt /root/<tmp>/<file>.img <br />
# cp /root/<tmp>/<file>.img.gpg /mnt/backup/<br />
# umount /root/<tmp>}}<br />
<br />
==== Manually ====<br />
{{Merge|#Wipe LUKS header|Calculating the header size should get expanded there and linked by few simple sentences from here.}}<br />
<br />
First you have to find out the payload offset of the crypted partition:<br />
{{hc|# cryptsetup luksDump /dev/<device> <nowiki>|</nowiki> grep "Payload offset"|<br />
Payload offset: 4040}}<br />
<br />
{{Accuracy|The Header size is now aligned to 1MB multiples for better block size alignment to hardware geometry. For a 1MB Header this is 2050 (or 2048?) Blocks of 512 Bytes. However Payload offset will be something like 4096 (4MB) or more.}}<br />
<br />
Now that you know the value, you can backup the header with a simple dd command:<br />
dd if=/dev/<device> of=/path/to/<file>.img bs=512 count=4040<br />
<br />
=== Restore ===<br />
Be careful before restore: make sure that you chose the right partition (again replace sdaX with the corresponding partition).<br />
Restoring the wrong header or restoring to an unencrypted partition will cause data loss.<br />
<br />
==== Using cryptsetup ====<br />
Or you can use the luksHeaderRestore command:<br />
cryptsetup luksHeaderRestore /dev/sdaX --header-backup-file ./backup.img<br />
<br />
'''Note:''' All the keyslot areas are overwritten; only active keyslots from the backup file are available after issuing this command.<br />
<br />
==== Manually ====<br />
Again, you will need to the same values as when backing up:<br />
dd if=./backup.img of=/dev/sdX bs=512 count=4040<br />
<br />
== Encrypting a loopback filesystem ==<br />
''[This paragraph has been merged from another page; its consistency with the other paragraphs should be improved]''<br />
<br />
=== Preparation and mapping ===<br />
First, start by creating an encrypted container!<br />
<br />
dd if=/dev/urandom of=/bigsecret bs=1M count=10<br />
<br />
This will create the file {{ic|bigsecret}} with a size of 10 megabytes.<br />
<br />
losetup /dev/loop0 /bigsecret<br />
<br />
This will create the device node {{ic|/dev/loop0}}, so that we can mount/use our container.<br />
<br />
{{Note|If it gives you the error {{ic|/dev/loop0: No such file or directory}}, you need to first load the kernel module with {{ic|modprobe loop}}. These days (Kernel 3.2) loop devices are created on demand. Ask for a new loop device with {{ic|losetup -f}}.}}<br />
<br />
cryptsetup luksFormat /dev/loop0<br />
<br />
This will ask you for a password for your new container file.<br />
<br />
{{Note|If you get an error like {{ic|Command failed: Failed to setup dm-crypt key mapping. Check kernel for support for the aes-cbc-essiv:sha256 cipher spec and verify that /dev/loop0 contains at least 133 sectors|}}, then run {{ic|modprobe dm-mod}}.}}<br />
<br />
cryptsetup luksOpen /dev/loop0 secret<br />
<br />
The encrypted container is now available through the device file {{ic|/dev/mapper/secret}}.<br />
Now we are able to create a partition in the container:<br />
<br />
mkfs.ext2 /dev/mapper/secret<br />
<br />
and mount it...<br />
<br />
mkdir /mnt/secret<br />
mount -t ext2 /dev/mapper/secret /mnt/secret<br />
<br />
We can now use the container as if it was a normal partition!<br />
To unmount the container:<br />
<br />
umount /mnt/secret<br />
cryptsetup luksClose secret<br />
losetup -d /dev/loop0 # free the loopdevice.<br />
<br />
so, if you want to mount the container again, you just apply the following commands:<br />
<br />
losetup /dev/loop0 /bigsecret<br />
cryptsetup luksOpen /dev/loop0 secret<br />
mount -t ext2 /dev/mapper/secret /mnt/secret<br />
<br />
=== Encrypt using a key-file ===<br />
Let us first generate a 2048 byte random keyfile:<br />
<br />
dd if=/dev/urandom of=keyfile bs=1k count=2<br />
<br />
We can now format our container using this key<br />
<br />
cryptsetup luksFormat /dev/loop0 keyfile<br />
<br />
or our partition : <br />
<br />
cryptsetup luksFormat /dev/hda2 keyfile<br />
<br />
Once formatted, we can now open the LUKS device using the key:<br />
<br />
cryptsetup -d keyfile luksOpen /dev/loop0 container<br />
<br />
You can now like before format the device {{ic|/dev/mapper/container}} with your favorite filesystem and then mount it just as easily.<br />
<br />
The keyfile is now the only key to your file. I personally advise encrypting your keyfile using your private GPG key and storing an off-site secured copy of the file.<br />
<br />
=== Resizing the loopback filesystem ===<br />
First we should unmount the encrypted container:<br />
umount /mnt/secret<br />
cryptsetup luksClose secret<br />
losetup -d /dev/loop0 # free the loopdevice.<br />
<br />
After this we need to expand our container file with the size of the data we want to add:<br />
<br />
dd if=/dev/urandom bs=1M count=1024 | cat - >> /bigsecret<br />
<br />
Be careful to really use TWO {{ic|>}}, or you will override your current container!<br />
<br />
You could use {{ic|/dev/zero}} instead of {{ic|/dev/urandom}} to significantly speed up the process, but with {{ic|/dev/zero}} your encrypted filesystems will ''not be as secure''. (A better option to create random data quicker than {{ic|/dev/urandom}} is {{ic|frandom}} [https://aur.archlinux.org/packages.php?ID=9869], available from the [[AUR]]).<br />
<br />
Now we have to map the container to the loop device:<br />
losetup /dev/loop0 /bigsecret<br />
cryptsetup luksOpen /dev/loop0 secret<br />
After this we will resize the encrypted part of the container to the maximum size of the container file:<br />
cryptsetup resize secret<br />
Finally, we can resize the filesystem. Here is an example for ext2/3/4:<br />
e2fsck -f /dev/mapper/secret # Just doing a filesystem check, because it's a bad idea to resize a broken fs<br />
resize2fs /dev/mapper/secret<br />
You can now mount your container again:<br />
mount /dev/mapper/secret /mnt/secret<br />
<br />
== Encrypting a LVM setup ==<br />
{{Merge|#LVM:_Logical_Volume_Manager|Device mapper stacking is already explained there. Duplicates should get merged one way (whereto?) and linked then. Maybe keeping theory there and practice here?}}<br />
<br />
It's really easy to use encryption with [[LVM]]. If you do not know how to set up LVM, then read [[Installing with Software RAID or LVM]].<br />
<br />
'''LVM on LUKS'''<br />
<br />
The easiest and best method is to set up LVM on top of the encrypted partition instead of the other way round. This link here is easy to follow and explains everything: [http://www.pindarsign.de/webblog/?p=767 Arch Linux: LVM on top of an encrypted partition]<br />
<br />
The most important thing in setting LVM on '''top''' of encryption is to [[#Configure initramfs|configure the initramfs]] for running the {{ic|encrypt}} hook '''before''' the {{ic|lvm2}} hook (and those two before the {{ic|filesystems}} hook). <br />
<br />
'''LUKS on LVM'''<br />
<br />
To use encryption on top of LVM, you have to first set up your LVM volumes and then use them as the base for the encrypted partitions. That means, in short, that you have to set up LVM first. Then follow this guide, but replace all occurrences of {{ic|/dev/sdXy}} in the guide with its LVM counterpart. (E.g.: {{ic|/dev/sda5}} -> {{ic|/dev/<volume group name>/home}}). This is used to setup partitions (inside the LVM) which can be unlocked separately or a mixture of encrypted and non-encrypted partitions. <br />
<br />
For encrypted partitions inside an LVM, the LVM-hook has to run first, before the respective encrypted logical volumes can be unlocked. So for this add the {{ic|encrypt}} hook in {{ic|/etc/mkinitcpio.conf}} '''after''' the {{ic|lvm2}} hook, if you chose to set up encrypted partitions on '''top''' of LVM. Also remember to change {{ic|USELVM}} in {{ic|/etc/rc.conf}} to {{ic|"yes"}}. <br />
<br />
=== LVM with Arch Linux Installer (>2009.08 <2012.07.15) ===<br />
{{Out of date|As of the [http://www.archlinux.org/news/install-media-20120715-released/ 2012.07.15 installation media release] the AIF (Arch Installation Framework) and grub-legacy are dropped. These outdated instructions still give the backbones to understanding what to do.}}<br />
<br />
In between Arch Linux installation media release 2009.08 and 2012.07.15 LVM and dm_crypt had been supported by the installer out of the box.<br />
This made it very easy to configure a system for [[LVM]] on dm-crypt or vice versa.<br />
Actually the configuration is done exactly as without LVM: see the [[#Arch Linux Installer (>2009.08 <2012.07.15)|corresponding]] section above. It differs only in two aspects.<br />
<br />
==== The partition and filesystem choice ====<br />
Create a small, unencrypted boot partition and use the remaining space for a single partition which can later be split up into multiple logic volumes by [[LVM]].<br />
<br />
For a LVM-on-dm-crypt system set up the filesystems and mounting points for example like this:<br />
/dev/sda1 raw->ext2;yes;/boot;no_opts;no_label;no_params<br />
/dev/sda2 raw->dm_crypt;yes;no_mountpoint;no_opts;sda2crypt;-c_aes-xts-plain_-y_-s_512<br />
/dev/mapper/sda2crypt dm_crypt->lvm-vg;yes;no_mountpoint;no_opts;no_label;no_params<br />
/dev/mapper/sda2crypt+ lvm-pv->lvm-vg;yes;no_mountpoint;no_opts;cryptpool;no_params<br />
/dev/mapper/cryptpool lvm-vg(cryptpool)->lvm-lv;yes;no_mountpoint;no_opts;cryptroot;10000M|lvm-lv;yes;no_mountpoint;no_opts;crypthome;20000M<br />
/dev/mapper/cryptpool-cryptroot lvm-lv(cryptroot)->ext3;yes;/;no_opts;cryptroot;no_params<br />
/dev/mapper/cryptpool-crypthome lvm-lv(crypthome)->ext3;yes;/home;no_opts;cryptroot;no_params<br />
<br />
==== The configuration stage ====<br />
* In {{ic|/etc/mkinitcpio.conf}} add the {{ic|encrypt}} hook '''before''' the {{ic|lvm2}} hook in the {{ic|HOOKS}} array, if you set up LVM on top of the encrypted partition.<br />
<br />
That is it for the LVM & dm_crypt specific part. The rest is done as usual.<br />
<br />
{{Accuracy|The {{ic|lvm2}} hook activates the (encrypted) root volume group long before sysvinit (or systemd) can run from there. Letting sysvinit later run a second LVM activation in addition serves no purpose. Read [[LVM#Configure system]]. However this error is duplicated within the [[#Encrypting a LVM setup]] section.}}<br />
* In {{ic|/etc/rc.conf}} set {{ic|USELVM}} to {{ic|"yes"}}.<br />
<br />
=== Applying this to a non-root partition ===<br />
You might get tempted to apply all this fancy stuff to a non-root partition. Arch does not support this out of the box, however, you can easily change the cryptdev and cryptname values in {{ic|/lib/initcpio/hooks/encrypt}} (the first one to your {{ic|/dev/sd*}} partition, the second to the name you want to attribute). That should be enough.<br />
<br />
The big advantage is you can have everything automated, while setting up {{ic|/etc/crypttab}} with an external key file (i.e. the keyfile is not on any internal hard drive partition) can be a pain - you need to make sure the USB/FireWire/... device gets mounted before the encrypted partition, which means you have to change the order of {{ic|/etc/fstab}} (at least).<br />
<br />
Of course, if the {{Pkg|cryptsetup}} package gets upgraded, you will have to change this script again. However, this solution is to be preferred over hacking {{ic|/etc/rc.sysinit}} or similar files. Unlike {{ic|/etc/crypttab}}, only one partition is supported, but with some further hacking one should be able to have multiple partitions unlocked.<br />
<br />
If you want to do this on a software RAID partition, there is one more thing you need to do. Just setting the {{ic|/dev/mdX}} device in {{ic|/lib/initcpio/hooks/encrypt}} is not enough; the {{ic|encrypt}} hook will fail to find the key for some reason, and not prompt for a passphrase either. It looks like the RAID devices are not brought up until after the {{ic|encrypt}} hook is run. You can solve this by putting the RAID array in {{ic|/boot/grub/menu.lst}}, like <br />
kernel /boot/vmlinuz-linux md=1,/dev/hda5,/dev/hdb5<br />
<br />
If you set up your root partition as a RAID, you will notice the similarities with that setup ;-). [[GRUB]] can handle multiple array definitions just fine:<br />
kernel /boot/vmlinuz-linux root=/dev/md0 ro md=0,/dev/sda1,/dev/sdb1 md=1,/dev/sda5,/dev/sdb5,/dev/sdc5<br />
<br />
=== LVM and dm-crypt manually (short version) ===<br />
<br />
==== Notes ====<br />
If you are smart enough for this, you will be smart enough to ignore/replace LVM-specific things if you do not want to use LVM.<br />
<br />
{{Note|This brief uses reiserfs for some of the partitions, so change this accordingly if you want to use a more "normal" file system, like ext4.}}<br />
<br />
==== Partitioning scheme ====<br />
{{ic|/dev/sda1}} -> {{ic|/boot}}<br />
{{ic|/dev/sda2}} -> LVM<br />
<br />
==== The commands ====<br />
cryptsetup -d /dev/random -c aes-xts-plain -s 512 create lvm /dev/sda2<br />
dd if=/dev/urandom of=/dev/mapper/lvm<br />
cryptsetup remove lvm<br />
lvm pvcreate /dev/sda2<br />
lvm vgcreate lvm /dev/sda2<br />
lvm lvcreate -L 10G -n root lvm<br />
lvm lvcreate -L 500M -n swap lvm<br />
lvm lvcreate -L 500M -n tmp lvm<br />
lvm lvcreate -l 100%FREE -n home lvm<br />
cryptsetup luksFormat -c aes-xts-plain -s 512 /dev/lvm/root<br />
cryptsetup luksOpen /dev/lvm/root root<br />
mkreiserfs /dev/mapper/root<br />
mount /dev/mapper/root /mnt<br />
dd if=/dev/zero of=/dev/sda1 bs=1M<br />
mkreiserfs /dev/sda1<br />
mkdir /mnt/boot<br />
mount /dev/sda1 /mnt/boot<br />
mkdir -p -m 700 /mnt/etc/luks-keys<br />
dd if=/dev/random of=/mnt/etc/luks-keys/home bs=1 count=256<br />
<br />
==== Install Arch Linux ====<br />
Run {{ic|/arch/setup}}<br />
<br />
==== Configuration ====<br />
<br />
===== /etc/rc.conf =====<br />
Change {{ic|USELVM<nowiki>=</nowiki>"no"}} to {{ic|USELVM<nowiki>=</nowiki>"yes"}}.<br />
<br />
===== /etc/mkinitcpio.conf =====<br />
Put {{ic|lvm2}} and {{ic|encrypt}} (in that order) before {{ic|filesystems}} in the {{ic|HOOKS}} array. Again, note that you are setting encryption on '''top''' of LVM.)<br />
<br />
if you want install the system on a usb stick, you need to put {{ic|usb}} just after {{ic|udev}}.<br />
<br />
===== /boot/grub/menu.lst =====<br />
Change {{ic|root<nowiki>=</nowiki>/dev/hda3}} to {{ic|root<nowiki>=</nowiki>/dev/lvm/root}}.<br />
<br />
For kernel >= 2.6.30, you should change {{ic|root<nowiki>=</nowiki>/dev/hda3}} to the following:<br />
cryptdevice=/dev/lvm/root:root root=/dev/mapper/root<br />
<br />
if you want install the system on a usb stick, you need to add {{ic|lvmdelay<nowiki>=</nowiki>/dev/mapper/lvm-root}}<br />
<br />
===== /etc/fstab =====<br />
/dev/mapper/root / reiserfs defaults 0 1<br />
/dev/sda1 /boot reiserfs defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
<br />
===== /etc/crypttab =====<br />
{{Accuracy|/dev/urandom needs dd count and skip paramters. |section=Specifying_skip_and_count_in_.2Fetc.2Fcrypttab_for_.2Ftmp}}<br />
<br />
swap /dev/lvm/swap SWAP -c aes-xts-plain -h whirlpool -s 512<br />
tmp /dev/lvm/tmp /dev/urandom -c aes-xts-plain -s 512<br />
<br />
==== After rebooting ====<br />
<br />
===== The commands =====<br />
cryptsetup luksFormat -c aes-xts-plain -s 512 /dev/lvm/home /etc/luks-keys/home<br />
cryptsetup luksOpen -d /etc/luks-keys/home /dev/lvm/home home<br />
mkreiserfs /dev/mapper/home<br />
mount /dev/mapper/home /home<br />
<br />
===== /etc/crypttab =====<br />
home /dev/lvm/home /etc/luks-keys/home<br />
<br />
===== /etc/fstab =====<br />
/dev/mapper/home /home reiserfs defaults 0 0<br />
<br />
=== / on LVM on LUKS ===<br />
Make sure your kernel command line looks like this:<br />
root=/dev/mapper/<volume-group>-<logical-volume> cryptdevice=/dev/<luks-part>:<volume-group><br />
For example:<br />
root=/dev/mapper/vg-arch cryptdevice=/dev/sda4:vg<br />
<br />
Or like this:<br />
cryptdevice=/dev/<volume-group>/<logical-volume>:root root=/dev/mapper/root<br />
<br />
==Using GPG or OpenSSL Encrypted Keyfiles==<br />
The following forum posts give instructions to use two factor authentication, gpg or openssl encrypted keyfiles, instead of a plaintext keyfile described earlier in this wiki article [https://bbs.archlinux.org/viewtopic.php?id=120243 System Encryption using LUKS with GPG encrypted keys]:<br />
* GnuPG: [https://bbs.archlinux.org/viewtopic.php?pid=943338#p943338 Post regarding GPG encrypted keys] This post has the generic instructions.<br />
* OpenSSL: [https://bbs.archlinux.org/viewtopic.php?pid=947805#p947805 Post regarding OpenSSL encrypted keys] This post only has the {{ic|ssldec}} hooks.<br />
<br />
Note that:<br />
* You can follow the above instructions with only two primary partitions one boot partition <br />
(required because of LVM), and one primary LVM partition. Within the LVM partition you can have <br />
as many partitions as you need, but most importantly it should contain at least root, swap, and <br />
home logical volume partitions. This has the added benefit of having only one keyfile for all <br />
your partitions, and having the ability to hibernate your computer (suspend to disk) where the <br />
swap partition is encrypted. If you decide to do so your hooks in {{ic|/etc/mkinitcpio.conf}} <br />
should look like<br />
{{ic|HOOKS&#61;" ... usb usbinput (etwo or ssldec) encrypt(if using openssl) lvm2 resume ... "}}<br />
and you should add to your {{ic|kernel}} line(if using grub, {{ic|/boot/grub/menu.lst}}) or <br />
{{ic|GRUB_CMD_LINE}}(if using grub2, {{ic|/etc/default/grub}}):<br />
{{ic|"resume&#61;/dev/mapper/<VolumeGroupName>-<LVNameOfSwap>"}}<br />
* If you need to temporarily store the unecrypted keyfile somewhere, do not store them on an <br />
unencrytped disk. Even better make sure to store them to RAM such as {{ic|/dev/shm}}.<br />
* If you want to use a GPG encrypted keyfile, you need to use a statically compiled GnuPG version 1.4 or you could edit the hooks and use this AUR package [https://aur.archlinux.org/packages.php?ID=58030 gnupg1]<br />
* It is possible that an update to OpenSSL could break the custom {{ic|ssldec}} mentioned in the second forum post.<br />
<br />
==Securing the unencrypted boot partition==<br />
Referring to an article from the ct-magazine (Issue 3/12, page 146, 01.16.2012 http://www.heise.de/ct/inhalt/2012/03/6/) the following script checks all files under {{ic|/boot}} for changes of SHA-1 hash, inode and occupied blocks on the hard drive. It also checks the MBR.<br />
<br />
The script with installation instructions is available here: ftp://ftp.heise.de/pub/ct/listings/1203-146.zip (Author: Juergen Schmidt, ju at heisec.de; License: GPLv2). There is also an AUR package: {{AUR|chkboot}}<br />
<br />
After installation:<br />
* For classical sysvinit: add {{ic|/usr/local/bin/chkboot.sh &}} to your {{ic|/etc/rc.local}}<br />
* For systemd: add a service file and enable the service: [[systemd]]. The service file might look like:<br />
[Unit]<br />
Description=Check that boot is what we want<br />
<br />
[Service]<br />
Type=oneshot<br />
ExecStart=/usr/local/bin/chkboot.sh<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
There is a small caveat for systemd: At the time of writing the original {{ic|chkboot.sh}} script provided contains an empty space at the beginning of {{ic|<u> </u>#!/bin/bash}} which has to be removed for the service to start successfully.<br />
<br />
As {{ic|/usr/local/bin/chkboot_user.sh}} need to be excuted after login, add it to the autostart (e.g. under KDE -> System Settings -> Startup and Shutdown -> Autostart; Gnome3: gnome-session-properties). <br />
<br />
With Arch Linux changes to {{ic|/boot}} are pretty frequent, for example by new kernels rolling-in. Therefore it may be helpful to use the scripts with every full system update. One way to do so: <br />
<br />
#!/bin/bash<br />
#<br />
# Note: Insert your <user> and execute it with sudo for pacman & chkboot to work automagically<br />
#<br />
echo "Pacman update [1] Quickcheck before updating" & <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user> <br />
/usr/local/bin/chkboot.sh<br />
sync # sync disks with any results <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user> <br />
echo "Pacman update [2] Syncing repos for pacman" <br />
pacman -Syu<br />
/usr/local/bin/chkboot.sh<br />
sync <br />
sudo -u <user> /usr/local/bin/chkboot_user.sh # insert your logged on <user><br />
echo "Pacman update [3] All done, let's roll on ..."<br />
<br />
== Automount user homes on login ==<br />
See [[Pam mount]].<br />
<br />
== Resources ==<br />
* [http://code.google.com/p/cryptsetup/wiki/FrequentlyAskedQuestions cryptsetup FAQ] - The main and foremost help resource, directly from the developers.<br />
* [http://www.freeotfe.org/ FreeOTFE] - Supports unlocking LUKS encrypted volumes in Microsoft Windows.<br />
<br />
<br />
{{Out of date|Explained separately for each link beneath.}}<br />
* [http://vimeo.com/40694871 Arch cryptsetup example video] - A HowTo video on setting up an encrypted Arch system from scratch. The video still shows an installation with AIF, which is at the time of writing deprecated / not developed further. The important partitioning and cryptsetup are shown outside AIF though.<br />
* [http://yannickloth.be/blog/2010/08/01/installing-archlinux-with-software-raid1-encrypted-filesystem-and-lvm2/ Install Arch Linux on top of RAID1, LVM2, and encrypted partitions] - The HowTo instructs to make a full Fedora 13 Install only to set up the mapping. Then legacy AIF is used.</div>Piratejon