1NCIDD(8)                             NCID                             NCIDD(8)
2
3
4

NAME

6       ncidd - Network Caller ID Server
7

SYNOPSIS

9       ncidd [options]
10
11       Options:
12
13       [-A <file>       | --alias <file>]
14       [-a <file>       | --announce <file>]
15       [-B <file>       | --blacklist <file>]
16       [-C <file>       | --config <file>]
17       [-c <file>       | --cidlog <file>]
18       [-D              | --debug]
19       [-d <file>       | --datalog <file>]
20       [-e <identifier> | --lineid <identifier>]
21       [-f <command>    | --audiofmt <command>]
22       [-g <0|1>        | --gencid <0|1>]
23       [-H <0|1|2|3>    | --hangup <0|1|2|3>]
24       [-h              | --help]
25       [-I <string>     | --initstr <string>]
26       [-i <string>     | --initcid <string>]
27       [-j <0|1|2|3>    | --cidinput <0|1|2|3>]
28       [-L <file>       | --logfile <file>]
29       [-l <file>       | --lockfile <file>]
30       [-M <MaxBytes>   | --cidlogmax <MaxBytes>]
31       [-m <0|1|2|3>    | --hupmode <0|1|2|3>]
32       [-N <0|1>        | --noserial <0|1>] (Obsolete, replaced by -j|--cidinput)
33       [-n <0|1>        | --nomodem <0|1>] (Obsolete, replaced by -j|--cidinput)
34       [-P <file>       | --pidfile <file>]
35       [-p <portnumber> | --port <portnumber>]
36       [-Q <dotted-ip>  | --ifaddr <dotted-ip>]
37       [-r <0|1|2>      | --regex <0|1|2>]
38       [-S <ttyspeed>   | --ttyspeed <ttyspeed>]
39       [-s <datatype>   | --send <datatype>]
40       [-T <0|1>        | --ttyclocal <0|1>]
41       [-t <ttyport>    | --ttyport <ttyport>]
42       [-V              | --version]
43       [-v <1-9>        | --verbose <1-9>]
44       [-W <file>       | --whitelist <file>]
45       [--osx-launchd]
46

DESCRIPTION

48       The ncidd server collects Caller ID data from:
49
50           - one of more modems or CID devices on a telephone line
51           - one of more CID gateways on the network
52           - or both modems and gateways
53
54       It  formats  the data on a single text line and then sends it to one or
55       more Network Caller ID (NCID) clients over TCP/IP.   The  ncidd  server
56       also allows an alias for the number, an alias for the name and an alias
57       for the telephone line identifier.
58
59       The telephone company limits names to 15 upper case characters,  so  by
60       using the alias function, you can display the name as you would like to
61       view it, or correct a name that was truncated.  You can even change  or
62       mask (hide) a telephone number.
63
64       The  send  cidinfo  option  configures  ncidd to send a CIDINFO line to
65       clients at each ring and when ringing stops.  It contains  a  telephone
66       LINE label and a RING indicator.
67
68       If  the  Caller  ID is obtained from a modem and the modem supports it,
69       the server will include a ring count in each CIDINFO line.  When  ring‐
70       ing  stops,  the  ring count will be zero.  This allows, for example, a
71       client to send the call information to a pager or cell phone on a  spe‐
72       cific  ring count.  If the ring count is not reached, it is assumed the
73       phone was answered and there is no need to send a page  or  cell  phone
74       notification.
75
76       If  ncidd is using a modem that indicates ring but not Caller ID, ncidd
77       can handle calls without Caller ID by generating call data on ring num‐
78       ber  2  and  sending  it  to the connected clients.  The number will be
79       "RING" and the name will be "No Caller ID".  This feature is on by  de‐
80       fault.
81
82       If  the  Caller  ID is obtained from a Gateway, the CIDINFO line may be
83       sent at the beginning and end of a call.  At the end of  a  call,  RING
84       indicates  either  Hangup  Without Answer or Hangup after Answer.  This
85       allows a cell phone or pager to receive a message only if the phone was
86       not answered.
87
88       If  the  Caller  ID  is  obtained from a Gateway that supports outgoing
89       calls and the send callout option is configured, ncidd will send outgo‐
90       ing call text lines to the clients.
91
92       If  the  Caller  ID  is obtained from a Gateway that supports automatic
93       hangup, ncidd will send hangup call text lines to the clients.
94
95       Internal Hangup refers to call termination that is based on the  black‐
96       list and whitelist files. A Hangup Extension refers to call termination
97       that is based on a user-defined external script or program.
98
99       If the Internal Hangup --hangup  option  and/or  the  Hangup  Extension
100       --hupmode  option  is  configured,  ncidd will automatically hangup the
101       call and send a hangup (HUP) text line to the  clients.  Both  --hangup
102       and  --hupmode  have identical modes: normal hangup, FAX hangup and An‐
103       nounce hangup. If the --hangup option and/or --hupmode option  is  con‐
104       figured  for  FAX  hangup,  but  the  modem does not support FAX, ncidd
105       changes the mode from a FAX hangup to a normal  hangup.  Similarly,  if
106       the  --hangup option and/or --hupmode option is configured for Announce
107       hangup, but the modem does not support Voice or the  Announcement  file
108       is  missing,  ncidd  changes hangup from an Announce hangup to a normal
109       hangup.
110
111       A client can send ncidd a text message.  The text message is then  sent
112       to all connected clients, including the one that sent it.
113
114       A  client can also send ncidd a job.  The job can be adding, modifying,
115       or deleting entries from the alias file;  adding  or  removing  entries
116       from  the blacklist or whitelist files; updating the call logs; dialing
117       a number.
118
119       Gateways send ncidd a CALL text line.  The CALL text line is either  an
120       incoming  call (CID), an outgoing call (OUT), a hangup (HUP), or a mes‐
121       sage (MSG).  Gateways are normally used in place of a  modem,  but  can
122       also be used with a modem connected to ncidd.
123
124       Gateways  also send ncidd CALLINFO text lines.  A SIP gateway will send
125       a CALLINFO line when it receives a CANCEL or BYE command.   The  server
126       then  sends a ring count of -1 to its clients to indicate a hangup with
127       no answer.
128
129       The NCID gateway sends ncidd CID and CIDINFO text lines instead of  the
130       normal gateway CALL and CALLINFO lines which need conversion.
131
132       When  ncidd  receives  a SIGHUP signal, it reloads the alias, blacklist
133       and whitelist files.
134
135       When ncidd receives a SIGUSR2 signal, it  sends  a  list  of  connected
136       clients to the logfile.  This is for troubleshooting in debug mode.
137

