lsoff README

The project's README from github.com/yutat23/lsoff. As one markdown file: README.md.

lsoff

English | 日本語

image

CLI / TUI that lists listening TCP/UDP ports on Windows, Linux, and macOS.

Think of it as a port-focused lsof: quickly see who is holding a port, then kill the process if you need to.

Install

Binaries are attached to GitHub Releases (lsoff-darwin-arm64, lsoff-linux-amd64, lsoff-windows-amd64.exe, …).

Windows (WinGet)

winget install yutat23.lsoff

macOS / Linux (Homebrew)

Install it from the Homebrew tap. Homebrew 6 requires trusting a third-party tap first:

brew tap yutat23/tap
brew trust yutat23/tap
brew install lsoff

Go install

go install github.com/yutat23/lsoff@latest

Build from source

git clone https://github.com/yutat23/lsoff
cd lsoff
go build -o lsoff .

A tagged push (git tag v0.1.0 && git push origin v0.1.0) builds those binaries and publishes the release.

macOS uses libproc, so CGO is required (enabled by a normal go build).

Usage

lsoff                 # TUI (prints a table if stdout is not a TTY)
lsoff 8080            # show processes holding port 8080
lsoff nginx           # search by name, path, PID, cmdline, project, service…
lsoff -q "node 8080"  # space-separated words are AND
lsoff -t              # TCP only (TUI)
lsoff -p              # hide rows with an unknown PID
lsoff -u 53           # UDP port 53
lsoff --json nginx    # search results as JSON
lsoff -k 8080         # kill those processes (with confirmation)
lsoff -k -y 8080      # skip confirmation (required when piped)
lsoff -h
lsoff -v

Example output for a port query:

PROTO  PORT  ADDRESS      PID    PROJECT  PROCESS  PATH                 CMD                   CWD
tcp    8080  127.0.0.1    41233  lsoff    node     /usr/local/bin/node  /usr/local/bin/node   ~/mywork/lsoff

TUI

Key / action What it does
/ / click Search: / ctrl+f Search (port, PID, name, project, path, cmdline; spaces are AND)
↑ / ↓ / j / k / click / wheel Move and select (works while searching too)
ctrl+u / ctrl+d Move one page up / down (works while searching too)
Click a header Sort by that column (click again for descending)
s / S Cycle sort column / toggle ascending-descending
p Hide rows with an unknown PID (toggle)
4 Show IPv4 rows only (press again to clear)
6 Show IPv6 rows only (press again to clear)
y Copy the selected addr:port
a Auto-refresh every 2 seconds (toggle)
enter / space / click ▸ Expand or collapse sockets within a group
h / l Collapse / expand
esc / ctrl+c Clear the search
r Reload the list now
x Kill the selected process (asks first)
q Quit

In the TUI, tcp is green and udp is amber. The selected row uses the highlight background instead. The CLI table stays uncolored so it stays script-friendly. Process names, command lines, and paths are sanitized for the terminal (control characters and ANSI/OSC sequences). JSON keeps the original strings.

Multiple bindings for the same logical process or Docker container endpoint (same protocol and port, such as an IPv4 + IPv6 pair) start collapsed as one row with ▸ and a +N count. enter expands them into a small tree: the head shows ▾, the last child is drawn with └─, and every child before it with ├─. So a pair of sockets shows a single └─ child, and three or more chain as ├─, … , └─. Different ports and protocols remain separate groups; Docker groups use the container identity rather than a PID.

The 4 and 6 filters are mutually exclusive. Press the other key to switch families, or press the same key again to show both.

Known service names (http, postgres, redis, vite, …) are searchable and shown on the SVC footer line. Ambiguous ports such as 3000 are aliases-only and have no single display name. Historic ports (echo, chargen) are not included. JSON may include "service" when a display name exists.

After x, press y to confirm, or n / esc to cancel. Kill verifies that the process is still the same one that was listed: Linux uses pidfd_open (the fd refers to that process, not the PID number), macOS checks pbi_start_tvsec/usec then signals, and Windows checks CreationTime on an open process handle. On Unix it sends SIGTERM first, then SIGKILL if that same process is still alive after 2 seconds. On Windows it uses TerminateProcess. pid 1 and the lsoff process itself are never killed.

CLI -k follows the same rules. If the same PID appears twice (IPv4 and IPv6), it is killed only once. When stdin is not a TTY, -y is required so a pipe cannot kill by accident.

