Add install.sh, uninstall.sh and README
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>
This commit is contained in:
Jaroslav Beneš
@@ -1,2 +1,120 @@
|
||||
# Plasma-Addon-Synology-NAS
|
||||
# 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).
|
||||
|
||||
Reference in New Issue
Block a user