--- name: "osmo-mslookup-client" section: "1" platform: "linux" package: "osmo-mslookup-utils" version: "1.9.0+dfsg1-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/osmo-mslookup-client" --- # osmo-mslookup-client(1) osmo-mgw ## NAME osmo-mslookup-client - osmo-mgw ## 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). ⟨https://osmocom.org/projects/osmo-mgw⟩ osmo-mslookup-client version 1.9.0 ## OPTIONS \[\[delay-\]\[timeout\]@\]service.number.id - A service query string with optional individual timeout. The same format is also used on a daemon socket, if any. The timeout consists of the min-delay and the timeout numbers, corresponding to the **--min-delay** and **--timeout** options, in milliseconds. These options apply if a query string lacks own numbers. Examples: - 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 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. **--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"\]} **--daemon** **-d** - Keep running after a request has been serviced **--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. **--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. **--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. **--socket** **-s** */path/to/unix-domain-socket* - Listen to requests from and write responses to a UNIX domain socket. **--send** **-S** \ \ \ \ \ \ - Do not query, but send an mslookup result. This is useful only for testing. 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. **--help** **-h** - This help ## COPYRIGHT Copyright © 2019 by sysmocom - s.f.m.c. GmbH\ Copyright © 2019 by Neels Hofmeyr \ 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. 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.). 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. 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. 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. \- 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. 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 \ 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.