wgctrl

https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl
Admin
wgctrl is a Go package that enables control and configuration of WireGuard secure network tunnel...
Tokens:4,400
Snippets:70
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### WireGuard IOCTL Constants

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Constants representing the IOCTL codes for getting and setting WireGuard configurations.

```go
const (
	IoctlGet = 0xb098c506
	IoctlSet = 0xb098c509
)
```

--------------------------------

### Create a new Client

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wguser

Initializes a new instance of the Client.

```go
func New() (*Client, error)
```

--------------------------------

### Initialize Client

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wglinux

Creates a new Client instance and checks for generic netlink interface availability.

```go
func New() (*Client, bool, error)
```

--------------------------------

### New

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl

Creates a new Client instance to interact with WireGuard devices.

```APIDOC
## func New()

### Description
Creates a new Client instance for managing WireGuard devices.

### Signature
func New() (*Client, error)
```

--------------------------------

### New

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows

Creates a new Client instance for interacting with WireGuardNT.

```APIDOC
### func New()

#### Description
Creates a new Client instance.

#### Signature
`func New() *Client`
```

--------------------------------

### ConfigBuilder Methods

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Methods for building WireGuard configurations.

```go
type ConfigBuilder struct {
	// contains filtered or unexported fields
}

func (builder *ConfigBuilder) AppendAllowedIP(allowedIP *AllowedIP)

func (builder *ConfigBuilder) AppendInterface(interfaze *Interface)

func (builder *ConfigBuilder) AppendPeer(peer *Peer)

func (builder *ConfigBuilder) Interface() (*Interface, uint32)

func (builder *ConfigBuilder) Preallocate(size uint32)
```

--------------------------------

### Client.ConfigureDevice

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows

Configures a specific WireGuard device.

```APIDOC
### func (*Client) ConfigureDevice

#### Description
Configures the specified WireGuard device with the provided configuration.

#### Signature
`func (c *Client) ConfigureDevice(name string, cfg wgtypes.Config) error`
```

--------------------------------

### Define DeviceType and Constants

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Enumeration of supported WireGuard device implementations.

```go
type DeviceType int
```

```go
const (
	Unknown DeviceType = iota
	LinuxKernel
	OpenBSDKernel
	FreeBSDKernel
	WindowsKernel
	Userspace
)
```

--------------------------------

### AllowedIP Methods

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Method to retrieve the next allowed IP in a list.

```go
func (allowedIP *AllowedIP) NextAllowedIP() *AllowedIP
```

--------------------------------

### Configure WireGuard device

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wglinux

Applies a configuration to a specific WireGuard device.

```go
func (c *Client) ConfigureDevice(name string, cfg wgtypes.Config) error
```

--------------------------------

### Interface Structure and Methods

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Structure representing a WireGuard interface and its associated methods.

```go
type Interface struct {
	Flags      InterfaceFlag
	ListenPort uint16
	PrivateKey [32]byte
	PublicKey  [32]byte
	PeerCount  uint32
	// contains filtered or unexported fields
}

func (interfaze *Interface) FirstPeer() *Peer
```

--------------------------------

### Peer Structure and Methods

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Structure representing a WireGuard peer and methods for traversing peer data.

```go
type Peer struct {
	Flags               PeerFlag
	ProtocolVersion     uint32
	PublicKey           [32]byte
	PresharedKey        [32]byte
	PersistentKeepalive uint16

	Endpoint        RawSockaddrInet
	TxBytes         uint64
	RxBytes         uint64
	LastHandshake   uint64
	AllowedIPsCount uint32
	// contains filtered or unexported fields
}

func (peer *Peer) FirstAllowedIP() *AllowedIP

func (peer *Peer) NextPeer() *Peer
```

--------------------------------

### Define Client interface

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wginternal

Defines the methods required to control a WireGuard device, including configuration and retrieval.

```go
type Client interface {
	io.Closer
	Devices() ([]*wgtypes.Device, error)
	Device(name string) (*wgtypes.Device, error)
	ConfigureDevice(name string, cfg wgtypes.Config) error
}
```

--------------------------------

### String Method for DeviceType

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Returns the string representation of a DeviceType.

```go
func (dt DeviceType) String() string
```

--------------------------------

### List all WireGuard devices

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wglinux

Retrieves a list of all available WireGuard devices.

```go
func (c *Client) Devices() ([]*wgtypes.Device, error)
```

--------------------------------

### Client.Devices

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows

Lists all WireGuard devices.

```APIDOC
### func (*Client) Devices

#### Description
Returns a list of all WireGuard devices.

#### Signature
`func (c *Client) Devices() ([]*wgtypes.Device, error)`
```

--------------------------------

### Key Generation and Parsing Functions

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Functions for creating, parsing, and manipulating cryptographic keys.

```go
func GenerateKey() (Key, error)
```

```go
func GeneratePrivateKey() (Key, error)
```

```go
func NewKey(b []byte) (Key, error)
```

```go
func ParseKey(s string) (Key, error)
```

