1NCIDD(8) NCID NCIDD(8)
2
6 ncidd - Network Caller ID Server
7
9 ncidd [options]
10 Options:
12 [-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
48 The ncidd server collects Caller ID data from:
49 - 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 The NCID gateway sends ncidd CID and CIDINFO text lines instead of the
130 normal gateway CALL and CALLINFO lines which need conversion.
131 When ncidd receives a SIGHUP signal, it reloads the alias, blacklist
133 and whitelist files.
134 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
139 -A <file> | --alias <file>
140 Alias file.
141 Default: /etc/ncid/ncidd.alias
143 -a <file> | --announce <file>
145 Announcement file. Used for the Internal Hangup Announce option,
146 --hangup 3. If a Hangup Extension is enabled with --hupmode 3
147 but the Hangup Extension does not specify its own Announcement
148 file, it will default to this announcement file.
149 Default: /usr/share/ncid/recordings/DisconnectedNotInService.rmd
151 -B <file> | --blacklist <file>
153 Blacklist file used for Internal Hangups.
154 Default: /etc/ncid/ncidd.blacklist
156 -C <file> | --config <file>
158 Config file.
159 Default: /etc/ncid/ncidd.conf
161 -c <file> | --cidlog <file>
163 Call log data file.
164 Default: /var/log/cidcall.log
166 -D | --debug
168 In debug mode, ncidd stays attached to the terminal and displays
169 all messages that go to the server logfile.
170 Default: verbose 3
172 -d <file> | --datalog <file>
174 Data logfile, used to capture the raw data sent to/received from
175 ncidd. This is usually the data to/from a modem, CID device or
176 gateway. The logfile must exist, ncidd will not create it.
177 Default: /var/log/ciddata.log
179 -e <identifier> | --lineid <identifier>
181 The telephone line identifier is used for a modem or serial de‐
182 vice. It is normally 1 to 16 characters. The default indicator
183 is POTS If you have multiple telephone lines, you probably want
184 to change the identifier from POTS to the 4 digit extension of
185 your exchange office. For example, if the telephone number is
186 321-555-1212 the identifier would be 1212.
187 When the gateway provides Caller ID and a hangup is required by
189 the modem connected to the same phone line, the line indicator
190 must be changed to the gateway line indicator.
191 For example, if the xdmf2ncid gateway line indicator (corre‐
193 sponds to the device name) is "CometUSB0" or "HoltekUSB0", the
194 line indicator must be changed to CometUSB0 or HoltekUSB0.
195 Default: -
197 -f <command> | --audiofmt <command>
199 Used for the Internal Hangup Announce option, --hangup 3 and for
200 a Hangup Extension Announce option, --hupmode 3. The audio for‐
201 mat command is very dependent on the modem. It must match the
202 number of one of the lines returned by AT+VSM=?. The default
203 modem manufacturer is CONEXANT, but the voice file also works
204 for U.S. Robotics provided the modem firmware version is at
205 least V1.2.23.
206 Default: AT+VSM=130
208 -g <0|1> | --gencid <0|1>
210 Generate a generic Caller ID at ring 2 if one is not received
211 from the modem, either because the telco is not sending it or
212 because the modem does not support it. The generic Caller ID
213 generated uses "RING" for the number and "No Caller ID" for the
214 name.
215 Default: gencid = 1
217 -H <0|1|2|3> | --hangup <0|1|2|3>
219 Controls Internal Hangup that will automatically hangup on a
220 call if the caller name or number is in the ncidd.blacklist file
221 but not the ncidd.whitelist file. If --hangup is set to 1, ncidd
222 will immediately hangup the call. If --hangup is set to 2,
223 ncidd will generate FAX tones and then hangup the call. (If FAX
224 mode does not produce FAX tones try setting pickup = 0 in
225 ncidd.conf.) If --hangup is set to 3, ncidd will play an an‐
226 nouncement file and then hangup the call.
227 Default: hangup = 0
229 -h | --help
231 Display a help message.
232 -I <string> | --initstr <string>
234 Modem initialization string.
235 Default: ATE1V1Q0
237 -i <string> | --initcid <string>
239 CID initialization string.
240 Default: AT+VCID=1
242 if it fails: AT#CID=1
244 -j <0|1|2|3> | --cidinput <0|1|2|3>
246 Determines the Caller ID input source:
247 0: Caller ID from a modem and optional gateways
249 1: Caller ID from a serial or USB device and optional gateways
250 2: Caller ID from a gateway with modem support
251 3: Caller ID from gateways without modem support
252 Default: cidinput = 0
254 -L <file> | --logfile <file>
256 Server logfile.
257 Default: /var/log/ncidd.log
259 -l <file> | --lockfile <file>
261 Modem lockfile.
262 Default: /var/lock/LCK..modem
264 -M <MaxBytes> | --cidlogmax <MaxBytes>
266 Set the maximum CID call logfile size in bytes.
267 Maximum size is 100000000.
269 Default: cidlogmax = 1000000
271 -m <0|1|2|3> | --hupmode <0|1|2|3>
273 A Hangup Extension uses the same modes as the Internal Hangup
274 setting, --hangup. It enables an external script or program to
275 determine if ncidd should hangup or not. It can be used with and
276 without the Internal Hangup. If used with Internal Hangup,
277 --hupmode is only executed if the Internal Hangup is not going
278 to terminate the call.
279 If --hupmode is set to 1, ncidd will immediately hangup the
281 call. If --hupmode is set to 2, ncidd will generate FAX tones
282 and then hangup the call. (If FAX mode does not produce FAX
283 tones try setting pickup = 0 in ncidd.conf.) If --hupmode is set
284 to 3, ncidd will play an announcement file and then hangup the
285 call.
286 Default: hupmode = 0
288 -N <0|1> | --noserial <0|1> (Obsolete, replaced by -j|--cidinput)
290 Serial device is being used (0) or no serial device (1).
291 Default: noserial = 0
293 -n <0|1> | --nomodem <0|1> (Obsolete, replaced by -j|--cidinput)
295 Modem is being used (0) or no modem (1).
296 Default: nomodem = 0
298 -P <pidfile> | --pidfile <pidfile>
300 Server PID file. Set to /var/run/ncidd.pid in an rc or init
301 script when ncidd is used as a service. The program will still
302 run if it does not have permission to write a pidfile. There is
303 no default. If pidfile is not set, no pid file will be used.
304 -p <port> | --port <port>
306 Server port.
307 Default: 3333
309 -Q <dotted-ip> | --ifaddr <dotted-ip>
311 Restrict connections to the interface associated with this IP
312 address.
313 Default: Port accepts client or gateway connections from any‐
315 where.
316 -r <0|1|2> | --regex <0|1|2>
318 Use 0 for Simple Expressions (default)
320 Use 1 for Posix Extended Regular Expressions
321 Use 2 for Perl-compatible Regular Expressions
322 NCID Simple Expression Syntax
324 ^ = partial match from beginning
326 * = partial match after the '*'
327 ^1? = optional leading 1 for US numbers only
328 Posix Regular Expression Description and Syntax:
330 https://en.wikipedia.org/wiki/Regular_expression
331 Perl-compatible regular expression syntax Cheatsheet
333 https://www.debuggex.com/cheatsheet/regex/pcre
334 Introduction to Regular Expressions:
336 http://www.regular-expressions.info/quickstart.html
337 Default: regex = 0
339 -S <ttyspeed> | --ttyspeed <ttyspeed>
341 Set the tty port speed to one of: 115200, 38400, 19200, 9600,
342 4800, 2400, 1200
343 Default: ttyspeed = 115200
345 -s <datatype> | --send <datatype>
347 Send optional CID data to a client. Where datatype is: cidlog:
348 sent when the client connects. If the CID call log gets too
349 big, it will not be sent.
350 cidinfo: sent on each ring, to all clients, gives the current
352 ring count.
353 Default: Optional CID DATA is not sent
355 -T <0|1> | --ttyclocal <0|1>
357 Enable (0) or disable (1) modem control signals.
358 Default: modem control signals enabled
360 -t <ttyport> | --ttyport <ttyport>
362 Modem device file, or serial port that provides Caller ID infor‐
363 mation.
364 Default: /dev/modem
366 -V | --version
368 Display the version number.
369 -v <1-9> | --verbose <1-9>
371 Verbose mode. Sends information to the server logfile and dis‐
372 plays information for the -D option. Set a higher number for
373 more information.
374 Do not use level 9 unless there is a problem in poll(). It
376 grows the logfile very fast.
377 To debug, try: verbose = 3
379 Default: verbose = 1
381 -W <file> | --whitelist <file>
383 Whitelist file used for Internal Hangups.
384 Default: /etc/ncid/ncidd.whitelist
386 --osx-launchd
388 This option is only for OSX when using launchd to control ncidd.
389 It prevents ncidd from entering daemon mode. It is like debug
390 mode, but nothing is printed to the screen.
391
393 The ncidd.conf(5) file is used to set options. The syntax of the
394 ncidd.conf(5) file is discussed separately and should be consulted for
395 detailed reference information.
396 The ncidd.alias(5) file is used to create aliases. The syntax of the
398 ncidd.alias(5) file is discussed separately and should be consulted for
399 detailed reference information.
400
402 These are six examples of the four types of lines sent to NCID clients.
403 The first field identifies the type of info which follows.
404 The CID: line gives the CID information of the current call.
406 The CIDLOG: line gives the CID information of a line in the CID log‐
408 file.
409 The CID: and CIDLOG: lines are identical, with data stored as name and
411 value pairs. Clients should always locate the line identifier and then
412 scan for a field name and get its value. It's possible that additional
413 name/value pairs may be added in the future.
414 CID: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
416 CIDLOG: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
417 The CIDINFO: line gives a line number and ring count from the server.
419 The ring count starts at 1 and increases until ringing ends, at which
420 time a count of 0 is sent. The line number default is 1. If Distinc‐
421 tive Ring service is being provided by the telco, ncidd will add one of
422 the letters A, B, C, or D to indicate the virtual line called.
423 CIDINFO: *LINE*line indicator*RING*ringcount*TIME*hh:mm:ss*
425 The MSG: line gives messages from the server.
427 The MSGLOG: line gives a message logged in the CID logfile.
429 The MSG: and MSGLOG: lines are identicalformat:
431 MSG: Too many clients connected: 15
433 MSGLOG: Too many clients connected: 15
434 The CIDOUT: line gives outgoing call information.
436 CIDOUT: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*NO‐
438 NAME*
439
441 Blacklist file: /etc/ncid/ncidd.blacklist
442 Whitelist file: /etc/ncid/ncidd.whitelist
444 Configuration file: /etc/ncid/ncidd.conf
446 PID file: /var/run/ncidd.pid
448 Call and Message Log: /var/log/cidcall.log
450 Modem, Device, or Gateway Output: /var/log/ciddata.log
452 Server logfile: /var/log/ncidd.log (Contents con‐
454 trolled by --verbose.)
455
457 Return Code Meaning
458 ----------- -------
459 0 Successful
460 -100 Usage
461 -101 Invalid port number
462 -102 TTY lockfile exists
463 -103 Unable to set modem for Caller ID
464 -104 Configuration file error
465 -105 No modem found
466 -106 Invalid data type.
467 -107 Invalid number
468 -108 Invalid tty port speed [set in config file]
469 -109 Alias file error
470 -110 PID file already exists
471 -111 Cannot init TTY
472 -112 Serial device error
473 -113 string too long
474 -114 Blacklist or whitelist file error
475 -? System error
476
478 ncidd.conf.5, ncidd.alias.5, ncidd.blacklist.5, ncidd.whitelist.5,
479 ncidrotate.1, ncid_extensions.7, ncid_gateways.7, ncid_tools.7, ncid.1,
480 lcdncid.1
481NCID 2023-3-15 NCIDD(8)