sentry-netstat

Retrieves the network connection list from a remote sentry.

Command properties

Property	Description
Command type	Transforming
Required permission	Administrator
License usage	N/A
Parallel execution	Supported
Distributed execution	Not supported

Syntax

sentry-netstat [timeout=INT]

Options

timeout=INT: RPC timeout in seconds. Accepts a value between 1 and 600. (Default: 30)

Input fields

Field	Type	Required	Description
guid	string	Required	Sentry unique identifier.

Output fields

Field	Type	Description
guid	string	Sentry unique identifier.
pid	integer	Process ID. For the values by operating system, see the table below.
protocol	string	Protocol (`tcp`, `tcp6`, `udp`, `udp6`).
local_ip	ipaddr	Local IP address.
local_port	integer	Local port number.
remote_ip	ipaddr	Remote IP address. Not present for UDP entries.
remote_port	integer	Remote port number. Not present for UDP entries.
state	string	Connection state. For the values by operating system, see the table below.
_error	string	Error message added to the original record if an error occurs.

The values of the state and pid fields depend on the operating system where the sentry is installed:

Operating system	state	pid
Linux	TCP entries: one of `ESTABLISHED`, `SYNSENT`, `SYNRECV`, `FINWAIT1`, `FINWAIT2`, `TIMEWAIT`, `CLOSE`, `CLOSEWAIT`, `LASTACK`, `LISTEN`, `CLOSING`, or `UNKNOWN`. UDP entries: always `LISTEN`.	The process ID found in the result of the `lsof` command. `0` if not found.
Windows	TCP entries: one of `CLOSED`, `LISTEN`, `SYNSENT`, `SYNRECEIVED`, `ESTABLISHED`, `FINWAIT1`, `FINWAIT2`, `CLOSEWAIT`, `CLOSING`, `LASTACK`, `TIMEWAIT`, `DELETETCB`, or `UNKNOWN`. UDP entries: always `LISTEN`.	The ID of the process that owns the socket.
AIX, HP-UX	TCP entries: the state value in the output of the `netstat -na` command (for example, `LISTEN` or `ESTABLISHED`) is assigned as is, and connections in the `CLOSED` state are not output. UDP entries: null.	Not output.
Solaris	The State column value in the output of the `netstat -na` command is assigned as is (for example, `LISTEN`, `IDLE`, or `ESTABLISHED` for TCP entries, and `Idle` or `Unbound` for UDP entries).	Not output.

AIX, HP-UX, and Solaris sentries assign 0.0.0.0 (:: for IPv6 entries) if the address in the output of the netstat -na command is *, and assign null if the port is *.

Linux sentries find the process that owns each socket with the lsof command. If the lsof package is not installed on the sentry host, pid is always 0. Even with the lsof package, pid is 0 for sockets owned by processes of other accounts that the sentry service account cannot access. For the packages required on a Linux sentry host, see Install required packages.

Error codes

Parsing errors

Error code	Message	Description
23100	no sentry rpc permission	A user without administrator privileges ran the command.
23101	invalid sentry rpc timeout. use timeout between 1 and 600.	The `timeout` option value is not an integer or is outside the range 1–600.

Runtime errors

Errors are returned via the _error field:

Error message	Description
guid is null	The `guid` field value in the input record is null.
guid should be string	The `guid` field value in the input record is not a string.
guid should be non empty string	The `guid` field value in the input record is an empty string.
not connected	The sentry is not connected.
timeout	The RPC request timed out.
disconnected	The sentry connection was already lost when the RPC request was sent.

Other RPC exception messages may be returned depending on the state of the system where the sentry is installed.

Description

The sentry-netstat command reads the guid field of each input record, sends an asynchronous RPC message to the corresponding sentry, and retrieves the network connection list. It returns connection information for TCP, TCP6, UDP, and UDP6 protocols, with a protocol field added to each connection to identify the protocol type.

Results are returned in the order RPC response messages are received from sentries, so the output record order may differ from the input record order.

The maximum length of the asynchronous RPC request queue is 100 by default and can be adjusted using the logpresso.core.sentry_rpc_parallel environment variable.

To retrieve results from all Data Nodes at once in a cluster environment, use the sonar-sentry-netstat command.

Examples

Retrieve the network connection list from all sentries
```
sentry | fields guid | sentry-netstat
```
Retrieves the current network connection list from all connected sentries.
Retrieve TCP sockets in the LISTEN state
```
sentry | fields guid | sentry-netstat | search protocol == "tcp*" and state == "LISTEN"
```
Filters only TCP sockets in the LISTEN state from all sentries. The state value of UDP entries differs by the operating system of the sentry, so the protocol condition selects only TCP entries.
Retrieve with a 60-second timeout
```
sentry | fields guid | sentry-netstat timeout=60
```
Retrieves the network connection list from sentries with the RPC timeout set to 60 seconds.

Change history

The sentry-netstat command has been available since before Sonar 4.0.