osmo-mslookup-client - osmo-mgw

Copyright

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.

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.pyhttp://git.osmocom.org/osmo-hlr/tree/contrib/dgsm/osmo-mslookup-socket.py

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

Name

       osmo-mslookup-client - osmo-mgw

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 <query> <age> <ip1> <port1> <ip2> <port2>

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

       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

              infoosmo-mslookup-client

       should give you access to the complete manual.

osmo-mslookup-client version 1.9.0                 March 2025                            OSMO-MSLOOKUP-CLIENT(1)