ncidd - Man Page

ncidd [options]

Options:

[-A <file>       | --alias <file>]
[-a <file>       | --announce <file>]
[-B <file>       | --blacklist <file>]
[-C <file>       | --config <file>]
[-c <file>       | --cidlog <file>]
[-D              | --debug]
[-d <file>       | --datalog <file>]
[-e <identifier> | --lineid <identifier>]
[-f <command>    | --audiofmt <command>]
[-g <0|1>        | --gencid <0|1>]
[-H <0|1|2|3>    | --hangup <0|1|2|3>]
[-h              | --help]
[-I <string>     | --initstr <string>]
[-i <string>     | --initcid <string>]
[-j <0|1|2|3>    | --cidinput <0|1|2|3>]
[-L <file>       | --logfile <file>]
[-l <file>       | --lockfile <file>]
[-M <MaxBytes>   | --cidlogmax <MaxBytes>]
[-m <0|1|2|3>    | --hupmode <0|1|2|3>]
[-N <0|1>        | --noserial <0|1>] (Obsolete, replaced by -j|--cidinput)
[-n <0|1>        | --nomodem <0|1>] (Obsolete, replaced by -j|--cidinput)
[-P <file>       | --pidfile <file>]
[-p <portnumber> | --port <portnumber>]
[-Q <dotted-ip>  | --ifaddr <dotted-ip>]
[-r <0|1|2>      | --regex <0|1|2>]
[-S <ttyspeed>   | --ttyspeed <ttyspeed>]
[-s <datatype>   | --send <datatype>]
[-T <0|1>        | --ttyclocal <0|1>]
[-t <ttyport>    | --ttyport <ttyport>]
[-V              | --version]
[-v <1-9>        | --verbose <1-9>]
[-W <file>       | --whitelist <file>]
[--osx-launchd]

The ncidd server collects Caller ID data from:

    - one of more modems or CID devices on a telephone line
    - one of more CID gateways on the network
    - or both modems and gateways

It formats the data on a single text line and then sends it to one or more Network Caller ID (NCID) clients over TCP/IP. The ncidd server also allows an alias for the number, an alias for the name and an alias for the telephone line identifier.

The telephone company limits names to 15 upper case characters, so by using the alias function, you can display the name as you would like to view it, or correct a name that was truncated. You can even change or mask (hide) a telephone number.

The send cidinfo option configures ncidd to send a CIDINFO line to clients at each ring and when ringing stops. It contains a telephone LINE label and a RING indicator.

If the Caller ID is obtained from a modem and the modem supports it, the server will include a ring count in each CIDINFO line. When ringing stops, the ring count will be zero. This allows, for example, a client to send the call information to a pager or cell phone on a specific ring count.  If the ring count is not reached, it is assumed the phone was answered and there is no need to send a page or cell phone notification.

If ncidd is using a modem that indicates ring but not Caller ID, ncidd can handle calls without Caller ID by generating call data on ring number 2 and sending it to the connected clients.  The number will be "RING" and the name will be "No Caller ID".  This feature is on by default.

If the Caller ID is obtained from a Gateway, the CIDINFO line may be sent at the beginning and end of a call.  At the end of a call, RING indicates either Hangup Without Answer or Hangup after Answer. This allows a cell phone or pager to receive a message only if the phone was not answered.

If the Caller ID is obtained from a Gateway that supports outgoing calls and the send callout option is configured, ncidd will send outgoing call text lines to the clients.

If the Caller ID is obtained from a Gateway that supports automatic hangup, ncidd will send hangup call text lines to the clients.

Internal Hangup refers to call termination that is based on the blacklist and whitelist files. A Hangup Extension refers to call termination that is based on a user-defined external script or program.

If the Internal Hangup --hangup option and/or the Hangup Extension --hupmode option is configured, ncidd will automatically hangup the call and send a hangup (HUP) text line to the clients. Both --hangup and --hupmode have identical modes: normal hangup, FAX hangup and Announce hangup. If the --hangup option and/or --hupmode option is configured for FAX hangup, but the modem does not support FAX, ncidd changes the mode from a FAX hangup to a normal hangup. Similarly, if the --hangup option and/or --hupmode option is configured for Announce hangup, but the modem does not support Voice or the Announcement file is missing, ncidd changes hangup from an Announce hangup to a normal hangup.

