SIP2NCID(8)

📦 version 1.18, in fedora 43, fedora 44

💅 SIP2NCID — the sip2ncid(8) manual, but make it make sense

okay bestie, so this is sip2ncid(8) from the NCID section of your manual pages, and I'm gonna walk you through it like we're texting at 2am 🦋

✨ NAME ✨

sip2ncid — a SIP to NCID gateway, aka it injects CID info into ncidd by snooping SIP INVITEs 👀✨

🌸 SYNOPSIS 🌸

sip2ncid [options]

Options, bestie:

[-C <filename>      | --config <filename>]
[-D                 | --debug]
[-h                 | --help]
[-H <0|1>           | --hostname-flag <0|1>]
[-i <interface>     | --interface <interface>]
[-l                 | --listdevs]
[-L <filename>      | --logfile <filename>]
[-n <[host][:port]> | --ncid <[host][:port]>]
[-P <filename>      | --pidfile <filename>]
[-r <dumpfile>      | --readfile <dumpfile>]
[-s <[host][:port]> | --sip <[host][:port]>]
[-S <1-9>           | --lineid-size <1-9>]
[-t                 | --testsip]
[-T                 | --testall]
[-v <1-9>           | --verbose <1-9>]
[-V                 | --version]
[-w <dumpfile>      | --writefile <dumpfile>]
[-W <0|1>           | --warn <0|1>]
[--osx-launchd]

💖 DESCRIPTION 💖

So what it does: it snoops SIP Invites via libpcap and injects the caller id information it finds to the NCID server you specified. It snoops TCP and UDP traffic on the specified SIP host and port. no cap 🫶

The sip2ncid gateway uses the trailing digits of a phone line as the lineid for each phone line monitored. The default number of trailing digits is 4, unless you change it with the extension-size option.

The log file is /var/log/sip2ncid.log.

If a pid file is given — usually /var/run/sip2ncid.pid — then a pid file used to store the process ID. (yes that's literally what it says, iconic 💅)

The configuration file for sip2ncid is prefix3=/etc/ncid/sip2ncid.conf.

👑 OPTIONS 👑

  • -C <filename>, --config <filename> — the configuration file. Default: prefix3=/etc/ncid/sip2ncid.conf
  • -D, --debug — debug mode, sip2ncid stays attached to the terminal 🖥️
  • -h, --help — prints this help
  • -H <0|1>, --hostname-flag <0|1> — sets the hosthame flag so the IDENT string sent to a server will include the hostname with the program name. Default: 0
  • -i <interface>, --interface <interface> — specifies the network interface to snoop on. If this is not specified then libpcap will pick a network interface. This will generally be the first Ethernet interface found.
  • -l, --listdevs — returns a list of all network device names that can be used 🧚
  • -L <filename>, --logfile <filename> — specifies the logfile name to use. The logfile must exist before it is used. Default log filename: /var/log/sip2ncid.log
  • -n <[host][:port]>, --ncid <[host][:port]> — specifies the NCID server to connect to. Port may be specified by suffixing the hostname with <:port>, or if you only want to change the port, just <:port>. By default it will connect to port 3333 on "127.0.0.1".
  • -P <filename>, --pidfile <filename> — specifies the pidfile name to write. Set to /var/run/ncidd.pid in a rc or init script when used as a service. The program will still run if it does not have permission to write a pidfile. There is no default. If pidfile is not set, no pid file will be used.
  • -r <dumpfile>, --readfile <dumpfile> — read packets from a libpcap capture file instead of the network. This also sets the testsip option, verbose to level 3 and no filter is applied. Mostly only useful for development and debug purposes 🛠️
  • -s <[host][:port]>, --sip <[host][:port]> — specifies the hostname of the SIP device to snoop. Both TCP and UDP protocol packets are automatically monitored. You may also specify the port by suffixing the hostname with :<port>, or if no hostname is wanted, just <:port>. If you do not specify a host, it defaults to the network interface. If you do not specify a port, it defaults to <5061> (Vonage default). Other Vonage ports are 5060 and 10000. The new Vonage default appears to be <10000>.
  • -S <1-9>, --lineid-size <1-9> — specify the number of trailing digits from a phone number to be used as the lineid. On a PBX, this usually represents the extension number. Default: 4
  • -t, --testsip — test for SIP packets. This option is used to check if SIP packets exist without starting the NCID server. It will display the Caller ID line generated when a call comes in and a CANCEL line if cancel was generated. It will not send any CID data to NCID. It also sets the debug option.
  • -T, --testall — test for all packets. This option is used to check for IP packets without starting the NCID server. It will display a packet count and the packet type. It will not send any CID data to NCID. It also sets the debug option.
  • -v <1-9>, --verbose <1-9> — verbose mode. Send information into the logfile and display information for the -D option. Set a higher number for more information. To debug, try: verbose = 3 Default: verbose = 1
  • -V, --version — displays the version ⭐
  • -w <dumpfile>, --writefile <dumpfile> — write packets to a libpcap capture file. This also sets the debug option, verbose to level 3 and no filter is applied. Mostly only useful for development and debug purposes 🛠️
  • -W <0|1>, --warn <0|1> — send 'No SIP packets' or 'SIP packets returned' messages to clients Default: warn = 0
  • --osx-launchd — this option is only for Mac OSX when using launchd to control sip2ncid. It prevents sip2ncid from entering daemon mode. It is like debug mode, but nothing is printed to the screen. 🍎

🎀 FILES 🎀

prefix3=/etc/ncid/sip2ncid.conf
/var/run/sip2ncid.pid
/var/log/sip2ncid.log

🌈 MESSAGES FORMAT 🌈

CALL: ###DATE<MMDDHHMM>...LINE<####>...NMBR<###########>...NAME<words>+++
CALLINFO: ###CANCEL...NMBR<###########>...DATE<MMDDHHMM+++
CALLINFO: ###BYE...NMBR<###########>...DATE<MMDDHHMM>+++

✨ Example ✨

CALL: ###DATE05311233...LINE1122...NMBR13215551212...NAMEBig John+++

🔥 EXAMPLES 🔥

# run sip2ncid as root and view status and SIP packets:
sip2ncid -Dv3
# run sip2ncid as root and list all network device names:
sip2ncid --listdevs
# run sip2ncid as root in test mode to look for SIP packets.
sip2ncid --testsip
# run sip2ncid as root in test mode to look for any packets.
sip2ncid --testall

💀 DIAGNOSTICS 💀

Return codes, bestie — here's the whole lineup:

  • 0 — Successful ✅
  • -100 — Usage
  • -101 — Invalid port number
  • -104 — Configuration file error
  • -107 — Invalid number
  • -110 — PID file already exists
  • -? — System error
(the original spells this out as a little table with Return Code and Meaning columns, but we're keeping the same numbers, same order, same meanings 💜)

🦋 SEE ALSO 🦋

sip2ncid.conf.5, ncidd.8, ncidd.conf.5

and that's the whole page, bestie, you ate it up 💅✨ This lil slice of NCID lore is from 2022-11-8, and it's living in the NCID manual — so if you forget everything else, remember: it snoops SIP INVITEs, it talks to ncidd, and it's lowkey iconic 🎀🫶

📦 where this page comes from