Skip to content

Linux + iPhone Continuity / iMessage / SMS

fix: flatpak setup instructions

Zack Bartele93395fe9eac
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..21a128f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,69 @@
+name: Bug report
+description: Something in Tether does not work
+labels: ["bug"]
+body:
+ - type: textarea
+ id: what
+ attributes:
+ label: What happened
+ description: What you did, what you expected, what you got instead.
+ validations:
+ required: true
+
+ - type: dropdown
+ id: install
+ attributes:
+ label: How did you install Tether?
+ options:
+ - Flatpak
+ - AppImage
+ - Arch / AUR
+ - Debian or Ubuntu package
+ - Fedora package
+ - Container
+ - Built from source
+ validations:
+ required: true
+
+ - type: input
+ id: version
+ attributes:
+ label: Output of `tether --version`
+ placeholder: "0.2.34"
+ validations:
+ required: true
+
+ - type: input
+ id: system
+ attributes:
+ label: Distribution, init system, desktop
+ placeholder: "Fedora 42, systemd, GNOME 49 Wayland"
+ validations:
+ required: true
+
+ - type: textarea
+ id: bt-status
+ attributes:
+ label: Output of `tether --bt-status` and `tether --bt-setup`
+ description: Skip if the problem has nothing to do with Bluetooth. Run both, paste both.
+ render: shell
+
+ - type: input
+ id: bluez
+ attributes:
+ label: BlueZ version
+ description: "`bluetoothctl --version`. Skip for non-Bluetooth problems."
+ placeholder: "5.87"
+
+ - type: input
+ id: iphone
+ attributes:
+ label: iPhone model and iOS version
+ placeholder: "iPhone 15 Pro, iOS 27.1"
+
+ - type: textarea
+ id: logs
+ attributes:
+ label: Logs
+ description: Relevant lines from `tetherd.log`, or the terminal output. Trim to what matters.
+ render: shell
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..88bdeaf
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Security vulnerability
+ url: https://github.com/zackb/tether/security/policy
+ about: Report privately, not as a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..6bf1e21
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,23 @@
+name: Feature request
+description: Suggest something Tether should do
+labels: ["enhancement"]
+body:
+ - type: textarea
+ id: problem
+ attributes:
+ label: The problem
+ description: What you are trying to do that Tether makes hard or impossible today.
+ validations:
+ required: true
+
+ - type: textarea
+ id: proposal
+ attributes:
+ label: What you would like instead
+ validations:
+ required: true
+
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives you tried
diff --git a/docs/BLUETOOTH.md b/docs/BLUETOOTH.md
index f1929ad..8d1f2ba 100644
--- a/docs/BLUETOOTH.md
+++ b/docs/BLUETOOTH.md
@@ -930,6 +930,7 @@ checks the daemon does not make.
| `systemctl enable --now tether-btclass@hci0` hangs in `activating (start)` forever | `btmgmt` epolls its stdin before running the command, and epoll rejects the `/dev/null` systemd hands it, so it waits having done nothing | Update the unit -- it pipes into `btmgmt` now. On an older build, `sudo btmgmt class 4 8` by hand sets the class until `bluetoothd` restarts, see 2026-09-01 below |
| `systemctl enable --now tether-btclass@hci0` says `Unit [email protected] does not exist` | A portable build (AppImage, Flatpak) installed no unit -- only the distro packages do | `tether --bt-setup` and run the command it prints, which writes the unit first, see 2026-09-05 below |
| `tether-btclass@hci0` fails with `Invalid Index`, having worked for months | The controller re-enumerated -- a failed firmware handshake resets it over USB and it comes back as `hci1` -- so the instance name points at an adapter that no longer exists | Update the unit -- it resolves the adapter itself now and the instance name is only a hint, see 2026-09-11 below. By hand, `ls /sys/class/bluetooth` names the live adapter |
+| `tether --bt-setup` keeps printing the experimental step after the drop-in was applied and `bluetooth` restarted | Before 0.2.35 the check read `/proc`, which a Flatpak sandbox cannot see, and which `main.conf` `Experimental = true` never touches | Update. Confirm the flag itself with `busctl --system introspect org.bluez /org/bluez/hci0 \| grep AdvertisementMonitor` -- a hit means the experimental API is on, see 2026-09-20 below |
| Messages and contacts worked, then stopped, and the error mentions a service record | `bluetoothd` restarted and reset the Class of Device | `sudo systemctl enable --now tether-btclass@hci0`, then re-pair if the phone dropped the bond |
| The phone never offers notifications / Sync Contacts | The class is wrong, or the ANCS advertisement is not running | Check for `class=ok` in `tether --bt-status`, can take minutes |
| MAP or PBAP reports `forbidden` | The matching toggle on the phone is off | Turn it on. This is not a pairing failure |
@@ -3209,7 +3210,9 @@ the bearer step is a `sed` plus a restart through the machine's own service mana
Not yet verified on hardware: that `class=ok` survives a `bluetoothd` restart on a machine
without hostnamed. The `sed` leaves a `main.conf` with no `Class` or `Experimental` line,
-commented or not, unchanged, and `--bt-setup` keeps listing the step.
+commented or not, unchanged, and `--bt-setup` keeps listing the step. The experimental half of
+that last point is fixed in 2026-09-20 below: the flag is read off BlueZ now, whichever way it
+was set.
### 2026-09-11 - The AirPods sink jammed after a call
@@ -3610,3 +3613,41 @@ every rebuild.
Not settled: the exact `ReadValue` error on the GAP characteristic with only BR/EDR up, and the
fix itself on hardware (walk out until only `LE1` times out, come back, expect `LE link dropped`
then a new session and a popup).
+
+### 2026-09-20 - `--bt-setup` kept printing the experimental step inside Flatpak (#206)
+
+Reported in #206: the drop-in `--bt-setup` printed was applied, `bluetooth` restarted, and the
+rerun under `flatpak run --command=tether com.tether.desktop --bt-setup` listed the same step.
+
+`bluetoothd` has no property for its own flags, so the check walked `/proc` for a process named
+`bluetoothd` and looked for `-E` / `--experimental`. Flatpak gives the app its own PID namespace:
+
+```
+$ flatpak run --command=sh <app> -c 'ls /proc | grep -c "^[0-9]*$"'
+4 bwrap, sh, and the pipeline -- no bluetoothd, ever
+```
+
+So `experimental_api` was always false in the sandbox, and with nothing bonded yet to populate
+`Bearer.LE1` the resolver had no second source and pinned `BearerApi::Absent`. The same false
+negative hit every install method whenever the flag came from `main.conf` `Experimental = true`,
+which is what the non-systemd branch of the step itself tells users to do -- the open item left
+in the 2026-09-10 entry above.
+
+`bluetoothd` answers the question on its own bus. `btd_adv_monitor_manager_create()` runs only
+inside `if (g_dbus_get_flags() & G_DBUS_FLAG_ENABLE_EXPERIMENTAL)` (`src/adapter.c`, 5.87 and
+master), so `org.bluez.AdvertisementMonitorManager1` on an adapter object exists only with the
+experimental API on. It arrives in the `GetManagedObjects` reply already parsed, so detection
+costs no extra call, no cache, and no `/proc`, and `scan_bluetoothd_cmdline()` is gone.
+
+```
+$ busctl --system introspect org.bluez /org/bluez/hci0 | grep AdvertisementMonitor
+org.bluez.AdvertisementMonitorManager1 interface
+```
+
+Verified on this machine against the live bus: `experimental_api=1`, `bearer_api=Confirmed`,
+only the class step left. The marker is a BlueZ implementation detail, not API: if a later
+release creates the monitor manager unconditionally, this reads experimental where there is
+none, and the check moves to `Adapter1.ConnectDevice`, which is `GDBUS_EXPERIMENTAL_ASYNC_METHOD`
+and therefore absent from introspection without the flag.
+
+Not verified here: the negative case, which needs `bluetoothd` restarted without the flag.
diff --git a/docs/CONTAINER.md b/docs/CONTAINER.md
index 76a27ef..ed1678c 100644
--- a/docs/CONTAINER.md
+++ b/docs/CONTAINER.md
@@ -223,10 +223,11 @@ Troubleshooting:
reason to enable privileged mode silently.
- **Phone not discoverable:** confirm Avahi, host firewall and local multicast
connectivity. This container cannot make mDNS cross an isolated network/VPN.
-- **Misleading `tether bt setup` advice:** some diagnostics inspect `/proc` for
- `bluetoothd` or use `btmgmt`. The host process is hidden by the container's PID
- namespace, and raw probes may lack permission. Apply the documented setup on
- the host; don't share host PID space just to improve a diagnostic.
+- **Misleading `tether bt setup` advice:** the experimental-API check reads
+ BlueZ's own objects now, so the container's PID namespace no longer hides the
+ answer, but `btmgmt` probes (Secure Connections) may still lack permission.
+ Apply the documented setup on the host; don't share host PID space just to
+ improve a diagnostic.
- **Host service repaired/restarted:** Tether may need a container restart if
BlueZ was unavailable during startup. This packaging does not promise new
D-Bus reconnection behavior.
diff --git a/src/core/include/tether/bluetooth/objects.hpp b/src/core/include/tether/bluetooth/objects.hpp
index 502524a..6d24e1d 100644
--- a/src/core/include/tether/bluetooth/objects.hpp
+++ b/src/core/include/tether/bluetooth/objects.hpp
@@ -41,6 +41,8 @@ namespace tether::bluetooth {
uint8_t advertising_instances = 0;
// Instances BlueZ currently holds registered.
uint8_t advertising_active_instances = 0;
+ // org.bluez.AdvertisementMonitorManager1
+ bool has_adv_monitor_manager = false;
bool has_role(const std::string& role) const;
bool class_is_handsfree() const { return (device_class & COD_MASK) == COD_TARGET; }
@@ -150,7 +152,7 @@ namespace tether::bluetooth {
std::vector<Telephony> telephony;
std::vector<Call> calls;
- // Whether bluetoothd was started with --experimental. Bearer.LE1 exists only under that flag
+ // bluetoothd has experimental API on
bool experimental_api = false;
const Adapter* find_adapter(const std::string& path) const;
diff --git a/src/core/src/bluetooth/monitor.cpp b/src/core/src/bluetooth/monitor.cpp
index 9d55eba..35504cd 100644
--- a/src/core/src/bluetooth/monitor.cpp
+++ b/src/core/src/bluetooth/monitor.cpp
@@ -9,8 +9,6 @@
#include <condition_variable>
#include <csignal>
#include <fcntl.h>
-#include <filesystem>
-#include <fstream>
#include <gio/gio.h>
#include <map>
#include <mutex>
@@ -170,47 +168,6 @@ namespace tether::bluetooth {
g_source_unref(source);
}
- // bluetoothd exposes no property for its own flags, so the argument vector is
- // the only place to read it. Accepts both spellings; Arch's unit uses -E.
- static bool scan_bluetoothd_cmdline() {
- std::error_code ec;
- for (const auto& entry : std::filesystem::directory_iterator("/proc", ec)) {
- std::ifstream comm(entry.path() / "comm");
- std::string name;
- if (!comm || !std::getline(comm, name) || name != "bluetoothd")
- continue;
-
- std::ifstream cmdline(entry.path() / "cmdline", std::ios::binary);
- if (!cmdline)
- continue;
- // Arguments are NUL-separated, so each one compares exactly.
- std::string arg;
- while (std::getline(cmdline, arg, '\0')) {
- if (arg == "-E" || arg == "--experimental")
- return true;
- }
- return false;
- }
- return false;
- }
-
- // Walking /proc costs about 2ms and refresh() runs on every debounced BlueZ
- // signal, so the answer is cached. It cannot change without bluetoothd
- // restarting, but that is exactly what applying the drop-in does, and
- // bluetoothd routinely restarts after tetherd is already up.
- bool bluetoothd_has_experimental() {
- static constexpr auto kRecheckAfter = std::chrono::seconds(3);
- static std::chrono::steady_clock::time_point checked_at{};
- static bool value = false;
-
- const auto now = std::chrono::steady_clock::now();
- if (checked_at == std::chrono::steady_clock::time_point{} || now - checked_at >= kRecheckAfter) {
- value = scan_bluetoothd_cmdline();
- checked_at = now;
- }
- return value;
- }
-
std::optional<bool> probe_secure_connections(const std::string& adapter_id, std::chrono::milliseconds timeout) {
if (adapter_id.empty())
return std::nullopt;
@@ -374,7 +331,6 @@ namespace tether::bluetooth {
BluezObjects parsed = parse_managed_objects(reply);
g_variant_unref(reply);
- parsed.experimental_api = bluetoothd_has_experimental();
std::string preferred;
{
std::lock_guard<std::mutex> lock(mutex);
@@ -482,7 +438,6 @@ namespace tether::bluetooth {
return false;
}
impl_->objects = parse_managed_objects(probe);
- impl_->objects.experimental_api = bluetoothd_has_experimental();
// Secure Connections stays unknown until the watcher thread's first
// refresh: probing it here would fork btmgmt on the startup path.
impl_->cap = resolve_capability(impl_->objects);
diff --git a/src/core/src/bluetooth/objects.cpp b/src/core/src/bluetooth/objects.cpp
index fed88ca..c525678 100644
--- a/src/core/src/bluetooth/objects.cpp
+++ b/src/core/src/bluetooth/objects.cpp
@@ -18,6 +18,7 @@ namespace tether::bluetooth {
constexpr const char* IFACE_TELEPHONY = "org.bluez.Telephony1";
constexpr const char* IFACE_CALL = "org.bluez.Call1";
constexpr const char* IFACE_LE_ADV_MGR = "org.bluez.LEAdvertisingManager1";
+ constexpr const char* IFACE_ADV_MONITOR_MGR = "org.bluez.AdvertisementMonitorManager1";
constexpr const char* IFACE_BEARER_LE = "org.bluez.Bearer.LE1";
constexpr const char* IFACE_BEARER_BREDR = "org.bluez.Bearer.BREDR1";
constexpr const char* IFACE_CHARACTERISTIC = "org.bluez.GattCharacteristic1";
@@ -149,6 +150,11 @@ namespace tether::bluetooth {
g_variant_unref(adv);
}
+ if (GVariant* mon = g_variant_lookup_value(ifaces, IFACE_ADV_MONITOR_MGR, G_VARIANT_TYPE("a{sv}"))) {
+ a.has_adv_monitor_manager = true;
+ g_variant_unref(mon);
+ }
+
out.adapters.push_back(std::move(a));
}
@@ -379,6 +385,10 @@ namespace tether::bluetooth {
}
}
+ // bluetoothd builds the advertisement monitor manager only when the experimental API is on
+ out.experimental_api = std::any_of(
+ out.adapters.begin(), out.adapters.end(), [](const Adapter& a) { return a.has_adv_monitor_manager; });
+
// BlueZ enumerates in a stable but unspecified order; sorting keeps
// snapshot comparison and UI listing deterministic.
std::sort(out.adapters.begin(), out.adapters.end(), [](const Adapter& a, const Adapter& b) {
diff --git a/test/test_bluetooth_objects.cpp b/test/test_bluetooth_objects.cpp
index 535ba45..c7f14f0 100644
--- a/test/test_bluetooth_objects.cpp
+++ b/test/test_bluetooth_objects.cpp
@@ -61,6 +61,26 @@ namespace {
}
})";
+ // The same adapter as reported by a bluetoothd running with the experimental API on:
+ // AdvertisementMonitorManager1 is created only under that flag.
+ constexpr const char* ADAPTER_EXPERIMENTAL = R"({
+ '/org/bluez/hci0': {
+ 'org.bluez.Adapter1': {
+ 'Address': <'02:00:00:00:00:02'>,
+ 'Alias': <'btw'>,
+ 'Class': <uint32 8127496>,
+ 'Powered': <true>,
+ 'Roles': <['central', 'peripheral']>
+ },
+ 'org.bluez.LEAdvertisingManager1': {
+ 'SupportedInstances': <byte 15>
+ },
+ 'org.bluez.AdvertisementMonitorManager1': {
+ 'SupportedFeatures': <['controller-patterns']>
+ }
+ }
+ })";
+
// An iPhone bonded on both transports, exposing MAP, PBAP and ANCS.
constexpr const char* IPHONE_BONDED = R"({
'/org/bluez/hci0/dev_02_00_00_00_00_01': {
@@ -237,6 +257,34 @@ TEST(Capability, SecureConnectionsStateIsInjectedRatherThanReadDuringResolution)
EXPECT_FALSE(disabled.secure_connections);
}
+// Reading the flag off bluetoothd's own objects is what makes it answerable from a
+// Flatpak sandbox, where /proc holds no bluetoothd, and from a main.conf
+// 'Experimental = true' that leaves no argv trace.
+TEST(BluetoothObjects, ExperimentalComesFromTheAdvertisementMonitorManager) {
+ Payload on(ADAPTER_EXPERIMENTAL);
+ auto with = parse_managed_objects(on.v);
+ ASSERT_EQ(with.adapters.size(), 1u);
+ EXPECT_TRUE(with.adapters[0].has_adv_monitor_manager);
+ EXPECT_TRUE(with.experimental_api);
+
+ Payload off(ADAPTER_FULL);
+ auto without = parse_managed_objects(off.v);
+ ASSERT_EQ(without.adapters.size(), 1u);
+ EXPECT_FALSE(without.adapters[0].has_adv_monitor_manager);
+ EXPECT_FALSE(without.experimental_api);
+}
+
+// The experimental step must clear on its own once bluetoothd restarts with the flag,
+// with nothing bonded yet to populate Bearer.LE1.
+TEST(Capability, ExperimentalAdapterAloneClearsTheSetupStep) {
+ Payload p(ADAPTER_EXPERIMENTAL);
+ auto cap = resolve_capability(parse_managed_objects(p.v));
+
+ EXPECT_EQ(cap.bearer_api, BearerApi::Unknown);
+ for (const auto& step : cap.setup)
+ EXPECT_EQ(step.command.find("--experimental"), std::string::npos) << step.command;
+}
+
// Without --experimental the bearer interface can never appear, so its absence
// is conclusive.
TEST(Capability, CompatibilityWhenExperimentalIsOff) {