Skip to content

Commit

Permalink
update help and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jpinsonneau
jpinsonneau committed Jan 10, 2025
1 parent 63a698a commit 4226644
Show file tree
Hide file tree
Showing 6 changed files with 343 additions and 201 deletions.
141 changes: 70 additions & 71 deletions commands/netobserv
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
#!/bin/bash
source "./scripts/functions.sh"
source "./scripts/help.sh"
source "./scripts/dependencies_check.sh"

set +u

# e2e skips inputs
if [ -z "${isE2E+x}" ]; then isE2E=false; fi
# keep capture state
Expand Down Expand Up @@ -46,7 +48,22 @@ maxTime="5m"
# max bytes (default: 50MB)
maxBytes=50000000

function flows() {
if [[ ! "$*" =~ ^(.*)help|version(.*) ]]; then
required_yq_version="v0.0.0"
supported_archs=""
check_dependencies "$required_yq_version" "$supported_archs"
fi

case "$1" in
*help)
help
exit 0
;;
*version)
version "$version"
exit 0
;;
*flows)
case "$2" in
"help")
flows_usage
Expand All @@ -59,9 +76,8 @@ function flows() {
command="flows"
;;
esac
}

function packets() {
;;
*packets)
case "$2" in
"help")
packets_usage
Expand All @@ -74,9 +90,8 @@ function packets() {
command="packets"
;;
esac
}

function metrics() {
;;
*metrics)
case "$2" in
"help")
metrics_usage
Expand All @@ -89,74 +104,58 @@ function metrics() {
command="metrics"
;;
esac
}

if [[ ! "$*" =~ ^(.*)help|version(.*) ]]; then
required_yq_version="v0.0.0"
supported_archs=""
check_dependencies "$required_yq_version" "$supported_archs"
fi

case "$1" in
"help")
# display Help
echo
echo "Netobserv allows you to capture flow, packets and metrics from your cluster."
echo "Find more information at: https://github.com/netobserv/network-observability-cli/"
echo
echo "Syntax: netobserv [flows|packets|metrics|follow|stop|copy|cleanup|version] [options]"
echo
echo "commands:"
echo " flows Capture flows information in JSON format using collector pod."
echo " Options:"
flows_usage
echo " packets Capture packets information in pcap format using collector pod."
echo " Options:"
packets_usage
echo " metrics Capture metrics information in Prometheus using a ServiceMonitor (OCP cluster only)."
echo " Options:"
metrics_usage
echo " follow Follow collector logs when running in background."
echo " stop Stop collection by removing agent daemonset."
echo " copy Copy collector generated files locally."
echo " cleanup Remove netobserv components and configurations."
echo " version Print software version."
echo
exit 0
;;
"version")
# display version
echo "Netobserv CLI version $version"
exit 0
;;
"flows")
flows $*
;;
"packets")
packets $*
;;
"metrics")
metrics $*
;;
"follow")
# run follow command
follow
exit 0
*follow)
case "$2" in
"help")
follow_usage
exit 0
;;
*)
# run follow command
follow
exit 0
;;
esac
;;
"stop")
# run deleteDaemonset command
deleteDaemonset
exit 0
*stop)
case "$2" in
"help")
stop_usage
exit 0
;;
*)
# run deleteDaemonset command
deleteDaemonset
exit 0
;;
esac
;;
"copy")
# run copy output command
copyOutput
exit 0
*copy)
case "$2" in
"help")
copy_usage
exit 0
;;
*)
# run copy output command
copyOutput
exit 0
;;
esac
;;
"cleanup")
# run cleanup command
cleanup
exit 0
*cleanup)
case "$2" in
"help")
cleanup_usage
exit 0
;;
*)
# run cleanup command
cleanup
exit 0
;;
esac
;;
*)
echo "Unknown command $1. Use 'netobserv help' to display options"
Expand Down
42 changes: 28 additions & 14 deletions docs/netobserv_cli.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
// Automatically generated by './scripts/generate-doc.sh'. Do not edit, or make the NETOBSERV team aware of the editions.
:_mod-docs-content-type: REFERENCE

[id="network-observability-cli-usage_{context}"]
= Network Observability CLI usage

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 flows data and packets data for further analysis, enable Network Observability Operator features or pass configuration options to the eBPF agent and `flowlogs-pipeline`.

[id=cli-syntax_{context}]
== Syntax
The basic syntax for `oc netobserv` commands:

Expand All @@ -14,15 +17,24 @@ $ 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 "Flow capture subcommands" table.
| Capture flows information. For subcommands, see the "Flows capture options" table.
| packets
| Capture packets data. For subcommands, see the "Packet capture subcommand" table.
| Capture packets data. For subcommands, see the "Packets capture options" table.
| metrics
| Capture metrics data. For subcommands, see the "Metrics capture options" table.
| follow
| Follow collector logs when running in background.
| stop
| Stop collection by removing agent daemonset.
| copy
| Copy collector generated files locally.
| cleanup
| Remove the Network Observability CLI components.
| version
Expand All @@ -31,8 +43,10 @@ $ oc netobserv [<command>] [<feature_option>] [<command_options>] <1>
| Show help.
|===

[id=cli-reference-flows-capture-options_{context}]
== Flows capture options
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.
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.

.`oc netobserv flows` syntax
[source,terminal]
----
Expand All @@ -52,7 +66,6 @@ $ oc netobserv flows [<feature_option>] [<command_options>]
|--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 @@ -71,17 +84,19 @@ $ oc netobserv flows [<feature_option>] [<command_options>]
|--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
|--regexes| filter flows using regular expression | n/a
|--interfaces| interfaces to monitor | n/a
|===

.Example running flow capture on TCP protocol and port 49051 with PacketDrop and RTT features enabled:
.Example running flows capture on TCP protocol and port 49051 with PacketDrop and RTT features enabled:
[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 packet capture data as same as flow capture using the filters. However, the features are not available here.
You can filter packets capture data as same as flows capture using the filters.
Note that the features, such as packets drop, dns, rtt, and network events, are only available for flows and metrics capture.

.`oc netobserv packets` syntax
[source,terminal]
Expand All @@ -97,7 +112,6 @@ $ oc netobserv packets [<option>]
|--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 @@ -116,16 +130,17 @@ $ oc netobserv packets [<option>]
|--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
|--regexes| filter flows using regular expression | n/a
|===

.Example running packet capture on TCP protocol and port 49051:
.Example running packets capture on TCP protocol and port 49051:
[source,terminal]
----
$ oc netobserv packets --action=Accept --cidr=0.0.0.0/0 --protocol=TCP --port=49051
----
[id=cli-reference-metrics-capture-options_{context}]
== Metrics capture options
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 flows capture. The generated graphs fill accordingly in the dashboard.

.`oc netobserv metrics` syntax
[source,terminal]
Expand All @@ -141,7 +156,6 @@ $ oc netobserv metrics [<option>]
|--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
|--protocol| filter protocol | n/a
Expand All @@ -160,7 +174,7 @@ $ oc netobserv metrics [<option>]
|--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
|--regexes| filter flows using regular expression | n/a
|--interfaces| interfaces to monitor | n/a
|===

Expand Down
Loading

0 comments on commit 4226644

Please sign in to comment.