Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OSDOCS-10730: NetObserv 1.8 CLI reference #86824

Open
wants to merge 1 commit into
base: no-1.8
Choose a base branch
from
+63 −15
Open

OSDOCS-10730: NetObserv 1.8 CLI reference #86824

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 63 additions & 15 deletions modules/network-observability-netobserv-cli-reference.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,7 @@
[id="network-observability-netobserv-cli-reference_{context}"]
= Network Observability CLI usage

You can use the Network Observability CLI (`oc netobserv`) to pass command line arguments to capture flow data and packet data for further analysis, enable Network Observability Operator features, or pass configuration options to the eBPF agent and `flowlogs-pipeline`.

[id="cli-syntax_{context}"]
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jpinsonneau all the headings have to have a unique ID. Can we add the ones I have here just so there's not any future removal of them as we update the reference?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think last time I added these in peer review and didn't sync with the upstream. Its just a requirement for Pantheon docs builds.

You can use the The Network Observability CLI (`oc netobserv`) to pass command line arguments to capture flow data and packet data for further analysis, enable Network Observability Operator features or pass configuration options to the eBPF agent and flowlogs-pipeline.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can use the The Network Observability CLI (`oc netobserv`) to pass command line arguments to capture flow data and packet data for further analysis, enable Network Observability Operator features or pass configuration options to the eBPF agent and flowlogs-pipeline.
You can use the The Network Observability CLI (`oc netobserv`) to pass command line arguments to capture flow data and packet data for further analysis, enable Network Observability Operator features or pass configuration options to the eBPF agent and `flowlogs-pipeline`.

== Syntax
The basic syntax for `oc netobserv` commands is as follows:

Expand All @@ -16,16 +14,15 @@ $ oc netobserv [<command>] [<feature_option>] [<command_options>] <1>
----
<1> Feature options can only be used with the `oc netobserv flows` command. They cannot be used with the `oc netobserv packets` command.

[id="cli-basic-commands_{context}"]
== Basic commands
[cols="3a,8a",options="header"]
.Basic commands
|===
| Command | Description
| flows
| Capture flows information. For subcommands, see the "Flows capture options" table.
| Capture flows information. For subcommands, see the "Flow capture subcommands" table.
| packets
| Capture packets data. For subcommands, see the "Packets capture options" table.
| Capture packets data. For subcommands, see the "Packet capture subcommand" table.
Comment on lines -26 to +25
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For these two, can we revert back to "options" instead of "subcommands", or did you intend to change this? If its a change we want to make, then I can update the headings for those "Packet capture" and "Flow capture" sections.

Additionally, there's "Packets" vs "Packet". I think in previous releases, we've intentionally used the plural.

| cleanup
| Remove the Network Observability CLI components.
| version
Expand All @@ -34,10 +31,8 @@ $ oc netobserv [<command>] [<feature_option>] [<command_options>] <1>
| Show help.
|===

[id="cli-reference-flows-capture-options_{context}"]
== Flows capture options
Flows capture has mandatory commands as well as additional options, such as enabling extra features about packet drops, DNS latencies, Round-trip time, and filtering.

Flow capture has mandatory commands as well as additional options, such as enabling extra features about packet drops, DNS latencies, Round-trip time, and filtering.
.`oc netobserv flows` syntax
Comment on lines +35 to 36
Copy link
Contributor Author

@skrthomas skrthomas Jan 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Flow capture has mandatory commands as well as additional options, such as enabling extra features about packet drops, DNS latencies, Round-trip time, and filtering.
.`oc netobserv flows` syntax
Flow capture has mandatory commands as well as additional options, such as enabling extra features about packet drops, DNS latencies, Round-trip time, and filtering.
.`oc netobserv flows` syntax

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Need a return here, otherwise the heading rendering is off:
image

[source,terminal]
----
Expand All @@ -50,11 +45,14 @@ $ oc netobserv flows [<feature_option>] [<command_options>]
|--enable_dns| enable DNS tracking | false
|--enable_rtt| enable RTT tracking | false
|--enable_network_events| enable Network events monitoring | false
|--enable_filter| enable flow filter | false
|--get-subnets| get subnets informations | false
|--log-level| components logs | info
|--max-time| maximum capture time | 5m
|--max-bytes| maximum capture bytes | 50000000 = 50MB
|--background| run in background | false
|--copy| copy the output files locally | prompt
|--node-selector| capture on specific nodes | n/a
|--enable_filter| enable flow filter | false
|--direction| filter direction | n/a
|--cidr| filter CIDR | 0.0.0.0/0
|--protocol| filter protocol | n/a
Expand All @@ -72,18 +70,18 @@ $ oc netobserv flows [<feature_option>] [<command_options>]
|--icmp_type| filter ICMP type | n/a
|--icmp_code| filter ICMP code | n/a
|--peer_ip| filter peer IP | n/a
|--drops| filter flows with only dropped packets | false
|--regexes| filter flows using regex | n/a
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 [error] RedHat.TermsErrors: Use 'regular expression' rather than 'regex'. For more information, see RedHat.TermsErrors.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can expand this to "regular expression"

