updated docs
James Batt
4 years ago
parent
763675628e
commit
7d039ce89e
@ -0,0 +1,8 @@
|
||||
package cmd
|
||||
|
||||
// Command represents a wg-access-server
|
||||
// subcommand module
|
||||
type Command interface {
|
||||
Name() string
|
||||
Run()
|
||||
}
|
||||
Binary file not shown.
@ -0,0 +1,53 @@
|
||||
# Configuration
|
||||
|
||||
You can configure wg-access-server using environment variables, cli flags or a config file
|
||||
taking precedence over one another in that order.
|
||||
|
||||
The default configuration should work out of the box if you're just looking to try it out.
|
||||
|
||||
The only required configuration is an admin password and a wireguard private key. The admin
|
||||
password can be anything you like. You can generate a wireguard private key by
|
||||
[following the official docs](https://www.wireguard.com/quickstart/#key-generation).
|
||||
|
||||
TLDR:
|
||||
|
||||
```bash
|
||||
wg genkey
|
||||
```
|
||||
|
||||
The config file format is `yaml` and an example is provided [below](#the-config-file-configyaml).
|
||||
|
||||
Here's what you can configure:
|
||||
|
||||
| Environment Variable | CLI Flag | Config File Path | Required | Default (docker) | Description |
|
||||
| -------------------------- | ------------------------- | ---------------------- | -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `WG_CONFIG` | `--config` | `loglevel` | | `info` | Global log level |
|
||||
| `WG_ADMIN_USERNAME` | `--admin-username` | `adminUsername` | | `admin` | The admin account username |
|
||||
| `WG_ADMIN_PASSWORD` | `--admin-password` | `adminPassword` | Yes | | The admin account password |
|
||||
| `WG_PORT` | `--port` | `port` | | `8000` | The port the web ui will listen on (http) |
|
||||
| `WG_EXTERNAL_HOST` | `--external-host` | `externalHost` | | | The external domain for the server (e.g. https://www.mydomain.com) |
|
||||
| `WG_STORAGE` | `--storage` | `storage` | | `sqlite3:///data/db.sqlite3` | A storage backend connection string. See [storage docs](./3-storage.md) |
|
||||
| `WG_DISABLE_METADATA` | `--disable-metadata` | `disableMetadata` | | `false` | Turn off collection of device metadata logging. Includes last handshake time and RX/TX bytes only. |
|
||||
| `WG_WIREGUARD_ENABLED` | `--wireguard-enabled` | `wireguard.enabled` | | `true` | Enable/disable the wireguard server. Useful for development on non-linux machines. |
|
||||
| `WG_WIREGUARD_INTERFACE` | `--wireguard-interface` | `wireguard.interface` | | `wg0` | The wireguard network interface name |
|
||||
| `WG_WIREGUARD_PRIVATE_KEY` | `--wireguard-private-key` | `wireguard.privateKey` | Yes | | The wireguard private key. This value is required and must be stable. If this value changes all devices must re-register. |
|
||||
| `WG_WIREGUARD_PORT` | `--wireguard-port` | `wireguard.port` | | `51820` | The wireguard server port (udp) |
|
||||
| `WG_VPN_CIDR` | `--vpn-cidr` | `vpn.cidr` | | `10.44.0.0/24` | The VPN network range. VPN clients will be assigned IP addresses in this range. |
|
||||
| `WG_VPN_GATEWAY_INTERFACE` | `--vpn-gateway-interface` | `vpn.gatewayInterface` | | _default gateway interface (e.g. eth0)_ | The VPN gateway interface. VPN client traffic will be forwarded to this interface. |
|
||||
| `WG_VPN_ALLOWED_IPS` | `--vpn-allowed-ips` | `vpn.allowedIPs` | | `0.0.0.0/1, 128.0.0.0/1` | Allowed IPs that clients may route through this VPN. This will be set in the client's WireGuard connection file and routing is also enforced by the server using iptables. |
|
||||
| `WG_DNS_ENABLED` | `--dns-enabled` | `dns.enabled` | | `true` | Enable/disable the embedded DNS proxy server. This is enabled by default and allows VPN clients to avoid DNS leaks by sending all DNS requests to wg-access-server itself. |
|
||||
| `WG_DNS_UPSTREAM` | `--dns-upstream` | `dns.upstream` | | _resolveconf autodetection or 1.1.1.1_ | The upstream DNS server to proxy DNS requests to. By default the host machine's resolveconf configuration is used to find it's upstream DNS server, otherwise 1.1.1.1 (cloudflare) is used. |
|
||||
|
||||
## The Config File (config.yaml)
|
||||
|
||||
Here's an example config file to get started with.
|
||||
|
||||
```yaml
|
||||
loglevel: info
|
||||
storage: sqlite3:///data/db.sqlite3
|
||||
wireguard:
|
||||
privateKey: "<some-key>"
|
||||
dns:
|
||||
upstream:
|
||||
- "8.8.8.8"
|
||||
```
|
||||
@ -1,13 +1,13 @@
|
||||
# Storage Backends
|
||||
# Storage
|
||||
|
||||
wg-access-server supports 4 storage backends suitable for different use-cases.
|
||||
wg-access-server supports 4 storage backends.
|
||||
|
||||
| Backend | Persistent | Supports HA | Use Case |
|
||||
|----------|------------|-------------|----------------------------------------|
|
||||
| memory | ❌ | ❌ | Local development |
|
||||
| sqlite3 | ✔️ | ❌ | Production - single instance deployments |
|
||||
| postgres | ✔️ | ✔️ (soon) | Production - multi instance deployments |
|
||||
| mysql | ✔️ | ❌ | Production - single instance deployments |
|
||||
| Backend | Persistent | Supports HA | Use Case |
|
||||
| -------- | ---------- | ----------- | ---------------------------------------- |
|
||||
| memory | ❌ | ❌ | Local development |
|
||||
| sqlite3 | ✔️ | ❌ | Production - single instance deployments |
|
||||
| postgres | ✔️ | ✔️ (soon) | Production - multi instance deployments |
|
||||
| mysql | ✔️ | ❌ | Production - single instance deployments |
|
||||
|
||||
## Backends
|
||||
|
||||
@ -0,0 +1,75 @@
|
||||
# Authentication
|
||||
|
||||
Authentication is pluggable in wg-access-server. Community contributions are welcome
|
||||
for supporting new authentication backends.
|
||||
|
||||
If you're just getting started you can skip over this section and rely on the default
|
||||
admin account instead.
|
||||
|
||||
If your authentication system is not yet supported and you aren't quite ready to
|
||||
contribute you could try using a project like [dex](https://github.com/dexidp/dex)
|
||||
or SaaS provider like [Auth0](https://auth0.com/) which supports a wider variety of
|
||||
authentication protocols. wg-access-server can happily be an OpenID Connect client
|
||||
to a larger solution like this.
|
||||
|
||||
The following authentication backends are currently supported:
|
||||
|
||||
| Backend | Use Case | Notes |
|
||||
| -------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| Basic Auth | Deployments with a static list of users. Simple and great for self-hosters and home use-cases | The wg-access-server admin account is powered by this backend |
|
||||
| OpenID Connect | For delegating authentication to an existing identity solution | |
|
||||
| Gitlab | For delegating authentication to gitlab. Supports self-hosted Gitlab. | |
|
||||
|
||||
## Configuration
|
||||
|
||||
Currently authentication providers are only configurable via the wg-access-server
|
||||
config file (config.yaml).
|
||||
|
||||
Below is an annotated example config section that can be used as a starting point.
|
||||
|
||||
```yaml
|
||||
# Configure zero or more authentication backends
|
||||
auth:
|
||||
# HTTP Basic Authentication
|
||||
basic:
|
||||
# Users is a list of htpasswd encoded username:password pairs
|
||||
# supports BCrypt, Sha, Ssha, Md5
|
||||
# You can create a user using "htpasswd -nB <username>"
|
||||
users: []
|
||||
oidc:
|
||||
# A name for the backend (can be anything you want)
|
||||
name: "My OIDC Backend"
|
||||
# Should point to the OIDC Issuer (excluding /.well-known/openid-configuration)
|
||||
issuer: "https://identity.example.com"
|
||||
# Your OIDC client credentials which would be provided by your OIDC provider
|
||||
clientID: "<client-id>"
|
||||
clientSecret: "<client-secret>"
|
||||
# List of scopes to request defaults to ["openid"]
|
||||
scopes:
|
||||
- openid
|
||||
# The full redirect URL
|
||||
# The path can be almost anything as long as it doesn't
|
||||
# conflict with a path that the web UI uses.
|
||||
# /callback is recommended.
|
||||
redirectURL: "https://wg-access-server.example.com/callback"
|
||||
# You can optionally restrict access to users with an email address
|
||||
# that matches an allowed domain.
|
||||
# If empty or omitted then all email domains will be allowed.
|
||||
emailDomains:
|
||||
- example.com
|
||||
# This is an advanced feature that allows you to define
|
||||
# OIDC claim mapping expressions.
|
||||
# This feature is used to define wg-access-server admins
|
||||
# based off a claim in your OIDC token
|
||||
# See https://github.com/Knetic/govaluate/blob/9aa49832a739dcd78a5542ff189fb82c3e423116/MANUAL.md for how to write rules
|
||||
userClaimsRules:
|
||||
admin: "'WireguardAdmins' in group_membership"
|
||||
gitlab:
|
||||
name: "My Gitlab Backend"
|
||||
baseURL: "https://mygitlab.example.com"
|
||||
clientID: "<client-id>"
|
||||
clientSecret: "<client-secret>"
|
||||
redirectURL: "https:///wg-access-server.example.com/callback"
|
||||
emailDomains:
|
||||
- example.com
|
||||
```
|
||||
@ -1,136 +0,0 @@
|
||||
# Configuration
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|-----------------------|-------------|
|
||||
| CONFIG | Set the config file path |
|
||||
| WIREGUARD_PRIVATE_KEY | Set the wireguard private key |
|
||||
| STORAGE | Set the directory where device config will be persisted |
|
||||
| ADMIN_USERNAME | Set the username (subject) for the admin account |
|
||||
| ADMIN_PASSWORD | Set the admin account's password. The admin account will be a basic-auth user. Leave blank if your admin username authenticates via a configured authentication backend. |
|
||||
| UPSTREAM_DNS | Set the upstream DNS server to proxy client DNS requests to. If empty, resolv.conf will be respected. |
|
||||
| LOG_LEVEL | Set the server's log level (debug, **info**, error, critical) |
|
||||
| DISABLE_METADATA | If true, the server will not record device level metadata such as the last handshake time, tx/rx data size |
|
||||
|
||||
## CLI Flags
|
||||
|
||||
All environment variables can be configured via a
|
||||
CLI flag as well.
|
||||
|
||||
For example you can configure `STORAGE` by passing `--storage="<value>"`.
|
||||
|
||||
## Config File (config.yaml)
|
||||
|
||||
Here's an annotated config file example:
|
||||
|
||||
```yaml
|
||||
# The application's log level.
|
||||
# Can be debug, info, error
|
||||
# Optional, defaults to info
|
||||
loglevel: info
|
||||
# Disable device metadata storage.
|
||||
# Device metadata includes the last handshake time,
|
||||
# total sent/received bytes count, their endpoint IP.
|
||||
# This metadata is captured from wireguard itself.
|
||||
# Disabling this flag will not stop wireguard from capturing
|
||||
# this data.
|
||||
# See stored data here: https://github.com/Place1/wg-access-server/blob/master/internal/storage/contracts.go#L14
|
||||
# Optional, defaults to false.
|
||||
disableMetadata: false
|
||||
# The port that the web ui server (http) will listen on.
|
||||
# Optional, defaults to 8000
|
||||
port: 8000
|
||||
# Directory that VPN devices (WireGuard peers)
|
||||
# What type of storage do you want? inmemory (default), file:///some/directory, or postgres, mysql, sqlite3
|
||||
storage: "memory://"
|
||||
wireguard:
|
||||
# The network interface name for wireguard
|
||||
# Optional, defaults to wg0
|
||||
interfaceName: wg0
|
||||
# The WireGuard PrivateKey
|
||||
# You can generate this value using "$ wg genkey"
|
||||
# If this value is empty then the server will use an in-memory
|
||||
# generated key
|
||||
privateKey: ""
|
||||
# ExternalAddress is the address (without port) that clients use to connect to the wireguard interface
|
||||
# By default, this will be empty and the web ui
|
||||
# will use the current page's origin i.e. window.location.origin
|
||||
# Optional
|
||||
externalHost: ""
|
||||
# The WireGuard ListenPort
|
||||
# Optional, defaults to 51820
|
||||
port: 51820
|
||||
vpn:
|
||||
# CIDR configures a network address space
|
||||
# that client (WireGuard peers) will be allocated
|
||||
# an IP address from.
|
||||
# Optional
|
||||
cidr: "10.44.0.0/24"
|
||||
# GatewayInterface will be used in iptable forwarding
|
||||
# rules that send VPN traffic from clients to this interface
|
||||
# Most use-cases will want this interface to have access
|
||||
# to the outside internet
|
||||
# If not configured then the server will select the default
|
||||
# network interface e.g. eth0
|
||||
# Optional
|
||||
gatewayInterface: ""
|
||||
# The "AllowedIPs" for VPN clients.
|
||||
# This value will be included in client config
|
||||
# files and in server-side iptable rules
|
||||
# to enforce network access.
|
||||
# Optional
|
||||
allowedIPs:
|
||||
- "0.0.0.0/0"
|
||||
dns:
|
||||
# Enable a DNS proxy for VPN clients.
|
||||
# Optional, Defaults to true
|
||||
enabled: true
|
||||
# upstream DNS servers.
|
||||
# that the server-side DNS proxy will forward requests to.
|
||||
# By default /etc/resolv.conf will be used to find upstream
|
||||
# DNS servers.
|
||||
# Optional
|
||||
upstream:
|
||||
- "1.1.1.1"
|
||||
# Auth configures optional authentication backends
|
||||
# to controll access to the web ui.
|
||||
# Devices will be managed on a per-user basis if any
|
||||
# auth backends are configured.
|
||||
# If no authentication backends are configured then
|
||||
# the server will not require any authentication.
|
||||
# It's recommended to make use of basic authentication
|
||||
# or use an upstream HTTP proxy that enforces authentication
|
||||
# Optional
|
||||
auth:
|
||||
# HTTP Basic Authentication
|
||||
basic:
|
||||
# Users is a list of htpasswd encoded username:password pairs
|
||||
# supports BCrypt, Sha, Ssha, Md5
|
||||
# You can create a user using "htpasswd -nB <username>"
|
||||
users: []
|
||||
oidc:
|
||||
name: "" # anything you want
|
||||
issuer: "" # Should point to the oidc url without .well-known
|
||||
clientID: ""
|
||||
clientSecret: ""
|
||||
scopes: null # list of scopes, defaults to ["openid"]
|
||||
redirectURL: "" # full url you want the oidc to redirect to, example: https://vpn-admin.example.com/finish-signin
|
||||
# See https://github.com/Knetic/govaluate/blob/9aa49832a739dcd78a5542ff189fb82c3e423116/MANUAL.md for how to write rules
|
||||
userClaimsRules:
|
||||
admin: "'WireguardAdmins' in group_membership"
|
||||
# Optionally restrict login to users with an allowed email domain
|
||||
# if empty or omitted, any email domain will be allowed.
|
||||
emailDomains:
|
||||
- example.com
|
||||
gitlab:
|
||||
name: ""
|
||||
baseURL: ""
|
||||
clientID: ""
|
||||
clientSecret: ""
|
||||
redirectURL: ""
|
||||
# Optionally restrict login to users with an allowed email domain
|
||||
# if empty or omitted, any email domain will be allowed.
|
||||
emailDomains:
|
||||
- example.com
|
||||
```
|
||||
Loading…
Reference in New Issue