NMSettingWireGuard: libnm Reference Manual

## NMSettingWireGuard NMSettingWireGuard — Describes connection properties for wireguard related options |

## Functions

NMWireGuardPeer * | nm_wireguard_peer_new ()
NMWireGuardPeer * | nm_wireguard_peer_new_clone ()
NMWireGuardPeer * | nm_wireguard_peer_ref ()
void | nm_wireguard_peer_unref ()
void | nm_wireguard_peer_seal ()
gboolean | nm_wireguard_peer_is_sealed ()
const char * | nm_wireguard_peer_get_public_key ()
gboolean | nm_wireguard_peer_set_public_key ()
const char * | nm_wireguard_peer_get_preshared_key ()
gboolean | nm_wireguard_peer_set_preshared_key ()
NMSettingSecretFlags | nm_wireguard_peer_get_preshared_key_flags ()
void | nm_wireguard_peer_set_preshared_key_flags ()
guint16 | nm_wireguard_peer_get_persistent_keepalive ()
void | nm_wireguard_peer_set_persistent_keepalive ()
const char * | nm_wireguard_peer_get_endpoint ()
gboolean | nm_wireguard_peer_set_endpoint ()
guint | nm_wireguard_peer_get_allowed_ips_len ()
const char * | nm_wireguard_peer_get_allowed_ip ()
void | nm_wireguard_peer_clear_allowed_ips ()
gboolean | nm_wireguard_peer_append_allowed_ip ()
gboolean | nm_wireguard_peer_remove_allowed_ip ()
gboolean | nm_wireguard_peer_is_valid ()
int | nm_wireguard_peer_cmp ()
NMSetting * | nm_setting_wireguard_new ()
const char * | nm_setting_wireguard_get_private_key ()
NMSettingSecretFlags | nm_setting_wireguard_get_private_key_flags ()
guint16 | nm_setting_wireguard_get_listen_port ()
guint32 | nm_setting_wireguard_get_fwmark ()
guint | nm_setting_wireguard_get_peers_len ()
NMWireGuardPeer * | nm_setting_wireguard_get_peer ()
NMWireGuardPeer * | nm_setting_wireguard_get_peer_by_public_key ()
void | nm_setting_wireguard_set_peer ()
void | nm_setting_wireguard_append_peer ()
gboolean | nm_setting_wireguard_remove_peer ()
guint | nm_setting_wireguard_clear_peers ()
gboolean | nm_setting_wireguard_get_peer_routes ()
guint32 | nm_setting_wireguard_get_mtu ()
NMTernary | nm_setting_wireguard_get_ip4_auto_default_route ()
NMTernary | nm_setting_wireguard_get_ip6_auto_default_route ()

## Types and Values

#define | NM_WIREGUARD_PUBLIC_KEY_LEN
#define | NM_WIREGUARD_SYMMETRIC_KEY_LEN
#define | NM_SETTING_WIREGUARD_SETTING_NAME
#define | NM_SETTING_WIREGUARD_FWMARK
#define | NM_SETTING_WIREGUARD_LISTEN_PORT
#define | NM_SETTING_WIREGUARD_PRIVATE_KEY
#define | NM_SETTING_WIREGUARD_PRIVATE_KEY_FLAGS
#define | NM_SETTING_WIREGUARD_PEERS
#define | NM_SETTING_WIREGUARD_MTU
#define | NM_SETTING_WIREGUARD_PEER_ROUTES
#define | NM_SETTING_WIREGUARD_IP4_AUTO_DEFAULT_ROUTE
#define | NM_SETTING_WIREGUARD_IP6_AUTO_DEFAULT_ROUTE
#define | NM_WIREGUARD_PEER_ATTR_ALLOWED_IPS
#define | NM_WIREGUARD_PEER_ATTR_ENDPOINT
#define | NM_WIREGUARD_PEER_ATTR_PERSISTENT_KEEPALIVE
#define | NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY
#define | NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY_FLAGS
#define | NM_WIREGUARD_PEER_ATTR_PUBLIC_KEY

## Object Hierarchy

        GBoxed
        ╰── NMWireGuardPeer

## Description

The NMSettingWireGuard object is a NMSetting subclass that contains settings for configuring WireGuard.

## Functions

### nm_wireguard_peer_new ()

    NMWireGuardPeer *
    nm_wireguard_peer_new (void);

#### Returns

a new, default, unsealed NMWireGuardPeer instance.

[transfer full]

Since: 1.16

