NAME

Acme::UPnP - Cheap UPnP Port Mapping (IGD)

SYNOPSIS

use Acme::UPnP;

my $mapper = Acme::UPnP->new( );

# Discovery
if ( $mapper->discover_device( ) ) {
    say 'Found router: ' . $mapper->upnp_device->getfriendlyname( );

    # Map a port
    $mapper->map_port( 8080, 8080, 'TCP', 'My Silly App' );
}

# Clean up on exit
$mapper->unmap_port( 8080, 'TCP' );

DESCRIPTION

Acme::UPnP provides a high-level, easy-to-use interface for the UPnP Internet Gateway Device (IGD) protocol. It automates the complex task of requesting port forwarding from residential routers, which is often required for peer-to-peer applications and local servers to be accessible from the internet.

PUBLIC METHODS

discover_device()

Scans the local network for UPnP-capable gateway devices. Returns true if a device was successfully identified.

map_port( $internal, $external, $protocol, $description )

Requests a new port mapping.

$protocol: 'TCP' or 'UDP'.

$description: A label for the router's mapping table.

Triggers map_success or map_failed events.

unmap_port( $external, $protocol )

Removes an existing port mapping.

get_external_ip( )

Queries the router for its public WAN IP address.

is_available( )

Returns boolean indicating if the required Net::UPnP dependency is installed.

AUTHOR

Sanko Robinson <sanko@cpan.org>

COPYRIGHT

Copyright (C) 2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.