Limitations

How it collects data

No external commands (lsof / ss / netstat).

OS API
Linux /proc/net/{tcp,tcp6,udp,udp6}, /proc/<pid>/{fd,cmdline,cwd}
macOS sysctl net.inet.{tcp,udp}.pcblist64 (all listeners), libproc (owning process and cwd) and sysctl kern.procargs2
Windows IP Helper, QueryFullProcessImageName, NtQueryInformationProcess (cmdline and cwd)

Without permission, PID, path, and cmdline may be empty. Run as root / Administrator in that case.

Docker-published ports are supported as well. lsoff supplements kernel socket discovery with published-port metadata from the local Docker Engine API over /var/run/docker.sock; it does not imply that the container owns a host namespace socket. The current user must have permission to access that socket. If Docker is absent, the socket is unavailable, or access/API calls fail, normal host-process discovery continues unchanged.

Docker rows show a container name such as docker:grafana in PROCESS. The TUI details show the container-side port and protocol, and the container ID. These rows have no PID, so p / -p hides them, and x / -k cannot stop containers.

UDP has no LISTEN state, so sockets bound to a port with no remote peer are shown.

License

MIT

lsoff (yutat23/lsoff)

Searching Database…

255 ·GitHub
Lsoff
Что это такое?lsoff — инструмент CLI/TUI для Windows, Linux и macOS, который перечисляет слушающие TCP/UDP-порты и позволяет увидеть, какой процесс держит порт, с возможностью его завершить.
Это CLI-инструмент, TUI-приложение или и то и другое?И то и другое: есть скриптуемый табличный вывод в CLI и интерактивный TUI с поиском, сортировкой, фильтрацией и хоткеями для завершения процессов.
Как установить lsoff?Скачайте готовый бинарник с GitHub Releases, используйте WinGet на Windows, установите из Homebrew-тапа на macOS/Linux, выполните go install или соберите из исходников.
Нужны ли другие инструменты вроде lsof или netstat?Нет, он читает API ядра/ОС напрямую (procfs на Linux, sysctl/libproc на macOS, IP Helper/NtQueryInformationProcess на Windows) вместо вызова внешних lsof, ss или netstat.
Есть ли подводные камни в завершении процессов или чтении информации о портах?На macOS завершение не полностью атомарно, поскольку нет pidfd, поэтому PID теоретически может быть переиспользован в крошечном окне; на Windows чтение cmdline/cwd опирается на недокументированный внутренний API, а 32-битная сборка не может разглядеть детали 64-битных процессов.
Нужны ли права администратора/root, чтобы видеть всё?Да, без повышенных прав данные о PID, пути и командной строке могут оказаться пустыми; запускайте под root или Администратором ради полных данных.
Как обеспечивается безопасное завершение процесса?Нажатие x запрашивает подтверждение, затем проверяет, что процесс всё ещё тот же, что в списке (через pidfd на Linux, проверку метки времени на macOS или CreationTime на Windows), прежде чем отправить SIGTERM, а затем SIGKILL на Unix или TerminateProcess на Windows. В не-TTY-пайпе для подтверждения завершения нужен флаг -y.
Может ли он показывать порты Docker-контейнеров?Да, lsoff опрашивает локальный Docker Engine API через /var/run/docker.sock, чтобы показывать опубликованные порты контейнеров рядом с процессами хоста; они выводятся строками вроде docker:grafana без PID, поэтому завершить их из lsoff нельзя.
Можно искать и фильтровать порты в TUI?Да, можно искать по порту, PID, имени, проекту, пути или cmdline, сортировать по любой колонке и переключать режимы только IPv4 или только IPv6 клавишами 4 и 6.
Группирует ли он несколько сокетов одного процесса?Да, привязки одного процесса или контейнера (например, пара IPv4+IPv6) изначально свёрнуты в одну строку со счётчиком +N, а нажатие enter разворачивает их в небольшое дерево.
What are similar projects?bottom, ctop, telegraf, sampler, witr, nvtop, k9s, wtf
Which topics is it in?process-manager, system-monitor, tui, sysadmin, golang, monitoring, utility, networking, go, command-line-tool, terminal, docker
Creator
yutat23
Size
0.2 MB
Stars
255
Updated
CommitSep 08Releasev0.1.5Sep 08
Age
2mo
Commits · 90 Days