### nm_wireguard_peer_new_clone ()

    NMWireGuardPeer *
    nm_wireguard_peer_new_clone (const NMWireGuardPeer *self,
                                 gboolean with_secrets);

#### Parameters

self | the NMWireGuardPeer instance to copy. |
with_secrets | if `TRUE`, the preshared-key secrets are copied as well. Otherwise, they will be removed. |

#### Returns

a clone of `self` . This instance is always unsealed.

[transfer full]

Since: 1.16

### nm_wireguard_peer_ref ()

    NMWireGuardPeer *
    nm_wireguard_peer_ref (NMWireGuardPeer *self);

This is not thread-safe.

#### Parameters

self | the NMWireGuardPeer instance. | [allow-none]

#### Returns

returns the input argument `self` after incrementing the reference count.

Since: 1.16

### nm_wireguard_peer_unref ()

    void
    nm_wireguard_peer_unref (NMWireGuardPeer *self);

Drop a reference to `self` . If the last reference is dropped, the instance is freed and all associate data released.

This is not thread-safe.

#### Parameters

self | the NMWireGuardPeer instance. | [allow-none]

Since: 1.16

### nm_wireguard_peer_seal ()

    void
    nm_wireguard_peer_seal (NMWireGuardPeer *self);

Seal the NMWireGuardPeer instance. Afterwards, it is a bug to call all functions that modify the instance (except ref/unref). A sealed instance cannot be unsealed again, but you can create an unsealed copy with `nm_wireguard_peer_new_clone()`.

#### Parameters

self | the NMWireGuardPeer instance |

Since: 1.16

