The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Wireguard-WGmeta-0.3.4
River stage zero No dependents
++
/ Wireguard::WGmeta::Wrapper::Config

NAME

WGmeta::Wrapper::Config - Class for interfacing the wireguard configuration

SYNOPSIS

 use Wireguard::WGmeta::Wrapper::Config;
 my $wg_meta = Wireguard::WGmeta::Wrapper::Config->new('<path to wireguard configuration>');

DESCRIPTION

This class provides wrapper-functions around a wireguard configuration parsed by Wireguard::WGmeta::Parser::Middleware which allow to edit, add and remove interfaces and peers.

CONCURRENCY

Please refer to Wireguard::WGmeta::Wrapper::ConfigT

EXAMPLES

 use Wireguard::WGmeta::Wrapper::Config;
 my $wg-meta = Wireguard::WGmeta::Wrapper::Config->new('<path to wireguard configuration>');

 # set an attribute (non wg-meta attributes forwarded to the original `wg set` command)
 wg_meta->set('wg0', 'WG_0_PEER_A_PUBLIC_KEY', '<attribute_name>', '<attribute_value>');

 # set an alias for a peer
 wg_meta->set('wg0', 'WG_0_PEER_A_PUBLIC_KEY', 'alias', 'some_fancy_alias');

 # disable peer (this comments out the peer in the configuration file)
 wg_meta->disable('wg0', 'some_fancy_alias');

 # write config (if parameter is set to True, the config is overwritten, if set to False the resulting file is suffixed with '.not_applied'
 wg_meta->commit(1);

METHODS

new($wireguard_home [, $wg_meta_prefix, $wg_meta_disabled_prefix, $custom_attributes])

Creates a new instance of this class.

Parameters

  • $wireguard_home Path to Wireguard configuration files. Make sure the path ends with a `/`.

  • [$wg_meta_prefix] A custom wg-meta comment prefix, has to begin with either `;` or `#`. It is recommended to not change this setting, especially in a already deployed installation.

  • [$wg_meta_disabled_prefix] A custom prefix for the commented out (disabled) sections, has to begin with either `;` or `#` and must not be equal with $wg_meta_prefix! (This is enforced and an exception is thrown if violated) It is recommended to not change this setting, especially in an already deployed installation.

  • [$not_applied_suffix] Suffix to add if commit() is set to not override an existing config.

  • [$custom_attributes] A reference to a hash defining custom attributes. Expects the following structure:

        {
        'attr_key'     => {
            'validator'      => 'Ref to validation function'
        },
        'example'         => {
            'validator'      => sub ($attr, $value) {
                return ($attr eq 'example') ? 1 : 0;
            }
        },
        ...
    }

Returns

An instance of WGmeta::Wrapper::Config

set($interface, $identifier, $attribute, $value [, $unknown_callback])

Sets a value on a specific interface section. If attribute_value == $value this sub is essentially a No-Op.

Parameters

  • $interface Valid interface identifier (e.g 'wg0')

  • $identifier Either an interface name, an alias or public-key of a peer

  • $attribute Attribute name (case does matter!)

  • [$unknown_callback = undef] A reference to a callback function which is fired when a previously unknown attribute is set. Expected signature:

        sub my_unknown_callback($attribute, $value) {
        # Handling of this particular case
        return $attribute, $value;
    }

    If not defined, a warning is emitted

Raises

Exception if:

  • Value is not defined

  • Interface is invalid

  • Identifier is invalid (also if alias translation fails)

  • Attribute is not valid for target section (Interface, Peer)

  • Validation for the attribute value fails

Returns

None

attr_value_is_valid($attribute, $value, $ref_valid_attrs)

Simply calls the validate() function defined in Wireguard::WGmeta::Validator or $custom_attributs

Parameters

  • $attribute Attribute name

  • $value Attribute value

Returns

True if validation was successful (or no validator function present), False if not.

disable($interface, $identifier)

Disables an interface/peer and setting the wg-meta attribute `Disabled` to 1.

Parameters

  • $interface Valid interface name (e.g 'wg0').

  • $identifier A valid identifier (or alias): If the target section is a peer, this is usually the public key of this peer. If target is an interface, its again the interface name.

Returns

None

enable($interface, $identifier)

Inverse method if "disable($interface, $identifier)"

is_valid_interface($interface)

Checks if an interface name is valid (present in parsed config)

Parameters

  • $interface An interface name

Returns

True if present, undef if not.

is_valid_alias($interface, $alias)

Simply checks if an alias is valid for a given interface

is_valid_identifier($interface, $identifier)

Checks if an identifier is valid for a given interface

Parameters

  • $interface An interface name

  • $identifier An identifier (no alias!)

Returns

True if present, undef if not.

try_translate_alias($interface, $may_alias)