```go
func (k Key) PublicKey() Key
```

```go
func (k Key) String() string
```

--------------------------------

### MustPublicKey Function

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgtest

Generates a new public key, panicking if generation fails.

```go
func MustPublicKey() wgtypes.Key
```

--------------------------------

### Define Config Struct

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Configuration structure for a WireGuard device, using pointers for optional fields.

```go
type Config struct {
	// PrivateKey specifies a private key configuration, if not nil.
	//
	// A non-nil, zero-value Key will clear the private key.
	PrivateKey *Key

	// ListenPort specifies a device's listening port, if not nil.
	ListenPort *int

	// FirewallMark specifies a device's firewall mark, if not nil.
	//
	// If non-nil and set to 0, the firewall mark will be cleared.
	FirewallMark *int

	// ReplacePeers specifies if the Peers in this configuration should replace
	// the existing peer list, instead of appending them to the existing list.
	ReplacePeers bool

	// Peers specifies a list of peer configurations to apply to a device.
	Peers []PeerConfig
}
```

--------------------------------

### Define Client struct

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wglinux

Represents the client structure for accessing Linux WireGuard netlink information.

```go
type Client struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### AddressFamily Type

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Enumeration for protocol family, mapping to windows.AF_* constants.

```go
type AddressFamily uint16
```

--------------------------------

### Retrieve device information

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wglinux

Fetches details for a specific WireGuard device by name.

```go
func (c *Client) Device(name string) (*wgtypes.Device, error)
```

--------------------------------

### Define Key Type

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Represents a 32-byte WireGuard key.

```go
type Key [KeyLen]byte
```

--------------------------------

### Define Device Struct

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Represents the current state and configuration of a WireGuard device.

```go
type Device struct {
	// Name is the name of the device.
	Name string

	// Type specifies the underlying implementation of the device.
	Type DeviceType

	// PrivateKey is the device's private key.
	PrivateKey Key

	// PublicKey is the device's public key, computed from its PrivateKey.
	PublicKey Key

	// ListenPort is the device's network listening port.
	ListenPort int

	// FirewallMark is the device's current firewall mark.
	//
	// The firewall mark can be used in conjunction with firewall software to
	// take action on outgoing WireGuard packets.
	FirewallMark int

	// Peers is the list of network peers associated with this device.
	Peers []Peer
}
```

--------------------------------

### MustPrivateKey Function

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgtest

Generates a new private key, panicking if generation fails.

```go
func MustPrivateKey() wgtypes.Key
```

--------------------------------

### Client.Device

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows

Retrieves information for a specific WireGuard device.

```APIDOC
### func (*Client) Device

#### Description
Retrieves the device information for the device with the given name.

#### Signature
`func (c *Client) Device(name string) (*wgtypes.Device, error)`
```

--------------------------------

### MustPresharedKey Function

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgtest

Generates a new preshared key, panicking if generation fails.

```go
func MustPresharedKey() wgtypes.Key
```

--------------------------------

### MustUDPAddr Function

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgtest

Parses a string into a net.UDPAddr, panicking if the address format is invalid.

```go
func MustUDPAddr(s string) *net.UDPAddr
```

--------------------------------

### RawSockaddrInet Structure and Methods

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Union structure for IPv4/IPv6 addresses and associated helper methods.

```go
type RawSockaddrInet struct {
	Family AddressFamily
	// contains filtered or unexported fields
}

func (addr *RawSockaddrInet) IP() net.IP

func (addr *RawSockaddrInet) Port() uint16

func (addr *RawSockaddrInet) SetIP(ip net.IP, port uint16) error
```

--------------------------------

### AllowedIP Structure

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Structure representing an allowed IP range for a WireGuard peer.

```go
type AllowedIP struct {
	Address       [16]byte
	AddressFamily AddressFamily
	Cidr          uint8
	// contains filtered or unexported fields
}
```

--------------------------------

### Define PeerConfig structure

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Represents configuration parameters for a WireGuard peer. Pointer types are used for fields where the zero value is significant, ensuring only non-nil values are applied.

```go
type PeerConfig struct {
	// PublicKey specifies the public key of this peer.  PublicKey is a
	// mandatory field for all PeerConfigs.
	PublicKey Key

	// Remove specifies if the peer with this public key should be removed
	// from a device's peer list.
	Remove bool

	// UpdateOnly specifies that an operation will only occur on this peer
	// if the peer already exists as part of the interface.
	UpdateOnly bool

	// PresharedKey specifies a peer's preshared key configuration, if not nil.
	//
	// A non-nil, zero-value Key will clear the preshared key.
	PresharedKey *Key

	// Endpoint specifies the endpoint of this peer entry, if not nil.
	Endpoint *net.UDPAddr

	// PersistentKeepaliveInterval specifies the persistent keepalive interval
	// for this peer, if not nil.
	//
	// A non-nil value of 0 will clear the persistent keepalive interval.
	PersistentKeepaliveInterval *time.Duration

	// ReplaceAllowedIPs specifies if the allowed IPs specified in this peer
	// configuration should replace any existing ones, instead of appending them
	// to the allowed IPs list.
	ReplaceAllowedIPs bool

	// AllowedIPs specifies a list of allowed IP addresses in CIDR notation
	// for this peer.
	AllowedIPs []net.IPNet
}
```

--------------------------------

### PeerFlag Constants

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Flags used to define peer configuration properties.

```go
type PeerFlag uint32

