1CAPIPLUGIN(8)               System Manager's Manual              CAPIPLUGIN(8)
2
3
4

NAME

6       capiplugin - Plugin for pppd (Point-to-Point Protocol daemon)
7
8

SYNOPSIS

10       pppd [options] plugin capiplugin.so [options for capiplugin]
11       before pppd 2.4.1:
12       pppd    [options]   plugin   /usr/lib/pppd/<pppd-version>/capiplugin.so
13       [options for capiplugin]
14
15

DESCRIPTION

17       The capiplugin provides a method to use PPP over ISDN  with  ISDN  con‐
18       trollers  that  provide a CAPI2.0 interface.  The plugin is responsible
19       for the call setup with CAPI2.0.  You can dial out, wait  for  incoming
20       calls  and set up communication over leased lines. It implements a fea‐
21       ture to reject an incoming call and callback. This feature can also  be
22       used  when  dialing  out.  In this case, the party called has to reject
23       the call and call back soon.  When using dial-on-demand it is  possible
24       let  both parties setup the connection, that means while the pppd is in
25       dial-on-demand mode not only an outgoing packet but  also  an  incoming
26       call  can  trigger  the  connection  setup. This can also combined with
27       callback to assign the cost to one side only (COSO).
28
29

PPPD VERSIONS

31       The plugin interface of the pppd is binary incompatible between differ‐
32       ent  version  of the pppd. So you need a different capiplugin for every
33       version of the pppd. The different plugins will  be  in  the  directory
34       /usr/lib/ppp/<pppd-version>.  Since 2.4.1 pppd checks if the version of
35       the plugin matches and also search the plugins  in  these  directories.
36       With  pppd versions before 2.4.1 you need to specify the absolute path‐
37       name of the plugin.
38
39

HOW IT WORKS

41       The capiplugin registers a new_phase_notifier and its  own  options  to
42       the  pppd  when  loaded.  When the pppd goes into phase SERIALCONN, the
43       capiplugin set up a connection and sets  the  global  variable  devnam.
44       The capiplugin will register a timer function that is called every sec‐
45       ond to handle the CAPI messages while pppd is running.  To notify  pppd
46       when  CAPI  messages  arrive,  the CAPI file descriptor is added to the
47       list of file descriptors which the pppd monitors for input.   Once  the
48       connection is set up the pppd will start PPP negotiation on device dev‐
49       nam. When the pppd enters  the  DEAD  phase,  the  connection  will  be
50       dropped  (if  it is still active) When operating in dial-on-demand mode
51       with wakeup on incoming calls, in phase DORMANT the plugin  will  setup
52       CAPI2.0 to accept incoming calls.  To wakeup pppd when an incoming call
53       arrives, the plugin will generate an UDP packet to the discard port (9)
54       of  the  gateway,  so  don't filter this packet or wakeup by incoming a
55       call will not work.
56
57

MODES OF OPERATION