OPTIONS

139       -A <file> | --alias <file>
140              Alias file.
141              Default: /etc/ncid/ncidd.alias
142       -a <file> | --announce <file>
143              Announcement file. Used for the Internal Hangup Announce option,
144              --hangup 3.  If a Hangup Extension is enabled with  --hupmode  3
145              but  the  Hangup Extension does not specify its own Announcement
146              file, it will default to this announcement file.
147              Default: /usr/share/ncid/recordings/DisconnectedNotInService.rmd
148       -B <file> | --blacklist <file>
149              Blacklist file used for Internal Hangups.
150              Default: /etc/ncid/ncidd.blacklist
151       -C <file> | --config <file>
152              Config file.
153              Default: /etc/ncid/ncidd.conf
154       -c <file> | --cidlog <file>
155              Call log data file.
156              Default: /var/log/cidcall.log
157       -D | --debug
158              In debug mode, ncidd stays attached to the terminal and displays
159              all messages that go to the server logfile.
160              Default: verbose 3
161       -d <file> | --datalog <file>
162              Data logfile, used to capture the raw data sent to/received from
163              ncidd.  This is usually the data to/from a modem, CID device  or
164              gateway.  The logfile must exist, ncidd will not create it.
165              Default: /var/log/ciddata.log
166       -e <identifier> | --lineid <identifier>
167              The  telephone line identifier is used for a modem or serial de‐
168              vice.  It is normally 1 to 16 characters.  The default indicator
169              is  POTS If you have multiple telephone lines, you probably want
170              to change the identifier from POTS to the 4 digit  extension  of
171              your  exchange  office.  For example, if the telephone number is
172              321-555-1212 the identifier would be 1212.
173
174              When the gateway provides Caller ID and a hangup is required  by
175              the  modem  connected to the same phone line, the line indicator
176              must be changed to the gateway line indicator.
177
178              For example, if the xdmf2ncid  gateway  line  indicator  (corre‐
179              sponds  to  the device name) is "CometUSB0" or "HoltekUSB0", the
180              line indicator must be changed to CometUSB0 or HoltekUSB0.
181              Default: -
182       -f <command> | --audiofmt <command>
183              Used for the Internal Hangup Announce option, --hangup 3 and for
184              a Hangup Extension Announce option, --hupmode 3.  The audio for‐
185              mat command is very dependent on the modem.  It must  match  the
186              number  of  one  of the lines returned by AT+VSM=?.  The default
187              modem manufacturer is CONEXANT, but the voice  file  also  works
188              for  U.S.  Robotics  provided  the  modem firmware version is at
189              least V1.2.23.
190              Default: AT+VSM=130
191       -g <0|1> | --gencid <0|1>
192              Generate a generic Caller ID at ring 2 if one  is  not  received
193              from  the  modem,  either because the telco is not sending it or
194              because the modem does not support it.  The  generic  Caller  ID
195              generated  uses "RING" for the number and "No Caller ID" for the
196              name.
197              Default: gencid = 1
198       -H <0|1|2|3> | --hangup <0|1|2|3>
199              Controls Internal Hangup that will  automatically  hangup  on  a
200              call if the caller name or number is in the ncidd.blacklist file
201              but not the ncidd.whitelist file. If --hangup is set to 1, ncidd
202              will  immediately  hangup  the  call.   If --hangup is set to 2,
203              ncidd will generate FAX tones and then hangup the call. (If  FAX
204              mode  does  not  produce  FAX  tones  try  setting pickup = 0 in
205              ncidd.conf.) If --hangup is set to 3, ncidd  will  play  an  an‐
206              nouncement file and then hangup the call.
207              Default: hangup = 0
208       -h | --help
209              Display a help message.
210       -I <string> | --initstr <string>
211              Modem initialization string.
212              Default: ATE1V1Q0
213       -i <string> | --initcid <string>
214              CID initialization string.
215              Default: AT+VCID=1
216              if it fails: AT#CID=1
217       -j <0|1|2|3> | --cidinput <0|1|2|3>
218              Determines the Caller ID input source:
219              0: Caller ID from a modem and optional gateways
220              1: Caller ID from a serial or USB device and optional gateways
221              2: Caller ID from a gateway with modem support
222              3: Caller ID from gateways without modem support
223              Default: cidinput = 0
224       -L <file> | --logfile <file>
225              Server logfile.
226              Default: /var/log/ncidd.log
227       -l <file> | --lockfile <file>
228              Modem lockfile.
229              Default: /var/lock/LCK..modem
230       -M <MaxBytes> | --cidlogmax <MaxBytes>
231              Set the maximum CID call logfile size in bytes.
232              Maximum size is 100000000.
233              Default: cidlogmax = 110000
234       -m <0|1|2|3> | --hupmode <0|1|2|3>
235              A  Hangup  Extension  uses the same modes as the Internal Hangup
236              setting, --hangup.  It enables an external script or program  to
237              determine if ncidd should hangup or not. It can be used with and
238              without the Internal  Hangup.  If  used  with  Internal  Hangup,
239              --hupmode  is  only executed if the Internal Hangup is not going
240              to terminate the call.
241
242              If --hupmode is set to 1,  ncidd  will  immediately  hangup  the
243              call.   If  --hupmode is set to 2, ncidd will generate FAX tones
244              and then hangup the call.  (If FAX mode  does  not  produce  FAX
245              tones try setting pickup = 0 in ncidd.conf.) If --hupmode is set
246              to 3, ncidd will play an announcement file and then  hangup  the
247              call.
248              Default: hupmode = 0
249       -N <0|1> | --noserial <0|1> (Obsolete, replaced by -j|--cidinput)
250              Serial device is being used (0) or no serial device (1).
251              Default: noserial = 0
252       -n <0|1> | --nomodem <0|1> (Obsolete, replaced by -j|--cidinput)
253              Modem is being used (0) or no modem (1).
254              Default: nomodem = 0
255       -P <pidfile> | --pidfile <pidfile>
256              Server  PID  file.   Set  to /var/run/ncidd.pid in an rc or init
257              script when ncidd is used as a service. The program  will  still
258              run  if it does not have permission to write a pidfile. There is
259              no default.  If pidfile is not set, no pid file will be used.
260       -p <port> | --port <port>
261              Server port.
262              Default: 3333
263       -Q <dotted-ip> | --ifaddr <dotted-ip>
264              Restrict connections to the interface associated  with  this  IP
265              address.
266              Default:  Port  accepts  client or gateway connections from any‐
267              where.
268       -r <0|1|2> | --regex <0|1|2>
269              Use 0 for Simple Expressions (default)
270              Use 1 for Posix Extended Regular Expressions
271              Use 2 for Perl-compatible Regular Expressions
272
273              NCID Simple Expression Syntax
274              ^   = partial match from beginning
275              *   = partial match after the '*'
276              ^1? = optional leading 1 for US numbers only
277
278              Posix Regular Expression Description and Syntax:
279              https://en.wikipedia.org/wiki/Regular_expression
280
281              Perl-compatible regular expression syntax Cheatsheet
282              https://www.debuggex.com/cheatsheet/regex/pcre
283
284              Introduction to Regular Expressions:
285              http://www.regular-expressions.info/quickstart.html
286
287              Default: regex = 0
288       -S <ttyspeed> | --ttyspeed <ttyspeed>
289              Set the tty port speed to one of: 115200,  38400,  19200,  9600,
290              4800, 2400, 1200
291              Default: ttyspeed = 115200
292       -s <datatype> | --send <datatype>
293              Send optional CID data to a client.  Where datatype is:
294              cidlog: sent when the client connects.  If the CID call log gets
295              too big, it will not be sent.
296              cidinfo: sent on each ring, to all clients,  gives  the  current
297              ring count.
298              Default: Optional CID DATA is not sent
299       -T <0|1> | --ttyclocal <0|1>
300              Enable (0) or disable (1) modem control signals.
301              Default: modem control signals enabled
302       -t <ttyport> | --ttyport <ttyport>
303              Modem device file, or serial port that provides Caller ID infor‐
304              mation.
305              Default: /dev/modem
306       -V | --version
307              Display the version number.
308       -v <1-9> | --verbose <1-9>
309              Verbose mode. Sends information to the server logfile  and  dis‐
310              plays  information  for the -D  option.  Set a higher number for
311              more information.  Do not use level 9 unless there is a  problem
312              in poll().  It grows the logfile very fast.
313              To debug, try: verbose = 3
314              Default: verbose = 1
315       -W <file> | --whitelist <file>
316              Whitelist file used for Internal Hangups.
317              Default: /etc/ncid/ncidd.whitelist
318       --osx-launchd
319              This option is only for OSX when using launchd to control ncidd.
320              It prevents ncidd from entering daemon mode.  It is  like  debug
321              mode, but nothing is printed to the screen.
322

