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 - a modem or CID device on a telephone line
51 - a CID gateway on the network
52 - or both
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
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 into the server logfile.
160 -d <file> | --datalog <file>
161 Data logfile, used to capture the raw data sent to/received from
162 ncidd. This is usually the data to/from a modem, CID device or
163 gateway. The logfile must exist, ncidd will not create it.
164 Default: /var/log/ciddata.log
165 -e <identifier> | --lineid <identifier>
166 The telephone line identifier is used for a modem or serial de‐
167 vice. It is normally 1 to 16 characters. The default indicator
168 is POTS If you have multiple telephone lines, you probably want
169 to change the identifier from POTS to the 4 digit extension of
170 your exchange office. For example, if the telephone number is
171 321-555-1212 the identifier would be 1212.
172 When the gateway provides Caller ID and a hangup is required by
174 the modem connected to the same phone line, the line indicator
175 must be changed to the gateway line indicator.
176 For example, if the xdmf2ncid gateway line indicator (corre‐
178 sponds to the device name) is "CometUSB0" or "HoltekUSB0", the
179 line indicator must be changed to CometUSB0 or HoltekUSB0.
180 Default: -
181 -f <command> | --audiofmt <command>
182 Used for the Internal Hangup Announce option, --hangup 3 and for
183 a Hangup Extension Announce option, --hupmode 3. The audio for‐
184 mat command is very dependent on the modem. It must match the
185 number of one of the lines returned by AT+VSM=?. The default
186 modem manufacturer is CONEXANT, but the voice file also works
187 for U.S. Robotics provided the modem firmware version is at
188 least V1.2.23.
189 Default: AT+VSM=130
190 -g <0|1> | --gencid <0|1>
191 Generate a generic Caller ID at ring 2 if one is not received
192 from the modem, either because the telco is not sending it or
193 because the modem does not support it. The generic Caller ID
194 generated uses "RING" for the number and "No Caller ID" for the
195 name.
196 Default: gencid = 1
197 -H <0|1|2|3> | --hangup <0|1|2|3>
198 Controls Internal Hangup that will automatically hangup on a
199 call if the caller name or number is in the ncidd.blacklist file
200 but not the ncidd.whitelist file. If --hangup is set to 1, ncidd
201 will immediately hangup the call. If --hangup is set to 2,
202 ncidd will generate FAX tones and then hangup the call. (If FAX
203 mode does not produce FAX tones try setting pickup = 0 in
204 ncidd.conf.) If --hangup is set to 3, ncidd will play an an‐
205 nouncement file and then hangup the call.
206 Default: hangup = 0
207 -h | --help
208 Display a help message.
209 -I <string> | --initstr <string>
210 Modem initialization string.
211 Default: ATE1V1Q0
212 -i <string> | --initcid <string>
213 CID initialization string.
214 Default: AT+VCID=1
215 if it fails: AT#CID=1
216 -j <0|1|2|3> | --cidinput <0|1|2|3>
217 Determines the Caller ID input source:
218 0: Caller ID from a modem and optional gateways
219 1: Caller ID from a serial or USB device and optional gateways
220 2: Caller ID from a gateway with modem support
221 3: Caller ID from gateways without modem support
222 Default: cidinput = 0
223 -L <file> | --logfile <file>
224 Server logfile.
225 Default: /var/log/ncidd.log
226 -l <file> | --lockfile <file>
227 Modem lockfile.
228 Default: /var/lock/LCK..modem
229 -M <MaxBytes> | --cidlogmax <MaxBytes>
230 Set the maximum CID call logfile size in bytes.
231 Maximum size is 100000000.
232 Default: cidlogmax = 110000
233 -m <0|1|2|3> | --hupmode <0|1|2|3>
234 A Hangup Extension uses the same modes as the Internal Hangup
235 setting, --hangup. It enables an external script or program to
236 determine if ncidd should hangup or not. It can be used with and
237 without the Internal Hangup. If used with Internal Hangup,
238 --hupmode is only executed if the Internal Hangup is not going
239 to terminate the call.
240 If --hupmode is set to 1, ncidd will immediately hangup the
242 call. If --hupmode is set to 2, ncidd will generate FAX tones
243 and then hangup the call. (If FAX mode does not produce FAX
244 tones try setting pickup = 0 in ncidd.conf.) If --hupmode is set
245 to 3, ncidd will play an announcement file and then hangup the
246 call.
247 Default: hupmode = 0
248 -N <0|1> | --noserial <0|1> (Obsolete, replaced by -j|--cidinput)
249 Serial device is being used (0) or no serial device (1).
250 Default: noserial = 0
251 -n <0|1> | --nomodem <0|1> (Obsolete, replaced by -j|--cidinput)
252 Modem is being used (0) or no modem (1).
253 Default: nomodem = 0
254 -P <pidfile> | --pidfile <pidfile>
255 Server PID file. Set to /var/run/ncidd.pid in an rc or init
256 script when ncidd is used as a service. The program will still
257 run if it does not have permission to write a pidfile. There is
258 no default. If pidfile is not set, no pid file will be used.
259 -p <port> | --port <port>
260 Server port.
261 Default: 3333
262 -Q <dotted-ip> | --ifaddr <dotted-ip>
263 Restrict connections to the interface associated with this IP
264 address.
265 Default: Port accepts client or gateway connections from any‐
266 where.
267 -r <0|1|2> | --regex <0|1|2>
268 Use 0 for Simple Expressions (default)
269 Use 1 for Posix Extended Regular Expressions
270 Use 2 for Perl-compatible Regular Expressions
271 NCID Simple Expression Syntax
273 ^ = partial match from beginning
274 * = partial match after the '*'
275 ^1? = optional leading 1 for US numbers only
276 Posix Regular Expression Description and Syntax:
278 https://en.wikipedia.org/wiki/Regular_expression
279 Perl-compatible regular expression syntax Cheatsheet
281 https://www.debuggex.com/cheatsheet/regex/pcre
282 Introduction to Regular Expressions:
284 http://www.regular-expressions.info/quickstart.html
285 Default: regex = 0
287 -S <ttyspeed> | --ttyspeed <ttyspeed>
288 Set the tty port speed to one of: 115200, 38400, 19200, 9600,
289 4800, 2400, 1200
290 Default: ttyspeed = 115200
291 -s <datatype> | --send <datatype>
292 Send optional CID data to a client. Where datatype is:
293 cidlog: sent when the client connects. If the CID call log gets
294 too big, it will not be sent.
295 cidinfo: sent on each ring, to all clients, gives the current
296 ring count.
297 Default: Optional CID DATA is not sent
298 -T <0|1> | --ttyclocal <0|1>
299 Enable (0) or disable (1) modem control signals.
300 Default: modem control signals enabled
301 -t <ttyport> | --ttyport <ttyport>
302 Modem device file, or serial port that provides Caller ID infor‐
303 mation.
304 Default: /dev/modem
305 -V | --version
306 Display the version number.
307 -v <1-9> | --verbose <1-9>
308 Verbose mode. Send information into the server logfile and dis‐
309 play information for the -D option. Set a higher number for
310 more information. Do not use level 9 unless there is a problem
311 in poll(). It grows the logfile very fast.
312 To debug, try: verbose = 3
313 Default: verbose = 1
314 -W <file> | --whitelist <file>
315 Whitelist file used for Internal Hangups.
316 Default: /etc/ncid/ncidd.whitelist
317 --osx-launchd
318 This option is only for OSX when using launchd to control ncidd.
319 It prevents ncidd from entering daemon mode. It is like debug
320 mode, but nothing is printed to the screen.
321
323 The ncidd.conf(5) file is used to set options. The syntax of the
324 ncidd.conf(5) file is discussed separately and should be consulted for
325 detailed reference information.
326 The ncidd.alias(5) file is used to create aliases. The syntax of the
328 ncidd.alias(5) file is discussed separately and should be consulted for
329 detailed reference information.
330
332 These are six examples of the four types of lines sent to NCID clients.
333 The first field identifies the type of info which follows.
334 The CID: line gives the CID information of the current call.
336 The CIDLOG: line gives the CID information of a line in the CID log‐
338 file.
339 The MSG: line gives messages from the server.
341 The MSGLOG: line gives a message logged in the CID logfile.
343 The CIDINFO: line gives a line number and ring count from the server.
345 The ring count starts at 1 and increases until ringing ends, at which
346 time a count of 0 is sent. The line number default is 1. If Distinc‐
347 tive Ring service is being provided by the telco, ncidd will add one of
348 the letters A, B, C, or D to indicate the virtual line called.
349 The CID: and CIDLOG: lines are identical, with data stored as name and
351 value pairs. Clients should always locate the line identifier and then
352 scan for a field name and get its value. It's possible that additional
353 name/value pairs may be added in the future.
354 The MSG: and MSGLOG: lines are identical,
356 CID: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
358 CIDLOG: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*name*
359 CIDINFO: *LINE*line indicator*RING*ringcount*TIME*hh:mm:ss*
360 MSG: Too many clients connected: 15
361 MSGLOG: Too many clients connected: 15
362 CIDOUT: *DATE*mmddyyyy*TIME*hhmm*NMBR*number*MESG*NONE*NAME*NONAME*
363
365 /etc/ncid/ncidd.blacklist
366 Blacklist file
367 /etc/ncid/ncidd.whitelist
369 Whitelist file
370 /etc/ncid/ncidd.conf
372 Configuration file
373 /var/run/ncidd.pid
375 PID file
376 /var/log/cidcall.log
378 Contains CID and MSG lines
379 /var/log/ciddata.log
381 Contains the output from the modem, device or gateway.
382 /var/log/ncidd.log
384 Server logfile. Contents controlled by --verbose.
385
387 Return Code Meaning
388 ----------- -------
389 0 Successful
390 -100 Usage
391 -101 Invalid port number
392 -102 TTY lockfile exists
393 -103 Unable to set modem for Caller ID
394 -104 Configuration file error
395 -105 No modem found
396 -106 Invalid data type.
397 -107 Invalid number
398 -108 Invalid tty port speed [set in config file]
399 -109 Alias file error
400 -110 PID file already exists
401 -111 Cannot init TTY
402 -112 Serial device error
403 -113 string too long
404 -114 Blacklist or whitelist file error
405 -? System error
406
408 ncidd.conf.5, ncidd.alias.5, ncidd.blacklist.5, ncidd.whitelist.5,
409 ncidrotate.1, ncid_extensions.7, ncid_gateways.7, ncid_tools.7, ncid.1,
410 lcdncid.1
411NCID 2021-06-16 NCIDD(8)