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 dDhS
  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 the use of
  52 .Xr ppp 8
  53 via an RFCOMM connection.
  54 It can operate in two modes: client and server.
  55 .Pp
  56 In 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 the 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 Likewise,
  71 .Xr ppp 8
  72 operates over the RFCOMM connection just like it would over a standard serial
  73 port, thus allowing a user to
  74 .Dq "dial out"
  75 and connect to the Internet.
  76 .Pp
  77 In 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 Likewise,
  89 .Xr ppp 8
  90 operates over the RFCOMM connection just like it would over a standard serial
  91 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 client mode, this required option specifies the address of the remote
  97 RFCOMM server.
  98 In server mode, this option can be used to specify the local
  99 address to listen on.
 100 By default, in server mode, the daemon will listen on
 101 .Dv ANY
 102 address.
 103 The address can be specified as BD_ADDR or name.
 104 If a name was specified, 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 mode, this required option specifies the RFCOMM
 110 channel to connect to or listen on.
 111 In server mode, the channel should be a number between 1 and 30.
 112 In client mode, the channel could either be a number between 1 and 30
 113 or a service name.
 114 Supported service names are:
 115 .Cm DUN
 116 (Dial-Up Networking) and
 117 .Cm LAN
 118 (LAN Access Using PPP).
 119 If a service name is used instead of a numeric channel number, then
 120 .Nm
 121 will try to obtain an RFCOMM channel number via SDP
 122 (Service 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 D
 129 In 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.
 134 AT-command exchange can be faked with
 135 .Xr ppp 8
 136 chat script.
 137 .It Fl h
 138 Display usage message and exit.
 139 .It Fl l Ar label
 140 In both client and server mode, this required option specifies which
 141 .Xr ppp 8
 142 label will be used.
 143 .It Fl S
 144 In 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
 150 It appears that some cell phones are using the so-called
 151 .Dq "callback mechanism" .
 152 In this scenario, the user is trying to connect his cell phone to the Internet,
 153 while the user's host computer is acting as the gateway server.
 154 It seems that it is not possible to tell the phone to just connect and start
 155 using the
 156 .Cm LAN
 157 service.
 158 Instead, the user's host computer must
 159 .Dq "jump start"
 160 the phone by connecting to the phone's
 161 .Cm SP
 162 service.
 163 What happens next is the phone kills the existing connection and opens another
 164 connection back to the user's host computer.
 165 The phone really wants to use the
 166 .Cm LAN
 167 service, but for whatever reason it looks for the
 168 .Cm SP
 169 service on the user's host computer.
 170 This brain-damaged behavior was reported for the Nokia 6600 and the
 171 Sony/Ericsson P900.
 172 .It Fl s
 173 Act as an RFCOMM server.
 174 .It Fl u Ar N
 175 This option maps directly to the
 176 .Fl unit
 177 .Xr ppp 8
 178 command-line option and tells
 179 .Nm
 180 to instruct
 181 .Xr ppp 8
 182 to only attempt to open
 183 .Pa /dev/tun Ns Ar N .
 184 This option only works in client mode.
 185 .El
 186 .Sh PPP CONFIGURATION
 187 .Ss Important Notes on PPP Configuration
 188 Special attention is required when adding new RFCOMM configurations to the
 189 existing PPP configuration.
 190 Please keep in mind that PPP will
 191 .Em always
 192 execute commands in the
 193 .Dq Li default
 194 label of your
 195 .Pa /etc/ppp/ppp.conf
 196 file.
 197 Please make sure that the
 198 .Dq Li default
 199 label
 200 .Em only
 201 contains commands that apply to
 202 .Em every
 203 other label.
 204 If you need to use PPP for both dialing out and accepting incoming
 205 RFCOMM connections, please make sure you have moved all commands related to
 206 dialing out from the
 207 .Dq Li default
 208 section into an appropriate outgoing label.
 209 .Ss RFCOMM Server
 210 One of the typical examples is the LAN access.
 211 In this example, an RFCOMM connection
 212 is used as a null-modem connection between a client and a server.
 213 Both client and server will start talking PPP right after the RFCOMM
 214 connection has been established.
 215 .Bd -literal -offset indent
 216 rfcomm-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
 231 The
 232 .Nm
 233 utility supports both
 234 .Cm LAN
 235 (LAN Access Using PPP) and
 236 .Cm DUN
 237 (Dial-Up Networking) access.
 238 The client's configuration for
 239 .Cm LAN
 240 access is very similar to the server's and might look like this:
 241 .Bd -literal -offset indent
 242 rfcomm-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
 257 The client's configuration for
 258 .Cm DUN
 259 access is different.
 260 In this scenario, the client gets connected to the virtual serial port on the
 261 server.
 262 To open a PPP session, the client must dial a number.
 263 Note that by default
 264 .Xr ppp 8
 265 will not execute any configured chat scripts.
 266 The
 267 .Ic force-scripts
 268 option can be used to override this behavior.
 269 An example configuration is shown below:
 270 .Bd -literal -offset indent
 271 rfcomm-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
 292 Note that by adjusting the initialization string, one can make a CSD (Circuit
 293 Switched Data), HSCSD (High Speed Circuit Switched Data) or GPRS (General
 294 Packet Radio Service) connection.
 295 The availability of the particular connection
 296 type 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
 302 This command will start
 303 .Nm
 304 in the server mode.
 305 The RFCOMM server will listen on local address
 306 .Li 00:01:02:03:04:05
 307 and channel
 308 .Li 1 .
 309 Once the incoming connection has been accepted,
 310 .Nm
 311 will execute
 312 .Xr ppp 8
 313 in
 314 .Fl direct
 315 mode with the
 316 .Dq Li rfcomm-server
 317 label.
 318 .Pp
 319 .Dl "rfcomm_pppd -c -a 00:01:02:03:04:05 -C 1 -l rfcomm-client"
 320 .Pp
 321 This command will start
 322 .Nm
 323 in the client mode.
 324 .Nm
 325 will try to connect to the RFCOMM server at
 326 .Li 00:01:02:03:04:05
 327 address and channel
 328 .Li 1 .
 329 Once connected,
 330 .Nm
 331 will execute
 332 .Xr ppp 8
 333 in
 334 .Fl direct
 335 mode with the
 336 .Dq Li rfcomm-client
 337 label.
 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 m_evmenkin@yahoo.com
 347 .Sh CAVEATS
 348 The
 349 .Nm
 350 utility in server mode will try to register the Bluetooth LAN Access Over PPP
 351 service with the local SPD daemon.
 352 If the local SDP daemon is not running,
 353 .Nm
 354 will exit with an error.