usr.sbin/btpand/btpand.8

   1 .\" $NetBSD: btpand.8,v 1.3 2008/08/17 14:43:07 plunky Exp $
   2 .\"
   3 .\" Copyright (c) 2008 Iain Hibbert
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd August 17, 2008
  27 .Dt BTPAND 8
  28 .Os
  29 .Sh NAME
  30 .Nm btpand
  31 .Nd Bluetooth PAN daemon
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Op Fl i Ar ifname
  35 .Op Fl m Ar mode
  36 .Fl a Ar addr
  37 .Fl d Ar device
  38 .Brq Fl s Ar service | Fl S Ar service Op Fl p Ar psm
  39 .Nm
  40 .Op Fl c Ar path
  41 .Op Fl i Ar ifname
  42 .Op Fl l Ar limit
  43 .Op Fl m Ar mode
  44 .Op Fl p Ar psm
  45 .Fl d Ar device
  46 .Brq Fl s Ar service | Fl S Ar service
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 daemon handles Bluetooth Personal Area Networking services
  51 in the system.
  52 It can operate in client mode as a Personal Area Networking User
  53 .Pq PANU
  54 or in server mode as Network Access Point
  55 .Pq NAP ,
  56 Group ad-hoc Network
  57 .Pq GN
  58 or PANU host.
  59 .Nm
  60 connects to the system via a
  61 .Xr tap 4
  62 virtual Ethernet device and forwards Ethernet packets to
  63 remote Bluetooth devices using the Bluetooth Network Encapsulation
  64 Protocol
  65 .Pq BNEP .
  66 .Pp
  67 The PANU client is the device that uses either the NAP or GN
  68 service, or can talk directly to a PANU host in a crossover
  69 cable fashion.
  70 .Pp
  71 A GN host forwards Ethernet packets to each of the connected PAN
  72 users as needed but does not provide access to any additional networks.
  73 .Pp
  74 The NAP service provides some of the features of an Ethernet bridge,
  75 with the NAP host forwarding Ethernet packets between each of the
  76 connected PAN users, and a different network
  77 media.
  78 .Pp
  79 Note, the only differences between NAP and GN services as implemented by
  80 .Nm
  81 are in the SDP service record.
  82 The bridging of packets by the NAP must be configured separately with
  83 .Xr brconfig 4 .
  84 .Pp
  85 The options are as follows:
  86 .Bl -tag -width ".Fl a Ar address"
  87 .It Fl a Ar address
  88 In client mode, address of remote server.
  89 May be given as BDADDR or name, in which case
  90 .Nm
  91 will attempt to resolve the address via the
  92 .Xr bt_gethostbyname 3
  93 call.
  94 .It Fl c Ar path
  95 In server mode, specify
  96 .Ar path
  97 to the
  98 .Xr sdpd 8
  99 control socket.
 100 The default path is
 101 .Pa /var/run/sdp .
 102 .It Fl d Ar device
 103 Restrict connections to the local
 104 .Ar device .
 105 May be given as BDADDR or name, in which case
 106 .Nm
 107 will attempt to resolve the address via the
 108 .Xr bt_devaddr 3
 109 call.
 110 .Nm
 111 will set the
 112 .Xr tap 4
 113 interface physical address to the BDADDR
 114 of the Bluetooth radio.
 115 .It Fl i Ar ifname
 116 .Nm
 117 uses the
 118 .Xr tap 4
 119 driver to create a new network interface for use.
 120 Use this option to select a specific
 121 .Xr tap 4
 122 device interface which must already be created.
 123 .It Fl l Ar limit
 124 In server mode, limit the number of simultaneous connections.
 125 The default limit is 7 for NAP and GN servers,
 126 and 1 for a PANU server.
 127 .It Fl m Ar mode
 128 Set L2CAP connection link mode.
 129 Supported modes are:
 130 .Pp
 131 .Bl -tag -compact
 132 .It auth
 133 require devices to be paired.
 134 .It encrypt
 135 auth, plus enable encryption.
 136 .It secure
 137 encryption, plus change of link key.
 138 .El
 139 .It Fl p Ar psm
 140 Use an alternative L2CAP Protocol/Service Multiplexer
 141 .Pq PSM
 142 for server mode or client mode
 143 .Pq when not using Service Discovery .
 144 The default PSM for BNEP is 15
 145 .Pq 0x000f .
 146 .It Fl s Ar service
 147 Name of
 148 .Ar service
 149 to provide or connect to, the following services are recognised:
 150 .Pp
 151 .Bl -tag -compact
 152 .It GN
 153 Group ad-hoc Network.
 154 .It NAP
 155 Network Access Point.
 156 .It PANU
 157 Personal Area Networking User.
 158 .El
 159 .Pp
 160 .It Fl S Ar service
 161 As per
 162 .Fl s
 163 except that
 164 .Nm
 165 will not use SDP services for connection setup.
 166 .El
 167 .Pp
 168 When providing networking services, the Bluetooth PAN profile says that the
 169 .Sq Class of Device
 170 property of the bluetooth controller SHALL include Networking capability
 171 .Pq set bit 0x020000 .
 172 See
 173 .Xr btconfig 8
 174 for details.
 175 .Pp
 176 After
 177 .Nm
 178 has set up the client or server connection and opened the
 179 .Xr tap 4
 180 interface, it will create a pid file and detach.
 181 .Sh EXIT STATUS
 182 .Ex -std
 183 .Sh FILES
 184 .Bl -tag -compact
 185 .It Pa /dev/tap
 186 .It Pa /etc/bluetooth/hosts
 187 .It Pa /var/run/sdp
 188 .It Pa /var/run/tap Ns Em N Ns No .pid
 189 .El
 190 .Sh EXAMPLES
 191 .Dl ifconfig tap1 create
 192 .Dl btpand -a host -d ubt0 -s NAP -m encrypt -i tap1
 193 .Dl dhclient -q -o -w -nw tap1
 194 .Pp
 195 Will create an encrypted connection to the NAP on
 196 .Ar host ,
 197 and link that to the
 198 .Ar tap1
 199 interface.
 200 .Pp
 201 .Dl btpand -d ubt0 -s GN -m auth
 202 .Pp
 203 Will create a Group Network requiring authentication to join and register
 204 the GN service with the local SDP server.
 205 .Sh SEE ALSO
 206 .Xr bluetooth 3 ,
 207 .Xr bluetooth 4 ,
 208 .Xr tap 4 ,
 209 .Xr bridge 4 ,
 210 .Xr btconfig 8 ,
 211 .Xr brconfig 8 ,
 212 .Xr dhclient 8 ,
 213 .Xr dhcpd 8 ,
 214 .Xr ifconfig 8 ,
 215 .Xr sdpd 8
 216 .Pp
 217 The
 218 .Qq Personal Area Networking Profile
 219 and
 220 .Qq Bluetooth Network Encapsulation Protocol
 221 specifications are available at
 222 .Dl http://www.bluetooth.com/
 223 .Sh AUTHORS
 224 .An Iain Hibbert
 225 .Sh BUGS
 226 There is no way to supply alternative values for the SDP record.
 227 .Pp
 228 There is no way to set net type or multicast address filters.
 229 .Pp
 230 .Nm
 231 does not do any address routing except to directly connected
 232 unicast addresses.
 233 All other packets are multicast.
 234 .Pp
 235 As
 236 .Nm
 237 uses the BDADDR of the Bluetooth radio as the physical address
 238 of the tap, only one instance can be run per radio.
 239 .Pp
 240 .Nm
 241 can only provide a single service.