OSMO-MSLOOKUP-CLIENT(1)

📦
version 1.9.0 · 2 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, meet osmo-mslookup-client — aka osmo-mgw 🫶 (yes the man page title is OSMO-MSLOOKUP-CLIENT(1), section 1, User Commands, we're in the group chat now 💅)

🌸 DESCRIPTION 🌸

Osmocom Media Gateway, to manage, connect and optionally transcode voice streams between different network elements such as BTSs and external entities like SIP. It is typically co-located with both OsmoBSC and OsmoMSC and controlled by them via IETF MGCP (Media Gateway Control Protocol). it's giving ✨voice-plumbing royalty✨

https://osmocom.org/projects/osmo-mgw

osmo-mslookup-client version 1.9.0 👑

💅 OPTIONS 💅

  • [[delay-][timeout]@]service.number.id — a service query string, with an optional individual timeout tacked on. the exact same format is also used on a daemon socket, if any 🧚 the timeout is made of the min-delay and the timeout numbers, and those correspond to the --min-delay and --timeout options, measured in milliseconds. these options kick in if a query string lacks its own numbers, no cap. examples bestie:
gsup.hlr.1234567.imsi

→ use cmdline timeout settings 🙈

5000@gsup.hlr.1234567.imsi

→ return N results for 5 seconds ⏱️

1000-5000@sip.voice.123.msisdn

→ same, but silent for the first second 🤫

10000-@smpp.sms.567.msisdn

→ return 1 result after 10 seconds 🦋

  • --format -f csv (default) — format result lines in CSV format 📄✨
  • --no-csv-headers -H — if the format is csv, by default the first output line prints the CSV headers used for CSV output format. this option disables these CSV headers 🚫 (goodbye header row, we hardly knew ye)
  • --format -f json — format result lines in json instead of semicolon separated, like:
{"query": "sip.voice.12345.msisdn", "result": "ok", "v4": ["10.9.8.7", "5060"]}

literal main character formatting 💖

  • --daemon -d — keep running after a request has been serviced 🏃♀️💨 (never leaving the function, iconic)
  • --mdns-ip -m 239.192.23.42 -m ff08::23:42 --mdns-port -M 4266 — set multicast IP address / port to send mDNS requests and listen for mDNS responses 📡🌈
  • --mdns-domain-suffix -D mdns.osmocom.org — append this suffix to each mDNS query's domain to avoid colliding with the top-level domains administrated by IANA 🎀 (we do not want the drama)
  • --min-delay -t 1000 (in milliseconds) — set minimum delay to wait before returning any results. when this timeout has elapsed, the best current result is returned, if any is available. responses arriving after the min-delay has elapsed which have a younger age than previous results are returned immediately. Note: when a response with age of zero comes in, the result is returned immediately and the request is discarded: non-daemon mode exits, daemon mode ignores later results. 🫢 that's the rule, periodt.
  • --timeout -T 1000 (in milliseconds) — set timeout after which to stop listening for responses. if this is smaller than -t, the value from -t will be used for -T as well. Note: when a response with age of zero comes in, the result is returned immediately and the request is discarded: non-daemon mode exits, daemon mode ignores later results. 👑 same energy, same rule.
  • --socket -s /path/to/unix-domain-socket — listen to requests from and write responses to a UNIX domain socket 🔌💜
  • --send -S <query> <age> <ip1> <port1> <ip2> <port2> — do not query, but send an mslookup result. this is useful only for testing 🧪 (emphasis on only for testing, bestie). examples:
--send foo.123.msisdn 300 23.42.17.11 1234
--send foo.123.msisdn 300 2323:4242:1717:1111::42 1234
--send foo.123.msisdn 300 23.42.17.11 1234 2323:4242:1717:1111::42 1234
  • --quiet -q — do not print errors to stderr, do not log to stderr 🤐 (silence, but make it ✨aesthetic✨)
  • --help -h — this help 🆘

Copyright © 2019 by sysmocom - s.f.m.c. GmbH

Copyright © 2019 by Neels Hofmeyr <neels@hofmeyr.de> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

okay so now the lore drop 📖✨:

Standalone mslookup client for Distributed GSM 🌍

Receiving mslookup results means listening for responses on a socket. Often, integration (e.g. FreeSwitch dialplan.py) makes it hard to select() on a socket to read responses, because that interferes with the main program (e.g. FreeSwitch's dialplan.py seems to be integrated with an own select() main loop that interferes with osmo_select_main(), or an smpp.py uses smpplib.client.listen() as main loop, etc.). 💀 the select() drama is REAL.

This program provides a trivial solution, by outsourcing the mslookup main loop to a separate process. Communication is done via cmdline arg and stdout pipe or a (blocking) unix domain socket, results are returned in CSV or JSON format. 🎀 so clean, so demure.

This can be done one-shot, i.e. exit as soon as the response has been determined, or in daemon form, i.e. continuously listen for requests and return responses. 👑

About running a local daemon: it is unintuitive to connect to a socket to solve a problem of reading from a socket -- it seems like just more of the same problem 😭 (fr fr, we get it). The reasons why the daemon is in fact useful are:

  • The osmo-mslookup-client daemon will return only those results matching requests issued on that socket connection.
  • A program can simply blockingly recv() from the osmo-mslookup-client socket instead of needing to run osmo_select_main() so that libosmo-mslookup is able to asynchronously receive responses from remote servers.
  • Only one long-lived multicast socket needs to be opened instead of a new socket for each request.

Output is in CSV or json, see --format. The default is tab-separated CSV with these columns: query result last age v4_ip v4_port v6_ip v6_port 🌈

One-shot operation example:

$ osmo-mslookup-client 1000-@sip.voice.12345.msisdn -f json
{"query": "sip.voice.12345.msisdn", "result": "result", "last": true, "age": 5, "v4": ["1.2.3.7", "23"]}
$

Daemon operation example:

$ osmo-mslookup-client -s /tmp/mslookup -d

(and a client program then connects to /tmp/mslookup, find an implementation example below) 🦋

Integrating with calling programs can be done by:

  • call osmo-mslookup-client with the query string as argument. It will open a multicast DNS socket, send out a query and wait for the matching response. It will print the result on stdout and exit. This method launches a new process for every mslookup query, and creates a short-lived multicast listener for each invocation. This is fine for low activity, but does not scale well. 🙈 (lowkey fine, highkey not scalable)
  • invoke osmo-mslookup-client --socket /tmp/mslookup -d. Individual queries can be sent by connecting to that unix domain socket, blockingly reading the response when it arrives and disconnecting. This way only one process keeps one multicast listener open. Callers can connect to this socket without spawning processes. This is recommended for scale. 🔥 periodt, this is the way.

Python example clients for {CSV,JSON}x{cmdline,socket} can be found here:

http://git.osmocom.org/osmo-hlr/tree/contrib/dgsm/osmo-mslookup-pipe.py

http://git.osmocom.org/osmo-hlr/tree/contrib/dgsm/osmo-mslookup-socket.py

Copyright © 2019 by sysmocom - s.f.m.c. GmbH

Copyright © 2019 by Neels Hofmeyr <neels@hofmeyr.de> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

🌈 SEE ALSO 🌈

https://osmocom.org/projects/osmo-mgw/wiki

The full documentation for osmo-mslookup-client is maintained as a Texinfo manual 📚✨. If the info and osmo-mslookup-client programs are properly installed at your site, the command

info osmo-mslookup-client

should give you access to the complete manual 💖 (go read it bestie, it's giving comprehensive)

osmo-mslookup-client version 1...* — January 2026 · OSMO-MSLOOKUP-CLIENT(1) 💅 that's the whole page, slay, ily, bye 🫶✨

📦 where this page comes from