upnpc

Forward the external TCP port 80 to port 8080 on a local machine

$ upnpc -a [192.168.0.1] 8080 80 tcp

$ upnpc -d 80 tcp

$ upnpc -s

$ upnpc -l

upnpc [-s] [-a <internal_ip> <external_port> <internal_port> <protocol> [duration] [description]] [-d <external_port> <protocol>] [-l] [options...]

Common usage examples:
upnpc -s
upnpc -a 192.168.1.100 8080 80 TCP
upnpc -d 8080 TCP
upnpc -l

-s
    Get WAN (external) IP address and connection status information.

-a [duration] [description]
    Add a port mapping. Protocol can be TCP or UDP. Duration is in seconds (0 for permanent). Description is optional.

-d
    Delete a port mapping for the specified external port and protocol.

-l
    List all active port mappings configured on the UPnP IGD.

-r
    Renew a port mapping lease for the specified external port and protocol.

-u
    Specify an alternative UPnP control URL instead of discovering one.

-m
    Specify the multicast IP for discovery (default is 239.255.255.250).

-e
    Provide a description for the port mapping (used with -a).

-p
    Specify the lease duration in seconds for the port mapping (used with -a).

-i
    Set an IGD description for the client.

-P
    Specify the local port for SSDP (Simple Service Discovery Protocol) discovery.

-A
    Specify the local network interface IP address to use for discovery.

-z
    Do not wait for a response from the IGD device.

-v
    Enable verbose output for more detailed information.

-D
    Enable debug output for even more detailed information.

-h
    Display help message and exit.

-N
    Disable NAT-PMP support; only use UPnP IGD.

-M
    Disable UPnP IGD support; only use NAT-PMP.

-L
    List NAT-PMP mappings (if supported and enabled).

upnpc is a command-line client for the Universal Plug and Play (UPnP) Internet Gateway Device (IGD) protocol. It allows users to programmatically interact with UPnP-enabled routers or gateway devices to manage Network Address Translation (NAT) and port forwarding rules. This tool is particularly useful for applications that require incoming connections (e.g., peer-to-peer applications, gaming, or remote access) to bypass NAT restrictions without manual configuration through a router's web interface.

With upnpc, you can query the router's external IP address, list existing port mappings, add new port forwarding rules (specifying internal IP, external port, internal port, and protocol), and delete them. It supports both UPnP IGD and NAT-PMP (NAT Port Mapping Protocol) for broader compatibility. While convenient, it's important to be aware of the security implications of enabling UPnP on a router, as it can potentially allow malicious software to open ports without explicit user permission.

UPnP IGD, while convenient, has known security vulnerabilities if not properly secured on the router. It can allow devices on your local network to open ports to the internet without explicit user approval, potentially exposing services or devices to external attacks. It's recommended to disable UPnP on your router if you do not actively use applications that require it, or to use it with caution and monitor open ports.

upnpc supports both Universal Plug and Play (UPnP) Internet Gateway Device (IGD) protocol and NAT Port Mapping Protocol (NAT-PMP). UPnP is more widely adopted by routers, while NAT-PMP is primarily associated with Apple devices and some open-source routers. The tool attempts to use both by default but allows users to specify preference with -N or -M options.

When adding a mapping with -a, you can specify a lease duration. If no duration or 0 is specified, the mapping is typically permanent. However, some routers may impose their own maximum durations or garbage collection, even for 'permanent' mappings. The -r option can be used to renew the lease of an existing mapping before it expires.

The upnpc command is part of the miniupnpc project, which provides a lightweight, portable UPnP client library. The library and its associated command-line tool were developed to offer a simple and efficient way to interact with UPnP IGD devices from C/C++ applications and the command line, respectively. Its development has focused on providing essential UPnP IGD functionalities, making it a popular choice for developers integrating UPnP capabilities into their applications on various platforms.

ss(8), netstat(8), iptables(8), nmap(1)