Skip to content

Linux + iPhone Continuity / iMessage / SMS

feat: non-systemd instructions

Zack Bartel95a31dd9bee6
diff --git a/README.md b/README.md
index 91878ee..885e54c 100644
--- a/README.md
+++ b/README.md
@@ -102,8 +102,8 @@ chmod +x tether-*-x86_64.AppImage
./tether-*-x86_64.AppImage --install-extension-host # if you use the browser or mail extension
```
-The iPhone Bluetooth features need a systemd unit the AppImage cannot install for you.
-`--bt-setup` prints the command that writes it.
+The iPhone Bluetooth features need one-time system setup the AppImage cannot do for you.
+`--bt-setup` prints the commands for this machine.
Requires glibc 2.38 and libstdc++ from GCC 13 (Fedora 39+, Ubuntu 23.10+, Debian 13+, Arch).
@@ -325,7 +325,7 @@ See [docs/HEADLESS.md](docs/HEADLESS.md).
#### Bluetooth (for Messages and Notifications)
- BlueZ 5.86+ must be running with experimental bearer API. `tether bt setup`
- prints the systemd drop-in command that enables it. Do this **before** pairing.
+ prints the command that enables it on this machine. Do this **before** pairing.
- A controller with BR/EDR, LE, and advertising support.
- Notification mirroring does not work on iOS 18 and earlier.
diff --git a/docs/BLUETOOTH.md b/docs/BLUETOOTH.md
index 4b101f5..0c84ebd 100644
--- a/docs/BLUETOOTH.md
+++ b/docs/BLUETOOTH.md
@@ -88,6 +88,13 @@ for the whole machine is the user's decision. The class unit ships but stays
disabled for the same reason, and `--install-btclass-unit` writes it without
enabling it on the builds that have no package to ship it.
+**Without systemd** (Artix, Void, Devuan) there is no unit to enable and no drop-in
+to write, so `--bt-setup` prints edits to `/etc/bluetooth/main.conf` instead:
+`Experimental = true`, the same switch as `--experimental`, and `Class = 0x000408`,
+applied to the running adapter with `btmgmt`. Restart `bluetoothd` with the machine's
+own service manager. The class setting only holds where nothing overrides it, which is
+why it is not the systemd answer, see 2026-09-10 below.
+
Without it `bluetoothd` still registers `org.bluez.Bearer.LE1`, but as an empty
marker: no properties, no `Connect()`. So the interface being present is not
evidence the API is available, and code that reads it that way sees an LE bearer
@@ -3053,3 +3060,26 @@ with no lock handler configured -- hypridle, swayidle -- will do nothing with it
`lock_command` in `bluetooth.json` runs a command instead for those setups. No
Wayland protocol is involved: implementing `ext-session-lock-v1` would mean shipping
a screen locker, which is not this daemon's job.
+
+### 2026-09-10 - `--bt-setup` printed systemd commands on machines without it
+
+Requested as #158 for Artix. Both setup steps assumed systemd: the bearer API step wrote a
+`bluetooth.service.d` drop-in, and the class step enabled `tether-btclass@`. On Artix the Arch
+package still installs the unit into `/usr/lib/systemd/system`, so `set_class_command()`'s
+probe found it and printed `systemctl enable` on a machine with no `systemctl`.
+
+BlueZ reads both settings from `main.conf` `[General]` under any init. `Experimental = true`
+sets the same option `--experimental` does. `Class` sets the adapter's default major and
+minor class, but the `hostname` plugin rewrites the class from the chassis type
+`org.freedesktop.hostname1` reports, which is why it cannot stand in for the unit where
+hostnamed runs; the Computer / Laptop `0x7c010c` recorded on 2026-07-16 matches that. With no
+hostnamed the plugin has nothing to apply, so `main.conf` should hold across a restart.
+
+`systemd_booted()` picks the branch by testing `/run/systemd/system`, as `sd_booted()` does,
+rather than looking for `systemctl` on PATH. Without systemd the class step is a `sed` on
+`main.conf` plus `echo | sudo btmgmt --index hci0 class 4 8` for the running adapter, and
+the bearer step is a `sed` plus a restart through the machine's own service manager.
+
+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.
diff --git a/docs/HEADLESS.md b/docs/HEADLESS.md
index 0bb56a6..cdde0fb 100644
--- a/docs/HEADLESS.md
+++ b/docs/HEADLESS.md
@@ -45,6 +45,26 @@ already, holding the port this unit wants. Enabling the unit takes it over.
Once the unit is enabled, clients stop spawning their own and leave the daemon
to systemd.
+## Without systemd
+
+On Artix, Void, Devuan, or Gentoo with OpenRC there is no user unit to enable,
+and `tether service` says so. `tetherd` itself does not need systemd, but
+whatever starts it has to provide three things:
+
+- **Your user.** Never root: the keys and pairings live in your home directory.
+- **A runtime directory.** Clients find the daemon's socket in
+ `$XDG_RUNTIME_DIR/tether`, or `/run/user/<uid>/tether` when the variable is
+ unset, as it is for anything an init system starts. elogind, turnstile, and
+ pam_rundir create that directory at login and remove it at your last logout,
+ so check it survives a logout before relying on a daemon that outlives you.
+- **A session bus.** Messages and contacts (`obexd`), the secret store, and
+ notifications live on it. With no desktop session, start the daemon inside
+ one: `dbus-run-session tetherd`.
+
+On a desktop, start it from the compositor instead (`exec-once = tetherd` in
+Hyprland, `exec tetherd` in Sway), or do nothing: a client starts `tetherd`
+when none is running.
+
## Pair the iPhone
The daemon advertises itself over mDNS and the iOS app finds it. Both ends have
diff --git a/docs/man/man1/tether.1.in b/docs/man/man1/tether.1.in
index 6fdec91..8d8c5d0 100644
--- a/docs/man/man1/tether.1.in
+++ b/docs/man/man1/tether.1.in
@@ -85,7 +85,8 @@ packages install the unit themselves. See \fB\-\-bt-setup\fR.
\fB\-\-install-service\fR
Write \fBtetherd.service\fR into \fB~/.config/systemd/user\fR and print the
commands that enable it. Never enables or starts anything. Needed only for a
-portable build; the distro packages install the unit system\-wide.
+portable build; the distro packages install the unit system\-wide. Without
+systemd it writes nothing.
.TP
\fB\-\-uninstall-service\fR
Remove the \fBtetherd.service\fR unit this user installed.
diff --git a/src/cli/main.cpp b/src/cli/main.cpp
index b681941..60e2e1f 100644
--- a/src/cli/main.cpp
+++ b/src/cli/main.cpp
@@ -1189,7 +1189,7 @@ static int print_pending(tether::Client& client) {
// systemd is what runs the unit, so writing one where there is no systemd would
// leave a dead file and instructions that go nowhere.
static bool has_systemd() {
- if (!tether::which_program("systemctl").empty())
+ if (tether::systemd_booted())
return true;
fprintf(stdout,
_("No systemd on this machine, so there is no user service to manage. Start tetherd from "
diff --git a/src/core/include/tether/bluetooth/objects.hpp b/src/core/include/tether/bluetooth/objects.hpp
index 1817c74..b070212 100644
--- a/src/core/include/tether/bluetooth/objects.hpp
+++ b/src/core/include/tether/bluetooth/objects.hpp
@@ -218,6 +218,10 @@ namespace tether::bluetooth {
std::optional<bool> secure_connections = std::nullopt,
const std::string& preferred_id = {});
+ // Shell commands for the two setup steps, for a machine booted with or without systemd.
+ std::string enable_experimental_command(bool systemd);
+ std::string set_class_command(const std::string& adapter_id, bool systemd);
+
nlohmann::json to_json(const Adapter& adapter);
nlohmann::json to_json(const Device& device);
nlohmann::json to_json(const SetupStep& step);
diff --git a/src/core/include/tether/service.hpp b/src/core/include/tether/service.hpp
index e56cfb2..8d7e65c 100644
--- a/src/core/include/tether/service.hpp
+++ b/src/core/include/tether/service.hpp
@@ -12,6 +12,9 @@ namespace tether {
// Absolute path of a program on PATH, empty when it is not there.
std::string which_program(const std::string& name);
+ // Whether systemd is this machine's init, the check sd_booted() makes.
+ bool systemd_booted();
+
// ExecStart= line for the systemd unit: an absolute program and its
// arguments, pointed at the tetherd this build would start. systemd runs no
// shell, so this is never quoted for one.
diff --git a/src/core/src/bluetooth/objects.cpp b/src/core/src/bluetooth/objects.cpp
index 3c56dc8..89eaef2 100644
--- a/src/core/src/bluetooth/objects.cpp
+++ b/src/core/src/bluetooth/objects.cpp
@@ -1,6 +1,7 @@
#include "tether/bluetooth/objects.hpp"
#include <tether/i18n.hpp>
#include <tether/packaging.hpp>
+#include <tether/service.hpp>
#include <algorithm>
#include <cstdlib>
@@ -394,49 +395,67 @@ namespace tether::bluetooth {
return {};
}
- // bluetoothd's path is distro-specific, this command resolves it in the user's shell instead of hardcoding.
- std::string enable_experimental_command() {
- const std::string found = bluetoothd_path();
- const std::string binary = found.empty()
- ? "$(ls /usr/lib/bluetooth/bluetoothd /usr/libexec/bluetooth/bluetoothd "
- "2>/dev/null | head -1)"
- : found;
-
- return "sudo mkdir -p /etc/systemd/system/bluetooth.service.d\n"
- "printf '[Service]\\nExecStart=\\nExecStart=%s --experimental\\n' \\\n"
- " \"" +
- binary +
- "\" \\\n"
- " | sudo tee /etc/systemd/system/bluetooth.service.d/experimental.conf\n"
- "sudo systemctl daemon-reload && sudo systemctl restart bluetooth";
- }
-
- // Distro packages install the unit. A portable build writes it out.
- std::string set_class_command(const std::string& adapter_id) {
- const std::string enable = "sudo systemctl enable --now tether-btclass@" + adapter_id;
- std::error_code ec;
- for (const char* dir : {"/etc/systemd/system",
- "/usr/lib/systemd/system",
- "/lib/systemd/system",
- "/usr/local/lib/systemd/system"}) {
- if (std::filesystem::exists(std::string(dir) + "/[email protected]", ec))
- return enable;
- }
+ } // namespace
- // The AppImage can write the unit itself, which beats pasting it. Flatpak cannot:
- // "flatpak run" under sudo is the wrong user, so it falls through to the here-document.
- if (const char* appimage = std::getenv("APPIMAGE"); appimage && *appimage)
- return "sudo \"" + std::string(appimage) +
- "\" --install-btclass-unit\n"
- "sudo systemctl daemon-reload\n" +
- enable;
-
- return "sudo tee /etc/systemd/system/[email protected] >/dev/null <<'EOF'\n" +
- std::string(packaging::BTCLASS_UNIT) +
- "EOF\n"
+ // bluetoothd's path is distro-specific, this command resolves it in the user's shell instead of hardcoding.
+ std::string enable_experimental_command(bool systemd) {
+ // main.conf's Experimental is the same switch as --experimental, and no init system is involved.
+ if (!systemd)
+ return "sudo sed -i -E 's/^#?[[:space:]]*Experimental[[:space:]]*=.*/Experimental = true/' "
+ "/etc/bluetooth/main.conf\n"
+ "# then restart bluetoothd with this system's service manager";
+
+ const std::string found = bluetoothd_path();
+ const std::string binary = found.empty()
+ ? "$(ls /usr/lib/bluetooth/bluetoothd /usr/libexec/bluetooth/bluetoothd "
+ "2>/dev/null | head -1)"
+ : found;
+
+ return "sudo mkdir -p /etc/systemd/system/bluetooth.service.d\n"
+ "printf '[Service]\\nExecStart=\\nExecStart=%s --experimental\\n' \\\n"
+ " \"" +
+ binary +
+ "\" \\\n"
+ " | sudo tee /etc/systemd/system/bluetooth.service.d/experimental.conf\n"
+ "sudo systemctl daemon-reload && sudo systemctl restart bluetooth";
+ }
+
+ // Distro packages install the unit. A portable build writes it out.
+ std::string set_class_command(const std::string& adapter_id, bool systemd) {
+ // Without hostnamed, BlueZ's hostname plugin leaves main.conf's Class alone across restarts.
+ // Checked before the unit probe: an Arch package on Artix still ships the unit file.
+ if (!systemd)
+ return "sudo sed -i -E 's/^#?[[:space:]]*Class[[:space:]]*=.*/Class = 0x000408/' "
+ "/etc/bluetooth/main.conf\n"
+ "echo | sudo btmgmt --index " +
+ adapter_id + " class 4 8";
+
+ const std::string enable = "sudo systemctl enable --now tether-btclass@" + adapter_id;
+ std::error_code ec;
+ for (const char* dir : {"/etc/systemd/system",
+ "/usr/lib/systemd/system",
+ "/lib/systemd/system",
+ "/usr/local/lib/systemd/system"}) {
+ if (std::filesystem::exists(std::string(dir) + "/[email protected]", ec))
+ return enable;
+ }
+
+ // The AppImage can write the unit itself, which beats pasting it. Flatpak cannot:
+ // "flatpak run" under sudo is the wrong user, so it falls through to the here-document.
+ if (const char* appimage = std::getenv("APPIMAGE"); appimage && *appimage)
+ return "sudo \"" + std::string(appimage) +
+ "\" --install-btclass-unit\n"
"sudo systemctl daemon-reload\n" +
enable;
- }
+
+ return "sudo tee /etc/systemd/system/[email protected] >/dev/null <<'EOF'\n" +
+ std::string(packaging::BTCLASS_UNIT) +
+ "EOF\n"
+ "sudo systemctl daemon-reload\n" +
+ enable;
+ }
+
+ namespace {
// /org/bluez/hci0 -> hci0
std::string adapter_id_of(const std::string& path) {
@@ -532,7 +551,7 @@ namespace tether::bluetooth {
cap.setup.push_back({_("Notification mirroring needs BlueZ's experimental bearer API "
"(org.bluez.Bearer.LE1), which bluetoothd is not exposing. Set this up before "
"pairing: a bond made without it has no LE half."),
- enable_experimental_command()});
+ enable_experimental_command(systemd_booted())});
cap.mode = DeliveryMode::Compatibility;
} else if (cap.bearer_api == BearerApi::Unknown && !cap.bonded_device_present) {
// only an iphone bond can confirm the api
@@ -559,7 +578,7 @@ namespace tether::bluetooth {
if (!cap.class_ok) {
cap.setup.push_back({_("The iPhone will not offer its Messages and Contacts permissions until this "
"adapter presents itself as A/V Hands-Free (major 4, minor 8)."),
- set_class_command(cap.adapter_id)});
+ set_class_command(cap.adapter_id, systemd_booted())});
}
return cap;
diff --git a/src/core/src/client.cpp b/src/core/src/client.cpp
index f524dfd..da1d640 100644
--- a/src/core/src/client.cpp
+++ b/src/core/src/client.cpp
@@ -123,7 +123,14 @@ namespace tether {
sockaddr_un addr{};
addr.sun_family = AF_UNIX;
- std::string path = tether::get_runtime_dir() + "/tetherd.sock";
+ std::string path;
+ try {
+ path = tether::get_runtime_dir() + "/tetherd.sock";
+ } catch (const std::exception& e) {
+ debug::log(ERR, "{}", e.what());
+ close(sock);
+ return -1;
+ }
if (path.size() >= sizeof(addr.sun_path)) {
debug::log(ERR, "Socket path too long: {}", path);
close(sock);
diff --git a/src/core/src/net.cpp b/src/core/src/net.cpp
index f31573c..137dc0c 100644
--- a/src/core/src/net.cpp
+++ b/src/core/src/net.cpp
@@ -777,11 +777,18 @@ namespace tether {
}
std::string get_runtime_dir() {
- const char* xdg_runtime = std::getenv("XDG_RUNTIME_DIR");
- if (!xdg_runtime) {
- throw std::runtime_error("XDG_RUNTIME_DIR is not set");
- }
- std::filesystem::path tether_dir = std::filesystem::path(xdg_runtime) / "tether";
+ std::filesystem::path base;
+ if (const char* xdg_runtime = std::getenv("XDG_RUNTIME_DIR")) {
+ base = xdg_runtime;
+ } else {
+ // login managers create this, but only a login session exports the variable.
+ const std::string fallback = "/run/user/" + std::to_string(getuid());
+ struct stat st{};
+ if (lstat(fallback.c_str(), &st) != 0 || !S_ISDIR(st.st_mode) || st.st_uid != getuid())
+ throw std::runtime_error("XDG_RUNTIME_DIR is not set");
+ base = fallback;
+ }
+ std::filesystem::path tether_dir = base / "tether";
if (!std::filesystem::exists(tether_dir)) {
std::filesystem::create_directories(tether_dir);
std::filesystem::permissions(
diff --git a/src/core/src/service.cpp b/src/core/src/service.cpp
index 60e4695..84416a2 100644
--- a/src/core/src/service.cpp
+++ b/src/core/src/service.cpp
@@ -81,6 +81,14 @@ namespace tether {
return {};
}
+ bool systemd_booted() {
+ // Flatpak sandbox hides the host's /run, so its host is assumed to run systemd
+ if (!flatpak_app_id().empty())
+ return true;
+ std::error_code ec;
+ return fs::is_directory("/run/systemd/system", ec);
+ }
+
std::string tetherd_exec_command() {
if (const char* appimage = std::getenv("APPIMAGE"); appimage && *appimage)
return std::string(appimage) + " --daemon";
diff --git a/src/gtk/daemon_client.cpp b/src/gtk/daemon_client.cpp
index 0a41474..3aac5bb 100644
--- a/src/gtk/daemon_client.cpp
+++ b/src/gtk/daemon_client.cpp
@@ -121,7 +121,14 @@ namespace tether::ui {
sockaddr_un addr{};
addr.sun_family = AF_UNIX;
- std::string path = tether::get_runtime_dir() + "/tetherd.sock";
+ std::string path;
+ try {
+ path = tether::get_runtime_dir() + "/tetherd.sock";
+ } catch (const std::exception&) {
+ close(fd);
+ schedule_event_retry();
+ return G_SOURCE_REMOVE;
+ }
std::strncpy(addr.sun_path, path.c_str(), sizeof(addr.sun_path) - 1);
if (::connect(fd, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)) < 0) {
diff --git a/test/test_bluetooth_objects.cpp b/test/test_bluetooth_objects.cpp
index 608df38..6facff4 100644
--- a/test/test_bluetooth_objects.cpp
+++ b/test/test_bluetooth_objects.cpp
@@ -1,6 +1,7 @@
#include <gtest/gtest.h>
#include <tether/bluetooth/objects.hpp>
#include <tether/packaging.hpp>
+#include <tether/service.hpp>
#include <sstream>
#include <string_view>
@@ -603,22 +604,40 @@ TEST(Capability, WrongClassIsReportedButDoesNotDowngradeMode) {
// The unit is templated on the adapter, so the wrong id makes the command a no-op.
EXPECT_EQ(cap.adapter_id, "hci0");
ASSERT_EQ(cap.setup.size(), 1u);
- EXPECT_TRUE(cap.setup[0].command.ends_with("sudo systemctl enable --now tether-btclass@hci0"))
- << cap.setup[0].command;
+ EXPECT_EQ(cap.setup[0].command, set_class_command("hci0", tether::systemd_booted()));
+}
+
+TEST(Capability, ClassCommandWithSystemdEnablesTheUnit) {
+ const std::string command = set_class_command("hci0", true);
+ EXPECT_TRUE(command.ends_with("sudo systemctl enable --now tether-btclass@hci0")) << command;
// The portable-build branch pastes the unit through a here-document, and a here-document
// delimiter only ends it at column 0. That is why the unit text has to end in a newline:
// without it EOF lands on the last line of the unit and closes nothing.
EXPECT_TRUE(std::string_view(tether::packaging::BTCLASS_UNIT).ends_with("\n"));
- if (cap.setup[0].command.find("<<'EOF'") != std::string::npos) {
+ if (command.find("<<'EOF'") != std::string::npos) {
bool terminated = false;
- std::istringstream lines(cap.setup[0].command);
+ std::istringstream lines(command);
for (std::string line; std::getline(lines, line);)
terminated = terminated || line == "EOF";
- EXPECT_TRUE(terminated) << cap.setup[0].command;
+ EXPECT_TRUE(terminated) << command;
}
}
+// No unit runs without systemd, even where a package left the file on disk.
+TEST(Capability, ClassCommandWithoutSystemdEditsMainConf) {
+ const std::string command = set_class_command("hci0", false);
+ EXPECT_NE(command.find("Class = 0x000408"), std::string::npos) << command;
+ EXPECT_NE(command.find("echo | sudo btmgmt --index hci0 class 4 8"), std::string::npos) << command;
+ EXPECT_EQ(command.find("systemctl"), std::string::npos) << command;
+}
+
+TEST(Capability, ExperimentalCommandWithoutSystemdEditsMainConf) {
+ const std::string command = enable_experimental_command(false);
+ EXPECT_NE(command.find("Experimental = true"), std::string::npos) << command;
+ EXPECT_EQ(command.find("systemd"), std::string::npos) << command;
+}
+
TEST(Capability, PrefersAPoweredAdapter) {
Payload p(R"({
'/org/bluez/hci0': {
diff --git a/test/test_net.cpp b/test/test_net.cpp
index cbf8be5..414c510 100644
--- a/test/test_net.cpp
+++ b/test/test_net.cpp
@@ -19,6 +19,7 @@
#include <sstream>
#include <sys/file.h>
#include <sys/socket.h>
+#include <sys/stat.h>
#include <sys/wait.h>
#include <thread>
#include <unistd.h>
@@ -91,6 +92,17 @@ namespace {
pid_t pid_;
};
+ // A daemon an init system starts has no XDG_RUNTIME_DIR, yet has to share a socket with login shells.
+ TEST(RuntimeDirTest, FallsBackToRunUserWhenXdgRuntimeDirIsUnset) {
+ ScopedEnvVar unset("XDG_RUNTIME_DIR", "");
+ const std::string run_user = "/run/user/" + std::to_string(getuid());
+ struct stat st{};
+ if (lstat(run_user.c_str(), &st) == 0 && S_ISDIR(st.st_mode) && st.st_uid == getuid())
+ EXPECT_EQ(tether::get_runtime_dir(), run_user + "/tether");
+ else
+ EXPECT_THROW(tether::get_runtime_dir(), std::runtime_error);
+ }
+
// The single-instance lock fd is deliberately leaked so the OS holds it for the
// process lifetime. Without O_CLOEXEC any helper the daemon exec's (btmgmt, the
// pair dialog) inherits it and keeps the lock alive after the daemon is gone,