A client can send ncidd a text message.  The text message is then sent to all connected clients, including the one that sent it.

A client can also send ncidd a job.  The job can be adding, modifying, or deleting entries from the alias file; adding or removing entries from the blacklist or whitelist files; updating the call logs; dialing a number.

Gateways send ncidd a CALL text line.  The CALL text line is either an incoming call (CID), an outgoing call (OUT), a hangup (HUP), or a message (MSG).  Gateways are normally used in place of a modem, but can also be used with a modem connected to ncidd.

Gateways also send ncidd CALLINFO text lines. A SIP gateway will send a CALLINFO line when it receives a CANCEL or BYE command.  The server then sends a ring count of -1 to its clients to indicate a hangup with no answer.

The NCID gateway sends ncidd CID and CIDINFO text lines instead of the normal gateway CALL and CALLINFO lines which need conversion.

When ncidd receives a SIGHUP signal, it reloads the alias, blacklist and whitelist files.

When ncidd receives a SIGUSR2 signal, it sends a list of connected clients to the logfile.  This is for troubleshooting in debug mode.

-A <file> | --alias <file>

Alias file.

Default: /etc/ncid/ncidd.alias

-a <file> | --announce <file>

Announcement file. Used for the Internal Hangup Announce option, --hangup 3. If a Hangup Extension is enabled with --hupmode 3 but the Hangup Extension does not specify its own Announcement file, it will default to this announcement file.

Default: /usr/share/ncid/recordings/DisconnectedNotInService.rmd

-B <file> | --blacklist <file>

Blacklist file used for Internal Hangups.

Default: /etc/ncid/ncidd.blacklist

-C <file> | --config <file>

Config file.

Default: /etc/ncid/ncidd.conf

-c <file> | --cidlog <file>

Call log data file.

Default: /var/log/cidcall.log

-D | --debug

In debug mode, ncidd stays attached to the terminal and displays all messages that go to the server logfile.

Default: verbose 3

-d <file> | --datalog <file>

Data logfile, used to capture the raw data sent to/received from ncidd. This is usually the data to/from a modem, CID device or gateway. The logfile must exist, ncidd will not create it.

Default: /var/log/ciddata.log

-e <identifier> | --lineid <identifier>

The telephone line identifier is used for a modem or serial device. It is normally 1 to 16 characters.  The default indicator is POTS If you have multiple telephone lines, you probably want to change the identifier from POTS to the 4 digit extension of your exchange office. For example, if the telephone number is 321-555-1212 the identifier would be 1212.

When the gateway provides Caller ID and a hangup is required by the modem connected to the same phone line, the line indicator must be changed to the gateway line indicator.

For example, if the xdmf2ncid gateway line indicator (corresponds to the device name) is "CometUSB0" or "HoltekUSB0", the line indicator must be changed to CometUSB0 or HoltekUSB0.

Default: -

-f <command> | --audiofmt <command>

Used for the Internal Hangup Announce option, --hangup 3 and for a Hangup Extension Announce option, --hupmode 3. The audio format command is very dependent on the modem.  It must match the number of one of the lines returned by AT+VSM=?. The default modem manufacturer is CONEXANT, but the voice file also works for U.S. Robotics provided the modem firmware version is at least V1.2.23.

Default: AT+VSM=130

-g <0|1> | --gencid <0|1>

Generate a generic Caller ID at ring 2 if one is not received from the modem, either because the telco is not sending it or because the modem does not support it. The generic Caller ID generated uses "RING" for the number and "No Caller ID" for the name.

Default: gencid = 1

-H <0|1|2|3> | --hangup <0|1|2|3>

Controls Internal Hangup that will automatically hangup on a call if the caller name or number is in the ncidd.blacklist file but not the ncidd.whitelist file. If --hangup is set to 1, ncidd will immediately hangup the call.  If --hangup is set to 2, ncidd will generate FAX tones and then hangup the call. (If FAX mode does not produce FAX tones try setting pickup = 0 in ncidd.conf.) If --hangup is set to 3, ncidd will play an announcement file and then hangup the call.

