Skip to content

wireguard

ibox.wireguard in the library, ibox wireguard in the CLI.

WireGuard VPN server and its clients.

app_status

app_status() -> str

Get Wireguard application status

server_status

server_status() -> str

Get Wireguard server status

clients

clients() -> str

Get configured Wireguard clients

client_status

client_status(alias: str) -> str

Get specific Wireguard client stats Such as connection status, data transferred, etc. Args: alias (str): client alias name

set_enabled

set_enabled(enable: bool) -> str

Turn WireGuard on or off as a whole, with its server and clients. The web UI has no switch for it.

While it's off, the web UI doesn't offer WireGuard, and set_server_enabled() and add_client() refuse. Turning it off disconnects the VPN clients. The server and its clients stay, and are back unchanged when it's turned on.

Parameters:

Name Type Description Default
enable bool

True to turn WireGuard on, False to turn it off.

required

Returns:

Name Type Description
str str

response content

set_server_enabled

set_server_enabled(enable: bool) -> str

Turn the WireGuard VPN server on or off, like the WireGuard switch in the web UI's VPN settings.

While it's on, the router accepts WireGuard connections from the internet on port 51820 (ListenPort in server_status()). Turning it off disconnects the VPN clients. Like the web UI, turning it on creates the server first if the router doesn't have one yet.

Parameters:

Name Type Description Default
enable bool

True to turn the server on, False to turn it off.

required

Returns:

Name Type Description
str str

response content

add_client

add_client(name: str, endpoint: str | None = None, intranet_access: bool = True) -> str

Add a WireGuard VPN client and get its configuration, like adding a WireGuard account in the web UI.

Import the configuration into the WireGuard app on the phone or computer, as a file or as a QR code (e.g. qrencode -t ansiutf8 < client.conf). Keep it safe: it contains the client's private key, which the router doesn't keep. The client can only connect while the server is on (see set_server_enabled()): unlike the web UI, this doesn't turn the server on, but like the web UI it creates the server if the router has none yet.

Parameters:

Name Type Description Default
name str

3 to 16 letters, digits, - or _, starting with a letter, e.g. "phone".

required
endpoint str | None

where the client finds the router: its public IP address, or a DynDNS host name pointing to it (see dyndns.hosts()). Default: the current public IPv4 address, which may change.

None
intranet_access bool

whether the client may reach the devices in your network, not only the internet. Default is True.

True

Returns:

Name Type Description
str str

response content, with the client's configuration as "status", e.g. {"status": "[Interface]\n..."}

Raises:

Type Description
ValueError

if the name is invalid or taken, there's no endpoint, or the router doesn't return the configuration. A client added before the error is deleted again.

set_client

set_client(name: str, enabled: bool | None = None, intranet_access: bool | None = None) -> str

Turn a WireGuard client on or off, or change whether it may reach the devices in your network.

Parameters:

Name Type Description Default
name str

client name (Alias in clients()).

required
enabled bool | None

False stops the client from connecting. Default: unchanged.

None
intranet_access bool | None

whether the client may reach the devices in your network, not only the internet. Default: unchanged.

None

Returns:

Name Type Description
str str

response content

delete_client

delete_client(name: str) -> str

Delete a WireGuard client. Its configuration stops working.

Parameters:

Name Type Description Default
name str

client name (Alias in clients()).

required

Returns:

Name Type Description
str str

response content