Re: Wanted: Novice Guides
On Wed, Feb 15, 2017 at 5:39 PM, jugs wrote: > Should we put them on a blog or the wireguard site? Either? Both? I'd very much welcome external blogs, since these tend to be good forums for guides that focus on particular platforms and setups. However, if there is some good general-purpose writing that might apply well to everybody, then it seems like the wireguard site could be an okay place for that. ___ WireGuard mailing list WireGuard@lists.zx2c4.com https://lists.zx2c4.com/mailman/listinfo/wireguard
Re: Wanted: Novice Guides
Hi Daniel, On Wed, Feb 15, 2017 at 3:53 PM, Daniel Kahn Gillmor wrote: > A good "novice guide" usually has the following pattern: This is a nice list of suggestions on how to structure guides. Thanks for that. > Those of us who are not novices understand that tools like WireGuard can > be used on a lot of different platforms (c) to perform a lot of > different tasks (a), but how those tasks are carried out might have more > to do with policy details (where do you get the peer's public keys from? > how do you verify that they're the right public keys? How do peers find > each other if there are no stable public IP addresses? How do you > allocate IP addresses for the wg interfaces? Which traffic should each > peer route over which wg interfaces?) than with WireGuard itself. Right. The concepts are simple, and simplify a lot of the things WireGuard is supposed to replace, but they're still somewhat new concepts. That means there's going to need to be explanations and diagrams and good solid descriptions for people who don't even know the prior concepts. > The fact that the WireGuard-specific instructions for any such guide are > likely to be minimal is one of the strengths of WireGuard, i think. But > that also means that any novice guide is going to be at least as much > about non-WireGuard details as it is about WireGuard itself. Right. This also raises the question of the role of WireGuard in general. It's being designed as sort of a fundumental basic build block, on which other tools and simple bash scripts should be built. How much should I build those larger things? (Such as wg-quick.) How much should I wait for others to integrate this into existing utilities (such as NetworkManager or systemd-networkd)? How much should other people simply build new tools ontop of the WireGuard core? I suspect the answer is: all of those things all at once, and then we'll have a flourishing ecosystem. This, though, makes the focus of beginner guides non obvious. > > Jason, what kinds of novice guides are people asking for? "How do I set up my laptop with my server?" "How do I set up my laptop with my home router?" "How do I put it on a RasPi at home and connect to it from the Internet with my laptop?" "How do I hook all my servers together with it?" "What's the difference between a tunnel IP address and an endpoint?" "What do I put in AllowedIPs and what do I put as the interface IP and what's the difference?" "What's the difference between AllowedIPs and the normal routing table?" etc etc ___ WireGuard mailing list WireGuard@lists.zx2c4.com https://lists.zx2c4.com/mailman/listinfo/wireguard
Re: Wanted: Novice Guides
Should we put them on a blog or the wireguard site? -jugs Original Message Subject: Wanted: Novice Guides Local Time: February 15, 2017 9:05 AM UTC Time: February 15, 2017 2:05 PM From: ja...@zx2c4.com To: WireGuard mailing list Hey guys, As WireGuard gets more and more popular, I have more people contacting me about novice guides and blog entries and step by step things. If anybody would be up for writing these or assisting with it, it would be much appreciated. Probably better to tackle this before horribly written guides with bad advice fill the void instead. Jason ___ WireGuard mailing list WireGuard@lists.zx2c4.com https://lists.zx2c4.com/mailman/listinfo/wireguard___ WireGuard mailing list WireGuard@lists.zx2c4.com https://lists.zx2c4.com/mailman/listinfo/wireguard
Re: Wanted: Novice Guides
I think it would be brilliant to see an guide setting up a server on a OpenWRT router, and then setting up a Mac laptop as a roaming client that could connect to the network as required. Unfortunately I do not have much time to help with this, but I believe that this would be a very common use case. Cheers, Paul On Wed, Feb 15, 2017 at 6:53 AM, Daniel Kahn Gillmor wrote: > Hi all-- > > On Wed 2017-02-15 09:05:29 -0500, Jason A. Donenfeld wrote: > > As WireGuard gets more and more popular, I have more people contacting > > me about novice guides and blog entries and step by step things. If > > anybody would be up for writing these or assisting with it, it would > > be much appreciated. Probably better to tackle this before horribly > > written guides with bad advice fill the void instead. > > Agreed about wanting better-written guides to pre-empt terrible ones :) > > A good "novice guide" usually has the following pattern: > > a) Present the specific goal of the guide at a high level (if you think > want X, this is the guide for you) -- the goal should not be > "install WireGuard", which is meaningless to a novice, but something > like one of the following: > > * have two machines establish a secure connection between each other > across the public Internet > > * give my laptop an IP address on my home network no matter where I am > > * allow co-workers to access office resources from the road > > * run a "virtual office" offering secure connections between the > computers of multiple co-workers who are scattered and have no > central physical location > > * operate a public-facing encrypted Internet proxy service > (a.k.a. "VPN provider") > > b) Present frequently-confused *non* use cases (if you think you want > these other things, this is not your guide) > > c) Document assumed platform details (if your examples are only known to > work on Ubuntu 16.10, say so!) > > d) Document steps to take to achieve the goal (these should be very > simple. If it's more than 5 steps, the tools or the platform should > probably be improved) > > e) Diagnostics, troubleshooting and debugging (again, should be > relatively minimal, but should include at least how to check that > things are working, what you might see if they're not working, and > recovery from common failure modes) > > f) Outbound links to learn more (this should include suggestions about > where to file bug reports, and how to follow up on this mailing list) > > > choosing (a) and (c) carefully are kind of critical for even knowing > where to begin if you want to write such a guide for novices. > > Those of us who are not novices understand that tools like WireGuard can > be used on a lot of different platforms (c) to perform a lot of > different tasks (a), but how those tasks are carried out might have more > to do with policy details (where do you get the peer's public keys from? > how do you verify that they're the right public keys? How do peers find > each other if there are no stable public IP addresses? How do you > allocate IP addresses for the wg interfaces? Which traffic should each > peer route over which wg interfaces?) than with WireGuard itself. > > The fact that the WireGuard-specific instructions for any such guide are > likely to be minimal is one of the strengths of WireGuard, i think. But > that also means that any novice guide is going to be at least as much > about non-WireGuard details as it is about WireGuard itself. > > Jason, what kinds of novice guides are people asking for? What kinds of > guides are people on this list interested in writing? > > --dkg > > ___ > WireGuard mailing list > WireGuard@lists.zx2c4.com > https://lists.zx2c4.com/mailman/listinfo/wireguard > > ___ WireGuard mailing list WireGuard@lists.zx2c4.com https://lists.zx2c4.com/mailman/listinfo/wireguard
Re: Wanted: Novice Guides
Hi all-- On Wed 2017-02-15 09:05:29 -0500, Jason A. Donenfeld wrote: > As WireGuard gets more and more popular, I have more people contacting > me about novice guides and blog entries and step by step things. If > anybody would be up for writing these or assisting with it, it would > be much appreciated. Probably better to tackle this before horribly > written guides with bad advice fill the void instead. Agreed about wanting better-written guides to pre-empt terrible ones :) A good "novice guide" usually has the following pattern: a) Present the specific goal of the guide at a high level (if you think want X, this is the guide for you) -- the goal should not be "install WireGuard", which is meaningless to a novice, but something like one of the following: * have two machines establish a secure connection between each other across the public Internet * give my laptop an IP address on my home network no matter where I am * allow co-workers to access office resources from the road * run a "virtual office" offering secure connections between the computers of multiple co-workers who are scattered and have no central physical location * operate a public-facing encrypted Internet proxy service (a.k.a. "VPN provider") b) Present frequently-confused *non* use cases (if you think you want these other things, this is not your guide) c) Document assumed platform details (if your examples are only known to work on Ubuntu 16.10, say so!) d) Document steps to take to achieve the goal (these should be very simple. If it's more than 5 steps, the tools or the platform should probably be improved) e) Diagnostics, troubleshooting and debugging (again, should be relatively minimal, but should include at least how to check that things are working, what you might see if they're not working, and recovery from common failure modes) f) Outbound links to learn more (this should include suggestions about where to file bug reports, and how to follow up on this mailing list) choosing (a) and (c) carefully are kind of critical for even knowing where to begin if you want to write such a guide for novices. Those of us who are not novices understand that tools like WireGuard can be used on a lot of different platforms (c) to perform a lot of different tasks (a), but how those tasks are carried out might have more to do with policy details (where do you get the peer's public keys from? how do you verify that they're the right public keys? How do peers find each other if there are no stable public IP addresses? How do you allocate IP addresses for the wg interfaces? Which traffic should each peer route over which wg interfaces?) than with WireGuard itself. The fact that the WireGuard-specific instructions for any such guide are likely to be minimal is one of the strengths of WireGuard, i think. But that also means that any novice guide is going to be at least as much about non-WireGuard details as it is about WireGuard itself. Jason, what kinds of novice guides are people asking for? What kinds of guides are people on this list interested in writing? --dkg signature.asc Description: PGP signature ___ WireGuard mailing list WireGuard@lists.zx2c4.com https://lists.zx2c4.com/mailman/listinfo/wireguard
