1.\" Copyright (c) 2001-2003 Maksim Yevmenkin <m_evmenkin@yahoo.com>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $Id: rfcomm_pppd.8,v 1.7 2003/09/07 18:32:11 max Exp $
26.\" $FreeBSD$
27.\"
28.Dd February 4, 2003
29.Dt RFCOMM_PPPD 8
30.Os
31.Sh NAME
32.Nm rfcomm_pppd
33.Nd RFCOMM PPP daemon
34.Sh SYNOPSIS
35.Nm
36.Fl c
37.Op Fl dh
38.Fl a Ar address
39.Fl C Ar channel
40.Fl l Ar label
41.Fl u Ar N
42.Nm
43.Fl s
44.Op Fl dDhS
45.Op Fl a Ar address
46.Fl C Ar channel
47.Fl l Ar label
48.Sh DESCRIPTION
49The
50.Nm
51daemon is a simple wrapper daemon that allows the use of
52.Xr ppp 8
53via an RFCOMM connection.
54It can operate in two modes: client and server.
55.Pp
56In client mode,
57.Nm
58opens an RFCOMM connection to the specified server's
59.Ar BD_ADRR
60and
61.Ar channel .
62Once the RFCOMM connection is established,
63.Nm
64executes
65.Xr ppp 8
66in
67.Fl direct
68mode with the specified
69.Ar label .
70Likewise,
71.Xr ppp 8
72operates over the RFCOMM connection just like it would over a standard serial
73port, thus allowing a user to
74.Dq "dial out"
75and connect to the Internet.
76.Pp
77In server mode,
78.Nm
79opens an RFCOMM socket and listens for incoming connections from remote clients.
80Once the new incoming connection is accepted,
81.Nm
82forks and executes
83.Xr ppp 8
84in
85.Fl direct
86mode with the specified
87.Ar label .
88Likewise,
89.Xr ppp 8
90operates over the RFCOMM connection just like it would over a standard serial
91port, thus providing network connectivity to remote clients.
92.Pp
93The options are as follows:
94.Bl -tag -width indent
95.It Fl a Ar address
96In client mode, this required option specifies the address of the remote
97RFCOMM server.
98In server mode, this option can be used to specify the local
99address to listen on.
100By default, in server mode, the daemon will listen on
101.Dv ANY
102address.
103The address can be specified as BD_ADDR or name.
104If a name was specified, the
105.Nm
106utility will attempt to resolve the name via
107.Xr bt_gethostbyname 3 .
108.It Fl C Ar channel
109In both client and server mode, this required option specifies the RFCOMM
110channel to connect to or listen on.
111In server mode, the channel should be a number between 1 and 30.
112In client mode, the channel could either be a number between 1 and 30
113or a service name.
114Supported service names are:
115.Cm DUN
116(Dial-Up Networking) and
117.Cm LAN
118(LAN Access Using PPP).
119If a service name is used instead of a numeric channel number, then
120.Nm
121will try to obtain an RFCOMM channel number via SDP
122(Service Discovery Protocol).
123.It Fl c
124Act as an RFCOMM client.
125This is the default mode.
126.It Fl d
127Do not detach from the controlling terminal, i.e., run in foreground.
128.It Fl D
129In server mode, register the
130.Cm DUN
131(Dial-Up Networking) service in addition to the
132.Cm LAN
133(LAN Access Using PPP) service.
134AT-command exchange can be faked with
135.Xr ppp 8
136chat script.
137.It Fl h
138Display usage message and exit.
139.It Fl l Ar label
140In both client and server mode, this required option specifies which
141.Xr ppp 8
142label will be used.
143.It Fl S
144In server mode, register the
145.Cm SP
146(Serial Port) service in addition to the
147.Cm LAN
148(LAN Access Using PPP) service.
149.Pp
150It appears that some cell phones are using the so-called
151.Dq "callback mechanism" .
152In this scenario, the user is trying to connect his cell phone to the Internet,
153while the user's host computer is acting as the gateway server.
154It seems that it is not possible to tell the phone to just connect and start
155using the
156.Cm LAN
157service.
158Instead, the user's host computer must
159.Dq "jump start"
160the phone by connecting to the phone's
161.Cm SP
162service.
163What happens next is the phone kills the existing connection and opens another
164connection back to the user's host computer.
165The phone really wants to use the
166.Cm LAN
167service, but for whatever reason it looks for the
168.Cm SP
169service on the user's host computer.
170This brain-damaged behavior was reported for the Nokia 6600 and the
171Sony/Ericsson P900.
172.It Fl s
173Act as an RFCOMM server.
174.It Fl u Ar N
175This option maps directly to the
176.Fl unit
177.Xr ppp 8
178command-line option and tells
179.Nm
180to instruct
181.Xr ppp 8
182to only attempt to open
183.Pa /dev/tun Ns Ar N .
184This option only works in client mode.
185.El
186.Sh PPP CONFIGURATION
187.Ss Important Notes on PPP Configuration
188Special attention is required when adding new RFCOMM configurations to the
189existing PPP configuration.
190Please keep in mind that PPP will
191.Em always
192execute commands in the
193.Dq Li default
194label of your
195.Pa /etc/ppp/ppp.conf
196file.
197Please make sure that the
198.Dq Li default
199label
200.Em only
201contains commands that apply to
202.Em every
203other label.
204If you need to use PPP for both dialing out and accepting incoming
205RFCOMM connections, please make sure you have moved all commands related to
206dialing out from the
207.Dq Li default
208section into an appropriate outgoing label.
209.Ss RFCOMM Server
210One of the typical examples is the LAN access.
211In this example, an RFCOMM connection
212is used as a null-modem connection between a client and a server.
213Both client and server will start talking PPP right after the RFCOMM
214connection has been established.
215.Bd -literal -offset indent
216rfcomm-server:
217 set timeout 0
218 set lqrperiod 10
219 set ifaddr 10.0.0.1 10.0.0.2 255.255.255.0
220 enable lqr
221 accept lqr
222 accept dns
223 # Do not use PPP authentication. Assume that
224 # Bluetooth connection was authenticated already
225 disable pap
226 deny pap
227 disable chap
228 deny chap
229.Ed
230.Ss RFCOMM Client
231The
232.Nm
233utility supports both
234.Cm LAN
235(LAN Access Using PPP) and
236.Cm DUN
237(Dial-Up Networking) access.
238The client's configuration for
239.Cm LAN
240access is very similar to the server's and might look like this:
241.Bd -literal -offset indent
242rfcomm-client:
243 enable lqr
244 accept lqr
245 set dial
246 set timeout 0
247 disable iface-alias
248 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
249 # Do not use PPP authentication. Assume that
250 # Bluetooth connection was authenticated already
251 deny pap
252 disable pap
253 deny chap
254 disable chap
255.Ed
256.Pp
257The client's configuration for
258.Cm DUN
259access is different.
260In this scenario, the client gets connected to the virtual serial port on the
261server.
262To open a PPP session, the client must dial a number.
263Note that by default
264.Xr ppp 8
265will not execute any configured chat scripts.
266The
267.Ic force-scripts
268option can be used to override this behavior.
269An example configuration is shown below:
270.Bd -literal -offset indent
271rfcomm-dialup:
272 # This is IMPORTANT option
273 enable force-scripts
274
275 # You might want to change these
276 set authname
277 set authkey
278 set phone "*99***1#"
279
280 # You might want to adjust dial string as well
281 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 5 \\
282           \\"\\" AT OK-AT-OK ATE1Q0 OK \\\\dATDT\\\\T TIMEOUT 40 CONNECT"
283 set login
284 set timeout 30
285 enable dns
286 resolv rewrite
287
288 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
289 add default HISADDR
290.Ed
291.Pp
292Note that by adjusting the initialization string, one can make a CSD (Circuit
293Switched Data), HSCSD (High Speed Circuit Switched Data) or GPRS (General
294Packet Radio Service) connection.
295The availability of the particular connection
296type depends on the phone model and service plan activated on the phone.
297.Sh EXIT STATUS
298.Ex -std
299.Sh EXAMPLES
300.Dl "rfcomm_pppd -s -a 00:01:02:03:04:05 -C 1 -l rfcomm-server"
301.Pp
302This command will start
303.Nm
304in the server mode.
305The RFCOMM server will listen on local address
306.Li 00:01:02:03:04:05
307and channel
308.Li 1 .
309Once the incoming connection has been accepted,
310.Nm
311will execute
312.Xr ppp 8
313in
314.Fl direct
315mode with the
316.Dq Li rfcomm-server
317label.
318.Pp
319.Dl "rfcomm_pppd -c -a 00:01:02:03:04:05 -C 1 -l rfcomm-client"
320.Pp
321This command will start
322.Nm
323in the client mode.
324.Nm
325will try to connect to the RFCOMM server at
326.Li 00:01:02:03:04:05
327address and channel
328.Li 1 .
329Once connected,
330.Nm
331will execute
332.Xr ppp 8
333in
334.Fl direct
335mode with the
336.Dq Li rfcomm-client
337label.
338.Sh SEE ALSO
339.Xr rfcomm_sppd 1 ,
340.Xr bluetooth 3 ,
341.Xr ng_btsocket 4 ,
342.Xr ppp 8 ,
343.Xr sdpcontrol 8 ,
344.Xr sdpd 8
345.Sh AUTHORS
346.An Maksim Yevmenkin Aq Mt m_evmenkin@yahoo.com
347.Sh CAVEATS
348The
349.Nm
350utility in server mode will try to register the Bluetooth LAN Access Over PPP
351service with the local SDP daemon.
352If the local SDP daemon is not running,
353.Nm
354will exit with an error.
355