const (
	PeerHasPublicKey           PeerFlag = 1 << 0
	PeerHasPresharedKey        PeerFlag = 1 << 1
	PeerHasPersistentKeepalive PeerFlag = 1 << 2
	PeerHasEndpoint            PeerFlag = 1 << 3
	PeerHasProtocolVersion     PeerFlag = 1 << 4
	PeerReplaceAllowedIPs      PeerFlag = 1 << 5
	PeerRemove                 PeerFlag = 1 << 6
	PeerUpdateOnly             PeerFlag = 1 << 7
)
```

--------------------------------

### Close Client connection

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wglinux

Closes the client connection, implementing the wginternal.Client interface.

```go
func (c *Client) Close() error
```

--------------------------------

### MustHexKey Function

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgtest

Decodes a hex-encoded string into a wgtypes.Key, panicking if the decoding fails.

```go
func MustHexKey(s string) wgtypes.Key
```

--------------------------------

### InterfaceFlag Constants

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows/internal/ioctl

Flags used to define interface configuration properties.

```go
type InterfaceFlag uint32

const (
	InterfaceHasPublicKey  InterfaceFlag = 1 << 0
	InterfaceHasPrivateKey InterfaceFlag = 1 << 1
	InterfaceHasListenPort InterfaceFlag = 1 << 2
	InterfaceReplacePeers  InterfaceFlag = 1 << 3
)
```

--------------------------------

### Define Key Length Constant

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

The constant representing the required length for a WireGuard key.

```go
const KeyLen = 32 // wgh.KeyLen
```

--------------------------------

### MustCIDR Function

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgtest

Converts a CIDR string into a net.IPNet structure, panicking if the input is invalid.

```go
func MustCIDR(s string) net.IPNet
```

--------------------------------

### Define Peer structure

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Represents a WireGuard peer associated with a device, containing status and configuration information.

```go
type Peer struct {
	// PublicKey is the public key of a peer, computed from its private key.
	//
	// PublicKey is always present in a Peer.
	PublicKey Key

	// PresharedKey is an optional preshared key which may be used as an
	// additional layer of security for peer communications.
	//
	// A zero-value Key means no preshared key is configured.
	PresharedKey Key

	// Endpoint is the most recent source address used for communication by
	// this Peer.
	Endpoint *net.UDPAddr

	// PersistentKeepaliveInterval specifies how often an "empty" packet is sent
	// to a peer to keep a connection alive.
	//
	// A value of 0 indicates that persistent keepalives are disabled.
	PersistentKeepaliveInterval time.Duration

	// LastHandshakeTime indicates the most recent time a handshake was performed
	// with this peer.
	//
	// A zero-value time.Time indicates that no handshake has taken place with
	// this peer.
	LastHandshakeTime time.Time

	// ReceiveBytes indicates the number of bytes received from this peer.
	ReceiveBytes int64

	// TransmitBytes indicates the number of bytes transmitted to this peer.
	TransmitBytes int64

	// AllowedIPs specifies which IPv4 and IPv6 addresses this peer is allowed
	// to communicate on.
	//
	// 0.0.0.0/0 indicates that all IPv4 addresses are allowed, and ::/0
	// indicates that all IPv6 addresses are allowed.
	AllowedIPs []net.IPNet

	// ProtocolVersion specifies which version of the WireGuard protocol is used
	// for this Peer.
	//
	// A value of 0 indicates that the most recent protocol version will be used.
	ProtocolVersion int
}
```

--------------------------------

### Client.Close

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl

Releases resources associated with the Client.

```APIDOC
## func (*Client) Close()

### Description
Closes the client and releases any underlying system resources.

### Signature
func (c *Client) Close() error
```

--------------------------------

### Define UpdateOnly Error Variable

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/wgtypes

Error returned when the platform lacks kernel support for the PeerConfig UpdateOnly flag.

```go
var ErrUpdateOnlyNotSupported = errors.New("the UpdateOnly flag is not supported by this platform")
```

--------------------------------

### Client.Close

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wgwindows

Closes the WireGuardNT client connection.

```APIDOC
### func (*Client) Close()

#### Description
Closes the client connection.

#### Signature
`func (c *Client) Close() error`
```

--------------------------------

### Define ErrReadOnly sentinel variable

Source: https://pkg.go.dev/golang.zx2c4.com/wireguard/wgctrl/internal/wginternal

Used to indicate that a driver backing a device is read-only, primarily for integration testing.

```go
var ErrReadOnly = errors.New("driver is read-only")
```
Tokens:
Raw