udpxy(1)

📦
version 1.0.25.1 · 2 versions
, in fedora 43, fedora 44

💖 udpxy(1) — the udpxy manual page, bestie edition 💖

okay so. sit down. grab a boba. we're talking about udpxy, and honestly? she's iconic. 🫶

✨ NAME ✨

udpxy — a UDP-to-HTTP multicast traffic relay daemon. that's the whole vibe. 💅

🌈 SYNOPSIS 🌈

udpxy [-vTS] [-a <listenaddr>] [-m <mcast_ifc_addr>] [-c <clients>] [-l
<logfile>] [-B <sizeK>] [-R <msgs>] [-H <sec>] [-n <nice_incr>] [-M
<sec>] -p <port>

🦋 DESCRIPTION 🦋

okay so udpxy is a UDP-to-HTTP multicast traffic relay daemon. say it with me. she takes UDP traffic coming from a multicast subscription (or a source-specific multicast subscription, fancy) and forwards it straight to whatever HTTP client asked for it. a whole relay girly. ✨

she listens on a dedicated address/port, waiting for HTTP requests from clients. and a client request? it's gotta be structured like this, no exceptions:

http://{address}:{port}/{cmd}/[src_address@]{mgroup_address}{sep}{mgroup_port}

where:

  • {sep} — one of :|%|~|+|-|^
  • {cmd} — udp or rtp

and address + port have to match the listening address/port combo of udpxy, while mgroup_address:mgroup_port is what identifies the multicast group/channel to subscribe to. iykyk. 👑

now the commands, bestie, pay attention:

  • udp — the udp command makes udpxy probe for known types of payload (stuff like MPEG-TS and RTP over MPEG-TS). she's investigating. 🔍
  • rtp — the rtp command makes udpxy assume RTP over MPEG-TS payload, which means she skips the probes entirely. no questions asked, we trust. 💅