59       normal dial out
60              Simply make a connection, for example to your Internet provider.
61              Required options: number.
62              Recommended options: msn.
63              Other possible options: controller, dialmax, dialtimeout, proto‐
64              col and redialdelay.
65
66
67       dial out with callback
68              Call  a given number, the called party rejects the call and then
69              calls back.
70              Required options: number and coso remote.
71              Recommended options: cli and msn or inmsn.
72              Other possible options: cbwait, controller, connectdelay,  dial‐
73              timeout, protocol
74
75
76       dial out on demand
77              Initiate  the  connection only on demand, i.e. when data traffic
78              is present and drop the connection after a fix  amount  of  idle
79              time.
80              Required options: number.
81              Required pppd options: demand, connect, idle.
82              Recommended options: msn.
83              Other possible options: controller, dialmax, dialtimeout, proto‐
84              col and redialdelay.
85
86
87       dial out on demand on an incoming phone call
88              Initiate the connection only on demand, i.e. when  data  traffic
89              is  present  or  an incoming phone call is detected and drop the
90              connection after a fix amount of idle time. This  is  useful  if
91              you are not at home and you want your computer to make a connec‐
92              tion to the internet.
93              Required options: number and cli.
94              Required options: number, voicecallwakeup and inmsn and/or cli.
95              Required pppd options: demand, connect, idle.
96              Recommended options: msn.  Other possible  options:  controller,
97              dialmax, dialtimeout, protocol, redialdelay and inmsn.
98
99
100       wait for dial in
101              Wait for calls and accept incoming calls.
102              Recommended options: cli and msn or inmsn.
103              Possible  options: connectdelay, controller, dialtimeout, proto‐
104              col
105
106
107       wait for dial in and call back.
108              Wait for calls, reject the call and then call back.
109              Required options: cbnumber.
110              Recommended options: cli and msn or inmsn.
111              Other possible options: cbdelay, connectdelay, controller, dial‐
112              timeout, protocol
113
114
115       dial on demand and also wait for dial in
116              Initiate  the  connection only on demand, i.e. when data traffic
117              is present or when the other side dial in and drop  the  connec‐
118              tion after a fix amount of idle time.
119              Required options: number and inmsn and/or cli.
120              Recommended options: cli and msn or inmsn.
121              Optional options: coso caller.
122              Other possible options: cbdelay, connectdelay, controller, dial‐
123              timeout, protocol
124
125
126       dial on demand and also wait for dial in with COSO.
127              Initiate the connection only on demand, i.e. when  data  traffic
128              is  present  or when the other side dial in and drop the connec‐
129              tion after a fix amount of idle time. If option  coso  local  is
130              set, pppd will reject an incoming call from the remote party and
131              will callback.  With the option  coso  remote  set,  the  remote
132              party should reject the incoming call and call back.
133              Required  options:  number, inmsn and/or cli, coso local or coso
134              remote.
135              Recommended options: cli and msn or inmsn.
136              Other possible options: cbdelay, connectdelay, controller, dial‐
137              timeout, protocol
138
139
140       leased line
141              set  up  a  leased line connection, with or without CAPI channel
142              bundling.
143              Required options: channels.  Other possible options:
144              connectdelay, controller, dialtimeout and protocol
145
146
147

OPTIONS

149       avmadsl
150              make an DSL connection with the Fritz!Card DSL controller.   The
151              parameters  for  the  DSL  connection  will  be loaded from file
152              /etc/drdsl/adsl.conf. This file can be edited or will be created
153              by the program drdsl.
154
155
156       cbdelay <seconds>
157              Number  of seconds to wait before callback, when acting as dial-
158              in server with callback. Default value is 2 seconds.
159
160
161       cbnumber <phone numbers>
162              List of phone numbers for callback, separated  by  commas,  when
163              acting as dial-in server with callback.
164
165
166       cbwait <seconds>
167              Time  to wait for callback before giving up. Default value is 60
168              seconds.
169
170
171       channels <channel specification>
172              List of b-channels or ranges to activate leased line mode, sepa‐
173              rated by commas.
174
175
176       cli <phone numbers>
177              List of numbers from which incoming calls will be accepted, sep‐
178              arated by commas.
179
180
181       clicb  The option is retained  for  compatibility  reasons  only.   Use
182              option coso local or coso remote instead.
183              Enable  callback  mode.   When option number is set, call number
184              and wait for callback.  When option number is not set, wait  for
185              incoming  call,  reject  the call and call back.  This option is
186              optional if the cbnumber option is set.
187
188
189       connectdelay <seconds>
190              Number of seconds to wait after a connection is set  up,  before
191              PPP negotiation starts. Default value is 0 seconds.  This option
192              is useful when connecting with protocol  modem.   Some  Internet
193              access  servers  will  hang  up if they receive data immediately
194              after the connection is established.
195
196
197       controller <controller specification>
198              For point-to-multipoint <controller specification> is  only  the
199              CAPI  2.0  controller number, default is 1.  For point-to-point,
200              specify <controller number>,<ddi>,<length of internal numbers>
201
202
203       controller[1-3] <controller specification>
204              Like option controller.  Used to  specify  more  than  one  con‐
205              troller
206
207
208       coso caller
209              No callback is done, the costs are assigned to the caller.
210
211
212       coso local
213              The  costs are assigned to the local party.  On an incoming call
214              pppd will reject the call and callback.
215
216
217       coso remote
218              The costs are assigned to the remote party.  On an outgoing call
219              the remote party will reject the call and callback.
220
221
222       dialmax <times>
223              Maximum  number  of  times  the  list  of phone numbers is tried
224              before giving up.  Default value is 4.
225              If dialmax is set to 0, the list is retried infinitely  until  a
226              connection is made (or the process is stopped).
227
228
229       dialtimeout <seconds>
230              Time to wait for the connection to be established or fail before
231              giving up.  Default value is 60 seconds.
232
233
234       inmsn <msn>
235              List of phone numbers to monitor for calls, separated by commas.
236              If this option is not set, the value of option msn is used.
237
238
239       inmsn[1-3] <msn>
240              List  of phone numbers to monitor for calls on controller speci‐
241              fied by option controller[1-3], separated by  commas.   If  this
242              option is not set, the value of option msn[1-3] is used.
243
244
245       msn <msn>
246              Phone number used to make outgoing calls. Also used for incoming
247              calls if option inmsn is not set.
248
249
250       msn[1-3] <msn>
251              Phone number used to make outgoing calls on controller specified
252              by  option  controller[1-3].  Also  used  for  incoming calls if
253              option inmsn[1-3] is not set.
254
255
256       number <phone numbers>
257              List of phone numbers to call, separated by commas.  Every  num‐
258              ber in the list is called until a connection can be established.
259              When the end of the list is reached, the first number is  called
260              again.  See option dialmax.
261
262
263       numberprefix <prefix>
264              phone  number  to  dial  to access an outside line. For example,
265              numberprefix 0.
266
267
268       numberprefix[1-3] <prefix>
269              phone number to dial to access an outside  line  for  controller
270              specified  by option controller[1-3]. For example, numberprefix1
271              0.
272
273
274       protocol hdlc | x75 | v42bis  |  modem  |  analogmodem  |  v110async  |
275       v120async
276              ISDN  protocol  to use. With hdlc and adskpppoe, the sync option
277              must be added to the pppd.  With x75, v42bis,  modem,  v110async
278              and v120async the sync option MUST NOT be enabled. Default value
279              is  hdlc.   Not  all  controllers  support  v42bis,  modem   and
280              v120async.   Use  capiinfo(8)  to  view which features your con‐
281              troller supports.
282
283
284       redialdelay <seconds>
285              Number of seconds to wait between redialing. Default value is  5
286              seconds.
287
288
289       voicewakeup
290              With  this  option  a incoming voicecall can trigger an outgoing
291              connection setup.
292
293

