New Feature: API Key Access!

[eduardogsilva]

Hey everyone,

I'm excited to announce some updates to our API! We now support the following endpoints that you can access using your API key. Below is a detailed list of each endpoint along with usage instructions.

---

1. /api/wireguard_status/

Description:
This endpoint returns the complete, JSON-formatted output of the WireGuard service's wg show command. It provides real-time status information, including interface details, peer connection data, and transfer statistics, all formatted and ready for immediate integration into your monitoring or automation systems.

Usage:

/api/wireguard_status/?key=<your_uuid_here>

---

2. /api/peer_list/

Description:
Returns a detailed list of configured peers for each instance.

Usage:

/api/peer_list/?key=<your_uuid_here>

Instance Filtering:
You can filter the results by instance. By default, all instances are returned. To filter, append the &instance= parameter with a comma-separated list (e.g., wg0,wg1):

/api/peer_list/?key=<your_uuid_here>&instance=wg0,wg1

---

3. /api/instance_info/

Description:
Provides information about the configured wireguard instances

Usage:

/api/instance_info/?key=<your_uuid_here>

Instance Filtering:
Like the peer list endpoint, you can filter by instance. Use the same &instance= parameter:

/api/instance_info/?key=<your_uuid_here>&instance=wg0,wg1

---

Generating an API Key

Your API key must be a valid UUID. You can generate one using the following commands:

• Outside the Container:

  cat /proc/sys/kernel/random/uuid > /var/lib/docker/volumes/wireguard_webadmin_wireguard/_data/api_key

• Inside the Container:

  cat /proc/sys/kernel/random/uuid > /etc/wireguard/api_key

Disabling the API Key

If you ever need to disable your API key, simply generate a new one or delete the api_key file.

---

I released these features in the latest version while working on an integration of my own. Feel free to explore them and share any cool projects you build using this functionality.

Cheers!

[eduardogsilva]

Hi there! 👋

I'm sharing a straightforward use case of the API that displays WireGuard peer information. Whether you're fetching data by a peer's public key or a more memorable name, this app is user-friendly and easy to implement. Below, you’ll find instructions on setting up and running the Flask application, along with how to use it effectively.

Flask Application Setup

First, ensure Flask is installed in your environment. If not, install it using pip:

pip install Flask

Create a file named app.py in your project directory and paste the following Flask application code into it:

from flask import Flask, request
import requests

app = Flask(__name__)

# Example mapping data. Replace with an external source if necessary.
PEERS = [
    {"peer_name": "normanbates", "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    {"peer_name": "hanniballecter", "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    {"peer_name": "jacktorrance", "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    # Add more peers as needed
]

@app.route('/')
def wireguard_status():
    peer = request.args.get('peer')
    peer_name = request.args.get('peer_name')
    
    if peer_name:
        # Finds the public_key based on the peer's name
        peer = next((p['public_key'] for p in PEERS if p['peer_name'] == peer_name), None)
        if not peer:
            return "Peer not found", 404
    
    # Replace this URL with the real endpoint from where you are getting the WireGuard data
    wireguard_endpoint = 'https://example.com/api/wireguard_status/?key=<your_key>'
    response = requests.get(wireguard_endpoint)
    if response.status_code != 200:
        return "Error fetching WireGuard endpoint", 500
    
    data = response.json()
    
    # Attempting to find the data for a specific peer
    for interface, peers in data.items():
        peer_data = peers.get(peer)
        if peer_data:
            break
    else:
        return "Peer data not found", 404
    
    # Creating a simple HTML view
    html = "<h1>Peer Status</h1>"
    for key, value in peer_data.items():
        if isinstance(value, dict):  # For fields like 'transfer', which are dictionaries
            html += f"<p><b>{key.capitalize()}:</b><br>"
            for sub_key, sub_value in value.items():
                html += f"{sub_key.capitalize()}: {sub_value}<br>"
            html += "</p>"
        else:
            html += f"<p><b>{key.capitalize()}:</b> {value}</p>"
    
    return html

if __name__ == '__main__':
    app.run(debug=True)

Make sure to replace 'http://example.com/api/wireguard' with the actual endpoint URL from where you intend to fetch the WireGuard data.

Running the Application

To run the application, execute:

flask run

This command starts a local server, typically accessible at http://127.0.0.1:5000/.

Using the application

• Fetching Information by Public Key:

  http://127.0.0.1:5000/?peer=<public_key>
  

  Replace <public_key> with the actual peer's public key.

• Fetching Information by Custom Name:

  http://127.0.0.1:5000/?peer_name=<name>
  

  Replace <name> with the name you've associated with a peer in the PEERS list.

Create easy to remember peer name (optional)

To facilitate memorable URLs, map custom names to public keys within the PEERS list in the app.py:

PEERS = [
    {"peer_name": "normanbates", "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    {"peer_name": "hanniballecter", "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    {"peer_name": "jacktorrance", "public_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    # Add more peers as needed
]

This approach allows for friendly and convenient access to peer data without the need to remember or distribute public keys.

This small app is just a simple example of how to consume and use the endpoint.

Happy coding and networking! 🚀

Edit: I will not be actively supporting this app. It's just a simple example of how to use the api.

[kamilner]

The API looks very cool, but I have a question:

wireguard_webadmin has a peer name already which is captured when the peer is defined. Could this not be exposed as a standard field within the output of /api/wireguard_status/

For example:

{
  "wg0": {
    "/hrOeQgW+HwnHq7WQ0cO//HwmhDL6Bh3EXxMHgvFWGI=": {
      "name": "normanbates",
      "allowed-ips": [
        "10.188.0.2/32"
      ],
      "latest-handshakes": "0",
      "transfer": {
        "tx": 0,
        "rx": 0
      },
      "endpoints": "(none)"
    }
  }
}

The flask app is interesting, but it requires a separate lookup of friendly name to public key.

The usage I am looking at is for a centralised monitoring platform which we currently have discovering Wireguard tunnels and monitoring them using shell wgcommands along with some comments in the wg0.conf config file which contains the peer name.

Using wireguared_webadmin we could do the same using the api if the name was exposed as I describe above.

[eduardogsilva]

Hello @kamilner

I've just released an update including the peer list. I also edited this discussion to include the information on the main message.

Cheers!

[kamilner]

Hi @eduardogsilva
That's great. I will give this a try next week and provide feedback on it.

[eduardogsilva]

Hi @eduardogsilva That's great. I will give this a try next week and provide feedback on it.

I've also added some extra peer information too. Just in case someone else needs it.

Cheers!

[kamilner]

Hi @eduardogsilva
This looks good. But it would also be useful if the peer_list also indicated which wireguard instance it was associated with, including the instance name and the interface. Would this be possible?

[kamilner]

Also, it may be useful to have another endpoint to discover the wireguard instances, (e.g. "instance_info") which returned the instance config, which might look something like this:

{   "instances": [
        {
            "name": "wireguard1",
            "interface": "wg0",
            "public_key": "QdCuyeEsIiilJooOgUlFZ05l4c2oV80Gspu/NDxAb2Y=",
            ... other config, probably except private key
        }
    ]
}

[eduardogsilva]

Hello @kamilner !

Thank you for your feedback. I just released this on the latest version.

The instance information can be found at: /api/instance_info/

both endpoints support instance filtering (defaults to all). Just use &instance= (wg0,wg1.... all)

Cheers!