This is the development version of Kanrisuru. Since this is still a pre-1.0 release, we don't recommend using this in system-critical production environments.

Kanrisuru

ss

Get socket statistics on a remote host with ruby.
linux manual

Basic Usage

require 'kanrisuru'
host = Kanrisuru::Remote::Host.new(host: '127.0.1.1', username: 'ubuntu', keys: ['~/.ssh/id_rsa'])

result = host.ss(tcp: true, expression: 'dport = 22', state: 'established')
result.success?
true

result[0].local_port
'ssh'

result[0].peer_address
'172.16.50.5'

Parameters

Field Type Description
numeric boolean
Do not try to resolve service names. Show exact bandwidth values, instead of human-readable.
tcp boolean
Display TCP sockets.
udp boolean
Display UDP sockets.
unix boolean
Display unix sockets.
raw boolean
Display RAW sockets.
family string
Display sockets of type FAMILY. Currently the following families are supported: unix, inet, inet6, link, netlink, vsock, xdp.
state string
Filter sockets by their state. Valid TCP states: established, syn-sent, syn-recv, fin-wait-1, fin-wait-2, time-wait, closed, close-wait, last-ack, listening and closing. Other states include: all, connected, synchronized, bucket, syn-recv, big.
expression string
Allows filtering based on specific criteria, using a series of predicates combined by boolean operators.

Result

Returns an array of Statistics structs.

Statistics Fields

Field Type Description
netid string Type of socket, eg TCP, UDP, Unix, RAW.
state string State of the socket. Most commonly ESTAB (established), UNCONN (unconnected), LISTEN (listening).
receive_queue integer Number of received packets in the queue.
send_queue integer Number of sent packets in the queue.
local_address string Address of local machine.
local_port stringinteger Address of local port.
peer_address string Address of remote machine.
peer_port stringinteger Address of remote port.
memory StatisticsMemory Additional details on how much memory is being consumed by the socket connection.

StatisticsMemory Fields

Field Type Description
rmem_alloc integer The memory allocated for receiving packet
rcv_buf integer The total memory can be allocated for receiving packet
snd_buf integer The total memory can be allocated for sending packet
fwd_alloc integer the memory allocated by the socket as cache, not used for receiving/sending packet yet. If need memory to send/receive packet, the memory in this cache will be used before allocate additional memory.
wmem_queued integer The memory allocated for sending packet (which has not been sent to layer 3)
ropt_mem integer The memory used for storing socket option, e.g., the key for TCP MD5 signature.
back_log integer The memory used for the sk backlog queue. On a process context, if the process is receiving packet, and a new packet is received, it will be put into the sk backlog queue, so it can be received by the process immediately
sock_drop integer The number of packets dropped before they are de-multiplexed into the socket

Return Example

host.ss(tcp: true, expression: 'dport = 22 || sport = 22', state: 'established').to_a
[
  [0] #<Struct:Kanrisuru::Core::Socket::Statistics:0x00002260
    local_address = "10.0.0.100",
    local_port = "ssh",
    memory = #<Struct:Kanrisuru::Core::Socket::StatisticsMemory:0x000022d8
      back_log = 0,
      fwd_alloc = 4096,
      rcv_buf = 131072,
      rmem_alloc = 0,
      ropt_mem = 0,
      snd_buf = 87040,
      sock_drop = 0,
      wmem_alloc = 0,
      wmem_queued = 0
    >,
    netid = "tcp",
    peer_address = "172.16.50.5",
    peer_port = 51410,
    receive_queue = 0,
    send_queue = 0,
    state = "established"
  >,
  [1] #<Struct:Kanrisuru::Core::Socket::Statistics:0x00002350
    local_address = "127.0.0.1",
    local_port = 33816,
    memory = #<Struct:Kanrisuru::Core::Socket::StatisticsMemory:0x000023a0
      back_log = 0,
      fwd_alloc = 4096,
      rcv_buf = 131072,
      rmem_alloc = 0,
      ropt_mem = 0,
      snd_buf = 2626560,
      sock_drop = 0,
      wmem_alloc = 0,
      wmem_queued = 0
    >,
    netid = "tcp",
    peer_address = "127.0.0.1",
    peer_port = "ssh",
    receive_queue = 0,
    send_queue = 0,
    state = "established"
  >,
  [2] #<Struct:Kanrisuru::Core::Socket::Statistics:0x00002418
    local_address = "127.0.0.1",
    local_port = "ssh",
    memory = #<Struct:Kanrisuru::Core::Socket::StatisticsMemory:0x00002490
      back_log = 0,
      fwd_alloc = 2648,
      rcv_buf = 131072,
      rmem_alloc = 0,
      ropt_mem = 0,
      snd_buf = 2626560,
      sock_drop = 0,
      wmem_alloc = 0,
      wmem_queued = 1448
    >,
    netid = "tcp",
    peer_address = "127.0.0.1",
    peer_port = 33816,
    receive_queue = 0,
    send_queue = 168,
    state = "established"
  >
]

Exit Status

Code Description

Tested On

  • Ubuntu, Debian, Centos, Fedora, Redhat, OpenSuse, SLES