Tries to translate an identifier (which may be an alias). no exception is thrown on failure, instead the $may_alias is returned.

Parameters

  • $interface A valid interface name

  • $may_alias An identifier which could be a valid alias for this interface

Returns

If the alias is valid for the specified interface, the corresponding identifier is returned, else $may_alias

get_all_conf_files($wireguard_home)

Returns a list of all files in $wireguard_home matching /.*\.conf$/.

Parameters

  • $wireguard_home Path to a folder where wireguard configuration files are located

Returns

A reference to a list with absolute paths to the config files (possibly empty)

commit([$is_hot_config = FALSE, $no_checksum = FALSE])

Writes down the parsed config to the wireguard configuration folder

Parameters

  • [$is_hot_config = FALSE]) If set to TRUE, the existing configuration is overwritten (and possibly existing, not applied configs are deleted). Otherwise, the suffix '.not_applied' is appended to the filename

  • [$no_checksum = FALSE]) If set to TRUE, no checksum is written

Raises

Exception if: Folder or file is not writeable

Returns

None

get_interface_list()

Return a list of all interfaces.

Returns

A list of all valid interface names. If no interfaces are available, an empty list is returned

get_interface_section($interface, $identifier)

Returns a hash representing a section of a given interface

Parameters

  • $interface Valid interface name

  • $identifier Valid section identifier

Returns

A hash containing the requested section. If the requested section/interface is not present, an empty hash is returned.

get_section_list($interface)

Returns a list of valid sections of an interface (ordered as in the original config file).

Parameters

  • $interface A valid interface name

Returns

A list of all sections of an interface. If interface is not present, an empty list is returned.

add_interface($interface_name, $ip_address, $listen_port, $private_key)

Adds a (minimally configured) interface. If more attributes are needed, please set them using the set() method.

Caveat: No validation is performed on the values!

Parameters

  • $interface_name A new interface name, must be unique.

  • $ip_address A string describing the ip net(s) (e.g '10.0.0.0/24, fdc9:281f:04d7:9ee9::2/64')

  • $listen_port The listen port for this interface.

  • $private_key A private key for this interface

Raises

An exception if the interface name already exists.

Returns

None

add_peer($interface, $ip_address, $public_key [, $alias, $preshared_key])

Adds a peer to an exiting interface.

Parameters

  • $interface A valid interface.

  • $ip_address A string describing the ip-address(es) of this this peer.

  • $public_key Public-key for this interface. This becomes the identifier of this peer.

  • [$preshared_key] Optional argument defining the psk.

  • [$alias] Optional argument defining an alias for this peer (wg-meta)

Raises

An exception if either the interface is invalid, the alias is already assigned or the public-key is already present on an other peer.

Returns

A tuple consisting of the iface private-key and listen port

remove_peer($interface, $identifier)

Removes a peer (identified by it's public key or alias) from an interface.

Parameters

  • $interface A valid interface name

  • $identifier A valid identifier (or an alias)

Raises

Exception if interface or identifier is invalid

Returns

None

remove_interface($interface [, $keep_file = FALSE])

Removes an interface. This command deletes the config file immediately. I.e no rollback possible!

Parameters

  • $interface A valid interface name

Raises

Exception if interface or identifier is invalid

Returns

None

get_peer_count([$interface = undef])

Returns the number of peers.

Caveat: Does return the count represented in the current (parsed) configuration state.

Parameters

  • [$interface = undef] If defined and valid, only return counts for this specific interface

Returns

Number of peers

may_reload_from_disk($interface [, $new = FALSE])

Method to reload an interface configuration from disk. Also useful to add an new (externally) created interface on-the-fly. If a config file with a .not_applied suffix is present (and its mtime is newer than the original one), it is taken as source for reloading the configuration data.

Parameters

  • $interface A valid interface name

  • [$new = FALSE] If set to True, the parser looks at $wireguard_home for this new interface config.

  • [$force = FALSE] When set to True, the configuration is reloaded regardless of its mtime.

Raises

Exception: If the interface is invalid (or the config file is not found)

Returns

None, or undef if $new == True and the interface is in fact not a wg config.

register_on_reload_listener($ref_handler, $handler_id [, $ref_listener_args = []])

Register your callback handlers for the reload_from_disk() event here. Your handler is called after the reload happened, is blocking and exceptions are caught in an eval{}; environment.

Parameters

  • $ref_handler Reference to a handler function. The following signature is expected:

        sub my_handler_function($interface, $ref_list_args){
        ...
    }

  • $handler_id An identifier for you handler function. Must be unique!

  • [$ref_listener_args = []] A reference to an argument list for your handler function

Returns

None, exception if $handler_id is already present.

remove_on_reload_listener($handler_id)

Removes a reload callback handler by it's $handler_id.

Parameters

  • $handler_id A valid handler id

Returns

1 on success, undef on failure.