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