EXAMPLE FOR NORMAL DIAL OUT

295       Probably the most common use of pppd is to dial out to  an  ISP.   This
296       can be specified with a command like
297
298              pppd call isp
299
300       where the /etc/ppp/peers/isp file is set up by the system administrator
301       to resemble the following:
302
303              sync
304              noauth
305              defaultroute
306              name USERNAME
307              plugin capiplugin.so ®msn MSN
308              number PHONENUMBER
309              protocol hdlc
310              ipcp-accept-local
311              ipcp-accept-remote
312              /dev/null
313
314       and where the files /etc/ppp/pap-secrets and /etc/ppp/chap-secrets  are
315       set up by the system administrator to resemble the following:
316
317              USERNAME * PASSWORD *
318
319
320

EXAMPLE OF DIAL OUT WITH CALLBACK

322       Dial out with callback can be specified with a command like
323
324              pppd call isp-callback
325
326       where  the  /etc/ppp/peers/isp-callback  file  is  set up by the system
327       administrator to resemble the following:
328
329              sync
330              noauth
331              defaultroute
332              name USERNAME
333              plugin capiplugin.so
334              msn MSN
335              number PHONENUMBER
336              coso remote
337              cli PHONENUMBER
338              protocol hdlc
339              ipcp-accept-local
340              ipcp-accept-remote
341              /dev/null
342
343       and where the files /etc/ppp/pap-secrets and /etc/ppp/chap-secrets  are
344       set up by the system administrator to resemble the following:
345       USERNAME * PASSWORD *
346
347

EXAMPLE DIAL OUT ON DEMAND

349       To  dial out on demand and drop the link after 120 seconds idle time on
350       the link add this line to the /etc/inittab file:
351
352              isp:23:respawn:/usr/sbin/pppd call isp demand  connect  ""  idle
353              120
354
355       where the /etc/ppp/peers/isp file is set up by the system administrator
356       to resemble the following:
357
358              sync
359              noauth
360              defaultroute
361              name USERNAME
362              plugin capiplugin.so ®msn MSN
363              number PHONENUMBER
364              protocol hdlc
365              ipcp-accept-local
366              ipcp-accept-remote
367              /dev/null
368
369       and where the files /etc/ppp/pap-secrets and /etc/ppp/chap-secrets  are
370       set up by the system administrator to resemble the following:
371
372              USERNAME * PASSWORD *
373
374