CONFIGURATION

324       The  ncidd.conf(5)  file  is  used  to  set options.  The syntax of the
325       ncidd.conf(5) file is discussed separately and should be consulted  for
326       detailed reference information.
327
328       The  ncidd.alias(5)  file is used to create aliases.  The syntax of the
329       ncidd.alias(5) file is discussed separately and should be consulted for
330       detailed reference information.
331

DATA LINE FORMAT EXAMPLES

333       These are six examples of the four types of lines sent to NCID clients.
334       The first field identifies the type of info which follows.
335
336       The CID: line gives the CID information of the current call.
337
338       The CIDLOG: line gives the CID information of a line in  the  CID  log‐
339       file.
340
341       The MSG: line gives messages from the server.
342
343       The MSGLOG: line gives a message logged in the CID logfile.
344
345       The  CIDINFO:  line gives a line number and ring count from the server.
346       The ring count starts at 1 and increases until ringing ends,  at  which
347       time  a  count of 0 is sent.  The line number default is 1. If Distinc‐
348       tive Ring service is being provided by the telco, ncidd will add one of
349       the letters A, B, C, or D to indicate the virtual line called.
350
351       The  CID: and CIDLOG: lines are identical, with data stored as name and
352       value pairs.  Clients should always locate the line identifier and then
353       scan for a field name and get its value.  It's possible that additional
354       name/value pairs may be added in the future.
355
356       The MSG: and MSGLOG: lines are identical,
357
358       CID: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
359       CIDLOG: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
360       CIDINFO: *LINE*line indicator*RING*ringcount*TIME*hh:mm:ss*
361       MSG: Too many clients connected: 15
362       MSGLOG: Too many clients connected: 15
363       CIDOUT: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*NONAME*
364

