Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Broadcast and multicast with Node.js dgram
How to send UDP broadcasts and join multicast groups with Node.js dgram: setBroadcast, addMembership, TTL, loopback, interfaces and typical discovery patterns.
Normally a UDP datagram goes to one receiver. Two features let one datagram reach many: broadcast sends to every host on a local network, and multicast sends to a group address that interested hosts have joined. Both are used for local discovery ("who is out there?"), for example by printers, media players and development tools that find each other without configuration.
In Node.js both are options of a dgram.Socket. Broadcast needs setBroadcast(true) on the sender and a broadcast destination such as 192.168.1.255 or 255.255.255.255. Multicast needs receivers to call addMembership(group) and senders to address the group, an IPv4 address from 224.0.0.0 to 239.255.255.255. Routers do not forward broadcast, and multicast crosses them only if configured, so both are mostly for a single network segment.
import dgram from 'node:dgram'; const socket = dgram.createSocket('udp4'); socket.bind(() => { socket.setBroadcast(true); socket.send('anyone there?', 41234, '255.255.255.255'); });
Try it
The runner has only a loopback network, so these examples use loopback addresses. On a real network you would use the broadcast address of your subnet and a real interface address.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
socket.setBroadcast(flag: boolean): void socket.addMembership(multicastAddress: string, multicastInterface?: string): void socket.dropMembership(multicastAddress: string, multicastInterface?: string): void socket.setMulticastTTL(ttl: number): number socket.setMulticastLoopback(flag: boolean): boolean socket.setMulticastInterface(multicastInterface: string): void socket.setTTL(ttl: number): number socket.addSourceSpecificMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void socket.dropSourceSpecificMembership(sourceAddress: string, groupAddress: string, multicastInterface?: string): void
| Name | Description |
|---|---|
setBroadcast(flag) |
Allow sending to broadcast addresses. Required, or send() fails with EACCES. The socket must be bound (a send() also binds it). |
addMembership(group, interface?) |
Join a multicast group on the given local interface address. Without an interface the system picks, which can fail on hosts without a multicast-capable route. |
dropMembership(group, interface?) |
Leave the group. Closing the socket does this automatically. |
setMulticastTTL(ttl) |
Hops a multicast packet may travel, 0 to 255. Default 1 (same network). |
setMulticastLoopback(flag) |
Whether the sending host also receives its own multicast. Default true. |
setMulticastInterface(address) |
The local interface used for outgoing multicast. |
setTTL(ttl) |
Hop limit for unicast traffic, 1 to 255. |
*SourceSpecificMembership |
Join or leave a group for a single source only (SSM, 232.0.0.0/8 range). |
Errors and edge cases: the membership methods throw synchronously if the group or interface is invalid, or when the system has no suitable interface (ENODEV, EADDRNOTAVAIL). Calling them on an unbound or closed socket throws ERR_SOCKET_DGRAM_NOT_RUNNING. In some containers and cloud networks, multicast and broadcast are blocked entirely, even though the calls succeed.
Usage notes
- Bind to the port, not to the group. Receivers bind
0.0.0.0:port(or the group address on Linux and macOS) and then calladdMembership(). UsereuseAddr: trueso several programs on the same host can listen on one port. - Broadcast addresses.
255.255.255.255is the limited broadcast (this network); a directed broadcast such as192.168.1.255reaches a specific subnet. Compute it fromos.networkInterfaces()(address, netmask). - Multicast is the more polite option. Hosts that did not join never process the packet; broadcast interrupts every host on the segment.
- No IPv6 broadcast. IPv6 has multicast only; use groups like
ff02::1(all nodes on the link) with a%interfacezone. - Discovery pattern. The searcher multicasts a request; each service replies with a unicast
send()toremote.addressandremote.porttaken from the'message'event. - Wi-Fi and VPNs. Many access points and VPN adapters drop multicast. When discovery fails on one network and works on another, suspect the network, not the code.
- Security. Anyone on the network can send to a group. Never trust a datagram for authentication; validate and rate limit.
Related
dgram.createSocket(),socket.send(),net.isIP()- Lessons: UDP and DNS