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 |
|
| Backend | Persistent | Supports HA | Use Case |
|
||||||
|----------|------------|-------------|----------------------------------------|
|
| -------- | ---------- | ----------- | ---------------------------------------- |
|
||||||
| memory | ❌ | ❌ | Local development |
|
| memory | ❌ | ❌ | Local development |
|
||||||
| sqlite3 | ✔️ | ❌ | Production - single instance deployments |
|
| sqlite3 | ✔️ | ❌ | Production - single instance deployments |
|
||||||
| postgres | ✔️ | ✔️ (soon) | Production - multi instance deployments |
|
| postgres | ✔️ | ✔️ (soon) | Production - multi instance deployments |
|
||||||
| mysql | ✔️ | ❌ | Production - single instance deployments |
|
| mysql | ✔️ | ❌ | Production - single instance deployments |
|
||||||
|
|
||||||
## Backends
|
## 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