### nm_wireguard_peer_is_sealed ()

    gboolean
    nm_wireguard_peer_is_sealed (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

whether `self` is sealed or not.

Since: 1.16

### nm_wireguard_peer_get_public_key ()

    const char *
    nm_wireguard_peer_get_public_key (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

the public key or `NULL` if unset.

[transfer none]

Since: 1.16

### nm_wireguard_peer_set_public_key ()

    gboolean
    nm_wireguard_peer_set_public_key (NMWireGuardPeer *self,
                                      const char *public_key,
                                      gboolean accept_invalid);

Reset the public key. Note that if the public key is valid, it will be normalized (which may or may not modify the set value).

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
public_key | the new public key or `NULL` to clear the public key. | [allow-none][transfer none]
accept_invalid | if `TRUE` and `public_key` is not `NULL` and invalid, then do not modify the instance. |

#### Returns

`TRUE` if the key was valid or `NULL`. Returns `FALSE` for invalid keys. Depending on `accept_invalid` will an invalid key be set or not.

Since: 1.16

### nm_wireguard_peer_get_preshared_key ()

    const char *
    nm_wireguard_peer_get_preshared_key (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

the preshared key or `NULL` if unset.

[transfer none]

Since: 1.16

### nm_wireguard_peer_set_preshared_key ()

    gboolean
    nm_wireguard_peer_set_preshared_key (NMWireGuardPeer *self,
                                         const char *preshared_key,
                                         gboolean accept_invalid);

Reset the preshared key. Note that if the preshared key is valid, it will be normalized (which may or may not modify the set value).

Note that the preshared-key is a secret and consequently has corresponding preshared-key-flags property. This is so that secrets can be optional and requested on demand from a secret-agent. Also, an invalid preshared-key may optionally cause `nm_wireguard_peer_is_valid()` to fail or it may be accepted.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
preshared_key | the new preshared key or `NULL` to clear the preshared key. | [allow-none][transfer none]
accept_invalid | whether to allow setting the key to an invalid value. If `FALSE`, `self` is unchanged if the key is invalid and if `FALSE` is returned. |

#### Returns

`TRUE` if the preshared-key is valid, otherwise `FALSE`. `NULL` is considered a valid value. If the key is invalid, it depends on `accept_invalid` whether the previous value was reset.

Since: 1.16

### nm_wireguard_peer_get_preshared_key_flags ()

    NMSettingSecretFlags
    nm_wireguard_peer_get_preshared_key_flags
                                   (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

get the secret flags for the preshared-key.

Since: 1.16

### nm_wireguard_peer_set_preshared_key_flags ()

    void
    nm_wireguard_peer_set_preshared_key_flags
                                   (NMWireGuardPeer *self,
                                    NMSettingSecretFlags preshared_key_flags);

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
preshared_key_flags | the secret flags to set. |

Since: 1.16

### nm_wireguard_peer_get_persistent_keepalive ()

    guint16
    nm_wireguard_peer_get_persistent_keepalive
                                   (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

get the persistent-keepalive setting in seconds. Set to zero to disable keep-alive.

Since: 1.16

### nm_wireguard_peer_set_persistent_keepalive ()

    void
    nm_wireguard_peer_set_persistent_keepalive
                                   (NMWireGuardPeer *self,
                                    guint16 persistent_keepalive);

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
persistent_keepalive | the keep-alive value to set. |

Since: 1.16

### nm_wireguard_peer_get_endpoint ()

    const char *
    nm_wireguard_peer_get_endpoint (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

the endpoint or `NULL` if none was set.

[transfer none]

Since: 1.16

### nm_wireguard_peer_set_endpoint ()

    gboolean
    nm_wireguard_peer_set_endpoint (NMWireGuardPeer *self,
                                    const char *endpoint,
                                    gboolean allow_invalid);

Sets or clears the endpoint of `self` .

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
endpoint | the socket address endpoint to set or `NULL`. |
allow_invalid | if `TRUE`, also invalid values are set. If `FALSE`, the function does nothing for invalid `endpoint` arguments. |

#### Returns

`TRUE` if the endpoint is `NULL` or valid. For an invalid `endpoint` argument, `FALSE` is returned. Depending on `allow_invalid` , the instance will be modified.

Since: 1.16

### nm_wireguard_peer_get_allowed_ips_len ()

    guint
    nm_wireguard_peer_get_allowed_ips_len (const NMWireGuardPeer *self);

#### Parameters

self | the NMWireGuardPeer instance |

#### Returns

the number of allowed-ips entries.

Since: 1.16

### nm_wireguard_peer_get_allowed_ip ()

    const char *
    nm_wireguard_peer_get_allowed_ip (const NMWireGuardPeer *self,
                                      guint idx,
                                      gboolean *out_is_valid);

#### Parameters

self | the NMWireGuardPeer instance |
idx | the index from zero to (allowed-ips-len - 1) to retrieve. |
out_is_valid | `TRUE` if the returned value is a valid allowed-ip setting. | [allow-none]

#### Returns

the allowed-ip setting at index `idx` . If `idx` is out of range, `NULL` will be returned.

[transfer none]

Since: 1.16

### nm_wireguard_peer_clear_allowed_ips ()

    void
    nm_wireguard_peer_clear_allowed_ips (NMWireGuardPeer *self);

Removes all allowed-ip entries.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |

Since: 1.16

### nm_wireguard_peer_append_allowed_ip ()

    gboolean
    nm_wireguard_peer_append_allowed_ip (NMWireGuardPeer *self,
                                         const char *allowed_ip,
                                         gboolean accept_invalid);

Appends `allowed_ip` setting to the list. This does not check for duplicates and always appends `allowed_ip` to the end of the list. If `allowed_ip` is valid, it will be normalized and a modified for might be appended. If `allowed_ip` is invalid, it will still be appended, but later verification will fail.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
allowed_ip | the allowed-ip entry to set. |
accept_invalid | if `TRUE`, also invalid `allowed_ip` value will be appended. Otherwise, the function does nothing in face of invalid values and returns `FALSE`. |

#### Returns

`TRUE` if the value is a valid allowed-ips value, `FALSE` otherwise. Depending on `accept_invalid` , also invalid values are added.

Since: 1.16

### nm_wireguard_peer_remove_allowed_ip ()

    gboolean
    nm_wireguard_peer_remove_allowed_ip (NMWireGuardPeer *self,
                                         guint idx);

Removes the allowed-ip at the given `idx` . This shifts all following entries one index down.

It is a bug trying to modify a sealed NMWireGuardPeer instance.

#### Parameters

self | the unsealed NMWireGuardPeer instance |
idx | the index from zero to (allowed-ips-len - 1) to retrieve. If the index is out of range, `FALSE` is returned and nothing is done. |

#### Returns

`TRUE` if `idx` was valid and the allowed-ip was removed. `FALSE` otherwise, and the peer will not be changed.

Since: 1.16

### nm_wireguard_peer_is_valid ()

    gboolean
    nm_wireguard_peer_is_valid (const NMWireGuardPeer *self,
                                gboolean check_non_secrets,
                                gboolean check_secrets,
                                GError **error);

#### Parameters

self | the NMWireGuardPeer instance |
check_secrets | if `TRUE`, non-secret properties are validated. Otherwise, they are ignored for this purpose. |
check_non_secrets | if `TRUE`, secret properties are validated. Otherwise, they are ignored for this purpose. |
error | the GError location for returning the failure reason. |

#### Returns

`TRUE` if the peer is valid or fails with an error reason.

Since: 1.16

### nm_wireguard_peer_cmp ()

    int
    nm_wireguard_peer_cmp (const NMWireGuardPeer *a,
                           const NMWireGuardPeer *b,
                           NMSettingCompareFlags compare_flags);

#### Parameters

a | the NMWireGuardPeer to compare. | [allow-none]
b | the other NMWireGuardPeer to compare. | [allow-none]
compare_flags | NMSettingCompareFlags to affect the comparison. |

#### Returns

zero of the two instances are equivalent or a non-zero integer otherwise. This defines a total ordering over the peers. Whether a peer is sealed or not, does not affect the comparison.

Since: 1.16

### nm_setting_wireguard_new ()

    NMSetting *
    nm_setting_wireguard_new (void);

Creates a new NMSettingWireGuard object with default values.

#### Returns

the new empty NMSettingWireGuard object.

[transfer full]

Since: 1.16

### nm_setting_wireguard_get_private_key ()

    const char *
    nm_setting_wireguard_get_private_key (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

the set private-key or `NULL`.

[transfer none]

Since: 1.16

### nm_setting_wireguard_get_private_key_flags ()

    NMSettingSecretFlags
    nm_setting_wireguard_get_private_key_flags
                                   (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

the secret-flags for “private-key”.

Since: 1.16

### nm_setting_wireguard_get_listen_port ()

    guint16
    nm_setting_wireguard_get_listen_port (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

the set UDP listen port.

Since: 1.16

### nm_setting_wireguard_get_fwmark ()

    guint32
    nm_setting_wireguard_get_fwmark (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

the set firewall mark.

Since: 1.16

### nm_setting_wireguard_get_peers_len ()

    guint
    nm_setting_wireguard_get_peers_len (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

the number of registered peers.

Since: 1.16

### nm_setting_wireguard_get_peer ()

    NMWireGuardPeer *
    nm_setting_wireguard_get_peer (NMSettingWireGuard *self,
                                   guint idx);

#### Parameters

self | the NMSettingWireGuard instance |
idx | the index to lookup. |

#### Returns

the NMWireGuardPeer entry at index `idx` . If the index is out of range, `NULL` is returned.

[transfer none]

Since: 1.16

### nm_setting_wireguard_get_peer_by_public_key ()

    NMWireGuardPeer *
    nm_setting_wireguard_get_peer_by_public_key
                                   (NMSettingWireGuard *self,
                                    const char *public_key,
                                    guint *out_idx);

#### Parameters

self | the NMSettingWireGuard instance |
public_key | the public key for looking up the peer. |
out_idx | optional output argument for the index of the found peer. If no index is found, this is set to the `nm_setting_wireguard_get_peers_len()`. | [out][allow-none]

#### Returns

the NMWireGuardPeer instance with a matching public key. If no such peer exists, `NULL` is returned.

[transfer none]

Since: 1.16

### nm_setting_wireguard_set_peer ()

    void
    nm_setting_wireguard_set_peer (NMSettingWireGuard *self,
                                   NMWireGuardPeer *peer,
                                   guint idx);

If `idx` is one past the last peer, the behavior is the same as `nm_setting_wireguard_append_peer()`. Otherwise, the peer will be at `idx` and replace the peer instance at that index. Note that if a peer with the same public-key exists on another index, then that peer will also be replaced. In that case, the number of peers will shrink by one (because the one at `idx` got replace and then one with the same public-key got removed). This also means, that the resulting index afterwards may be one less than `idx` (if another peer with a lower index was dropped).

#### Parameters

self | the NMSettingWireGuard instance |
peer | the NMWireGuardPeer instance to set. This seals `peer` and keeps a reference on the instance. |
idx | the index, in the range of 0 to the number of peers (including). That means, if `idx` is one past the end of the number of peers, this is the same as `nm_setting_wireguard_append_peer()`. Otherwise, the peer at this index is replaced. |

Since: 1.16

### nm_setting_wireguard_append_peer ()

    void
    nm_setting_wireguard_append_peer (NMSettingWireGuard *self,
                                      NMWireGuardPeer *peer);

If a peer with the same public-key already exists, that one is replaced by `peer` . The new `peer` is always appended (or moved to) the end, so in case a peer is replaced, the indexes are shifted and the number of peers stays unchanged.

#### Parameters

self | the NMSettingWireGuard instance |
peer | the NMWireGuardPeer instance to append. This seals `peer` and keeps a reference on the instance. |

Since: 1.16

### nm_setting_wireguard_remove_peer ()

    gboolean
    nm_setting_wireguard_remove_peer (NMSettingWireGuard *self,
                                      guint idx);

#### Parameters

self | the NMSettingWireGuard instance |
idx | the index to remove. |

#### Returns

`TRUE` if `idx` was in range and a peer was removed. Otherwise, `self` is unchanged.

Since: 1.16

### nm_setting_wireguard_clear_peers ()

    guint
    nm_setting_wireguard_clear_peers (NMSettingWireGuard *self);

### nm_setting_wireguard_get_peer_routes ()

    gboolean
    nm_setting_wireguard_get_peer_routes (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

whether automatically add peer routes.

Since: 1.16

### nm_setting_wireguard_get_mtu ()

    guint32
    nm_setting_wireguard_get_mtu (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard instance |

#### Returns

the MTU of the setting.

Since: 1.16

### nm_setting_wireguard_get_ip4_auto_default_route ()

    NMTernary
    nm_setting_wireguard_get_ip4_auto_default_route
                                   (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard setting. |

#### Returns

the "ip4-auto-default-route" property of the setting.

Since: 1.20

### nm_setting_wireguard_get_ip6_auto_default_route ()

    NMTernary
    nm_setting_wireguard_get_ip6_auto_default_route
                                   (NMSettingWireGuard *self);

#### Parameters

self | the NMSettingWireGuard setting. |

#### Returns

the "ip6-auto-default-route" property of the setting.

Since: 1.20

## Types and Values

### NM_WIREGUARD_PUBLIC_KEY_LEN

    #define NM_WIREGUARD_PUBLIC_KEY_LEN    32

### NM_WIREGUARD_SYMMETRIC_KEY_LEN

    #define NM_WIREGUARD_SYMMETRIC_KEY_LEN 32

### NM_SETTING_WIREGUARD_SETTING_NAME

    #define NM_SETTING_WIREGUARD_SETTING_NAME "wireguard"

### NM_SETTING_WIREGUARD_FWMARK

    #define NM_SETTING_WIREGUARD_FWMARK            "fwmark"

### NM_SETTING_WIREGUARD_LISTEN_PORT

    #define NM_SETTING_WIREGUARD_LISTEN_PORT       "listen-port"

### NM_SETTING_WIREGUARD_PRIVATE_KEY

    #define NM_SETTING_WIREGUARD_PRIVATE_KEY       "private-key"

### NM_SETTING_WIREGUARD_PRIVATE_KEY_FLAGS

    #define NM_SETTING_WIREGUARD_PRIVATE_KEY_FLAGS "private-key-flags"

### NM_SETTING_WIREGUARD_PEERS

    #define NM_SETTING_WIREGUARD_PEERS "peers"

### NM_SETTING_WIREGUARD_MTU

    #define NM_SETTING_WIREGUARD_MTU                    "mtu"

### NM_SETTING_WIREGUARD_PEER_ROUTES

    #define NM_SETTING_WIREGUARD_PEER_ROUTES            "peer-routes"

### NM_SETTING_WIREGUARD_IP4_AUTO_DEFAULT_ROUTE

    #define NM_SETTING_WIREGUARD_IP4_AUTO_DEFAULT_ROUTE "ip4-auto-default-route"

### NM_SETTING_WIREGUARD_IP6_AUTO_DEFAULT_ROUTE

    #define NM_SETTING_WIREGUARD_IP6_AUTO_DEFAULT_ROUTE "ip6-auto-default-route"

### NM_WIREGUARD_PEER_ATTR_ALLOWED_IPS

    #define NM_WIREGUARD_PEER_ATTR_ALLOWED_IPS          "allowed-ips"

### NM_WIREGUARD_PEER_ATTR_ENDPOINT

    #define NM_WIREGUARD_PEER_ATTR_ENDPOINT             "endpoint"

### NM_WIREGUARD_PEER_ATTR_PERSISTENT_KEEPALIVE

    #define NM_WIREGUARD_PEER_ATTR_PERSISTENT_KEEPALIVE "persistent-keepalive"

### NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY

    #define NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY        "preshared-key"

### NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY_FLAGS

    #define NM_WIREGUARD_PEER_ATTR_PRESHARED_KEY_FLAGS  "preshared-key-flags"

### NM_WIREGUARD_PEER_ATTR_PUBLIC_KEY

    #define NM_WIREGUARD_PEER_ATTR_PUBLIC_KEY           "public-key"