usr.sbin/bluetooth/bluetooth-config/bluetooth-config.8

   1 .\" Copyright (c) 2019 Dirk Engling
   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 .\" $FreeBSD$
  26 .\"
  27 .Dd January 7, 2019
  28 .Dt BLUETOOTH-CONFIG 8
  29 .Os
  30 .Sh NAME
  31 .Nm bluetooth-config
  32 .Nd a script to manage config files for the bluetooth sub system
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Ar scan
  36 .Op Fl d Ar device
  37 .Op Fl n Ar node
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility is an interactive script to provide a frontend to the complex bluetooth sub system daemons.
  42 .Pp
  43 The following options are available:
  44 .Bl -tag -width indent+
  45 .It Fl d
  46 Scan for a specific bluetooth device address.
  47 .It Fl n
  48 Limit scan to a specific host controller.
  49 Hint: List all netgraph nodes with
  50 .Ql /usr/sbin/ngctl list .
  51 .El
  52 .Pp
  53 .Nm
  54 will help finding and setting up bluetooth controllers, scan for nearby bluetooth devices in
  55 pairing mode, lookup their names, allow mapping to friendly names in
  56 .Pa /etc/bluetooth/hosts ,
  57 ask for the paring PIN, instrument
  58 .Xr hcsecd 8
  59 to securely pair with new devices and, if the device offers HID endpoints such as mice or
  60 keyboards, configure and restart
  61 .Xr bthidd 8 .
  62 .Pp
  63 .Nm
  64 can bring up any interface and daemon necessary for operation and, if a node is provided on
  65 command line, will do so automatically for that interface.
  66 .Sh FILES
  67 .Bl -tag -width ".Pa /etc/bluetooth/hosts" -compact
  68 .It Pa /etc/bluetooth/hosts
  69 .It Pa sysrc -n bthidd_config
  70 .It Pa sysrc -n hcsecd_config
  71 .El
  72 .Sh EXAMPLES
  73 .Nm
  74 scan -n ubt0 -a 00:26:bb:7a:58:95
  75 .Bd -ragged -offset indent
  76 This will scan the bluetooth controller ubt0hci for a bluetooth device with the address
  77 00:26:bb:7a:58:95, set up ubt0 if necessary and enter an interactive dialog to pair the
  78 new device.
  79 Since in this example a mouse is paired,
  80 .Nm
  81 will interact with
  82 .Xr bthidd 8 ,
  83 enabling it if necessary and then write an HID descriptor to its config.
  84 .Ed
  85 .Pp
  86 .Nm
  87 scan
  88 .Bd -ragged -offset indent
  89 This will scan all bluetooth controllers on the systems for bluetooth devices, prompting
  90 to bring up controllers or daemons along the way.
  91 .Ed
  92 .Sh SEE ALSO
  93 .Xr bthost 1 ,
  94 .Xr bthidcontrol 8 ,
  95 .Xr bthidd 8 ,
  96 .Xr hccontrol 8 ,
  97 .Xr hcsecd 8 ,
  98 .Xr sdpcontrol 8 ,
  99 .Xr sysrc 8
 100 .Sh HISTORY
 101 A
 102 .Nm
 103 utility first appeared in
 104 .Fx 12.1 .
 105 .Sh AUTHORS
 106 .An Dirk Engling Aq Mt erdgeist@erdgeist.org
 107 .Sh CAVEATS
 108 .Nm
 109 can not parse entries in
 110 .Xr hcsecd 8
 111 config file and thus will ask the user to manually modify existing pairing PIN entries.
 112 .Sh THANKS TO
 113 Lars Engels and Warren Block for suggestions, help, and testing.