[PATCH iproute2] ss: document -K requirements in man page

[PATCH iproute2] ss: document -K requirements in man page

[Gopal Malaviya]

The -K/--kill option uses SOCK_DESTROY, which the kernel only provides
when built with CONFIG_INET_DIAG_DESTROY=y (default n). Closing a
socket also requires CAP_NET_ADMIN. The man page mentions neither.

Without CONFIG_INET_DIAG_DESTROY, the kernel answers every SOCK_DESTROY
request with EOPNOTSUPP. ss treats that the same as a single socket
that cannot be closed and skips it silently, so nothing is closed, no
error is printed and ss exits with status 0. For example, on a WSL2
kernel (6.6.114.1-microsoft-standard-WSL2), running as root:

  # ss -tan '( sport = :52616 or dport = :52616 )'
  State      Recv-Q Send-Q Local Address:Port  Peer Address:Port
  FIN-WAIT-2 0      0          127.0.0.1:52616    127.0.0.1:58995
  CLOSE-WAIT 1      0          127.0.0.1:58995    127.0.0.1:52616
  # ss --kill -tan sport = :52616
  State Recv-Q Send-Q Local Address:Port Peer Address:Port
  # echo $?
  0
  # ss -tan '( sport = :52616 or dport = :52616 )'
  State      Recv-Q Send-Q Local Address:Port  Peer Address:Port
  FIN-WAIT-2 0      0          127.0.0.1:52616    127.0.0.1:58995
  CLOSE-WAIT 1      0          127.0.0.1:58995    127.0.0.1:52616

With the same kernel rebuilt with CONFIG_INET_DIAG_DESTROY=y, the same
--kill command closes the matching socket when run as root, and fails
with "SOCK_DESTROY answers: Operation not permitted" without
CAP_NET_ADMIN.

Making ss report this was discussed in 2016 [1] without agreement,
since the kernel also returns EOPNOTSUPP for individual sockets that
cannot be closed (e.g. some UDP or TIME_WAIT sockets on older kernels),
and per-socket errors would be noisy on correctly configured systems.
This patch does not change behaviour; it only documents both
requirements and the silent case, so users can tell why -K had no
effect.

Link: https://lore.kernel.org/netdev/1463442791-2399-2-git-send-email-dsa@cumulusnetworks.com/ [1]
Signed-off-by: Gopal Malaviya <gopalmalaviya53@gmail.com>
---
 man/man8/ss.8 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man/man8/ss.8 b/man/man8/ss.8
index 3871612d..4be0a8e2 100644
--- a/man/man8/ss.8
+++ b/man/man8/ss.8
@@ -313,6 +313,11 @@ Show internal tipc socket information.
 Attempts to forcibly close sockets. This option displays sockets that are
 successfully closed and silently skips sockets that the kernel does not support
 closing. It supports IPv4 and IPv6 sockets only.
+Closing sockets requires the
+.B CAP_NET_ADMIN
+capability and a kernel built with CONFIG_INET_DIAG_DESTROY=y.
+If the kernel lacks this support, no sockets are closed and no error
+is reported.
 .TP
 .B \-s, \-\-summary
 Print summary statistics. This option does not parse socket lists obtaining
-- 
2.43.0