EXAMPLE DIAL OUT ON DEMAND AND ON AN INCOMING PHONE CALL

376       To  dial  out  on demand or on an incoming phone call and drop the link
377       after 120 seconds idle time on the link add this line to the /etc/init‐
378       tab file:
379
380              isp:23:respawn:/usr/sbin/pppd  call  isp  demand connect "" idle
381              120
382
383       where the /etc/ppp/peers/isp file is set up by the system administrator
384       to resemble the following:
385
386              sync
387              noauth
388              defaultroute
389              name USERNAME
390              plugin capiplugin.so
391              msn MSN
392              number PHONENUMBER
393              cli VOICEPHONENUMBER
394              voicecallwakeup
395              protocol hdlc
396              ipcp-accept-local
397              ipcp-accept-remote
398              /dev/null
399
400       and  where the files /etc/ppp/pap-secrets and /etc/ppp/chap-secrets are
401       set up by the system administrator to resemble the following:
402
403              USERNAME * PASSWORD *
404
405

EXAMPLE DIAL OUT ON DEMAND AND ALSO ACCEPT AN INCOMING DATA CALL

407       To dial out on demand or on an incoming data call  and  drop  the  link
408       after 120 seconds idle time on the link add this line to the /etc/init‐
409       tab file:
410
411              isp:23:respawn:/usr/sbin/pppd call isp demand  connect  ""  idle
412              120
413
414       where the /etc/ppp/peers/isp file is set up by the system administrator
415       to resemble the following:
416
417              sync
418              noauth
419              defaultroute
420              name USERNAME
421              plugin capiplugin.so
422              msn MSN
423              number PHONENUMBER
424              inmsn MSN
425              protocol hdlc
426              ipcp-accept-local
427              ipcp-accept-remote
428              /dev/null
429
430       and where the files /etc/ppp/pap-secrets and /etc/ppp/chap-secrets  are
431       set up by the system administrator to resemble the following:
432
433              USERNAME * PASSWORD *
434
435

EXAMPLE OF WAIT FOR DIAL IN WITHOUT CLI AUTHENTICATION

437       Wait  for  incoming calls, accept them according to options msn, inmsn,
438       and protocol.
439
440       Do not provide option cli to the capiplugin.  Start a pppd for every  b
441       channel.   Authorization  is  checked  using  PAP  or  CHAP  and the IP
442       addresses  are  assigned  according  to  the  /etc/ppp/pap-secrets   or
443       /etc/ppp/chap-secrets  file.   Assume  that  the  server has IP address
444       192.168.0.1, the clients are to be assigned IP addresses starting  from
445       192.168.0.2,  and  the  hostname  of the server is "dialinserver".  Add
446       these two lines to the /etc/inittab file:
447
448              p0:23:respawn:/usr/sbin/pppd call incoming-noncli
449              p1:23:respawn:/usr/sbin/pppd call incoming-noncli
450
451       where the /etc/ppp/peers/incoming-noncli file is set up to resemble the
452       following:
453
454              sync
455              auth
456              plugin capiplugin.so
457              inmsn MSN
458              protocol hdlc 192.168.0.1:
459
460       with the files /etc/ppp/pap-secrets and /etc/ppp/chap-secrets set up to
461       resemble the following:
462
463              user1 dialinserver PASSWORD1 192.168.0.2
464              user2 dialinserver PASSWORD2 192.168.0.3
465
466

EXAMPLE OF WAIT FOR DIAL IN WITH CLI AUTHENTICATION

468       Wait for incoming calls, accept them according to options  msn,  inmsn,
469       cli and protocol.
470
471       Start  a  pppd for every client.  Assume that the server has IP address
472       192.168.0.1 and the clients are to be assigned  IP  addresses  starting
473       from 192.168.0.2.  Add these three lines to the /etc/inittab file:
474
475              p0:23:respawn:/usr/sbin/pppd   call   incoming-cli   cli   04711
476              192.168.0.1:192.168.0.2
477              p1:23:respawn:/usr/sbin/pppd   call   incoming-cli   cli   04712
478              192.168.0.1:192.168.0.3
479              p2:23:respawn:/usr/sbin/pppd   call   incoming-cli   cli   04713
480              192.168.0.1:192.168.0.4
481
482
483       where the /etc/ppp/peers/incoming-cli file is set up  to  resemble  the
484       following:
485
486              sync
487              noauth
488              plugin capiplugin.so
489              inmsn MSN
490              protocol hdlc
491
492

