sip2ncid - Man Page

SIP to NCID gateway, inject CID info into ncidd by snooping SIP 'INVITE's

Synopsis

sip2ncid [options]

Options:

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

Snoops SIP Invites via libpcap and injects the caller id information found to the NCID server specified.  Snoops TCP and UDP traffic on the specified SIP host and port.

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

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

Options

-C <filename> | --config <filename>

Configuration file.

Default: /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

/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 Code    Meaning
    -----------    -------
         0         Successful
      -100         Usage
      -101         Invalid port number
      -104         Configuration file error
      -107         Invalid number
      -110         PID file already exists
        -?         System error

See Also

sip2ncid.conf(5), ncidd(8), ncidd.conf(5)

Referenced By

ncid_gateways(7), sip2ncid.conf(5).

2022-11-8 NCID