1NCIDD(8) System Manager's Manual 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 [-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
47 The ncidd server collects Caller ID data from:
48 - a modem or CID device on a telephone line
50 - a CID gateway on the network
51 - or both
52 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 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 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 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 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 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 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 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 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 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 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 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 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 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 The NCID gateway sends ncidd CID and CIDINFO text lines instead of the
129 normal gateway CALL and CALLINFO lines which need conversion.
130 When ncidd receives a SIGHUP signal, it reloads the alias, blacklist
132 and whitelist files.
133 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
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 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 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 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 NCID Simple Expression Syntax
267 ^ = partial match from beginning
268 * = partial match after the '*'
269 ^1? = optional leading 1 for US numbers only
270 Posix Regular Expression Description and Syntax:
272 https://en.wikipedia.org/wiki/Regular_expression
273 Perl-compatible regular expression syntax Cheatsheet
275 https://www.debuggex.com/cheatsheet/regex/pcre
276 Introduction to Regular Expressions:
278 http://www.regular-expressions.info/quickstart.html
279 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
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 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
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 The CID: line gives the CID information of the current call.
330 The CIDLOG: line gives the CID information of a line in the CID log‐
332 file.
333 The MSG: line gives messages from the server.
335 The MSGLOG: line gives a message logged in the CID logfile.
337 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 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 The MSG: and MSGLOG: lines are identical,
350 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
359 /etc/ncid/ncidd.blacklist
360 Blacklist file
361 /etc/ncid/ncidd.whitelist
363 Whitelist file
364 /etc/ncid/ncidd.conf
366 Configuration file
367 /var/run/ncidd.pid
369 PID file
370 /var/log/cidcall.log
372 Contains CID and MSG lines
373 /var/log/ciddata.log
375 Contains the output from the modem, device or gateway.
376 /var/log/ncidd.log
378 Server logfile. Contents controlled by --verbose.
379
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
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 NCIDD(8)