Retina capture command allows the user to capture network traffic and metadata for the capture target, and then send the capture file to the location by Output Configuration.
Note: captures can also be performed with a Capture CRD after installing Retina with capture support.
retina capture create
creates a Capture with underlying Kubernetes jobs.
Do not wait for the long-running capture job to finish.
By default, Retina capture CLI will exit before the jobs are completed. With --no-wait=false
, the CLI will wait until the jobs are completed and clean up the Kubernetes resources created.
- do not wait for the long-running capture job to finish
kubectl retina capture create --name capture-test --host-path /mnt/capture --node-selectors "kubernetes.io/os=linux" --no-wait=true
Namespace to host capture job and the other k8s resources for a network capture. Please make sure the namespace exists.
- deploy the capture job in namespace
capture
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux"
Capture target indicates the target on which the network packets capture will be performed, and the user can select either node, by node-selectors or node-names, or Pods, by pod-selector and namespace-selector pair.
- capture network packets on the node selected by node selectors
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux"
- capture network packets on the node selected by node names
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-names "aks-nodepool1-41844487-vmss000000,aks-nodepool1-41844487-vmss000001"
- capture network packets on the pod selected by pod-selector and namespace-selector pairs
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --pod-selectors="k8s-app=kube-dns" --namespace-selectors="kubernetes.io/metadata.name=kube-system"
The Capture can be stopped in either way below:
- In a given time, by the
duration
flag, or when the allowed maximum capture file reaches by themax-size
flag. When both are specified, the capture will stop when either condition first meets. - On demand by deleting the capture before the specified conditions meets.
The network traffic will be uploaded to the specified output location.
Duration of capturing packets(default 1m)
- stop the capture in 2 minutes
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux" --duration=2m
Limit the capture file to MB in size(default 100MB)
- stop the capture when the capture file size reaches 50MB
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux" --max-size=50
Limits the each packet to bytes in size and packets longer than PacketSize will be truncated. This is beneficial when the user wants to reduce the capture file size or hide customer data for security concern.
- limit each packet size to 96 bytes
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux" --packet-size=96
capture configuration indicates the configurations of the network capture.
Packet capture filters represent a range of filters to be included/excluded in the capture. This is not available on Windows.
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux" --exclude-filter="10.224.0.26:80,10.224.0.33:8080" --include-filter="10.224.0.42:80,10.224.0.33:8080"
Raw tcpdump flags which works only for Linux. Available tcpdump filters can be found in TCPDUMP MAN PAGE NOTE: this includes only tcpdump flags, for expression part, please user Packet include/exclude filters .
- filter DNS query
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux" --tcpdump-filter="udp port 53"
If true, collect static network metadata into the capture file(default true)
- disable collecting network metadata
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux" --include-metadata=false
The maximum number of jobs can be created for each capture. The default value 0 indicates no limit.
This can be configured by CLI flags for each CLI command, or config map consumed by retina-operator.
When creating a job requires job number exceeds this limit, it will fail with prompt like
Error: the number of capture jobs 3 exceeds the limit 2
kubectl retina capture create --name capture-test --job-num-limit=10 --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux"
OutputConfiguration indicates the location capture will be stored, and at least one location should be specified.
Blob-upload requires a Blob Shared Access Signature with the write permission to the storage account container, to create SAS tokens in the Azure portal, please read Create SAS Tokens in the Azure Portal
- store the capture file in the node host path
/mnt/capture
kubectl retina capture create --name capture-test --host-path /mnt/capture --namespace capture --node-selectors "kubernetes.io/os=linux"
- store the capture file to a PVC
mypvc
with access mode ReadWriteMany in namespacecapture
kubectl retina capture create --name capture-test --pvc mypvc --namespace capture --node-selectors "kubernetes.io/os=linux"
- store the capture file to a storage account
kubectl retina capture create --name capture-test --blob-upload <Blob SAS URL with write permission> --node-selectors "kubernetes.io/os=linux"
- store the capture file to AWS S3
kubectl retina capture create --name capture-test --s3-bucket "your-bucket-name" --s3-region "eu-central-1" --s3-access-key-id "your-access-key-id" --s3-secret-access-key "your-secret-access-key" --node-selectors "kubernetes.io/os=linux"
- store the capture file to S3-compatible service (like MinIO)
kubectl retina capture create --name capture-test --s3-bucket "your-bucket-name" --s3-endpoint "https://play.min.io:9000" --s3-access-key-id "your-access-key-id" --s3-secret-access-key "your-secret-access-key" --node-selectors "kubernetes.io/os=linux"
With debug mode, when --debug
is specified, we can overwrite the capture job Pod image from the default official GHCR
one.
- use
ghcr.io
image in default debug mode
kubectl retina capture create --name capture-test --host-path /mnt/test --namespace capture --node-selectors "kubernetes.io/os=linux" --debug
- use customized retina-agent image
RETINA_AGENT_IMAGE=<YOUR RETINA AGENT IMAGE> kubectl retina capture create --name capture-test --host-path /mnt/test --namespace capture --node-selectors "kubernetes.io/os=linux" --debug
retina capture delete
deletes a Kubernetes Jobs with the specified Capture name.
kubectl retina capture delete --name retina-capture-zlx5v
retina capture list
lists Captures in a namespace or all namespaces.
- list Captures under namespace
capture
kubectl retina capture list --namespace capture
- list Captures under in all namespaces
kubectl retina capture list --all-namespaces
After downloading or copying the tarball from the location specified, extract the tarball through the tar
command in either Linux shell or Windows Powershell, for example,
tar -xvf retina-capture-aks-nodepool1-41844487-vmss000000-20230320013600UTC.tar.gz
the tarball take such name pattern, $(capturename)-$(hostname)-$(date +%Y%m%d%H%M%S%Z).tar.gz
, for example, retina-capture-aks-nodepool1-41844487-vmss000000-20230313101436UTC.tar.gz
.
- Linux
├── ip-resources.txt
├── iptables-rules.txt
├── retina-capture-aks-nodepool1-41844487-vmss000000-20230320013600UTC.pcap
├── proc-net
│ ├── anycast6
│ ├── arp
... ...
├── proc-sys-net
│ ├── bridge
... ...
|-- socket-stats.txt
`-- tcpdump.log
- Windows
│ retina-capture-akswin000002-20230322010252UTC.etl
│ retina-capture-akswin000002-20230322010252UTC.pcap
│ netsh.log
│
└───metadata
│ arp.txt
... ...
│
├───adapters
│ 6to4 Adapter_int.txt
... ...
│
├───logs
│ ├───cbs
│ │ CBS.log
│ │
│ ├───dism
│ │ dism.log
│ │
│ └───NetSetup
│ service.0.etl
... ...
│
├───wfp
│ filters.xml
│ netevents.xml
│ wfpstate.xml
│
└───winevt
Application.evtx
... ...
-
Linux
- IP address configuration (ip -d -j addr show)
- IP neighbor status (ip -d -j neighbor show)
- IPtables rule dumps
- iptables-save
- iptables -vnx -L
- iptables -vnx -L -t nat
- iptables -vnx -L -t mangle
- Network statistics information
- ss -s (summary)
- ss -tapionume (socket information)
- networking stats (/proc/net)
- kernel networking configuration (/proc/sys/net)
-
Windows
- reference: Microsoft SDN Debug tool
When creating a capture, we can specify --no-wait
to clean up the jobs after the Capture is completed. Otherwise, after creating a Capture, a random Capture name is returned, with which we can delete the jobs by kubectl retina capture delete
command.