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.8.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 <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

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.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.