usr.sbin/bluetooth/rfcomm_pppd/rfcomm_pppd.8

   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
  49 The
  50 .Nm
  51 daemon is a simple wrapper daemon that allows to use standard
  52 .Xr ppp 8
  53 on RFCOMM connection.
  54 It can operate in two modes: client and server.
  55 .Pp
  56 In the client mode,
  57 .Nm
  58 opens an RFCOMM connection to the specified server's
  59 .Ar BD_ADRR
  60 and
  61 .Ar channel .
  62 Once RFCOMM connection is established,
  63 .Nm
  64 executes
  65 .Xr ppp 8
  66 in
  67 .Fl direct
  68 mode with the specified
  69 .Ar label .
  70 The
  71 .Xr ppp 8
  72 in its turn operates over the RFCOMM connection just like it would operate
  73 over the standard serial port thus allowing user to
  74 .Dq "dial out"
  75 and connect to the Internet.
  76 .Pp
  77 In the server mode,
  78 .Nm
  79 opens an RFCOMM socket and listens for incoming connections from remote clients.
  80 Once the new incoming connection is accepted,
  81 .Nm
  82 forks and executes
  83 .Xr ppp 8
  84 in
  85 .Fl direct
  86 mode with the specified
  87 .Ar label .
  88 The
  89 .Xr ppp 8
  90 in its turn operates over the RFCOMM connection just like it would operate over
  91 the standard serial port thus providing network connectivity to remote clients.
  92 .Pp
  93 The options are as follows:
  94 .Bl -tag -width indent
  95 .It Fl a Ar address
  96 In the client mode, this required option specifies the address of the remote
  97 RFCOMM server.
  98 In the server mode, this option can be used to specify the local
  99 address to listen on.
 100 By default, server will listen on
 101 .Dv ANY
 102 address.
 103 The address can be specified as BD_ADDR or name.
 104 If name was specified then the
 105 .Nm
 106 utility will attempt to resolve the name via
 107 .Xr bt_gethostbyname 3 .
 108 .It Fl C Ar channel
 109 In both client and server modes, this required option specifies RFCOMM channel
 110 to connect to or listen on.
 111 In the server mode, RFCOMM channel should be a number between 1 and 30.
 112 In the client mode, RFCOMM channel could either be a number between 1 and 30
 113 or a service name.
 114 Supported service names are:
 115 .Cm DUN
 116 (for DialUp Networking service) and
 117 .Cm LAN
 118 (for LAN Access Using PPP service).
 119 If service name was specified instead of numeric RFCOMM channel then
 120 .Nm
 121 utility will try to obtain RFCOMM channel for the service via Service
 122 Discovery Protocol.
 123 .It Fl c
 124 Act as an RFCOMM client.
 125 This is the default mode.
 126 .It Fl d
 127 Do not detach from the controlling terminal, i.e., run in foreground.
 128 .It Fl h
 129 Display usage message and exit.
 130 .It Fl l Ar label
 131 In both client and server modes, this required option specifies which
 132 .Xr ppp 8
 133 label will be used.
 134 .It Fl S
 135 In the server mode, register the Serial Port (SP) service in addition to the
 136 LAN Access Using PPP (LAN) service.
 137 It appears that some cell phones are using the so-called
 138 .Dq "callback mechanism" .
 139 In this scenario, the user is trying to connect his cell phone to the Internet,
 140 and user's host computer is acting as the gateway server.
 141 It seems that it is not possible to tell the phone to just connect and start
 142 using the LAN service.
 143 Instead, the user's host computer must
 144 .Dq "jump start"
 145 the phone by connecting to the phone's SP service.
 146 What happens next is the phone kills the existing connection and opens another
 147 connection back to the user's host computer.
 148 The phone really wants to use LAN service, but for whatever reason it looks
 149 for the SP service on the user's host computer.
 150 This brain damaged behavior was reported for Nokia 6600 and Sony/Ericsson P900.
 151 .It Fl s
 152 Act as an RFCOMM server.
 153 .It Fl u Ar N
 154 This option maps directly onto
 155 .Fl unit
 156 .Xr ppp 8
 157 command line option and tells
 158 .Nm
 159 to instruct
 160 .Xr ppp 8
 161 to only attempt to open
 162 .Pa /dev/tun Ns Ar N .
 163 This option only works in the client mode.
 164 .El
 165 .Sh PPP CONFIGURATION
 166 .Ss Important Notes on PPP Configuration
 167 Special attention is required when adding new RFCOMM configurations to the
 168 existing PPP configuration.
 169 Please keep in mind that PPP will
 170 .Em always
 171 execute commands in the
 172 .Dq Li default
 173 label of your
 174 .Pa /etc/ppp/ppp.conf
 175 file.
 176 Please make sure that the
 177 .Dq Li default
 178 label
 179 .Em only
 180 contains commands that apply to
 181 .Em every
 182 other label.
 183 If you need to use PPP for both dialing out and accepting incoming
 184 RFCOMM connections, please make sure you have moved all commands related to
 185 dialing out from the
 186 .Dq Li default
 187 section into an appropriate outgoing label.
 188 .Ss RFCOMM Server
 189 One of the typical examples is the LAN access.
 190 In this example, RFCOMM connection
 191 is used as a null-modem connection between client and server.
 192 Both client
 193 and server will start talking PPP right after RFCOMM connection was established.
 194 .Bd -literal -offset indent
 195 rfcomm-server:
 196  set timeout 0
 197  set lqrperiod 10
 198  set ifaddr 10.0.0.1 10.0.0.2 255.255.255.0
 199  enable lqr
 200  accept lqr
 201  # Do not use PPP authentication. Assume that
 202  # Bluetooth connection was authenticated already
 203  disable pap
 204  deny pap
 205  disable chap
 206  deny chap
 207 .Ed
 208 .Ss RFCOMM Client
 209 The
 210 .Nm
 211 utility
 212 supports both LAN and DUN (Dial-Up Networking) access.
 213 The client's configuration for the LAN access is very similar to server's and
 214 might look like this.
 215 .Bd -literal -offset indent
 216 rfcomm-client:
 217  enable lqr
 218  accept lqr
 219  set dial
 220  set timeout 0
 221  disable iface-alias
 222  set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
 223  # Do not use PPP authentication. Assume that
 224  # Bluetooth connection was authenticated already
 225  deny pap
 226  disable pap
 227  deny chap
 228  disable chap
 229 .Ed
 230 .Pp
 231 The client's configuration for the DUN access is different.
 232 In this scenario, the client gets connected to the virtual serial port on the
 233 server.
 234 To open a PPP session, client must dial a number.
 235 Note that by default
 236 .Xr ppp 8
 237 will not execute any configured chat scripts.
 238 The
 239 .Ic force-scripts
 240 option can be used to override this behavior.
 241 The example of such configuration is shown below.
 242 .Bd -literal -offset indent
 243 rfcomm-dialup:
 244  # This is IMPORTANT option
 245  enable force-scripts
 246
 247  # You might want to change these
 248  set authname
 249  set authkey
 250  set phone "*99***1#"
 251
 252  # You might want to adjust dial string as well
 253  set dial "ABORT BUSY ABORT NO\\\\sCARRIER TIMEOUT 5 \\
 254            \\"\\" AT OK-AT-OK ATE1Q0 OK \\\\dATDT\\\\T TIMEOUT 40 CONNECT"
 255  set login
 256  set timeout 30
 257  enable dns
 258  resolv rewrite
 259
 260  set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.0 0.0.0.0
 261  add default HISADDR
 262 .Ed
 263 .Pp
 264 Note that by adjusting the initialization string, one can make CSD (Circuit
 265 Switched Data), HSCSD (High Speed Circuit Switched Data) or GPRS (General
 266 Packet Radio Service) connection.
 267 The availability of the particular connection
 268 type depends on the phone model and service plan activated on the phone.
 269 .Sh EXIT STATUS
 270 .Ex -std
 271 .Sh EXAMPLES
 272 .Dl "rfcomm_pppd -s -a 00:01:02:03:04:05 -C 1 -l rfcomm-server"
 273 .Pp
 274 This command will start
 275 .Nm
 276 in the server mode.
 277 The RFCOMM server will listen on local address
 278 .Li 00:01:02:03:04:05
 279 and channel
 280 .Li 1 .
 281 Once the incoming connection has been accepted,
 282 .Nm
 283 will execute
 284 .Xr ppp 8
 285 in
 286 .Fl direct
 287 mode with
 288 .Dq Li rfcomm-server
 289 label.
 290 .Pp
 291 .Dl "rfcomm_pppd -c -a 00:01:02:03:04:05 -C 1 -l rfcomm-client"
 292 .Pp
 293 This command will start
 294 .Nm
 295 in the client mode.
 296 .Nm
 297 will try to connect to the RFCOMM server at
 298 .Li 00:01:02:03:04:05
 299 address and channel
 300 .Li 1 .
 301 Once connected, the
 302 .Nm
 303 will execute
 304 .Xr ppp 8
 305 in
 306 .Fl direct
 307 mode with
 308 .Dq Li rfcomm-client
 309 label.
 310 .Sh CAVEAT
 311 The
 312 .Nm
 313 utility in server mode will try to register Bluetooth LAN Access Over PPP
 314 service with local SPD daemon.
 315 If local SDP daemon is not running the
 316 .Nm
 317 utility will exit with error.
 318 .Sh SEE ALSO
 319 .Xr rfcomm_sppd 1 ,
 320 .Xr bluetooth 3 ,
 321 .Xr ng_btsocket 4 ,
 322 .Xr ppp 8 ,
 323 .Xr sdpcontrol 8 ,
 324 .Xr sdpd 8
 325 .Sh AUTHORS
 326 .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com