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 dhS
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 h
129Display usage message and exit.
130.It Fl l Ar label
131In both client and server mode, this required option specifies which
132.Xr ppp 8
133label will be used.
134.It Fl S
135In server mode, register the
136.Cm SP
137(Serial Port) service in addition to the
138.Cm LAN
139(LAN Access Using PPP) service.
140.Pp
141It appears that some cell phones are using the so-called
142.Dq "callback mechanism" .
143In this scenario, the user is trying to connect his cell phone to the Internet,
144while the user's host computer is acting as the gateway server.
145It seems that it is not possible to tell the phone to just connect and start
146using the
147.Cm LAN
148service.
149Instead, the user's host computer must
150.Dq "jump start"
151the phone by connecting to the phone's
152.Cm SP
153service.
154What happens next is the phone kills the existing connection and opens another
155connection back to the user's host computer.
156The phone really wants to use the
157.Cm LAN
158service, but for whatever reason it looks for the
159.Cm SP
160service on the user's host computer.
161This brain-damaged behavior was reported for the Nokia 6600 and the
162Sony/Ericsson P900.
163.It Fl s
164Act as an RFCOMM server.
165.It Fl u Ar N
166This option maps directly to the
167.Fl unit
168.Xr ppp 8
169command-line option and tells
170.Nm
171to instruct
172.Xr ppp 8
173to only attempt to open
174.Pa /dev/tun Ns Ar N .
175This option only works in client mode.
176.El
177.Sh PPP CONFIGURATION
178.Ss Important Notes on PPP Configuration
179Special attention is required when adding new RFCOMM configurations to the
180existing PPP configuration.
181Please keep in mind that PPP will
182.Em always
183execute commands in the
184.Dq Li default
185label of your
186.Pa /etc/ppp/ppp.conf
187file.
188Please make sure that the
189.Dq Li default
190label
191.Em only
192contains commands that apply to
193.Em every
194other label.
195If you need to use PPP for both dialing out and accepting incoming
196RFCOMM connections, please make sure you have moved all commands related to
197dialing out from the
198.Dq Li default
199section into an appropriate outgoing label.
200.Ss RFCOMM Server
201One of the typical examples is the LAN access.
202In this example, an RFCOMM connection
203is used as a null-modem connection between a client and a server.
204Both client and server will start talking PPP right after the RFCOMM
205connection has been established.
206.Bd -literal -offset indent
207rfcomm-server:
208 set timeout 0
209 set lqrperiod 10
210 set ifaddr 10.0.0.1 10.0.0.2 255.255.255.0
211 enable lqr
212 accept lqr
213 # Do not use PPP authentication. Assume that
214 # Bluetooth connection was authenticated already
215 disable pap
216 deny pap
217 disable chap
218 deny chap
219.Ed
220.Ss RFCOMM Client
221The
222.Nm
223utility supports both
224.Cm LAN
225(LAN Access Using PPP) and
226.Cm DUN
227(Dial-Up Networking) access.
228The client's configuration for
229.Cm LAN
230access is very similar to the server's and might look like this:
231.Bd -literal -offset indent
232rfcomm-client:
233 enable lqr
234 accept lqr
235 set dial
236 set timeout 0
237 disable iface-alias
238 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
239 # Do not use PPP authentication. Assume that
240 # Bluetooth connection was authenticated already
241 deny pap
242 disable pap
243 deny chap
244 disable chap
245.Ed
246.Pp
247The client's configuration for
248.Cm DUN
249access is different.
250In this scenario, the client gets connected to the virtual serial port on the
251server.
252To open a PPP session, the client must dial a number.
253Note that by default
254.Xr ppp 8
255will not execute any configured chat scripts.
256The
257.Ic force-scripts
258option can be used to override this behavior.
259An example configuration is shown below:
260.Bd -literal -offset indent
261rfcomm-dialup:
262 # This is IMPORTANT option
263 enable force-scripts
264
265 # You might want to change these
266 set authname
267 set authkey
268 set phone "*99***1#"
269
270 # You might want to adjust dial string as well
271 set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 5 \\
272           \\"\\" AT OK-AT-OK ATE1Q0 OK \\\\dATDT\\\\T TIMEOUT 40 CONNECT"
273 set login
274 set timeout 30
275 enable dns
276 resolv rewrite
277
278 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
279 add default HISADDR
280.Ed
281.Pp
282Note that by adjusting the initialization string, one can make a CSD (Circuit
283Switched Data), HSCSD (High Speed Circuit Switched Data) or GPRS (General
284Packet Radio Service) connection.
285The availability of the particular connection
286type depends on the phone model and service plan activated on the phone.
287.Sh EXIT STATUS
288.Ex -std
289.Sh EXAMPLES
290.Dl "rfcomm_pppd -s -a 00:01:02:03:04:05 -C 1 -l rfcomm-server"
291.Pp
292This command will start
293.Nm
294in the server mode.
295The RFCOMM server will listen on local address
296.Li 00:01:02:03:04:05
297and channel
298.Li 1 .
299Once the incoming connection has been accepted,
300.Nm
301will execute
302.Xr ppp 8
303in
304.Fl direct
305mode with the
306.Dq Li rfcomm-server
307label.
308.Pp
309.Dl "rfcomm_pppd -c -a 00:01:02:03:04:05 -C 1 -l rfcomm-client"
310.Pp
311This command will start
312.Nm
313in the client mode.
314.Nm
315will try to connect to the RFCOMM server at
316.Li 00:01:02:03:04:05
317address and channel
318.Li 1 .
319Once connected,
320.Nm
321will execute
322.Xr ppp 8
323in
324.Fl direct
325mode with the
326.Dq Li rfcomm-client
327label.
328.Sh CAVEATS
329The
330.Nm
331utility in server mode will try to register the Bluetooth LAN Access Over PPP
332service with the local SPD daemon.
333If the local SDP daemon is not running,
334.Nm
335will exit with an error.
336.Sh SEE ALSO
337.Xr rfcomm_sppd 1 ,
338.Xr bluetooth 3 ,
339.Xr ng_btsocket 4 ,
340.Xr ppp 8 ,
341.Xr sdpcontrol 8 ,
342.Xr sdpd 8
343.Sh AUTHORS
344.An Maksim Yevmenkin Aq m_evmenkin@yahoo.com
345