https://wiki.archlinux.org/api.php?action=feedcontributions&user=Chippey5&feedformat=atomArchWiki - User contributions [en]2024-03-29T11:29:22ZUser contributionsMediaWiki 1.41.0https://wiki.archlinux.org/index.php?title=Talk:WireGuard&diff=605991Talk:WireGuard2020-04-13T08:33:48Z<p>Chippey5: Added a new talk section as my results differ from the results a section implies a configuration does.</p>
<hr />
<div>== systemd-networkd-wait-online.service needed? ==<br />
<br />
{{ic|wq-quick@.service}} already contains {{ic|1=After=network-online.target}}. Enabling the wait online service causes the whole boot process to pause while waiting for a network connection and can dramatically increase boot times.<br />
{{Unsigned|03:54, 3 May 2018 (UTC)|Smasher816}}<br />
<br />
: I suspect the long network wait times might be caused by a lack of entropy rather than the target unit. Recommend [[rng-tools]] or [[haveged]]. [[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 12:09, 17 November 2018 (UTC)<br />
<br />
:: [[systemd-networkd]] has a timeout of 2 minutes for {{ic|systemd-networkd-wait-online}}. See this GitHub issue: https://github.com/systemd/systemd/issues/6441 (especially [https://github.com/systemd/systemd/issues/6441#issuecomment-418592758 this comment]). I've had to explicitly tell [[systemd-networkd]] to ignore all links on one of my systems (with {{ic|1=RequireForOnline=no}}), because it seems to wait for ''all'' devices to be online, not ''one'' of them. [[User:Aude|Aude]] ([[User talk:Aude|talk]]) 17:40, 17 November 2018 (UTC)<br />
<br />
::: Just a guess based on some delays with a headless box. For some other use cases (wpa_supplicant on a raspberry pi), I needed to use an override as well. [[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 19:33, 17 November 2018 (UTC).<br />
{{hc|/etc/systemd/system/systemd-networkd-wait-online.service.d/override.conf|2=<br />
[Service]<br />
ExecStart=<br />
ExecStart=/usr/lib/systemd/systemd-networkd-wait-online --ignore eth0<br />
}}<br />
<br />
:::: Yeah, that makes sense. I did an error and made the reply to your comment [[User:Graysky|Graysky]], but it was supposed to be a reply to the original poster. Sorry for the confusion. [[User:Aude|Aude]] ([[User talk:Aude|talk]]) 22:05, 17 November 2018 (UTC)<br />
<br />
== DNS troubleshoot ==<br />
<br />
Until a proper NM plugin is released, weird interactions are going to occur between Wireguard and NM. Typically, if you create a tunnel and NM touches DNS for whatever reason (lease timeout, reconnection, etc.) I loose my connection.<br />
<br />
I specifically focused on {{ic|systemd-resolved}} because I find the approach much saner than the resolvconf mess. It is also supported by NM and not really "broadly" documented elsewhere.<br />
{{Unsigned|10:52, 15 September 2018 (UTC)|Gdonval}}<br />
<br />
I'm also facing this issue after networkmanager upgrade. using wg-quick interface is up and running but after a minute it simply stops working. Problem is networkmanager changing dns lease.. I tried all possible solutions but with no results. [[User:Mohit310|Mohit310]] ([[User talk:Mohit310|talk]]) 01:53, 6 April 2019 (UTC)<br />
<br />
== Move `Endpoint with changing IP` to `Tips & Tricks` ==<br />
<br />
I can't justify it being under `Raw usage` as it's only a problem if you reference the server with a domain. I think it can be moved to the tips and tricks section.<br />
[[User:Foxboron|Foxboron]] ([[User talk:Foxboron|talk]]) 13:13, 16 December 2018 (UTC)<br />
<br />
: No objections. [[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 14:07, 16 December 2018 (UTC)<br />
<br />
: Hey, thank you for your feedback. When I contributed this section I was unsure where I should put it, but I figured its critical enough to include it under the "Usage" section. Why can't you justify this being under "Usage", I think "server with a domain" is a pretty trivial configuration? systemd-networkd examples aren't exactly "Raw usage" either. Also I have just noted that VPN-Server [https://wiki.archlinux.org/index.php/WireGuard#Client_config Wireguard#Client_config] has exactly the described issue my section covers. Note: I'm happy to move it to "Tips & Tricks", I'm just fairly new to archwiki and I'm trying to get a better understanding of common practices here. -- [[User:Insecuriy|Insecuriy]] ([[User talk:Insecuriy|talk]]) 15:12, 16 December 2018 (UTC)<br />
<br />
:: The configuration describes a configuration and/or decision choice. Not something that is inherent to the configuration of wireguard. Arguably not even a common problem. If it was a "trivial configuration" the section wouldn't be needed. The systemd and config parts are examples and not explained with a lot of text and thus fits quite nicely within the "Usage" section. "Tips and tricks" also fits better for opinionated solutions or configurations tips.<br />
:: [[User:Foxboron|Foxboron]] ([[User talk:Foxboron|talk]]) 15:19, 16 December 2018 (UTC)<br />
<br />
::: I think this is a common problem, judging by seeing that "even this page" got it wrong under the "VPN Server Client Confing", maybe its a better fit under "VPN Server"? -- [[User:Insecuriy|Insecuriy]] ([[User talk:Insecuriy|talk]]) 15:26, 16 December 2018 (UTC)<br />
<br />
:::: It is a possible problem for both sections. Listing it under "VPN Server" would not really illustrate that very well. The usage section should be concise and to the point. Trying to fit every problem into that section would not really work in the long run.<br />
:::: [[User:Foxboron|Foxboron]] ([[User talk:Foxboron|talk]]) 15:31, 16 December 2018 (UTC)<br />
<br />
== <s>Page is unclear on how to set up a routed network using WireGuard</s> ==<br />
<br />
When I initially started using WireGuard I started with this page, but going on I found it very misleading and usually I tell people who ask me to read the main website instead.<br />
<br />
The problem is that it is unclear on how its cryptokey-routing mechanism works, and most of the examples in the page show configs that, in my opinion, "work by mistake".<br />
<br />
On a regular switched network you have ARP and you usually set up a network prefix properly - an IP address and a netmask. So, if my address is 10.0.0.1/24 (i.e. on eth0) and a program on my machine wants to contact 10.0.0.2/24, this is what happens:<br />
<br />
* The request reaches the kernel<br />
* The kernel (no routing involved) sees that 10.0.0.2/24 is in the same network as the eth0 interface<br />
* The packet needs to go through layer 2, an ARP request is sent and the MAC address is resolved<br />
* An Ethernet frame is built for .2's MAC address and is sent to the network interface<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
: ''Commenting in-line due to the size of the post and the inaccuracies contained within''<br />
: ''This is not, in fact, what happens. Try it: empty out your routing table and try to reach anything that should be directly reachable on your LAN by IP address. You can't. No matter, however, that's not relevant to the rest of your post. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
:: ''I'll comment inline for the same reason.''<br />
:: ''First of all, thanks for your feedback. I must admit that I haven't actually tested some of these configuration, and wrote this out of what I remembered. Shame on me.''<br />
:: ''I'm still not convinced on this point in particular, I will definitely test it though. [[User:Depau|Depau]] ([[User talk:Depau|talk]]) 07:50, 13 May 2019 (UTC)''<br />
<br />
<br />
However, WireGuard is a layer 3 VPN so we have no ARP. We don't have Ethernet cables either, but we do have one or more UDP sockets and another WireGuard interface on the other end.<br />
<br />
WireGuard has **no way** to know what IP address there is on the other end of the socket, and it defines no protocol to find it out. It still does have to pick one socket to send the packet to. It does that by using the AllowedIPs list "backwards", so:<br />
<br />
* When a packet is received from the WireGuard socket<br />
** it is dropped if it doesn't match any rule<br />
* When a packet is sent through the WireGuard interface<br />
** AllowedIPs is used as a "routing table" to pick a socket<br />
<br />
The name "AllowedIPs" is a bit misleading: I think the wiki page should try to make this a little clearer.<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''This is called CryptoKey routing and we've been having discussion on improving the documentation about that on the wireguard homepage and in the manpage itself. I don't believe it is up to us to fully explain the mechanism, but a quick mention would be in order. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
::: ''I also don't think the page is up to explain it fully, but yes, it should at least mention it. [[User:Depau|Depau]] ([[User talk:Depau|talk]]) 07:50, 13 May 2019 (UTC)''<br />
<br />
<br />
So, for example, to have a behavior that is similar to the switched network example, one would have to<br />
<br />
* Set IP address/netmask to 10.0.0.1/24<br />
* Set AllowedIPs for that specific peer should be set to "10.0.0.2/32, 10.0.0.0/24"<br />
<br />
The important part here is that 10.0.0.2/32 should *always* be added to AllowedIPs, even if other rules are more permissive.<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''This is unnecessary. Without that particular address this setup '''works''' and it works '''intentionally'''. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
<br />
Why? Because of cryptokey routing:<br />
<br />
* When I receive a packet, it doesn't matter, both rules allow it<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''Actually it '''does''' matter because AllowedIPs functions on a '''strict rpfilter''' basis: It will only accept a packet if it would have been '''sent''' to that peer using that address as well. Which is why wireguard does '''not''' allow ambiguities like the one you're showing below. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
::: ''I will double check and update accordingly. [[User:Depau|Depau]] ([[User talk:Depau|talk]]) 07:50, 13 May 2019 (UTC)''<br />
<br />
* When I *send* a packet, it's used as a routing table<br />
** Longest netmask wins<br />
** If I had multiple peers on the same network, WireGuard wouldn't know where to send the packet<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''It would, because there is absolutely no allowance for ambiguity. You've just got a misconfiguration. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
<br />
A real-life example where this is an issue is when I want one peer to be a gateway to the Internet, but I still want to reach all the others directly.<br />
<br />
In this case, this is what I should have:<br />
<br />
* Address (wg0): 10.0.0.1/24<br />
* Gateway's AllowedIPs: 0.0.0.0/0, 10.0.0.0/24, 10.0.0.2/32<br />
* Other peer's AllowedIPs: 10.0.0.0/24, 10.0.0.3/32<br />
* etc.<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''This is wrong, plain and simple. You've now created an identical AllowedIPs configuration for the LAN, and it will only allow you to set it on one of them. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
<br />
<br />
Note that wg-quick also takes every AllowedIPs entry and adds it to the routing table. Also note that I only have to add the "10.0.0.0/24" entry if I want those peers to route packets to other peers that I haven't configured on my machine.<br />
<br />
So this is what happens now (if I use wg-quick):<br />
<br />
* I send a packet to 10.0.0.3<br />
** The kernel sees the address is in the same network as wg0, so it's sent to the WireGuard module<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''Nope. Goes through the routing table, then sees that it's supposed to go to wg0, so gets sent to wg0, which is handled by the wireguard module. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
<br />
** WireGuard looks through all the AllowedIPs entries<br />
*** They all match, but 10.0.0.3/32 has the longest netmask so it's sent to that peer<br />
<br />
* I send a packet to 1.1.1.1<br />
** The kernel sees no interface is in the same network, so the packet needs to go through the routing table<br />
** wg-quick added an entry 0.0.0.0/0 -> wg0 to the routing table, so it's sent to WireGuard<br />
** WireGuard looks through all the AllowedIPs entries<br />
*** None matches except for 0.0.0.0/0, so it's sent to that peer<br />
<br />
If I don't use wg-quick and I use, for example, systemd-networkd, I need to make sure I explicitly add those routes to the .network file to replicate the same behavior.<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
:: ''How is this relevant to any of the above? Yes, you need to configure routing, or your network manager needs to do it for you and you need to tell it how. This page is '''not''' intended as a crash course to networking. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)''<br />
::: ''I see, but I think it should at least be mentioned that wg-quick does set routes (if it isn't, I haven't checked) [[User:Depau|Depau]] ([[User talk:Depau|talk]]) 07:50, 13 May 2019 (UTC)''<br />
<br />
I decided to discuss this issue before actually editing the page. Let me know what you think about it :)<br />
<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 17:15, 1 May 2019 (UTC)<br />
<br />
: Good, because I think you're wrong on the point that one should ''always'' add the address of the remote peer to AllowedIPs. You should configure the AllowedIPs for multiple peers based on the actual routing mesh that you've got. (Or rather, routing tree, because of the strict rpfilter functionality I mentioned. To use wireguard in a mesh with failover you actually do need to ensure there's only one path to a peer from any other peer, so you need some active management.) Bear in mind that it's perfectly reasonable to configure ''no IP address at all'' on the wireguard interface, and only check on the traffic it routes; also bear in mind that most configurations are single-peer on the client-side and the server-side, and '''if''' the server-side is multi-peer there will usually be no overlap at all anyway. These configurations do not work "by mistake", they're correctly configured. However, I do agree that it would be beneficial to add a ('''correct''') configuration example for the more advanced usecase of the mesh you're describing. If you need help figuring out what that configuration would be, it'd be easiest on IRC in either #archlinux or #wireguard, rather than here; and then summarize it here. [[User:MacGyver|MacGyver]] ([[User talk:MacGyver|talk]]) 22:47, 12 May 2019 (UTC)<br />
:: I replied inline as I don't have time to actively discuss about this on IRC any time this week. Also I would like to test what you pointed out before I get back to it.<br />
:: I'll come back to IRC as soon as I can. Again, thanks for your feedback :) [[User:Depau|Depau]] ([[User talk:Depau|talk]]) 07:50, 13 May 2019 (UTC)<br />
<br />
<br />
::: Sorry for getting back to this again after almost one year. Thanks for your feedback, by now I've had time to understand your points and I'm pretty convinced, I'd close this to leave space for other discussions.<br />
::: I still think it's worth mentioning that wg-quick will add routes in some cases, but it can be discussed separately. [[User:Depau|Depau]] ([[User talk:Depau|talk]]) 21:42, 3 January 2020 (UTC)<br />
<br />
== Proposed merge of usage with use-case ==<br />
<br />
@Nl6720 - You proposed a merge of these sections with he text, "There are no servers and clients in WireGuard, only peers." I feel breaking this out as-is and using terminology like "client" and "server" is needed for wireguard naive users. These are terms they have in their minds (e.g. openvpn) and when wanting to come over to wireguard help this transition. I added [https://wiki.archlinux.org/index.php?title=WireGuard&type=revision&diff=589846&oldid=589845 this note] to make this more clear in the subsection. [[User:Graysky|Graysky]] ([[User talk:Graysky|talk]]) 09:40, 23 November 2019 (UTC)<br />
<br />
:The only thing that makes a specific peer into a ''server'' is that another peer is routing all traffic ({{ic|0.0.0.0/0}}, {{ic|::/0}}) to it and sets it as the DNS server, and maybe that the ''server'' has a DNS record. That's it. I think creating a top level section with multiple subsections just to state this simple fact is too much and it gives the impression that WireGuard setup is more complicated than it actually is. It could be simple explained in [[WireGuard#Usage]], possibly in one subsection of it. Also the [[WireGuard#Usage]] and [[WireGuard#Specific use-case: VPN server]] separation makes it seem like you either just connect the individual peers or setup a ''server'' and other peers router all traffic to it. There's not limit to which and from which peer you route {{ic|0.0.0.0/0}} & {{ic|::/0}}.<br />
:Personally I use WireGuard through NetworkManager and I have two almost identical connections ([http://ix.io/22Bz wg0.nmconnection] and [http://ix.io/22BA wg1.nmconnection]), the only difference is that wg1 routes {{ic|0.0.0.0/0;::/0;}} to peer 1.<br />
: -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 10:47, 23 November 2019 (UTC)<br />
<br />
== Additional routes subsection is not working ==<br />
<br />
Internal addresses can't be reached unless you also specifically add the correct CIDR for the network when using Windows as peer. So in my case I have to use {{ic|0.0.0.0/0, 192.168.1.0/24}} in the AllowedIPs clause for that to work.<br />
-- [[User:Chippey5|Chippey5]] ([[User talk:Chippey5|talk]]) 08:33, 13 April 2020 (UTC)<br />
<br />
== Peer C ==<br />
<br />
This is a idea for an improvement to the [[WireGuard#Usage]] section. <s>The draft is barely started and '''none of it is tested'''.</s> -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:04, 1 December 2019 (UTC)<br />
<br />
:[https://git.kernel.org/pub/scm/network/connman/connman.git/log/?qt=grep&q=WireGuard It looks] like the next version of ConnMan will support WireGuard. I hope to finish this draft before it gets released. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 10:01, 25 January 2020 (UTC)<br />
<br />
::[https://lists.01.org/hyperkitty/list/connman@lists.01.org/message/EKDRUYMT7FZJ5KLFZXEZ5P73O656VUOA/] :( The draft has not been progressing as fast as I hoped. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 12:33, 18 February 2020 (UTC)<br />
<br />
::Looking at [https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt vpn-config-format.txt], it seams that Connman's implementation only supports connections betwean two peers. Thus I will not be adding Connman examples. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 08:49, 4 April 2020 (UTC)<br />
<br />
:The draft could use some list2text and section intros, but otherwise it's ready for review. -- [[User:nl6720|nl6720]] ([[User talk:nl6720|talk]]) 08:49, 4 April 2020 (UTC)<br />
<br />
=== Draft "Peer C" ===<br />
<br />
The below commands demonstrate how to setup a basic tunnel between two or more peers with the following settings:<br />
<br />
{| class="wikitable"<br />
! rowspan="2" |<br />
! colspan="3" | External (public) addresses<br />
! colspan="2" | Internal IP addresses<br />
! rowspan="2" | Port<br />
|-<br />
! Domain name<br />
! IPv4 address<br />
! IPv6 address<br />
! IPv4 address<br />
! IPv6 address<br />
|-<br />
! Peer A<br />
| <br />
| 198.51.100.101<br />
| 2001:db8:a85b:70a:ffd4:ec1b:4650:a001<br />
| 10.0.0.1/24<br />
| fdc9:281f:04d7:9ee9::1/64<br />
| UDP/51871<br />
|-<br />
! Peer B<br />
| peer-b.example<br />
| 203.0.113.102<br />
| 2001:db8:40f0:147a:80ad:3e88:f8e9:b002<br />
| 10.0.0.2/24<br />
| fdc9:281f:04d7:9ee9::2/64<br />
| UDP/51902<br />
|-<br />
! Peer C<br />
| <br />
| ''dynamic''<br />
| ''dynamic''<br />
| 10.0.0.3/24<br />
| fdc9:281f:04d7:9ee9::3/64<br />
| UDP/51993<br />
|}<br />
<br />
The external addresses should already exist. For example, if ICMP echo requests are not blocked, peer A should be able to [[ping]] peer B via its the public IP address(es), and vice versa.<br />
<br />
The internal addresses will be new addresses, created either manually using the {{man|8|ip}} utility or by a network management software, which will be used internally within the new WireGuard network. The following examples will use 10.0.0.0/24 and fdc9:281f:04d7:9ee9::/64 as the internal network. The {{ic|/24}} and {{ic|/64}} in the IP addresses is the [[Wikipedia:Classless Inter-Domain Routing#CIDR notation|CIDR]].<br />
<br />
==== Key generation ====<br />
<br />
Create a private and public key for each peer.<br />
<br />
To create a private key run:<br />
<br />
$ wg genkey > peer_A.key<br />
<br />
{{Note|It is recommended to only allow reading and writing access for the owner:<br />
<br />
$ chmod 600 peer_A.key<br />
<br />
}}<br />
<br />
To create a public key:<br />
<br />
$ wg pubkey < peer_A.key > peer_A.pub<br />
<br />
Alternatively, do this all at once:<br />
<br />
$ wg genkey | tee peer_A.key | wg pubkey > peer_A.pub<br />
<br />
One can also generate a pre-shared key to add an additional layer of symmetric-key cryptography to be mixed into the already existing public-key cryptography, for post-quantum resistance. A pre-shared key should be generated for each peer pair and should not be reused. For example, if you have three interconnected peers—A, B and C—you will need three pre-shared keys, for peer A - peer B, peer A - peer C and peer B - peer C.<br />
<br />
Generate a pre-shared key for each peer pair using the following command:<br />
<br />
$ wg genpsk > peer_A-peer_B.psk<br />
$ wg genpsk > peer_A-peer_C.psk<br />
$ wg genpsk > peer_B-peer_C.psk<br />
<br />
==== Manual WireGuard setup ====<br />
<br />
Manual setup is accomplished by using {{man|8|ip}} and {{man|8|wg}}.<br />
<br />
'''Peer A setup:'''<br />
<br />
In this example peer A will listen on UDP port 51871 and will accept connection from peer B and C.<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.1/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::1/64 dev wg0<br />
# wg set wg0 listen-port 51871 private-key ''/path/to/''peer_A.key<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
{{ic|''PEER_X_PUBLIC_KEY''}} should have the same format as {{ic|1=EsnHH9m6RthHSs+sd9uM6eCHe/mMVFaRh93GYadDDnM=}}.<br />
<br />
The keyword {{ic|allowed-ips}} is a list of addresses that will get routed to the peer. Make sure to specify the WireGuard connection's internal IP address(es) otherwise you will not be able to establish a connection between the peers.<br />
<br />
'''Peer B setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.2/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::2/64 dev wg0<br />
# wg set wg0 listen-port 51902 private-key ''/path/to/''peer_B.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_B.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_C_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk allowed-ips 10.0.0.3/32,fdc9:281f:04d7:9ee9::3/128<br />
# ip link set wg0 up<br />
<br />
'''Peer C setup:'''<br />
<br />
# ip link add dev wg0 type wireguard<br />
# ip addr add 10.0.0.3/24 dev wg0<br />
# ip addr add fdc9:281f:04d7:9ee9::3/64 dev wg0<br />
# wg set wg0 listen-port 51993 private-key ''/path/to/''peer_C.key<br />
# wg set wg0 peer ''PEER_A_PUBLIC_KEY'' preshared-key ''/path/to/''peer_A-peer_C.psk endpoint 198.51.100.101:51871 allowed-ips 10.0.0.1/32,fdc9:281f:04d7:9ee9::1/128<br />
# wg set wg0 peer ''PEER_B_PUBLIC_KEY'' preshared-key ''/path/to/''peer_B-peer_C.psk endpoint peer-b.example:51902 allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128<br />
# ip link set wg0 up<br />
<br />
===== Additional routes =====<br />
<br />
If you want to access a peer's internal network, specify the network subnet(s) in {{ic|allowed-ips}} in the configuration of the peers who should be able to connect to it. E.g. {{ic|allowed-ips 10.0.0.2/32,fdc9:281f:04d7:9ee9::2/128,'''192.168.35.0/24,fd7b:d0bd:7a6e::/64'''}}. To route all traffic, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|allowed-ips}}. E.g. {{ic|allowed-ips 0.0.0.0/0,::/0}}.<br />
<br />
Make sure to also set up the [[Network configuration#Routing table|routing table]] with {{man|8|ip-route}}. E.g.:<br />
<br />
# ip route add 192.168.35.0/24 dev wg0<br />
# ip route add fd7b:d0bd:7a6e::/64 dev wg0<br />
<br />
or:<br />
<br />
# ip route add 0.0.0.0/0 dev wg0<br />
# ip route add ::/0 dev wg0<br />
<br />
Enable IP forwarding on the peer through which others will connect:<br />
<br />
# sysctl -w net.ipv4.ip_forward=1<br />
# sysctl -w net.ipv6.conf.all.forwarding=1<br />
<br />
===== DNS =====<br />
<br />
To use a peer as a DNS server, add its WireGuard tunnel IP address(es) to [[:/etc/resolv.conf]]. For example, to use peer B as the DNS server:<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver fdc9:281f:04d7:9ee9::2<br />
nameserver 10.0.0.2<br />
}}<br />
<br />
{{Note|If a peer will act as a DNS server, make sure to use its WireGuard tunnel address(es) as the DNS server address(es) instead of another of its addresses from allowed IPs. Otherwise the DNS lookups may fail.}}<br />
<br />
==== Basic checkups ====<br />
<br />
Invoking the {{man|8|wg}} command without parameter will give a quick overview of the current configuration.<br />
<br />
As an example, when peer A has been configured we are able to see its identity and its associated peers:<br />
<br />
{{hc|[user@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
endpoint: 192.0.2.103:51993<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
At this point one could reach the end of the tunnel. If the peers do not block ICMP echo requests, try [[ping]]ing a peer to test the connection between them.<br />
<br />
Using ICMPv4:<br />
<br />
[user@peer-a]$ ping 10.0.0.2<br />
<br />
Using ICMPv6:<br />
<br />
[user@peer-a]$ ping fdc9:281f:04d7:9ee9::2<br />
<br />
After transferring some data between peers, the {{ic|wg}} utility will show additional information:<br />
<br />
{{hc|[root@peer-a]# wg|2=<br />
interface: wg0<br />
public key: UguPyBThx/+xMXeTbRYkKlP0Wh/QZT3vTLPOVaaXTD8=<br />
private key: (hidden)<br />
listening port: 51871<br />
<br />
peer: 9jalV3EEBnVXahro0pRMQ+cHlmjE33Slo9tddzCVtCw=<br />
endpoint: 203.0.113.102:51902<br />
allowed ips: 10.0.0.2/32, fdc9:281f:04d7:9ee9::2<br />
latest handshake: 5 seconds ago<br />
transfer: 1.24 KiB received, 1.38 KiB sent<br />
<br />
peer: 2RzKFbGMx5g7fG0BrWCI7JIpGvcwGkqUaCoENYueJw4=<br />
allowed ips: 10.0.0.3/32, fdc9:281f:04d7:9ee9::3<br />
}}<br />
<br />
==== Persistent configuration ====<br />
<br />
Persistent configuration can be achieved using {{ic|wg-quick@.service}}, which is shipped with {{Pkg|wireguard-tools}}, or using network manager. Network managers that support WireGuard are—[[systemd-networkd]], [[NetworkManager]] and [[ConnMan]][https://git.kernel.org/pub/scm/network/connman/connman.git/tree/doc/vpn-config-format.txt].<br />
<br />
===== wg-quick =====<br />
<br />
{{man|8|wg-quick}} configures WireGuard tunnels using configuration files from {{ic|/etc/wireguard/''interfacename''.conf}}.<br />
<br />
The current WireGuard configuration can be saved by utilizing the {{man|8|wg}} utility's {{ic|showconf}} command. For example:<br />
<br />
# wg showconf wg0 > /etc/wireguard/wg0.conf<br />
<br />
To start a tunnel with a configuration file, use<br />
<br />
# wg-quick up ''interfacename''<br />
<br />
or use the systemd service—{{ic|wg-quick@''interfacename''.service}}. To start the tunnel at boot, [[enable]] the unit.<br />
<br />
{{Note|<br />
* If you are configuring the WireGuard interface using ''wg-quick'', make sure that no other [[network management]] software tries to manage it. If you use [[NetworkManager]], but do not want to configure WireGuard interfaces with it, see [[#Routes are periodically reset]].<br />
* ''wg-quick'' adds additional configuration options to the configuration file format thus making it incompatible with {{man|8|wg|CONFIGURATION FILE FORMAT}}. See the {{man|8|wg-quick|CONFIGURATION}} man page for the configuration values in question. A ''wg''-compatible configuration file can be produced by using {{ic|wg-quick strip}}.<br />
* ''wg-quick'' does not support setting DNS search domains.[https://lists.zx2c4.com/pipermail/wireguard/2020-January/004895.html]<br />
}}<br />
<br />
'''Peer A:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.1/24, fdc9:281f:04d7:9ee9::1/64<br />
ListenPort = 51871<br />
PrivateKey = ''PEER_A_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
* To route all traffic through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|AllowedIPs}}. E.g. {{ic|1=AllowedIPs = 0.0.0.0/0, ::/0}}.<br />
* To use a peer as a DNS server, specify it using {{ic|1=DNS = ''wireguard_internal_ip_address_of_peer''}} in the {{ic|[Interface]}} section. E.g.:<br />
<br />
{{bc|1=<br />
[Interface]<br />
..<br />
DNS = 10.0.0.2, fdc9:281f:04d7:9ee9::2<br />
...<br />
}}<br />
<br />
'''Peer B:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.2/24, fdc9:281f:04d7:9ee9::2/64<br />
ListenPort = 51902<br />
PrivateKey = ''PEER_B_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_C_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.3/32, fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
'''Peer C:'''<br />
<br />
{{hc|1=/etc/wireguard/wg0.conf|2=<br />
[Interface]<br />
Address = 10.0.0.3/24, fdc9:281f:04d7:9ee9::3/64<br />
ListenPort = 51993<br />
PrivateKey = ''PEER_C_PRIVATE_KEY''<br />
<br />
[Peer]<br />
PublicKey = ''PEER_A_PUBLIC_KEY''<br />
PresharedKey = ''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.1/32, fdc9:281f:04d7:9ee9::1/128<br />
Endpoint = 198.51.100.101:51871<br />
<br />
[Peer]<br />
PublicKey = ''PEER_B_PUBLIC_KEY''<br />
PresharedKey = ''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs = 10.0.0.2/32, fdc9:281f:04d7:9ee9::2/128<br />
Endpoint = peer-b.example:51902<br />
}}<br />
<br />
===== systemd-networkd =====<br />
<br />
[[systemd-networkd]] has native support for setting up WireGuard interfaces. An example is provided in the {{man|5|systemd.netdev|EXAMPLES}} man page.<br />
<br />
{{Note|<br />
* systemd-networkd does not support having the default route on a WireGuard interface.<br />
* Routing all DNS over WireGuard (i.e. {{ic|1=Domains=~.}}) will prevent the DNS resolution of endpoints.<br />
* systemd-networkd does not automatically create routes for subnets specified in AllowedIPs. See [https://github.com/systemd/systemd/issues/14176 systemd issue 14176]. This will not affect the connectivity between peers since they exist in the subnet that is specified with the {{ic|1=Address=}} option in the ''.network'' file.<br />
}}<br />
<br />
'''Peer A:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51871<br />
PrivateKey=''PEER_A_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.1/24<br />
Address=fdc9:281f:04d7:9ee9::1/64<br />
}}<br />
<br />
* To use a peer as a DNS server, specify its WireGuard tunnel's IP address(es) in the ''.network'' file using the {{ic|1=DNS=}} option. For search domains use the {{ic|1=Domains=}} option. See {{man|5|systemd.network|[NETWORK] SECTION OPTIONS}} for details.<br />
* If you want to use a peer as the '''only''' DNS server, then in the ''.network'' file's {{ic|[Network]}} section set {{ic|1=DNSDefaultRoute=true}} and add {{ic|~.}} to the search domains.<br />
* To route additional subnet add them as {{ic|[Route]}} sections in the ''.network'' file. For example:<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
...<br />
[Route]<br />
Destination=192.168.35.0/24<br />
Scope=link<br />
<br />
[Route]<br />
Destination=fd7b:d0bd:7a6e::/64<br />
Scope=link<br />
}}<br />
<br />
'''Peer B:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51902<br />
PrivateKey=''PEER_B_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_B-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_C_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.3/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::3/128<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.2/24<br />
Address=fdc9:281f:04d7:9ee9::2/64<br />
}}<br />
<br />
'''Peer C:'''<br />
<br />
{{hc|/etc/systemd/network/99-wg0.netdev|2=<br />
[NetDev]<br />
Name=wg0<br />
Kind=wireguard<br />
Description=WireGuard tunnel wg0<br />
<br />
[WireGuard]<br />
ListenPort=51993<br />
PrivateKey=''PEER_C_PRIVATE_KEY''<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_A_PUBLIC_KEY''<br />
PresharedKey=''PEER_A-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.1/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::1/128<br />
Endpoint=198.51.100.101:51871<br />
<br />
[WireGuardPeer]<br />
PublicKey=''PEER_B_PUBLIC_KEY''<br />
PresharedKey=''PEER_B-PEER_C-PRESHARED_KEY''<br />
AllowedIPs=10.0.0.2/32<br />
AllowedIPs=fdc9:281f:04d7:9ee9::2/128<br />
Endpoint=peer-b.example:51902<br />
}}<br />
<br />
{{hc|/etc/systemd/network/99-wg0.network|2=<br />
[Match]<br />
Name=wg0<br />
<br />
[Network]<br />
Address=10.0.0.3/24<br />
Address=fdc9:281f:04d7:9ee9::3/64<br />
}}<br />
<br />
===== NetworkManager =====<br />
<br />
[[NetworkManager]] has native support for setting up WireGuard interfaces. For all details about WireGuard usage in NetworkManager, read Thomas Haller's blog post—[https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/ WireGuard in NetworkManager].<br />
<br />
{{Tip|NetworkManager can import a wg-quick configuration file. E.g.: {{bc|# nmcli connection import type wireguard file /etc/wireguard/wg0.conf}}}}<br />
<br />
{{Note|nmcli can create a WireGuard connection profile, but it does not support configuring WireGuard peers. See [https://gitlab.freedesktop.org/NetworkManager/NetworkManager/issues/358 NetworkManager issue 358].}}<br />
<br />
The following examples configure WireGuard via the keyfile format ''.nmconnection'' files. See {{man|5|nm-settings-keyfile}} and {{man|5|nm-settings}} for a explanation on the syntax and available options.<br />
<br />
'''Peer A:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51871<br />
private-key=''PEER_A_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.1/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::1/64<br />
method=manual<br />
}}<br />
<br />
* To route all traffic through the tunnel to a specific peer, add the [[Wikipedia:Default route|default route]] ({{ic|0.0.0.0/0}} for IPv4 and {{ic|::/0}} for IPv6) to {{ic|wireguard-peer.''PEER_X_PUBLIC_KEY''.allowed-ips}}. E.g. {{ic|1=wireguard-peer.''PEER_B_PUBLIC_KEY''.allowed-ips=0.0.0.0/0;::/0;}}.<br />
* To use a peer as a DNS server, specify specify its WireGuard tunnel's IP address(es) with the {{ic|ipv4.dns}} and {{ic|ipv6.dns}} settings, Search domains are set using the {{ic|1=ipv4.dns-search=}} and {{ic|1=ipv6.dns-search=}} options. See {{man|5|nm-settings}} for more details. For example, using the keyfile format:<br />
<br />
{{bc|1=<br />
...<br />
[ipv4]<br />
...<br />
dns=10.0.0.2;<br />
dns-search=corp;<br />
...<br />
[ipv6]<br />
...<br />
dns=fdc9:281f:04d7:9ee9::2;<br />
dns-search=corp;<br />
...<br />
}}<br />
<br />
If you want to use a peer as the '''only''' DNS server, then set a negative DNS priority (e.g. {{ic|1=dns-priority=-1}}) and add {{ic|~.}} to the search domains.<br />
<br />
'''Peer B:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51902<br />
private-key=''PEER_B_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_B-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_C_PUBLIC_KEY'']<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.3/32;fdc9:281f:04d7:9ee9::3/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.2/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::2/64<br />
method=manual<br />
}}<br />
<br />
'''Peer C:'''<br />
<br />
{{hc|/etc/NetworkManager/system-connections/wg0.nmconnection|2=<br />
[connection]<br />
id=wg0<br />
type=wireguard<br />
interface-name=wg0<br />
<br />
[wireguard]<br />
listen-port=51993<br />
private-key=''PEER_C_PRIVATE_KEY''<br />
private-key-flags=0<br />
<br />
[wireguard-peer.''PEER_A_PUBLIC_KEY'']<br />
endpoint=198.51.100.101:51871<br />
preshared-key=''PEER_A-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.1/32;fdc9:281f:04d7:9ee9::1/128;<br />
<br />
[wireguard-peer.''PEER_B_PUBLIC_KEY'']<br />
endpoint=peer-b.example:51902<br />
preshared-key=''PEER_B-PEER_C-PRESHARED_KEY''<br />
preshared-key-flags=0<br />
allowed-ips=10.0.0.2/32;fdc9:281f:04d7:9ee9::2/128;<br />
<br />
[ipv4]<br />
address1=10.0.0.3/24<br />
method=manual<br />
<br />
[ipv6]<br />
address1=fdc9:281f:04d7:9ee9::3/64<br />
method=manual<br />
}}<br />
<br />
== Add subsection in troubleshooting for other MTU issues ==<br />
<br />
I'd like to add a section under "Troubleshooting" on a problem I've been bashing my head onto for a few hours.<br />
<br />
I've been having this issue with two peers communicating over IPv6. Handshakes and small packets would go through. If I curl-ed the other host I could see the TCP handshake and the last part of the HTML, but not the big chunks. I eventually did some quick math and figured an MTU of 1380 should be enough to account for IPv6, UDP and WireGuard headers + some extra bytes to be on the safe side on an interface with a default 1500B MTU. It did work.<br />
<br />
I would like some advice on wording to keep the page quality and accuracy good, and to avoid stuff like my discussion above. 1380 (or rather 1500 - around 120) works for me, though I wouldn't throw that magic number into the page without a proper technical explanation.<br />
<br />
[[User:Depau|Depau]] ([[User talk:Depau|talk]]) 21:30, 3 January 2020 (UTC)</div>Chippey5https://wiki.archlinux.org/index.php?title=Android_tethering&diff=588200Android tethering2019-11-08T15:38:59Z<p>Chippey5: Re-added a section that previously was available to temporarily perform USB tethering with Android using dhcpcd.</p>
<hr />
<div>[[Category:Android]]<br />
[[Category:Network sharing]]<br />
[[fr:Modem attache Android]]<br />
[[ja:Android テザリング]]<br />
[[ru:Android tethering]]<br />
[[Wikipedia:Tethering|Tethering]] is a way to have internet access on your PC through your smartphone using its network connection. USB tethering and Wi-Fi access point tethering are natively supported since Android 2.2 "Froyo".<br />
<br />
== Wi-Fi access point ==<br />
<br />
Using an Android phone as a Wi-Fi access point (to a 3G/4G mobile internet connection) is available for devices running Android 2.2 "Froyo" or newer.<br />
<br />
Enable it via one of the following:<br />
<br />
* ''Settings > Wireless & networks > Internet tethering > Wi-Fi access point''<br />
* ''Settings > More... > Tethering & mobile hotspot > Mobile Wi-Fi hotspot''<br />
<br />
{{Note|On some phones, this method will discharge the battery rapidly and tends to cause intense heating, unlike USB.}}<br />
<br />
== USB tethering ==<br />
<br />
USB tethering is available since Android 2.2 "Froyo".<br />
<br />
* Connect the phone to your computer via USB (the USB connection mode -- Phone Portal, Memory Card or Charge only -- is not important, but please note that you will not be able to change the USB mode during tethering)<br />
* Enable the tethering option from your phone. This is usually done from one of:<br />
** ''Settings -> Wireless & networks -> Internet tethering'' (or ''Tethering & portable hotspot'', for more recent versions)<br />
** ''Settings -> More... -> Tethering & mobile hotspot -> USB tethering''<br />
* Follow [[Network configuration]].<br />
<br />
{{Note|The network interface name may change depending on the USB port you use. You may want to [[Network configuration#Change interface name|change the interface name]] to create a unique name for your device regardless of the USB port.}}<br />
<br />
* If you're using a cellular data plan and you have recently entered a new billing period, you may need to restart your phone.<br />
<br />
==== Using systemd-networkd with udev ====<br />
<br />
Using [[systemd-networkd]] you can automatically adjust the networking to use the phone as the gateway when plugged in.<br />
<br />
{{hc|/etc/udev/rules.d/90-android-tethering.rules|<nowiki><br />
# Execute pairing program when appropriate<br />
ACTION=="add|remove", SUBSYSTEM=="net", ATTR{idVendor}=="18d1" ENV{ID_USB_DRIVER}=="rndis_host", SYMLINK+="android", RUN+="/usr/bin/systemctl restart systemd-networkd.service"<br />
</nowiki>}}<br />
<br />
You may have to adjust the {{ic|idVendor}} attribute depending on your phone. You can check using ''udevadm'':<br />
<br />
$ udevadm info /sys/class/net/enp0s26u1u2<br />
<br />
Then create the corresponding systemd-networkd file:<br />
<br />
{{hc|/etc/systemd/network/50-enp0s26u1u2.network|<nowiki><br />
[Match]<br />
Name=enp0s26u1u2<br />
<br />
[Network]<br />
DHCP=ipv4<br />
</nowiki>}}<br />
<br />
==== Temporarily establish a connection with DHCPCD ====<br />
<br />
In order to establish a temporary connection with android tethering, [[Dhcpcd]] can be used as follows:<br />
<br />
Find the Android tethering interface after it has been activated on your phone:<br />
<br />
$ ip link<br />
<br />
An interface similar to ''enp0s26u1u2''<sup>1</sup> should be returned. To establish the connection:<br />
<br />
$ dhcpcd enp0s26u1u2<br />
<br />
# Replace ''enp0s26u1u2'' with the interface name that is returned by your system.<br />
<br />
== USB tethering with AziLink ==<br />
<br />
[https://github.com/aziwoqpd/azilink AziLink] is an application that allows USB tethering for Android-based phones, without requiring root access. It is very useful for Android older than version 2.2, when there was no stock USB tethering feature implemented. It also does not require changes to your browser, and all network traffic is transparently handled (except ICMP pings). It may be somewhat CPU intensive on the phone at high usage rates (a 500 kBytes/sec data transfer rate may take more than 50% of phone CPU).<br />
<br />
=== Tools needed ===<br />
<br />
For Arch, you need to [[install]] the {{pkg|openvpn}} package. You will also need to install the {{pkg|android-tools}} package for the ''adb'' tool and {{pkg|android-udev}} which sets up the correct {{ic|/usr/lib/udev/rules.d/51-android.rules}} file for your device to be recognized. On the phone, you need the [http://lfx.org/azilink/azilink.apk azilink.apk] ([https://github.com/aziwoqpd/azilink azilink homepage]). The android application acts as a NAT, adb forwards the ports to your phone, and your openvnp setup will connect to it.<br />
<br />
==== Configuring the phone connection in Arch Linux ====<br />
<br />
So that you do not have to run adb as root, we are going to grant your user permissions to your usb device. Make sure you have turned on USB debugging on the phone (usually in ''Settings -> Applications -> Development -> USB debugging'') so that it will be shown as a device, and that it is plugged in to your computer via the USB cable. You should see it with you run the {{ic|lsusb}} command. Original azi link instructions are [https://raw.githubusercontent.com/aziwoqpd/azilink/master/HOWTO here]<br />
<br />
The device should be listed. Example output for the Acer Liquid phone:<br />
<br />
Bus 001 Device 006: ID '''0502''':3202 Acer, Inc. <br />
<br />
Then, create the following file, replacing {{ic|ciri}} by your own Linux user name, and '''0502''' by the vendor ID of your own phone:<br />
<br />
{{hc|/etc/udev/rules.d/51-android.rules|<nowiki><br />
SUBSYSTEM=="usb", ATTR(idVendor)=="0502", MODE="0666" OWNER="ciri"<br />
</nowiki>}}<br />
<br />
As root run the {{ic|udevadm control --reload}} command to make the change effective. To make sure the change took effect, run {{ic|adb devices}} and it should say {{ic|device}} instead of {{ic|unauthorized}}. Another way to make it take effect is to reboot. Another test is to run {{ic|adb shell}} to get to your phones unix prompt.<br />
<br />
=== Procedure ===<br />
<br />
Run the AziLink application in the phone and select ''About'' at the bottom to receive instructions, which basically are:<br />
<br />
# You will have to enable USB debugging on the phone if it was not already enabled (usually in ''Settings -> Applications -> Development -> USB debugging'').<br />
# Connect the phone with the USB cable to the PC.<br />
# Run AziLink and make sure that the ''Service active'' option at the top is checked.<br />
# Run the following commands in your Linux PC:<br />
<br />
$ adb forward tcp:41927 tcp:41927<br />
# openvpn azilink.ovpn<br />
<br />
{{ic|azilink.ovpn}} source from [https://raw.githubusercontent.com/aziwoqpd/azilink/master/azilink.ovpn here]<br />
<br />
{{hc|azilink.ovpn|<nowiki><br />
dev tun<br />
remote 127.0.0.1 41927 tcp-client<br />
ifconfig 192.168.56.2 192.168.56.1<br />
route 0.0.0.0 128.0.0.0<br />
route 128.0.0.0 128.0.0.0<br />
socket-flags TCP_NODELAY<br />
keepalive 10 30<br />
dhcp-option DNS 192.168.56.1<br />
</nowiki>}}<br />
<br />
You may need to manually update the contents of [[resolv.conf]] to<br />
<br />
{{hc|/etc/resolv.conf|<br />
nameserver 192.168.56.1<br />
}}<br />
<br />
If you're running NetworkManager, you may need to stop it before running OpenVPN.<br />
<br />
== USB tethering with EasyTether ==<br />
<br />
Get the [http://www.mobile-stream.com/easytether/drivers.html easytether] linux client software. The commands to set it up and run it are as follows.<br />
<br />
# pacman -U easytether-0.8.5-2-x86_64.pkg.tar.xz<br />
# easytether-usb<br />
# dhcpcd tap-easytether<br />
<br />
Make sure you have the EasyTether android app installed on your phone for it to connect to. Note: The Lite app disables some connections and you must have the paid app for full functionality. For this reason, using the AziLink setup is recommended instead.<br />
<br />
== Tethering via Bluetooth ==<br />
<br />
Android (from at least 4.0 onwards, possibly earlier) can provide a Bluetooth personal-area network (PAN) in access point mode.<br />
<br />
NetworkManager can perform this action and handle the network initialisation itself; consult its documentation for more details. <br />
<br />
Alternatively: pair and ensure you can connect your computer and Android device, as described on [[Bluetooth]], then, substituting the address of the device (here given as {{ic|AA_BB_CC_DD_EE_FF}}), do:<br />
<br />
{{bc|<nowiki>$ dbus-send --system --type=method_call --dest=org.bluez /org/bluez/hci0/dev_AA_BB_CC_DD_EE_FF org.bluez.Network1.Connect string:'nap'</nowiki>}}<br />
<br />
This will create a network interface {{ic|bnep0}}. Finally, [[Network configuration|configure a network connection]] on this interface; Android offers DHCP by default.<br />
<br />
== Tethering with SOCKS proxy ==<br />
<br />
With this method tethering is achieved by port forwarding from the phone to the PC. This is suitable only for browsing. For Firefox, you should set {{ic|network.proxy.socks_remote_dns}} to {{ic|true}} in {{ic|about:config}} ( address bar )<br />
<br />
=== Tools needed ===<br />
<br />
* The {{Pkg|android-tools}} and {{Pkg|android-udev}} packages<br />
* USB connection cable from your phone to PC<br />
* Either [http://graha.ms/androidproxy/ Tetherbot] or [https://code.google.com/p/proxoid/ Proxoid]<br />
<br />
=== Instructions ===<br />
<br />
==== Tetherbot ====<br />
<br />
Tetherbot is ''an experimental SOCKS proxy and Port Bouncer that should allow you to connect your laptop to the internet using the internet connection (EDGE, 3G or Wifi) of your T-Mobile G1 Cellphone.'' It is discontinued and its website is down, but still can be accessed from Wayback Machine[https://web.archive.org/web/20171121193952/http://graha.ms/androidproxy/] and its APK can be downloaded from [https://android-apk.org/graha.ms.tunnel/ Android APK website].<br />
<br />
In order to do SOCKS proxy via Tetherbot to connect your browser to the Internet, do:<br />
<br />
# For your phone, open the application ''Tetherbot'' and press the ''Start Socks'' button<br />
# Start your SOCKS proxy by running: {{bc|# adb forward tcp:1080 tcp:1080}}<br />
# Now go to your web browser's proxy settings, set a manual proxy configuration with the proxy host address {{ic|localhost}} and port {{ic|1080}}, leaving the rest blank.<br />
<br />
{{Note|Remember to disable these proxy settings in your web browser if you want to stop using your phone's connection.}}<br />
<br />
==== Proxoid ====<br />
<br />
Follow the instructions demonstrated in the following [http://www.linux-magazine.com/Online/Blogs/Productivity-Sauce/Tether-an-Android-Phone-Using-Proxoid link].</div>Chippey5https://wiki.archlinux.org/index.php?title=Dm-crypt/Encrypting_an_entire_system&diff=588122Dm-crypt/Encrypting an entire system2019-11-07T19:46:17Z<p>Chippey5: Added a user-friendly step after adding hooks to mkinitcpio.conf that easily can be missed by users.</p>
<hr />
<div>{{Lowercase title}}<br />
[[Category:Disk encryption]]<br />
[[Category:Installation process]]<br />
[[de:Systemverschlüsselung mit dm-crypt]]<br />
[[es:Dm-crypt (Español)/Encrypting an entire system]]<br />
[[ja:Dm-crypt/システム全体の暗号化]]<br />
[[pl:Dm-crypt/Encrypting an entire system]]<br />
<br />
The following are examples of common scenarios of full system encryption with ''dm-crypt''. They explain all the adaptations that need to be done to the normal [[Installation guide|installation procedure]]. All the necessary tools are on the [https://www.archlinux.org/download/ installation image].<br />
<br />
== Overview ==<br />
<br />
Securing a root filesystem is where ''dm-crypt'' excels, feature and performance-wise. Unlike selectively encrypting non-root filesystems, an encrypted root filesystem can conceal information such as which programs are installed, the usernames of all user accounts, and common data-leakage vectors such as [[mlocate]] and {{ic|/var/log/}}. Furthermore, an encrypted root filesystem makes tampering with the system far more difficult, as everything except the [[boot loader]] and (usually) the kernel is encrypted.<br />
<br />
All scenarios illustrated in the following share these advantages, other pros and cons differentiating them are summarized below:<br />
<br />
{| class="wikitable"<br />
! Scenarios<br />
! Advantages<br />
! Disadvantages<br />
|----------------------------------------------------------<br />
| [[#LUKS on a partition]]<br />
shows a basic and straight-forward set-up for a fully LUKS encrypted root.<br />
|<br />
* Simple partitioning and setup<br />
|<br />
* Inflexible; disk-space to be encrypted has to be pre-allocated<br />
|----------------------------------------------------------<br />
| [[#LVM on LUKS]]<br />
achieves partitioning flexibility by using LVM inside a single LUKS encrypted partition.<br />
|<br />
* Simple partitioning with knowledge of LVM<br />
* Only one key required to unlock all volumes (e.g. easy resume-from-disk setup)<br />
* Volume layout not transparent when locked<br />
* Easiest method to allow [[dm-crypt/Swap encryption#With suspend-to-disk support|suspension to disk]]<br />
|<br />
* LVM adds an additional mapping layer and hook<br />
* Less useful, if a singular volume should receive a separate key<br />
|----------------------------------------------------------<br />
| [[#LUKS on LVM]]<br />
uses dm-crypt only after the LVM is setup.<br />
|<br />
* LVM can be used to have encrypted volumes span multiple disks<br />
* Easy mix of un-/encrypted volume groups<br />
|<br />
* Complex; changing volumes requires changing encryption mappers too<br />
* Volumes require individual keys<br />
* LVM layout is transparent when locked<br />
|----------------------------------------------------------<br />
| [[#LUKS on software RAID]]<br />
uses dm-crypt only after RAID is setup.<br />
|<br />
* Analogous to LUKS on LVM<br />
|<br />
* Analogous to LUKS on LVM<br />
|----------------------------------------------------------<br />
| [[#Plain dm-crypt]]<br />
uses dm-crypt plain mode, i.e. without a LUKS header and its options for multiple keys. <br>This scenario also employs USB devices for {{ic|/boot}} and key storage, which may be applied to the other scenarios.<br />
|<br />
* Data resilience for cases where a LUKS header may be damaged<br />
* Allows [[Wikipedia:Disk encryption#Full disk encryption|Full Disk Encryption]]<br />
* Helps addressing [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)|problems]] with SSDs<br />
|<br />
* High care to all encryption parameters is required<br />
* Single encryption key and no option to change it<br />
|----------------------------------------------------------<br />
| [[#Encrypted boot partition (GRUB)]]<br />
shows how to encrypt the boot partition using the GRUB bootloader. <br> This scenario also employs an EFI system partition, which may be applied to the other scenarios.<br />
|<br />
* Same advantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* Less data is left unencrypted, i.e. the boot loader and the EFI system partition, if present<br />
|<br />
* Same disadvantages as the scenario the installation is based on (LVM on LUKS for this particular example)<br />
* More complicated configuration<br />
* Not supported by other boot loaders<br />
|----------------------------------------------------------<br />
| [[#Btrfs subvolumes with swap]]<br />
shows how to encrypt a [[Btrfs]] system, including the {{ic|/boot}} directory, also adding a partition for swap, on UEFI hardware.<br />
|<br />
* Similar advantages as [[#Encrypted boot partition (GRUB)]]<br />
* Availability of Btrfs' features<br />
|<br />
* Similar disadvantages as [[#Encrypted boot partition (GRUB)]]<br />
|}<br />
<br />
While all above scenarios provide much greater protection from outside threats than encrypted secondary filesystems, they also share a common disadvantage: any user in possession of the encryption key is able to decrypt the entire drive, and therefore can access other users' data. If that is of concern, it is possible to use a combination of blockdevice and stacked filesystem encryption and reap the advantages of both. See [[Disk encryption]] to plan ahead.<br />
<br />
See [[dm-crypt/Drive preparation#Partitioning]] for a general overview of the partitioning strategies used in the scenarios.<br />
<br />
Another area to consider is whether to set up an encrypted swap partition and what kind. See [[dm-crypt/Swap encryption]] for alternatives.<br />
<br />
If you anticipate to protect the system's data not only against physical theft, but also have a requirement of precautions against logical tampering, see [[dm-crypt/Specialties#Securing the unencrypted boot partition]] for further possibilities after following one of the scenarios.<br />
<br />
For [[solid state drive]]s you might want to consider enabling TRIM support, but be warned, there are potential security implications. See [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]] for more information.<br />
<br />
{{Warning|<br />
* In any scenario, never use file system repair software such as [[fsck]] directly on an encrypted volume, or it will destroy any means to recover the key used to decrypt your files. Such tools must be used on the decrypted (opened) device instead.<br />
* For the LUKS2 format:<br />
** [[GRUB]] does not support LUKS2.[https://savannah.gnu.org/bugs/?55093] Use LUKS1 on partitions that GRUB needs to access.<br />
** The LUKS2 format has a high RAM usage per design, defaulting to 1GB per encrypted mapper. Machines with low RAM and/or multiple LUKS2 partitions unlocked in parallel may error on boot. See the {{ic|--pbkdf-memory}} option to control memory usage.[https://gitlab.com/cryptsetup/cryptsetup/issues/372]<br />
}}<br />
<br />
== LUKS on a partition ==<br />
<br />
This example covers a full system encryption with ''dm-crypt'' + LUKS in a simple partition layout:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------+------------------------+-----------------------+<br />
| Boot partition | LUKS2 encrypted system | Optional free space |<br />
| | partition | for additional |<br />
| | | partitions or swap |<br />
| /boot | / | to be setup later |<br />
| | | |<br />
| | /dev/mapper/cryptroot | |<br />
| |------------------------| |<br />
| /dev/sda1 | /dev/sda2 | |<br />
+-----------------------+------------------------+-----------------------+<br />
</nowiki>}}<br />
<br />
The first steps can be performed directly after booting the Arch Linux install image.<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
Then create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}) and {{ic|/boot}} ({{ic|/dev/sda1}}). See [[Partitioning]].<br />
<br />
=== Preparing non-boot partitions ===<br />
<br />
The following commands create and mount the encrypted root partition. They correspond to the procedure described in detail in [[dm-crypt/Encrypting a non-root file system#Partition]] (which, despite the title, ''can'' be applied to root partitions, as long as [[#Configuring mkinitcpio|mkinitcpio]] and the [[#Configuring the boot loader|boot loader]] are correctly configured).<br />
If you want to use particular non-default encryption options (e.g. cipher, key length), see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|encryption options]] before executing the first command:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sda2<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
Check the mapping works as intended:<br />
<br />
# umount /mnt<br />
# cryptsetup close cryptroot<br />
# cryptsetup open /dev/sda2 cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
If you created separate partitions (e.g. {{ic|/home}}), these steps have to be adapted and repeated for all of them, ''except'' for {{ic|/boot}}. See [[dm-crypt/Encrypting a non-root file system#Automated unlocking and mounting]] on how to handle additional partitions at boot.<br />
<br />
Note that each blockdevice requires its own passphrase. This may be inconvenient, because it results in a separate passphrase to be input during boot. An alternative is to use a keyfile stored in the system partition to unlock the separate partition via {{ic|crypttab}}. See [[dm-crypt/Device encryption#Using LUKS to format partitions with a keyfile]] for instructions.<br />
<br />
=== Preparing the boot partition ===<br />
<br />
What you do have to setup is a non-encrypted {{ic|/boot}} partition, which is needed for a encrypted root. For an ordinary boot partition on BIOS systems, for example, execute:<br />
<br />
# mkfs.ext4 /dev/sda1<br />
<br />
or for an [[EFI system partition]] on UEFI systems:<br />
<br />
# mkfs.fat -F32 /dev/sda1<br />
<br />
Afterwards create the directory for the mountpoint and mount the partition:<br />
<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Mounting the devices ===<br />
<br />
At [[Installation guide#Mount the file systems]] you will have to mount the mapped devices, not the actual partitions. Of course {{ic|/boot}}, which is not encrypted, will still have to be mounted directly.<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|keymap}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]. If the default US keymap is fine for you, you can omit the {{ic|keymap}} hook.<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' filesystems fsck)<br />
<br />
Depending on which other hooks are used, the order may be relevant. See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
Generate a new kernel image after editing [[mkinitcpio.conf]], otherwise the kernel will be unaware that the disk needs to be unencrypted on init:<br />
<br />
# mkinitcpio -p linux<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptroot root=/dev/mapper/cryptroot<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptroot root=/dev/mapper/cryptroot<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda2}}. See [[Persistent block device naming]] for details.<br />
<br />
== LVM on LUKS ==<br />
<br />
The straight-forward method is to set up [[LVM]] on top of the encrypted partition instead of the other way round. Technically the LVM is setup inside one big encrypted blockdevice. Hence, the LVM is not transparent until the blockdevice is unlocked and the underlying volume structure is scanned and mounted during boot.<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+-----------------------------------------------------------------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot partition |<br />
| | | | | |<br />
| [SWAP] | / | /home | | /boot |<br />
| | | | | |<br />
| /dev/MyVolGroup/swap | /dev/MyVolGroup/root | /dev/MyVolGroup/home | | |<br />
|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _| | (may be on |<br />
| | | other device) |<br />
| LUKS2 encrypted partition | | |<br />
| /dev/sda1 | | /dev/sdb1 |<br />
+-----------------------------------------------------------------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Note|While using the {{ic|encrypt}} hook this method does not allow you to span the logical volumes over multiple disks; either use the [[sd-encrypt]] or see [[dm-crypt/Specialties#Modifying the encrypt hook for multiple partitions]].}}<br />
<br />
{{Tip|Two variants of this setup:<br />
* Instructions at [[dm-crypt/Specialties#Encrypted system using a detached LUKS header]] use this setup with a detached LUKS header on a USB device to achieve a two factor authentication with it.<br />
* Instructions at [[dm-crypt/Specialties#Encrypted /boot and a detached LUKS header on USB]] use this setup with a detached LUKS header, encrypted {{ic|/boot}} partition, and encrypted keyfile all on a USB device.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
{{Tip|When using the [[GRUB]] boot loader for BIOS booting from a [[GPT]] disk, create a [[BIOS boot partition]].}}<br />
<br />
Create a partition to be mounted at {{ic|/boot}} with a size of 200 MiB or more.<br />
<br />
{{Tip|UEFI systems can use the [[EFI system partition]] for {{ic|/boot}}.}}<br />
<br />
Create a partition which will later contain the encrypted container.<br />
<br />
Create the LUKS encrypted container at the "system" partition. Enter the chosen password twice.<br />
<br />
# cryptsetup luksFormat /dev/sda1<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda1 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
Create a physical volume on top of the opened LUKS container:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
<br />
Create the volume group named {{ic|MyVolGroup}} (or whatever you want), adding the previously created physical volume to it:<br />
<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
<br />
Create all your logical volumes on the volume group:<br />
<br />
# lvcreate -L 8G MyVolGroup -n swap<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
Format your filesystems on each logical volume:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mkswap /dev/MyVolGroup/swap<br />
<br />
Mount your filesystems:<br />
<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The bootloader loads the kernel, [[initramfs]], and its own configuration files from the {{ic|/boot}} directory. Any filesystem on a disk that can be read by the bootloader is eligible.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
<br />
{{Tip|When opting to keep {{ic|/boot}} on an [[EFI system partition]] the recommended formatting is<br />
<br />
# mkfs.fat -F32 /dev/sdb1<br />
<br />
}}<br />
<br />
Create the directory {{ic|/mnt/boot}}:<br />
<br />
# mkdir /mnt/boot<br />
<br />
Mount the partition to {{ic|/mnt/boot}}:<br />
<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following kernel parameter needs to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':cryptlvm root=/dev/MyVolGroup/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=cryptlvm root=/dev/MyVolGroup/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda1}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
== LUKS on LVM ==<br />
<br />
To use encryption on top of [[LVM]], the LVM volumes are set up first and then used as the base for the encrypted partitions. This way, a mixture of encrypted and non-encrypted volumes/partitions is possible as well.<br />
{{tip|Unlike [[#LVM on LUKS]], this method allows normally spanning the logical volumes over multiple disks. }}<br />
<br />
The following short example creates a LUKS on LVM setup and mixes in the use of a key-file for the /home partition and temporary crypt volumes for {{ic|/tmp}} and {{ic|/swap}}. The latter is considered desirable from a security perspective, because no potentially sensitive temporary data survives the reboot, when the encryption is re-initialised. If you are experienced with LVM, you will be able to ignore/replace LVM and other specifics according to your plan.<br />
<br />
If you want to span a logical volume over multiple disks that have already been set up, or expand the logical volume for {{ic|/home}} (or any other volume), a procedure to do so is described in [[dm-crypt/Specialties#Expanding LVM on multiple disks]]. It is important to note that the LUKS encrypted container has to be resized as well.<br />
<br />
{{Expansion|The intro of this scenario needs some adjustment now that a comparison has been added to [[#Overview]]. A suggested structure is to make it similar to the [[#LUKS on a partition]] intro.}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Partitioning scheme:<br />
<br />
{{Text art|<nowiki><br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
| Boot partition | dm-crypt plain encrypted volume | LUKS2 encrypted volume | LUKS2 encrypted volume |<br />
| | | | |<br />
| /boot | [SWAP] | / | /home |<br />
| | | | |<br />
| | /dev/mapper/swap | /dev/mapper/root | /dev/mapper/home |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | /dev/MyVolGroup/cryptswap | /dev/MyVolGroup/cryptroot | /dev/MyVolGroup/crypthome |<br />
| |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|<br />
| | |<br />
| /dev/sda1 | /dev/sda2 |<br />
+----------------+-------------------------------------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
Randomise {{ic|/dev/sda2}} according to [[dm-crypt/Drive preparation#dm-crypt wipe on an empty disk or partition]].<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
# pvcreate /dev/sda2<br />
# vgcreate MyVolGroup /dev/sda2<br />
# lvcreate -L 32G -n cryptroot MyVolGroup<br />
# lvcreate -L 500M -n cryptswap MyVolGroup<br />
# lvcreate -L 500M -n crypttmp MyVolGroup<br />
# lvcreate -l 100%FREE -n crypthome MyVolGroup<br />
<br />
# cryptsetup luksFormat /dev/MyVolGroup/cryptroot<br />
# cryptsetup open /dev/MyVolGroup/cryptroot root<br />
# mkfs.ext4 /dev/mapper/root<br />
# mount /dev/mapper/root /mnt<br />
<br />
More information about the encryption options can be found in [[dm-crypt/Device encryption#Encryption options for LUKS mode]].<br />
Note that {{ic|/home}} will be encrypted in [[#Encrypting logical volume /home]].<br />
<br />
{{Tip|If you ever have to access the encrypted root from the Arch-ISO, the above {{ic|open}} action will allow you to after the [[LVM#Logical Volumes do not show up|LVM shows up]].}}<br />
<br />
=== Preparing the boot partition ===<br />
<br />
# dd if=/dev/zero of=/dev/sda1 bs=1M status=progress<br />
# mkfs.ext4 /dev/sda1<br />
# mkdir /mnt/boot<br />
# mount /dev/sda1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|lvm2}} and {{ic|encrypt}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''lvm2''' '''encrypt''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to unlock the encrypted root partition at boot, the following [[kernel parameters]] need to be set by the boot loader:<br />
<br />
cryptdevice=UUID=''device-UUID'':root root=/dev/mapper/root<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
rd.luks.name=''device-UUID''=root root=/dev/mapper/root<br />
<br />
The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/MyVolGroup/cryptroot}}. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details.<br />
<br />
=== Configuring fstab and crypttab ===<br />
<br />
Both [[crypttab]] and [[fstab]] entries are required to both unlock the device and mount the filesystems, respectively. The following lines will re-encrypt the temporary filesystems on each reboot:<br />
<br />
{{hc|/etc/crypttab|2=<br />
swap /dev/MyVolGroup/cryptswap /dev/urandom swap,cipher=aes-xts-plain64,size=256<br />
tmp /dev/MyVolGroup/crypttmp /dev/urandom tmp,cipher=aes-xts-plain64,size=256<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/root / ext4 defaults 0 1<br />
/dev/sda1 /boot ext4 defaults 0 2<br />
/dev/mapper/tmp /tmp tmpfs defaults 0 0<br />
/dev/mapper/swap none swap sw 0 0<br />
}}<br />
<br />
=== Encrypting logical volume /home ===<br />
<br />
Since this scenario uses LVM as the primary and dm-crypt as secondary mapper, each encrypted logical volume requires its own encryption. Yet, unlike the temporary filesystems configured with volatile encryption above, the logical volume for {{ic|/home}} should of course be persistent. The following assumes you have rebooted into the installed system, otherwise you have to adjust paths.<br />
To save on entering a second passphrase at boot, a [[dm-crypt/Device encryption#Keyfiles|keyfile]] is created:<br />
<br />
# mkdir -m 700 /etc/luks-keys<br />
# dd if=/dev/random of=/etc/luks-keys/home bs=1 count=256 status=progress<br />
<br />
The logical volume is encrypted with it:<br />
<br />
# cryptsetup luksFormat -v /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
# cryptsetup -d /etc/luks-keys/home open /dev/MyVolGroup/crypthome home<br />
# mkfs.ext4 /dev/mapper/home<br />
# mount /dev/mapper/home /home<br />
<br />
The encrypted mount is configured in both [[crypttab]] and [[fstab]]:<br />
<br />
{{hc|/etc/crypttab|<br />
home /dev/MyVolGroup/crypthome /etc/luks-keys/home<br />
}}<br />
<br />
{{hc|/etc/fstab|<br />
/dev/mapper/home /home ext4 defaults 0 2<br />
}}<br />
<br />
== LUKS on software RAID ==<br />
<br />
This example is based on a real-world setup for a workstation class laptop equipped with two SSDs of equal size, and an additional HDD for bulk storage. The end result is LUKS1 based full disk encryption (including {{ic|/boot}}) for all drives, with the SSDs in a [[RAID|RAID0]] array, and keyfiles used to unlock all encryption after [[GRUB]] is given a correct passphrase at boot.<br />
<br />
This setup utilizes a very simplistic partitioning scheme, with all the available RAID storage being mounted at {{ic|/}} (no separate {{ic|/boot}} partition), and the decrypted HDD being mounted at {{ic|/data}}.<br />
<br />
Please note that regular [[System backup|backups]] are very important in this setup. If either of the SSDs fail, the data contained in the RAID array will be practically impossible to recover. You may wish to select a different [[RAID#Standard RAID levels|RAID level]] if fault tolerance is important to you. <br />
<br />
The encryption is not deniable in this setup.<br />
<br />
For the sake of the instructions below, the following block devices are used:<br />
<br />
/dev/sda = first SSD<br />
/dev/sdb = second SSD<br />
/dev/sdc = HDD<br />
<br />
{{Text art|<nowiki><br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
| BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | BIOS boot partition | EFI system partition | LUKS1 encrypted volume | | LUKS2 encrypted volume |<br />
| | | | | | | | | |<br />
| | /efi | / | | | /efi | / | | /data |<br />
| | | | | | | | | |<br />
| | | /dev/mapper/cryptroot | | | | /dev/mapper/cryptroot | | |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ | |<br />
| | RAID1 array (part 1 of 2) | RAID0 array (part 1 of 2) | | | RAID1 array (part 2 of 2) | RAID0 array (part 2 of 2) | | |<br />
| | | | | | | | | |<br />
| | /dev/md/ESP | /dev/md/root | | | /dev/md/ESP | /dev/md/root | | /dev/mapper/cryptdata |<br />
| +---------------------------+---------------------------+ | +---------------------------+---------------------------+ +---------------------------+<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 | | /dev/sdb1 | /dev/sdb2 | /dev/sdb3 | | /dev/sdc1 |<br />
+---------------------+---------------------------+---------------------------+ +---------------------+---------------------------+---------------------------+ +---------------------------+<br />
</nowiki>}}<br />
<br />
Be sure to substitute them with the appropriate device designations for your setup, as they may be different.<br />
<br />
=== Preparing the disks ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] with GPT, create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
In the remaining space on the drive create a partition ({{ic|/dev/sda3}} in this example) for "Linux RAID". Choose partition type ID {{ic|fd}} for MBR or partition type GUID {{ic|A19D880F-05FC-4D3B-A006-743F0F84911E}} for GPT.<br />
<br />
Once partitions have been created on {{ic|/dev/sda}}, the following commands can be used to clone them to {{ic|/dev/sdb}}.<br />
<br />
# sfdisk -d /dev/sda > sda.dump<br />
# sfdisk /dev/sdb < sda.dump<br />
<br />
The HDD is prepared with a single Linux partition covering the whole drive at {{ic|/dev/sdc1}}.<br />
<br />
=== Building the RAID array ===<br />
<br />
Create the RAID array for the SSDs.<br />
<br />
{{Note|<br />
* All parts of an EFI system partition RAID array must be individually usable, that means that ESP can only placed in a RAID1 array.<br />
* The RAID superblock must be placed at the end of the EFI system partition using {{ic|1=--metadata=1.0}}, otherwise the firmware will not be able to access the partition.<br />
}}<br />
<br />
# mdadm --create --verbose --level=1 --metadata=1.0 --raid-devices=2 /dev/md/ESP /dev/sda2 /dev/sdb2<br />
<br />
This example utilizes RAID0 for root, you may wish to substitute a different level based on your preferences or requirements.<br />
<br />
# mdadm --create --verbose --level=0 --metadata=1.2 --raid-devices=2 /dev/md/root /dev/sda3 /dev/sdb3<br />
<br />
=== Preparing the block devices ===<br />
<br />
As explained in [[dm-crypt/Drive preparation]], the devices are wiped with random data utilizing {{ic|/dev/zero}} and a crypt device with a random key. Alternatively, you could use {{ic|dd}} with {{ic|/dev/random}} or {{ic|/dev/urandom}}, though it will be much slower.<br />
<br />
# cryptsetup open --type plain /dev/md/root container --key-file /dev/random<br />
# dd if=/dev/zero of=/dev/mapper/container bs=1M status=progress<br />
# cryptsetup close container<br />
<br />
And repeat above for the HDD ({{ic|/dev/sdc1}} in this example).<br />
<br />
Set up encryption for {{ic|/dev/md/root}}:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup -y -v luksFormat --type luks1 /dev/md/root<br />
# cryptsetup open /dev/md/root cryptroot<br />
# mkfs.ext4 /dev/mapper/cryptroot<br />
# mount /dev/mapper/cryptroot /mnt<br />
<br />
And repeat for the HDD:<br />
<br />
# cryptsetup -y -v luksFormat /dev/sdc1<br />
# cryptsetup open /dev/sdc1 cryptdata<br />
# mkfs.ext4 /dev/mapper/cryptdata<br />
# mkdir /mnt/data<br />
# mount /dev/mapper/cryptdata /mnt/data<br />
<br />
For UEFI systems, set up the EFI system partition:<br />
<br />
# mkfs.fat -F32 /dev/md/ESP<br />
# mount /dev/md/ESP /mnt/efi<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure [[GRUB]] for the LUKS1 encrypted system by editing {{ic|/etc/default/grub}} with the following:<br />
<br />
GRUB_CMDLINE_LINUX="cryptdevice=/dev/md/root:cryptroot"<br />
GRUB_ENABLE_CRYPTODISK=y<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details.<br />
<br />
Complete the GRUB install to both SSDs (in reality, installing only to {{ic|/dev/sda}} will work).<br />
<br />
# grub-install --target=i386-pc /dev/sda<br />
# grub-install --target=i386-pc /dev/sdb<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
=== Creating the keyfiles ===<br />
<br />
The next steps save you from entering your passphrase twice when you boot the system (once so GRUB can unlock the LUKS1 device, and second time once the initramfs assumes control of the system). This is done by creating a [[dm-crypt/Device encryption#Keyfiles|keyfile]] for the encryption and adding it to the initramfs image to allow the encrypt hook to unlock the root device. See [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] for details.<br />
<br />
* Create the [[dm-crypt/Device encryption#Keyfiles|keyfile]] and add the key to {{ic|/dev/md/root}}.<br />
* Create another keyfile for the HDD ({{ic|/dev/sdc1}}) so it can also be unlocked at boot. For convenience, leave the passphrase created above in place as this can make recovery easier if you ever need it. Edit {{ic|/etc/crypttab}} to decrypt the HDD at boot. See [[Dm-crypt/System configuration#Unlocking with a keyfile]].<br />
<br />
=== Configuring the system ===<br />
<br />
Edit [[fstab]] to mount the cryptroot and cryptdata block devices and the ESP:<br />
<br />
/dev/mapper/cryptroot / ext4 rw,noatime 0 1<br />
/dev/mapper/cryptdata /data ext4 defaults 0 2<br />
/dev/md/ESP /efi vfat rw,relatime,codepage=437,iocharset=iso8859-1,shortname=mixed,utf8,tz=UTC,errors=remount-ro 0 2<br />
<br />
Save the RAID configuration:<br />
<br />
# mdadm --detail --scan >> /etc/mdadm.conf<br />
<br />
Edit [[mkinitcpio.conf]] to include your keyfile and add the proper hooks:<br />
<br />
FILES=(/crypto_keyfile.bin)<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''mdadm_udev''' '''encrypt''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details.<br />
<br />
== Plain dm-crypt ==<br />
<br />
Contrary to LUKS, dm-crypt ''plain'' mode does not require a header on the encrypted device: this scenario exploits this feature to set up a system on an unpartitioned, encrypted disk that will be indistinguishable from a disk filled with random data, which could allow [[Wikipedia:Deniable encryption|deniable encryption]]. See also [[wikipedia:Disk encryption#Full disk encryption]].<br />
<br />
Note that if full-disk encryption is not required, the methods using LUKS described in the sections above are better options for both system encryption and encrypted partitions. LUKS features like key management with multiple passphrases/key-files or re-encrypting a device in-place are unavailable with ''plain'' mode.<br />
<br />
''Plain'' dm-crypt encryption can be more resilient to damage than LUKS, because it does not rely on an encryption master-key which can be a single-point of failure if damaged. However, using ''plain'' mode also requires more manual configuration of encryption options to achieve the same cryptographic strength. See also [[Disk encryption#Cryptographic metadata]]. Using ''plain'' mode could also be considered if concerned with the problems explained in [[dm-crypt/Specialties#Discard/TRIM support for solid state drives (SSD)]].<br />
<br />
{{Tip|If headerless encryption is your goal but you are unsure about the lack of key-derivation with ''plain'' mode, then two alternatives are:<br />
* [[dm-crypt/Specialties#Encrypted system using a detached LUKS header|dm-crypt LUKS mode with a detached header]] by using the ''cryptsetup'' {{ic|--header}} option. It cannot be used with the standard ''encrypt'' hook, but the hook may be modified.<br />
* [[tcplay]] which offers headerless encryption but with the PBKDF2 function.<br />
}}<br />
<br />
The scenario uses two USB sticks:<br />
<br />
* one for the boot device, which also allows storing the options required to open/unlock the plain encrypted device in the boot loader configuration, since typing them on each boot would be error prone;<br />
* another for the encryption key file, assuming it stored as raw bits so that to the eyes of an unaware attacker who might get the usbkey the encryption key will appear as random data instead of being visible as a normal file. See also [[Wikipedia:Security through obscurity]], follow [[dm-crypt/Device encryption#Keyfiles]] to prepare the keyfile.<br />
<br />
The disk layout is:<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+ +----------------+ +----------------+<br />
| Logical volume 1 | Logical volume 2 | Logical volume 3 | | Boot device | | Encryption key |<br />
| | | | | | | file storage |<br />
| / | [SWAP] | /home | | /boot | | (unpartitioned |<br />
| | | | | | | in example) |<br />
| /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home | | /dev/sdb1 | | /dev/sdc |<br />
|----------------------+----------------------+----------------------| |----------------| |----------------|<br />
| disk drive /dev/sda encrypted using plain mode and LVM | | USB stick 1 | | USB stick 2 |<br />
+--------------------------------------------------------------------+ +----------------+ +----------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* It is also possible to use a single USB key physical device:<br />
** By putting the key on another partition (/dev/sdb2) of the USB storage device (/dev/sdb).<br />
** By copying the keyfile to the initramfs directly. An example keyfile {{ic|/etc/keyfile}} gets copied to the initramfs image by setting {{ic|1=FILES=(/etc/keyfile)}} in {{ic|/etc/mkinitcpio.conf}}. The way to instruct the {{ic|encrypt}} hook to read the keyfile in the initramfs image is using {{ic|rootfs:}} prefix before the filename, e.g. {{ic|1=cryptkey=rootfs:/etc/keyfile}}.<br />
* Another option is using a passphrase with good [[Disk encryption#Choosing a strong passphrase|entropy]].<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
It is vital that the mapped device is filled with random data. In particular this applies to the scenario use case we apply here.<br />
<br />
See [[dm-crypt/Drive preparation]] and [[dm-crypt/Drive preparation#dm-crypt specific methods]]<br />
<br />
=== Preparing the non-boot partitions ===<br />
<br />
See [[dm-crypt/Device encryption#Encryption options for plain mode]] for details.<br />
<br />
Using the device {{ic|/dev/sda}}, with the aes-xts cipher with a 512 bit key size and using a keyfile we have the following options for this scenario:<br />
<br />
# cryptsetup --cipher=aes-xts-plain64 --offset=0 --key-file=/dev/sdc --key-size=512 open --type plain /dev/sda cryptlvm<br />
<br />
Unlike encrypting with LUKS, the above command must be executed ''in full'' whenever the mapping needs to be re-established, so it is important to remember the cipher, and key file details.<br />
<br />
We can now check a mapping entry has been made for {{ic|/dev/mapper/cryptlvm}}:<br />
<br />
# fdisk -l<br />
<br />
{{Tip|A simpler alternative to using LVM, advocated in the cryptsetup FAQ for cases where LVM is not necessary, is to just create a filesystem on the entirety of the mapped dm-crypt device.}} <br />
<br />
Next, we setup [[LVM]] logical volumes on the mapped device. See [[LVM#Installing Arch Linux on LVM]] for further details:<br />
<br />
# pvcreate /dev/mapper/cryptlvm<br />
# vgcreate MyVolGroup /dev/mapper/cryptlvm<br />
# lvcreate -L 32G MyVolGroup -n root<br />
# lvcreate -L 10G MyVolGroup -n swap<br />
# lvcreate -l 100%FREE MyVolGroup -n home<br />
<br />
We format and mount them and activate swap. See [[File systems#Create a file system]] for further details:<br />
<br />
# mkfs.ext4 /dev/MyVolGroup/root<br />
# mkfs.ext4 /dev/MyVolGroup/home<br />
# mount /dev/MyVolGroup/root /mnt<br />
# mkdir /mnt/home<br />
# mount /dev/MyVolGroup/home /mnt/home<br />
# mkswap /dev/MyVolGroup/swap<br />
# swapon /dev/MyVolGroup/swap<br />
<br />
=== Preparing the boot partition ===<br />
<br />
The {{ic|/boot}} partition can be installed on the standard vfat partition of a USB stick, if required. But if manual partitioning is needed, then a small 200 MiB partition is all that is required. Create the partition using a [[Partitioning#Partitioning tools|partitioning tool]] of your choice.<br />
<br />
Create a [[filesystem]] on the partition intended for {{ic|/boot}}, if it is not already formatted as vfat:<br />
<br />
# mkfs.ext4 /dev/sdb1<br />
# mkdir /mnt/boot<br />
# mount /dev/sdb1 /mnt/boot<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base udev autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring the boot loader ===<br />
<br />
In order to boot the encrypted root partition, the following [[kernel parameters]] need to be set by the boot loader (note that 64 is the number of bytes in 512 bits):<br />
<br />
cryptdevice=/dev/disk/by-id/''disk-ID-of-sda'':cryptlvm cryptkey=/dev/disk/by-id/''disk-ID-of-sdc'':0:64 crypto=:aes-xts-plain64:512:0:<br />
<br />
The {{ic|''disk-ID-of-'''disk'''''}} refers to the id of the referenced disk. See [[Persistent block device naming]] for details.<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] for details and other parameters that you may need.<br />
<br />
{{Tip|If using GRUB, you can install it on the same USB as the {{ic|/boot}} partition with:<br />
<br />
# grub-install --recheck /dev/sdb<br />
<br />
}}<br />
<br />
=== Post-installation ===<br />
<br />
You may wish to remove the USB sticks after booting. Since the {{ic|/boot}} partition is not usually needed, the {{ic|noauto}} option can be added to the relevant line in {{ic|/etc/fstab}}:<br />
<br />
{{hc|/etc/fstab|<br />
# /dev/sdb1<br />
/dev/sdb1 /boot ext4 '''noauto''',rw,noatime 0 2<br />
}}<br />
<br />
However, when an update to anything used in the initramfs, or a kernel, or the bootloader is required; the {{ic|/boot}} partition must be present and mounted. As the entry in {{ic|fstab}} already exists, it can be mounted simply with:<br />
<br />
# mount /boot<br />
<br />
== Encrypted boot partition (GRUB) ==<br />
<br />
This setup utilizes the same partition layout and configuration as the previous [[#LVM on LUKS]] section, with the difference that the [[GRUB]] boot loader is used since it is capable of booting from an LVM logical volume and a LUKS1-encrypted {{ic|/boot}}. See also [[GRUB#Encrypted /boot]].<br />
<br />
The disk layout in this example is:<br />
<br />
{{Text art|<nowiki><br />
+---------------------+----------------------+----------------------+----------------------+----------------------+<br />
| BIOS boot partition | EFI system partition | Logical volume 1 | Logical volume 2 | Logical volume 3 |<br />
| | | | | |<br />
| | /efi | / | [SWAP] | /home |<br />
| | | | | |<br />
| | | /dev/MyVolGroup/root | /dev/MyVolGroup/swap | /dev/MyVolGroup/home |<br />
| /dev/sda1 | /dev/sda2 |----------------------+----------------------+----------------------+<br />
| unencrypted | unencrypted | /dev/sda3 encrypted using LVM on LUKS1 |<br />
+---------------------+----------------------+--------------------------------------------------------------------+<br />
</nowiki>}}<br />
<br />
{{Tip|<br />
* All scenarios are intended as examples. It is, of course, possible to apply both of the two above distinct installation steps with the other scenarios as well. See also the variants linked in [[#LVM on LUKS]].<br />
* You can use {{ic|cryptboot}} script from {{AUR|cryptboot}} package for simplified encrypted boot management (mounting, unmounting, upgrading packages) and as a defense against [https://www.schneier.com/blog/archives/2009/10/evil_maid_attac.html Evil Maid] attacks with [[Secure Boot#Using your own keys|UEFI Secure Boot]]. For more information and limitations see [https://github.com/xmikos/cryptboot cryptboot project] page.<br />
}}<br />
<br />
=== Preparing the disk ===<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]].<br />
<br />
For [[GRUB#BIOS systems|BIOS systems]] create a [[BIOS boot partition]] with size of 1 MiB for GRUB to store the second stage of BIOS bootloader. Do not mount the partition.<br />
<br />
For [[GRUB#UEFI systems|UEFI systems]] create an [[EFI system partition]] with an appropriate size, it will later be mounted at {{ic|/efi}}.<br />
<br />
Create a partition of type {{ic|8309}}, which will later contain the encrypted container for the LVM.<br />
<br />
Create the LUKS encrypted container:<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
# cryptsetup luksFormat --type luks1 /dev/sda3<br />
<br />
For more information about the available cryptsetup options see the [[dm-crypt/Device encryption#Encryption options for LUKS mode|LUKS encryption options]] prior to above command.<br />
<br />
Your partition layout should look similar to this:<br />
<br />
{{hc|# gdisk -l /dev/sda|<br />
...<br />
Number Start (sector) End (sector) Size Code Name<br />
1 2048 4095 1024.0 KiB EF02 BIOS boot partition<br />
2 4096 1130495 550.0 MiB EF00 EFI System<br />
3 1130496 68239360 32.0 GiB 8309 Linux LUKS<br />
}}<br />
<br />
Open the container:<br />
<br />
# cryptsetup open /dev/sda3 cryptlvm<br />
<br />
The decrypted container is now available at {{ic|/dev/mapper/cryptlvm}}.<br />
<br />
=== Preparing the logical volumes ===<br />
<br />
The LVM logical volumes of this example follow the exact layout as the [[#LVM on LUKS]] scenario. Therefore, please follow [[#Preparing the logical volumes]] above and adjust as required.<br />
<br />
If you plan to boot in UEFI mode, create a mountpoint for the [[EFI system partition]] at {{ic|/efi}} for compatibility with {{ic|grub-install}} and mount it:<br />
<br />
# mkdir /mnt/efi<br />
# mount /dev/sda2 /mnt/efi<br />
<br />
At this point, you should have the following partitions and logical volumes inside of {{ic|/mnt}}:<br />
<br />
{{hc|$ lsblk|<br />
NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT<br />
sda 8:0 0 200G 0 disk<br />
├─sda1 8:1 0 1M 0 part<br />
├─sda2 8:2 0 550M 0 part /mnt/efi<br />
└─sda3 8:3 0 100G 0 part<br />
└─cryptlvm 254:0 0 100G 0 crypt<br />
├─MyVolGroup-swap 254:1 0 8G 0 lvm [SWAP]<br />
├─MyVolGroup-root 254:2 0 32G 0 lvm /mnt<br />
└─MyVolGroup-home 254:3 0 60G 0 lvm /mnt/home<br />
}}<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
Add the {{ic|keyboard}}, {{ic|encrypt}} and {{ic|lvm2}} hooks to [[mkinitcpio.conf]]:<br />
<br />
HOOKS=(base '''udev''' autodetect '''keyboard''' '''keymap''' consolefont modconf block '''encrypt''' '''lvm2''' filesystems fsck)<br />
<br />
If using the [[sd-encrypt]] hook with the systemd-based initramfs, the following needs to be set instead:<br />
<br />
HOOKS=(base '''systemd''' autodetect '''keyboard''' '''sd-vconsole''' modconf block '''sd-encrypt''' '''sd-lvm2''' filesystems fsck)<br />
<br />
See [[dm-crypt/System configuration#mkinitcpio]] for details and other hooks that you may need.<br />
<br />
=== Configuring GRUB ===<br />
<br />
Configure GRUB to allow booting from {{ic|/boot}} on a LUKS1 encrypted partition:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_ENABLE_CRYPTODISK=y<br />
}}<br />
<br />
Set the kernel parameters, so that the initramfs can unlock the encrypted root partition. Using the {{ic|encrypt}} hook:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... cryptdevice=UUID=''device-UUID'':cryptlvm ..."<br />
}}<br />
<br />
If using the [[sd-encrypt]] hook, the following need to be set instead:<br />
<br />
{{hc|/etc/default/grub|2=<br />
GRUB_CMDLINE_LINUX="... rd.luks.name=''device-UUID''=cryptlvm ..."<br />
}}<br />
<br />
See [[dm-crypt/System configuration#Boot loader]] and [[GRUB#Encrypted /boot]] for details. The {{ic|''device-UUID''}} refers to the UUID of {{ic|/dev/sda3}} (the partition which holds the lvm containing the root filesystem). See [[Persistent block device naming]].<br />
<br />
[[GRUB#Installation_2|install GRUB]] to the mounted ESP for UEFI booting:<br />
<br />
# grub-install --target=x86_64-efi --efi-directory=/efi --bootloader-id=GRUB --recheck<br />
<br />
[[GRUB#Installation|install GRUB]] to the disk for BIOS booting:<br />
<br />
# grub-install --target=i386-pc --recheck /dev/sda<br />
<br />
Generate GRUB's [[GRUB#Generate the main configuration file|configuration]] file:<br />
<br />
# grub-mkconfig -o /boot/grub/grub.cfg<br />
<br />
If all commands finished without errors, GRUB should prompt for the passphrase to unlock the {{ic|/dev/sda3}} partition after the next reboot.<br />
<br />
=== Avoiding having to enter the passphrase twice ===<br />
<br />
{{Merge|Dm-crypt/Device encryption#With a keyfile embedded in the initramfs|Too much duplicated content, too much detail here for this overview page.|section=Security Issue with Grub Keyfile}}<br />
<br />
While GRUB asks for a passphrase to unlock the LUKS1 encrypted partition after above instructions, the partition unlock is not passed on to the initramfs. Hence, you have to enter the passphrase twice at boot: once for GRUB and once for the initramfs.<br />
<br />
This section deals with extra configuration to let the system boot by only entering the passphrase once, in GRUB. This is accomplished by [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs|with a keyfile embedded in the initramfs]].<br />
<br />
First create a keyfile and add it as LUKS key:<br />
<br />
# dd bs=512 count=4 if=/dev/random of=/root/cryptlvm.keyfile iflag=fullblock<br />
# chmod 000 /root/cryptlvm.keyfile<br />
# chmod 600 /boot/initramfs-linux*<br />
# cryptsetup -v luksAddKey /dev/sda3 /root/cryptlvm.keyfile<br />
<br />
Add the keyfile to the initramfs image:<br />
<br />
{{hc|/etc/mkinitcpio.conf|2=<br />
FILES=(/root/cryptlvm.keyfile)<br />
}}<br />
<br />
Set the following kernel parameters to unlock the LUKS partition with the keyfile. Using the {{ic|encrypt}} hook:<br />
<br />
GRUB_CMDLINE_LINUX="... cryptkey=rootfs:/root/cryptlvm.keyfile"<br />
<br />
Or, using the [[sd-encrypt]] hook:<br />
<br />
GRUB_CMDLINE_LINUX="... rd.luks.key=''device-UUID''=/root/cryptlvm.keyfile"<br />
<br />
If for some reason the keyfile fails to unlock the boot partition, systemd will fallback to ask for a passphrase to unlock and, in case that is correct, continue booting.<br />
<br />
{{Tip|If you want to encrypt the {{ic|/boot}} partition to protect against offline tampering threats, the [[dm-crypt/Specialties#mkinitcpio-chkcryptoboot|mkinitcpio-chkcryptoboot]] hook has been contributed to help.}}<br />
<br />
== Btrfs subvolumes with swap ==<br />
<br />
The following example creates a full system encryption with LUKS1 using [[Btrfs]] subvolumes to [[Btrfs#Mounting subvolumes|simulate partitions]].<br />
<br />
If using UEFI, an [[EFI system partition]] (ESP) is required. {{ic|/boot}} itself may reside on {{ic|/}} and be encrypted; however, the ESP itself cannot be encrypted. In this example layout, the ESP is {{ic|/dev/sda1}} and is mounted at {{ic|/efi}}. {{ic|/boot}} itself is located on the system partition, {{ic|/dev/sda2}}.<br />
<br />
Since {{ic|/boot}} resides on the LUKS1 encrypted {{ic|/}}, [[GRUB]] must be used as the bootloader because only GRUB can load modules necessary to decrypt {{ic|/boot}} (e.g., crypto.mod, cryptodisk.mod and luks.mod).<br />
<br />
Additionally an optional plain-encrypted [[swap]] partition is shown.<br />
<br />
{{Warning|Do not use a [[swap file]] instead of a separate partition on Linux kernels before v5.0, because this may result in data loss. See [[Btrfs#Swap file]].}}<br />
<br />
{{Text art|<nowiki><br />
+----------------------+----------------------+----------------------+<br />
| EFI system partition | System partition | Swap partition |<br />
| unencrypted | LUKS1-encrypted | plain-encrypted |<br />
| | | |<br />
| /efi | / | [SWAP] |<br />
| /dev/sda1 | /dev/sda2 | /dev/sda3 |<br />
|----------------------+----------------------+----------------------+<br />
</nowiki>}}<br />
<br />
=== Preparing the disk ===<br />
<br />
{{Note|It is not possible to use btrfs partitioning as described in [[Btrfs#Partitionless Btrfs disk]] when using LUKS. Traditional partitioning must be used, even if it is just to create one partition.}}<br />
<br />
Prior to creating any partitions, you should inform yourself about the importance and methods to securely erase the disk, described in [[dm-crypt/Drive preparation]]. If you are using [[UEFI]] create an [[EFI system partition]] with an appropriate size. It will later be mounted at {{ic|/efi}}. If you are going to create an encrypted swap partition, create the partition for it, but do '''not''' mark it as swap, since plain ''dm-crypt'' will be used with the partition.<br />
<br />
Create the needed partitions, at least one for {{ic|/}} (e.g. {{ic|/dev/sda2}}). See the [[Partitioning]] article.<br />
<br />
=== Preparing the system partition ===<br />
<br />
==== Create LUKS container ====<br />
<br />
{{Warning|GRUB does not support LUKS2. Use LUKS1 ({{ic|1=--type luks1}}) on partitions that GRUB needs to access.}}<br />
<br />
Follow [[dm-crypt/Device encryption#Encrypting devices with LUKS mode]] to setup {{ic|/dev/sda2}} for LUKS. See the [[dm-crypt/Device encryption#Encryption options for LUKS mode]] before doing so for a list of encryption options.<br />
<br />
==== Unlock LUKS container ====<br />
<br />
Now follow [[dm-crypt/Device encryption#Unlocking/Mapping LUKS partitions with the device mapper]] to unlock the LUKS container and map it.<br />
<br />
==== Format mapped device ====<br />
<br />
Proceed to format the mapped device as described in [[Btrfs#File system on a single device]], where {{ic|''/dev/partition''}} is the name of the mapped device (i.e., {{ic|cryptroot}}) and '''not''' {{ic|/dev/sda2}}.<br />
<br />
==== Mount mapped device ====<br />
<br />
Finally, [[mount]] the now-formatted mapped device (i.e., {{ic|/dev/mapper/cryptroot}}) to {{ic|/mnt}}.<br />
<br />
{{Tip|You may want to use the {{ic|1=compress=lzo}} mount option. See [[Btrfs#Compression]] for more information.}}<br />
<br />
=== Creating btrfs subvolumes ===<br />
<br />
{{Merge|Btrfs|The subvolume layout is not specific to an encrypted system.}}<br />
<br />
==== Layout ====<br />
<br />
[[Btrfs#Subvolumes|Subvolumes]] will be used to simulate partitions, but other (nested) subvolumes will also be created. Here is a partial representation of what the following example will generate:<br />
<br />
{{Text art|<nowiki><br />
subvolid=5 (/dev/sda2)<br />
|<br />
├── @ (mounted as /)<br />
| |<br />
| ├── /bin (directory)<br />
| |<br />
| ├── /home (mounted @home subvolume)<br />
| |<br />
| ├── /usr (directory)<br />
| |<br />
| ├── /.snapshots (mounted @snapshots subvolume)<br />
| |<br />
| ├── /var/cache/pacman/pkg (nested subvolume)<br />
| |<br />
| ├── ... (other directories and nested subvolumes)<br />
|<br />
├── @snapshots (mounted as /.snapshots)<br />
|<br />
├── @home (mounted as /home)<br />
|<br />
└── @... (additional subvolumes you wish to use as mount points)<br />
</nowiki>}}<br />
<br />
This section follows the [[Snapper#Suggested filesystem layout]], which is most useful when used with [[Snapper]]. You should also consult [https://btrfs.wiki.kernel.org/index.php/SysadminGuide#Layout Btrfs Wiki SysadminGuide#Layout].<br />
<br />
==== Create top-level subvolumes ====<br />
<br />
Here we are using the convention of prefixing {{ic|@}} to subvolume names that will be used as mount points, and {{ic|@}} will be the subvolume that is mounted as {{ic|/}}.<br />
<br />
Following the [[Btrfs#Creating a subvolume]] article, create subvolumes at {{ic|/mnt/@}}, {{ic|/mnt/@snapshots}}, and {{ic|/mnt/@home}}.<br />
<br />
Create any additional subvolumes you wish to use as mount points now.<br />
<br />
==== Mount top-level subvolumes ====<br />
<br />
Unmount the system partition at {{ic|/mnt}}.<br />
<br />
Now mount the newly created {{ic|@}} subvolume which will serve as {{ic|/}} to {{ic|/mnt}} using the {{ic|1=subvol=}} mount option. Assuming the mapped device is named {{ic|cryptroot}}, the command would look like:<br />
<br />
# mount -o compress=lzo,subvol=@ /dev/mapper/cryptroot /mnt<br />
<br />
See [[Btrfs#Mounting subvolumes]] for more details.<br />
<br />
Also mount the other subvolumes to their respective mount points: {{ic|@home}} to {{ic|/mnt/home}} and {{ic|@snapshots}} to {{ic|/mnt/.snapshots}}.<br />
<br />
==== Create nested subvolumes ====<br />
<br />
Create any subvolumes you do '''not''' want to have snapshots of when taking a snapshot of {{ic|/}}. For example, you probably do not want to take snapshots of {{ic|/var/cache/pacman/pkg}}. These subvolumes will be nested under the {{ic|@}} subvolume, but just as easily could have been created earlier at the same level as {{ic|@}} according to your preference.<br />
<br />
Since the {{ic|@}} subvolume is mounted at {{ic|/mnt}} you will need to [[create a subvolume]] at {{ic|/mnt/var/cache/pacman/pkg}} for this example. You may have to create any parent directories first.<br />
<br />
Other directories you may wish to do this with are {{ic|/var/abs}}, {{ic|/var/tmp}}, and {{ic|/srv}}.<br />
<br />
==== Mount ESP ====<br />
<br />
If you prepared an EFI system partition earlier, create its mount point and mount it now.<br />
<br />
{{Note|Btrfs snapshots will exclude {{ic|/efi}}, since it is not a btrfs file system.}}<br />
<br />
At the [[Installation guide#Install essential packages|pacstrap]] installation step, the {{Pkg|btrfs-progs}} must be installed in addition to the {{Pkg|base}} [[meta package]].<br />
<br />
=== Configuring mkinitcpio ===<br />
<br />
==== Create keyfile ====<br />
<br />
In order for GRUB to open the LUKS partition without having the user enter his passphrase twice, we will use a keyfile embedded in the initramfs. Follow [[dm-crypt/Device encryption#With a keyfile embedded in the initramfs]] making sure to add the key to {{ic|/dev/sda2}} at the ''luksAddKey'' step.<br />
<br />
==== Edit mkinitcpio.conf ====<br />
<br />
After creating, adding, and embedding the key as described above, add the {{ic|encrypt}} hook to [[mkinitcpio.conf]] as well as any other hooks you require. See [[dm-crypt/System configuration#mkinitcpio]] for detailed information.<br />
<br />
{{Tip|You may want to add {{ic|1=BINARIES=(/usr/bin/btrfs)}} to your {{ic|mkinitcpio.conf}}. See the [[Btrfs#Corruption recovery]] article.}}<br />
<br />
=== Configuring the boot loader ===<br />
<br />
Install [[GRUB]] to {{ic|/dev/sda}}. Then, edit {{ic|/etc/default/grub}} as instructed in the [[GRUB#Additional arguments]] and [[GRUB#Encrypted /boot]], following both the instructions for an encrypted root and boot partition. Finally, generate the GRUB configuration file.<br />
<br />
=== Configuring swap ===<br />
<br />
If you created a partition to be used for encrypted swap, now is the time to configure it. Follow the instructions at [[dm-crypt/Swap encryption]].</div>Chippey5