.github/workflows | ||
aioupnp | ||
stubs | ||
tests | ||
.coveragerc | ||
.gitignore | ||
.pylintrc | ||
CHANGELOG.md | ||
generate_bug_report.py | ||
LICENSE | ||
mypy.ini | ||
README.md | ||
setup.py | ||
wine_build.sh |
UPnP for asyncio
aioupnp
is a python 3.6-8 library and command line tool to interact with UPnP gateways using asyncio. aioupnp
requires the netifaces
and defusedxml
modules.
Supported devices
Installation
Verify python is version 3.6-8
python --version
Installation for normal usage
pip install aioupnp
Installation for development
git clone https://github.com/lbryio/aioupnp.git
cd aioupnp
pip install -e .
Usage
aioupnp [-h] [--debug_logging] [--interface=<interface>] [--gateway_address=<gateway_address>]
[--lan_address=<lan_address>] [--timeout=<timeout>]
[(--<case sensitive m-search header>=<value>)...]
command [--<arg name>=<arg>]...
Commands
help
get_external_ip
m_search
add_port_mapping
get_port_mapping_by_index
get_redirects
get_specific_port_mapping
delete_port_mapping
get_next_mapping
gather_debug_info
To get the documentation for a command
aioupnp help get_external_ip
To get the external ip address
aioupnp get_external_ip
To list the active port mappings on the gateway
aioupnp get_redirects
To set up a TCP port mapping
aioupnp add_port_mapping --external_port=1234 --internal_port=1234 --lan_address=<lan_addr> --description=test --protocol=TCP
To delete a TCP port mapping
aioupnp delete_port_mapping --external_port=1234 --protocol=TCP
M-Search headers
UPnP uses a multicast protocol (SSDP) to locate the gateway. Gateway discovery is automatic by default, but you may provide specific headers for the search to use to override automatic discovery.
If m-search headers are provided as keyword arguments then all of the headers to be used must be provided, in the order they are to be used. For example:
aioupnp --HOST=239.255.255.250:1900 --MAN=\"ssdp:discover\" --MX=1 --ST=upnp:rootdevice m_search
Using non-default network interfaces
By default, the network device will be automatically discovered. The interface may instead be specified with the --interface
, provided before the command to be run. The gateway used on the interface network may be specified with the --gateway_address
argument.
aioupnp --interface=wlp4s0 --gateway_address=192.168.1.6 m_search
Example usage from python
from aioupnp.upnp import UPnP
async def main():
upnp = await UPnP.discover()
print(await upnp.get_external_ip())
print(await upnp.get_redirects())
print("adding a port mapping")
await upnp.add_port_mapping(1234, 'TCP', 1234, upnp.lan_address, 'test mapping')
print(await upnp.get_redirects())
print("deleting the port mapping")
await upnp.delete_port_mapping(1234, 'TCP')
print(await upnp.get_redirects())
asyncio.run(main())
Troubleshooting
Debug logging
To enable verbose debug logging, add the --debug_logging
argument before the command being run
aioupnp --debug_logging m_search
Is it turned on?
Check that UPnP is turned on in the web gui for your router.
It really doesn't work
If it always fails with an m-search error, or the UPnP device is found but making a port mapping or getting the external address fails, a bug report can be generated and automatically sent using the generate_bug_report.py
script. This script will run a packet capture while attempting to find the device and add/remove a mapping using miniupnpc
and aioupnp
. Once complete, it will submit a bug report of the packets sent/recieved by aioupnp/miniupnpc.
To run the bug report script, first pip install certifi aiohttp miniupnpc
. You'll also need aioupnp
installed. Then generate and send the bug report with sudo /full/path/to/your/python generate_bug_report.py
.
License
This project is MIT licensed. For the full license, see LICENSE.
Contact
The primary contact for this project is @jackrobison