wg-meta

An approach to add metadata to the main wireguard config, written in Perl.

Highlights

• Compatible with your existing setup (no configuration changes needed).
• A CLI interface with abilities to set, enable, disable, apply, add and remove wireguard config nodes.
• A fancy show output which combines metadata, running-config and static-configs.
• Modular structure: The whole parser is independent of the CLI module - and can be used as a standalone library.
• The config parser/writer and as well as the wg show dump parser are independent too. For more info, please refer to their respective POD.
• Concurrent Access support is built-in.
• No external dependencies, runs on plain Perl (>=v5.22)!

Installation

Probably the easiest way is through cpan: https://metacpan.org/release/Wireguard-WGmeta

Build from source

perl Makefile.PL
make test
make install

Using .deb package

sudo dpkg -i wg-meta_X.X.X.deb

Environment variables

• WIREGUARD_HOME: Directory containing the Wireguard configuration -> Make sure the path ends with a /. Defaults to /etc/wireguard/.
• IS_TESTING: When defined, it has the following effects:
  • Commands::Set|Enable|Disable omits the header of the generated configuration files.
  • Line of code is shown for warnings and errors.
• WG_NO_COLOR: If defined, the show command does not prettify the output with colors.
• WGmeta_NO_WG: If defined, no wireguard commands are run

Usage

Intended to use as command wrapper for the wg show and wg set commands. Support for wg-quickis enabled by default.

Please note that non-meta attributes have to be specified in the wg set syntax, which means AllowedIPs becomes allowed-ips and so on.

sudo wg-meta show wg0

# output
interface: wg0
  private-key: WG_0_PEER_B_PRIVATE_KEY
  public-key: wg0d845RRItYcmcEW3i+dqatmja18F2P9ujy+lAtsBM=
  listen-port: 51888
  fwmark: off

peer: IPv6_only1
  public-key: WG_0_PEER_A_PUBLIC_KEY
  preshared-key: PEER_A-PEER_B-PRESHARED_KEY
  allowed-ips: fdc9:281f:04d7:9ee9::1/128
  endpoint: 147.86.207.49:10400
  latest-handshake: >month ago
  transfer-rx: 0.26 MiB
  transfer-tx: 1.36 MiB
  persistent-keepalive: off


# Access using peer (note the '+' before 'name' -> we add a previously unseen attribute)
sudo wg-meta set wg0 peer WG_0_PEER_A_PUBLIC_KEY +name Fancy_meta_name

# Access using alias
sudo wg-meta set wg0 IPv6_only1 +description "Some Desc"

# Lets check our newly set attributes
sudo wg-meta show wg0 name description

# output
interface: wg0
  name: (none)
  description: (none)

peer: IPv6_only1
  name: Fancy_meta_name
  description: Some Desc

# Disable peer
sudo wg-meta disable wg0 IPv6_only1

# Enable peer
sudo wg-meta enable wg0 WG_0_PEER_A_PUBLIC_KEY

# Apply config
sudo wg-meta apply wg0

# Add new peer
# Note: To automatically set the DNS and endpoint address, make sure you add #+DNSHost and #+FQDN to your hosts interface config
wg-meta addpeer wg0 10.60.0.10 alias tobi_laptop

[Interface]
Address = 10.60.0.10
ListenPort = 44544
PrivateKey = PEER_PRIVATE_KEY
DNS = 10.20.0.1
#+Alias = tobi_laptop

[Peer]
PublicKey = HOST_PUBLIC_KEY
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = your.fqdn.con:51888
PersistentKeepalive = 25

Migrating from 0.2.x

With the introduction of version 0.3.x, the way custom attributes work has slightly changed:

• There is no "in-config" name for custom attributes anymore, they are written down as initially defined.
• All predefined custom attributes like name and description have been removed (an exception is the alias attribute). To use your own custom attributes, register them using WGmeta::Wrapper::Config->new([..], $custom_attributes) or when using the CLI interface, by prefixing them with +. As a consequence WGmeta::Wrapper::Config->add_peer() has no name parameter anymore, set additional attributes by calling WGmeta::Wrapper::Config->set()

Under the hood

The main advantage is that this tool is not dependent on any other storage, metadata is stored inside the corresponding wgXX.conf file (Metadata is prefixed with #+):

[Interface]
Address = 10.0.0.7/24
ListenPort = 51888
PrivateKey = WG_0_PEER_B_PRIVATE_KEY

[Peer]
#+Alias = IPv6_only1
#+name = Fancy_meta_name
#+description = Some Desc
PublicKey = WG_0_PEER_A_PUBLIC_KEY
AllowedIPs = fdc9:281f:04d7:9ee9::1/128
Endpoint = wg.example.com

Initial development of this project is sponsored by OETIKER+PARTNER AG