Default: hangup = 0

-h | --help

Display a help message.

-I <string> | --initstr <string>

Modem initialization string.

Default: ATE1V1Q0

-i <string> | --initcid <string>

CID initialization string.

Default: AT+VCID=1

if it fails: AT#CID=1

-j <0|1|2|3> | --cidinput <0|1|2|3>

Determines the Caller ID input source:

0: Caller ID from a modem and optional gateways
1: Caller ID from a serial or USB device and optional gateways
2: Caller ID from a gateway with modem support
3: Caller ID from gateways without modem support

Default: cidinput = 0

-L <file> | --logfile <file>

Server logfile.

Default: /var/log/ncidd.log

-l <file> | --lockfile <file>

Modem lockfile.

Default: /var/lock/LCK..modem

-M <MaxBytes> | --cidlogmax <MaxBytes>

Set the maximum CID call logfile size in bytes.

Maximum size is 100000000.

Default: cidlogmax = 1000000

-m <0|1|2|3> | --hupmode <0|1|2|3>

A Hangup Extension uses the same modes as the Internal Hangup setting, --hangup.  It enables an external script or program to determine if ncidd should hangup or not. It can be used with and without the Internal Hangup. If used with Internal Hangup, --hupmode is only executed if the Internal Hangup is not going to terminate the call.

If --hupmode is set to 1, ncidd will immediately hangup the call.  If --hupmode is set to 2, ncidd will generate FAX tones and then hangup the call.  (If FAX mode does not produce FAX tones try setting pickup = 0 in ncidd.conf.) If --hupmode is set to 3, ncidd will play an announcement file and then hangup the call.

Default: hupmode = 0

-N <0|1> | --noserial <0|1> (Obsolete, replaced by -j|--cidinput)

Serial device is being used (0) or no serial device (1).

Default: noserial = 0

-n <0|1> | --nomodem <0|1> (Obsolete, replaced by -j|--cidinput)

Modem is being used (0) or no modem (1).

Default: nomodem = 0

-P <pidfile> | --pidfile <pidfile>

Server PID file. Set to /var/run/ncidd.pid in an rc or init script when ncidd is 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.

-p <port> | --port <port>

Server port.

Default: 3333

-Q <dotted-ip> | --ifaddr <dotted-ip>

Restrict connections to the interface associated with this IP address.

Default: Port accepts client or gateway connections from anywhere.

-r <0|1|2> | --regex <0|1|2>

Use 0 for Simple Expressions (default)
Use 1 for Posix Extended Regular Expressions
Use 2 for Perl-compatible Regular Expressions

NCID Simple Expression Syntax

^   = partial match from beginning
*   = partial match after the '*'
^1? = optional leading 1 for US numbers only

Posix Regular Expression Description and Syntax:
https://en.wikipedia.org/wiki/Regular_expression

Perl-compatible regular expression syntax Cheatsheet
https://www.debuggex.com/cheatsheet/regex/pcre

Introduction to Regular Expressions:
http://www.regular-expressions.info/quickstart.html

Default: regex = 0

-S <ttyspeed> | --ttyspeed <ttyspeed>

Set the tty port speed to one of: 115200, 38400, 19200, 9600, 4800, 2400, 1200

Default: ttyspeed = 115200

-s <datatype> | --send <datatype>

Send optional CID data to a client. Where datatype is: cidlog: sent when the client connects. If the CID call log gets too big, it will not be sent.

cidinfo: sent on each ring, to all clients, gives the current ring count.

Default: Optional CID DATA is not sent

-T <0|1> | --ttyclocal <0|1>

Enable (0) or disable (1) modem control signals.

Default: modem control signals enabled

-t <ttyport> | --ttyport <ttyport>

Modem device file, or serial port that provides Caller ID information.

Default: /dev/modem

-V | --version

Display the version number.

-v <1-9> | --verbose <1-9>

Verbose mode. Sends information to the server logfile and displays information for the -D  option.  Set a higher number for more information.

Do not use level 9 unless there is a problem in poll().  It grows the logfile very fast.

To debug, try: verbose = 3

Default: verbose = 1

-W <file> | --whitelist <file>

Whitelist file used for Internal Hangups.

