60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# Portctl
|
||
|
||
A simple and minimal plugin to inspect and terminate listening TCP/UDP ports from the bar.
|
||
|
||
## Plugin
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| ID | `rxtsel/portctl` |
|
||
| Entries | Bar widget: `indicator`; panel: `panel`; service: `scanner` |
|
||
|
||
## Requirements
|
||
|
||
Install `ss` from `iproute2` on `PATH`. Available on all major Linux distributions; install the `iproute2` package if missing.
|
||
|
||
## Usage
|
||
|
||
Add the `indicator` widget to a bar. It shows a plug icon with the count of active listening ports. The widget is hidden when no ports are detected. Click it to open the port panel.
|
||
|
||
Open the panel directly with:
|
||
|
||
```sh
|
||
noctalia msg panel-toggle rxtsel/portctl:panel
|
||
```
|
||
|
||
The panel lists listening ports grouped by category (Development, Databases, Containers, Servers, Cloud, Other). From there you can:
|
||
|
||
- Search by port number, process name, or PID.
|
||
- Toggle TCP and UDP visibility independently with the header toggles.
|
||
- Click any PID label to copy the PID to the clipboard.
|
||
- Kill a process: click `×` to stage the kill, then confirm with `Kill` in the inline confirmation row. The row transforms in place — no dialog opens.
|
||
|
||
To customize the bar icon, right-click the widget → settings → **Glyph**.
|
||
|
||
## Settings
|
||
|
||
| Setting | Type | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `refresh_interval` | `int` | `5` | Seconds between automatic port scans (1–60). |
|
||
| `ignore_list` | `string` | *(empty)* | Comma-separated process name substrings to hide (e.g. `discord,chrome,steam`). |
|
||
| `ignore_ports` | `string` | *(empty)* | Comma-separated port numbers to hide (e.g. `37700,6463`). |
|
||
| `hide_system_ports` | `bool` | `true` | Hide ports below 1024 (privileged/root ports). |
|
||
| `hide_unknown_ports` | `bool` | `false` | Hide ports whose process info is inaccessible (root-owned processes, rootlessport, etc.). |
|
||
|
||
Widget settings (right-click widget → settings):
|
||
|
||
| Setting | Type | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `glyph` | `glyph` | `plug` | Icon shown in the bar. |
|
||
|
||
## Notes
|
||
|
||
**Root-owned ports** — ports owned by root-level processes show `—` as the PID and cannot be killed from the plugin (no privilege escalation is performed). Enable `hide_unknown_ports` to exclude them from the list.
|
||
|
||
**Container ports with pasta networking** — ports forwarded via `pasta` (the default network backend in Podman 4+) do not create a host-side socket and are not visible to `ss`. They will not appear in portctl. Ports forwarded via `rootlessport` (older Podman, or explicit `--network slirp4netns`) do appear, categorized under Containers.
|
||
|
||
**`rootlessport` entries** — expected behavior when running Podman or Docker in rootless mode with published ports (`-p`). Add `rootlessport` to `ignore_list` or the specific port number to `ignore_ports` to suppress them.
|
||
|
||
**Processes spawned** — `ss -ltnp` and `ss -lunp` on every scan. No network calls. No filesystem writes outside `noctalia.pluginDataDir()`.
|