Skip to content

Commit e446c17

Browse files
committed
docs: document --x11 and the enable_x11 key
Follow the flag rename, drop the claim that --hw-access mounts the X11 socket, and fix the stale desktop path (/proc/1/root was never used, the bridge reads /.old_root). The systemd ExecCondition examples now grep enable_x11=1, which is what the running container's config snapshot holds. Signed-off-by: ravindu644 <droidcasts@protonmail.com>
1 parent a884275 commit e446c17

6 files changed

Lines changed: 18 additions & 18 deletions

File tree

‎Documentation/Features.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -183,13 +183,13 @@ No manual `groupadd`/`usermod` inside the container is needed.
183183

184184
### X11 socket mounting
185185

186-
For GUI applications, Droidspaces bind-mounts the X11 socket directory automatically:
186+
For GUI applications, Droidspaces bind-mounts the host X11 socket when `--x11` is set:
187187

188188
- **Android (Termux X11):** Detects and mounts `/data/data/com.termux/files/usr/tmp/.X11-unix`
189-
- **Desktop Linux:** Mounts `/tmp/.X11-unix` via `/proc/1/root/tmp/.X11-unix`
189+
- **Desktop Linux:** Mounts the host `/tmp/.X11-unix/X0` into the container
190190

191191
> [!TIP]
192-
> X11 support can be enabled on its own with the `--termux-x11` (`-X`) flag. This is the recommended way to run GUI applications on Android if you do not need full GPU/hardware access, because the container stays more isolated.
192+
> X11 support is enabled with the `--x11` (`-X`) flag and does not need `--hw-access`. This is the recommended way to run GUI applications if you do not need full GPU/hardware access, because the container stays more isolated.
193193
194194
Droidspaces injects `DISPLAY=:5` and (if VirGL is enabled) `GALLIUM_DRIVER=virpipe` into the container environment through `/run/droidspaces.env`, which is symlinked from `/etc/profile.d/droidspaces_env.sh`. Shells like `bash` and `sh` source it automatically. If you use `zsh`, `fish`, or another non-login shell, source it yourself: `source /run/droidspaces.env`.
195195

‎Documentation/Graphics-and-Audio.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ After=graphical.target
238238
[Service]
239239
Type=simple
240240
User=root
241-
ExecCondition=/bin/sh -c "grep -q 'enable_termux_x11=1' /run/droidspaces/container.config"
241+
ExecCondition=/bin/sh -c "grep -q 'enable_x11=1' /run/droidspaces/container.config"
242242
ExecCondition=/bin/sh -c "test -S /tmp/.X11-unix/X5"
243243
ExecStart=/usr/local/bin/xfce-start
244244
Restart=on-failure
@@ -348,7 +348,7 @@ After=graphical.target
348348

349349
[Service]
350350
Type=simple
351-
ExecCondition=/bin/sh -c "grep -q 'enable_termux_x11=1' /run/droidspaces/container.config"
351+
ExecCondition=/bin/sh -c "grep -q 'enable_x11=1' /run/droidspaces/container.config"
352352
ExecCondition=/bin/sh -c "test -S /tmp/.X11-unix/X5"
353353
ExecStart=/usr/local/bin/de-start
354354
Restart=on-failure