Default: /etc/ncid/ncidd.whitelist

--osx-launchd

This option is only for OSX when using launchd to control ncidd.  It prevents ncidd from entering daemon mode.  It is like debug mode, but nothing is printed to the screen.

The ncidd.conf(5) file is used to set options. The syntax of the ncidd.conf(5) file is discussed separately and should be consulted for detailed reference information.

The ncidd.alias(5) file is used to create aliases. The syntax of the ncidd.alias(5) file is discussed separately and should be consulted for detailed reference information.

These are six examples of the four types of lines sent to NCID clients. The first field identifies the type of info which follows.

The CID: line gives the CID information of the current call.

The CIDLOG: line gives the CID information of a line in the CID logfile.

The CID: and CIDLOG: lines are identical, with data stored as name and value pairs. Clients should always locate the line identifier and then scan for a field name and get its value. It's possible that additional name/value pairs may be added in the future.

CID: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
CIDLOG: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*

The CIDINFO: line gives a line number and ring count from the server. The ring count starts at 1 and increases until ringing ends, at which time a count of 0 is sent. The line number default is 1. If Distinctive Ring service is being provided by the telco, ncidd will add one of the letters A, B, C, or D to indicate the virtual line called.

CIDINFO: *LINE*line indicator*RING*ringcount*TIME*hh:mm:ss*

The MSG: line gives messages from the server.

The MSGLOG: line gives a message logged in the CID logfile.

The MSG: and MSGLOG: lines are identicalformat:

MSG: Too many clients connected: 15
MSGLOG: Too many clients connected: 15

The CIDOUT: line gives outgoing call information.

CIDOUT: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*NONAME*

Blacklist file:

/etc/ncid/ncidd.blacklist

Whitelist file:

/etc/ncid/ncidd.whitelist

Configuration file:

/etc/ncid/ncidd.conf

PID file:

/var/run/ncidd.pid

Call and Message Log:

/var/log/cidcall.log

Modem, Device, or Gateway Output:

/var/log/ciddata.log

Server logfile:

/var/log/ncidd.log (Contents controlled by --verbose.)

    Return Code    Meaning
    -----------    -------
         0         Successful
      -100         Usage
      -101         Invalid port number
      -102         TTY lockfile exists
      -103         Unable to set modem for Caller ID
      -104         Configuration file error
      -105         No modem found
      -106         Invalid data type.
      -107         Invalid number
      -108         Invalid tty port speed [set in config file]
      -109         Alias file error
      -110         PID file already exists
      -111         Cannot init TTY
      -112         Serial device error
      -113         string too long
      -114         Blacklist or whitelist file error
        -?         System error

ncidd.conf(5), ncidd.alias(5), ncidd.blacklist(5), ncidd.whitelist(5), ncidrotate(1), ncid_extensions(7), ncid_gateways(7), ncid_tools(7), ncid(1), lcdncid.1

artech2ncid(1), artech2ncid.conf(5), cideasy2ncid(1), cideasy2ncid.conf(5), email2ncid(1), get-areacodes-list(1), get-fcc-list(1), hangup-calls(1), hangup-closed-skel(1), hangup-combo(1), hangup-fakenum(1), hangup-fcc(1), hangup-greylist(1), hangup-message-skel(1), hangup-nohangup(1), hangup-postal-code(1), hangup-skel(1), ncid(1), ncid2ncid(1), ncid-alert(1), ncidd.alias(5), ncidd.blacklist(5), ncidd.conf(5), ncidd.greylist(5), ncidd.whitelist(5), ncid-initmodem(1), ncid-kpopup(1), ncid-mysql(1), ncid-mysql-setup(8), ncid-mythtv(1), ncid-notify(1), ncidnumberinfo(1), ncid-page(1), ncidrotate(1), ncid-samba(1), ncid-skel(1), ncid-speak(1), ncid-wakeup(1), ncid-yac(1), ncid-yearlog(1), obi2ncid(1), rn2ncid(1), sip2ncid(8), sip2ncid.conf(5), update-cidcall(1), wc2ncid(1), wc2ncid.conf(5), wct(1), xdmf2ncid(1), yac2ncid(1), yac2ncid.conf(5).