|--interfaces| interfaces to monitor | n/a
|===

.Example running flows capture on TCP protocol and port 49051 with PacketDrop and RTT features enabled:
.Example running flow capture on TCP protocol and port 49051 with PacketDrop and RTT features enabled:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another flow/flows question here.

[source,terminal]
----
$ oc netobserv flows --enable_pktdrop=true --enable_rtt=true --enable_filter=true --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051
----

[id="cli-reference-packet-capture-options_{context}"]
== Packets capture options
You can filter on port and protocol for packet capture data.
You can filter packet capture data as same as flow capture using the filters. However, the features are not available here.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can filter packet capture data as same as flow capture using the filters. However, the features are not available here.
You can filter packet capture data, the same as flow capture, using the filters. However, the features are not available here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "The features are not available here" mean? I'm a little confused. There is the --enable_filter option in the Packets captures options.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The features (pkt drop, dns, rtt and network events) are only available for flows and metrics capture.
The packet capture will return an error if you try to enable these.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahhh, I got it sorry about that. Its THE features, not the filter. Sorry. I was focused too much on the "However" modifying the "filter" part of the preceding sentence but its about the "same as flow capture", noting that the features available in flow capture aren't available here. I suggest we could say that more explicitly, like:

Note that the features, such as packet drop, dns, rtt, and network events, are only available for flows and metrics capture

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks works for me ! Thanks for the feedback. I will open a PR to adress all of these changes


.`oc netobserv packets` syntax
[source,terminal]
Expand All @@ -96,7 +94,10 @@ $ oc netobserv packets [<option>]
|--log-level| components logs | info
|--max-time| maximum capture time | 5m
|--max-bytes| maximum capture bytes | 50000000 = 50MB
|--background| run in background | false
|--copy| copy the output files locally | prompt
|--node-selector| capture on specific nodes | n/a
|--enable_filter| enable flow filter | false
|--direction| filter direction | n/a
|--cidr| filter CIDR | 0.0.0.0/0
|--protocol| filter protocol | n/a
Expand All @@ -114,10 +115,57 @@ $ oc netobserv packets [<option>]
|--icmp_type| filter ICMP type | n/a
|--icmp_code| filter ICMP code | n/a
|--peer_ip| filter peer IP | n/a
|--drops| filter flows with only dropped packets | false
|--regexes| filter flows using regex | n/a
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 [error] RedHat.TermsErrors: Use 'regular expression' rather than 'regex'. For more information, see RedHat.TermsErrors.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we expand to regular expression?

|===

.Example running packets capture on TCP protocol and port 49051:
.Example running packet capture on TCP protocol and port 49051:
[source,terminal]
----
$ oc netobserv packets --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051
----
== Metrics capture options
You can enable features and use filters on metrics capture as same as flow capture. The generated graphs will fill accordingly.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can enable features and use filters on metrics capture as same as flow capture. The generated graphs will fill accordingly.
You can enable features and use filters on metrics capture, the same as flow capture. The generated graphs fill accordingly.


.`oc netobserv metrics` syntax
[source,terminal]
----
$ oc netobserv metrics [<option>]
----
[cols="1,1,1",options="header"]
|===
| Option | Description | Default
|--enable_pktdrop| enable packet drop | false
|--enable_dns| enable DNS tracking | false
|--enable_rtt| enable RTT tracking | false
|--enable_network_events| enable Network events monitoring | false
|--get-subnets| get subnets informations | false
|--node-selector| capture on specific nodes | n/a
|--enable_filter| enable flow filter | false
|--direction| filter direction | n/a
|--cidr| filter CIDR | 0.0.0.0/0
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 [error] RedHat.CaseSensitiveTerms: Use 'CIDR' rather than 'cidr'. For more information, see RedHat.CaseSensitiveTerms.

|--protocol| filter protocol | n/a
|--sport| filter source port | n/a
|--dport| filter destination port | n/a
|--port| filter port | n/a
|--sport_range| filter source port range | n/a
|--dport_range| filter destination port range | n/a
|--port_range| filter port range | n/a
|--sports| filter on either of two source ports | n/a
|--dports| filter on either of two destination ports | n/a
|--ports| filter on either of two ports | n/a
|--tcp_flags| filter TCP flags | n/a
|--action| filter action | Accept
|--icmp_type| filter ICMP type | n/a
|--icmp_code| filter ICMP code | n/a
|--peer_ip| filter peer IP | n/a
|--drops| filter flows with only dropped packets | false
|--regexes| filter flows using regex | n/a
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 [error] RedHat.TermsErrors: Use 'regular expression' rather than 'regex'. For more information, see RedHat.TermsErrors.

|--interfaces| interfaces to monitor | n/a
|===

.Example running metrics capture for TCP drops:
[source,terminal]
----
$ oc netobserv metrics --enable_pktdrop=true --enable_filter=true --protocol=TCP
----