1NCIDD(8)                    System Manager's Manual                   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       [-r <0|1|2>      | --regex <0|1|2>]
37       [-S <ttyspeed>   | --ttyspeed <ttyspeed>]
38       [-s <datatype>   | --send <datatype>]
39       [-T <0|1>        | --ttyclocal <0|1>]
40       [-t <ttyport>    | --ttyport <ttyport>]
41       [-V              | --version]
42       [-v <1-9>        | --verbose <1-9>]
43       [-W <file>       | --whitelist <file>]
44       [--osx-launchd]
45

DESCRIPTION

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

OPTIONS

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

CONFIGURATION

317       The  ncidd.conf(5)  file  is  used  to  set options.  The syntax of the
318       ncidd.conf(5) file is discussed separately and should be consulted  for
319       detailed reference information.
320
321       The  ncidd.alias(5)  file is used to create aliases.  The syntax of the
322       ncidd.alias(5) file is discussed separately and should be consulted for
323       detailed reference information.
324

DATA LINE FORMAT EXAMPLES

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

FILES

359       /etc/ncid/ncidd.blacklist
360              Blacklist file
361
362       /etc/ncid/ncidd.whitelist
363              Whitelist file
364
365       /etc/ncid/ncidd.conf
366              Configuration file
367
368       /var/run/ncidd.pid
369              PID file
370
371       /var/log/cidcall.log
372              Contains CID and MSG lines
373
374       /var/log/ciddata.log
375              Contains the output from the modem, device or gateway.
376
377       /var/log/ncidd.log
378              Server logfile.  Contents controlled by --verbose.
379

DIAGNOSTICS

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

SEE ALSO

402       ncidd.conf.5,  ncidd.alias.5,   ncidd.blacklist.5,   ncidd.whitelist.5,
403       ncidrotate.1, ncid_extensions.7, ncid_gateways.7, ncid_tools.7, ncid.1,
404       lcdncid.1
405
406
407
408                                                                      NCIDD(8)
Impressum