UPnP: bind to specified interface

DanglingPointer · DanglingPointer · commit c5d2e3ac62d4 · 2026-04-05T18:46:19.000+01:00
diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@ This repo contains reusable library crates and a CLI executable. For GUI version
 - [x] [DHT](https://www.bittorrent.org/beps/bep_0005.html) ([Kademlia](https://homes.cs.aau.dk/~bnielsen/DSE04/papers/kademlia.pdf))
 - [x] [Protocol Encryption](https://css.csail.mit.edu/6.858/2018/projects/bgu-kelvinlu.pdf)
 - [x] [uTP](https://github.com/bittorrent/libutp)
+- [x] [UPnP](https://upnp.org/specs/gw/UPnP-gw-WANIPConnection-v2-Service.pdf)
 - [ ] [IPv6 DHT](https://www.bittorrent.org/beps/bep_0032.html)
 - [ ] [STUN (for DHT)?](https://datatracker.ietf.org/doc/html/rfc8489)
 - [ ] [Fast Extension](https://www.bittorrent.org/beps/bep_0006.html)
diff --git a/mtorrent-cli/src/bin/dht_node.rs b/mtorrent-cli/src/bin/dht_node.rs
@@ -50,9 +50,9 @@ struct Args {
 
 /// Example usage:
 /// ```bash
-/// ./target/release/dht_node --duration=30
 /// ./target/release/dht_node --nodes '"router.bittorrent.com:6881" "dht.transmissionbt.com:6881"' --duration=72
 /// ./target/release/dht_node --duration=10 -t "magnet:?xt=urn:btih:1EBD3DBFBB25C1333F51C99C7EE670FC2A1727C9" -o peers.txt
+/// ./target/release/dht_node --duration=30 -t "magnet:?xt=urn:btih:1EBD3DBFBB25C1333F51C99C7EE670FC2A1727C9" -i "wlp0s20f3"
 /// ```
 fn main() -> io::Result<()> {
     #[cfg(debug_assertions)]
@@ -67,6 +67,7 @@ fn main() -> io::Result<()> {
         .with_threads(false)
         .with_level(log::LevelFilter::Info)
         .with_module_level("mtorrent_dht", log::LevelFilter::Debug)
+        .with_module_level("mtorrent_utils", log::LevelFilter::Debug)
         .with_module_level("mtorrent::app::dht", log::LevelFilter::Debug)
         .with_module_level("dht_node", log::LevelFilter::Debug)
         .init()
diff --git a/mtorrent-utils/src/net.rs b/mtorrent-utils/src/net.rs
@@ -4,34 +4,29 @@ use std::hash::{DefaultHasher, Hash, Hasher};
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6};
 use std::{io, ops};
 
-/// Get local (non-loopback) IPv4.
-#[cfg(target_os = "linux")]
-pub fn get_local_addr() -> io::Result<Ipv4Addr> {
-    let hostname_out = std::process::Command::new("hostname").arg("-I").output()?;
-    let ipv4_string = String::from_utf8_lossy(&hostname_out.stdout)
-        .split_once(' ')
-        .ok_or_else(|| io::Error::other("Unexpected output from 'hostname -I'"))?
-        .0
-        .to_string();
-    ipv4_string.parse::<Ipv4Addr>().map_err(io::Error::other)
+#[cfg(not(windows))]
+pub(crate) fn get_local_addr(mut predicate: impl FnMut(&IpAddr) -> bool) -> Option<IpAddr> {
+    sysinfo::Networks::new_with_refreshed_list()
+        .values()
+        .flat_map(sysinfo::NetworkData::ip_networks)
+        .filter_map(|network| predicate(&network.addr).then_some(network.addr))
+        .next()
 }
 
-/// Get local (non-loopback) IPv4.
 #[cfg(windows)]
-pub fn get_local_addr() -> io::Result<Ipv4Addr> {
-    // naively uses first connected adapter
-    ipconfig::get_adapters()
-        .map_err(io::Error::other)?
+pub(crate) fn get_local_addr(predicate: impl FnMut(&IpAddr) -> bool) -> Option<IpAddr> {
+    // can't use sysinfo on Windows because it doesn't return SW adapters, e.g. loopback
+    let adapters = ipconfig::get_adapters().ok()?;
+    adapters
         .iter()
         .filter(|adapter| matches!(adapter.oper_status(), ipconfig::OperStatus::IfOperStatusUp))
         .flat_map(ipconfig::Adapter::ip_addresses)
-        .find_map(|addr| match addr {
-            IpAddr::V4(ipv4) => Some(*ipv4),
-            _ => None,
-        })
-        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "IPv4 not found"))
+        .cloned()
+        .find(predicate)
 }
 
+// ------------------------------------------------------------------------------------------------
+
 #[cfg(windows)]
 fn get_adapter_addrs<'a>(
     adapters: impl IntoIterator<Item = &'a ipconfig::Adapter>,
@@ -104,10 +99,7 @@ pub fn get_bind_addr_v6(interface: Option<&str>) -> Ipv6Addr {
     Ipv6Addr::UNSPECIFIED
 }
 
-#[cfg(not(any(target_os = "linux", windows)))]
-pub fn get_local_addr() -> io::Result<Ipv4Addr> {
-    Ok(Ipv4Addr::UNSPECIFIED)
-}
+// ------------------------------------------------------------------------------------------------
 
 #[doc(hidden)]
 pub fn set_so_sndbuf_internal<'s>(socket: impl Into<SockRef<'s>>, value: usize, module: &str) {
@@ -123,6 +115,24 @@ pub fn set_so_rcvbuf_internal<'s>(socket: impl Into<SockRef<'s>>, value: usize,
     }
 }
 
+/// Set SO_SNDBUF on a socket.
+#[macro_export]
+macro_rules! set_so_sndbuf {
+    ($sock:expr, $size:expr) => {{
+        $crate::net::set_so_sndbuf_internal($sock, $size, std::module_path!());
+    }};
+}
+
+/// Set SO_RCVBUF on a socket.
+#[macro_export]
+macro_rules! set_so_rcvbuf {
+    ($sock:expr, $size:expr) => {{
+        $crate::net::set_so_rcvbuf_internal($sock, $size, std::module_path!());
+    }};
+}
+
+// ------------------------------------------------------------------------------------------------
+
 /// Bind a socket to a specific network interface. Does nothing on Windows.
 #[cfg(target_os = "windows")]
 pub fn bind_to_interface<'s>(_socket: impl Into<SockRef<'s>>, _interface: &str) -> io::Result<()> {
@@ -176,21 +186,7 @@ pub fn bind_to_interface<'s>(socket: impl Into<SockRef<'s>>, interface: &str) ->
     Ok(())
 }
 
-/// Set SO_SNDBUF on a socket.
-#[macro_export]
-macro_rules! set_so_sndbuf {
-    ($sock:expr, $size:expr) => {{
-        $crate::net::set_so_sndbuf_internal($sock, $size, std::module_path!());
-    }};
-}
-
-/// Set SO_RCVBUF on a socket.
-#[macro_export]
-macro_rules! set_so_rcvbuf {
-    ($sock:expr, $size:expr) => {{
-        $crate::net::set_so_rcvbuf_internal($sock, $size, std::module_path!());
-    }};
-}
+// ------------------------------------------------------------------------------------------------
 
 const DYNAMIC_PORT_RANGE: ops::Range<u32> = 49152..65536;
 
@@ -332,4 +328,15 @@ mod tests {
         let addr = get_bind_addr_v6(Some(iface));
         assert_eq!(addr, Ipv6Addr::LOCALHOST);
     }
+
+    #[test]
+    fn test_local_addr_predicate() {
+        let addr = get_local_addr(|addr| addr.is_loopback() && addr.is_ipv4());
+        assert_eq!(addr, Some(IpAddr::V4(Ipv4Addr::LOCALHOST)));
+
+        let addr = get_local_addr(|addr| !addr.is_loopback() && !addr.is_unspecified());
+        let addr = addr.expect("failed to find non-loopback address");
+        assert!(!addr.is_loopback());
+        assert!(!addr.is_unspecified());
+    }
 }
diff --git a/mtorrent-utils/src/upnp.rs b/mtorrent-utils/src/upnp.rs
@@ -1,7 +1,9 @@
+use crate::net;
 use igd_next::{SearchOptions, aio};
 use local_async_utils::prelude::*;
 use std::mem;
-use std::net::SocketAddr;
+use std::net::{Ipv4Addr, SocketAddr};
+use tokio::time::sleep;
 
 type AsyncGateway = aio::Gateway<aio::tokio::Tokio>;
 type BlockingGateway = igd_next::Gateway;
@@ -16,36 +18,50 @@ pub struct PortOpener {
 }
 
 impl PortOpener {
-    const LEASE_DURATION: std::time::Duration = sec!(300);
+    /// Recommended lease duration from <https://upnp.org/specs/gw/UPnP-gw-WANIPConnection-v2-Service.pdf>.
+    const LEASE_DURATION_SEC: u32 = 3600;
 
+    /// Create a port mapping on the local gateway and return a `PortOpener` that maintains it.
+    ///
+    /// The mapping will be automatically removed when the `PortOpener` is dropped, but it will not
+    /// be renewed unless `run_continuous_renewal()` is called.
     pub async fn new(
-        internal_addr: SocketAddr,
         proto: PortMappingProtocol,
+        internal_port: u16,
         desired_external_port: Option<u16>,
+        interface: Option<&str>,
     ) -> igd_next::Result<Self> {
+        // get local IP for the specified interface (or any interface)
+        let internal_ip = if let Some(iface) = interface {
+            net::get_bind_addr_v4(Some(iface)).into()
+        } else {
+            net::get_local_addr(|addr| {
+                addr.is_ipv4() && !addr.is_loopback() && !addr.is_multicast()
+            })
+            .unwrap_or(Ipv4Addr::UNSPECIFIED.into())
+        };
+        let internal_addr = SocketAddr::new(internal_ip, internal_port);
+
+        // see if the gateway supports UPnP
         let gateway = aio::tokio::search_gateway(SearchOptions {
             timeout: Some(sec!(5)),
+            bind_addr: (internal_ip, 0).into(),
             ..Default::default()
         })
         .await?;
+
+        // create port mapping and get our external IP and port
         let public_ip = gateway.get_external_ip().await?;
         let public_port = if let Some(desired_port) = desired_external_port {
             gateway
-                .add_port(
-                    proto,
-                    desired_port,
-                    internal_addr,
-                    Self::LEASE_DURATION.as_secs() as u32,
-                    "",
-                )
+                .add_port(proto, desired_port, internal_addr, Self::LEASE_DURATION_SEC, "")
                 .await?;
             desired_port
         } else {
-            gateway
-                .add_any_port(proto, internal_addr, Self::LEASE_DURATION.as_secs() as u32, "")
-                .await?
+            gateway.add_any_port(proto, internal_addr, Self::LEASE_DURATION_SEC, "").await?
         };
         let external_addr = SocketAddr::new(public_ip, public_port);
+
         log::debug!("UPnP: port mapping created ({}:{})", proto, external_addr.port());
         Ok(Self {
             gateway,
@@ -55,22 +71,30 @@ impl PortOpener {
         })
     }
 
+    /// Get the external socket address that was mapped to the internal port.
     pub fn external_ip(&self) -> SocketAddr {
         self.external_addr
     }
 
+    /// Start continuous renewal of the port mapping. The mapping will be automatically removed when
+    /// the returned future is dropped.
     pub async fn run_continuous_renewal(self) -> igd_next::Result<()> {
+        // renewal interval must be slightly higher than the lease duration because renewing a
+        // mapping that hasn't expired yet has no effect
+        let renewal_interval = sec!(Self::LEASE_DURATION_SEC as u64) + millisec!(500);
         loop {
-            tokio::time::sleep(Self::LEASE_DURATION).await;
+            sleep(renewal_interval).await;
+
             self.gateway
                 .add_port(
                     self.proto,
                     self.external_addr.port(),
                     self.internal_addr,
-                    Self::LEASE_DURATION.as_secs() as u32,
+                    Self::LEASE_DURATION_SEC,
                     "",
                 )
                 .await?;
+
             log::debug!(
                 "UPnP: port mapping renewed ({}:{})",
                 self.proto,
@@ -81,6 +105,8 @@ impl PortOpener {
 }
 
 impl Drop for PortOpener {
+    /// Remove the port mapping when the `PortOpener` is dropped. Note that this is a blocking
+    /// operation because [`AsyncDrop`](https://doc.rust-lang.org/std/future/trait.AsyncDrop.html) is experimental.
     fn drop(&mut self) {
         let gateway = BlockingGateway {
             addr: self.gateway.addr,
@@ -108,19 +134,16 @@ impl Drop for PortOpener {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::net;
     use log::Level;
-    use std::net::SocketAddrV4;
     use tokio::time;
 
     #[ignore]
     #[tokio::test]
     async fn test_async_port_opener() {
         simple_logger::init_with_level(Level::Debug).unwrap();
 
-        let local_ip = net::get_local_addr().unwrap();
-        let local_internal_ip = SocketAddrV4::new(local_ip, 23015);
-        let port_opener = PortOpener::new(local_internal_ip.into(), PortMappingProtocol::TCP, None)
+        let internal_port = 12345;
+        let port_opener = PortOpener::new(PortMappingProtocol::TCP, internal_port, None, None)
             .await
             .unwrap_or_else(|e| panic!("Failed to create PortOpener: {e}"));
         log::info!("port opener created, external ip: {}", port_opener.external_ip());
diff --git a/mtorrent/src/app/dht.rs b/mtorrent/src/app/dht.rs
@@ -1,7 +1,7 @@
 use mtorrent_dht as dht;
 use mtorrent_utils::{info_stopwatch, net, upnp, worker};
 use std::io;
-use std::net::{SocketAddr, SocketAddrV4};
+use std::net::SocketAddrV4;
 use std::path::PathBuf;
 use std::time::Duration;
 use tokio::net::UdpSocket;
@@ -54,14 +54,13 @@ pub fn launch_dht_node_runtime(cfg: Config) -> io::Result<(worker::rt::Handle, d
     Ok((worker_handle, cmd_sender))
 }
 
-async fn start_upnp(local_port: u16) -> io::Result<()> {
-    let local_addr = net::get_local_addr()?;
-
+async fn start_upnp(local_port: u16, interface: Option<&str>) -> io::Result<()> {
     // try create a port mapping with the same port number
     let port_opener = upnp::PortOpener::new(
-        SocketAddr::new(local_addr.into(), local_port),
         upnp::PortMappingProtocol::UDP,
+        local_port,
         Some(local_port),
+        interface,
     )
     .await
     .map_err(io::Error::other)?;
@@ -101,14 +100,14 @@ async fn dht_main(
         Ok(socket) => socket,
     };
 
-    if let Some(interface) = bind_interface
-        && let Err(e) = net::bind_to_interface(&socket, &interface)
+    if let Some(interface) = &bind_interface
+        && let Err(e) = net::bind_to_interface(&socket, interface)
     {
         log::error!("Failed to bind DHT UDP socket to interface {interface}: {e}");
         return;
     }
 
-    if use_upnp && let Err(e) = start_upnp(local_port).await {
+    if use_upnp && let Err(e) = start_upnp(local_port, bind_interface.as_deref()).await {
         log::error!("UPnP for DHT failed: {e}");
     }
 
diff --git a/mtorrent/src/app/main.rs b/mtorrent/src/app/main.rs
@@ -61,15 +61,17 @@ struct Params {
 }
 
 async fn start_upnp(
-    internal_addr: SocketAddr,
+    internal_port: u16,
     desired_external_port: Option<u16>,
     proto: upnp::PortMappingProtocol,
-) -> SocketAddr {
-    let Ok(port_opener) = upnp::PortOpener::new(internal_addr, proto, desired_external_port)
-        .await
-        .inspect_err(|e| log::error!("UPnP: {proto:?} port mapping failed: {e}"))
+    interface: Option<&str>,
+) -> u16 {
+    let Ok(port_opener) =
+        upnp::PortOpener::new(proto, internal_port, desired_external_port, interface)
+            .await
+            .inspect_err(|e| log::error!("UPnP: {proto:?} port mapping failed: {e}"))
     else {
-        return internal_addr;
+        return internal_port;
     };
 
     let external_addr = port_opener.external_ip();
@@ -80,7 +82,7 @@ async fn start_upnp(
             log::error!("UPnP: {proto:?} port renewal for PWP failed: {e}");
         }
     });
-    external_addr
+    external_addr.port()
 }
 
 /// Download a single torrent given a magnet link or a path to its metainfo file.
@@ -109,12 +111,21 @@ pub async fn single_torrent(
     // peers later
     let external_pwp_port = if cfg.use_upnp {
         let _g = ctx.pwp_runtime.enter();
-        let internal_addr = (net::get_local_addr()?, listener_port).into();
-        let (_public_pwp_addr, public_utp_addr) = join!(
-            start_upnp(internal_addr, cfg.pwp_port, upnp::PortMappingProtocol::TCP),
-            start_upnp(internal_addr, cfg.pwp_port, upnp::PortMappingProtocol::UDP),
+        let (_public_pwp_port, public_utp_port) = join!(
+            start_upnp(
+                listener_port,
+                cfg.pwp_port,
+                upnp::PortMappingProtocol::TCP,
+                cfg.bind_interface.as_deref()
+            ),
+            start_upnp(
+                listener_port,
+                cfg.pwp_port,
+                upnp::PortMappingProtocol::UDP,
+                cfg.bind_interface.as_deref()
+            ),
         );
-        public_utp_addr.port()
+        public_utp_port
     } else {
         listener_port
     };