‎Documentation/Linux-CLI.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -136,11 +136,11 @@ Hand a container's LAN to another running container (for example OpenWRT), which
136136
|--------|-------|-------------|
137137
| `--foreground` | `-f` | Attach to the container console on start to see init logs. |
138138
| `--volatile` | `-V` | Ephemeral mode. Changes live in RAM and are lost on exit. |
139-
| `--hw-access` | `-H` | Expose host hardware (GPU, USB, etc.). Auto-detects GPU group IDs and creates matching groups inside the container. Mounts X11 socket for GUI apps (Termux X11 on Android, `/tmp/.X11-unix` on Linux). See [Safety Warning](Features.md#hardware-access-mode). |
139+
| `--hw-access` | `-H` | Expose host hardware (GPU, USB, etc.). Auto-detects GPU group IDs and creates matching groups inside the container. See [Safety Warning](Features.md#hardware-access-mode). |
140140
| `--gpu` | | Enable GPU acceleration only. Scans the host `/dev` for known GPU nodes and maps only those into the container, without exposing other host hardware. Ignored if `-H` is passed. |
141141
| `--allow-vts` | | With `--hw-access`, leave the host's virtual terminals (`/dev/tty1`-`tty6`) visible. By default they are masked with `/dev/null` so a systemd container's `getty` does not take over the host console. No effect without `-H`. |
142142
| `--allow-sandboxing` | | Let unprivileged Docker, Podman, Flatpak, bwrap and browser sandboxes run inside the container. Weakens isolation. See [Sandboxing](Features.md#sandboxing). |
143-
| `--termux-x11`| `-X` | Mount X11 socket for Termux-X11 display (Android only). |
143+
| `--x11`| `-X` | Bridge the host X11 socket into the container. Launches Termux:X11 on Android. |
144144
| `--enable-android-storage`| | Mount `/storage/emulated/0` (Android only). |
145145
| `--selinux-permissive` | | Set host SELinux to permissive for the container session. |
146146
| `--force-cgroupv1` | | Force the legacy cgroup v1 hierarchy. Required if the host kernel has a broken or partial cgroup v2 implementation (common on older Android 4.x kernels). |
@@ -216,8 +216,8 @@ enable_hw_access=0
216216
# Auto-detect and securely map GPU nodes without full hardware access
217217
enable_gpu_mode=0
218218

219-
# Android: Setup Termux X11 socket
220-
enable_termux_x11=0
219+
# Bridge the host X11 socket (Termux:X11 on Android)
220+
enable_x11=0
221221

222222
# Android: Setup Android internal shared storage mount
223223
enable_android_storage=0

‎Documentation/zh-CN/Features.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -183,13 +183,13 @@ droidspaces --name=gpu-test --rootfs=/path/to/rootfs --hw-access start
183183

184184
### X11 套接字挂载
185185

186-
为支持 GUI 应用程序,Droidspaces 自动 bind mount X11 套接字目录:
186+
为支持 GUI 应用程序,Droidspaces 在设置 `--x11` 时 bind mount 主机 X11 套接字:
187187

188188
- **Android (Termux X11):** 检测并挂载 `/data/data/com.termux/files/usr/tmp/.X11-unix`
189-
- **桌面 Linux:** 通过 `/proc/1/root/tmp/.X11-unix` 挂载 `/tmp/.X11-unix`
189+
- **桌面 Linux:** 将主机的 `/tmp/.X11-unix/X0` 挂载到容器中
190190

191191
> [!TIP]
192-
> X11 支持可以使用 `--termux-x11` (`-X`) 标志独立启用。如果您不需要完整的 GPU/硬件访问权限,这是在 Android 上使用 GUI 应用程序的推荐方式,因为它保留了更高级别的隔离性。
192+
> X11 支持通过 `--x11` (`-X`) 标志启用,无需 `--hw-access`。如果您不需要完整的 GPU/硬件访问权限,这是使用 GUI 应用程序的推荐方式,因为它保留了更高级别的隔离性。
193193
194194

195195
Droidspaces 会通过 `/run/droidspaces.env`(从 `/etc/profile.d/droidspaces_env.sh` 符号链接)自动将 `DISPLAY=:5` 以及(启用 VirGL 时)`GALLIUM_DRIVER=virpipe` 注入到容器环境中。`bash` 和 `sh` 会自动读取此文件。如果您使用 `zsh`、`fish` 或其他非登录 shell,请手动执行:`source /run/droidspaces.env`。

‎Documentation/zh-CN/Graphics-and-Audio.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,7 @@ After=graphical.target
239239
[Service]
240240
Type=simple
241241
User=root
242-
ExecCondition=/bin/sh -c "grep -q 'enable_termux_x11=1' /run/droidspaces/container.config"
242+
ExecCondition=/bin/sh -c "grep -q 'enable_x11=1' /run/droidspaces/container.config"
243243
ExecCondition=/bin/sh -c "test -S /tmp/.X11-unix/X5"
244244
ExecStart=/usr/local/bin/xfce-start
245245
Restart=on-failure
@@ -349,7 +349,7 @@ After=graphical.target
349349

350350
[Service]
351351
Type=simple
352-
ExecCondition=/bin/sh -c "grep -q 'enable_termux_x11=1' /run/droidspaces/container.config"
352+
ExecCondition=/bin/sh -c "grep -q 'enable_x11=1' /run/droidspaces/container.config"
353353
ExecCondition=/bin/sh -c "test -S /tmp/.X11-unix/X5"
354354
ExecStart=/usr/local/bin/de-start
355355
Restart=on-failure

‎Documentation/zh-CN/Linux-CLI.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -133,11 +133,11 @@ sudo droidspaces --name=web,db,app stop
133133
|--------|------|-------------|
134134
| `--foreground` | `-f` | 启动时附加到容器控制台以查看 init 日志。 |
135135
| `--volatile` | `-V` | 临时模式。更改存储在 RAM 中,退出后丢失。 |
136-
| `--hw-access` | `-H` | 暴露主机硬件(GPU、USB 等)。自动检测 GPU 组 ID 并在容器内创建匹配的组。挂载 X11 socket 以支持 GUI 应用(Android 上为 Termux X11,Linux 上为 `/tmp/.X11-unix`)。参见[安全警告](./Features.md#hardware-access-mode)。 |
136+
| `--hw-access` | `-H` | 暴露主机硬件(GPU、USB 等)。自动检测 GPU 组 ID 并在容器内创建匹配的组。参见[安全警告](./Features.md#hardware-access-mode)。 |
137137
| `--gpu` | | 仅启用 GPU 加速。扫描主机 `/dev` 中的已知 GPU 节点,并仅将其安全映射到容器中,不暴露其他主机硬件。(若已传入 `-H`,此选项将被忽略)。 |
138138
| `--allow-vts` | | 与 `--hw-access` 一起使用时,保留主机虚拟终端(`/dev/tty1`-`tty6`)可见。默认情况下它们会被 `/dev/null` 遮蔽,以免 systemd 容器的 `getty` 接管主机控制台。没有 `-H` 时无效。 |
139139
| `--allow-sandboxing` | | 允许非特权 Docker、Podman、Flatpak、bwrap 以及浏览器沙箱在容器内运行。会削弱隔离性。参见[沙箱支持](./Features.md#sandboxing) |
140-
| `--termux-x11`| `-X` | 挂载 X11 socket 以支持 Termux-X11 显示(仅限 Android)。 |
140+
| `--x11`| `-X` | 将主机 X11 socket 桥接到容器中。在 Android 上会启动 Termux:X11。 |
141141
| `--enable-android-storage`| | 挂载 `/storage/emulated/0`(仅限 Android)。 |
142142
| `--selinux-permissive` | | 在容器会话期间将主机 SELinux 设置为宽容模式。 |
143143
| `--force-cgroupv1` | | 强制使用旧版 Cgroup V1 层级。若主机内核存在损坏或不完整的 Cgroups V2 实现(常见于旧版 Android 4.x 内核),则需要此选项。 |
@@ -202,8 +202,8 @@ enable_hw_access=0
202202
# 自动检测并安全映射 GPU 节点,无需完整硬件访问权限
203203
enable_gpu_mode=0
204204

205-
# Android:设置 Termux X11 socket
206-
enable_termux_x11=0
205+
# 桥接主机 X11 socket(Android 上为 Termux:X11)
206+
enable_x11=0
207207

208208
# Android:设置 Android 内部共享存储挂载
209209
enable_android_storage=0

0 commit comments

Comments
 (0)