EXAMPLE OF WAIT FOR DIAL IN WITH CLI AUTHENTICATION AND CALLBACK

494       Wait  for  incoming calls, accept them according to options msn, inmsn,
495       cli and protocol, reject incoming calls and call back.
496
497       Start a pppd for every client.  Assume that the server has  IP  address
498       192.168.0.1  and  the  clients are to be assigned IP addresses starting
499       from 192.168.0.2.  Add these three lines to the /etc/inittab file.
500
501              p0:23:respawn:/usr/sbin/pppd call incoming-cli cli 04711  cbnum‐
502              ber 4711 192.168.0.1:192.168.0.2
503              p1:23:respawn:/usr/sbin/pppd  call incoming-cli cli 04712 cbnum‐
504              ber 4712 192.168.0.1:192.168.0.3
505              p2:23:respawn:/usr/sbin/pppd call incoming-cli cli 04713  cbnum‐
506              ber 4713 192.168.0.1:192.168.0.4
507
508       where  the  /etc/ppp/peers/incoming-cli  file is set up to resemble the
509       following:
510
511              sync
512              noauth
513              plugin capiplugin.so
514              inmsn MSN
515              protocol hdlc
516
517

EXAMPLE OF A LEASED LINE CONNECTION WITH HDLC

519       Assume that the server has IP address 192.168.0.1 and the peer has  the
520       IP address 192.168.0.2.  Add this line to the /etc/inittab file:
521
522              p0:23:respawn:/usr/sbin/pppd call leased-hdlc controller 1 chan‐
523              nels 1 192.168.0.1:192.168.0.2
524
525       where the /etc/ppp/peers/leased-hdlc file is set  up  to  resemble  the
526       following:
527
528              sync
529              noauth
530              lcp-echo-interval 5
531              lcp-echo-failure 3
532              lcp-max-configure 50
533              lcp-max-terminate 2
534              noccp
535              noipx
536              persist
537              plugin capiplugin.so
538              protocol hdlc
539
540

EXAMPLE OF A LEASED LINE CONNECTION WITH V42BIS

542       Assume  that the server has IP address 192.168.0.1 and the peer has the
543       IP address 192.168.0.2.  Add this line to  the  /etc/inittab  file  for
544       server 1 (192.168.0.1):
545
546              p0:23:respawn:/usr/sbin/pppd  call  leased-v42bis  controller  1
547              channels 1 192.168.0.1:192.168.0.2
548
549       and this line to the /etc/inittab file for server 1 (192.168.0.2):
550
551              p0:23:respawn:/usr/sbin/pppd  call  leased-v42bis  controller  1
552              channels p1 192.168.0.2:192.168.0.1
553
554       where  the  /etc/ppp/peers/leased-v42bis file is set up to resemble the
555       following:
556
557              sync
558              noauth
559              lcp-echo-interval 5
560              lcp-echo-failure 3
561              lcp-max-configure 50
562              lcp-max-terminate 2
563              noccp
564              noipx
565              persist
566              plugin capiplugin.so
567              protocol v42bis
568
569

CAVEATS

571       Every pppd awaiting incoming calls can receive an incoming call  first.
572       So  when  two  pppds  are started to monitor the same MSN, one with CLI
573       Authentication and the other without, the following can happen:
574
575              The Client with the CLI specified to the first pppd  calls,  but
576              the  pppd  without  the  cli  option receives the call first and
577              accepts it.
578
579       To combine CLI Authentication and PAP/CHAP Authentication, use one  MSN
580       for  CLI authenticated calls and another for the PAP/CHAP authenticated
581       calls.
582
583

DIAGNOSTICS

585       Messages are sent to the syslog daemon just as in  normal  pppd  opera‐
586       tion; see the pppd manual page.
587
588

SEE ALSO

590       pppd(8), capiinfo(8), capiinit(8), capictrl(8)
591
592

AUTHORS

594       Carsten Paeth (calle@calle.in-berlin.de)
595       AVM GmbH Berlin (info@avm.de)
596
597
598
599                                                                 CAPIPLUGIN(8)
Impressum