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
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 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 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 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 NCID Simple Expression Syntax
274 ^ = partial match from beginning
275 * = partial match after the '*'
276 ^1? = optional leading 1 for US numbers only
277 Posix Regular Expression Description and Syntax:
279 https://en.wikipedia.org/wiki/Regular_expression
280 Perl-compatible regular expression syntax Cheatsheet
282 https://www.debuggex.com/cheatsheet/regex/pcre
283 Introduction to Regular Expressions:
285 http://www.regular-expressions.info/quickstart.html
286 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
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 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
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 The CID: line gives the CID information of the current call.
337 The CIDLOG: line gives the CID information of a line in the CID log‐
339 file.
340 The MSG: line gives messages from the server.
342 The MSGLOG: line gives a message logged in the CID logfile.
344 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 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 The MSG: and MSGLOG: lines are identical,
357 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
366 /etc/ncid/ncidd.blacklist
367 Blacklist file
368 /etc/ncid/ncidd.whitelist
370 Whitelist file
371 /etc/ncid/ncidd.conf
373 Configuration file
374 /var/run/ncidd.pid
376 PID file
377 /var/log/cidcall.log
379 Contains CID and MSG lines
380 /var/log/ciddata.log
382 Contains the output from the modem, device or gateway.
383 /var/log/ncidd.log
385 Server logfile. Contents controlled by --verbose.
386
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
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
412NCID 2021-12-8 NCIDD(8)