Jaroslav Beneš
e6eae24a7f
Distro-agnostic installer (dep check, sudo helper+policy install, per-user kpackagetool6 install/upgrade) and matching uninstaller; full public README covering requirements, usage, architecture and security notes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
121 lines
5.1 KiB
Markdown
121 lines
5.1 KiB
Markdown
# Synology NAS — KDE Plasma 6 widget
|
|
|
|
A system-tray widget for **KDE Plasma 6** that lets you browse and mount your
|
|
**Synology** (or any **SMB/CIFS**) network shares the same way Plasma Vaults
|
|
handles encrypted vaults: click the tray icon, and a popup lists each configured
|
|
host with its shares — mount or unmount any of them with one click.
|
|
|
|
- Add **multiple** NAS / SMB hosts.
|
|
- Auto-discovers each host's shared folders with `smbclient`.
|
|
- Mounts real **kernel CIFS** mounts (visible to every app, not just Dolphin).
|
|
- Passwords are kept in **KWallet**, never in plain config.
|
|
- Privileged mounting is done through a tiny **polkit**-authorized helper — no
|
|
passwordless-sudo hacks, no editing `/etc/fstab`.
|
|
|
|
> Works with any SMB server. "Synology" is just the friendly name — point it at
|
|
> a Synology DSM, a Samba box, a Windows share, a TrueNAS, whatever speaks SMB.
|
|
|
|
## Requirements
|
|
|
|
Install these with your distribution's package manager:
|
|
|
|
| Tool | Provided by (Arch) | Purpose |
|
|
|------------------|------------------------|----------------------------------|
|
|
| `kpackagetool6` | `plasma-workspace` | install the widget |
|
|
| `mount.cifs` | `cifs-utils` | mount CIFS shares |
|
|
| `smbclient` | `smbclient` | list shares on a host |
|
|
| `pkexec` | `polkit` | authorize the mount helper |
|
|
| `kwallet-query` | `kwallet` (KF6) | store/read passwords in KWallet |
|
|
| `findmnt` | `util-linux` | detect mounted shares |
|
|
|
|
On Debian/Ubuntu the equivalents are `plasma-workspace`, `cifs-utils`,
|
|
`smbclient`, `policykit-1`, `kwallet-bin`/`kf6-kwallet`, `util-linux`.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
git clone https://git.houmeres.sk/Houmeres/Plasma-Addon-Synology-NAS.git
|
|
cd Plasma-Addon-Synology-NAS
|
|
./install.sh
|
|
```
|
|
|
|
`install.sh` copies the helper to `/usr/lib/synology-nas/helper` and the polkit
|
|
policy to `/usr/share/polkit-1/actions/` (via `sudo`), then installs the widget
|
|
for your user with `kpackagetool6`. Re-run it any time to upgrade.
|
|
|
|
Then add **Synology NAS** to your panel or system tray (right-click →
|
|
*Add Widgets…*), or try it standalone:
|
|
|
|
```sh
|
|
plasmawindowed sk.houmeres.synologynas
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Open the widget's settings (right-click → *Configure…*).
|
|
2. Under **NAS Hosts**, add a host: display name, host/IP, username, password
|
|
(saved to KWallet), and optionally a domain, a mount-folder override, or an
|
|
SMB-version override.
|
|
3. Under **General**, optionally set the default mount folder (defaults to
|
|
`~/NAS`), SMB version, extra mount options and permission modes.
|
|
4. Click the tray icon → **Refresh**. Each host's shares appear; click a share
|
|
to **Mount** it (you'll get a polkit prompt) or **Unmount** it. Use the row's
|
|
menu to open a mounted share in your file manager.
|
|
|
|
Shares mount under `<mount folder>/<host>/<share>` (e.g.
|
|
`~/NAS/HomeNAS/photos`).
|
|
|
|
## How it works
|
|
|
|
```
|
|
Plasmoid (QML) Privileged helper (root, via pkexec)
|
|
───────────── ────────────────────────────────────
|
|
smbclient -L ── list shares mount.cifs //host/share <mountpoint>
|
|
kwallet-query ── read password -o credentials=…,uid=…,forceuid,…
|
|
│ umount <mountpoint>
|
|
▼
|
|
write 0600 cred file in polkit action:
|
|
$XDG_RUNTIME_DIR ───────────► sk.houmeres.synologynas.manage
|
|
│ (auth_admin_keep)
|
|
└── pkexec helper mount …
|
|
```
|
|
|
|
The QML never runs privileged operations directly. It builds a `0600`
|
|
credentials file in your `$XDG_RUNTIME_DIR` (reading the password straight from
|
|
KWallet, so it never lands in QML, argv or `ps`) and calls the helper through
|
|
`pkexec`. The helper treats every argument as hostile: the mount point must
|
|
resolve inside your `$HOME` or `/run/media/<you>`, the source must be
|
|
`//host/share`, and the credentials file must be your own `0600` file under your
|
|
runtime dir.
|
|
|
|
## Security notes
|
|
|
|
- **Passwords** live in KWallet (folder *Synology NAS*). They are copied into a
|
|
transient `0600` credentials file only for the moment of mounting, then
|
|
removed.
|
|
- The **one** place a password briefly touches process arguments is when you
|
|
first *save* it in the config page (`kwallet-query -w`), because the CLI has no
|
|
other input channel here. The window is milliseconds and visible only to your
|
|
own user (and root). Everything afterward reads from KWallet.
|
|
- The privileged helper is intentionally tiny and does **no** recursive
|
|
deletion — on unmount it only `rmdir`s the now-empty mount/host directories.
|
|
|
|
## Uninstall
|
|
|
|
```sh
|
|
./uninstall.sh
|
|
```
|
|
|
|
Mounted shares stay mounted (unmount them first) and KWallet passwords remain —
|
|
remove them with `kwalletmanager` if desired.
|
|
|
|
## Limitations / roadmap
|
|
|
|
- No mount-at-login persistence yet (planned; the config schema already leaves
|
|
room for it).
|
|
- Share discovery is via `smbclient -L` only (no Synology DSM API).
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|