FILES

366       /etc/ncid/ncidd.blacklist
367              Blacklist file
368
369       /etc/ncid/ncidd.whitelist
370              Whitelist file
371
372       /etc/ncid/ncidd.conf
373              Configuration file
374
375       /var/run/ncidd.pid
376              PID file
377
378       /var/log/cidcall.log
379              Contains CID and MSG lines
380
381       /var/log/ciddata.log
382              Contains the output from the modem, device or gateway.
383
384       /var/log/ncidd.log
385              Server logfile.  Contents controlled by --verbose.
386

DIAGNOSTICS

388           Return Code    Meaning
389           -----------    -------
390                0         Successful
391             -100         Usage
392             -101         Invalid port number
393             -102         TTY lockfile exists
394             -103         Unable to set modem for Caller ID
395             -104         Configuration file error
396             -105         No modem found
397             -106         Invalid data type.
398             -107         Invalid number
399             -108         Invalid tty port speed [set in config file]
400             -109         Alias file error
401             -110         PID file already exists
402             -111         Cannot init TTY
403             -112         Serial device error
404             -113         string too long
405             -114         Blacklist or whitelist file error
406               -?         System error
407

SEE ALSO

409       ncidd.conf.5,  ncidd.alias.5,   ncidd.blacklist.5,   ncidd.whitelist.5,
410       ncidrotate.1, ncid_extensions.7, ncid_gateways.7, ncid_tools.7, ncid.1,
411       lcdncid.1
412
413
414
415NCID                               2021-12-8                          NCIDD(8)
Impressum