Author image Tobias Bossert
and 1 contributors




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


  • Compatible with your existing setup (no configuration changes needed).

  • A CLI interface with abilities to set, enable, disable and apply your wireguard config(s).

  • A fancy show output which combines the meta-data, 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 Wireguard::WGmeta::Wrapper::Config and Wireguard::WGmeta::Wrapper::Show

  • No external dependencies, runs on plain Perl (>=v5.22)!


        # Build from source
        perl Makefile.PL
        make test
        make install

        # Using `.deb` package (available in the linked git repo)
        sudo dpkg -i wg-meta_X.X.X.deb


  • 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.


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

Please note that all attributes have to be specified in the `wg set` _syntax_, which means _AllowedIPs_ becomes allowed-ips and so on.

        sudo wg-meta show

        # output
        interface: wg0
          State: UP
          ListenPort: 51888
          PublicKey: +qz742hzxD3E5z5QF7VOvleVS1onavQpXBK3NdTh40g=

        +peer: WG_0_PEER_A_PUBLIC_KEY
          Name: testero
          Alias: Dual_stack_peer1
          AllowedIPs: fdc9:281f:04d7:9ee9::1/128,
          endpoint:  latest-handshake: >month ago  transfer-rx: 0.26 MiB  transfer-tx: 1.36 MiB

        # Access using peer
        sudo wg-meta set wg0 peer +qz742hzxD3E5z5QF7VOvleVS1onavQpXBK3NdTh40g= name Fancy_meta_name

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

        # Disable peer
        sudo wg-meta disable wg0 some_alias

        # Enable peer
        sudo wg-meta enable wg0 +qz742hzxD3E5z5QF7VOvleVS1onavQpXBK3NdTh40g=

        # Apply config
        sudo wg-meta apply wg0


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 #+):

        #+Alias = some_alias
        #+Description = Some Desc
        Address =
        ListenPort = 6666
        PrivateKey = WEkEJW3b4TDmRvN+G+K9elzq52/djAXT+LAB6BSEUmM=

        #+Name = Fancy_meta_name
        PublicKey = +qz742hzxD3E5z5QF7VOvleVS1onavQpXBK3NdTh40g=
        AllowedIPs =
        Endpoint =