Fill out readme

README.md

@@ -1,12 +1,58 @@
-### Do not use this Go code.
+# Go Implementation of [WireGuard](https://www.wireguard.com/)
 
-This is not a complete implementation of WireGuard. If you're interested in using WireGuard, use the implementation for Linux [found here](https://git.zx2c4.com/WireGuard/) and described on the [main wireguard website](https://www.wireguard.io/). There is no group of users that should be using the code in this repository here under any circumstances at the moment, not even beta testers or dare devils. It simply isn't complete. However, if you're interested in assisting with the Go development of WireGuard and contributing to this repository, by all means dig in and help out. But users: stay far away, at least for now.
+This is an implementation of WireGuard in Go.
 
--------
+***WARNING:*** This is a work in progress and not ready for prime time, with no official "releases" yet. It is extremely rough around the edges and leaves much to be desired. There are bugs and we are not yet in a position to make claims about its security. Beware.
 
-# Go Implementation of WireGuard
+## Usage
 
-This is a work in progress for implementing WireGuard in Go.
+Most Linux kernel WireGuard users are used to adding an interface with `ip link add wg0 type wireguard`. With wireguard-go, instead simply run:
+
+```
+$ wireguard-go wg0
+```
+
+This will create an interface and fork into the background. To remove the interface, use the usual `ip link del wg0`, or if your system does not support removing interfaces directly, you may instead remove the control socket via `rm -f /var/run/wireguard/wg0.sock`, which will result in wireguard-go shutting down.
+
+To run wireguard-go without forking to the background, pass `-f` or `--foreground`:
+
+```
+$ wireguard-go -f wg0
+```
+
+When an interface is running, you may use [`wg(8)`](https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8) to configure it, as well as the usual `ip(8)` and `ifconfig(8)` commands.
+
+To run with more logging you may set the environment variable `LOG_LEVEL=debug`.
+
+## Platforms
+
+### Linux
+
+This will run on Linux; however **YOU SHOULD NOT RUN THIS ON LINUX**. Instead use the kernel module; see the [installation page](https://www.wireguard.com/install/) for instructions.
+
+### macOS
+
+This runs on macOS using the utun driver. It does not yet support sticky sockets, and won't support fwmarks because of Darwin limitations. Since the utun driver cannot have arbitrary interface names, you must either use `utun[0-9]+` for an explicit interface name or `utun` to have the kernel select one for you. If you choose `utun` as the interface name, and the environment variable `WG_DARWIN_UTUN_NAME_FILE` is defined, then the actual name of the interface chosen by the kernel is written to the file specified by that variable.
+
+### Windows
+
+It is currently a work in progress to strip out the beginnings of an experiment done with the OpenVPN tuntap driver and instead port to the new UWP APIs for tunnels. In other words, this does not *yet* work on Windows.
+
+### FreeBSD
+
+Work in progress, but nothing yet to share.
+
+## Building
+
+You can satisfy dependencies with either `go get -d -v` or `dep ensure -vendor-only`. Then run `make`. As this is a Go project, a `GOPATH` is required. For example, wireguard-go can be built with:
+
+```
+$ git clone https://git.zx2c4.com/wireguard-go
+$ cd wireguard-go
+$ export GOPATH="$PWD/gopath"
+$ go get -d -v
+$ make
+```
 
 ## License