udpxy will spin up a separate client process for each new relay request (as long as she's still within the specified limit on active clients). that client process relays/forwards all the network traffic it receives (via a UDP socket) from the specified multicast group over to the requesting HTTP connection. main character energy fr fr. 🔥

she also supports a couple of administrative requests, because of course she does:

🌸 EXAMPLES 🌸

here's what it actually looks like in the wild:

http://192.168.0.12:5056/udp/10.170.185.82@232.22.137.57:5057
http://192.168.0.12:5056/udp/224.0.2.26:24012
http://192.168.0.12:5056/rtp/224.0.2.26:24012
http://192.168.0.15:5056/rtp/224.0.2.26^24055
http://192.168.0.15:5056/status/

see how the ^ is doing her little separator moment in there? slay. 🎀

💅 OPTIONS 💅

udpxy accepts the following options, and yes we're going through every single one:

  • -v — enable verbose output [default = disabled]. she's yapping, on purpose.
  • -S — enable client statistics [default = disabled].
  • -T — do NOT run as a daemon [default = daemon if root]. read that again. capital T. it's a negation. 🙈
  • -a <listenaddr> — IPv4 address/interface to listen on [default = 0.0.0.0].
  • -m <mcast_ifc_addr> — IPv4 address/interface of the (multicast) source [default = 0.0.0.0].
  • -c <clients> — maximum number of clients to accept [default = 3, max = 5000].
  • -l <logfile> — log output to file [default = stderr].
  • -B <sizeK> — buffer size (65536, 32Kb, 1Mb) for inbound (multicast) data [default = 2048 bytes].
  • -R <msgs> — maximum number of messages to buffer (-1 = all) [default = 1].
  • -H <sec> — maximum time (in seconds) to hold data in a buffer (-1 = unlimited) [default = 1].
  • -n <nice_incr> — nice value increment [default = 0].
  • -M <sec> — renew multicast subscription every M seconds (skip if 0) [default = 0].
  • -p <port> — port to listen on. this one's required, no cap. ⭐

🧚 PAYLOAD TYPES AND HANDLING 🧚

udpxy recognizes MPEG-TS and RTP over MPEG-TS payloads inside relayed packets. and if she bumps into RTP payload? she automatically 'translates' it to MPEG-TS by stripping the RTP headers — so media players that don't recognize RTP can still play the stream back. she's a translator. a linguist. a diplomat. 💜

so far, no translation is performed for other payload types. that's it. that's the whole story. 😭

🌈 RECORDING MPEG TRAFFIC 🌈

udpxy also has functionality to record captured traffic as a raw MPEG-TS stream into a file. this is enabled through udpxrec: a bundled-in application that's linked together with udpxy as one executable. ✨

udpxrec is invoked via a symbolic link (named udpxrec) pointing to the udpxy executable. and listen — do not rename the udpxy executable. just don't. 🙅♀️

⚠️ important bestie warning: udpxrec creates MPEG files encapsulating MPEG-TS segments, and certain media players will NOT play such files. to make them playable, the stream must be transcoded to MPEG-PS. vlc 'knows' how to do that transcoding — here's a command-line example:
vlc input-ts.mpg --sout="#std{access=file,mux=ps,dst=out-ps.mpg}"

the resulting MPEG-PS file can be played back by most media players. problem solved, we love a glow-up. 🦋

💜 ENVIRONMENT 💜

udpxy uses the following environment variables to compliment her command-line options — these are for the options most people wouldn't need to change too often (or that are just straight-up inconvenient to use from the command line). 💅

NB: if there's a command-line switch that would intersect in functionality with an environment variable, the switch always has higher priority. always. she said what she said.
  • UDPXY_RCV_TMOUT — timeout (sec) on the inbound data stream (multicast), default=5;
  • UDPXY_DHOLD_TMOUT — timeout (sec) to hold buffered data before sending/flushing to client(s), default=1;
  • UDPXY_SREAD_TMOUT — timeout (sec) to read from the listening socked (handling HTTP requests), default=1;
  • UDPXY_SWRITE_TMOUT — timeout (sec) to write to the listening socked (handling HTTP requests), default=1;
  • UDPXY_SSEL_TMOUT — timeout (sec) to select(2) in server loop (unused if pselect(2) is employed), default=30;
  • UDPXY_LQ_BACKLOG — size of the listener socket's backlog, default=16;
  • UDPXY_SRV_RLWMARK — low watermaek on the receiving (m-cast) socket, default=0 (not set);
  • UDPXY_SSOCKBUF_NOSYNC — do not sync inbound (UDP) socket's buffer size (with the value set by -B), default=1 (sync);
  • UDPXY_DSOCKBUF_NOSYNC — do not sync outbound (TCP) socket's buffer size (with the value set by -B), default=1 (sync);
  • UDPXY_TCP_NODELAY — disable Nagle algorithm on the newly accepted socket (faster channel switching), default=1;
  • UDPXY_HTTP200_FTR_FILE — append contents of the given text file to the HTTP 200 response, default=none;
  • UDPXY_HTTP200_FTR_LN — append the text (line) to the HTTP 200 response, default=none;
  • UDPXY_ALLOW_PAUSES — if blocked on a write(2), keep reading data until the buffer (-B <sizeK>) is full, default=disabled;
  • UDPXY_PAUSE_MSEC — allow only N milliseconds of reading data when blocked on a write(2).
  • UDPXY_CONTENT_TYPE — specify custom Content-Type in HTTP responses.

👑 AUTHORS 👑

Pavel V. Cherenkov and all the good people who submitted patches or otherwise contributed to the project. 🫶 legends, every single one.

🔥 SEE ALSO 🔥

udpxrec(1)

okay that's the whole page bestie, you're officially educated, go forth and relay 🎀

Version 1.0 — November 17, 2012 — from the udpxy(1) manual page. mwah. 💖✨🦋

📦 where this page comes from